@agent-os/workspace-job

Purpose

Provider-neutral workspace job fact carrier for protected terminal artifact settlement.

Public API Status

Carrier package. It owns protected terminal artifact and verdict fact vocabulary, not workspace execution or verifier policy.

Invariant

Workspace-job owns workspace_job.* request, finalized terminal artifact, verifier verdict, terminal failure fact, and raw projection vocabulary. It does not execute agent submits, workspace effects, verifiers, or runtime diagnostic joins. Runtime and host packages must construct workspace-job facts through this carrier's exported constructors and settlement helpers.

Minimal Usage

Emit workspace_job.requested with an idempotency key and optional attempt metadata, then run the closed runtime pipeline: build terminal bytes from the submitted candidate, write them to the declared terminal path, read the artifact back, hash the readback bytes, and pass those same readback bytes to the verifier. Commit workspace_job.terminal_finalized only from that readback metadata, then commit exactly one terminal attempt verdict: workspace_job.verified, workspace_job.verifier_rejected, or workspace_job.failed.

verified and verifier_rejected reference the terminal_finalized event id; the projection only becomes deliverable when the verdict joins to the finalized artifact metadata. When runtime recovery is declared, a verifier rejection is an attempt terminal state until the repair budget is exhausted. AgentOS owns attempt indexes, per-attempt idempotency keys, workspace reuse, and final job projection aggregation; consumers only declare verifier checks and repair submit spec construction. The job projection is derived from the latest requested attempt for the product run id.

failed.failure is terminal vocabulary only: { phase, code, reason, retryable? }. workspace_job.failed may carry submitRunId as a raw substrate/debug join key, but diagnostics, category, owner, and public message are not workspace-job facts. Consumer-facing failure explanation is derived in runtime composition from workspace-job facts joined with runtime diagnostic projections.

Consumers may declare a terminal schema builder, but they do not choose the terminal path, artifact ref, digest, byte count, or verified projection. The runtime/data-plane boundary enforces written bytes == readback bytes == hashed bytes == verified bytes == delivered bytes.

Verification

cd packages/carriers/workspace-job
vp test run