@humain/humain-code-contracts 0.3.2

package/dist/trace-payload.js

@@ -0,0 +1,1519 @@
+import { Type } from "typebox";
+import { DH_COVERAGE_REASONS, DH_COVERAGE_STATES, DH_EVENT_KINDS, DH_OUTCOMES, DhAgentIdSchema, DhArtifactIdSchema, DhAttemptIdSchema, DhEventIdSchema, resolveDhEffectiveTerminals, } from "./trace.js";
+import { DhContractError } from "./trace-canonical.js";
+import { DH_CONTROL_ACTIONS, DH_CONTROL_REJECT_REASONS, DH_CONTROL_STATES, dhStrictDtoParser } from "./trace-http.js";
+/*
+ * C0 typed payload contracts. `payload.schema` carries a `dh.payload.<name>/1` id; the registry maps
+ * (event kind, payload schema id) to a strict parser. The event envelope stays `dh.event/1`: payloads
+ * remain JSON objects bounded by assertJsonPayload, and these parsers only tighten them.
+ *
+ * Rules
+ * - Event kinds that existed before this freeze (DH_LEGACY_FREEFORM_PAYLOAD_KINDS) may still carry a
+ *   legacy freeform payload WITHOUT `schema`, so current CLI/Flow producer output stays valid. If such a
+ *   payload has `schema`, it must be a registered id for that kind (no typo can masquerade as legacy).
+ * - Kinds added by this freeze (DH_PAYLOAD_REQUIRED_KINDS) have no legacy shape: `schema` is required.
+ * - Field names already emitted by the CLI (callId, toolName, stopReason, nonTextBlockCount, childAgentId,
+ *   spawnedByEventId, nextAttemptNumber, delayMs, ...) keep their spelling.
+ * - Coverage and loss stay in the envelope `fields`; payload schemas never duplicate them, they only
+ *   require that an absent value has explicit loss coverage.
+ * - Raw file paths never appear in typed payloads: a file is referenced by artifact.
+ * - This module is loaded through the trace.ts <-> trace-http.ts import cycle: NOTHING here reads an
+ *   imported value at module top level. Schemas and parsers are built lazily on first use.
+ */
+export const DH_PAYLOAD_SCHEMA_IDS = Object.freeze({
+    agentRelation: "dh.payload.agent-relation/1",
+    agentSpawn: "dh.payload.agent-spawn/1",
+    amendment: "dh.payload.amendment/1",
+    attemptLifecycle: "dh.payload.attempt-lifecycle/1",
+    captureHealth: "dh.payload.capture-health/1",
+    continuationDecision: "dh.payload.continuation-decision/1",
+    controlCorrelation: "dh.payload.control-correlation/1",
+    fileEvidence: "dh.payload.file-evidence/1",
+    flowDecision: "dh.payload.flow-decision/1",
+    localCancellation: "dh.payload.local-cancellation/1",
+    modelResponse: "dh.payload.model-response/1",
+    modelSubmission: "dh.payload.model-submission/1",
+    toolCall: "dh.payload.tool-call/1",
+    toolResult: "dh.payload.tool-result/1",
+    usage: "dh.payload.usage/1",
+});
+/** Kinds that existed before typed payloads. They may keep a freeform payload without `schema`. */
+export const DH_LEGACY_FREEFORM_PAYLOAD_KINDS = Object.freeze([
+    "generation.started",
+    "generation.finished",
+    "agent.spawned",
+    "attempt.started",
+    "attempt.finished",
+    "attempt.retry_scheduled",
+    "model.request",
+    "model.response",
+    "tool.call",
+    "tool.result",
+    "file.change",
+    "orchestration.decision",
+    "cancellation.requested",
+    "cancellation.outcome",
+    "usage.reported",
+]);
+/** Kinds introduced with typed payloads; `payload.schema` is mandatory. */
+export const DH_PAYLOAD_REQUIRED_KINDS = Object.freeze([
+    "capture.health",
+    "control.correlation",
+    "event.amendment",
+]);
+/**
+ * Continuation decisions recorded on `orchestration.decision` (dh.payload.continuation-decision/1).
+ * `consumed` is the only consumption event type: a control `continue` is `applied` only when the addressed
+ * target recorded `continuation.consumed` for that request (admitted, pending and rejected are not consumption).
+ */
+export const DH_CONTINUATION_DECISIONS = [
+    "continuation.pending",
+    "continuation.admitted",
+    "continuation.rejected",
+    "continuation.consumed",
+];
+/** Delivery channel of a continuation. `queue-steering` is never a live continuation of a running child. */
+export const DH_CONTINUATION_CHANNELS = [
+    "live-child",
+    "native-descendant",
+    "run-root",
+    "queue-steering",
+    "internal",
+];
+/** Named observations from the existing local process-cancellation seam; never arbitrary diagnostic text. */
+export const DH_LOCAL_CANCELLATION_DIAGNOSTICS = [
+    "cancelled_before_spawn",
+    "logical_cancellation_observed",
+    "process_closed_after_signal",
+];
+const IDS = DH_PAYLOAD_SCHEMA_IDS;
+/** Which event kinds each payload schema id may appear on. */
+const REGISTRATIONS = [
+    { id: IDS.modelSubmission, kinds: ["model.request"] },
+    { id: IDS.modelResponse, kinds: ["model.response"] },
+    { id: IDS.toolCall, kinds: ["tool.call"] },
+    { id: IDS.toolResult, kinds: ["tool.result"] },
+    { id: IDS.fileEvidence, kinds: ["file.change"] },
+    { id: IDS.agentSpawn, kinds: ["agent.spawned"] },
+    { id: IDS.agentRelation, kinds: ["agent.spawned"] },
+    { id: IDS.attemptLifecycle, kinds: ["attempt.started", "attempt.finished", "attempt.retry_scheduled"] },
+    { id: IDS.flowDecision, kinds: ["orchestration.decision"] },
+    { id: IDS.continuationDecision, kinds: ["orchestration.decision"] },
+    { id: IDS.usage, kinds: ["usage.reported"] },
+    { id: IDS.captureHealth, kinds: ["capture.health"] },
+    { id: IDS.controlCorrelation, kinds: ["control.correlation", "cancellation.requested", "cancellation.outcome"] },
+    { id: IDS.localCancellation, kinds: ["cancellation.requested", "cancellation.outcome"] },
+    { id: IDS.amendment, kinds: ["event.amendment"] },
+];
+/** Payload schema ids accepted on a kind (empty for kinds that only carry legacy freeform payloads). */
+export function dhPayloadSchemaIdsForKind(kind) {
+    return REGISTRATIONS.filter((entry) => entry.kinds.includes(kind)).map((entry) => entry.id);
+}
+// ---------------------------------------------------------------------------
+// Shared schema pieces (only `typebox` values at top level; everything else is lazy)
+// ---------------------------------------------------------------------------
+const strict = (properties) => Type.Object(properties, { additionalProperties: false });
+const count = Type.Integer({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER });
+const positive = Type.Integer({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER });
+const digest = Type.String({ pattern: "^[a-f0-9]{64}$" });
+const text = Type.String({ minLength: 1, maxLength: 256 });
+/** Opaque producer-side identifier (request, submission, call, logical task). */
+const ident = Type.String({ minLength: 1, maxLength: 128, pattern: "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$" });
+const code = Type.String({ pattern: "^[a-z][a-z0-9_.-]{0,63}$", maxLength: 64 });
+const revision = Type.String({ pattern: "^[a-f0-9]{40}(?:[a-f0-9]{24})?$" });
+const requestId = Type.String({ pattern: "^ctl_[A-Za-z0-9_-]{8,128}$", maxLength: 132 });
+const FIELD_PATH = "^[A-Za-z][A-Za-z0-9_-]*(?:\\.[A-Za-z0-9_-]+)*$";
+const FORBIDDEN_SEGMENTS = new Set(["__proto__", "constructor", "prototype"]);
+const LOSS_STATES = new Set(["unavailable", "redacted", "truncated"]);
+const MAX_LIST = 64;
+const artifactRef = () => strict({ artifactId: DhArtifactIdSchema, sha256: digest, sizeBytes: Type.Optional(count) });
+const coverageGap = () => strict({
+    path: Type.String({ minLength: 1, maxLength: 256, pattern: FIELD_PATH }),
+    state: Type.Enum(DH_COVERAGE_STATES),
+    reason: Type.Optional(Type.Enum(DH_COVERAGE_REASONS)),
+});
+const usageOrigin = () => Type.Union([
+    strict({ owner: Type.Literal("submission"), submissionId: ident }),
+    strict({ owner: Type.Literal("attempt"), attemptId: DhAttemptIdSchema }),
+    strict({ owner: Type.Literal("flow-aggregate"), inclusive: Type.Literal(true) }),
+]);
+/** Unknown is explicit (`state: unknown`); an absent count is unknown, never zero; price is known-with-provenance or unknown. */
+const measurement = () => Type.Union([
+    strict({ state: Type.Literal("unknown") }),
+    strict({
+        state: Type.Literal("reported"),
+        input: Type.Optional(count),
+        output: Type.Optional(count),
+        cacheRead: Type.Optional(count),
+        cacheWrite: Type.Optional(count),
+        reasoning: Type.Optional(count),
+        totalTokens: Type.Optional(count),
+        durationMs: Type.Optional(count),
+        cost: Type.Union([
+            strict({ state: Type.Literal("unknown") }),
+            strict({
+                state: Type.Literal("known"),
+                amount: Type.Number({ minimum: 0 }),
+                currency: Type.String({ pattern: "^[A-Z]{3}$" }),
+                priceProvenance: text,
+            }),
+        ]),
+    }),
+]);
+const snapshot = () => Type.Union([
+    strict({ state: Type.Literal("observed"), sha256: digest, sizeBytes: count }),
+    strict({
+        state: Type.Literal("unavailable"),
+        reason: Type.Enum(["missing", "denied", "oversized", "binary", "unsupported", "read-failed"]),
+    }),
+]);
+// ---------------------------------------------------------------------------
+// Check helpers
+// ---------------------------------------------------------------------------
+function bad(id, reason) {
+    throw new DhContractError("schema_invalid", `Invalid ${id}: ${reason}`);
+}
+function listed(event, artifactId) {
+    return (event.artifacts ?? []).includes(artifactId);
+}
+function assertListed(id, event, artifactId) {
+    if (!listed(event, artifactId))
+        bad(id, "artifact is not listed in event artifacts");
+}
+function assertLossCovered(id, event, path) {
+    const coverage = event.fields[path];
+    if (coverage === undefined || !LOSS_STATES.has(coverage.state)) {
+        bad(id, "absent field requires unavailable, redacted or truncated coverage");
+    }
+}
+function assertEventAttempt(id, event, attemptId) {
+    if (event.attemptId === undefined)
+        bad(id, "attemptId is required on the event");
+    if (event.attemptId !== attemptId)
+        bad(id, "attemptId does not match the event attemptId");
+}
+function assertGaps(id, gaps) {
+    for (const gap of gaps) {
+        if (gap.state === "captured" || gap.reason === undefined) {
+            bad(id, "coverage entries must describe a loss state and give a reason");
+        }
+        if (gap.path.split(".").some((segment) => FORBIDDEN_SEGMENTS.has(segment))) {
+            bad(id, "coverage path is not a valid field path");
+        }
+    }
+}
+function assertMeasurement(id, value) {
+    if (value.state !== "reported")
+        return;
+    const tokens = [value.input, value.output, value.cacheRead, value.cacheWrite, value.reasoning, value.totalTokens];
+    if (tokens.every((token) => token === undefined) && value.cost.state !== "known") {
+        bad(id, "measurement reports no token count and no known cost; use state unknown");
+    }
+}
+/**
+ * `semantic` sees the payload only; `envelope` also sees the event envelope. Both run after the shared
+ * strict DTO parser (plain-JSON wire gate, schema check, clone, re-check).
+ */
+function define(id, schema, semantic, envelope) {
+    const parse = dhStrictDtoParser(id, schema, semantic);
+    return {
+        check: (event) => {
+            const payload = parse(event.payload);
+            envelope?.(payload, event);
+        },
+    };
+}
+// -- model submission / response ---------------------------------------------------------------
+function modelSubmissionSchema() {
+    return strict({
+        schema: Type.Literal(IDS.modelSubmission),
+        requestId: ident,
+        submissionId: ident,
+        attemptId: DhAttemptIdSchema,
+        transportRetryIndex: Type.Integer({ minimum: 0, maximum: 1000 }),
+        provider: text,
+        api: text,
+        model: text,
+        operation: Type.Enum(["chat", "image", "classifier", "auxiliary"]),
+        purpose: Type.Optional(Type.Enum(["chat", "compaction", "branch-summary", "cache-warming"])),
+        transport: Type.Enum(["http", "websocket"]),
+        representation: Type.Enum(["json-body", "json-frame"]),
+        adapterVersion: Type.Optional(text),
+        requestArtifact: Type.Optional(artifactRef()),
+    });
+}
+function modelResponseSchema() {
+    return strict({
+        schema: Type.Literal(IDS.modelResponse),
+        submissionId: ident,
+        attemptId: DhAttemptIdSchema,
+        stopReason: Type.Enum(["pending", "stop", "length", "toolUse", "error", "aborted", "deferred"]),
+        provider: Type.Optional(text),
+        api: Type.Optional(text),
+        model: Type.Optional(text),
+        responseModel: Type.Optional(text),
+        toolCallCount: Type.Optional(count),
+        text: Type.Optional(Type.String({ maxLength: 65536 })),
+        reasoning: Type.Optional(Type.String({ maxLength: 65536 })),
+        errorMessage: Type.Optional(Type.String({ maxLength: 4096 })),
+        responseArtifact: Type.Optional(artifactRef()),
+        usage: Type.Optional(strict({ origin: usageOrigin(), measurement: measurement() })),
+    });
+}
+// -- tool calls --------------------------------------------------------------------------------
+/**
+ * The typed call carries no free `arguments` object: the shared DTO parser scans every nested key for
+ * instant-named fields (`startedAt`, `occurredAt`, ...), so arbitrary tool arguments would be rejected on a
+ * name collision. Arguments travel as a bounded redacted JSON-text preview and/or a complete artifact; a
+ * truncated preview is marked in the envelope `fields` at `payload.argumentsPreview`.
+ */
+function toolCallSchema() {
+    return strict({
+        schema: Type.Literal(IDS.toolCall),
+        callId: ident,
+        toolName: text,
+        argumentsPreview: Type.Optional(Type.String({ maxLength: 4096 })),
+        argumentsArtifact: Type.Optional(artifactRef()),
+        /** Provenance of a nested call: the enclosing call's id and (when recorded) its tool.call event. */
+        parentCallId: Type.Optional(ident),
+        parentEventId: Type.Optional(DhEventIdSchema),
+    });
+}
+// -- tool results ------------------------------------------------------------------------------
+function toolResultSchema() {
+    return strict({
+        schema: Type.Literal(IDS.toolResult),
+        callId: ident,
+        toolName: text,
+        stage: Type.Enum(["original", "final"]),
+        source: Type.Enum(["executed", "blocked", "synthetic"]),
+        isError: Type.Boolean(),
+        modified: Type.Optional(Type.Boolean()),
+        originalResultEventId: Type.Optional(DhEventIdSchema),
+        parentCallId: Type.Optional(ident),
+        output: Type.Optional(Type.String({ maxLength: 65536 })),
+        outputArtifact: Type.Optional(artifactRef()),
+        nonTextBlockCount: count,
+        nonTextArtifacts: Type.Optional(Type.Array(artifactRef(), { maxItems: MAX_LIST })),
+        childAgentId: Type.Optional(DhAgentIdSchema),
+        childAgentIds: Type.Optional(Type.Array(DhAgentIdSchema, { maxItems: MAX_LIST, uniqueItems: true })),
+    });
+}
+// -- file evidence -----------------------------------------------------------------------------
+function fileEvidenceSchema() {
+    return strict({
+        schema: Type.Literal(IDS.fileEvidence),
+        callId: ident,
+        toolName: text,
+        operation: Type.Enum(["write", "edit", "delete"]),
+        outcome: Type.Enum(["succeeded", "failed", "cancelled"]),
+        intent: strict({
+            contentSha256: Type.Optional(digest),
+            contentBytes: Type.Optional(count),
+            patchSha256: Type.Optional(digest),
+        }),
+        observed: strict({ before: snapshot(), after: snapshot(), effectObserved: Type.Boolean() }),
+        pathRef: artifactRef(),
+        evidence: Type.Optional(Type.Array(strict({
+            artifactId: DhArtifactIdSchema,
+            sha256: digest,
+            sizeBytes: Type.Optional(count),
+            role: Type.Enum(["diff", "snapshot"]),
+        }), { maxItems: 8 })),
+        worktree: Type.Optional(strict({
+            mode: Type.Enum(["shared", "isolated", "degraded-to-shared"]),
+            baseRevision: Type.Optional(revision),
+            endRevision: Type.Optional(revision),
+            baseObserved: Type.Boolean(),
+        })),
+    });
+}
+// -- lifecycle ---------------------------------------------------------------------------------
+function agentSpawnSchema() {
+    return strict({
+        schema: Type.Literal(IDS.agentSpawn),
+        via: Type.Enum(["subagent", "flow"]),
+        spawnedByEventId: Type.Optional(DhEventIdSchema),
+        launchedByToolCallEventId: Type.Optional(DhEventIdSchema),
+        command: Type.Optional(strict({ name: text, decisionEventId: Type.Optional(DhEventIdSchema) })),
+        logicalTaskId: Type.Optional(ident),
+        nativeLaunchId: Type.Optional(ident),
+    });
+}
+/** Cross-agent relation (native Code retry): a NEW agent linked to its source, never a same-agent retryOfAttemptId. */
+function agentRelationSchema() {
+    return strict({
+        schema: Type.Literal(IDS.agentRelation),
+        via: Type.Literal("native-code"),
+        relation: Type.Literal("native-retry"),
+        sourceAgentId: DhAgentIdSchema,
+        sourceAttemptId: DhAttemptIdSchema,
+        reasonCode: Type.Optional(code),
+    });
+}
+const PHASE_KIND = {
+    started: "attempt.started",
+    finished: "attempt.finished",
+    "retry-scheduled": "attempt.retry_scheduled",
+};
+function attemptLifecycleSchema() {
+    return strict({
+        schema: Type.Literal(IDS.attemptLifecycle),
+        phase: Type.Enum(["started", "finished", "retry-scheduled"]),
+        agentId: DhAgentIdSchema,
+        attemptId: DhAttemptIdSchema,
+        attemptNumber: Type.Optional(positive),
+        retryOfAttemptId: Type.Optional(DhAttemptIdSchema),
+        retryReason: Type.Optional(code),
+        nextAttemptNumber: Type.Optional(positive),
+        delayMs: Type.Optional(count),
+        spawnOutcome: Type.Optional(Type.Enum(["spawned", "failed-to-spawn", "unknown"])),
+        terminationConfirmed: Type.Optional(Type.Boolean()),
+    });
+}
+// -- flow decisions ----------------------------------------------------------------------------
+function flowDecisionSchema() {
+    return strict({
+        schema: Type.Literal(IDS.flowDecision),
+        decision: Type.Enum(["schedule", "delegate", "dependency-not-launched", "dependency-released", "retry"]),
+        issuer: Type.Literal("flow"),
+        via: Type.Literal("flow"),
+        mode: Type.Enum(["single", "parallel", "chain", "hierarchy"]),
+        /** A command launch has no tool call: the two variants share no event-id field. */
+        provenance: Type.Union([
+            strict({ source: Type.Literal("tool-call"), toolCallEventId: DhEventIdSchema }),
+            strict({ source: Type.Literal("command"), command: text, commandEventId: Type.Optional(DhEventIdSchema) }),
+            strict({ source: Type.Literal("internal") }),
+        ]),
+        logicalTaskId: Type.Optional(ident),
+        dependencies: Type.Optional(Type.Array(ident, { maxItems: MAX_LIST })),
+        causeEventId: Type.Optional(DhEventIdSchema),
+        childAgentId: Type.Optional(DhAgentIdSchema),
+        failedAttemptId: Type.Optional(DhAttemptIdSchema),
+        nextAttemptNumber: Type.Optional(positive),
+        delayMs: Type.Optional(count),
+        wave: Type.Optional(count),
+        order: Type.Optional(count),
+        policyVersion: Type.Optional(text),
+        reasonCode: Type.Optional(code),
+    });
+}
+/**
+ * A continuation decision about one addressed target (agent + attempt). `pending` and `consumed` are recorded
+ * by the target itself; `admitted` and `rejected` may be recorded by the admitting authority. `requestId`
+ * links a decision to a control `continue` request; a continuation that no request caused names none. Message
+ * text never appears here: it is content, and would also be free text inside a typed payload.
+ */
+function continuationDecisionSchema() {
+    return strict({
+        schema: Type.Literal(IDS.continuationDecision),
+        decision: Type.Enum(DH_CONTINUATION_DECISIONS),
+        target: strict({ agentId: DhAgentIdSchema, attemptId: DhAttemptIdSchema }),
+        requestId: Type.Optional(requestId),
+        channel: Type.Enum(DH_CONTINUATION_CHANNELS),
+        reason: Type.Optional(Type.Enum(DH_CONTROL_REJECT_REASONS)),
+    });
+}
+// -- usage, health, control, amendment ---------------------------------------------------------
+function usageSchema() {
+    return strict({
+        schema: Type.Literal(IDS.usage),
+        usageId: ident,
+        origin: usageOrigin(),
+        measurement: measurement(),
+    });
+}
+function captureHealthSchema() {
+    return strict({
+        schema: Type.Literal(IDS.captureHealth),
+        status: Type.Enum(["healthy", "degraded", "failed", "recovered"]),
+        condition: Type.Enum([
+            "none",
+            "dropped",
+            "write_failed",
+            "redaction_failed",
+            "unsupported_adapter",
+            "flush_timeout",
+            "lost_observer",
+            "recovery",
+        ]),
+        droppedEvents: Type.Optional(count),
+        droppedArtifacts: Type.Optional(count),
+        adapter: Type.Optional(strict({ name: text, version: text })),
+        affectedKinds: Type.Optional(Type.Array(Type.Enum(DH_EVENT_KINDS), { maxItems: 32, uniqueItems: true })),
+        coverageGaps: Type.Optional(Type.Array(coverageGap(), { maxItems: 32 })),
+        sequenceRange: Type.Optional(strict({ from: count, to: count })),
+    });
+}
+function controlCorrelationSchema() {
+    return strict({
+        schema: Type.Literal(IDS.controlCorrelation),
+        requestId,
+        action: Type.Enum(DH_CONTROL_ACTIONS),
+        phase: Type.Enum(["requested", "observed"]),
+        state: Type.Enum(DH_CONTROL_STATES),
+        reason: Type.Optional(Type.Enum(DH_CONTROL_REJECT_REASONS)),
+        terminationConfirmed: Type.Optional(Type.Boolean()),
+        observed: Type.Optional(strict({
+            startedAgentId: Type.Optional(DhAgentIdSchema),
+            startedAttemptId: Type.Optional(DhAttemptIdSchema),
+            consumingEventId: Type.Optional(DhEventIdSchema),
+        })),
+    });
+}
+/** Local cancellation is not a Code control request: there is deliberately no requestId. */
+function localCancellationSchema() {
+    return strict({
+        schema: Type.Literal(IDS.localCancellation),
+        requester: Type.Literal("local"),
+        scope: Type.Enum(["selected", "whole-run"]),
+        phase: Type.Enum(["requested", "observed"]),
+        state: Type.Enum(["requested", "applied", "rejected", "unsupported", "unknown"]),
+        reason: Type.Optional(Type.Enum(DH_CONTROL_REJECT_REASONS)),
+        diagnosticCode: Type.Optional(Type.Enum(DH_LOCAL_CANCELLATION_DIAGNOSTICS)),
+        terminationConfirmed: Type.Optional(Type.Boolean()),
+        exitCode: Type.Optional(Type.Integer({ minimum: Number.MIN_SAFE_INTEGER, maximum: Number.MAX_SAFE_INTEGER })),
+    });
+}
+function amendmentSchema() {
+    return strict({
+        schema: Type.Literal(IDS.amendment),
+        amendsEventId: DhEventIdSchema,
+        amendsKind: Type.Enum(DH_EVENT_KINDS),
+        relation: Type.Enum(["supersedes", "resolves-unknown"]),
+        reasonCode: code,
+        coverage: Type.Optional(Type.Array(coverageGap(), { minItems: 1, maxItems: 32 })),
+        replacement: Type.Optional(strict({ outcome: Type.Enum(DH_OUTCOMES), failureCode: Type.Optional(code) })),
+    });
+}
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+function buildParsers() {
+    const submission = define(IDS.modelSubmission, modelSubmissionSchema, undefined, (payload, event) => {
+        const id = IDS.modelSubmission;
+        assertEventAttempt(id, event, payload.attemptId);
+        if (payload.requestArtifact !== undefined) {
+            assertListed(id, event, payload.requestArtifact.artifactId);
+        }
+        else
+            assertLossCovered(id, event, "payload.requestArtifact");
+    });
+    const response = define(IDS.modelResponse, modelResponseSchema, (payload) => {
+        if (payload.usage !== undefined)
+            assertMeasurement(IDS.modelResponse, payload.usage.measurement);
+    }, (payload, event) => {
+        const id = IDS.modelResponse;
+        assertEventAttempt(id, event, payload.attemptId);
+        const origin = payload.usage?.origin;
+        if (origin !== undefined && (origin.owner !== "submission" || origin.submissionId !== payload.submissionId)) {
+            bad(id, "usage origin must be the submission this response answers");
+        }
+        if (payload.responseArtifact !== undefined)
+            assertListed(id, event, payload.responseArtifact.artifactId);
+    });
+    const toolCall = define(IDS.toolCall, toolCallSchema, (payload) => {
+        const id = IDS.toolCall;
+        if (payload.parentEventId !== undefined && payload.parentCallId === undefined) {
+            bad(id, "parentEventId requires parentCallId");
+        }
+        if (payload.parentCallId === payload.callId)
+            bad(id, "a call cannot be its own parent");
+    }, (payload, event) => {
+        const id = IDS.toolCall;
+        if (payload.argumentsArtifact !== undefined) {
+            assertListed(id, event, payload.argumentsArtifact.artifactId);
+        }
+        else if (payload.argumentsPreview === undefined)
+            assertLossCovered(id, event, "payload.argumentsArtifact");
+    });
+    const toolResult = define(IDS.toolResult, toolResultSchema, (payload) => {
+        const id = IDS.toolResult;
+        if (payload.stage === "original") {
+            if (payload.originalResultEventId !== undefined) {
+                bad(id, "originalResultEventId is only allowed on a final result");
+            }
+            if (payload.modified !== undefined)
+                bad(id, "modified is only allowed on a final result");
+        }
+        else if (payload.originalResultEventId === undefined) {
+            bad(id, "originalResultEventId is required on a final result");
+        }
+        if (payload.childAgentId !== undefined && payload.childAgentIds !== undefined) {
+            bad(id, "use childAgentId or childAgentIds, not both");
+        }
+        if ((payload.nonTextArtifacts?.length ?? 0) > 0 && payload.nonTextBlockCount === 0) {
+            bad(id, "nontext artifacts require nonTextBlockCount above zero");
+        }
+    }, (payload, event) => {
+        const id = IDS.toolResult;
+        if (payload.stage === "original") {
+            // The untouched executed result keeps the real execution outcome, independent of later hooks.
+            if (event.outcome === undefined)
+                bad(id, "outcome is required on an original tool result");
+            if (event.outcome === "succeeded" && payload.isError)
+                bad(id, "isError contradicts outcome succeeded");
+            if (event.outcome === "failed" && !payload.isError)
+                bad(id, "isError contradicts outcome failed");
+        }
+        if (payload.outputArtifact !== undefined)
+            assertListed(id, event, payload.outputArtifact.artifactId);
+        if (payload.nonTextBlockCount > 0) {
+            const artifacts = payload.nonTextArtifacts ?? [];
+            for (const ref of artifacts)
+                assertListed(id, event, ref.artifactId);
+            if (artifacts.length === 0) {
+                const coverage = event.fields["payload.nonTextContent"];
+                if (coverage === undefined || !LOSS_STATES.has(coverage.state)) {
+                    bad(id, "nontext content has neither artifacts nor loss coverage at payload.nonTextContent");
+                }
+            }
+        }
+    });
+    const file = define(IDS.fileEvidence, fileEvidenceSchema, (payload) => {
+        const id = IDS.fileEvidence;
+        const { before, after, effectObserved } = payload.observed;
+        if (effectObserved && after.state !== "observed") {
+            bad(id, "effectObserved requires an observed after snapshot");
+        }
+        if (before.state === "observed" && after.state === "observed") {
+            const changed = before.sha256 !== after.sha256;
+            if (changed !== effectObserved)
+                bad(id, "effectObserved must match the snapshot change when both snapshots are observed");
+        }
+        const tree = payload.worktree;
+        if (tree !== undefined) {
+            if (!tree.baseObserved && tree.baseRevision !== undefined) {
+                bad(id, "baseRevision must not be recorded when the base was not observed");
+            }
+            if (tree.mode === "isolated" && (!tree.baseObserved || tree.baseRevision === undefined)) {
+                bad(id, "an isolated worktree needs an observed baseRevision");
+            }
+        }
+    }, (payload, event) => {
+        const id = IDS.fileEvidence;
+        assertListed(id, event, payload.pathRef.artifactId);
+        for (const ref of payload.evidence ?? [])
+            assertListed(id, event, ref.artifactId);
+    });
+    const spawn = define(IDS.agentSpawn, agentSpawnSchema, (payload) => {
+        const id = IDS.agentSpawn;
+        if (payload.via === "subagent") {
+            if (payload.command !== undefined)
+                bad(id, "a subagent spawn cannot carry command");
+            if (payload.launchedByToolCallEventId !== undefined) {
+                bad(id, "a subagent spawn uses spawnedByEventId, not launchedByToolCallEventId");
+            }
+            return;
+        }
+        if (payload.spawnedByEventId !== undefined)
+            bad(id, "a flow launch does not use spawnedByEventId");
+        if ((payload.launchedByToolCallEventId === undefined) === (payload.command === undefined)) {
+            bad(id, "exactly one of launchedByToolCallEventId or command is required");
+        }
+    }, (payload, event) => {
+        const id = IDS.agentSpawn;
+        if (payload.via === "flow") {
+            if (event.producer.issuer !== "flow")
+                bad(id, "a flow launch requires producer issuer flow");
+        }
+        else if (payload.spawnedByEventId === undefined)
+            assertLossCovered(id, event, "payload.spawnedByEventId");
+    });
+    const relation = define(IDS.agentRelation, agentRelationSchema, undefined, (payload, event) => {
+        const id = IDS.agentRelation;
+        if (payload.sourceAgentId === event.agentId) {
+            bad(id, "a cross-agent relation needs a sourceAgentId different from the event agentId");
+        }
+        if (event.retryOfAttemptId !== undefined) {
+            bad(id, "retryOfAttemptId is a same-agent link and cannot accompany a cross-agent relation");
+        }
+        if (event.producer.issuer !== "code")
+            bad(id, "native retry requires Code issuer");
+    });
+    const lifecycle = define(IDS.attemptLifecycle, attemptLifecycleSchema, (payload) => {
+        const id = IDS.attemptLifecycle;
+        if (payload.retryOfAttemptId !== undefined) {
+            if (payload.phase !== "started")
+                bad(id, "retryOfAttemptId is only allowed in phase started");
+            if (payload.retryOfAttemptId === payload.attemptId)
+                bad(id, "retryOfAttemptId cannot equal attemptId");
+        }
+        if (payload.phase === "retry-scheduled") {
+            if (payload.delayMs === undefined)
+                bad(id, "delayMs is required in phase retry-scheduled");
+            if (payload.nextAttemptNumber === undefined || payload.nextAttemptNumber < 2) {
+                bad(id, "nextAttemptNumber of at least 2 is required in phase retry-scheduled");
+            }
+        }
+        else if (payload.nextAttemptNumber !== undefined || payload.delayMs !== undefined) {
+            bad(id, "nextAttemptNumber and delayMs are only allowed in phase retry-scheduled");
+        }
+        if (payload.terminationConfirmed !== undefined && payload.phase !== "finished") {
+            bad(id, "terminationConfirmed is only allowed in phase finished");
+        }
+        if (payload.spawnOutcome !== undefined && payload.phase !== "started") {
+            bad(id, "spawnOutcome is only allowed in phase started");
+        }
+    }, (payload, event) => {
+        const id = IDS.attemptLifecycle;
+        if (PHASE_KIND[payload.phase] !== event.kind)
+            bad(id, "phase does not match event kind");
+        if (payload.agentId !== event.agentId)
+            bad(id, "agentId does not match the event agentId");
+        assertEventAttempt(id, event, payload.attemptId);
+        if (payload.attemptNumber !== undefined && payload.attemptNumber !== event.attemptNumber) {
+            bad(id, "attemptNumber does not match the event attemptNumber");
+        }
+        if (payload.retryOfAttemptId !== event.retryOfAttemptId) {
+            bad(id, "retryOfAttemptId must match the event retryOfAttemptId");
+        }
+        if (payload.phase === "finished" && event.outcome === undefined)
+            bad(id, "outcome is required on attempt finish");
+    });
+    const decision = define(IDS.flowDecision, flowDecisionSchema, (payload) => {
+        const id = IDS.flowDecision;
+        const kind = payload.decision;
+        if (payload.logicalTaskId === undefined)
+            bad(id, "logicalTaskId is required");
+        if (payload.childAgentId !== undefined && kind !== "delegate") {
+            bad(id, "childAgentId is only allowed on delegate");
+        }
+        const retryFields = payload.failedAttemptId !== undefined ||
+            payload.nextAttemptNumber !== undefined ||
+            payload.delayMs !== undefined;
+        if (retryFields && kind !== "retry")
+            bad(id, "failedAttemptId, nextAttemptNumber and delayMs are only allowed on retry");
+        const dependencies = payload.dependencies ?? [];
+        if (new Set(dependencies).size !== dependencies.length || dependencies.includes(payload.logicalTaskId)) {
+            bad(id, "dependencies must be unique logical tasks other than the task itself");
+        }
+        if (kind === "dependency-not-launched" || kind === "dependency-released") {
+            if (dependencies.length === 0)
+                bad(id, "dependency decision requires dependencies");
+            if (payload.causeEventId === undefined)
+                bad(id, "dependency decision requires causeEventId");
+        }
+        if (kind === "retry") {
+            if (payload.failedAttemptId === undefined)
+                bad(id, "retry requires failedAttemptId");
+            if (payload.nextAttemptNumber === undefined || payload.nextAttemptNumber < 2) {
+                bad(id, "retry requires nextAttemptNumber of at least 2");
+            }
+        }
+    }, (_payload, event) => {
+        if (event.producer.issuer !== "flow")
+            bad(IDS.flowDecision, "a flow decision requires producer issuer flow");
+    });
+    const continuation = define(IDS.continuationDecision, continuationDecisionSchema, (payload) => {
+        if (payload.decision === "continuation.consumed" &&
+            payload.channel === "queue-steering" &&
+            payload.requestId !== undefined)
+            bad(IDS.continuationDecision, "queue-steering cannot certify consumption");
+        if ((payload.decision === "continuation.rejected") !== (payload.reason !== undefined)) {
+            bad(IDS.continuationDecision, "reason is required when the decision is continuation.rejected, and only then");
+        }
+    }, (payload, event) => {
+        // Pending and consumed are facts the target itself observes; admission and rejection may come from the authority.
+        if (payload.decision !== "continuation.pending" && payload.decision !== "continuation.consumed")
+            return;
+        if (event.agentId !== payload.target.agentId || event.attemptId !== payload.target.attemptId) {
+            bad(IDS.continuationDecision, "pending or consumed continuation must be recorded on the addressed target agent and attempt");
+        }
+    });
+    const usage = define(IDS.usage, usageSchema, (payload) => assertMeasurement(IDS.usage, payload.measurement), (payload, event) => {
+        const id = IDS.usage;
+        const origin = payload.origin;
+        if (origin.owner === "attempt" && event.attemptId !== origin.attemptId) {
+            bad(id, "usage origin attemptId does not match the event attemptId");
+        }
+        if (origin.owner === "submission" && event.attemptId === undefined) {
+            bad(id, "usage origin needs the submission's attemptId on the event");
+        }
+    });
+    const health = define(IDS.captureHealth, captureHealthSchema, (payload) => {
+        const id = IDS.captureHealth;
+        if ((payload.status === "healthy") !== (payload.condition === "none")) {
+            bad(id, "condition none is required for, and only for, status healthy");
+        }
+        if (payload.sequenceRange !== undefined && payload.sequenceRange.from > payload.sequenceRange.to) {
+            bad(id, "sequenceRange.from must not exceed sequenceRange.to");
+        }
+        assertGaps(id, payload.coverageGaps ?? []);
+    }, undefined);
+    const control = define(IDS.controlCorrelation, controlCorrelationSchema, (payload) => {
+        const id = IDS.controlCorrelation;
+        if (payload.phase === "requested" && payload.state !== "requested" && payload.state !== "accepted") {
+            bad(id, "phase requested allows only states requested or accepted");
+        }
+        if (payload.phase === "observed" && payload.state === "requested") {
+            bad(id, "phase observed cannot be in state requested");
+        }
+        if ((payload.state === "rejected") !== (payload.reason !== undefined)) {
+            bad(id, "reason is required when state is rejected, and only then");
+        }
+        if (payload.terminationConfirmed !== undefined) {
+            if (payload.action !== "cancel")
+                bad(id, "terminationConfirmed is only valid for the cancel action");
+            if (payload.terminationConfirmed && payload.state !== "applied") {
+                bad(id, "terminationConfirmed true requires state applied");
+            }
+        }
+        const applied = payload.state === "applied";
+        if (payload.observed !== undefined && !(applied && payload.action !== "cancel")) {
+            bad(id, "observed is only valid for an applied retry or continue");
+        }
+        if (applied && payload.action === "retry") {
+            if (payload.observed?.startedAgentId === undefined || payload.observed?.startedAttemptId === undefined) {
+                bad(id, "an applied retry needs both observed.startedAgentId and observed.startedAttemptId");
+            }
+        }
+        if (applied && payload.action === "continue" && payload.observed?.consumingEventId === undefined) {
+            bad(id, "an applied continue needs observed.consumingEventId");
+        }
+    }, (payload, event) => {
+        const id = IDS.controlCorrelation;
+        if (event.kind === "cancellation.requested" || event.kind === "cancellation.outcome") {
+            if (payload.action !== "cancel")
+                bad(id, "cancellation event carries only the cancel action");
+            const phase = event.kind === "cancellation.requested" ? "requested" : "observed";
+            if (payload.phase !== phase)
+                bad(id, "phase does not match cancellation event kind");
+        }
+        // The graph links a claim to observed facts of the addressed attempt, so the claim must name it.
+        const claim = payload.terminationConfirmed === true || (payload.state === "applied" && payload.action !== "cancel");
+        if (claim && event.attemptId === undefined) {
+            bad(id, "a termination, retry or continue claim needs the addressed attemptId on the event");
+        }
+    });
+    const localCancellation = define(IDS.localCancellation, localCancellationSchema, (payload) => {
+        const id = IDS.localCancellation;
+        if (payload.phase === "requested") {
+            if (payload.state !== "requested" ||
+                payload.reason !== undefined ||
+                payload.diagnosticCode !== undefined ||
+                payload.terminationConfirmed !== undefined ||
+                payload.exitCode !== undefined) {
+                bad(id, "phase requested requires state requested and forbids reason, diagnosticCode, terminationConfirmed and exitCode");
+            }
+            return;
+        }
+        if (payload.state === "requested")
+            bad(id, "phase observed cannot be in state requested");
+        if (payload.terminationConfirmed === undefined)
+            bad(id, "phase observed requires terminationConfirmed");
+        if (payload.terminationConfirmed && payload.state !== "applied")
+            bad(id, "terminationConfirmed true requires state applied");
+        if ((payload.state === "rejected") !== (payload.reason !== undefined)) {
+            bad(id, "reason is required when state is rejected, and only then");
+        }
+    }, (payload, event) => {
+        const phase = event.kind === "cancellation.requested" ? "requested" : "observed";
+        if (payload.phase !== phase)
+            bad(IDS.localCancellation, "phase does not match cancellation event kind");
+        if (payload.terminationConfirmed === true && event.attemptId === undefined) {
+            bad(IDS.localCancellation, "a termination claim needs the addressed attemptId on the event");
+        }
+    });
+    const amendment = define(IDS.amendment, amendmentSchema, (payload) => {
+        const id = IDS.amendment;
+        const replacement = payload.replacement;
+        if (payload.relation === "supersedes") {
+            if (replacement !== undefined)
+                bad(id, "supersedes cannot carry a replacement outcome");
+            if (payload.coverage === undefined)
+                bad(id, "an amendment needs coverage or a replacement outcome");
+        }
+        else {
+            if (replacement === undefined)
+                bad(id, "resolves-unknown requires a replacement outcome");
+            if (replacement.outcome === "unknown")
+                bad(id, "resolves-unknown requires a known replacement outcome");
+        }
+        if (replacement?.failureCode !== undefined && replacement.outcome !== "failed") {
+            bad(id, "failureCode is only allowed when the replacement outcome is failed");
+        }
+        assertGaps(id, payload.coverage ?? []);
+    }, (payload, event) => {
+        if (payload.amendsEventId === event.eventId)
+            bad(IDS.amendment, "an amendment cannot amend itself");
+    });
+    return new Map([
+        [IDS.modelSubmission, submission],
+        [IDS.modelResponse, response],
+        [IDS.toolCall, toolCall],
+        [IDS.toolResult, toolResult],
+        [IDS.fileEvidence, file],
+        [IDS.agentSpawn, spawn],
+        [IDS.agentRelation, relation],
+        [IDS.attemptLifecycle, lifecycle],
+        [IDS.flowDecision, decision],
+        [IDS.continuationDecision, continuation],
+        [IDS.usage, usage],
+        [IDS.captureHealth, health],
+        [IDS.controlCorrelation, control],
+        [IDS.localCancellation, localCancellation],
+        [IDS.amendment, amendment],
+    ]);
+}
+let parsers;
+/**
+ * Enforces the payload contract on one event. Legacy kinds without `payload.schema` pass; everything
+ * else must name a registered (kind, schema id) pair and satisfy that schema and its envelope rules.
+ * Called by `parseDhEvent` on the trusted clone.
+ */
+export function assertDhEventPayload(event) {
+    const id = event.payload.schema;
+    if (id === undefined) {
+        if (DH_LEGACY_FREEFORM_PAYLOAD_KINDS.includes(event.kind))
+            return;
+        throw new DhContractError("schema_invalid", "Invalid dh.event/1: event kind requires a payload schema");
+    }
+    if (typeof id !== "string")
+        throw new DhContractError("schema_invalid", "Invalid dh.event/1: payload.schema must be a string");
+    const registration = REGISTRATIONS.find((entry) => entry.id === id);
+    if (registration === undefined)
+        throw new DhContractError("schema_invalid", "Invalid dh.event/1: unknown payload schema");
+    if (!registration.kinds.includes(event.kind)) {
+        throw new DhContractError("schema_invalid", "Invalid dh.event/1: payload schema is not registered for kind");
+    }
+    parsers ??= buildParsers();
+    parsers.get(id)?.check(event);
+}
+// ---------------------------------------------------------------------------
+// Cross-event payload graph
+// ---------------------------------------------------------------------------
+function str(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function obj(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+}
+const typed = (event, id) => event.payload.schema === id;
+/** Generation, agent and attempt: what a control request addresses. */
+const targetKey = (event) => JSON.stringify([event.generationId, event.agentId, event.attemptId ?? null]);
+/** A cancellation.outcome that observed the target terminate for a control cancel request. */
+const confirmsTermination = (event) => event.kind === "cancellation.outcome" &&
+    typed(event, IDS.controlCorrelation) &&
+    event.payload.action === "cancel" &&
+    event.payload.phase === "observed" &&
+    event.payload.state === "applied" &&
+    event.payload.terminationConfirmed === true;
+/** The only consumption event type: the addressed target recorded that it consumed the continuation. */
+const consumesContinuation = (event) => event.kind === "orchestration.decision" &&
+    typed(event, IDS.continuationDecision) &&
+    event.payload.decision === "continuation.consumed";
+/** Every artifact reference a typed payload carries, with the payload field that names it. */
+function* artifactRefs(event) {
+    const { payload } = event;
+    for (const field of [
+        "requestArtifact",
+        "responseArtifact",
+        "argumentsArtifact",
+        "outputArtifact",
+        "pathRef",
+    ]) {
+        const ref = obj(payload[field]);
+        if (ref !== undefined)
+            yield [field, ref];
+    }
+    for (const field of ["nonTextArtifacts", "evidence"]) {
+        const list = payload[field];
+        if (!Array.isArray(list))
+            continue;
+        for (const item of list) {
+            const ref = obj(item);
+            if (ref !== undefined)
+                yield [field, ref];
+        }
+    }
+}
+/**
+ * A reference carries the sha256 (and optionally size) the producer claims for the artifact; the artifact
+ * metadata is the stored fact. A mismatch means the reference does not describe that artifact. Artifacts
+ * missing from the metadata are reported by the bundle's own link check, not here.
+ */
+function validateArtifactRefs(events, artifacts, err) {
+    const byId = new Map();
+    for (const artifact of artifacts)
+        if (!byId.has(artifact.artifactId))
+            byId.set(artifact.artifactId, artifact);
+    for (const event of events) {
+        if (typeof event.payload.schema !== "string")
+            continue;
+        for (const [field, ref] of artifactRefs(event)) {
+            const id = str(ref.artifactId) ?? "";
+            const artifact = byId.get(id);
+            if (artifact === undefined)
+                continue;
+            if (ref.sha256 !== artifact.sha256)
+                err(event, `${field} sha256 does not match artifact metadata`);
+            if (typeof ref.sizeBytes === "number" && ref.sizeBytes !== artifact.sizeBytes) {
+                err(event, `${field} sizeBytes does not match artifact metadata`);
+            }
+        }
+    }
+}
+/**
+ * Cross-event rules over already-parsed events. Legacy freeform events are ignored. Returns one message per
+ * violation (never throws); `validateDhTraceBundle` appends these to its own errors. Nothing here rewrites or
+ * reinterprets an original event: amendments are separate events that point at their target.
+ *
+ * One pass builds the indexes (events by id, attempts by agent, attempt starts, relations, confirmed
+ * terminations); every rule after it is a Map/Set lookup, so the cost is linear in the number of events
+ * (no per-event scan of `events`, no per-event array copy).
+ */
+export function validateDhPayloadGraph(events, artifacts, ownership) {
+    const errors = [];
+    const err = (_event, message) => errors.push(message);
+    if (artifacts !== undefined)
+        validateArtifactRefs(events, artifacts, err);
+    const byId = new Map();
+    const attemptsByAgent = new Map();
+    const attemptStarts = new Map();
+    const effectiveTerminals = resolveDhEffectiveTerminals(events, ownership);
+    const failedAttempts = new Set([...effectiveTerminals]
+        .filter(([, terminal]) => terminal.outcome === "failed" && !terminal.conflict && !terminal.authorityUnresolved)
+        .map(([id]) => id));
+    const confirmedFinishes = new Set();
+    const relationsByAgent = new Map();
+    const confirmedCancels = new Map();
+    for (const event of events) {
+        if (!byId.has(event.eventId))
+            byId.set(event.eventId, event);
+        let attempts = attemptsByAgent.get(event.agentId);
+        if (attempts === undefined) {
+            attempts = new Set();
+            attemptsByAgent.set(event.agentId, attempts);
+        }
+        if (event.attemptId !== undefined) {
+            attempts.add(event.attemptId);
+            if (event.kind === "attempt.started" && !attemptStarts.has(event.attemptId)) {
+                attemptStarts.set(event.attemptId, event);
+            }
+            if (event.kind === "attempt.finished") {
+                if (typed(event, IDS.attemptLifecycle) && event.payload.terminationConfirmed === true) {
+                    confirmedFinishes.add(targetKey(event));
+                }
+            }
+        }
+        if (typed(event, IDS.agentRelation) && !relationsByAgent.has(event.agentId)) {
+            relationsByAgent.set(event.agentId, event);
+        }
+        if (confirmsTermination(event)) {
+            const request = str(event.payload.requestId) ?? "";
+            const targets = confirmedCancels.get(request) ?? new Set();
+            targets.add(targetKey(event));
+            confirmedCancels.set(request, targets);
+        }
+    }
+    const submissions = new Map();
+    const requests = new Map();
+    const responses = new Map();
+    for (const event of events) {
+        if (typed(event, IDS.modelSubmission)) {
+            const submissionId = str(event.payload.submissionId) ?? "";
+            if (submissions.has(submissionId))
+                err(event, "duplicate submissionId");
+            else
+                submissions.set(submissionId, event);
+            const requestKey = str(event.payload.requestId) ?? "";
+            const attemptId = str(event.payload.attemptId);
+            const entry = requests.get(requestKey) ?? { attemptId, indexes: new Set() };
+            if (entry.attemptId !== attemptId)
+                err(event, "requestId spans attempts");
+            const index = Number(event.payload.transportRetryIndex);
+            if (entry.indexes.has(index))
+                err(event, "duplicate transportRetryIndex for requestId");
+            entry.indexes.add(index);
+            requests.set(requestKey, entry);
+        }
+        else if (typed(event, IDS.modelResponse)) {
+            const submissionId = str(event.payload.submissionId) ?? "";
+            const list = responses.get(submissionId);
+            if (list === undefined)
+                responses.set(submissionId, [event]);
+            else
+                list.push(event);
+        }
+    }
+    for (const [submissionId, list] of responses) {
+        const submission = submissions.get(submissionId);
+        for (const event of list) {
+            if (submission === undefined) {
+                err(event, "model response has no matching model submission");
+                continue;
+            }
+            if (submission.payload.attemptId !== event.payload.attemptId) {
+                err(event, "response attempt differs from the submission attempt");
+            }
+            if (submission.agentId !== event.agentId) {
+                err(event, "response agent differs from the submission agent");
+            }
+        }
+        for (let index = 1; index < list.length; index++) {
+            const event = list[index];
+            if (event !== undefined)
+                err(event, "more than one model response for submission");
+        }
+    }
+    // Each usage measurement has exactly one owner; aggregates are inclusive and never counted.
+    const owned = new Map();
+    const submissionUsageAttempts = new Set();
+    const attemptUsage = [];
+    const own = (event, key) => {
+        if (owned.has(key))
+            err(event, "usage is owned by more than one event (double count)");
+        else
+            owned.set(key, event);
+    };
+    for (const event of events) {
+        let origin;
+        if (typed(event, IDS.modelResponse))
+            origin = obj(obj(event.payload.usage)?.origin);
+        else if (typed(event, IDS.usage))
+            origin = obj(event.payload.origin);
+        if (origin === undefined)
+            continue;
+        if (origin.owner === "submission") {
+            const submissionId = str(origin.submissionId) ?? "";
+            own(event, `submission:${submissionId}`);
+            if (typed(event, IDS.usage)) {
+                // A response's submission link is checked above; a usage event names its submission on its own.
+                const submission = submissions.get(submissionId);
+                if (submission === undefined) {
+                    err(event, "usage.reported references no model submission");
+                }
+                else {
+                    if (submission.attemptId !== event.attemptId) {
+                        err(event, "usage submission belongs to a different attempt");
+                    }
+                    if (submission.agentId !== event.agentId) {
+                        err(event, "usage submission belongs to a different agent");
+                    }
+                }
+            }
+            const attemptId = str(event.payload.attemptId) ?? event.attemptId;
+            if (attemptId !== undefined)
+                submissionUsageAttempts.add(attemptId);
+        }
+        else if (origin.owner === "attempt") {
+            const attemptId = str(origin.attemptId) ?? "";
+            own(event, `attempt:${attemptId}`);
+            attemptUsage.push({ event, attemptId });
+        }
+    }
+    for (const { event, attemptId } of attemptUsage) {
+        if (submissionUsageAttempts.has(attemptId)) {
+            err(event, "usage for attempt duplicates submission-owned usage in the same attempt (double count)");
+        }
+    }
+    // Tool calls: a nested call names a real enclosing tool.call.
+    for (const event of events) {
+        if (!typed(event, IDS.toolCall))
+            continue;
+        const parentId = str(event.payload.parentEventId);
+        if (parentId === undefined)
+            continue;
+        const parent = byId.get(parentId);
+        if (parent?.kind !== "tool.call") {
+            err(event, "parentEventId is not a tool.call in this bundle");
+            continue;
+        }
+        if (parent.generationId !== event.generationId) {
+            err(event, "parent tool.call belongs to a different generation");
+        }
+        const parentCallId = str(event.payload.parentCallId);
+        const expected = str(parent.payload.callId);
+        if (parentCallId !== expected) {
+            err(event, "parentCallId differs from the parent tool.call callId");
+        }
+    }
+    // Original and final tool results.
+    const originals = new Map();
+    const finalsFor = new Set();
+    for (const event of events) {
+        if (!typed(event, IDS.toolResult) || event.payload.stage !== "original")
+            continue;
+        const key = JSON.stringify([event.agentId, event.attemptId ?? null, event.payload.callId]);
+        if (originals.has(key))
+            err(event, "duplicate original tool.result for call");
+        else
+            originals.set(key, event);
+    }
+    for (const event of events) {
+        if (!typed(event, IDS.toolResult) || event.payload.stage !== "final")
+            continue;
+        const targetId = str(event.payload.originalResultEventId) ?? "";
+        const target = byId.get(targetId);
+        if (target === undefined || target.kind !== "tool.result") {
+            err(event, "originalResultEventId references no original tool.result");
+            continue;
+        }
+        if (!typed(target, IDS.toolResult) || target.payload.stage !== "original") {
+            err(event, "originalResultEventId is not an original tool.result");
+            continue;
+        }
+        if (target.payload.callId !== event.payload.callId) {
+            err(event, "final result callId differs from the original call");
+        }
+        else if (target.agentId !== event.agentId || target.attemptId !== event.attemptId) {
+            err(event, "final result agent or attempt differs from the original");
+        }
+        if (finalsFor.has(targetId))
+            err(event, "duplicate final tool.result for original");
+        finalsFor.add(targetId);
+    }
+    // Flow decisions.
+    const notLaunched = new Set();
+    const released = new Set();
+    for (const event of events) {
+        if (!typed(event, IDS.flowDecision))
+            continue;
+        const provenance = obj(event.payload.provenance);
+        const cause = str(event.payload.causeEventId);
+        if (cause !== undefined && !byId.has(cause))
+            err(event, "causeEventId references no event");
+        if (provenance?.source === "tool-call") {
+            const target = byId.get(str(provenance.toolCallEventId) ?? "");
+            if (target?.kind !== "tool.call")
+                err(event, "provenance toolCallEventId is not a tool.call in this bundle");
+            else if (target.generationId !== event.generationId) {
+                err(event, "provenance toolCallEventId is in a different generation");
+            }
+        }
+        else if (provenance?.source === "command") {
+            const commandEvent = str(provenance.commandEventId);
+            if (commandEvent !== undefined && !byId.has(commandEvent)) {
+                err(event, "provenance commandEventId references no event");
+            }
+        }
+        const task = str(event.payload.logicalTaskId) ?? "";
+        if (event.payload.decision === "dependency-not-launched")
+            notLaunched.add(task);
+        if (event.payload.decision === "dependency-released")
+            released.add(task);
+        if (event.payload.decision === "retry") {
+            const failed = str(event.payload.failedAttemptId) ?? "";
+            if (!failedAttempts.has(failed))
+                err(event, "retry failedAttemptId has no failed attempt.finished");
+        }
+    }
+    for (const event of events) {
+        if (!typed(event, IDS.agentSpawn))
+            continue;
+        const task = str(event.payload.logicalTaskId);
+        if (task !== undefined && notLaunched.has(task) && !released.has(task)) {
+            err(event, "task was decided not launched and has no dependency-released decision");
+        }
+        // A Flow launch from a tool call names a real tool.call of the same generation made by the parent agent.
+        const callId = event.payload.via === "flow" ? str(event.payload.launchedByToolCallEventId) : undefined;
+        if (callId === undefined)
+            continue;
+        const call = byId.get(callId);
+        if (call?.kind !== "tool.call") {
+            err(event, "launchedByToolCallEventId is not a tool.call in this bundle");
+            continue;
+        }
+        if (call.generationId !== event.generationId) {
+            err(event, "launching tool.call belongs to a different generation");
+        }
+        if (event.parentAgentId === undefined)
+            err(event, "a flow launch from a tool call needs parentAgentId");
+        else if (call.agentId !== event.parentAgentId) {
+            err(event, "launching tool.call belongs to an agent other than the parent agent");
+        }
+        if (call.streamId === event.streamId && call.sequence >= event.sequence) {
+            err(event, "flow launch precedes its launching tool.call in the producer stream");
+        }
+    }
+    // Full graph eligibility; a partial ingest may retain unresolved relations, never invent a failure.
+    const nativeClaims = new Map();
+    const latestByAgent = new Map();
+    for (const start of attemptStarts.values()) {
+        const latest = latestByAgent.get(start.agentId);
+        if (!latest || (start.attemptNumber ?? 0) > (latest.attemptNumber ?? 0))
+            latestByAgent.set(start.agentId, start);
+    }
+    for (const event of events) {
+        if (!typed(event, IDS.agentRelation))
+            continue;
+        const source = str(event.payload.sourceAgentId) ?? "";
+        const attempt = str(event.payload.sourceAttemptId) ?? "";
+        const known = attemptsByAgent.get(source);
+        if (known === undefined)
+            err(event, "sourceAgentId has no events in this bundle");
+        else if (!known.has(attempt))
+            err(event, "sourceAttemptId is not an attempt of sourceAgentId");
+        const start = attemptStarts.get(attempt);
+        const terminal = effectiveTerminals.get(attempt);
+        if (!start ||
+            !terminal ||
+            terminal.outcome !== "failed" ||
+            terminal.conflict ||
+            terminal.authorityUnresolved ||
+            terminal.event.agentId !== source ||
+            latestByAgent.get(source)?.attemptId !== attempt)
+            err(event, "not_eligible: native source must be the latest finished failed attempt");
+        if (event.producer.issuer !== "code" || event.agentId === source || event.retryOfAttemptId !== undefined)
+            err(event, "schema_invalid: invalid native relation authority or identity");
+        if (start &&
+            (start.generationId !== event.generationId ||
+                start.tenantScope.environmentId !== event.tenantScope.environmentId ||
+                start.tenantScope.projectId !== event.tenantScope.projectId))
+            err(event, "not_eligible: native source has a foreign generation or scope");
+        if (terminal &&
+            (terminal.event.generationId !== event.generationId ||
+                terminal.event.tenantScope.environmentId !== event.tenantScope.environmentId ||
+                terminal.event.tenantScope.projectId !== event.tenantScope.projectId))
+            err(event, "not_eligible: native terminal has a foreign generation or scope");
+        const targets = [...(attemptsByAgent.get(event.agentId) ?? [])].map((id) => attemptStarts.get(id));
+        const first = targets.filter((start) => start?.attemptNumber === 1);
+        const target = first.length === 1 ? first[0] : undefined;
+        if (!target ||
+            targets.some((start) => start?.attemptNumber === undefined) ||
+            target.retryOfAttemptId !== undefined ||
+            target.generationId !== event.generationId ||
+            target.tenantScope.environmentId !== event.tenantScope.environmentId ||
+            target.tenantScope.projectId !== event.tenantScope.projectId)
+            err(event, "not_eligible: native target must start one fresh attempt at number 1");
+        if (relationsByAgent.get(event.agentId) !== event || nativeClaims.has(attempt))
+            err(event, "not_eligible: native source or target already claimed");
+        nativeClaims.set(attempt, event.agentId);
+    }
+    // Amendments point at originals of the same producer and stream and never overwrite a known outcome.
+    const resolved = new Set();
+    for (const event of events) {
+        if (!typed(event, IDS.amendment))
+            continue;
+        const targetId = str(event.payload.amendsEventId) ?? "";
+        const target = byId.get(targetId);
+        if (target === undefined) {
+            err(event, "amendsEventId references no event");
+            continue;
+        }
+        if (target.kind === "event.amendment")
+            err(event, "cannot amend an amendment");
+        else if (target.kind !== event.payload.amendsKind) {
+            err(event, "amendsKind differs from the amended event kind");
+        }
+        if (target.agentId !== event.agentId)
+            err(event, "amendment and amended event belong to different agents");
+        if (target.generationId !== event.generationId) {
+            err(event, "amendment and amended event belong to different generations");
+        }
+        // Producer identity is the issuer bound at authentication; version and mode are claims and are not compared.
+        if (target.producer.issuer !== event.producer.issuer) {
+            err(event, "amendment issuer differs from the amended event issuer");
+        }
+        if (target.streamId !== event.streamId) {
+            err(event, "amendment stream differs from the amended event stream");
+        }
+        else if (target.sequence >= event.sequence) {
+            err(event, "amendment precedes the amended event in the producer stream");
+        }
+        if (event.payload.relation === "resolves-unknown") {
+            if (target.outcome !== "unknown") {
+                err(event, "resolves-unknown targets an event whose outcome is not unknown");
+            }
+            else if (resolved.has(targetId))
+                err(event, "outcome is already resolved by another amendment");
+            resolved.add(targetId);
+        }
+    }
+    // Continuation decisions address a known target attempt; a request is consumed at most once.
+    const consumedRequests = new Set();
+    for (const event of events) {
+        if (!typed(event, IDS.continuationDecision))
+            continue;
+        const target = obj(event.payload.target);
+        const agent = str(target?.agentId) ?? "";
+        const attempt = str(target?.attemptId) ?? "";
+        const known = attemptsByAgent.get(agent);
+        if (known === undefined)
+            err(event, "continuation target agent has no events in this bundle");
+        else if (!known.has(attempt))
+            err(event, "continuation target attempt is not an attempt of target agent");
+        const request = str(event.payload.requestId);
+        if (consumesContinuation(event) && request !== undefined) {
+            if (consumedRequests.has(request))
+                err(event, "duplicate continuation.consumed for request");
+            consumedRequests.add(request);
+        }
+    }
+    // One local origin per target AND scope: selected and whole-run are distinct requests.
+    // Index the earliest sequence per stream so duplicate-origin diagnostics never make array order chronology.
+    const localKey = (event) => JSON.stringify([targetKey(event), event.payload.scope]);
+    const localRequests = new Map();
+    for (const event of events) {
+        if (!typed(event, IDS.localCancellation) || event.kind !== "cancellation.requested")
+            continue;
+        const key = localKey(event);
+        let streams = localRequests.get(key);
+        if (streams !== undefined)
+            err(event, "duplicate local cancellation.requested for target and scope");
+        else {
+            streams = new Map();
+            localRequests.set(key, streams);
+        }
+        streams.set(event.streamId, Math.min(streams.get(event.streamId) ?? event.sequence, event.sequence));
+    }
+    for (const event of events) {
+        if (!typed(event, IDS.localCancellation) || event.kind !== "cancellation.outcome")
+            continue;
+        const streams = localRequests.get(localKey(event));
+        if (streams === undefined) {
+            err(event, "no matching local cancellation.requested for target and scope");
+        }
+        else {
+            const sequence = streams.get(event.streamId);
+            // Different streams have no shared sequence clock. Do not infer order from timestamps.
+            if (sequence !== undefined && sequence >= event.sequence) {
+                err(event, "observation precedes its local cancellation.requested in the producer stream");
+            }
+        }
+    }
+    // Control correlation: a claim of termination, consumption or a started retry needs observed linkage.
+    for (const event of events) {
+        if (!typed(event, IDS.controlCorrelation) || event.payload.state !== "applied")
+            continue;
+        const request = str(event.payload.requestId) ?? "";
+        const observed = obj(event.payload.observed);
+        if (event.payload.action === "cancel") {
+            // A cancellation.outcome is itself the observation; any other event must point at one.
+            if (event.payload.terminationConfirmed !== true || event.kind === "cancellation.outcome")
+                continue;
+            const outcome = confirmedCancels.get(request)?.has(targetKey(event)) ?? false;
+            if (!outcome && !confirmedFinishes.has(targetKey(event))) {
+                err(event, "terminationConfirmed is claimed without a matching observed cancellation.outcome or confirmed attempt.finished for request");
+            }
+        }
+        else if (event.payload.action === "continue") {
+            const proofError = dhAppliedControlEvidenceError({
+                generationId: event.generationId,
+                agentId: event.agentId,
+                attemptId: event.attemptId,
+                requestId: request,
+            }, "continue", { consumingEventId: str(observed?.consumingEventId) }, { attemptStarts, relationsByAgent, byId });
+            if (proofError)
+                err(event, proofError);
+            const consumingId = str(observed?.consumingEventId) ?? "";
+            const consumer = byId.get(consumingId);
+            if (consumer === undefined) {
+                err(event, "consumingEventId references no event");
+            }
+            else if (!consumesContinuation(consumer)) {
+                err(event, "consumingEventId is not a continuation.consumed decision");
+            }
+            else {
+                if (consumer.generationId !== event.generationId ||
+                    consumer.agentId !== event.agentId ||
+                    consumer.attemptId !== event.attemptId) {
+                    err(event, "consuming event belongs to a different generation, agent or attempt than the addressed target");
+                }
+                const answered = str(consumer.payload.requestId);
+                if (answered !== request) {
+                    err(event, "consuming event answers a different request");
+                }
+            }
+        }
+        else if (event.payload.action === "retry") {
+            const proofError = dhAppliedControlEvidenceError(event, "retry", { startedAgentId: str(observed?.startedAgentId), startedAttemptId: str(observed?.startedAttemptId) }, { attemptStarts, relationsByAgent, byId });
+            if (proofError)
+                err(event, proofError);
+            const startedAgent = str(observed?.startedAgentId);
+            const startedAttempt = str(observed?.startedAttemptId);
+            if (startedAgent !== undefined && startedAgent !== event.agentId) {
+                // Native Code retry: a new agent linked to the addressed agent and attempt by a cross-agent relation.
+                const relation = relationsByAgent.get(startedAgent);
+                if (relation === undefined) {
+                    err(event, "startedAgentId has no agent.spawned relation in this bundle");
+                }
+                else if (relation.payload.sourceAgentId !== event.agentId ||
+                    relation.payload.sourceAttemptId !== event.attemptId) {
+                    err(event, "started agent is related to a different agent or attempt than the addressed target");
+                }
+                if (startedAttempt !== undefined && attemptStarts.get(startedAttempt)?.agentId !== startedAgent) {
+                    err(event, "startedAttemptId has no attempt.started for startedAgentId");
+                }
+            }
+            else if (startedAttempt === undefined) {
+                err(event, "a same-agent retry needs observed.startedAttemptId");
+            }
+            else {
+                // Same agent, new attempt: the start event retries the addressed attempt.
+                const start = attemptStarts.get(startedAttempt);
+                if (start === undefined) {
+                    err(event, "startedAttemptId has no attempt.started in this bundle");
+                }
+                else {
+                    if (start.agentId !== event.agentId) {
+                        err(event, "started attempt belongs to a different agent");
+                    }
+                    if (start.retryOfAttemptId !== event.attemptId) {
+                        err(event, "started attempt does not retry the addressed attempt");
+                    }
+                }
+            }
+        }
+    }
+    return errors;
+}
+/** Shared status/graph linkage check. Supplied records are evidence, never an allocation alone. */
+function dhAppliedControlEvidenceError(target, action, observed, index) {
+    if (action === "continue") {
+        const consumer = observed.consumingEventId ? index.byId.get(observed.consumingEventId) : undefined;
+        if (!consumer ||
+            !consumesContinuation(consumer) ||
+            consumer.payload.channel === "queue-steering" ||
+            consumer.generationId !== target.generationId ||
+            consumer.agentId !== target.agentId ||
+            consumer.attemptId !== target.attemptId ||
+            consumer.payload.requestId !== target.requestId)
+            return "not_eligible: no matching target consumption";
+        return;
+    }
+    const start = observed.startedAttemptId ? index.attemptStarts.get(observed.startedAttemptId) : undefined;
+    const source = target.attemptId ? index.attemptStarts.get(target.attemptId) : undefined;
+    if (!observed.startedAgentId || !start || start.agentId !== observed.startedAgentId)
+        return "not_eligible: no matching observed start pair";
+    if (!source ||
+        source.agentId !== target.agentId ||
+        source.generationId !== target.generationId ||
+        start.generationId !== target.generationId ||
+        source.tenantScope.environmentId !== start.tenantScope.environmentId ||
+        source.tenantScope.projectId !== start.tenantScope.projectId)
+        return "not_eligible: observed start has wrong generation or scope";
+    if (start.agentId === target.agentId) {
+        if (start.retryOfAttemptId !== target.attemptId ||
+            source.attemptNumber === undefined ||
+            start.attemptNumber !== source.attemptNumber + 1)
+            return "not_eligible: observed start has wrong retry linkage or number";
+    }
+    else {
+        const relation = index.relationsByAgent.get(start.agentId);
+        if (start.attemptNumber !== 1 ||
+            start.retryOfAttemptId !== undefined ||
+            !relation ||
+            relation.producer.issuer !== "code" ||
+            relation.generationId !== target.generationId ||
+            relation.payload.sourceAgentId !== target.agentId ||
+            relation.payload.sourceAttemptId !== target.attemptId ||
+            relation.tenantScope.environmentId !== source.tenantScope.environmentId ||
+            relation.tenantScope.projectId !== source.tenantScope.projectId)
+            return "not_eligible: no admitted native relation for observed start";
+    }
+}
+export function assertDhAppliedControlEvidence(target, action, observed, events) {
+    const attemptStarts = new Map(), relationsByAgent = new Map(), byId = new Map();
+    for (const event of events) {
+        byId.set(event.eventId, event);
+        if (event.kind === "attempt.started" && event.attemptId)
+            attemptStarts.set(event.attemptId, event);
+        if (typed(event, IDS.agentRelation))
+            relationsByAgent.set(event.agentId, event);
+    }
+    if (dhAppliedControlEvidenceError(target, action, observed, { attemptStarts, relationsByAgent, byId }))
+        throw new DhContractError("not_eligible");
+}
+//# sourceMappingURL=trace-payload.js.map