@humain/humain-code-contracts 0.3.2

package/dist/trace-payload.d.ts

@@ -0,0 +1,425 @@
+import { type Static, Type } from "typebox";
+import { type DhArtifactV1, type DhEventKind, type DhEventV1, type DhTerminalOwnership } from "./trace.ts";
+export declare const DH_PAYLOAD_SCHEMA_IDS: Readonly<{
+    readonly agentRelation: "dh.payload.agent-relation/1";
+    readonly agentSpawn: "dh.payload.agent-spawn/1";
+    readonly amendment: "dh.payload.amendment/1";
+    readonly attemptLifecycle: "dh.payload.attempt-lifecycle/1";
+    readonly captureHealth: "dh.payload.capture-health/1";
+    readonly continuationDecision: "dh.payload.continuation-decision/1";
+    readonly controlCorrelation: "dh.payload.control-correlation/1";
+    readonly fileEvidence: "dh.payload.file-evidence/1";
+    readonly flowDecision: "dh.payload.flow-decision/1";
+    readonly localCancellation: "dh.payload.local-cancellation/1";
+    readonly modelResponse: "dh.payload.model-response/1";
+    readonly modelSubmission: "dh.payload.model-submission/1";
+    readonly toolCall: "dh.payload.tool-call/1";
+    readonly toolResult: "dh.payload.tool-result/1";
+    readonly usage: "dh.payload.usage/1";
+}>;
+export type DhPayloadSchemaId = (typeof DH_PAYLOAD_SCHEMA_IDS)[keyof typeof DH_PAYLOAD_SCHEMA_IDS];
+/** Kinds that existed before typed payloads. They may keep a freeform payload without `schema`. */
+export declare const DH_LEGACY_FREEFORM_PAYLOAD_KINDS: readonly DhEventKind[];
+/** Kinds introduced with typed payloads; `payload.schema` is mandatory. */
+export declare const DH_PAYLOAD_REQUIRED_KINDS: readonly DhEventKind[];
+/**
+ * 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 declare const DH_CONTINUATION_DECISIONS: readonly ["continuation.pending", "continuation.admitted", "continuation.rejected", "continuation.consumed"];
+export type DhContinuationDecision = (typeof DH_CONTINUATION_DECISIONS)[number];
+/** Delivery channel of a continuation. `queue-steering` is never a live continuation of a running child. */
+export declare const DH_CONTINUATION_CHANNELS: readonly ["live-child", "native-descendant", "run-root", "queue-steering", "internal"];
+export type DhContinuationChannel = (typeof DH_CONTINUATION_CHANNELS)[number];
+/** Named observations from the existing local process-cancellation seam; never arbitrary diagnostic text. */
+export declare const DH_LOCAL_CANCELLATION_DIAGNOSTICS: readonly ["cancelled_before_spawn", "logical_cancellation_observed", "process_closed_after_signal"];
+export type DhLocalCancellationDiagnostic = (typeof DH_LOCAL_CANCELLATION_DIAGNOSTICS)[number];
+/** Payload schema ids accepted on a kind (empty for kinds that only carry legacy freeform payloads). */
+export declare function dhPayloadSchemaIdsForKind(kind: DhEventKind): readonly DhPayloadSchemaId[];
+declare function modelSubmissionSchema(): Type.TObject<{
+    readonly schema: Type.TLiteral<"dh.payload.model-submission/1">;
+    readonly requestId: Type.TString;
+    readonly submissionId: Type.TString;
+    readonly attemptId: Type.TString;
+    readonly transportRetryIndex: Type.TInteger;
+    readonly provider: Type.TString;
+    readonly api: Type.TString;
+    readonly model: Type.TString;
+    readonly operation: Type.TEnum<["chat", "image", "classifier", "auxiliary"]>;
+    readonly purpose: Type.TOptional<Type.TEnum<["chat", "compaction", "branch-summary", "cache-warming"]>>;
+    readonly transport: Type.TEnum<["http", "websocket"]>;
+    readonly representation: Type.TEnum<["json-body", "json-frame"]>;
+    readonly adapterVersion: Type.TOptional<Type.TString>;
+    readonly requestArtifact: Type.TOptional<Type.TObject<{
+        readonly artifactId: Type.TString;
+        readonly sha256: Type.TString;
+        readonly sizeBytes: Type.TOptional<Type.TInteger>;
+    }>>;
+}>;
+export type DhModelSubmissionPayload = Static<ReturnType<typeof modelSubmissionSchema>>;
+declare function modelResponseSchema(): Type.TObject<{
+    readonly schema: Type.TLiteral<"dh.payload.model-response/1">;
+    readonly submissionId: Type.TString;
+    readonly attemptId: Type.TString;
+    readonly stopReason: Type.TEnum<["pending", "stop", "length", "toolUse", "error", "aborted", "deferred"]>;
+    readonly provider: Type.TOptional<Type.TString>;
+    readonly api: Type.TOptional<Type.TString>;
+    readonly model: Type.TOptional<Type.TString>;
+    readonly responseModel: Type.TOptional<Type.TString>;
+    readonly toolCallCount: Type.TOptional<Type.TInteger>;
+    readonly text: Type.TOptional<Type.TString>;
+    readonly reasoning: Type.TOptional<Type.TString>;
+    readonly errorMessage: Type.TOptional<Type.TString>;
+    readonly responseArtifact: Type.TOptional<Type.TObject<{
+        readonly artifactId: Type.TString;
+        readonly sha256: Type.TString;
+        readonly sizeBytes: Type.TOptional<Type.TInteger>;
+    }>>;
+    readonly usage: Type.TOptional<Type.TObject<{
+        readonly origin: Type.TUnion<[Type.TObject<{
+            readonly owner: Type.TLiteral<"submission">;
+            readonly submissionId: Type.TString;
+        }>, Type.TObject<{
+            readonly owner: Type.TLiteral<"attempt">;
+            readonly attemptId: Type.TString;
+        }>, Type.TObject<{
+            readonly owner: Type.TLiteral<"flow-aggregate">;
+            readonly inclusive: Type.TLiteral<true>;
+        }>]>;
+        readonly measurement: Type.TUnion<[Type.TObject<{
+            readonly state: Type.TLiteral<"unknown">;
+        }>, Type.TObject<{
+            readonly state: Type.TLiteral<"reported">;
+            readonly input: Type.TOptional<Type.TInteger>;
+            readonly output: Type.TOptional<Type.TInteger>;
+            readonly cacheRead: Type.TOptional<Type.TInteger>;
+            readonly cacheWrite: Type.TOptional<Type.TInteger>;
+            readonly reasoning: Type.TOptional<Type.TInteger>;
+            readonly totalTokens: Type.TOptional<Type.TInteger>;
+            readonly durationMs: Type.TOptional<Type.TInteger>;
+            readonly cost: Type.TUnion<[Type.TObject<{
+                readonly state: Type.TLiteral<"unknown">;
+            }>, Type.TObject<{
+                readonly state: Type.TLiteral<"known">;
+                readonly amount: Type.TNumber;
+                readonly currency: Type.TString;
+                readonly priceProvenance: Type.TString;
+            }>]>;
+        }>]>;
+    }>>;
+}>;
+export type DhModelResponsePayload = Static<ReturnType<typeof modelResponseSchema>>;
+/**
+ * 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`.
+ */
+declare function toolCallSchema(): Type.TObject<{
+    readonly schema: Type.TLiteral<"dh.payload.tool-call/1">;
+    readonly callId: Type.TString;
+    readonly toolName: Type.TString;
+    readonly argumentsPreview: Type.TOptional<Type.TString>;
+    readonly argumentsArtifact: Type.TOptional<Type.TObject<{
+        readonly artifactId: Type.TString;
+        readonly sha256: Type.TString;
+        readonly sizeBytes: Type.TOptional<Type.TInteger>;
+    }>>;
+    /** Provenance of a nested call: the enclosing call's id and (when recorded) its tool.call event. */
+    readonly parentCallId: Type.TOptional<Type.TString>;
+    readonly parentEventId: Type.TOptional<Type.TString>;
+}>;
+export type DhToolCallPayload = Static<ReturnType<typeof toolCallSchema>>;
+declare function toolResultSchema(): Type.TObject<{
+    readonly schema: Type.TLiteral<"dh.payload.tool-result/1">;
+    readonly callId: Type.TString;
+    readonly toolName: Type.TString;
+    readonly stage: Type.TEnum<["original", "final"]>;
+    readonly source: Type.TEnum<["executed", "blocked", "synthetic"]>;
+    readonly isError: Type.TBoolean;
+    readonly modified: Type.TOptional<Type.TBoolean>;
+    readonly originalResultEventId: Type.TOptional<Type.TString>;
+    readonly parentCallId: Type.TOptional<Type.TString>;
+    readonly output: Type.TOptional<Type.TString>;
+    readonly outputArtifact: Type.TOptional<Type.TObject<{
+        readonly artifactId: Type.TString;
+        readonly sha256: Type.TString;
+        readonly sizeBytes: Type.TOptional<Type.TInteger>;
+    }>>;
+    readonly nonTextBlockCount: Type.TInteger;
+    readonly nonTextArtifacts: Type.TOptional<Type.TArray<Type.TObject<{
+        readonly artifactId: Type.TString;
+        readonly sha256: Type.TString;
+        readonly sizeBytes: Type.TOptional<Type.TInteger>;
+    }>>>;
+    readonly childAgentId: Type.TOptional<Type.TString>;
+    readonly childAgentIds: Type.TOptional<Type.TArray<Type.TString>>;
+}>;
+export type DhToolResultPayload = Static<ReturnType<typeof toolResultSchema>>;
+declare function fileEvidenceSchema(): Type.TObject<{
+    readonly schema: Type.TLiteral<"dh.payload.file-evidence/1">;
+    readonly callId: Type.TString;
+    readonly toolName: Type.TString;
+    readonly operation: Type.TEnum<["write", "edit", "delete"]>;
+    readonly outcome: Type.TEnum<["succeeded", "failed", "cancelled"]>;
+    readonly intent: Type.TObject<{
+        readonly contentSha256: Type.TOptional<Type.TString>;
+        readonly contentBytes: Type.TOptional<Type.TInteger>;
+        readonly patchSha256: Type.TOptional<Type.TString>;
+    }>;
+    readonly observed: Type.TObject<{
+        readonly before: Type.TUnion<[Type.TObject<{
+            readonly state: Type.TLiteral<"observed">;
+            readonly sha256: Type.TString;
+            readonly sizeBytes: Type.TInteger;
+        }>, Type.TObject<{
+            readonly state: Type.TLiteral<"unavailable">;
+            readonly reason: Type.TEnum<["missing", "denied", "oversized", "binary", "unsupported", "read-failed"]>;
+        }>]>;
+        readonly after: Type.TUnion<[Type.TObject<{
+            readonly state: Type.TLiteral<"observed">;
+            readonly sha256: Type.TString;
+            readonly sizeBytes: Type.TInteger;
+        }>, Type.TObject<{
+            readonly state: Type.TLiteral<"unavailable">;
+            readonly reason: Type.TEnum<["missing", "denied", "oversized", "binary", "unsupported", "read-failed"]>;
+        }>]>;
+        readonly effectObserved: Type.TBoolean;
+    }>;
+    readonly pathRef: Type.TObject<{
+        readonly artifactId: Type.TString;
+        readonly sha256: Type.TString;
+        readonly sizeBytes: Type.TOptional<Type.TInteger>;
+    }>;
+    readonly evidence: Type.TOptional<Type.TArray<Type.TObject<{
+        readonly artifactId: Type.TString;
+        readonly sha256: Type.TString;
+        readonly sizeBytes: Type.TOptional<Type.TInteger>;
+        readonly role: Type.TEnum<["diff", "snapshot"]>;
+    }>>>;
+    readonly worktree: Type.TOptional<Type.TObject<{
+        readonly mode: Type.TEnum<["shared", "isolated", "degraded-to-shared"]>;
+        readonly baseRevision: Type.TOptional<Type.TString>;
+        readonly endRevision: Type.TOptional<Type.TString>;
+        readonly baseObserved: Type.TBoolean;
+    }>>;
+}>;
+export type DhFileEvidencePayload = Static<ReturnType<typeof fileEvidenceSchema>>;
+declare function agentSpawnSchema(): Type.TObject<{
+    readonly schema: Type.TLiteral<"dh.payload.agent-spawn/1">;
+    readonly via: Type.TEnum<["subagent", "flow"]>;
+    readonly spawnedByEventId: Type.TOptional<Type.TString>;
+    readonly launchedByToolCallEventId: Type.TOptional<Type.TString>;
+    readonly command: Type.TOptional<Type.TObject<{
+        readonly name: Type.TString;
+        readonly decisionEventId: Type.TOptional<Type.TString>;
+    }>>;
+    readonly logicalTaskId: Type.TOptional<Type.TString>;
+    readonly nativeLaunchId: Type.TOptional<Type.TString>;
+}>;
+export type DhAgentSpawnPayload = Static<ReturnType<typeof agentSpawnSchema>>;
+/** Cross-agent relation (native Code retry): a NEW agent linked to its source, never a same-agent retryOfAttemptId. */
+declare function agentRelationSchema(): Type.TObject<{
+    readonly schema: Type.TLiteral<"dh.payload.agent-relation/1">;
+    readonly via: Type.TLiteral<"native-code">;
+    readonly relation: Type.TLiteral<"native-retry">;
+    readonly sourceAgentId: Type.TString;
+    readonly sourceAttemptId: Type.TString;
+    readonly reasonCode: Type.TOptional<Type.TString>;
+}>;
+export type DhAgentRelationPayload = Static<ReturnType<typeof agentRelationSchema>>;
+declare function attemptLifecycleSchema(): Type.TObject<{
+    readonly schema: Type.TLiteral<"dh.payload.attempt-lifecycle/1">;
+    readonly phase: Type.TEnum<["started", "finished", "retry-scheduled"]>;
+    readonly agentId: Type.TString;
+    readonly attemptId: Type.TString;
+    readonly attemptNumber: Type.TOptional<Type.TInteger>;
+    readonly retryOfAttemptId: Type.TOptional<Type.TString>;
+    readonly retryReason: Type.TOptional<Type.TString>;
+    readonly nextAttemptNumber: Type.TOptional<Type.TInteger>;
+    readonly delayMs: Type.TOptional<Type.TInteger>;
+    readonly spawnOutcome: Type.TOptional<Type.TEnum<["spawned", "failed-to-spawn", "unknown"]>>;
+    readonly terminationConfirmed: Type.TOptional<Type.TBoolean>;
+}>;
+export type DhAttemptLifecyclePayload = Static<ReturnType<typeof attemptLifecycleSchema>>;
+declare function flowDecisionSchema(): Type.TObject<{
+    readonly schema: Type.TLiteral<"dh.payload.flow-decision/1">;
+    readonly decision: Type.TEnum<["schedule", "delegate", "dependency-not-launched", "dependency-released", "retry"]>;
+    readonly issuer: Type.TLiteral<"flow">;
+    readonly via: Type.TLiteral<"flow">;
+    readonly mode: Type.TEnum<["single", "parallel", "chain", "hierarchy"]>;
+    /** A command launch has no tool call: the two variants share no event-id field. */
+    readonly provenance: Type.TUnion<[Type.TObject<{
+        readonly source: Type.TLiteral<"tool-call">;
+        readonly toolCallEventId: Type.TString;
+    }>, Type.TObject<{
+        readonly source: Type.TLiteral<"command">;
+        readonly command: Type.TString;
+        readonly commandEventId: Type.TOptional<Type.TString>;
+    }>, Type.TObject<{
+        readonly source: Type.TLiteral<"internal">;
+    }>]>;
+    readonly logicalTaskId: Type.TOptional<Type.TString>;
+    readonly dependencies: Type.TOptional<Type.TArray<Type.TString>>;
+    readonly causeEventId: Type.TOptional<Type.TString>;
+    readonly childAgentId: Type.TOptional<Type.TString>;
+    readonly failedAttemptId: Type.TOptional<Type.TString>;
+    readonly nextAttemptNumber: Type.TOptional<Type.TInteger>;
+    readonly delayMs: Type.TOptional<Type.TInteger>;
+    readonly wave: Type.TOptional<Type.TInteger>;
+    readonly order: Type.TOptional<Type.TInteger>;
+    readonly policyVersion: Type.TOptional<Type.TString>;
+    readonly reasonCode: Type.TOptional<Type.TString>;
+}>;
+export type DhFlowDecisionPayload = Static<ReturnType<typeof flowDecisionSchema>>;
+/**
+ * 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.
+ */
+declare function continuationDecisionSchema(): Type.TObject<{
+    readonly schema: Type.TLiteral<"dh.payload.continuation-decision/1">;
+    readonly decision: Type.TEnum<["continuation.pending", "continuation.admitted", "continuation.rejected", "continuation.consumed"]>;
+    readonly target: Type.TObject<{
+        readonly agentId: Type.TString;
+        readonly attemptId: Type.TString;
+    }>;
+    readonly requestId: Type.TOptional<Type.TString>;
+    readonly channel: Type.TEnum<["live-child", "native-descendant", "run-root", "queue-steering", "internal"]>;
+    readonly reason: Type.TOptional<Type.TEnum<["not_authorized", "scope_mismatch", "stale_epoch", "target_settled", "not_eligible", "policy_denied", "budget_exhausted", "workspace_unavailable"]>>;
+}>;
+export type DhContinuationDecisionPayload = Static<ReturnType<typeof continuationDecisionSchema>>;
+declare function usageSchema(): Type.TObject<{
+    readonly schema: Type.TLiteral<"dh.payload.usage/1">;
+    readonly usageId: Type.TString;
+    readonly origin: Type.TUnion<[Type.TObject<{
+        readonly owner: Type.TLiteral<"submission">;
+        readonly submissionId: Type.TString;
+    }>, Type.TObject<{
+        readonly owner: Type.TLiteral<"attempt">;
+        readonly attemptId: Type.TString;
+    }>, Type.TObject<{
+        readonly owner: Type.TLiteral<"flow-aggregate">;
+        readonly inclusive: Type.TLiteral<true>;
+    }>]>;
+    readonly measurement: Type.TUnion<[Type.TObject<{
+        readonly state: Type.TLiteral<"unknown">;
+    }>, Type.TObject<{
+        readonly state: Type.TLiteral<"reported">;
+        readonly input: Type.TOptional<Type.TInteger>;
+        readonly output: Type.TOptional<Type.TInteger>;
+        readonly cacheRead: Type.TOptional<Type.TInteger>;
+        readonly cacheWrite: Type.TOptional<Type.TInteger>;
+        readonly reasoning: Type.TOptional<Type.TInteger>;
+        readonly totalTokens: Type.TOptional<Type.TInteger>;
+        readonly durationMs: Type.TOptional<Type.TInteger>;
+        readonly cost: Type.TUnion<[Type.TObject<{
+            readonly state: Type.TLiteral<"unknown">;
+        }>, Type.TObject<{
+            readonly state: Type.TLiteral<"known">;
+            readonly amount: Type.TNumber;
+            readonly currency: Type.TString;
+            readonly priceProvenance: Type.TString;
+        }>]>;
+    }>]>;
+}>;
+export type DhUsagePayload = Static<ReturnType<typeof usageSchema>>;
+declare function captureHealthSchema(): Type.TObject<{
+    readonly schema: Type.TLiteral<"dh.payload.capture-health/1">;
+    readonly status: Type.TEnum<["healthy", "degraded", "failed", "recovered"]>;
+    readonly condition: Type.TEnum<["none", "dropped", "write_failed", "redaction_failed", "unsupported_adapter", "flush_timeout", "lost_observer", "recovery"]>;
+    readonly droppedEvents: Type.TOptional<Type.TInteger>;
+    readonly droppedArtifacts: Type.TOptional<Type.TInteger>;
+    readonly adapter: Type.TOptional<Type.TObject<{
+        readonly name: Type.TString;
+        readonly version: Type.TString;
+    }>>;
+    readonly affectedKinds: Type.TOptional<Type.TArray<Type.TEnum<["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", "capture.health", "control.correlation", "event.amendment"]>>>;
+    readonly coverageGaps: Type.TOptional<Type.TArray<Type.TObject<{
+        readonly path: Type.TString;
+        readonly state: Type.TEnum<["captured", "redacted", "truncated", "unavailable", "not-applicable", "inferred"]>;
+        readonly reason: Type.TOptional<Type.TEnum<["secret_redacted", "policy_redacted", "size_limit", "producer_lost", "worker_exited_before_flush", "legacy_producer", "not_captured_by_version", "provider_hidden", "not_applicable", "derived_from_summary"]>>;
+    }>>>;
+    readonly sequenceRange: Type.TOptional<Type.TObject<{
+        readonly from: Type.TInteger;
+        readonly to: Type.TInteger;
+    }>>;
+}>;
+export type DhCaptureHealthPayload = Static<ReturnType<typeof captureHealthSchema>>;
+declare function controlCorrelationSchema(): Type.TObject<{
+    readonly schema: Type.TLiteral<"dh.payload.control-correlation/1">;
+    readonly requestId: Type.TString;
+    readonly action: Type.TEnum<["cancel", "retry", "continue"]>;
+    readonly phase: Type.TEnum<["requested", "observed"]>;
+    readonly state: Type.TEnum<["requested", "accepted", "delivered", "applied", "rejected", "unsupported", "unknown"]>;
+    readonly reason: Type.TOptional<Type.TEnum<["not_authorized", "scope_mismatch", "stale_epoch", "target_settled", "not_eligible", "policy_denied", "budget_exhausted", "workspace_unavailable"]>>;
+    readonly terminationConfirmed: Type.TOptional<Type.TBoolean>;
+    readonly observed: Type.TOptional<Type.TObject<{
+        readonly startedAgentId: Type.TOptional<Type.TString>;
+        readonly startedAttemptId: Type.TOptional<Type.TString>;
+        readonly consumingEventId: Type.TOptional<Type.TString>;
+    }>>;
+}>;
+export type DhControlCorrelationPayload = Static<ReturnType<typeof controlCorrelationSchema>>;
+/** Local cancellation is not a Code control request: there is deliberately no requestId. */
+declare function localCancellationSchema(): Type.TObject<{
+    readonly schema: Type.TLiteral<"dh.payload.local-cancellation/1">;
+    readonly requester: Type.TLiteral<"local">;
+    readonly scope: Type.TEnum<["selected", "whole-run"]>;
+    readonly phase: Type.TEnum<["requested", "observed"]>;
+    readonly state: Type.TEnum<["requested", "applied", "rejected", "unsupported", "unknown"]>;
+    readonly reason: Type.TOptional<Type.TEnum<["not_authorized", "scope_mismatch", "stale_epoch", "target_settled", "not_eligible", "policy_denied", "budget_exhausted", "workspace_unavailable"]>>;
+    readonly diagnosticCode: Type.TOptional<Type.TEnum<["cancelled_before_spawn", "logical_cancellation_observed", "process_closed_after_signal"]>>;
+    readonly terminationConfirmed: Type.TOptional<Type.TBoolean>;
+    readonly exitCode: Type.TOptional<Type.TInteger>;
+}>;
+export type DhLocalCancellationPayload = Static<ReturnType<typeof localCancellationSchema>>;
+declare function amendmentSchema(): Type.TObject<{
+    readonly schema: Type.TLiteral<"dh.payload.amendment/1">;
+    readonly amendsEventId: Type.TString;
+    readonly amendsKind: Type.TEnum<["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", "capture.health", "control.correlation", "event.amendment"]>;
+    readonly relation: Type.TEnum<["supersedes", "resolves-unknown"]>;
+    readonly reasonCode: Type.TString;
+    readonly coverage: Type.TOptional<Type.TArray<Type.TObject<{
+        readonly path: Type.TString;
+        readonly state: Type.TEnum<["captured", "redacted", "truncated", "unavailable", "not-applicable", "inferred"]>;
+        readonly reason: Type.TOptional<Type.TEnum<["secret_redacted", "policy_redacted", "size_limit", "producer_lost", "worker_exited_before_flush", "legacy_producer", "not_captured_by_version", "provider_hidden", "not_applicable", "derived_from_summary"]>>;
+    }>>>;
+    readonly replacement: Type.TOptional<Type.TObject<{
+        readonly outcome: Type.TEnum<["succeeded", "failed", "cancelled", "unknown"]>;
+        readonly failureCode: Type.TOptional<Type.TString>;
+    }>>;
+}>;
+export type DhAmendmentPayload = Static<ReturnType<typeof amendmentSchema>>;
+/**
+ * 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 declare function assertDhEventPayload(event: DhEventV1): void;
+/**
+ * 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 declare function validateDhPayloadGraph(events: readonly DhEventV1[], artifacts?: readonly DhArtifactV1[], ownership?: DhTerminalOwnership): string[];
+interface DhControlEvidenceTarget {
+    readonly generationId: string;
+    readonly agentId: string;
+    readonly attemptId?: string;
+    readonly requestId?: string;
+}
+interface DhControlObserved {
+    readonly startedAgentId?: string;
+    readonly startedAttemptId?: string;
+    readonly consumingEventId?: string;
+}
+export declare function assertDhAppliedControlEvidence(target: DhControlEvidenceTarget, action: "retry" | "continue", observed: DhControlObserved, events: readonly DhEventV1[]): void;
+export {};
+//# sourceMappingURL=trace-payload.d.ts.map

package/dist/trace-payload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-payload.d.ts","sourceRoot":"","sources":["../src/trace-payload.ts"],"names":[],"mappings":"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"}