@humain/humain-code-contracts 0.3.2

package/dist/trace.js

@@ -0,0 +1,1014 @@
+import { Type } from "typebox";
+import { Compile } from "typebox/compile";
+import { assertDhPlainData, DhContractError, dhCanonicalText, parseDhRawJson } from "./trace-canonical.js";
+import { assertDhEventPayload, validateDhPayloadGraph } from "./trace-payload.js";
+export * from "./trace-api.js";
+export * from "./trace-artifact.js";
+export * from "./trace-canonical.js";
+export * from "./trace-export.js";
+export * from "./trace-http.js";
+export * from "./trace-payload.js";
+/**
+ * HUMAIN Code agent-activity trace wire contract (v1), shared by Code, CLI and Flow producers.
+ *
+ * Three independent axes are never conflated: execution outcome (`outcome`), capture coverage
+ * (`DhCoverage`) and transfer state (`DhAck`). Producers redact before upload; the server
+ * re-checks `tenantScope`, which is producer-declared only and never trusted on its own.
+ */
+const StrictObject = (properties) => Type.Object(properties, { additionalProperties: false });
+const PositiveInteger = Type.Integer({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER });
+const NonnegativeInteger = Type.Integer({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER });
+const Digest = Type.String({ pattern: "^[a-f0-9]{64}$" });
+const SafeArtifactReference = Type.String({
+    minLength: 1,
+    maxLength: 512,
+    pattern: "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))[A-Za-z0-9._-]+(?:/[A-Za-z0-9._-]+)*$",
+});
+const BoundedString = (maxLength) => Type.String({ minLength: 1, maxLength });
+const ShortString = BoundedString(256);
+const DetailString = Type.String({ minLength: 1, maxLength: 1024 });
+const IsoUtcTimestamp = Type.String({
+    minLength: 20,
+    maxLength: 30,
+    pattern: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,9})?Z$",
+});
+export const DH_TRACE_CONTRACT_VERSION = 1;
+export const DH_EVENT_SCHEMA_ID = "dh.event/1";
+export const DH_ARTIFACT_SCHEMA_ID = "dh.artifact/1";
+export const DH_ACK_SCHEMA_ID = "dh.ack/1";
+export const DH_EVENT_MAX_UTF8_BYTES = 65536;
+export const DH_ARTIFACT_MAX_BYTES = 64 * 1024 * 1024;
+export const DH_MAX_EXTERNAL_IDS = 16;
+export const DH_MAX_PAYLOAD_PROPERTIES = 128;
+export const DH_MAX_FIELD_COVERAGE_ENTRIES = 64;
+export const DH_MAX_ARTIFACT_REFS = 32;
+export const DH_MAX_REMOVED_FIELD_PATHS = 256;
+export const DH_MAX_ACK_IDS = 1000;
+/** Maximum container nesting of `payload` (the payload object itself is depth 1). */
+export const DH_PAYLOAD_MAX_DEPTH = 16;
+/** Maximum number of JSON values (containers and scalars, root included) in one `payload`. */
+export const DH_PAYLOAD_MAX_NODES = 4096;
+/** Maximum length of any object key inside `payload`, at any depth. */
+export const DH_PAYLOAD_MAX_KEY_LENGTH = 128;
+/** Maximum length of a `fields` key (field path). */
+export const DH_FIELD_PATH_MAX_LENGTH = 256;
+// ---------------------------------------------------------------------------
+// External ids and canonical trace ids
+// ---------------------------------------------------------------------------
+export const DH_ISSUERS = ["code", "cli", "flow"];
+export const DhIssuerSchema = Type.Enum(DH_ISSUERS);
+/** Producer-native id mapped onto the canonical trace id space (e.g. code.run, cli.session, flow.launch). */
+export const DhExternalIdSchema = StrictObject({
+    issuer: DhIssuerSchema,
+    namespace: Type.String({ pattern: "^[a-z][a-z0-9_.-]{0,63}$", maxLength: 64 }),
+    value: ShortString,
+    mappingVersion: PositiveInteger,
+});
+const prefixedId = (prefix) => Type.String({
+    pattern: `^${prefix}_[A-Za-z0-9_-]{8,128}$`,
+    minLength: prefix.length + 9,
+    maxLength: prefix.length + 129,
+});
+export const DhGenerationIdSchema = prefixedId("gen");
+export const DhAgentIdSchema = prefixedId("agt");
+export const DhAttemptIdSchema = prefixedId("att");
+export const DhEventIdSchema = prefixedId("evt");
+export const DhArtifactIdSchema = prefixedId("art");
+// ---------------------------------------------------------------------------
+// Coverage
+// ---------------------------------------------------------------------------
+export const DH_COVERAGE_STATES = [
+    "captured",
+    "redacted",
+    "truncated",
+    "unavailable",
+    "not-applicable",
+    "inferred",
+];
+export const DH_COVERAGE_REASONS = [
+    "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",
+];
+/**
+ * Per-field or per-artifact capture coverage. A `reason` is REQUIRED for every state except
+ * `captured` (enforced by the parse functions, not by the schema alone).
+ *
+ * `inferred` means the value was derived (e.g. from a summary) rather than recorded. Consumers
+ * MUST NOT present an `inferred` value as a recorded fact.
+ */
+export const DhCoverageSchema = StrictObject({
+    state: Type.Enum(DH_COVERAGE_STATES),
+    reason: Type.Optional(Type.Enum(DH_COVERAGE_REASONS)),
+    detail: Type.Optional(DetailString),
+});
+// ---------------------------------------------------------------------------
+// Shared sub-schemas
+// ---------------------------------------------------------------------------
+export const DhRedactionSchema = StrictObject({
+    policyId: ShortString,
+    policyVersion: ShortString,
+    removedFieldPaths: Type.Array(BoundedString(512), { maxItems: DH_MAX_REMOVED_FIELD_PATHS }),
+});
+/** Producer-declared scope. The server re-checks it against the authenticated producer binding. */
+export const DH_SCOPE_ID_PATTERN = "^[A-Za-z0-9][A-Za-z0-9_.-]{0,255}$";
+export const DhScopeIdSchema = Type.String({ minLength: 1, maxLength: 256, pattern: DH_SCOPE_ID_PATTERN });
+export const DhStreamIdSchema = Type.String({ minLength: 1, maxLength: 128, pattern: "^[A-Za-z0-9_-]{1,128}$" });
+export const DhTenantScopeSchema = StrictObject({
+    environmentId: DhScopeIdSchema,
+    projectId: DhScopeIdSchema,
+});
+export const DH_EVENT_KINDS = [
+    "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",
+    // Added with typed payloads (dh.payload.*/1): no legacy freeform shape, `payload.schema` is required.
+    // Amended into dh.event/1 before any deployment (C0 freeze doc, section 1.15). The exact list is pinned by
+    // test/trace-payload-conformance.test.ts and the freeze digest: a further kind is a deliberate, reviewed change.
+    "capture.health",
+    "control.correlation",
+    "event.amendment",
+];
+export const DH_OUTCOMES = ["succeeded", "failed", "cancelled", "unknown"];
+export const DhFailureSchema = StrictObject({
+    code: Type.String({ pattern: "^[a-z][a-z0-9_.-]{0,63}$", maxLength: 64 }),
+    message: Type.Optional(DetailString),
+});
+// ---------------------------------------------------------------------------
+// Event
+// ---------------------------------------------------------------------------
+export const DhEventV1Schema = StrictObject({
+    schema: Type.Literal(DH_EVENT_SCHEMA_ID),
+    eventId: DhEventIdSchema,
+    generationId: DhGenerationIdSchema,
+    agentId: DhAgentIdSchema,
+    attemptId: Type.Optional(DhAttemptIdSchema),
+    parentAgentId: Type.Optional(DhAgentIdSchema),
+    producer: StrictObject({
+        issuer: DhIssuerSchema,
+        version: ShortString,
+        mode: ShortString,
+    }),
+    externalIds: Type.Array(DhExternalIdSchema, { maxItems: DH_MAX_EXTERNAL_IDS }),
+    /** Monotonic per producer stream. */
+    sequence: NonnegativeInteger,
+    streamId: DhStreamIdSchema,
+    occurredAt: IsoUtcTimestamp,
+    recordedAt: IsoUtcTimestamp,
+    kind: Type.Enum(DH_EVENT_KINDS),
+    outcome: Type.Optional(Type.Enum(DH_OUTCOMES)),
+    failure: Type.Optional(DhFailureSchema),
+    retryOfAttemptId: Type.Optional(DhAttemptIdSchema),
+    attemptNumber: Type.Optional(PositiveInteger),
+    /**
+     * JSON-safe values only. TypeBox cannot express the depth, node, key-length or forbidden-key
+     * limits (and drops `maxLength` on Record key schemas), so `parseDhEvent` enforces them with
+     * `assertJsonPayload` before cloning.
+     */
+    payload: Type.Record(Type.String(), Type.Unknown(), {
+        maxProperties: DH_MAX_PAYLOAD_PROPERTIES,
+    }),
+    /**
+     * Field path (e.g. `payload.messages`) -> coverage for that field. Key length and pattern are
+     * enforced by `parseDhEvent` (`assertFieldPaths`), not by the schema.
+     */
+    fields: Type.Record(Type.String(), DhCoverageSchema, {
+        maxProperties: DH_MAX_FIELD_COVERAGE_ENTRIES,
+    }),
+    artifacts: Type.Optional(Type.Array(DhArtifactIdSchema, { maxItems: DH_MAX_ARTIFACT_REFS })),
+    redaction: DhRedactionSchema,
+    tenantScope: DhTenantScopeSchema,
+});
+// ---------------------------------------------------------------------------
+// Artifact
+// ---------------------------------------------------------------------------
+export const DH_ARTIFACT_KINDS = [
+    "file-diff",
+    "file-snapshot",
+    "tool-output",
+    "model-context",
+    "log",
+    "bundle",
+];
+export const DH_ARTIFACT_MEDIA_TYPES = [
+    "text/plain",
+    "text/x-diff",
+    "application/json",
+    "application/octet-stream",
+];
+export const DhArtifactV1Schema = StrictObject({
+    schema: Type.Literal(DH_ARTIFACT_SCHEMA_ID),
+    artifactId: DhArtifactIdSchema,
+    generationId: DhGenerationIdSchema,
+    agentId: DhAgentIdSchema,
+    attemptId: Type.Optional(DhAttemptIdSchema),
+    eventId: DhEventIdSchema,
+    kind: Type.Enum(DH_ARTIFACT_KINDS),
+    mediaType: Type.Enum(DH_ARTIFACT_MEDIA_TYPES),
+    sizeBytes: Type.Integer({ minimum: 0, maximum: DH_ARTIFACT_MAX_BYTES }),
+    sha256: Digest,
+    logicalPath: Type.Optional(SafeArtifactReference),
+    coverage: DhCoverageSchema,
+    redaction: DhRedactionSchema,
+    tenantScope: DhTenantScopeSchema,
+});
+// ---------------------------------------------------------------------------
+// Ack
+// ---------------------------------------------------------------------------
+export const DH_REJECTION_CODES = [
+    "duplicate_conflict",
+    "schema_invalid",
+    "scope_denied",
+    "tombstoned",
+    "too_large",
+    "rate_limited",
+];
+/**
+ * Server acknowledgement for a producer stream. Delivering an identical record again is accepted
+ * idempotently (it appears in `accepted`); delivering the same id with different content is
+ * rejected as `duplicate_conflict` and never overwrites the stored record.
+ */
+export const DhAckV1Schema = StrictObject({
+    schema: Type.Literal(DH_ACK_SCHEMA_ID),
+    streamId: DhStreamIdSchema,
+    ackedThroughSequence: NonnegativeInteger,
+    accepted: StrictObject({
+        eventIds: Type.Array(DhEventIdSchema, { maxItems: DH_MAX_ACK_IDS }),
+        artifactIds: Type.Array(DhArtifactIdSchema, { maxItems: DH_MAX_ACK_IDS }),
+    }),
+    rejected: Type.Array(StrictObject({
+        id: Type.String({ pattern: "^(?:evt|art)_[A-Za-z0-9_-]{8,128}$", maxLength: 136 }),
+        code: Type.Enum(DH_REJECTION_CODES),
+        retryable: Type.Boolean(),
+    }), { maxItems: DH_MAX_ACK_IDS }),
+    receivedAt: IsoUtcTimestamp,
+});
+// ---------------------------------------------------------------------------
+// Parsing
+// ---------------------------------------------------------------------------
+const EventValidator = Compile(DhEventV1Schema);
+const ArtifactValidator = Compile(DhArtifactV1Schema);
+const AckValidator = Compile(DhAckV1Schema);
+const textEncoder = new TextEncoder();
+function schemaError(label, errors) {
+    const field = errors[0]?.instancePath.split("/")[1];
+    const properties = label === "dh.event/1"
+        ? DhEventV1Schema.properties
+        : label === "dh.artifact/1"
+            ? DhArtifactV1Schema.properties
+            : DhAckV1Schema.properties;
+    const where = field !== undefined && Object.hasOwn(properties, field) ? ` at /${field}` : "";
+    return new DhContractError("schema_invalid", `Invalid ${label}${where}`);
+}
+function assertCoverage(label, coverage) {
+    if (coverage.state !== "captured" && coverage.reason === undefined) {
+        throw new DhContractError("schema_invalid", `Invalid ${label}: coverage has state but no reason`);
+    }
+}
+const FORBIDDEN_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+const FIELD_PATH_PATTERN = /^[A-Za-z][A-Za-z0-9_-]*(?:\.[A-Za-z0-9_-]+)*$/;
+const TIMESTAMP_PARTS = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,9}))?Z$/;
+/**
+ * Returns the UTC instant (epoch milliseconds, sub-millisecond digits ignored) of a calendar-valid
+ * timestamp, or undefined. `Date.parse` rolls impossible dates over (2025-02-30 becomes 03-02), so
+ * the parsed instant must round-trip to the same calendar fields.
+ */
+function parseInstant(timestamp) {
+    const parts = TIMESTAMP_PARTS.exec(timestamp);
+    if (parts === null)
+        return undefined;
+    const [, year, month, day, hour, minute, second, fraction] = parts;
+    const base = `${year}-${month}-${day}T${hour}:${minute}:${second}`;
+    const whole = Date.parse(`${base}.000Z`);
+    if (Number.isNaN(whole))
+        return undefined;
+    if (new Date(whole).toISOString().slice(0, 19) !== base)
+        return undefined;
+    return whole + (fraction === undefined ? 0 : Number(fraction.slice(0, 3).padEnd(3, "0")));
+}
+function assertTimestamp(label, path, timestamp) {
+    if (parseInstant(timestamp) === undefined) {
+        throw new DhContractError("schema_invalid", `Invalid ${label}: ${path} is not a calendar-valid UTC instant`);
+    }
+}
+function assertFieldPaths(fields) {
+    for (const path of Object.keys(fields)) {
+        if (path.length > DH_FIELD_PATH_MAX_LENGTH) {
+            throw new DhContractError("schema_invalid", `Invalid dh.event/1: fields key exceeds ${DH_FIELD_PATH_MAX_LENGTH} characters`);
+        }
+        if (!FIELD_PATH_PATTERN.test(path) || path.split(".").some((segment) => FORBIDDEN_KEYS.has(segment))) {
+            throw new DhContractError("schema_invalid", "Invalid dh.event/1: fields key is not a valid field path");
+        }
+    }
+}
+function fail(_path, reason) {
+    throw new DhContractError(reason.startsWith("exceeds") ? "too_large" : "schema_invalid", `Invalid dh.event/1: payload ${reason}`);
+}
+/**
+ * Iterative (non-recursive) walk that admits only JSON-safe values: null, boolean, finite number,
+ * string, array and plain object. Enforces depth, total node count and key limits, and rejects the
+ * keys `__proto__`, `constructor` and `prototype` at any depth, plus accessor properties on both
+ * objects and arrays. Counting happens when a value is queued, so the work stack never exceeds
+ * `DH_PAYLOAD_MAX_NODES` entries. Keys come from `Object.keys`, which includes own `__proto__`
+ * properties created by `JSON.parse`, so the same walk is safe to run on a parsed result.
+ */
+function assertJsonPayload(payload) {
+    const stack = [{ value: payload, depth: 1, path: "payload" }];
+    let nodes = 1;
+    while (stack.length > 0) {
+        const item = stack.pop();
+        if (item === undefined)
+            break;
+        const { value, depth, path } = item;
+        if (value === null || typeof value === "boolean" || typeof value === "string")
+            continue;
+        if (typeof value === "number") {
+            if (!Number.isFinite(value))
+                fail(path, "is not a finite number");
+            continue;
+        }
+        if (typeof value !== "object")
+            fail(path, `has non-JSON type ${typeof value}`);
+        if (depth > DH_PAYLOAD_MAX_DEPTH)
+            fail(path, `exceeds maximum nesting depth ${DH_PAYLOAD_MAX_DEPTH}`);
+        const container = value;
+        const children = [];
+        if (Array.isArray(container)) {
+            if (nodes + container.length > DH_PAYLOAD_MAX_NODES) {
+                fail(path, `exceeds maximum of ${DH_PAYLOAD_MAX_NODES} payload nodes`);
+            }
+            for (let index = 0; index < container.length; index++) {
+                const descriptor = Object.getOwnPropertyDescriptor(container, String(index));
+                if (descriptor === undefined)
+                    fail(path, "is a sparse array");
+                if (!("value" in descriptor))
+                    fail(`${path}[${index}]`, "is an accessor property");
+                children.push([`${path}[${index}]`, descriptor.value]);
+            }
+        }
+        else {
+            const proto = Object.getPrototypeOf(container);
+            if (proto !== Object.prototype && proto !== null)
+                fail(path, "is not a plain object");
+            const keys = Object.keys(container);
+            if (keys.length > DH_MAX_PAYLOAD_PROPERTIES)
+                fail(path, `exceeds maximum of ${DH_MAX_PAYLOAD_PROPERTIES} payload properties`);
+            if (nodes + keys.length > DH_PAYLOAD_MAX_NODES) {
+                fail(path, `exceeds maximum of ${DH_PAYLOAD_MAX_NODES} payload nodes`);
+            }
+            for (const key of keys) {
+                if (key.length > DH_PAYLOAD_MAX_KEY_LENGTH) {
+                    fail(path, `has a key longer than ${DH_PAYLOAD_MAX_KEY_LENGTH} characters`);
+                }
+                if (FORBIDDEN_KEYS.has(key))
+                    fail(path, `has forbidden key "${key}"`);
+                const descriptor = Object.getOwnPropertyDescriptor(container, key);
+                if (descriptor === undefined || !("value" in descriptor))
+                    fail(`${path}.${key}`, "is an accessor property");
+                children.push([`${path}.${key}`, descriptor?.value]);
+            }
+        }
+        nodes += children.length;
+        for (const [childPath, child] of children)
+            stack.push({ value: child, depth: depth + 1, path: childPath });
+    }
+}
+/**
+ * Attempt-linked fields need an `attemptId`: attempt lifecycle kinds, retry links and attempt
+ * numbers are meaningless (and would skip attempt validation) without one. Returns the violated
+ * rule, or undefined.
+ */
+function attemptIdViolation(event) {
+    if (event.attemptId !== undefined)
+        return undefined;
+    if (event.kind === "attempt.started" ||
+        event.kind === "attempt.finished" ||
+        event.kind === "attempt.retry_scheduled") {
+        return "attemptId is required on attempt lifecycle events";
+    }
+    if (event.retryOfAttemptId !== undefined)
+        return "attemptId is required when retryOfAttemptId is present";
+    if (event.attemptNumber !== undefined)
+        return "attemptId is required when attemptNumber is present";
+    return undefined;
+}
+function deepFreeze(root) {
+    const stack = [root];
+    while (stack.length > 0) {
+        const value = stack.pop();
+        if (value === null || typeof value !== "object" || Object.isFrozen(value))
+            continue;
+        Object.freeze(value);
+        for (const child of Object.values(value))
+            stack.push(child);
+    }
+    return root;
+}
+/** Content checks the schema cannot express. Run on the input and again on the serialized clone. */
+function assertEventContent(event) {
+    assertJsonPayload(event.payload);
+    assertFieldPaths(event.fields);
+    assertTimestamp("dh.event/1", "occurredAt", event.occurredAt);
+    assertTimestamp("dh.event/1", "recordedAt", event.recordedAt);
+    for (const coverage of Object.values(event.fields)) {
+        assertCoverage("dh.event/1", coverage);
+    }
+    const violation = attemptIdViolation(event);
+    if (violation !== undefined)
+        throw new DhContractError("schema_invalid", `Invalid dh.event/1: ${violation}`);
+}
+/**
+ * The input is validated, serialized exactly once, and the serialized string is parsed and fully
+ * re-validated. The shared descriptor gate rejects getters and toJSON before invocation.
+ * The byte limit is measured on the same canonical string returned by serialization.
+ */
+export function parseDhEvent(value) {
+    if (value instanceof Uint8Array)
+        value = parseDhRawJson(value, { maxBytes: DH_EVENT_MAX_UTF8_BYTES });
+    assertDhPlainData(value);
+    if (!EventValidator.Check(value))
+        throw schemaError("dh.event/1", EventValidator.Errors(value));
+    assertEventContent(value);
+    const text = dhCanonicalText(value);
+    if (textEncoder.encode(text).length > DH_EVENT_MAX_UTF8_BYTES) {
+        throw new DhContractError("too_large", "Invalid dh.event/1: exceeds UTF-8 bytes limit");
+    }
+    const parsed = JSON.parse(text);
+    if (!EventValidator.Check(parsed))
+        throw schemaError("dh.event/1", EventValidator.Errors(parsed));
+    assertEventContent(parsed);
+    assertDhEventPayload(parsed);
+    return deepFreeze(parsed);
+}
+export function parseDhArtifact(value) {
+    assertDhPlainData(value);
+    if (!ArtifactValidator.Check(value))
+        throw schemaError("dh.artifact/1", ArtifactValidator.Errors(value));
+    assertCoverage("dh.artifact/1", value.coverage);
+    const parsed = JSON.parse(dhCanonicalText(value));
+    if (!ArtifactValidator.Check(parsed))
+        throw schemaError("dh.artifact/1", ArtifactValidator.Errors(parsed));
+    assertCoverage("dh.artifact/1", parsed.coverage);
+    return deepFreeze(parsed);
+}
+export function parseDhAck(value) {
+    assertDhPlainData(value);
+    if (!AckValidator.Check(value))
+        throw schemaError("dh.ack/1", AckValidator.Errors(value));
+    assertTimestamp("dh.ack/1", "receivedAt", value.receivedAt);
+    const parsed = JSON.parse(dhCanonicalText(value));
+    if (!AckValidator.Check(parsed))
+        throw schemaError("dh.ack/1", AckValidator.Errors(parsed));
+    assertTimestamp("dh.ack/1", "receivedAt", parsed.receivedAt);
+    return deepFreeze(parsed);
+}
+/** Single-record shape only. It never treats a retry link as proof that its source failed. */
+export function assertDhManagedLifecycle(input) {
+    const event = parseDhEvent(input);
+    const payload = event.payload;
+    if (!["attempt.started", "attempt.finished", "attempt.retry_scheduled"].includes(event.kind) ||
+        payload.schema !== "dh.payload.attempt-lifecycle/1")
+        throw new DhContractError("schema_invalid");
+    if (event.retryOfAttemptId !== undefined && event.kind !== "attempt.started")
+        throw new DhContractError("schema_invalid");
+    if (event.attemptNumber !== undefined &&
+        (!Number.isSafeInteger(event.attemptNumber) || event.attemptNumber < 1 || event.attemptNumber > 10000))
+        throw new DhContractError("schema_invalid");
+    if (event.kind === "attempt.started" &&
+        (event.attemptNumber === undefined ||
+            payload.attemptNumber !== event.attemptNumber ||
+            event.outcome !== undefined ||
+            event.failure !== undefined))
+        throw new DhContractError("schema_invalid");
+    if (event.kind === "attempt.retry_scheduled" &&
+        (typeof payload.nextAttemptNumber !== "number" ||
+            payload.nextAttemptNumber < 2 ||
+            payload.nextAttemptNumber > 10000))
+        throw new DhContractError("schema_invalid");
+}
+/** Original terminals remain immutable. Only committed, explicitly authorized same-owner resolutions apply. */
+export function resolveDhEffectiveTerminals(events, ownership) {
+    const terminals = new Map();
+    const byId = new Map();
+    for (const event of events) {
+        byId.set(event.eventId, event);
+        if (event.kind !== "attempt.finished" || event.attemptId === undefined)
+            continue;
+        const prior = terminals.get(event.attemptId);
+        terminals.set(event.attemptId, {
+            event: prior?.event ?? event,
+            outcome: prior?.outcome ?? event.outcome,
+            conflict: prior !== undefined,
+            authorityUnresolved: prior?.authorityUnresolved ?? false,
+        });
+    }
+    const resolutions = new Set();
+    for (const amendment of events) {
+        if (amendment.kind !== "event.amendment" ||
+            amendment.payload.schema !== "dh.payload.amendment/1" ||
+            amendment.payload.relation !== "resolves-unknown")
+            continue;
+        const target = byId.get(String(amendment.payload.amendsEventId));
+        if (target?.kind !== "attempt.finished" || target.attemptId === undefined)
+            continue;
+        const terminal = terminals.get(target.attemptId);
+        if (!terminal)
+            continue;
+        const replacement = amendment.payload.replacement;
+        const outcome = replacement !== null && typeof replacement === "object" && !Array.isArray(replacement)
+            ? replacement.outcome
+            : undefined;
+        const a = ownership?.receiptOwners.get(target.eventId);
+        const b = ownership?.receiptOwners.get(amendment.eventId);
+        const sameOwner = a !== undefined &&
+            b !== undefined &&
+            a.bindingId === b.bindingId &&
+            a.originProducerInstanceId === b.originProducerInstanceId &&
+            a.originStreamId === b.originStreamId &&
+            a.originIssuer === b.originIssuer &&
+            a.originStreamId === target.streamId &&
+            b.originStreamId === amendment.streamId &&
+            a.originIssuer === target.producer.issuer &&
+            b.originIssuer === amendment.producer.issuer;
+        const conflict = terminal.conflict ||
+            resolutions.has(target.eventId) ||
+            target.outcome !== "unknown" ||
+            target.agentId !== amendment.agentId ||
+            target.attemptId !== amendment.attemptId ||
+            target.generationId !== amendment.generationId ||
+            scopeKey(target.tenantScope) !== scopeKey(amendment.tenantScope) ||
+            target.streamId !== amendment.streamId ||
+            target.sequence >= amendment.sequence ||
+            amendment.payload.amendsKind !== target.kind ||
+            !outcome ||
+            outcome === "unknown";
+        const authorized = ownership?.authorizedAmendmentEventIds.has(amendment.eventId) === true && sameOwner;
+        resolutions.add(target.eventId);
+        terminals.set(target.attemptId, {
+            event: terminal.event,
+            outcome: !conflict && authorized ? outcome : terminal.outcome,
+            ...(authorized && !conflict ? { resolutionEventId: amendment.eventId } : {}),
+            conflict,
+            authorityUnresolved: terminal.authorityUnresolved || !authorized,
+        });
+    }
+    return terminals;
+}
+/** Eligibility uses durable authenticated context, not source absence or producer timestamps. */
+export function assertDhRetryAdmission(start, context) {
+    assertDhManagedLifecycle(start);
+    if (start.kind !== "attempt.started")
+        throw new DhContractError("schema_invalid");
+    function deny() {
+        throw new DhContractError("not_eligible");
+    }
+    const target = context.starts.find((event) => event.attemptId === start.attemptId);
+    if (target) {
+        if (start.retryOfAttemptId !== undefined &&
+            context.retryClaims.get(start.retryOfAttemptId) === start.attemptId &&
+            dhCanonicalText(target) === dhCanonicalText(start))
+            return;
+        deny();
+    }
+    const priorId = start.retryOfAttemptId;
+    const starts = context.starts.filter((event) => event.kind === "attempt.started" && event.agentId === start.agentId);
+    if (priorId === undefined) {
+        if (starts.length !== 0 || start.attemptNumber !== 1)
+            deny();
+        return;
+    }
+    const source = context.starts.find((event) => event.attemptId === priorId);
+    if (source?.kind !== "attempt.started" ||
+        source.agentId !== start.agentId ||
+        source.generationId !== start.generationId ||
+        scopeKey(source.tenantScope) !== scopeKey(start.tenantScope))
+        deny();
+    try {
+        assertDhManagedLifecycle(source);
+    }
+    catch {
+        deny();
+    }
+    if (source.attemptNumber === undefined ||
+        start.attemptNumber !== source.attemptNumber + 1 ||
+        starts.some((event) => event.attemptNumber === undefined || event.attemptNumber > source.attemptNumber))
+        deny();
+    if (new Set(starts.map((event) => event.attemptNumber)).size !== starts.length)
+        deny();
+    const terminal = resolveDhEffectiveTerminals([...context.terminals, ...context.amendments], context).get(priorId);
+    if (terminal?.outcome !== "failed" ||
+        terminal.conflict ||
+        terminal.authorityUnresolved ||
+        terminal.event.agentId !== start.agentId ||
+        terminal.event.generationId !== start.generationId ||
+        scopeKey(terminal.event.tenantScope) !== scopeKey(start.tenantScope))
+        deny();
+    const claim = context.retryClaims.get(priorId);
+    if (claim !== undefined && claim !== start.attemptId)
+        deny();
+}
+function scopeKey(scope) {
+    return JSON.stringify([scope.environmentId, scope.projectId]);
+}
+/**
+ * Validates cross-record integrity of already-parsed records. Does not re-run schema checks, but
+ * reports (rather than compares) timestamps that are not calendar-valid UTC instants.
+ */
+export function validateDhTraceBundle(bundle, ownership) {
+    const errors = [];
+    const { events, artifacts } = bundle;
+    const generationIds = new Set();
+    const scopes = new Set();
+    for (const record of [...events, ...artifacts]) {
+        generationIds.add(record.generationId);
+        scopes.add(scopeKey(record.tenantScope));
+    }
+    if (generationIds.size > 1)
+        errors.push("records span multiple generationIds; expected one");
+    if (scopes.size > 1)
+        errors.push("records span multiple tenantScopes; expected one");
+    // Timestamps are compared only when calendar-valid; invalid ones are reported once.
+    const occurredAt = new Map();
+    for (const event of events) {
+        const occurred = parseInstant(event.occurredAt);
+        if (occurred === undefined)
+            errors.push("occurredAt is not a calendar-valid UTC instant");
+        else
+            occurredAt.set(event, occurred);
+        if (parseInstant(event.recordedAt) === undefined) {
+            errors.push("recordedAt is not a calendar-valid UTC instant");
+        }
+    }
+    const eventsById = new Map();
+    const streamSequences = new Set();
+    for (const event of events) {
+        if (eventsById.has(event.eventId))
+            errors.push("duplicate eventId");
+        else
+            eventsById.set(event.eventId, event);
+        const key = JSON.stringify([event.streamId, event.sequence]);
+        if (streamSequences.has(key))
+            errors.push("duplicate (streamId, sequence)");
+        streamSequences.add(key);
+    }
+    // Artifact links are reciprocal: artifact.eventId <-> event.artifacts, with matching owner.
+    const artifactsById = new Map();
+    for (const artifact of artifacts) {
+        if (artifactsById.has(artifact.artifactId))
+            errors.push("duplicate artifactId");
+        else
+            artifactsById.set(artifact.artifactId, artifact);
+        const event = eventsById.get(artifact.eventId);
+        if (event === undefined) {
+            errors.push("artifact references unknown eventId");
+            continue;
+        }
+        if (!(event.artifacts ?? []).includes(artifact.artifactId)) {
+            errors.push("artifact is not listed in artifacts of event");
+        }
+        if (artifact.agentId !== event.agentId) {
+            errors.push("artifact agentId does not match event");
+        }
+        if (artifact.attemptId !== event.attemptId) {
+            errors.push("artifact attemptId does not match event");
+        }
+    }
+    for (const event of events) {
+        for (const ref of event.artifacts ?? []) {
+            const artifact = artifactsById.get(ref);
+            if (artifact === undefined)
+                errors.push("event references unknown artifact");
+            else if (artifact.eventId !== event.eventId) {
+                errors.push("event lists artifact which names a different event");
+            }
+        }
+    }
+    validateAgentHierarchy(events, errors);
+    validateAttempts(events, occurredAt, errors, ownership);
+    validateDelegations(events, eventsById, errors);
+    errors.push(...validateDhPayloadGraph(events, artifacts, ownership));
+    return errors.length === 0 ? { ok: true } : { ok: false, errors };
+}
+/** Validate declared subagent provenance without requiring a result from unfinished work. */
+function validateDelegations(events, eventsById, errors) {
+    const calls = new Map();
+    const spawns = new Map();
+    const childrenByCall = new Map();
+    for (const event of events) {
+        if (event.kind === "tool.call" && typeof event.payload.callId === "string") {
+            const key = JSON.stringify([event.agentId, event.attemptId ?? null, event.payload.callId]);
+            if (calls.has(key))
+                errors.push("duplicate tool call identity");
+            else
+                calls.set(key, event);
+        }
+        if (event.kind !== "agent.spawned")
+            continue;
+        if (spawns.has(event.agentId))
+            errors.push("duplicate agent.spawned");
+        else
+            spawns.set(event.agentId, event);
+        if (event.payload.via !== "subagent" && event.payload.spawnedByEventId === undefined)
+            continue;
+        const sourceId = event.payload.spawnedByEventId;
+        if (typeof sourceId !== "string" || sourceId.length === 0) {
+            const coverage = event.fields["payload.spawnedByEventId"] ?? event.fields.payload;
+            if (!coverage || !["unavailable", "redacted", "truncated"].includes(coverage.state) || !coverage.reason) {
+                errors.push("subagent spawn has no call provenance or loss coverage");
+            }
+            continue;
+        }
+        const call = eventsById.get(sourceId);
+        if (call?.kind !== "tool.call" || call.payload.toolName !== "subagent") {
+            errors.push("spawn references no subagent tool.call");
+        }
+        else if (call.agentId !== event.parentAgentId || typeof call.payload.callId !== "string") {
+            errors.push("spawn does not belong to the parent call");
+        }
+        else {
+            if (call.streamId === event.streamId && call.sequence >= event.sequence) {
+                errors.push("spawn precedes its parent call in the producer stream");
+            }
+            const children = childrenByCall.get(call.eventId) ?? new Set();
+            children.add(event.agentId);
+            childrenByCall.set(call.eventId, children);
+        }
+    }
+    for (const event of events) {
+        if (event.kind !== "tool.result" || event.payload.toolName !== "subagent")
+            continue;
+        const callId = event.payload.callId;
+        const key = JSON.stringify([event.agentId, event.attemptId ?? null, callId]);
+        const call = typeof callId === "string" ? calls.get(key) : undefined;
+        if (call?.payload.toolName !== "subagent") {
+            errors.push("subagent result has no matching parent call");
+            continue;
+        }
+        if (call.streamId === event.streamId && call.sequence >= event.sequence) {
+            errors.push("result precedes its parent call in the producer stream");
+        }
+        const one = event.payload.childAgentId;
+        const many = event.payload.childAgentIds;
+        if (one !== undefined && many !== undefined) {
+            errors.push("use childAgentId or childAgentIds, not both");
+            continue;
+        }
+        if (one !== undefined && typeof one !== "string") {
+            errors.push("childAgentId must be a string");
+            continue;
+        }
+        if (many !== undefined && (!Array.isArray(many) || many.some((id) => typeof id !== "string"))) {
+            errors.push("childAgentIds must be an array of strings");
+            continue;
+        }
+        const children = typeof one === "string" ? [one] : Array.isArray(many) ? many : [];
+        const seen = new Set();
+        for (const child of children) {
+            if (typeof child !== "string")
+                continue;
+            if (seen.has(child))
+                errors.push("duplicate child");
+            seen.add(child);
+            const spawn = spawns.get(child);
+            if (!spawn || spawn.parentAgentId !== event.agentId || spawn.payload.spawnedByEventId !== call.eventId) {
+                errors.push("child was not spawned by this call");
+            }
+            else if (spawn.streamId === event.streamId && spawn.sequence >= event.sequence) {
+                errors.push("result precedes child in the producer stream");
+            }
+        }
+        const coverage = event.fields["payload.childAgentIds"] ?? event.fields["payload.childAgentId"] ?? event.fields.payload;
+        const missingCovered = coverage && ["unavailable", "redacted", "truncated"].includes(coverage.state) && coverage.reason;
+        if (!missingCovered) {
+            for (const child of childrenByCall.get(call.eventId) ?? []) {
+                if (!seen.has(child))
+                    errors.push("result omits observed child");
+            }
+        }
+    }
+}
+/** One parent per agent, no ancestry cycles, exactly one root agent per generation. */
+function validateAgentHierarchy(events, errors) {
+    const parentOf = new Map();
+    const agentsWithoutParentEvent = new Set();
+    const spawnedAgents = new Set();
+    const generationOf = new Map();
+    for (const event of events) {
+        generationOf.set(event.agentId, event.generationId);
+        if (event.kind === "agent.spawned")
+            spawnedAgents.add(event.agentId);
+        if (event.parentAgentId === undefined) {
+            agentsWithoutParentEvent.add(event.agentId);
+            continue;
+        }
+        const known = parentOf.get(event.agentId);
+        if (known === undefined)
+            parentOf.set(event.agentId, event.parentAgentId);
+        else if (known !== event.parentAgentId) {
+            errors.push("agent has conflicting parentAgentId values");
+        }
+    }
+    for (const agentId of agentsWithoutParentEvent) {
+        if (parentOf.has(agentId))
+            errors.push("agent has events both with and without parentAgentId");
+    }
+    for (const [agentId, parent] of parentOf) {
+        if (parent === agentId)
+            errors.push("agent is its own parent");
+        else if (!generationOf.has(parent))
+            errors.push("unknown parentAgentId");
+        else if (parentOf.has(parent) && !spawnedAgents.has(parent)) {
+            errors.push("parentAgentId was never spawned in this generation");
+        }
+    }
+    // Cycle detection: walk each ancestry chain once; revisiting a node on the current walk is a cycle.
+    const settled = new Set();
+    for (const start of parentOf.keys()) {
+        const walk = new Set();
+        let current = start;
+        while (current !== undefined && !settled.has(current)) {
+            if (walk.has(current)) {
+                errors.push("agent ancestry cycle");
+                break;
+            }
+            walk.add(current);
+            current = parentOf.get(current);
+        }
+        for (const visited of walk)
+            settled.add(visited);
+    }
+    const rootsByGeneration = new Map();
+    for (const [agentId, generationId] of generationOf) {
+        if (parentOf.has(agentId))
+            continue;
+        const roots = rootsByGeneration.get(generationId) ?? [];
+        roots.push(agentId);
+        rootsByGeneration.set(generationId, roots);
+    }
+    for (const generationId of new Set(generationOf.values())) {
+        const roots = rootsByGeneration.get(generationId) ?? [];
+        if (roots.length !== 1) {
+            errors.push("generation must have exactly one root agent");
+        }
+    }
+}
+/** Attempt ownership, uniqueness, chronology and retry linkage. */
+function validateAttempts(events, occurredAt, errors, ownership) {
+    const effective = resolveDhEffectiveTerminals(events, ownership);
+    const retryClaims = new Map();
+    const started = new Map();
+    const finished = new Map();
+    for (const event of events) {
+        if (event.attemptId === undefined)
+            continue;
+        if (event.kind === "attempt.started") {
+            if (started.has(event.attemptId))
+                errors.push("duplicate attempt.started for attempt");
+            else
+                started.set(event.attemptId, event);
+        }
+        else if (event.kind === "attempt.finished") {
+            if (finished.has(event.attemptId))
+                errors.push("duplicate attempt.finished for attempt");
+            else
+                finished.set(event.attemptId, event);
+        }
+    }
+    for (const event of events) {
+        const violation = attemptIdViolation(event);
+        if (violation !== undefined)
+            errors.push(violation);
+        if (event.retryOfAttemptId !== undefined && event.kind !== "attempt.started") {
+            errors.push("retryOfAttemptId is only allowed on attempt.started");
+        }
+        if (event.attemptId === undefined)
+            continue;
+        const start = started.get(event.attemptId);
+        if (start === undefined) {
+            errors.push(event.kind === "attempt.finished"
+                ? "attempt.finished for attempt has no matching attempt.started"
+                : "attempt has no attempt.started");
+            continue;
+        }
+        if (start.agentId !== event.agentId) {
+            errors.push("attempt belongs to a different agent");
+        }
+        if (event.kind === "attempt.finished" && finished.get(event.attemptId) === event) {
+            const startedAt = occurredAt.get(start);
+            const finishedAt = occurredAt.get(event);
+            if (start.streamId === event.streamId &&
+                startedAt !== undefined &&
+                finishedAt !== undefined &&
+                finishedAt < startedAt) {
+                errors.push("attempt finished before it started");
+            }
+        }
+    }
+    const previousByAttempt = new Map();
+    const startedByAgent = new Map();
+    for (const event of started.values()) {
+        const list = startedByAgent.get(event.agentId) ?? [];
+        list.push(event);
+        startedByAgent.set(event.agentId, list);
+    }
+    for (const list of startedByAgent.values()) {
+        list.sort((a, b) => (a.attemptNumber ?? a.sequence + 1) - (b.attemptNumber ?? b.sequence + 1));
+        list.forEach((event, index) => {
+            const previous = list[index - 1];
+            if (previous && event.attemptId)
+                previousByAttempt.set(event.attemptId, previous);
+            if (event.payload.schema === "dh.payload.attempt-lifecycle/1") {
+                try {
+                    assertDhManagedLifecycle(event);
+                }
+                catch {
+                    errors.push("schema_invalid: invalid managed lifecycle");
+                }
+                if ((index === 0 && event.retryOfAttemptId !== undefined) ||
+                    (index > 0 && event.retryOfAttemptId !== previous?.attemptId))
+                    errors.push("not_eligible: attempt start must link its latest recorded predecessor");
+            }
+            if (event.attemptNumber !== undefined && event.attemptNumber !== index + 1) {
+                errors.push("attemptNumber does not match the attempt order");
+            }
+        });
+    }
+    const scheduled = new Map();
+    for (const event of events) {
+        if (event.kind !== "attempt.retry_scheduled" || !event.attemptId)
+            continue;
+        const list = scheduled.get(event.attemptId) ?? [];
+        list.push(event);
+        scheduled.set(event.attemptId, list);
+    }
+    for (const event of started.values()) {
+        const prior = event.retryOfAttemptId;
+        if (prior === undefined)
+            continue;
+        if (prior === event.attemptId) {
+            errors.push("attempt cannot retry itself");
+            continue;
+        }
+        for (const schedule of scheduled.get(prior) ?? []) {
+            if (schedule.agentId !== event.agentId ||
+                schedule.generationId !== event.generationId ||
+                scopeKey(schedule.tenantScope) !== scopeKey(event.tenantScope) ||
+                schedule.payload.nextAttemptNumber !== event.attemptNumber)
+                errors.push("not_eligible: retry schedule does not match source and next attempt number");
+        }
+        const priorStart = started.get(prior);
+        const priorFinish = finished.get(prior);
+        if (priorFinish === undefined || priorStart === undefined) {
+            errors.push("retryOfAttemptId is not a known finished attempt");
+            continue;
+        }
+        if (priorStart.agentId !== event.agentId) {
+            errors.push("retryOfAttemptId belongs to a different agent");
+        }
+        const terminal = effective.get(prior);
+        if (terminal?.outcome !== "failed" || terminal.conflict || terminal.authorityUnresolved) {
+            errors.push("retryOfAttemptId did not finish with outcome failed");
+        }
+        if (priorStart.generationId !== event.generationId ||
+            scopeKey(priorStart.tenantScope) !== scopeKey(event.tenantScope))
+            errors.push("not_eligible: retry source has a foreign generation or scope");
+        if (retryClaims.has(prior) && retryClaims.get(prior) !== event.attemptId)
+            errors.push("not_eligible: retry source already claimed");
+        retryClaims.set(prior, event.attemptId);
+        if (event.attemptId && previousByAttempt.get(event.attemptId)?.attemptId !== prior)
+            errors.push("not_eligible: retry source is not the latest attempt");
+        const priorFinishedAt = occurredAt.get(priorFinish);
+        const retryStartedAt = occurredAt.get(event);
+        if (priorFinish.streamId === event.streamId &&
+            priorFinishedAt !== undefined &&
+            retryStartedAt !== undefined &&
+            priorFinishedAt > retryStartedAt) {
+            errors.push("retryOfAttemptId finished after the retry");
+        }
+        if (event.attemptNumber !== undefined &&
+            priorStart.attemptNumber !== undefined &&
+            event.attemptNumber !== priorStart.attemptNumber + 1) {
+            errors.push("attemptNumber does not follow the prior attemptNumber");
+        }
+    }
+}
+//# sourceMappingURL=trace.js.map