@alma-harness/batch

Governed single-dispatch batch execution. Node >=22 and matching Alma packages are required. createGovernedBatchRunner composes BatchSubmissionStore, BatchUsageStore, BatchAccountingStore, ExecutionResultStore, governed settlement, same-counter spend.peek, audit and SingleDispatchBatchClient capabilities.

Supply immutable configRevision (including provider account selection), bounded request/output/aggregate sizes, runTimeoutMs <=5 minutes and onBackgroundError. The host creates authorized complete manifests: scope/session, item identities, original prices/policy/controls, content/config revisions and result retention. The host derives allowed tools/media/schema; this primitive does not route policy or execute handlers. Never accept manifests/scopes/handles from model output or unverified browser input. Changing config requires a new revision; old batches must still resolve their original configuration, prices and provider account.

submit({input,rationale,loadItems,signal?}) reserves every result and awaits audit before loading content. Requests must match ordered IDs, model, batch tier and controls. Only the first durable dispatch:true response permits a provider attempt. Equal replay never loads input or submits again. The optional awaited onInputFile hook can retain upload references before create; without it no durable orphan-file inventory is claimed. Any ambiguous submission stays unresolved, even after expiry. No fallback, automatic resubmission or lease takeover exists. Explicit provider cancellation is separate from submission ownership and settlement.

collect({scope,key},{signal?}) resolves the stored handle and collects every terminal status, including failed/expired/cancelled. Every observation is journaled before governed settlement and inclusive accounting. Those are the only financial writers: neither SpendStore.add nor AuditLog.cost runs. Hashes deduplicate metadata observations only; original manifest settlement identities own charges. Unknown, unpriced and contradictory evidence stays pending for explicit reconciliation.

New output is retained only after complete, independently validated EOF. Corrupt or missing tails cannot authorize partial new output. Content bounds/failures do not stop known-usage drainage. eof describes this invocation, not a durable completion certificate. reconciliationRequired reports this collection's pending financial/content work. Existing output remains readable after a later failed GET. A crash between puts can require another GET, but never another model submission.

read({scope,key}) returns persisted metadata, inclusive financial evidence and current retained item results; it makes no claim of EOF or delivery. Successful output is a backstage governed-batch-v1 envelope with ordered neutral blocks and stop. Reasoning is not a public reply; the host validates its business schema and authorizes any effects. Refusal/truncation/invalid/blocked/unavailable stay distinct. Original block decisions suppress successful outputs; missing aggregate receipts keep block-mode success pending until those decisions can be evaluated; warn preserves them. Monetary warnings are durable evidence, not calls to an external notification service.

reconcile({scope,key},query?) repairs journaled finance without provider/content access. It returns scanned/repaired/pending counts and afterId. Pages default50, maximum100; restart future passes at the beginning. Already adopted observations must still repair missing aggregate receipts, so default queries include them.

Result retention begins at submission reservation. Collection never prepares a new reservation, renews retention or resurrects erasure. Read/put respect the original binding; register result erasure/purge with the host. Successful public submit/collect promises are bounded by timeout/abort (submission also by its original deadline); cancellation does not prove dependency termination. Late acceptance/financial work is observed, and background failures report only scoped stage metadata. Permanent process loss cannot guarantee missing provider evidence.

Migrate batch accounting (which composes submission, usage and governed costs), results and audit before enabling this runner. PostgreSQL store deadlines still apply to read/reconcile. Routines and channel/business delivery require their own persistent claims; this runner never sends real messages or certifies delivery. See spec.

Status and cancellation (spec: governed-batch-cancellation-adoption)

status({scope,key},{signal?}) and cancel({scope,key},{signal?}) resolve the original accepted handle under the runner's configuration. They reject missing handles, foreign scope/configuration and unsupported cancellation before HTTP. They remain available after the submission deadline, bounded by this invocation's runTimeoutMs/signal. Neither loads input nor changes durable execution or finance.

Cancellation returns {status:"requested",progress}: one validated provider acknowledgement, not terminal cancellation or a refund. A failed/ambiguous request is never retried automatically; an explicit later call is another cancellation request. Continue explicit status/collection to account for completed items and retain unknown evidence. Closing a connection does not prove dependency termination.

Tool selection

Each item's execution.controls.toolChoice must equal its loaded request.toolChoice. Supported neutral modes are auto, none, required and {type:"tool",name}; provider/model restrictions remain those documented by the providers package. Named choices are validated against the actual authorized ToolSpecs before dispatch, including with custom transport validators. Choice is part of immutable batch identity; changed choice conflicts without another input load or submission. Absence retains the old wire and replay contract.

Successful extraction items preserve their tool_use stop and ordered tool_call blocks, alongside original financial receipts. Inspect outcome, stop, expected name and validate arguments before using them. Selection invokes no business handler or personal-memory write. Read/status/collect/reconcile/cancel never infer authority to submit again from missing content, unknown usage or an absent handle.