HandoffEnvelope reference

HandoffEnvelope is the exchange root for work performed by agents over CSAG artifacts. It references content-hashed PaperExtraction snapshots and keeps workflow state outside the manuscript-local extraction.

Each envelope revision is immutable by convention. A state change is recorded as a separate revision with the immediate prior revisions in parents.

Root fields

Field	Cardinality	Contract
id	one, required	Stable workspace or handoff identifier.
envelope_version	one, required	Supported handoff contract version: 1.0.0.
revision	one, required	Stable revision identifier, not a digest of the envelope bytes.
parents	many	Immediate parent revision identifiers.
source_artifacts	one or more	Content-hashed source snapshots, including at least one paper_extraction.
assessments	many	Agent assessments with artifact, source-object, or execution bases.
actions	many	Owned work items with status, dependencies, and acceptance criteria.
executions	many	Runs tied to actions, including content-hashed inputs and outputs.
conflicts	many	Open or resolved disagreements between revision heads.
current_heads	one or more	Revisions that head the workspace.
created_on, created_by	one each, required	Revision timestamp and responsible actor.

Content identity

Every HandoffArtifactDigest records:

Field	Requirement
id	Globally unique within the envelope.
artifact_role	Controlled role such as paper_extraction, code, or result.
artifact_path	Bundle-relative path or external locator.
sha256	Lowercase, 64-character SHA-256 digest.
media_type, byte_size	Optional media type and byte count.

Repeated occurrences of one artifact_path carry the same hash and byte size. The handoff validator resolves bundle-relative paths against the envelope directory, verifies local bytes, and records every verified local artifact in the validation report's inputs map. It rejects absolute paths, file: locators, and relative paths that escape the bundle. It does not fetch external locators that are not files; they keep their declared content identity.

A local paper_extraction snapshot conforms to the closed PaperExtraction schema and has a fresh local validation report with ok: true. Validation and quality reports link back to a declared source-extraction digest, and every locally resolvable report input matches its recorded hash.

Trust boundary

Version 1.0 does not content-address or sign the envelope itself. The validator checks revision relationships, but it cannot prove that two envelopes carrying the same revision have identical bytes or that a named agent created them. Artifact hashes protect referenced inputs and outputs, not the history record around them. When revision integrity or actor authenticity matters, store the envelope in a content-addressed repository and exchange its digest or signature through that repository's trust layer.

Assessments

An assessment records assessment_status, assessment_text, its creator, and its timestamp. It cites at least one of:

• basis_artifacts: artifact digest IDs in the envelope
• basis_refs: IDs inside source artifacts, such as assertions or evidence items
• basis_executions: execution IDs in the envelope

The validator resolves artifact and execution bases locally. When a local, hash-matching paper_extraction snapshot is available, it also resolves basis_refs, target_assertions, and target_knowledge_gaps against that snapshot. References into remote-only snapshots stay anchored by the declared content hash and cannot be dereferenced locally.

Actions and executions

Every action has one owner, one action_status, and at least one measurable acceptance_criteria entry. dependencies resolve to other actions in the same envelope and form an acyclic graph.

Each execution references one action through action_ref. It records hashed inputs, an environment lockfile locator and digest, and the code revision. A published handoff uses the exact commit; a development fixture may use an explicit uncommitted-tree-based-on:<commit> descriptor. The validator verifies a local environment lockfile and includes it in the report's inputs map. Terminal runs record completed_on and execution_outcome; completed runs also record at least one hashed output. A completed action requires a linked completed execution.

Revision heads and conflicts

current_heads identifies the revisions that an agent may extend. When no conflict is open, the envelope's revision is a current head. An open conflict lists at least two competing_heads, all of which are current heads. A resolved conflict records resolution and a resolved_by_head that appears in current_heads.

Validation

Validate the worked two-agent fixture against the LinkML (Linked Data Modeling Language) root:

uv run linkml-validate \
  -s skills/csag-extraction/assets/csag.yaml \
  -C HandoffEnvelope \
  tests/fixtures/handoff/two_agent_handoff.valid.json

Run the semantic handoff profile through the CLI:

uv run csag validate \
  tests/fixtures/handoff/two_agent_handoff.valid.json \
  --profile handoff \
  --report-out /tmp/two_agent_handoff.validation.json

The closed JSON Schema is skills/csag-extraction/assets/csag.handoff.schema.json. The fixture contains two agent-owned actions and executions, a two-parent merge revision, and a resolved conflict. The fixture directory is self-contained. It includes the source extraction, Markdown, article sidecar, validation report, quality report, and environment lockfile that the envelope references.

These files are historical snapshots of the fixture's recorded executions. The quality report retains the checks from that execution, including the Dataset signal field. It is not an expected-output fixture for the current quality-report command; handoff tests verify its recorded content hashes.