@humain/humain-code-contracts 0.3.2 → 0.3.3

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

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

package/dist/trace-records.js

@@ -0,0 +1,535 @@
+import { Type } from "typebox";
+import { DH_COVERAGE_REASONS, DH_COVERAGE_STATES, DH_OUTCOMES, DhAgentIdSchema, DhAttemptIdSchema, DhEventIdSchema, DhGenerationIdSchema, } from "./trace.js";
+import { assertDhPlainData, DhContractError, dhCanonicalText } from "./trace-canonical.js";
+import { dhStrictDtoParser } from "./trace-http.js";
+import { assertDhUsageMeasurement, dhUsageMeasurementSchema } from "./trace-payload.js";
+/*
+ * Usage response/correction DTOs and records-policy (generation delete, legal hold) DTOs. Additions only:
+ * origin contractVersion 1, every existing /2 DTO and dh.batch/1-proposal are untouched, and DH_ROUTES is
+ * not changed (see DH_RECORDS_ROUTE_SCHEMAS for the route mapping).
+ *
+ * Usage rules (C0 decision 16): usage is submission-owned. Failed attempts keep their usage and every
+ * attempt is summed. Inclusive Flow aggregates are listed but contribute zero. Unknown usage or price is
+ * an explicit unknown/partial state, never zero. Corrections are append-only: a new record names the
+ * record it supersedes; nothing is overwritten.
+ *
+ * Hold precedence: an active legal hold always wins over deletion. A hold blocks the deletion claim; a
+ * claimed or tombstoned generation cannot accept a new hold.
+ *
+ * Like trace-payload.ts this module is loaded through the trace.ts import cycle: only typebox values are
+ * read at module top level; schemas and parsers are built lazily.
+ */
+export const DH_RECORDS_SCHEMA_IDS = Object.freeze({
+    generationDeleteRequest: "dh.generation-delete-request/1",
+    generationDeletion: "dh.generation-deletion/1",
+    legalHold: "dh.legal-hold/1",
+    legalHoldReleaseRequest: "dh.legal-hold-release-request/1",
+    legalHoldRequest: "dh.legal-hold-request/1",
+    usageCorrection: "dh.usage-correction/1",
+    usageResponse: "dh.usage-response/1",
+    usageSearchPage: "dh.usage-search-page/1",
+});
+/** Route to schema mapping. DH_ROUTES stays byte-identical; DELETE routes carry no body, so their request DTO is path-derived. */
+export const DH_RECORDS_ROUTE_SCHEMAS = Object.freeze({
+    usage: Object.freeze({ response: DH_RECORDS_SCHEMA_IDS.usageResponse }),
+    search: Object.freeze({ response: DH_RECORDS_SCHEMA_IDS.usageSearchPage }),
+    generationDelete: Object.freeze({
+        request: DH_RECORDS_SCHEMA_IDS.generationDeleteRequest,
+        response: DH_RECORDS_SCHEMA_IDS.generationDeletion,
+    }),
+    legalHoldCreate: Object.freeze({
+        request: DH_RECORDS_SCHEMA_IDS.legalHoldRequest,
+        response: DH_RECORDS_SCHEMA_IDS.legalHold,
+    }),
+    legalHoldRelease: Object.freeze({ request: DH_RECORDS_SCHEMA_IDS.legalHoldReleaseRequest }),
+});
+export const DH_USAGE_PAGE_MAX_ITEMS = 100;
+export const DH_USAGE_RESPONSE_MAX_ATTEMPTS = 4096;
+export const DH_USAGE_MAX_CURRENCIES = 16;
+export const DH_LEGAL_HOLD_REASONS = ["litigation", "regulatory-inquiry", "internal-investigation", "audit"];
+export const DH_LEGAL_HOLD_STATES = ["active", "released"];
+export const DH_DELETION_STATES = ["blocked-by-hold", "accepted", "claimed", "tombstoned"];
+export const DH_USAGE_CORRECTION_REASONS = [
+    "provider-reconciliation",
+    "price-correction",
+    "capture-error",
+    "duplicate-owner",
+];
+export const DH_DELETION_MAX_HOLD_IDS = 64;
+/** Upper bound for one currency amount; keeps float sums finite and the comparison tolerance meaningful. */
+export const DH_USAGE_MAX_AMOUNT = 1e15;
+const strict = (properties) => Type.Object(properties, { additionalProperties: false });
+const count = Type.Integer({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER });
+const positive = Type.Integer({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER });
+const digest = Type.String({ pattern: "^[a-f0-9]{64}$" });
+const 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$",
+});
+/** Opaque producer-side usage and submission identifier; same grammar as dh.payload.usage/1. */
+const ident = Type.String({ minLength: 1, maxLength: 128, pattern: "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$" });
+const prefixed = (prefix) => Type.String({ pattern: `^${prefix}_[A-Za-z0-9_-]{8,128}$`, maxLength: prefix.length + 129 });
+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 currency = Type.String({ pattern: "^[A-Z]{3}$" });
+function bad(label, reason) {
+    throw new DhContractError("schema_invalid", `Invalid ${label}: ${reason}`);
+}
+const unique = (ids) => new Set(ids).size === ids.length;
+/** Fixed-width key so fractional-second instants compare lexicographically. */
+const instantKey = (text) => {
+    const [whole = "", fraction = ""] = text.slice(0, -1).split(".");
+    return `${whole}.${fraction.padEnd(9, "0")}`;
+};
+function coverageSchema() {
+    // No detail: it can carry transcript text.
+    return strict({ state: Type.Enum(DH_COVERAGE_STATES), reason: Type.Optional(Type.Enum(DH_COVERAGE_REASONS)) });
+}
+// ---------------------------------------------------------------------------
+// Usage totals
+// ---------------------------------------------------------------------------
+const USAGE_DIMENSIONS = [
+    "input",
+    "output",
+    "cacheRead",
+    "cacheWrite",
+    "reasoning",
+    "totalTokens",
+    "durationMs",
+];
+/** unknown: no counted submission reports it. known: every one does. partial: value is a lower bound. */
+function dimensionSchema() {
+    return Type.Union([
+        strict({ state: Type.Literal("unknown"), unknownSubmissions: count }),
+        strict({ state: Type.Literal("known"), value: count, knownSubmissions: positive }),
+        strict({
+            state: Type.Literal("partial"),
+            value: count,
+            knownSubmissions: positive,
+            unknownSubmissions: positive,
+        }),
+    ]);
+}
+function currencyTotalSchema() {
+    return strict({
+        currency,
+        amount: Type.Number({ minimum: 0, maximum: DH_USAGE_MAX_AMOUNT }),
+        submissions: positive,
+    });
+}
+/** Price is never converted across currencies and never zero when unknown. */
+function costTotalSchema() {
+    const currencies = Type.Array(currencyTotalSchema(), { minItems: 1, maxItems: DH_USAGE_MAX_CURRENCIES });
+    return Type.Union([
+        strict({ state: Type.Literal("unknown"), unknownSubmissions: count }),
+        strict({ state: Type.Literal("known"), byCurrency: currencies }),
+        strict({ state: Type.Literal("partial"), byCurrency: currencies, unknownSubmissions: positive }),
+    ]);
+}
+function totalsSchema() {
+    return strict({
+        /** Counted submission-owned records only: superseded records and inclusive Flow aggregates are excluded. */
+        submissions: count,
+        input: dimensionSchema(),
+        output: dimensionSchema(),
+        cacheRead: dimensionSchema(),
+        cacheWrite: dimensionSchema(),
+        reasoning: dimensionSchema(),
+        totalTokens: dimensionSchema(),
+        durationMs: dimensionSchema(),
+        cost: costTotalSchema(),
+    });
+}
+const accOf = (d) => d.state === "unknown"
+    ? { value: 0, known: 0, unknown: d.unknownSubmissions }
+    : { value: d.value, known: d.knownSubmissions, unknown: d.state === "partial" ? d.unknownSubmissions : 0 };
+const dimensionOf = ({ value, known, unknown }) => known === 0
+    ? { state: "unknown", unknownSubmissions: unknown }
+    : unknown === 0
+        ? { state: "known", value, knownSubmissions: known }
+        : { state: "partial", value, knownSubmissions: known, unknownSubmissions: unknown };
+/** Sums totals. Unknown never contributes a value; any unknown submission turns known into partial. */
+export function sumDhUsageTotals(parts) {
+    const dimensions = Object.fromEntries(USAGE_DIMENSIONS.map((key) => {
+        const sum = { value: 0, known: 0, unknown: 0 };
+        for (const part of parts) {
+            const next = accOf(part[key]);
+            sum.value += next.value;
+            sum.known += next.known;
+            sum.unknown += next.unknown;
+        }
+        return [key, dimensionOf(sum)];
+    }));
+    const byCurrency = new Map();
+    let unknown = 0;
+    for (const { cost } of parts) {
+        if (cost.state !== "known")
+            unknown += cost.unknownSubmissions;
+        if (cost.state === "unknown")
+            continue;
+        for (const entry of cost.byCurrency) {
+            const total = byCurrency.get(entry.currency) ?? { amount: 0, submissions: 0 };
+            byCurrency.set(entry.currency, {
+                amount: total.amount + entry.amount,
+                submissions: total.submissions + entry.submissions,
+            });
+        }
+    }
+    const list = [...byCurrency]
+        .sort(([a], [b]) => (a < b ? -1 : 1))
+        .map(([code, total]) => ({ currency: code, ...total }));
+    const cost = list.length === 0
+        ? { state: "unknown", unknownSubmissions: unknown }
+        : unknown === 0
+            ? { state: "known", byCurrency: list }
+            : { state: "partial", byCurrency: list, unknownSubmissions: unknown };
+    return { submissions: parts.reduce((n, part) => n + part.submissions, 0), ...dimensions, cost };
+}
+/** Totals for counted submission-owned measurements. No measurements is unknown, not zero. */
+export function dhUsageTotalsOf(measurements) {
+    return sumDhUsageTotals(measurements.map((measurement) => {
+        const reported = measurement.state === "reported" ? measurement : undefined;
+        const dimensions = Object.fromEntries(USAGE_DIMENSIONS.map((key) => {
+            const value = reported?.[key];
+            return [
+                key,
+                value === undefined
+                    ? { state: "unknown", unknownSubmissions: 1 }
+                    : { state: "known", value, knownSubmissions: 1 },
+            ];
+        }));
+        const cost = reported?.cost.state === "known"
+            ? {
+                state: "known",
+                byCurrency: [{ currency: reported.cost.currency, amount: reported.cost.amount, submissions: 1 }],
+            }
+            : { state: "unknown", unknownSubmissions: 1 };
+        return { submissions: 1, ...dimensions, cost };
+    }));
+}
+function assertTotals(label, totals) {
+    for (const key of USAGE_DIMENSIONS) {
+        const { known, unknown } = accOf(totals[key]);
+        if (known + unknown !== totals.submissions)
+            bad(label, `${key} does not account for every submission`);
+    }
+    const { cost } = totals;
+    if (cost.state === "unknown") {
+        if (cost.unknownSubmissions !== totals.submissions)
+            bad(label, "cost does not account for every submission");
+        return;
+    }
+    const codes = cost.byCurrency.map((entry) => entry.currency);
+    if (codes.some((code, index) => index > 0 && code <= codes[index - 1]))
+        bad(label, "cost currencies must be unique and sorted");
+    const priced = cost.byCurrency.reduce((n, entry) => n + entry.submissions, 0);
+    if (priced + (cost.state === "partial" ? cost.unknownSubmissions : 0) !== totals.submissions)
+        bad(label, "cost does not account for every submission");
+}
+/** Amounts are decimal sums whose float order varies, so they compare with a relative tolerance; everything else is exact. */
+function sameTotals(a, b) {
+    const zeroed = (totals) => dhCanonicalText((totals.cost.state === "unknown"
+        ? totals
+        : {
+            ...totals,
+            cost: { ...totals.cost, byCurrency: totals.cost.byCurrency.map((e) => ({ ...e, amount: 0 })) },
+        }));
+    const amounts = (totals) => totals.cost.state === "unknown" ? [] : totals.cost.byCurrency.map((entry) => entry.amount);
+    const other = amounts(b);
+    return ([...amounts(a), ...other].every(Number.isFinite) &&
+        zeroed(a) === zeroed(b) &&
+        amounts(a).every((x, i) => Math.abs(x - other[i]) <= 1e-9 * Math.max(1, Math.abs(x), Math.abs(other[i]))));
+}
+// ---------------------------------------------------------------------------
+// Usage response, search page, correction
+// ---------------------------------------------------------------------------
+function usageResponseSchema() {
+    return strict({
+        schema: Type.Literal(DH_RECORDS_SCHEMA_IDS.usageResponse),
+        generationId: DhGenerationIdSchema,
+        captureCutoff: timestamp,
+        /** Sum of every attempt below, failed attempts included. */
+        totals: totalsSchema(),
+        attempts: Type.Array(strict({
+            agentId: DhAgentIdSchema,
+            attemptId: DhAttemptIdSchema,
+            /** Absent while the attempt has no recorded terminal outcome. */
+            outcome: Type.Optional(Type.Enum(DH_OUTCOMES)),
+            totals: totalsSchema(),
+        }), { maxItems: DH_USAGE_RESPONSE_MAX_ATTEMPTS }),
+        /** Appended correction records that replaced an earlier record; they are retained and contribute zero. */
+        supersededRecords: count,
+        /** Inclusive Flow aggregate records: listed by search, contribute zero to totals. */
+        inclusiveAggregateRecords: count,
+        coverage: coverageSchema(),
+    });
+}
+export const parseDhUsageResponse = dhStrictDtoParser("usage response", usageResponseSchema, (response) => {
+    const label = "usage response";
+    assertTotals(label, response.totals);
+    for (const attempt of response.attempts)
+        assertTotals(label, attempt.totals);
+    if (!unique(response.attempts.map((attempt) => attempt.attemptId)))
+        bad(label, "duplicate attempt");
+    if (response.coverage.state !== "captured" && response.coverage.reason === undefined)
+        bad(label, "non-captured coverage requires a reason");
+    if (!sameTotals(response.totals, sumDhUsageTotals(response.attempts.map((attempt) => attempt.totals))))
+        bad(label, "totals do not equal the sum of attempts");
+});
+const usageOriginSchema = () => Type.Union([
+    strict({ owner: Type.Literal("submission"), submissionId: ident }),
+    strict({ owner: Type.Literal("flow-aggregate"), inclusive: Type.Literal(true) }),
+]);
+function usageRecordSchema() {
+    return strict({
+        usageId: ident,
+        eventId: DhEventIdSchema,
+        generationId: DhGenerationIdSchema,
+        agentId: DhAgentIdSchema,
+        /** Required for submission-owned records so failed and retried attempts stay separable. */
+        attemptId: Type.Optional(DhAttemptIdSchema),
+        origin: usageOriginSchema(),
+        measurement: dhUsageMeasurementSchema(),
+        /** True only for a submission-owned record that no correction supersedes. */
+        counted: Type.Boolean(),
+        supersedesUsageId: Type.Optional(ident),
+        /** Query-time pointer to the correction that replaced this record; the stored record is never mutated. */
+        supersededByUsageId: Type.Optional(ident),
+    });
+}
+function assertUsageRecord(record) {
+    const label = "usage record";
+    assertDhUsageMeasurement(label, record.measurement);
+    const submission = record.origin.owner === "submission";
+    if (submission && record.attemptId === undefined)
+        bad(label, "submission-owned usage needs attemptId");
+    if (record.counted !== (submission && record.supersededByUsageId === undefined))
+        bad(label, "counted must be true only for a submission-owned record that is not superseded");
+    if (!submission && (record.supersedesUsageId !== undefined || record.supersededByUsageId !== undefined))
+        bad(label, "inclusive aggregates are never corrected");
+    if (record.supersedesUsageId === record.usageId || record.supersededByUsageId === record.usageId)
+        bad(label, "a record cannot supersede itself");
+    if (record.supersedesUsageId !== undefined && record.supersedesUsageId === record.supersededByUsageId)
+        bad(label, "supersession cycle");
+}
+export const parseDhUsageRecord = dhStrictDtoParser("usage record", usageRecordSchema, assertUsageRecord);
+function usageSearchPageSchema() {
+    return strict({
+        schema: Type.Literal(DH_RECORDS_SCHEMA_IDS.usageSearchPage),
+        generationId: DhGenerationIdSchema,
+        captureCutoff: timestamp,
+        filterSha256: digest,
+        nextCursor: Type.Union([Type.Null(), cursorSchema]),
+        items: Type.Array(usageRecordSchema(), { maxItems: DH_USAGE_PAGE_MAX_ITEMS }),
+    });
+}
+export const parseDhUsageSearchPage = dhStrictDtoParser("usage search page", usageSearchPageSchema, (page) => {
+    const label = "usage search page";
+    const byId = new Map();
+    for (const item of page.items) {
+        assertUsageRecord(item);
+        if (item.generationId !== page.generationId)
+            bad(label, "record belongs to a different generation");
+        if (byId.has(item.usageId))
+            bad(label, "duplicate usageId");
+        byId.set(item.usageId, item);
+    }
+    const owners = page.items.flatMap((item) => item.counted && item.origin.owner === "submission" ? [item.origin.submissionId] : []);
+    if (!unique(owners))
+        bad(label, "more than one counted owner for a submission");
+    const predecessors = page.items.flatMap((item) => item.supersedesUsageId === undefined ? [] : [item.supersedesUsageId]);
+    if (!unique(predecessors))
+        bad(label, "more than one record supersedes the same record");
+    const successors = page.items.flatMap((item) => item.supersededByUsageId === undefined ? [] : [item.supersededByUsageId]);
+    if (!unique(successors))
+        bad(label, "more than one record is superseded by the same record");
+    const sameSubmission = (a, b) => a.agentId === b.agentId &&
+        a.attemptId === b.attemptId &&
+        a.origin.owner === "submission" &&
+        b.origin.owner === "submission" &&
+        a.origin.submissionId === b.origin.submissionId;
+    for (const item of page.items) {
+        const older = item.supersedesUsageId === undefined ? undefined : byId.get(item.supersedesUsageId);
+        if (older !== undefined && older.supersededByUsageId !== item.usageId)
+            bad(label, "supersession pointers disagree");
+        const newer = item.supersededByUsageId === undefined ? undefined : byId.get(item.supersededByUsageId);
+        if (newer !== undefined && newer.supersedesUsageId !== item.usageId)
+            bad(label, "supersession pointers disagree");
+        if ((older !== undefined && !sameSubmission(older, item)) ||
+            (newer !== undefined && !sameSubmission(item, newer)))
+            bad(label, "supersession identity differs between agent, attempt and submission");
+        const seen = new Set([item.usageId]);
+        for (let next = newer; next !== undefined; next = byId.get(next.supersededByUsageId ?? "")) {
+            if (seen.has(next.usageId))
+                bad(label, "supersession cycle");
+            seen.add(next.usageId);
+        }
+    }
+});
+function usageCorrectionSchema() {
+    return strict({
+        schema: Type.Literal(DH_RECORDS_SCHEMA_IDS.usageCorrection),
+        /** The new record's id. Append-only: it never reuses the superseded id. */
+        usageId: ident,
+        supersedesUsageId: ident,
+        generationId: DhGenerationIdSchema,
+        agentId: DhAgentIdSchema,
+        attemptId: DhAttemptIdSchema,
+        submissionId: ident,
+        reason: Type.Enum(DH_USAGE_CORRECTION_REASONS),
+        recordedAt: timestamp,
+        /** Replacement measurement. An explicit unknown retracts a value; zero is never implied. */
+        measurement: dhUsageMeasurementSchema(),
+    });
+}
+export const parseDhUsageCorrection = dhStrictDtoParser("usage correction", usageCorrectionSchema, (correction) => {
+    assertDhUsageMeasurement("usage correction", correction.measurement);
+    if (correction.usageId === correction.supersedesUsageId)
+        bad("usage correction", "a record cannot supersede itself");
+});
+/** One stored record id (and the id it supersedes, if any) from the caller's store; parsed through the plain-data gate. */
+const parseStoredUsageId = dhStrictDtoParser("stored usage id", () => strict({ usageId: ident, supersedesUsageId: Type.Optional(ident) }));
+/**
+ * Checks a correction against the stored record it supersedes and the records already stored.
+ * `existing` lists every stored usageId (originals and corrections; supersedesUsageId for corrections).
+ * Same submission, no fork (one correction per superseded record), no reuse of any stored id or of the
+ * superseded record's predecessor, only submission-owned targets.
+ */
+export function assertDhUsageCorrection(correctionInput, supersededInput, existing = []) {
+    const correction = parseDhUsageCorrection(correctionInput);
+    const superseded = parseDhUsageRecord(supersededInput);
+    const stored = existing.map(parseStoredUsageId);
+    if (superseded.origin.owner !== "submission" ||
+        superseded.usageId !== correction.supersedesUsageId ||
+        superseded.generationId !== correction.generationId ||
+        superseded.agentId !== correction.agentId ||
+        superseded.attemptId !== correction.attemptId ||
+        superseded.origin.submissionId !== correction.submissionId)
+        throw new DhContractError("usage_correction_mismatch", "Usage correction does not match the superseded record");
+    const storedIds = new Set([
+        superseded.usageId,
+        ...(superseded.supersedesUsageId === undefined ? [] : [superseded.supersedesUsageId]),
+        ...stored.flatMap((entry) => [
+            entry.usageId,
+            ...(entry.supersedesUsageId === undefined ? [] : [entry.supersedesUsageId]),
+        ]),
+    ]);
+    if (superseded.supersededByUsageId !== undefined ||
+        stored.some((entry) => entry.supersedesUsageId === correction.supersedesUsageId) ||
+        storedIds.has(correction.usageId))
+        throw new DhContractError("usage_correction_conflict", "Usage correction conflicts with an appended correction");
+}
+// ---------------------------------------------------------------------------
+// Records policy: generation delete and legal holds (hold precedence)
+// ---------------------------------------------------------------------------
+const holdId = () => prefixed("hld");
+/** DELETE has no body, so this is the path-derived request context, not a wire body. */
+export const parseDhGenerationDeleteRequest = dhStrictDtoParser("generation delete request", () => strict({ schema: Type.Literal(DH_RECORDS_SCHEMA_IDS.generationDeleteRequest), generationId: DhGenerationIdSchema }));
+/** Path-derived like the delete request; release is explicit and authorized, never implied by deletion. */
+export const parseDhLegalHoldReleaseRequest = dhStrictDtoParser("legal hold release request", () => strict({
+    schema: Type.Literal(DH_RECORDS_SCHEMA_IDS.legalHoldReleaseRequest),
+    generationId: DhGenerationIdSchema,
+    holdId: holdId(),
+}));
+/** Reason is an enum and matterRef an opaque reference: no free text, so a hold cannot carry content. */
+export const parseDhLegalHoldRequest = dhStrictDtoParser("legal hold request", () => strict({
+    schema: Type.Literal(DH_RECORDS_SCHEMA_IDS.legalHoldRequest),
+    requestId: prefixed("hlr"),
+    generationId: DhGenerationIdSchema,
+    reasonCode: Type.Enum(DH_LEGAL_HOLD_REASONS),
+    matterRef: Type.Optional(refSchema),
+}));
+function legalHoldSchema() {
+    return strict({
+        schema: Type.Literal(DH_RECORDS_SCHEMA_IDS.legalHold),
+        holdId: holdId(),
+        requestId: prefixed("hlr"),
+        generationId: DhGenerationIdSchema,
+        state: Type.Enum(DH_LEGAL_HOLD_STATES),
+        reasonCode: Type.Enum(DH_LEGAL_HOLD_REASONS),
+        matterRef: Type.Optional(refSchema),
+        placedAt: timestamp,
+        releasedAt: Type.Optional(timestamp),
+    });
+}
+export const parseDhLegalHold = dhStrictDtoParser("legal hold", legalHoldSchema, (hold) => {
+    if (hold.state === "active" ? hold.releasedAt !== undefined : hold.releasedAt === undefined)
+        bad("legal hold", "releasedAt is required exactly when the hold is released");
+    if (hold.releasedAt !== undefined && instantKey(hold.releasedAt) < instantKey(hold.placedAt))
+        bad("legal hold", "releasedAt precedes placedAt");
+});
+function generationDeletionSchema() {
+    return strict({
+        schema: Type.Literal(DH_RECORDS_SCHEMA_IDS.generationDeletion),
+        generationId: DhGenerationIdSchema,
+        state: Type.Enum(DH_DELETION_STATES),
+        /** Evidence from the same locked snapshot as the state: held iff blocked-by-hold. */
+        holdCheck: Type.Union([
+            strict({ state: Type.Literal("clear") }),
+            strict({
+                state: Type.Literal("held"),
+                holdIds: Type.Array(holdId(), { minItems: 1, maxItems: DH_DELETION_MAX_HOLD_IDS, uniqueItems: true }),
+            }),
+        ]),
+        /** Durable deletion claim time; present exactly when claimed or tombstoned. */
+        claimedAt: Type.Optional(timestamp),
+    });
+}
+export const parseDhGenerationDeletion = dhStrictDtoParser("generation deletion", generationDeletionSchema, (deletion) => {
+    const label = "generation deletion";
+    if ((deletion.holdCheck.state === "held") !== (deletion.state === "blocked-by-hold"))
+        bad(label, "an active hold blocks deletion and only a hold blocks it");
+    if ((deletion.claimedAt !== undefined) !== (deletion.state === "claimed" || deletion.state === "tombstoned"))
+        bad(label, "claimedAt is required exactly for claimed or tombstoned");
+});
+/** A generation with a durable deletion claim cannot accept a new hold. */
+export function assertDhHoldPlacementAllowed(deletionInput) {
+    const { state } = parseDhGenerationDeletion(deletionInput);
+    if (state === "claimed" || state === "tombstoned")
+        throw new DhContractError("deletion_claimed", "Generation deletion is already claimed");
+}
+/**
+ * Hold wins. Given one snapshot's deletion status and holds: an active hold forbids any state but
+ * blocked-by-hold and must be named in holdCheck. A hold placed at or before the claim that was released
+ * only after the claim (or never) blocks the deletion; a hold placed after the claim is also rejected.
+ */
+export function assertDhHoldPrecedence(deletionInput, holdInputs) {
+    const deletion = parseDhGenerationDeletion(deletionInput);
+    const holds = holdInputs.map(parseDhLegalHold);
+    if (holds.some((hold) => hold.generationId !== deletion.generationId))
+        throw new DhContractError("hold_precedence", "Hold belongs to a different generation");
+    const active = holds.filter((hold) => hold.state === "active");
+    const named = deletion.holdCheck.state === "held" ? deletion.holdCheck.holdIds : [];
+    if (active.length > 0 &&
+        (deletion.state !== "blocked-by-hold" || active.some((hold) => !named.includes(hold.holdId))))
+        throw new DhContractError("hold_precedence", "An active legal hold takes precedence over deletion");
+    if (named.some((id) => !active.some((hold) => hold.holdId === id)))
+        throw new DhContractError("hold_precedence", "Deletion names a hold that is not active in this snapshot");
+    const claimedAt = deletion.claimedAt === undefined ? undefined : instantKey(deletion.claimedAt);
+    if (claimedAt !== undefined && holds.some((hold) => instantKey(hold.placedAt) > claimedAt))
+        throw new DhContractError("hold_precedence", "A hold cannot attach after the deletion claim");
+    if (claimedAt !== undefined &&
+        holds.some((hold) => hold.releasedAt !== undefined && instantKey(hold.releasedAt) > claimedAt))
+        throw new DhContractError("hold_precedence", "An active legal hold takes precedence over deletion");
+}
+/** The body must match the route's path generation (and hold). Route params are validated by buildDhRoutePath. */
+export function assertDhRecordsRequestForPath(requestInput, params) {
+    assertDhPlainData(requestInput);
+    if (typeof requestInput !== "object" || requestInput === null || Array.isArray(requestInput))
+        throw new DhContractError("schema_invalid", "Records request must be an object");
+    const schema = requestInput.schema;
+    const parse = schema === DH_RECORDS_SCHEMA_IDS.generationDeleteRequest
+        ? parseDhGenerationDeleteRequest
+        : schema === DH_RECORDS_SCHEMA_IDS.legalHoldRequest
+            ? parseDhLegalHoldRequest
+            : schema === DH_RECORDS_SCHEMA_IDS.legalHoldReleaseRequest
+                ? parseDhLegalHoldReleaseRequest
+                : undefined;
+    if (parse === undefined)
+        throw new DhContractError("schema_invalid", "Invalid records request schema");
+    const request = parse(requestInput);
+    if (request.generationId !== params.generationId || ("holdId" in request && request.holdId !== params.holdId))
+        throw new DhContractError("schema_invalid", "Records request does not match the route path");
+}
+//# sourceMappingURL=trace-records.js.map