@humain/humain-code-contracts

Runtime-neutral contracts shared by HUMAIN Code CLI and its hosts.

• The package root exports agent-execution v1 schemas, types, validators, and parsers.
• The package root also exports Auto-mode orchestration contracts: the orchestration policy block Forge writes for the sandbox extension (OrchestrationPolicyV1Schema, parseOrchestrationPolicy), the frozen run decision record (RunOrchestrationDecisionV1Schema), and the subagent task event and identity envelope shapes the runtime emits (SubagentTaskEventSchema, parseSubagentTaskEvent, SubagentIdentityEnvelopeSchema).
• @humain/humain-code-contracts/orchestration exports the same orchestration contracts directly.
• @humain/humain-code-contracts/rpc exports the minimal persistent RPC wire seam used by Forge. It is dependency-free (no TypeBox, no Node APIs) and reads the optional subagentProgress metadata through readRpcSubagentProgress.
• The subagent progress projection (schemaVersion 1, "C1") carries per-worker agent, label, task, model, timestamps, turns, toolCalls, failureKind and resultPreview, and per-run toolCallId, mode, startedAt and endedAt. Text fields are presentation text: render as plain text, never markdown or HTML. Producers sanitize with toSubagentPresentationText; parsers validate with isSubagentPresentationText. See docs/research/a04-c1-contract.md.
• @humain/humain-code-contracts/testing exports immutable execution conformance vectors and subagentProgressFixtures / invalidSubagentProgressFixtures for progress consumers.

Synthetic-local trace contracts

@humain/humain-code-contracts/trace exports the runtime-neutral C0 raw JSON/JCS, admission, workload/delegation, managed retry and ACK context helpers. Origin event, artifact and ACK schemas remain /1; producer enrollment and enrollment requests use /2. Parser success is not authentication, registry admission or durable receipt. Callers supply authenticated ownership and committed amendment context for retry eligibility; missing authority cannot resolve an unknown terminal.

Package version 0.3.3 records the disabled-by-default C0 technical resolution, not production approval. Batch ingress remains exclusively dh.batch/1-proposal (resolved-synthetic-local); origin contractVersion stays 1.

Usage and records policy (0.3.3, additions only): dh.usage-response/1, dh.usage-search-page/1 and the append-only dh.usage-correction/1 expose submission-owned usage. Failed attempts are summed, inclusive Flow aggregates add zero, and unknown usage or price is an explicit unknown, never zero. dh.generation-delete-request/1, dh.generation-deletion/1, dh.legal-hold-request/1, dh.legal-hold/1 and dh.legal-hold-release-request/1 cover generation delete and legal holds; an active hold always wins over deletion. See decisions D18 and D19.

Read pages and complete cursor bindings use /2. A dh.snapshot-cutoff/1 committed receipt ordinal fixes the snapshot; captureCutoff is display time only. Bindings include the immutable generation root (or project mapping for lists), principal, grant, session and authorization revision. Compare the full returned binding across pages and processes; never reconstruct it from timestamps.

Export header/page /2 carries sorted, representation-specific digests and segment ownership. beginDhExportManifest / acceptDhExportManifestPage / finishDhExportManifest retain one last identity and at most 1,024 descriptors and navigation cursors, not all records. Hash callbacks consume exact Uint8Array bytes, including the binary root chain. parseDhExportManifestResponse places the first opaque cursor outside the sealed header. The older monolithic manifest is historical/import-only.

Passive DH-BUNDLE/1 verification checks frames, membership, omissions, canonical records, header/root, seal and entire-byte download /2 digest. Artifact chunks are never buffered by contracts. Publish an owned staged file only after finishDhBundleVerification succeeds; native reads and atomic publication remain consumer responsibilities.

Control requests/status use /2 admission, attempt, session and capability fences. Applied retry requires both observed start IDs with actual linkage; applied continue requires target consumption, never queue-steering. Controller descriptors are non-secret. The handshake token belongs only to private socket/fd3 transport, not journals or diagnostics. Delivery assertions recheck supplied live authority, deadline, scope, fences and request digest; they do not implement durable effects.

Capability and artifact manifests bind package/export/schema/vector identities and exact build/mode/platform qualifications. Required controls are not supported controls. A contracts-only manifest may have no runtimes. Artifact fixture bytes are synthetic vectors, not a delivered tarball or native qualification evidence. See the decision record for parser enforcement and remaining product-owner integration requirements.

parseDhRawJson rejects decoded duplicate keys, malformed UTF-8/Unicode and integer-form tokens that change mathematical integer value in binary64. Exactly representable larger integers, including 100000000000000000000, are accepted; decimal/exponent tokens use finite binary64 semantics. Count fields still require safe integers. dhCanonicalText uses RFC 8785 ECMAScript number rendering and UTF-16 key order without Unicode normalization. It rejects getters, toJSON and sparse arrays before invocation. dhDigestInput returns UTF-8 domain + NUL + JCS; callers hash those bytes with native SHA-256. Artifact content and spool integrity hashes remain raw-byte hashes, not canonical record digests.

For POST replies, validate sent views with assertDhAckSentBatch and pass the parsed mandatory x-dh-previous-acked-sequence to the unchanged validateDhBatchAck. Empty event prefixes never advance the local cursor. Artifact metadata acceptance is separate from byte durability: inspect the PUT receipt's state even after validating its ID/hash/size.

These helpers do not implement workload registries, publication/revocation locks, private bootstrap custody, native launch/cancellation, transport retries or GC. Synthetic capability and production activation remain product-owner decisions.

This package contains no process, stream, provider, filesystem, or execution-host code.