@humain/humain-code-contracts 0.3.2

package/dist/trace-http.js

@@ -0,0 +1,1481 @@
+import { Type } from "typebox";
+import { Compile } from "typebox/compile";
+import { DH_ARTIFACT_KINDS, DH_ARTIFACT_MAX_BYTES, DH_ARTIFACT_MEDIA_TYPES, DH_COVERAGE_REASONS, DH_COVERAGE_STATES, DH_EVENT_KINDS, DH_ISSUERS, DH_OUTCOMES, DH_REJECTION_CODES, DhAgentIdSchema, DhArtifactIdSchema, DhAttemptIdSchema, DhEventIdSchema, DhGenerationIdSchema, DhTenantScopeSchema, parseDhArtifact, parseDhEvent, } from "./trace.js";
+import { DH_EXPORT_STATES, parseDhIngestAck } from "./trace-api.js";
+import { assertDhPlainData, DhContractError, dhCanonicalText, dhDigestInput, parseDhRawJson, } from "./trace-canonical.js";
+import { acceptDhExportManifestPage, beginDhExportManifest, finishDhExportManifest, } from "./trace-export.js";
+import { assertDhAppliedControlEvidence } from "./trace-payload.js";
+/*
+ * C0 HTTP contract freeze: route table, auth/export/control DTOs, ACK validation and the safe
+ * Flow producer types. Everything here is a proposal frozen for consumer alignment, not an
+ * existing Code endpoint. This module is re-exported by ./trace.ts, which it also imports, so
+ * NOTHING here may read an imported trace.ts/trace-api.ts value at module top level: schemas are
+ * built lazily inside functions. Literals that mirror trace.ts constants are asserted equal in
+ * test/trace-http-conformance.test.ts.
+ */
+// ---------------------------------------------------------------------------
+// Decisions and limits
+// ---------------------------------------------------------------------------
+/** Schema ids introduced by this freeze. Existing dh.event/1, dh.artifact/1 and dh.ack/1 are unchanged. */
+export const DH_HTTP_SCHEMA_IDS = Object.freeze({
+    admissionBinding: "dh.admission-binding/1",
+    workloadBinding: "dh.workload-binding/1",
+    originDelegation: "dh.origin-delegation/1",
+    artifactReceipt: "dh.artifact-receipt/1",
+    controlReceipt: "dh.control-receipt/1",
+    controlRequest: "dh.control-request/2",
+    controlStatus: "dh.control-status/2",
+    controlTarget: "dh.control-target/1",
+    controlDelivery: "dh.control-delivery/1",
+    controlHandshake: "dh.control-handshake/1",
+    controllerCredential: "dh.controller-credential/1",
+    cursorBinding: "dh.cursor-binding/2",
+    snapshotCutoff: "dh.snapshot-cutoff/1",
+    generationPage: "dh.generation-page/2",
+    agentPage: "dh.agent-page/2",
+    eventPage: "dh.event-page/2",
+    exportManifestHeader: "dh.export-manifest-header/2",
+    exportManifestPage: "dh.export-manifest-page/2",
+    producerEnrollment: "dh.producer-enrollment/2",
+    producerEnrollmentRequest: "dh.producer-enrollment-request/2",
+});
+/**
+ * Batch version decision record. dh.batch/1-proposal stays the ONLY schema managed ingress accepts.
+ * C0 resolves the synthetic-local lane to the proposal literal only. Production promotion remains
+ * a separate coordinated decision; it is never accepted alongside the proposal.
+ */
+export const DH_BATCH_VERSION_DECISION = Object.freeze({
+    accepted: "dh.batch/1-proposal",
+    promotionCandidate: "dh.batch/1",
+    status: "resolved-synthetic-local",
+    dualVersionIngress: false,
+});
+/** Validation ceiling only; the real access-token TTL is an open policy input. Matches the current client ceiling. */
+export const DH_TOKEN_MAX_EXPIRES_IN_SECONDS = 600;
+export const DH_EXPORT_MANIFEST_MAX_SHARDS = 1024;
+/** Equal to DH_MAX_ACK_IDS (asserted in tests): one shard page is one bounded ACK-sized ID list. */
+export const DH_EXPORT_MANIFEST_SHARD_MAX_IDS = 1000;
+export const DH_GRANT_MAX_PROJECTS = 16;
+/** Provisional bound for continuation text; policy may lower it. */
+export const DH_CONTROL_MESSAGE_MAX_CHARS = 16384;
+export const DH_GRANT_PERMISSIONS = ["review-metadata", "review-content", "export"];
+// ---------------------------------------------------------------------------
+// Shared helpers
+// ---------------------------------------------------------------------------
+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 timestamp = Type.String({
+    minLength: 20,
+    maxLength: 30,
+    pattern: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,9})?Z$",
+});
+const digest = Type.String({ pattern: "^[a-f0-9]{64}$" });
+const SCOPE_ID = "^[A-Za-z0-9][A-Za-z0-9_.-]{0,255}$";
+const scopeId = Type.String({ minLength: 1, maxLength: 256, pattern: SCOPE_ID });
+const streamIdSchema = Type.String({ minLength: 1, maxLength: 128, pattern: "^[A-Za-z0-9_-]{1,128}$" });
+const refSchema = Type.String({ minLength: 1, maxLength: 128, pattern: "^[A-Za-z0-9_.-]+$" });
+const cursorSchema = Type.String({ minLength: 1, maxLength: 1024, pattern: "^[\\x21-\\x7e]+$" });
+const nextCursorSchema = Type.Union([Type.Null(), cursorSchema]);
+const opaqueToken = Type.String({ minLength: 1, maxLength: 4096, pattern: "^[\\x21-\\x7e]+$" });
+const clientIdSchema = Type.String({ minLength: 1, maxLength: 256, pattern: "^[A-Za-z0-9._~-]+$" });
+const LOOPBACK_REDIRECT = "^http://(?:127\\.0\\.0\\.1|localhost|\\[::1\\]):[1-9][0-9]{0,4}(?:/[A-Za-z0-9._~/-]*)?$";
+const prefixed = (prefix) => Type.String({ pattern: `^${prefix}_[A-Za-z0-9_-]{8,128}$`, maxLength: prefix.length + 129 });
+const requestIdSchema = () => prefixed("ctl");
+const enrollmentIdSchema = () => prefixed("enr");
+const jobIdSchema = Type.String({ minLength: 1, maxLength: 256, pattern: "^[A-Za-z0-9_-]+$" });
+const FORBIDDEN_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+const FIELD_PATH = /^[A-Za-z][A-Za-z0-9_-]*(?:\.[A-Za-z0-9_-]+)*$/;
+const INSTANT_KEYS = new Set([
+    "captureCutoff",
+    "startedAt",
+    "finishedAt",
+    "occurredAt",
+    "recordedAt",
+    "receivedAt",
+    "updatedAt",
+    "admittedAt",
+    "expiresAt",
+    "authorizedAt",
+    "issuedAt",
+]);
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+const INSTANT_PARTS = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d{1,9})?Z$/;
+/** Date.parse rolls impossible dates over, so the parsed instant must round-trip to the same calendar fields. */
+function isCalendarInstant(text) {
+    const parts = INSTANT_PARTS.exec(text);
+    if (parts === null)
+        return false;
+    const base = text.slice(0, 19);
+    const whole = Date.parse(`${base}.000Z`);
+    return Number.isFinite(whole) && new Date(whole).toISOString().slice(0, 19) === base;
+}
+function assertInstants(label, root) {
+    const stack = [root];
+    while (stack.length > 0) {
+        const value = stack.pop();
+        if (Array.isArray(value))
+            stack.push(...value);
+        else if (isRecord(value)) {
+            for (const [key, child] of Object.entries(value)) {
+                if (typeof child === "string" && INSTANT_KEYS.has(key) && !isCalendarInstant(child)) {
+                    throw new DhContractError("schema_invalid", `Invalid ${label}: ${key} is not a calendar-valid UTC instant`);
+                }
+                stack.push(child);
+            }
+        }
+    }
+}
+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;
+}
+/** Strict parser: plain-JSON gate, schema check, clone, re-check, calendar-valid instants, DTO semantics, freeze. */
+function dtoParser(label, schema, semantic) {
+    let validator;
+    return (value) => {
+        assertDhPlainData(value);
+        validator ??= Compile(schema());
+        if (!validator.Check(value))
+            throw new DhContractError("schema_invalid", `Invalid ${label}`);
+        const clone = JSON.parse(JSON.stringify(value));
+        if (!validator.Check(clone))
+            throw new DhContractError("schema_invalid", `Invalid ${label}`);
+        assertInstants(label, clone);
+        semantic?.(clone);
+        return deepFreeze(clone);
+    };
+}
+/**
+ * The strict DTO parser (plain-JSON wire gate, schema check, clone, re-check, instants, semantics, freeze)
+ * for sibling modules such as trace-payload.ts, so the gate is never re-implemented.
+ */
+export { dtoParser as dhStrictDtoParser };
+/** Replay and duplicate comparisons share the origin JCS profile. */
+const canonicalText = dhCanonicalText;
+function assertUnique(label, ids) {
+    if (new Set(ids).size !== ids.length)
+        throw new DhContractError("schema_invalid", `Invalid ${label}: duplicate ids`);
+}
+function metadataCoverage() {
+    // No `detail`: it can carry transcript text.
+    return strict({ state: Type.Enum(DH_COVERAGE_STATES), reason: Type.Optional(Type.Enum(DH_COVERAGE_REASONS)) });
+}
+function assertCoverageReason(label, coverage) {
+    if (coverage.state !== "captured" && coverage.reason === undefined) {
+        throw new Error(`Invalid ${label}: non-captured coverage requires a reason`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Route table
+// ---------------------------------------------------------------------------
+export const DH_ROUTE_AUDIENCES = ["browser-review", "producer", "workload", "control", "records-policy"];
+const S = "/api/v1/environments/{environmentId}/projects/{projectId}";
+const I = `${S}/trace-ingest`;
+const JSON_TYPE = "application/json";
+const FORM_TYPE = "application/x-www-form-urlencoded";
+const BYTES_TYPE = "application/octet-stream";
+function route(method, path, audience, requestContentType, responseContentType, successStatus, requestHeaders, responseSchemaId) {
+    return Object.freeze({
+        method,
+        path,
+        audience,
+        requestContentType,
+        ...(requestHeaders ? { requestHeaders: Object.freeze([...requestHeaders]) } : {}),
+        responseContentType,
+        ...(responseSchemaId ? { responseSchemaId } : {}),
+        successStatus: Object.freeze([...successStatus]),
+    });
+}
+const ROUTE_DEFINITIONS = {
+    authorizeConsent: route("GET", "/auth/trace-client/authorize", "browser-review", null, "text/html", [200]),
+    authorizeSubmit: route("POST", "/auth/trace-client/authorize", "browser-review", FORM_TYPE, null, [303]),
+    clientToken: route("POST", "/auth/trace-client/token", "browser-review", FORM_TYPE, JSON_TYPE, [200]),
+    clientRevoke: route("POST", "/auth/trace-client/revoke", "browser-review", FORM_TYPE, null, [204]),
+    producerEnroll: route("POST", `${S}/producer-enrollments`, "workload", JSON_TYPE, JSON_TYPE, [201], ["authorization"]),
+    producerToken: route("POST", "/auth/trace-producer/token", "workload", JSON_TYPE, JSON_TYPE, [200], ["authorization"]),
+    producerRevoke: route("POST", "/auth/trace-producer/revoke", "workload", JSON_TYPE, null, [204], ["authorization"]),
+    ingestRecords: route("POST", `${I}/streams/{streamId}/records`, "producer", JSON_TYPE, JSON_TYPE, [200], ["x-dh-previous-acked-sequence"], "dh.ack/1"),
+    ingestArtifactContent: route("PUT", `${I}/artifacts/{artifactId}/content`, "producer", BYTES_TYPE, JSON_TYPE, [200], ["x-dh-sha256"], "dh.artifact-receipt/1"),
+    reviewGenerations: route("GET", `${S}/generations`, "browser-review", null, JSON_TYPE, [200]),
+    reviewAgents: route("GET", `${S}/generations/{generationId}/agents`, "browser-review", null, JSON_TYPE, [200]),
+    reviewEvents: route("GET", `${S}/generations/{generationId}/events`, "browser-review", null, JSON_TYPE, [200]),
+    reviewArtifact: route("GET", `${S}/artifacts/{artifactId}`, "browser-review", null, JSON_TYPE, [200]),
+    reviewArtifactContent: route("GET", `${S}/artifacts/{artifactId}/content`, "browser-review", null, BYTES_TYPE, [200]),
+    usage: route("GET", `${S}/generations/{generationId}/usage`, "browser-review", null, JSON_TYPE, [200]),
+    search: route("GET", `${S}/generations/{generationId}/search`, "browser-review", null, JSON_TYPE, [200]),
+    exportCreate: route("POST", `${S}/generations/{generationId}/exports`, "browser-review", JSON_TYPE, JSON_TYPE, [202]),
+    exportStatus: route("GET", `${S}/generations/{generationId}/exports/{jobId}`, "browser-review", null, JSON_TYPE, [200]),
+    exportManifest: route("GET", `${S}/generations/{generationId}/exports/{jobId}/manifest`, "browser-review", null, JSON_TYPE, [200]),
+    exportDownload: route("GET", `${S}/generations/{generationId}/exports/{jobId}/download`, "browser-review", null, JSON_TYPE, [200]),
+    exportContent: route("GET", `${S}/generations/{generationId}/exports/{jobId}/content`, "browser-review", null, BYTES_TYPE, [200]),
+    controlTarget: route("GET", `${S}/generations/{generationId}/agents/{agentId}/control-target`, "control", null, JSON_TYPE, [200], undefined, "dh.control-target/1"),
+    controlCancel: route("POST", `${S}/generations/{generationId}/agents/{agentId}/cancel`, "control", JSON_TYPE, JSON_TYPE, [200, 202]),
+    controlRetry: route("POST", `${S}/generations/{generationId}/agents/{agentId}/retry`, "control", JSON_TYPE, JSON_TYPE, [200, 202]),
+    controlContinue: route("POST", `${S}/generations/{generationId}/agents/{agentId}/continue`, "control", JSON_TYPE, JSON_TYPE, [200, 202]),
+    controlRequest: route("GET", `${S}/generations/{generationId}/agents/{agentId}/control-requests/{requestId}`, "control", null, JSON_TYPE, [200]),
+    generationDelete: route("DELETE", `${S}/generations/{generationId}`, "records-policy", null, JSON_TYPE, [202]),
+    legalHoldCreate: route("POST", `${S}/generations/{generationId}/legal-holds`, "records-policy", JSON_TYPE, JSON_TYPE, [201]),
+    legalHoldRelease: route("DELETE", `${S}/generations/{generationId}/legal-holds/{holdId}`, "records-policy", null, null, [204]),
+};
+export const DH_ROUTES = Object.freeze(ROUTE_DEFINITIONS);
+/** ID segment validators. Only unreserved characters: no separators, dots-only segments, encodings or wildcards. */
+export const DH_PATH_PARAM_PATTERNS = Object.freeze({
+    environmentId: new RegExp(SCOPE_ID),
+    projectId: new RegExp(SCOPE_ID),
+    streamId: /^[A-Za-z0-9_-]{1,128}$/,
+    generationId: /^gen_[A-Za-z0-9_-]{8,128}$/,
+    agentId: /^agt_[A-Za-z0-9_-]{8,128}$/,
+    artifactId: /^art_[A-Za-z0-9_-]{8,128}$/,
+    jobId: /^[A-Za-z0-9_-]{1,256}$/,
+    requestId: /^ctl_[A-Za-z0-9_-]{8,128}$/,
+    holdId: /^[A-Za-z0-9_-]{1,256}$/,
+});
+function routeFor(id) {
+    if (!Object.hasOwn(ROUTE_DEFINITIONS, id))
+        throw new DhContractError("schema_invalid", "Unknown trace route");
+    return ROUTE_DEFINITIONS[id];
+}
+/** Builds a path from the frozen template. Params must be exactly the template's placeholders, each validated then percent-encoded. */
+export function buildDhRoutePath(id, params) {
+    const definition = routeFor(id);
+    const names = [...definition.path.matchAll(/\{(\w+)\}/g)].map((match) => match[1]);
+    if (!isRecord(params))
+        throw new Error(`Route ${id} requires exactly the parameters ${names.join(", ") || "(none)"}`);
+    assertDhPlainData(params);
+    const given = Object.keys(params);
+    if (given.length !== names.length || given.some((name) => !names.includes(name))) {
+        throw new Error(`Route ${id} requires exactly the parameters ${names.join(", ") || "(none)"}`);
+    }
+    return definition.path.replace(/\{(\w+)\}/g, (_, name) => {
+        const value = Object.hasOwn(params, name) ? params[name] : undefined;
+        const pattern = DH_PATH_PARAM_PATTERNS[name];
+        if (typeof value !== "string" || pattern === undefined || !pattern.test(value)) {
+            throw new Error(`Invalid route parameter ${name}`);
+        }
+        return encodeURIComponent(value);
+    });
+}
+/**
+ * Grant permissions a browser-review route needs. Export reads (status, manifest, download, content)
+ * are authorized from the SERVER-STORED job, passed as `job` (its `contentIncluded`, e.g. from
+ * DhExportJobStatus): export + review-metadata always, plus review-content when the stored job
+ * includes content. A caller-supplied `includeContent` is ignored for them and a missing or malformed
+ * `job` throws. The server must evaluate this on every read, so a grant that lost review-content after
+ * creation can no longer read a content job. Only `exportCreate` (which creates the job) and the
+ * event/search views use `includeContent`. Control/producer/records-policy routes use no read-grant permission.
+ * `options` (and the `job` inside it) pass the plain-JSON wire gate before any member is read, so an accessor or
+ * non-plain object is rejected without executing user code.
+ */
+export function requiredDhPermissions(id, options) {
+    assertDhPlainData(options);
+    const content = options.includeContent === true;
+    switch (id) {
+        case "reviewGenerations":
+        case "reviewAgents":
+        case "usage":
+        case "reviewArtifact":
+            return ["review-metadata"];
+        case "reviewEvents":
+        case "search":
+            return content ? ["review-content"] : ["review-metadata"];
+        case "reviewArtifactContent":
+            return ["review-content"];
+        case "exportCreate":
+            return content ? ["export", "review-content", "review-metadata"] : ["export", "review-metadata"];
+        case "exportStatus":
+        case "exportManifest":
+        case "exportDownload":
+        case "exportContent": {
+            const stored = options.job?.contentIncluded;
+            if (typeof stored !== "boolean")
+                throw new Error(`Route ${id} needs the stored export job to derive permissions`);
+            return stored ? ["export", "review-content", "review-metadata"] : ["export", "review-metadata"];
+        }
+        default:
+            routeFor(id);
+            return [];
+    }
+}
+/** Credential classes are not interchangeable: a credential is valid only on routes of its own audience class. */
+export function assertDhCredentialForRoute(id, credentialClass) {
+    const definition = routeFor(id);
+    if (!DH_ROUTE_AUDIENCES.includes(credentialClass)) {
+        throw new Error("Unknown credential class");
+    }
+    if (definition.audience !== credentialClass) {
+        throw new DhContractError(definition.audience === "workload" ? "workload_proof_invalid" : "not_authorized", `Credential class is not valid for route ${id}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Immutable admission and caller-supplied registry facts
+// ---------------------------------------------------------------------------
+function admissionBindingSchema() {
+    return strict({
+        schema: Type.Literal(DH_HTTP_SCHEMA_IDS.admissionBinding),
+        bindingId: prefixed("bnd"),
+        generationRootBindingId: prefixed("bnd"),
+        mappingRevision: digest,
+        tenantId: scopeId,
+        environmentId: scopeId,
+        projectId: scopeId,
+        nativeProjectId: scopeId,
+        nativeRunId: scopeId,
+        nativeSegmentId: scopeId,
+        generationId: DhGenerationIdSchema,
+        rootAgentId: DhAgentIdSchema,
+        initiatingActorId: scopeId,
+        bindingEpoch: refSchema,
+        policyRevision: refSchema,
+        admittedAt: timestamp,
+        environment: Type.Literal("local"),
+        syntheticOnly: Type.Literal(true),
+    });
+}
+export const parseDhAdmissionBinding = dtoParser("admission binding", admissionBindingSchema);
+/** Pure equality over supplied durable facts, not a registry lookup or authentication. */
+export function assertDhRecordBinding(recordInput, bindingInput, context = {}) {
+    const binding = parseDhAdmissionBinding(bindingInput);
+    assertDhPlainData(recordInput);
+    const record = isRecord(recordInput) && recordInput.schema === "dh.artifact/1"
+        ? parseDhArtifact(recordInput)
+        : parseDhEvent(recordInput);
+    assertDhPlainData(context);
+    if (context.routeScope &&
+        (context.routeScope.environmentId !== binding.environmentId || context.routeScope.projectId !== binding.projectId))
+        throw new DhContractError("not_found");
+    if (context.tombstoned)
+        throw new DhContractError("tombstoned");
+    if (record.generationId !== binding.generationId ||
+        record.tenantScope.environmentId !== binding.environmentId ||
+        record.tenantScope.projectId !== binding.projectId)
+        throw new DhContractError("scope_binding_conflict");
+    const mapping = context.registryMapping;
+    if (mapping === null)
+        throw new DhContractError("mapping_missing");
+    if (mapping !== undefined) {
+        if (mapping.mappingRevision !== binding.mappingRevision)
+            throw new DhContractError("mapping_stale");
+        for (const key of ["tenantId", "environmentId", "projectId", "nativeProjectId"])
+            if (mapping[key] !== binding[key])
+                throw new DhContractError("scope_binding_conflict");
+    }
+    if (context.previousBinding &&
+        canonicalText(parseDhAdmissionBinding(context.previousBinding)) !== canonicalText(binding))
+        throw new DhContractError("scope_binding_conflict");
+    if (context.rootBinding) {
+        const root = parseDhAdmissionBinding(context.rootBinding);
+        if (root.bindingId !== root.generationRootBindingId || binding.generationRootBindingId !== root.bindingId)
+            throw new DhContractError("scope_binding_conflict");
+        for (const key of [
+            "tenantId",
+            "environmentId",
+            "projectId",
+            "nativeProjectId",
+            "generationId",
+            "rootAgentId",
+            "initiatingActorId",
+        ])
+            if (root[key] !== binding[key])
+                throw new DhContractError("scope_binding_conflict");
+    }
+    if (context.owner && context.owner.bindingId !== binding.bindingId)
+        throw new DhContractError("scope_binding_conflict");
+    if (context.existingOwner) {
+        if (!context.owner ||
+            context.owner.bindingId !== context.existingOwner.bindingId ||
+            context.owner.originProducerInstanceId !== context.existingOwner.originProducerInstanceId)
+            throw new DhContractError("duplicate_conflict");
+    }
+}
+// ---------------------------------------------------------------------------
+// Browser public-client and producer authentication DTOs
+// ---------------------------------------------------------------------------
+function grantScopeSchema() {
+    return strict({
+        environmentId: scopeId,
+        projectIds: Type.Array(scopeId, { minItems: 1, maxItems: DH_GRANT_MAX_PROJECTS, uniqueItems: true }),
+        permissions: Type.Array(Type.Enum(DH_GRANT_PERMISSIONS), {
+            minItems: 1,
+            maxItems: DH_GRANT_PERMISSIONS.length,
+            uniqueItems: true,
+        }),
+    });
+}
+function tokenResponseSchema() {
+    return strict({
+        access_token: opaqueToken,
+        token_type: Type.Literal("Bearer"),
+        expires_in: Type.Integer({ minimum: 1, maximum: DH_TOKEN_MAX_EXPIRES_IN_SECONDS }),
+        refresh_token: opaqueToken,
+        grant_scope: grantScopeSchema(),
+    });
+}
+export const parseDhTokenResponse = dtoParser("trace token response", tokenResponseSchema);
+/** OAuth errors have no reflecting error_description or non-OAuth fields. */
+export const parseDhTokenError = dtoParser("trace token error", () => strict({
+    error: Type.Enum([
+        "invalid_grant",
+        "invalid_request",
+        "invalid_client",
+        "unauthorized_client",
+        "unsupported_grant_type",
+        "invalid_scope",
+        "server_error",
+        "temporarily_unavailable",
+    ]),
+}));
+/** Decodes a form body; rejects duplicates except the explicitly repeatable keys, which always become arrays. */
+function parseForm(label, input, repeatable = new Set()) {
+    if (typeof input === "string" && input.length > 8192)
+        throw new DhContractError("too_large", `Invalid ${label}: too large`);
+    if (typeof input !== "string" && !(input instanceof URLSearchParams))
+        throw new DhContractError("schema_invalid", `Invalid ${label}`);
+    const params = typeof input === "string" ? new URLSearchParams(input) : input;
+    const out = Object.create(null);
+    for (const [key, value] of params) {
+        if (FORBIDDEN_KEYS.has(key))
+            throw new DhContractError("schema_invalid", `Invalid ${label}: forbidden key`);
+        const existing = out[key];
+        if (existing === undefined)
+            out[key] = repeatable.has(key) ? [value] : value;
+        else if (Array.isArray(existing) && repeatable.has(key))
+            existing.push(value);
+        else
+            throw new DhContractError("schema_invalid", `Invalid ${label}: duplicate form parameter`);
+    }
+    return out;
+}
+function assertLoopback(value) {
+    new URL(value); // Throws for ports above 65535; the pattern already pins scheme, host and no query/fragment.
+}
+const redirectUriSchema = () => Type.String({ maxLength: 512, pattern: LOOPBACK_REDIRECT });
+function tokenRequestSchema() {
+    return Type.Union([
+        strict({
+            grant_type: Type.Literal("authorization_code"),
+            client_id: clientIdSchema,
+            code: Type.String({ minLength: 8, maxLength: 512, pattern: "^[\\x21-\\x7e]+$" }),
+            code_verifier: Type.String({ minLength: 43, maxLength: 128, pattern: "^[A-Za-z0-9._~-]+$" }),
+            redirect_uri: redirectUriSchema(),
+        }),
+        strict({ grant_type: Type.Literal("refresh_token"), client_id: clientIdSchema, refresh_token: opaqueToken }),
+    ]);
+}
+const parseTokenRequestRecord = dtoParser("trace token request", tokenRequestSchema, (value) => {
+    if (value.grant_type === "authorization_code")
+        assertLoopback(value.redirect_uri);
+});
+export const parseDhTokenRequest = (input) => parseTokenRequestRecord(parseForm("trace token request", input));
+function revokeRequestSchema() {
+    return strict({ client_id: clientIdSchema, token: opaqueToken, token_type_hint: Type.Literal("refresh_token") });
+}
+const parseRevokeRecord = dtoParser("trace revoke request", revokeRequestSchema);
+export const parseDhRevokeRequest = (input) => parseRevokeRecord(parseForm("trace revoke request", input));
+function authorizeQuerySchema() {
+    return strict({
+        response_type: Type.Literal("code"),
+        client_id: clientIdSchema,
+        redirect_uri: redirectUriSchema(),
+        state: Type.String({ minLength: 16, maxLength: 256, pattern: "^[A-Za-z0-9._~-]+$" }),
+        code_challenge: Type.String({ pattern: "^[A-Za-z0-9_-]{43}$" }),
+        code_challenge_method: Type.Literal("S256"),
+        environment_id: scopeId,
+        project_id: Type.Array(scopeId, { minItems: 1, maxItems: DH_GRANT_MAX_PROJECTS, uniqueItems: true }),
+        permission: Type.Array(Type.Enum(DH_GRANT_PERMISSIONS), {
+            minItems: 1,
+            maxItems: DH_GRANT_PERMISSIONS.length,
+            uniqueItems: true,
+        }),
+    });
+}
+const parseAuthorizeRecord = dtoParser("trace authorize query", authorizeQuerySchema, (value) => assertLoopback(value.redirect_uri));
+export const parseDhAuthorizeQuery = (input) => parseAuthorizeRecord(parseForm("trace authorize query", input, new Set(["project_id", "permission"])));
+const producerSummary = () => strict({
+    issuer: Type.Enum(DH_ISSUERS),
+    version: Type.String({ minLength: 1, maxLength: 256, pattern: "^[\\x20-\\x7e]+$" }),
+    mode: Type.String({ minLength: 1, maxLength: 256, pattern: "^[\\x20-\\x7e]+$" }),
+});
+function producerEnrollmentRequestSchema() {
+    return strict({
+        schema: Type.Literal(DH_HTTP_SCHEMA_IDS.producerEnrollmentRequest),
+        bindingId: prefixed("bnd"),
+        producerInstanceId: prefixed("prd"),
+        generationId: DhGenerationIdSchema,
+        originStreamId: streamIdSchema,
+        producer: producerSummary(),
+    });
+}
+/** Workload proof travels in the authentication header, never the body; a reviewer grant is never producer proof. */
+export const parseDhProducerEnrollmentRequest = dtoParser("producer enrollment request", producerEnrollmentRequestSchema);
+function producerEnrollmentSchema() {
+    return strict({
+        schema: Type.Literal(DH_HTTP_SCHEMA_IDS.producerEnrollment),
+        enrollmentId: enrollmentIdSchema(),
+        tenantScope: DhTenantScopeSchema,
+        generationId: DhGenerationIdSchema,
+        originStreamId: streamIdSchema,
+        issuer: Type.Enum(DH_ISSUERS),
+        credentialVersion: positive,
+        bindingId: prefixed("bnd"),
+        producerInstanceId: prefixed("prd"),
+        allowedOriginIssuers: Type.Array(Type.Enum(DH_ISSUERS), { minItems: 1, maxItems: 3, uniqueItems: true }),
+    });
+}
+export const parseDhProducerEnrollment = dtoParser("producer enrollment", producerEnrollmentSchema);
+export const parseDhProducerTokenRequest = dtoParser("producer token request", () => strict({ enrollmentId: enrollmentIdSchema() }));
+export const parseDhProducerRevokeRequest = dtoParser("producer revoke request", () => strict({ enrollmentId: enrollmentIdSchema() }));
+function producerAudienceSchema() {
+    return strict({
+        environmentId: scopeId,
+        projectId: scopeId,
+        generationId: DhGenerationIdSchema,
+        originStreamId: streamIdSchema,
+        issuer: Type.Enum(DH_ISSUERS),
+        enrollmentId: enrollmentIdSchema(),
+        credentialVersion: positive,
+        bindingId: prefixed("bnd"),
+        producerInstanceId: prefixed("prd"),
+        allowedOriginIssuers: Type.Array(Type.Enum(DH_ISSUERS), { minItems: 1, maxItems: 3, uniqueItems: true }),
+    });
+}
+/** No refresh_token and no grant_scope: a producer credential cannot be refreshed into, or mistaken for, a read grant. */
+export const parseDhProducerTokenResponse = dtoParser("producer token response", () => strict({
+    access_token: opaqueToken,
+    token_type: Type.Literal("Bearer"),
+    expires_in: Type.Integer({ minimum: 1, maximum: DH_TOKEN_MAX_EXPIRES_IN_SECONDS }),
+    audience: producerAudienceSchema(),
+}));
+/**
+ * A producer credential is bound to one environment/project/generation/origin stream AND to its issuer,
+ * enrollment and credential version, so a credential from a superseded or other enrollment never passes.
+ */
+export function assertDhProducerAudience(audience, expected) {
+    assertDhPlainData(audience);
+    assertDhPlainData(expected);
+    for (const key of [
+        "environmentId",
+        "projectId",
+        "generationId",
+        "originStreamId",
+        "issuer",
+        "enrollmentId",
+        "credentialVersion",
+        "bindingId",
+        "producerInstanceId",
+    ]) {
+        if (audience[key] !== expected[key])
+            throw new DhContractError("producer_revoked", `Producer credential audience mismatch: ${key}`);
+    }
+    if (canonicalText(audience.allowedOriginIssuers) !== canonicalText(expected.allowedOriginIssuers))
+        throw new DhContractError("producer_revoked", "Producer credential audience mismatch: allowedOriginIssuers");
+}
+// ---------------------------------------------------------------------------
+// Local workload descriptors and delegated origins (no secret DTO fields)
+// ---------------------------------------------------------------------------
+export const parseDhWorkloadBinding = dtoParser("workload binding", () => strict({
+    schema: Type.Literal(DH_HTTP_SCHEMA_IDS.workloadBinding),
+    workloadId: prefixed("wld"),
+    bindingId: prefixed("bnd"),
+    producerInstanceId: prefixed("prd"),
+    launchNonce: refSchema,
+    issuer: Type.Enum(DH_ISSUERS),
+    buildSha256: digest,
+    mode: refSchema,
+    credentialVersion: positive,
+    expiresAt: timestamp,
+}));
+export const parseDhOriginDelegation = dtoParser("origin delegation", () => strict({
+    schema: Type.Literal(DH_HTTP_SCHEMA_IDS.originDelegation),
+    delegationId: prefixed("dlg"),
+    bindingId: prefixed("bnd"),
+    originProducerInstanceId: prefixed("prd"),
+    originStreamId: streamIdSchema,
+    originIssuer: Type.Enum(DH_ISSUERS),
+    relayProducerInstanceId: prefixed("prd"),
+    enrollmentId: enrollmentIdSchema(),
+    credentialVersion: positive,
+    expiresAt: timestamp,
+}));
+/** Compare to a live server-issued receipt. A syntactically valid receipt grants nothing by itself. */
+export function assertDhOriginDelegation(delegationInput, expected) {
+    const delegation = parseDhOriginDelegation(delegationInput);
+    if (expected === null || expected === undefined)
+        throw new DhContractError("origin_not_delegated");
+    if (canonicalText(delegation) !== canonicalText(parseDhOriginDelegation(expected)))
+        throw new DhContractError("origin_not_delegated");
+}
+/** Exactly 32 bytes in canonical unpadded base64url; caller handles private custody and live verification. */
+export function parseDhWorkloadAuthorizationHeader(value) {
+    if (typeof value !== "string" || !/^DH-Workload [A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$/.test(value))
+        throw new DhContractError("workload_proof_invalid");
+    return value.slice("DH-Workload ".length);
+}
+export function parseDhOriginDelegationHeader(value) {
+    if (typeof value !== "string" || !/^dlg_[A-Za-z0-9_-]{8,128}$/.test(value))
+        throw new DhContractError("origin_not_delegated");
+    return value;
+}
+// ---------------------------------------------------------------------------
+// Snapshot paging: event metadata/content pages, artifact metadata, cursor binding
+// ---------------------------------------------------------------------------
+function eventMetadataViewSchema() {
+    return strict({
+        eventId: DhEventIdSchema,
+        generationId: DhGenerationIdSchema,
+        agentId: DhAgentIdSchema,
+        parentAgentId: Type.Optional(DhAgentIdSchema),
+        attemptId: Type.Optional(DhAttemptIdSchema),
+        retryOfAttemptId: Type.Optional(DhAttemptIdSchema),
+        attemptNumber: Type.Optional(positive),
+        streamId: streamIdSchema,
+        sequence: count,
+        kind: Type.Enum(DH_EVENT_KINDS),
+        occurredAt: timestamp,
+        recordedAt: timestamp,
+        outcome: Type.Optional(Type.Enum(DH_OUTCOMES)),
+        /** The failure code only. Raw failure messages are content. */
+        failureCode: Type.Optional(Type.String({ pattern: "^[a-z][a-z0-9_.-]{0,63}$", maxLength: 64 })),
+        coverage: Type.Array(strict({
+            path: Type.String({ minLength: 1, maxLength: 256 }),
+            state: Type.Enum(DH_COVERAGE_STATES),
+            reason: Type.Optional(Type.Enum(DH_COVERAGE_REASONS)),
+        }), { maxItems: 64 }),
+        artifactIds: Type.Array(DhArtifactIdSchema, { maxItems: 32, uniqueItems: true }),
+    });
+}
+function assertEventMetadataView(view) {
+    const paths = view.coverage.map((entry) => entry.path);
+    assertUnique("event metadata coverage", paths);
+    for (const entry of view.coverage) {
+        if (!FIELD_PATH.test(entry.path) || entry.path.split(".").some((segment) => FORBIDDEN_KEYS.has(segment))) {
+            throw new Error("Invalid event metadata coverage: path is not a valid field path");
+        }
+        assertCoverageReason("event metadata coverage", entry);
+    }
+}
+export const parseDhEventMetadataView = dtoParser("event metadata view", eventMetadataViewSchema, assertEventMetadataView);
+function pageSchema(included, item) {
+    return strict({
+        schema: Type.Literal(DH_HTTP_SCHEMA_IDS.eventPage),
+        cursorBinding: dhCursorBindingSchema(),
+        nextCursor: nextCursorSchema,
+        captureCutoff: timestamp,
+        contentIncluded: included,
+        items: Type.Array(item, { maxItems: 100 }),
+    });
+}
+const parseEventMetadataPage = dtoParser("event metadata page", () => pageSchema(Type.Literal(false), eventMetadataViewSchema()), (page) => {
+    assertDhReadPageBinding(page, "events", "metadata");
+    for (const item of page.items)
+        assertEventMetadataView(item);
+    assertUnique("event metadata page", page.items.map((item) => item.eventId));
+});
+const parseEventContentEnvelope = dtoParser("event content page", () => pageSchema(Type.Literal(true), Type.Unknown()), (page) => assertDhReadPageBinding(page, "events", "content"));
+/** The metadata view never carries payload, raw failure messages, coverage detail or redaction paths; content pages are full dh.event/1. */
+export function parseDhEventPage(value) {
+    assertDhPlainData(value);
+    if (isRecord(value) && value.contentIncluded === true) {
+        const envelope = parseEventContentEnvelope(value);
+        const items = Array.from(envelope.items, parseDhEvent);
+        assertUnique("event content page", items.map((item) => item.eventId));
+        assertDhReadPageBinding({ ...envelope, items }, "events", "content");
+        return deepFreeze({
+            schema: envelope.schema,
+            cursorBinding: envelope.cursorBinding,
+            nextCursor: envelope.nextCursor,
+            captureCutoff: envelope.captureCutoff,
+            contentIncluded: true,
+            items,
+        });
+    }
+    return parseEventMetadataPage(value);
+}
+export const DH_ARTIFACT_AVAILABILITY = ["available", "pending", "unavailable"];
+function artifactMetadataViewSchema() {
+    return strict({
+        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,
+        /** available = bytes stored; pending = metadata acknowledged, bytes not yet; unavailable = never readable (lost, withheld or purged). */
+        availability: Type.Enum(DH_ARTIFACT_AVAILABILITY),
+        coverage: metadataCoverage(),
+    });
+}
+/** Excludes logicalPath (sensitive file names), redaction paths and coverage.detail. Bytes are a separate route and grant. */
+export const parseDhArtifactMetadataView = dtoParser("artifact metadata view", artifactMetadataViewSchema, (view) => assertCoverageReason("artifact metadata view", view.coverage));
+export const DH_CURSOR_RESOURCES = ["generations", "agents", "events", "manifest"];
+function snapshotCutoffSchema() {
+    return strict({
+        schema: Type.Literal(DH_HTTP_SCHEMA_IDS.snapshotCutoff),
+        snapshotId: prefixed("snp"),
+        receiptOrdinal: count,
+        captureCutoff: timestamp,
+    });
+}
+export const parseDhSnapshotCutoff = dtoParser("snapshot cutoff", snapshotCutoffSchema);
+/** Internal lazy schema seam shared by existing read-page parsers. */
+export function dhCursorBindingSchema() {
+    return strict({
+        schema: Type.Literal(DH_HTTP_SCHEMA_IDS.cursorBinding),
+        environmentId: scopeId,
+        projectId: scopeId,
+        resource: Type.Enum(DH_CURSOR_RESOURCES),
+        generationId: Type.Optional(DhGenerationIdSchema),
+        bindingId: Type.Optional(prefixed("bnd")),
+        filterSha256: digest,
+        view: Type.Union([Type.Literal("metadata"), Type.Literal("content")]),
+        cutoff: snapshotCutoffSchema(),
+        mappingRevision: digest,
+        authorizationRevision: refSchema,
+        principalId: scopeId,
+        grantId: scopeId,
+        sessionId: scopeId,
+        pageSize: Type.Integer({ minimum: 1, maximum: 1000 }),
+    });
+}
+/** What an opaque cursor is authenticated against (server-side); clients compare it across continuation pages. */
+export const parseDhCursorBinding = dtoParser("cursor binding", dhCursorBindingSchema, (binding) => {
+    const projectList = binding.resource === "generations";
+    if (projectList
+        ? binding.generationId !== undefined || binding.bindingId !== undefined
+        : binding.generationId === undefined || binding.bindingId === undefined)
+        throw new DhContractError("schema_invalid");
+    if (binding.resource !== "manifest" && binding.pageSize > 100)
+        throw new DhContractError("schema_invalid");
+});
+export function assertDhReadPageBinding(page, resource, view = "metadata") {
+    const binding = parseDhCursorBinding(page.cursorBinding);
+    if (binding.resource !== resource ||
+        binding.view !== view ||
+        binding.cutoff.captureCutoff !== page.captureCutoff ||
+        page.items.length > binding.pageSize)
+        throw new DhContractError("cursor_binding_mismatch");
+    for (const item of page.items) {
+        if (!isRecord(item))
+            continue;
+        if (resource !== "generations" && item.generationId !== binding.generationId)
+            throw new DhContractError("cursor_binding_mismatch");
+        if (isRecord(item.tenantScope) &&
+            (item.tenantScope.environmentId !== binding.environmentId || item.tenantScope.projectId !== binding.projectId))
+            throw new DhContractError("cursor_binding_mismatch");
+    }
+}
+/** Pure supplied-context checks; opaque storage and authentication remain server responsibilities. */
+export function assertDhCursorContext(context) {
+    assertDhPlainData(context);
+    if (!isCalendarInstant(context.now) || !isCalendarInstant(context.expiresAt))
+        throw new DhContractError("schema_invalid");
+    if (!context.registered)
+        throw new DhContractError("cursor_invalid");
+    if (Date.parse(context.now) >= Date.parse(context.expiresAt))
+        throw new DhContractError("cursor_expired");
+}
+export function assertDhCursorProgress(previous, next, seen = new Set()) {
+    if (next !== null &&
+        (typeof next !== "string" || !/^[\x21-\x7e]{1,1024}$/.test(next) || next === previous || seen.has(next)))
+        throw new DhContractError("cursor_invalid");
+}
+/** Every field, including the cutoff and view, must be identical across pages of one snapshot. */
+export function assertDhCursorBinding(expected, actual) {
+    const a = parseDhCursorBinding(expected);
+    const b = parseDhCursorBinding(actual);
+    for (const key of ["principalId", "grantId", "sessionId", "authorizationRevision"])
+        if (a[key] !== b[key])
+            throw new DhContractError("authorization_changed");
+    if (canonicalText(a) !== canonicalText(b))
+        throw new DhContractError("cursor_binding_mismatch");
+}
+// ---------------------------------------------------------------------------
+// Exports: create request, job status, sharded manifest
+// ---------------------------------------------------------------------------
+export const parseDhExportCreateRequest = dtoParser("export create request", () => strict({ includeContent: Type.Boolean(), acknowledgeNonRevocable: Type.Literal(true) }));
+/** GET exports/{jobId}. `DhExportJob` (jobId+state) stays the POST 202 handle. */
+export const parseDhExportJobStatus = dtoParser("export job status", () => strict({
+    jobId: jobIdSchema,
+    generationId: DhGenerationIdSchema,
+    state: Type.Enum(DH_EXPORT_STATES),
+    contentIncluded: Type.Boolean(),
+    captureCutoff: Type.Optional(timestamp),
+}));
+function exportContextSchema() {
+    return {
+        jobId: jobIdSchema,
+        generationId: DhGenerationIdSchema,
+        tenantScope: DhTenantScopeSchema,
+        bindingId: prefixed("bnd"),
+        cutoff: snapshotCutoffSchema(),
+        captureCutoff: timestamp,
+        contentIncluded: Type.Boolean(),
+        policyRevision: refSchema,
+    };
+}
+function exportManifestHeaderSchema() {
+    return strict({
+        schema: Type.Literal(DH_HTTP_SCHEMA_IDS.exportManifestHeader),
+        ...exportContextSchema(),
+        canonicalProfile: Type.Literal("dh.canonical-jcs/1"),
+        state: Type.Literal("sealed"),
+        eventCount: count,
+        artifactCount: count,
+        streamCount: count,
+        omittedArtifactCount: count,
+        shardCount: Type.Integer({ minimum: 0, maximum: 1024 }),
+        shards: Type.Array(strict({
+            index: Type.Integer({ minimum: 0, maximum: 1023 }),
+            recordCount: Type.Integer({ minimum: 1, maximum: 1000 }),
+            sha256: digest,
+        }), { maxItems: 1024 }),
+        manifestSha256: digest,
+        coverage: metadataCoverage(),
+    });
+}
+function assertManifestSize(value) {
+    assertDhPlainData(value);
+    if (isRecord(value) &&
+        ((typeof value.shardCount === "number" && value.shardCount > 1024) ||
+            (Array.isArray(value.shards) && value.shards.length > 1024) ||
+            (Array.isArray(value.entries) && value.entries.length > 1000)))
+        throw new DhContractError("too_large");
+    if (new TextEncoder().encode(canonicalText(value)).length > 1048576)
+        throw new DhContractError("too_large");
+}
+const parseManifestHeader = dtoParser("export manifest header", exportManifestHeaderSchema, (header) => {
+    const total = header.eventCount + header.artifactCount + header.streamCount;
+    if (!Number.isSafeInteger(total) ||
+        header.shards.length !== header.shardCount ||
+        header.shards.some((shard, index) => shard.index !== index) ||
+        total !== header.shards.reduce((sum, shard) => sum + shard.recordCount, 0) ||
+        header.omittedArtifactCount > header.artifactCount ||
+        header.captureCutoff !== header.cutoff.captureCutoff)
+        throw new DhContractError("manifest_invalid");
+    assertCoverageReason("export manifest header", header.coverage);
+});
+export function parseDhExportManifestHeader(value) {
+    assertManifestSize(value);
+    return parseManifestHeader(value);
+}
+function manifestEntrySchema() {
+    const owner = { bindingId: prefixed("bnd"), originProducerInstanceId: prefixed("prd") };
+    const record = {
+        ...owner,
+        originStreamId: streamIdSchema,
+        representation: Type.Enum(["metadata", "content"]),
+        recordSha256: digest,
+    };
+    return Type.Union([
+        strict({ kind: Type.Literal("event"), id: DhEventIdSchema, ...record }),
+        strict({
+            kind: Type.Literal("artifact"),
+            id: DhArtifactIdSchema,
+            ...record,
+            sha256: digest,
+            sizeBytes: Type.Integer({ minimum: 0, maximum: 67108864 }),
+            bytes: Type.Enum(["included", "omitted", "unavailable"]),
+            reason: Type.Optional(Type.Enum(["policy_redacted", "producer_lost", "size_limit", "not_captured_by_version"])),
+        }),
+        strict({
+            kind: Type.Literal("stream"),
+            id: streamIdSchema,
+            ...owner,
+            prefixThroughSequence: Type.Integer({ minimum: -1, maximum: Number.MAX_SAFE_INTEGER }),
+            state: Type.Enum(["open", "closed", "lost", "disputed"]),
+        }),
+    ]);
+}
+function exportManifestPageSchema() {
+    return strict({
+        schema: Type.Literal(DH_HTTP_SCHEMA_IDS.exportManifestPage),
+        ...exportContextSchema(),
+        shardIndex: Type.Integer({ minimum: 0, maximum: 1023 }),
+        sha256: digest,
+        entries: Type.Array(manifestEntrySchema(), { minItems: 1, maxItems: 1000 }),
+        nextCursor: nextCursorSchema,
+    });
+}
+const parseManifestPage = dtoParser("export manifest page", exportManifestPageSchema, (page) => {
+    if (page.captureCutoff !== page.cutoff.captureCutoff)
+        throw new DhContractError("manifest_integrity");
+    let previous = "";
+    for (const entry of page.entries) {
+        const key = `${entry.kind}\0${entry.id}`;
+        if (key <= previous)
+            throw new DhContractError("manifest_invalid");
+        previous = key;
+        if (entry.kind !== "stream" && entry.representation !== (page.contentIncluded ? "content" : "metadata"))
+            throw new DhContractError("manifest_invalid");
+        if (entry.kind === "artifact" &&
+            ((entry.bytes === "included") !== (entry.reason === undefined) ||
+                (!page.contentIncluded && entry.bytes === "included")))
+            throw new DhContractError("manifest_invalid");
+    }
+});
+export function parseDhExportManifestPage(value) {
+    assertManifestSize(value);
+    return parseManifestPage(value);
+}
+/** Navigation is outside the immutable sealed header. */
+export const parseDhExportManifestResponse = dtoParser("export manifest response", () => strict({
+    header: exportManifestHeaderSchema(),
+    firstShardCursor: nextCursorSchema,
+    cursorBinding: dhCursorBindingSchema(),
+}), (response) => {
+    const header = parseDhExportManifestHeader(response.header), binding = parseDhCursorBinding(response.cursorBinding);
+    if ((header.shardCount === 0) !== (response.firstShardCursor === null))
+        throw new DhContractError("manifest_invalid");
+    if (binding.resource !== "manifest" ||
+        binding.generationId !== header.generationId ||
+        binding.bindingId !== header.bindingId ||
+        binding.environmentId !== header.tenantScope.environmentId ||
+        binding.projectId !== header.tenantScope.projectId ||
+        binding.view !== (header.contentIncluded ? "content" : "metadata") ||
+        canonicalText(binding.cutoff) !== canonicalText(header.cutoff))
+        throw new DhContractError("manifest_integrity");
+});
+/** JCS shard body; hash its domain-separated bytes, never navigation cursors. */
+export function dhManifestShardCanonicalText(page) {
+    const { sha256: _hash, nextCursor: _cursor, ...body } = parseDhExportManifestPage(page);
+    return canonicalText(body);
+}
+/** Convenience over the same bounded incremental algorithm. */
+export function validateDhExportManifest(headerInput, pageInputs, options) {
+    const state = beginDhExportManifest(headerInput, options);
+    if (pageInputs.length !== state.header.shardCount)
+        throw new DhContractError("manifest_invalid");
+    const pages = Array.from(pageInputs, (page) => acceptDhExportManifestPage(state, page));
+    return { header: finishDhExportManifest(state), pages };
+}
+// ---------------------------------------------------------------------------
+// Controls
+// ---------------------------------------------------------------------------
+export const DH_CONTROL_ACTIONS = ["cancel", "retry", "continue"];
+/** Acceptance, delivery and application are not termination: terminationConfirmed is a separate observation. */
+export const DH_CONTROL_STATES = [
+    "requested",
+    "accepted",
+    "delivered",
+    "applied",
+    "rejected",
+    "unsupported",
+    "unknown",
+];
+export const DH_CONTROL_REJECT_REASONS = [
+    "not_authorized",
+    "scope_mismatch",
+    "stale_epoch",
+    "target_settled",
+    "not_eligible",
+    "policy_denied",
+    "budget_exhausted",
+    "workspace_unavailable",
+];
+const controlRoutes = { controlCancel: "cancel", controlRetry: "retry", controlContinue: "continue" };
+function controlRequestSchema() {
+    const fenced = (action, payload) => strict({
+        schema: Type.Literal(DH_HTTP_SCHEMA_IDS.controlRequest),
+        requestId: requestIdSchema(),
+        idempotencyKey: Type.String({ pattern: "^[A-Za-z0-9_-]{16,128}$" }),
+        generationId: DhGenerationIdSchema,
+        agentId: DhAgentIdSchema,
+        attemptId: DhAttemptIdSchema,
+        bindingId: prefixed("bnd"),
+        bindingEpoch: refSchema,
+        sessionEpoch: refSchema,
+        capabilityRevision: digest,
+        action: Type.Literal(action),
+        payload,
+    });
+    return Type.Union([
+        fenced("cancel", strict({ scope: Type.Union([Type.Literal("selected"), Type.Literal("whole-run")]) })),
+        fenced("retry", strict({
+            sourceAttemptId: DhAttemptIdSchema,
+            /** new-attempt: same agent, new att_ (Flow/CLI worker). new-agent: new agent + cross-agent relation (Code native retry). */
+            relation: Type.Union([Type.Literal("new-attempt"), Type.Literal("new-agent")]),
+            /** Literal on purpose: a retry cannot drop model/context/workspace policy or reset cumulative spend. */
+            policy: strict({
+                model: Type.Literal("retain"),
+                context: Type.Literal("retain"),
+                workspace: Type.Literal("retain"),
+                spend: Type.Literal("cumulative"),
+            }),
+        })),
+        fenced("continue", strict({ message: Type.String({ minLength: 1, maxLength: DH_CONTROL_MESSAGE_MAX_CHARS }) })),
+    ]);
+}
+export const parseDhControlRequest = dtoParser("control request", controlRequestSchema, (request) => {
+    if (new TextEncoder().encode(canonicalText(request)).length > 65536)
+        throw new DhContractError("too_large");
+    if (request.action === "retry" && request.payload.sourceAttemptId !== request.attemptId)
+        throw new DhContractError("schema_invalid");
+});
+function expectAction(value, action) {
+    const request = parseDhControlRequest(value);
+    if (request.action !== action)
+        throw new Error(`Expected a ${action} control request`);
+    return request;
+}
+export const parseDhCancelRequest = (value) => expectAction(value, "cancel");
+export const parseDhRetryRequest = (value) => expectAction(value, "retry");
+export const parseDhContinueRequest = (value) => expectAction(value, "continue");
+/** A different generation/agent is a scope error; a replaced attempt or binding epoch is stale. Never apply a stale fence. */
+export function checkDhControlFence(request, live) {
+    assertDhPlainData(request);
+    assertDhPlainData(live);
+    if (request.generationId !== live.generationId || request.agentId !== live.agentId)
+        return "scope_mismatch";
+    if (request.attemptId !== live.attemptId ||
+        request.bindingId !== live.bindingId ||
+        request.bindingEpoch !== live.bindingEpoch ||
+        request.sessionEpoch !== live.sessionEpoch)
+        return "stale_epoch";
+    if (request.capabilityRevision !== live.capabilityRevision)
+        return "policy_denied";
+    return "ok";
+}
+/** The POST body must match the action-specific route and the path's generation/agent. */
+export function assertDhControlRequestForRoute(id, params, request) {
+    const action = Object.hasOwn(controlRoutes, id) ? controlRoutes[id] : undefined;
+    if (action === undefined)
+        throw new DhContractError("schema_invalid", "Route is not a control action route");
+    buildDhRoutePath(id, params);
+    const parsed = expectAction(request, action);
+    if (parsed.generationId !== params.generationId || parsed.agentId !== params.agentId) {
+        throw new Error("Control request does not match the route generation or agent");
+    }
+    return parsed;
+}
+/**
+ * Idempotency: entries with the same actor, environment/project, generation, agent, action and key are
+ * one request. Then a byte-equal canonical body (request id, attempt, epoch, payload) is a replay (`same`);
+ * anything else under that key is a `conflict` (HTTP 409, no second effect). Other keys/actors/scopes/targets are `distinct`.
+ */
+export function compareDhControlReplay(stored, incoming) {
+    assertDhPlainData(stored);
+    assertDhPlainData(incoming);
+    if (![
+        stored.actor,
+        incoming.actor,
+        stored.authorityId,
+        incoming.authorityId,
+        stored.tenantId,
+        incoming.tenantId,
+    ].every((value) => typeof value === "string" && new RegExp(SCOPE_ID).test(value)))
+        throw new DhContractError("schema_invalid");
+    const a = parseDhControlRequest(stored.request);
+    const b = parseDhControlRequest(incoming.request);
+    const lookup = (entry, request) => canonicalText([
+        entry.actor,
+        entry.authorityId,
+        entry.tenantId,
+        entry.scope.environmentId,
+        entry.scope.projectId,
+        request.generationId,
+        request.agentId,
+        request.action,
+        request.idempotencyKey,
+    ]);
+    if (lookup(stored, a) !== lookup(incoming, b))
+        return "distinct";
+    return canonicalText(a) === canonicalText(b) ? "same" : "conflict";
+}
+function assertRejectedReason(label, value) {
+    if ((value.state === "rejected") !== (value.reason !== undefined)) {
+        throw new Error(`Invalid ${label}: a reason is required for, and only for, state rejected`);
+    }
+}
+const controlStateSchema = () => Type.Enum(DH_CONTROL_STATES);
+const controlActionSchema = () => Type.Enum(DH_CONTROL_ACTIONS);
+const rejectReasonSchema = () => Type.Enum(DH_CONTROL_REJECT_REASONS);
+/** POST response: a correlated handle, not an effect. */
+export const parseDhControlReceipt = dtoParser("control receipt", () => strict({
+    schema: Type.Literal(DH_HTTP_SCHEMA_IDS.controlReceipt),
+    requestId: requestIdSchema(),
+    action: controlActionSchema(),
+    state: controlStateSchema(),
+    reason: Type.Optional(rejectReasonSchema()),
+}), (receipt) => assertRejectedReason("control receipt", receipt));
+export const parseDhControlRequestStatus = dtoParser("control request status", () => strict({
+    schema: Type.Literal(DH_HTTP_SCHEMA_IDS.controlStatus),
+    requestId: requestIdSchema(),
+    action: controlActionSchema(),
+    generationId: DhGenerationIdSchema,
+    agentId: DhAgentIdSchema,
+    attemptId: DhAttemptIdSchema,
+    bindingId: prefixed("bnd"),
+    bindingEpoch: refSchema,
+    sessionEpoch: refSchema,
+    capabilityRevision: digest,
+    requestSha256: digest,
+    state: controlStateSchema(),
+    reason: Type.Optional(rejectReasonSchema()),
+    /** Cancel only: an observed fact, independent of `state`. Only an applied cancel can confirm it. */
+    terminationConfirmed: Type.Optional(Type.Boolean()),
+    observed: Type.Optional(strict({
+        startedAgentId: Type.Optional(DhAgentIdSchema),
+        startedAttemptId: Type.Optional(DhAttemptIdSchema),
+        consumedByEventId: Type.Optional(DhEventIdSchema),
+    })),
+    updatedAt: timestamp,
+}), (status) => {
+    assertRejectedReason("control request status", status);
+    if (status.action === "cancel") {
+        if (status.terminationConfirmed === undefined) {
+            throw new Error("Invalid control request status: cancel requires terminationConfirmed");
+        }
+        if (status.terminationConfirmed && status.state !== "applied") {
+            throw new Error("Invalid control request status: termination can only be confirmed after an applied cancel");
+        }
+    }
+    else if (status.terminationConfirmed !== undefined) {
+        throw new Error("Invalid control request status: terminationConfirmed applies to cancel only");
+    }
+    const observed = status.observed;
+    if (status.state === "applied" &&
+        ((status.action === "retry" &&
+            (observed?.startedAgentId === undefined || observed.startedAttemptId === undefined)) ||
+            (status.action === "continue" && observed?.consumedByEventId === undefined)))
+        throw new DhContractError("schema_invalid");
+    if (observed === undefined)
+        return;
+    const keys = Object.keys(observed);
+    const allowed = status.action === "retry"
+        ? ["startedAgentId", "startedAttemptId"]
+        : status.action === "continue"
+            ? ["consumedByEventId"]
+            : [];
+    if (status.state !== "applied" || keys.length === 0 || keys.some((key) => !allowed.includes(key))) {
+        throw new Error("Invalid control request status: observed outcome does not fit the action or state");
+    }
+});
+function controlTargetProperties() {
+    return {
+        generationId: DhGenerationIdSchema,
+        agentId: DhAgentIdSchema,
+        attemptId: DhAttemptIdSchema,
+        bindingId: prefixed("bnd"),
+        bindingEpoch: refSchema,
+        sessionEpoch: refSchema,
+        capabilityRevision: digest,
+    };
+}
+export const parseDhControlTarget = dtoParser("control target", () => strict({
+    schema: Type.Literal(DH_HTTP_SCHEMA_IDS.controlTarget),
+    ...controlTargetProperties(),
+    updatedAt: timestamp,
+}));
+export const parseDhControlHandshake = dtoParser("control handshake", () => strict({
+    schema: Type.Literal(DH_HTTP_SCHEMA_IDS.controlHandshake),
+    bindingId: prefixed("bnd"),
+    sessionEpoch: refSchema,
+    token: Type.String({ pattern: "^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$" }),
+}));
+export const parseDhControlDelivery = dtoParser("control delivery", () => strict({
+    schema: Type.Literal(DH_HTTP_SCHEMA_IDS.controlDelivery),
+    request: controlRequestSchema(),
+    tenantScope: DhTenantScopeSchema,
+    actorId: scopeId,
+    authorityId: scopeId,
+    authorizationRevision: refSchema,
+    authorizedAt: timestamp,
+    expiresAt: timestamp,
+    requestSha256: digest,
+}), (delivery) => {
+    parseDhControlRequest(delivery.request);
+    const lifetime = Date.parse(delivery.expiresAt) - Date.parse(delivery.authorizedAt);
+    if (lifetime <= 0 || lifetime > 30000)
+        throw new DhContractError("schema_invalid");
+});
+export function assertDhControlDelivery(input, context, options) {
+    const delivery = parseDhControlDelivery(input);
+    assertDhPlainData(context);
+    if (!isCalendarInstant(context.now))
+        throw new DhContractError("schema_invalid");
+    if (context.authorized !== true ||
+        context.actorId !== delivery.actorId ||
+        context.authorityId !== delivery.authorityId ||
+        context.authorizationRevision !== delivery.authorizationRevision ||
+        Date.parse(context.now) < Date.parse(delivery.authorizedAt) ||
+        Date.parse(context.now) >= Date.parse(delivery.expiresAt))
+        throw new DhContractError("not_authorized");
+    if (canonicalText(context.scope) !== canonicalText(delivery.tenantScope))
+        throw new DhContractError("scope_mismatch");
+    const fence = checkDhControlFence(delivery.request, context.live);
+    if (fence !== "ok")
+        throw new DhContractError(fence);
+    if (typeof options?.sha256Hex !== "function" ||
+        options.sha256Hex(dhDigestInput("dh.control-request/2", delivery.request)) !== delivery.requestSha256)
+        throw new DhContractError("control_integrity");
+}
+/** Non-secret registry descriptor only. The bearer is held privately and never serialized here. */
+export const parseDhControllerCredential = dtoParser("controller credential", () => strict({
+    schema: Type.Literal(DH_HTTP_SCHEMA_IDS.controllerCredential),
+    authorityId: scopeId,
+    actorId: scopeId,
+    bindingId: prefixed("bnd"),
+    targets: Type.Array(strict({ generationId: DhGenerationIdSchema, agentId: DhAgentIdSchema, attemptId: DhAttemptIdSchema }), { minItems: 1, maxItems: 128, uniqueItems: true }),
+    actions: strict({
+        cancelSelected: Type.Boolean(),
+        cancelWholeRun: Type.Boolean(),
+        continueLive: Type.Boolean(),
+        retryFresh: Type.Boolean(),
+    }),
+    statusRead: Type.Boolean(),
+    discoverTarget: Type.Boolean(),
+    sessionVersion: count,
+    credentialVersion: positive,
+    issuedAt: timestamp,
+    expiresAt: timestamp,
+}), (credential) => {
+    const lifetime = Date.parse(credential.expiresAt) - Date.parse(credential.issuedAt);
+    if (lifetime <= 0 || lifetime > 300000)
+        throw new DhContractError("schema_invalid");
+});
+export function assertDhControllerAction(input, targetInput, action, context) {
+    const credential = parseDhControllerCredential(input), target = parseDhControlTarget(targetInput);
+    assertDhPlainData(context);
+    if (!isCalendarInstant(context.now))
+        throw new DhContractError("schema_invalid");
+    if (context.membershipActive !== true ||
+        context.liveVersion !== credential.credentialVersion ||
+        context.sessionVersion !== credential.sessionVersion ||
+        Date.parse(context.now) < Date.parse(credential.issuedAt) ||
+        Date.parse(context.now) >= Date.parse(credential.expiresAt) ||
+        credential.bindingId !== target.bindingId ||
+        credential.actions[action] !== true ||
+        !credential.targets.some((t) => t.generationId === target.generationId && t.agentId === target.agentId && t.attemptId === target.attemptId))
+        throw new DhContractError("not_authorized");
+}
+export function assertDhControlStatusEvidence(input, events) {
+    const status = parseDhControlRequestStatus(input);
+    if (status.state !== "applied" || status.action === "cancel")
+        return;
+    assertDhAppliedControlEvidence(status, status.action, {
+        startedAgentId: status.observed?.startedAgentId,
+        startedAttemptId: status.observed?.startedAttemptId,
+        consumingEventId: status.observed?.consumedByEventId,
+    }, events);
+}
+/** Socket/fd3 message framing only; no I/O or transport authority is implemented. */
+export function parseDhControlFrame(bytes) {
+    if (!(bytes instanceof Uint8Array) || bytes.length < 5)
+        throw new DhContractError("schema_invalid");
+    const length = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getUint32(0, false);
+    if (length > 65536)
+        throw new DhContractError("too_large");
+    if (length !== bytes.length - 4)
+        throw new DhContractError("schema_invalid");
+    const value = parseDhRawJson(bytes.subarray(4), { maxBytes: 65536 });
+    return isRecord(value) && value.schema === DH_HTTP_SCHEMA_IDS.controlHandshake
+        ? parseDhControlHandshake(value)
+        : parseDhControlDelivery(value);
+}
+export function dhControlFrameBytes(input) {
+    assertDhPlainData(input);
+    const value = isRecord(input) && input.schema === DH_HTTP_SCHEMA_IDS.controlHandshake
+        ? parseDhControlHandshake(input)
+        : parseDhControlDelivery(input);
+    const payload = new TextEncoder().encode(canonicalText(value));
+    if (payload.length > 65536)
+        throw new DhContractError("too_large");
+    const bytes = new Uint8Array(4 + payload.length);
+    new DataView(bytes.buffer).setUint32(0, payload.length, false);
+    bytes.set(payload, 4);
+    return bytes;
+}
+// ---------------------------------------------------------------------------
+// ACK semantics
+// ---------------------------------------------------------------------------
+/** POST-local reply context only: never an assertion of the collector's durable prefix. */
+export function parseDhPreviousAckedSequenceHeader(value) {
+    if (typeof value !== "string" || !/^(?:-1|0|[1-9][0-9]*)$/.test(value) || !Number.isSafeInteger(Number(value)))
+        throw new DhContractError("schema_invalid");
+    return Number(value);
+}
+const parseAckSentView = dtoParser("sent ACK view", () => strict({
+    streamId: streamIdSchema,
+    events: Type.Array(strict({ eventId: DhEventIdSchema, sequence: count }), { maxItems: 500 }),
+    artifacts: Type.Array(strict({ artifactId: DhArtifactIdSchema }), { maxItems: 500 }),
+}));
+/** Validate at the transport boundary before invoking the unchanged prefix checker. Full batches are allowed. */
+export function assertDhAckSentBatch(sent) {
+    try {
+        assertDhPlainData(sent);
+        const view = parseAckSentView({
+            streamId: sent.streamId,
+            events: sent.events.map(({ eventId, sequence }) => ({ eventId, sequence })),
+            artifacts: sent.artifacts.map(({ artifactId }) => ({ artifactId })),
+        });
+        if (view.events.length + view.artifacts.length > 500 ||
+            new Set(view.events.map((event) => event.eventId)).size !== view.events.length ||
+            new Set(view.events.map((event) => event.sequence)).size !== view.events.length ||
+            new Set(view.artifacts.map((artifact) => artifact.artifactId)).size !== view.artifacts.length)
+            throw new DhContractError("ack_invalid");
+    }
+    catch {
+        throw new DhContractError("ack_invalid");
+    }
+}
+/** Value of `previousAckedSequence` when no event has been acknowledged yet (the uploader cursor's initial `-1`). */
+export const DH_ACK_NO_PREVIOUS_SEQUENCE = -1;
+/**
+ * Validates a dh.ack/1 against the batch that was actually sent. The ACK must name the same stream and
+ * only sent ids; accepted and rejected are disjoint; accepted events are exactly the first k sent events
+ * by sequence (k may be 0).
+ *
+ * `previousAckedSequence` is REQUIRED: the stream's current acknowledged watermark, or
+ * DH_ACK_NO_PREVIOUS_SEQUENCE (-1) when nothing is acknowledged yet. The accepted prefix must be gap-free
+ * and start at previous + 1, so `[0,10,20]` cannot be acknowledged as one prefix. For k > 0,
+ * ackedThroughSequence is the prefix's last sequence. For k = 0 it must repeat the previous watermark
+ * (0 when previous is -1, because dh.ack/1 cannot carry a negative value and the empty accepted list
+ * disambiguates), so an empty ACK can neither advance nor regress the stream.
+ */
+export function validateDhBatchAck(sent, ackInput, options) {
+    const previous = options?.previousAckedSequence;
+    if (typeof previous !== "number" || !Number.isSafeInteger(previous) || previous < DH_ACK_NO_PREVIOUS_SEQUENCE) {
+        throw new Error("Invalid trace acknowledgement check: previousAckedSequence must be an integer >= -1");
+    }
+    const ack = parseDhIngestAck(ackInput);
+    if (ack.streamId !== sent.streamId)
+        throw new Error("Invalid trace acknowledgement: stream does not match the sent batch");
+    const events = [...sent.events].sort((a, b) => a.sequence - b.sequence);
+    events.forEach((event, index) => {
+        const previous = events[index - 1];
+        if (previous !== undefined && previous.sequence >= event.sequence)
+            throw new Error("Sent batch repeats a sequence");
+    });
+    const sentEvents = new Set(events.map((event) => event.eventId));
+    const sentArtifacts = new Set(sent.artifacts.map((artifact) => artifact.artifactId));
+    if (sentEvents.size !== events.length || sentArtifacts.size !== sent.artifacts.length) {
+        throw new Error("Sent batch repeats an id");
+    }
+    for (const id of ack.accepted.eventIds)
+        if (!sentEvents.has(id))
+            throw new Error("Trace acknowledgement accepts an event that was not sent");
+    for (const id of ack.accepted.artifactIds) {
+        if (!sentArtifacts.has(id))
+            throw new Error("Trace acknowledgement accepts an artifact that was not sent");
+    }
+    for (const entry of ack.rejected) {
+        if (!sentEvents.has(entry.id) && !sentArtifacts.has(entry.id))
+            throw new Error("Trace acknowledgement rejects an id that was not sent");
+    }
+    const prefix = events.slice(0, ack.accepted.eventIds.length);
+    const accepted = new Set(ack.accepted.eventIds);
+    if (prefix.some((event) => !accepted.has(event.eventId))) {
+        throw new Error("Trace acknowledgement accepted events are not the contiguous sent prefix");
+    }
+    let eventPrefix = { kind: "none" };
+    const last = prefix[prefix.length - 1];
+    if (last === undefined) {
+        const unchanged = Math.max(previous, 0);
+        if (ack.ackedThroughSequence !== unchanged) {
+            throw new Error("Trace acknowledgement with no accepted events must repeat the previous watermark");
+        }
+    }
+    else {
+        if (ack.ackedThroughSequence !== last.sequence)
+            throw new Error("Trace acknowledgement ackedThroughSequence does not end the accepted prefix");
+        prefix.forEach((event, index) => {
+            if (event.sequence !== previous + 1 + index)
+                throw new Error("Trace acknowledgement prefix is not gap-free from the previous watermark");
+        });
+        eventPrefix = { kind: "prefix", throughSequence: last.sequence, eventIds: prefix.map((event) => event.eventId) };
+    }
+    const rejected = ack.rejected.map((entry) => ({ id: entry.id, code: entry.code, retryable: entry.retryable }));
+    return deepFreeze({
+        ack,
+        eventPrefix,
+        eventRejections: rejected.filter((entry) => sentEvents.has(entry.id)),
+        artifactMetadata: {
+            accepted: [...ack.accepted.artifactIds],
+            rejected: rejected.filter((entry) => sentArtifacts.has(entry.id)),
+        },
+        bytesAcknowledged: false,
+    });
+}
+function artifactReceiptSchema() {
+    return strict({
+        schema: Type.Literal(DH_HTTP_SCHEMA_IDS.artifactReceipt),
+        artifactId: DhArtifactIdSchema,
+        sha256: digest,
+        sizeBytes: Type.Optional(Type.Integer({ minimum: 0, maximum: DH_ARTIFACT_MAX_BYTES })),
+        state: Type.Union([Type.Literal("stored"), Type.Literal("rejected")]),
+        rejection: Type.Optional(strict({ code: Type.Enum(DH_REJECTION_CODES), retryable: Type.Boolean() })),
+        receivedAt: timestamp,
+    });
+}
+/**
+ * Response to PUT artifacts/{artifactId}/content. Names only the requested artifact and carries no
+ * sequence, event id or watermark, so it cannot advance an event cursor or acknowledge metadata.
+ */
+export const parseDhArtifactReceipt = dtoParser("artifact receipt", artifactReceiptSchema, (receipt) => {
+    if (receipt.state === "stored" && (receipt.sizeBytes === undefined || receipt.rejection !== undefined)) {
+        throw new Error("Invalid artifact receipt: stored requires sizeBytes and no rejection");
+    }
+    if (receipt.state === "rejected" && receipt.rejection === undefined) {
+        throw new Error("Invalid artifact receipt: rejected requires a rejection");
+    }
+});
+export function validateDhArtifactReceipt(requested, receiptInput) {
+    const receipt = parseDhArtifactReceipt(receiptInput);
+    if (receipt.artifactId !== requested.artifactId)
+        throw new DhContractError("receipt_invalid", "Artifact receipt names a different artifact");
+    if (receipt.sha256 !== requested.sha256)
+        throw new DhContractError("receipt_invalid", "Artifact receipt hash differs from the uploaded bytes");
+    if (requested.sizeBytes !== undefined &&
+        receipt.sizeBytes !== undefined &&
+        receipt.sizeBytes !== requested.sizeBytes) {
+        throw new DhContractError("receipt_invalid", "Artifact receipt size differs from the uploaded bytes");
+    }
+    return receipt;
+}
+/** Same id, same canonical bytes is an idempotent redelivery; the same id with different bytes is a conflict and never overwrites. */
+export function classifyDhDuplicate(existing, incoming) {
+    return canonicalText(existing) === canonicalText(incoming) ? "identical" : "conflict";
+}
+// ---------------------------------------------------------------------------
+// Supported runtimes and capabilities
+// ---------------------------------------------------------------------------
+export const DH_CONTROL_SUPPORT = ["required", "unsupported"];
+const allRequired = () => ({
+    backgroundStatus: "required",
+    cancelSelected: "required",
+    cancelWholeRun: "required",
+    continueLive: "required",
+    retryFresh: "required",
+});
+const cliRuntime = () => ({
+    controls: allRequired(),
+    modes: ["interactive", "print", "json", "rpc", "sdk", "child", "agent-exec-node"],
+    unsupportedModes: ["agent-exec-workflow", "experimental-transport"],
+});
+/**
+ * "required" means the implementation and a positive qualification check are mandatory for full
+ * completion; an `unsupported` reply never satisfies it. "unsupportedModes" cannot claim full capture.
+ */
+export const DH_SUPPORTED_RUNTIMES = deepFreeze({
+    "cli-node": cliRuntime(),
+    "cli-bun": cliRuntime(),
+    flow: {
+        controls: allRequired(),
+        modes: ["single", "parallel", "chain", "hierarchy"],
+        unsupportedModes: [],
+    },
+});
+//# sourceMappingURL=trace-http.js.map