@humain/humain-code-contracts 0.3.2 → 0.3.3

package/dist/trace-records.d.ts

@@ -0,0 +1,985 @@
+import { type Static, Type } from "typebox";
+import { dhUsageMeasurementSchema } from "./trace-payload.ts";
+export declare const DH_RECORDS_SCHEMA_IDS: Readonly<{
+    readonly generationDeleteRequest: "dh.generation-delete-request/1";
+    readonly generationDeletion: "dh.generation-deletion/1";
+    readonly legalHold: "dh.legal-hold/1";
+    readonly legalHoldReleaseRequest: "dh.legal-hold-release-request/1";
+    readonly legalHoldRequest: "dh.legal-hold-request/1";
+    readonly usageCorrection: "dh.usage-correction/1";
+    readonly usageResponse: "dh.usage-response/1";
+    readonly 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 declare const DH_RECORDS_ROUTE_SCHEMAS: Readonly<{
+    readonly usage: Readonly<{
+        response: "dh.usage-response/1";
+    }>;
+    readonly search: Readonly<{
+        response: "dh.usage-search-page/1";
+    }>;
+    readonly generationDelete: Readonly<{
+        request: "dh.generation-delete-request/1";
+        response: "dh.generation-deletion/1";
+    }>;
+    readonly legalHoldCreate: Readonly<{
+        request: "dh.legal-hold-request/1";
+        response: "dh.legal-hold/1";
+    }>;
+    readonly legalHoldRelease: Readonly<{
+        request: "dh.legal-hold-release-request/1";
+    }>;
+}>;
+export declare const DH_USAGE_PAGE_MAX_ITEMS = 100;
+export declare const DH_USAGE_RESPONSE_MAX_ATTEMPTS = 4096;
+export declare const DH_USAGE_MAX_CURRENCIES = 16;
+export declare const DH_LEGAL_HOLD_REASONS: readonly ["litigation", "regulatory-inquiry", "internal-investigation", "audit"];
+export declare const DH_LEGAL_HOLD_STATES: readonly ["active", "released"];
+export declare const DH_DELETION_STATES: readonly ["blocked-by-hold", "accepted", "claimed", "tombstoned"];
+export declare const DH_USAGE_CORRECTION_REASONS: readonly ["provider-reconciliation", "price-correction", "capture-error", "duplicate-owner"];
+export declare const DH_DELETION_MAX_HOLD_IDS = 64;
+/** Upper bound for one currency amount; keeps float sums finite and the comparison tolerance meaningful. */
+export declare const DH_USAGE_MAX_AMOUNT = 1000000000000000;
+declare function totalsSchema(): Type.TObject<{
+    /** Counted submission-owned records only: superseded records and inclusive Flow aggregates are excluded. */
+    readonly submissions: Type.TInteger;
+    readonly input: Type.TUnion<[Type.TObject<{
+        readonly state: Type.TLiteral<"unknown">;
+        readonly unknownSubmissions: Type.TInteger;
+    }>, Type.TObject<{
+        readonly state: Type.TLiteral<"known">;
+        readonly value: Type.TInteger;
+        readonly knownSubmissions: Type.TInteger;
+    }>, Type.TObject<{
+        readonly state: Type.TLiteral<"partial">;
+        readonly value: Type.TInteger;
+        readonly knownSubmissions: Type.TInteger;
+        readonly unknownSubmissions: Type.TInteger;
+    }>]>;
+    readonly output: Type.TUnion<[Type.TObject<{
+        readonly state: Type.TLiteral<"unknown">;
+        readonly unknownSubmissions: Type.TInteger;
+    }>, Type.TObject<{
+        readonly state: Type.TLiteral<"known">;
+        readonly value: Type.TInteger;
+        readonly knownSubmissions: Type.TInteger;
+    }>, Type.TObject<{
+        readonly state: Type.TLiteral<"partial">;
+        readonly value: Type.TInteger;
+        readonly knownSubmissions: Type.TInteger;
+        readonly unknownSubmissions: Type.TInteger;
+    }>]>;
+    readonly cacheRead: Type.TUnion<[Type.TObject<{
+        readonly state: Type.TLiteral<"unknown">;
+        readonly unknownSubmissions: Type.TInteger;
+    }>, Type.TObject<{
+        readonly state: Type.TLiteral<"known">;
+        readonly value: Type.TInteger;
+        readonly knownSubmissions: Type.TInteger;
+    }>, Type.TObject<{
+        readonly state: Type.TLiteral<"partial">;
+        readonly value: Type.TInteger;
+        readonly knownSubmissions: Type.TInteger;
+        readonly unknownSubmissions: Type.TInteger;
+    }>]>;
+    readonly cacheWrite: Type.TUnion<[Type.TObject<{
+        readonly state: Type.TLiteral<"unknown">;
+        readonly unknownSubmissions: Type.TInteger;
+    }>, Type.TObject<{
+        readonly state: Type.TLiteral<"known">;
+        readonly value: Type.TInteger;
+        readonly knownSubmissions: Type.TInteger;
+    }>, Type.TObject<{
+        readonly state: Type.TLiteral<"partial">;
+        readonly value: Type.TInteger;
+        readonly knownSubmissions: Type.TInteger;
+        readonly unknownSubmissions: Type.TInteger;
+    }>]>;
+    readonly reasoning: Type.TUnion<[Type.TObject<{
+        readonly state: Type.TLiteral<"unknown">;
+        readonly unknownSubmissions: Type.TInteger;
+    }>, Type.TObject<{
+        readonly state: Type.TLiteral<"known">;
+        readonly value: Type.TInteger;
+        readonly knownSubmissions: Type.TInteger;
+    }>, Type.TObject<{
+        readonly state: Type.TLiteral<"partial">;
+        readonly value: Type.TInteger;
+        readonly knownSubmissions: Type.TInteger;
+        readonly unknownSubmissions: Type.TInteger;
+    }>]>;
+    readonly totalTokens: Type.TUnion<[Type.TObject<{
+        readonly state: Type.TLiteral<"unknown">;
+        readonly unknownSubmissions: Type.TInteger;
+    }>, Type.TObject<{
+        readonly state: Type.TLiteral<"known">;
+        readonly value: Type.TInteger;
+        readonly knownSubmissions: Type.TInteger;
+    }>, Type.TObject<{
+        readonly state: Type.TLiteral<"partial">;
+        readonly value: Type.TInteger;
+        readonly knownSubmissions: Type.TInteger;
+        readonly unknownSubmissions: Type.TInteger;
+    }>]>;
+    readonly durationMs: Type.TUnion<[Type.TObject<{
+        readonly state: Type.TLiteral<"unknown">;
+        readonly unknownSubmissions: Type.TInteger;
+    }>, Type.TObject<{
+        readonly state: Type.TLiteral<"known">;
+        readonly value: Type.TInteger;
+        readonly knownSubmissions: Type.TInteger;
+    }>, Type.TObject<{
+        readonly state: Type.TLiteral<"partial">;
+        readonly value: Type.TInteger;
+        readonly knownSubmissions: Type.TInteger;
+        readonly unknownSubmissions: Type.TInteger;
+    }>]>;
+    readonly cost: Type.TUnion<[Type.TObject<{
+        readonly state: Type.TLiteral<"unknown">;
+        readonly unknownSubmissions: Type.TInteger;
+    }>, Type.TObject<{
+        readonly state: Type.TLiteral<"known">;
+        readonly byCurrency: Type.TArray<Type.TObject<{
+            readonly currency: Type.TString;
+            readonly amount: Type.TNumber;
+            readonly submissions: Type.TInteger;
+        }>>;
+    }>, Type.TObject<{
+        readonly state: Type.TLiteral<"partial">;
+        readonly byCurrency: Type.TArray<Type.TObject<{
+            readonly currency: Type.TString;
+            readonly amount: Type.TNumber;
+            readonly submissions: Type.TInteger;
+        }>>;
+        readonly unknownSubmissions: Type.TInteger;
+    }>]>;
+}>;
+export type DhUsageTotals = Static<ReturnType<typeof totalsSchema>>;
+type Measurement = Static<ReturnType<typeof dhUsageMeasurementSchema>>;
+/** Sums totals. Unknown never contributes a value; any unknown submission turns known into partial. */
+export declare function sumDhUsageTotals(parts: readonly DhUsageTotals[]): DhUsageTotals;
+/** Totals for counted submission-owned measurements. No measurements is unknown, not zero. */
+export declare function dhUsageTotalsOf(measurements: readonly Measurement[]): DhUsageTotals;
+declare function usageResponseSchema(): Type.TObject<{
+    readonly schema: Type.TLiteral<"dh.usage-response/1">;
+    readonly generationId: Type.TString;
+    readonly captureCutoff: Type.TString;
+    /** Sum of every attempt below, failed attempts included. */
+    readonly totals: Type.TObject<{
+        /** Counted submission-owned records only: superseded records and inclusive Flow aggregates are excluded. */
+        readonly submissions: Type.TInteger;
+        readonly input: Type.TUnion<[Type.TObject<{
+            readonly state: Type.TLiteral<"unknown">;
+            readonly unknownSubmissions: Type.TInteger;
+        }>, Type.TObject<{
+            readonly state: Type.TLiteral<"known">;
+            readonly value: Type.TInteger;
+            readonly knownSubmissions: Type.TInteger;
+        }>, Type.TObject<{
+            readonly state: Type.TLiteral<"partial">;
+            readonly value: Type.TInteger;
+            readonly knownSubmissions: Type.TInteger;
+            readonly unknownSubmissions: Type.TInteger;
+        }>]>;
+        readonly output: Type.TUnion<[Type.TObject<{
+            readonly state: Type.TLiteral<"unknown">;
+            readonly unknownSubmissions: Type.TInteger;
+        }>, Type.TObject<{
+            readonly state: Type.TLiteral<"known">;
+            readonly value: Type.TInteger;
+            readonly knownSubmissions: Type.TInteger;
+        }>, Type.TObject<{
+            readonly state: Type.TLiteral<"partial">;
+            readonly value: Type.TInteger;
+            readonly knownSubmissions: Type.TInteger;
+            readonly unknownSubmissions: Type.TInteger;
+        }>]>;
+        readonly cacheRead: Type.TUnion<[Type.TObject<{
+            readonly state: Type.TLiteral<"unknown">;
+            readonly unknownSubmissions: Type.TInteger;
+        }>, Type.TObject<{
+            readonly state: Type.TLiteral<"known">;
+            readonly value: Type.TInteger;
+            readonly knownSubmissions: Type.TInteger;
+        }>, Type.TObject<{
+            readonly state: Type.TLiteral<"partial">;
+            readonly value: Type.TInteger;
+            readonly knownSubmissions: Type.TInteger;
+            readonly unknownSubmissions: Type.TInteger;
+        }>]>;
+        readonly cacheWrite: Type.TUnion<[Type.TObject<{
+            readonly state: Type.TLiteral<"unknown">;
+            readonly unknownSubmissions: Type.TInteger;
+        }>, Type.TObject<{
+            readonly state: Type.TLiteral<"known">;
+            readonly value: Type.TInteger;
+            readonly knownSubmissions: Type.TInteger;
+        }>, Type.TObject<{
+            readonly state: Type.TLiteral<"partial">;
+            readonly value: Type.TInteger;
+            readonly knownSubmissions: Type.TInteger;
+            readonly unknownSubmissions: Type.TInteger;
+        }>]>;
+        readonly reasoning: Type.TUnion<[Type.TObject<{
+            readonly state: Type.TLiteral<"unknown">;
+            readonly unknownSubmissions: Type.TInteger;
+        }>, Type.TObject<{
+            readonly state: Type.TLiteral<"known">;
+            readonly value: Type.TInteger;
+            readonly knownSubmissions: Type.TInteger;
+        }>, Type.TObject<{
+            readonly state: Type.TLiteral<"partial">;
+            readonly value: Type.TInteger;
+            readonly knownSubmissions: Type.TInteger;
+            readonly unknownSubmissions: Type.TInteger;
+        }>]>;
+        readonly totalTokens: Type.TUnion<[Type.TObject<{
+            readonly state: Type.TLiteral<"unknown">;
+            readonly unknownSubmissions: Type.TInteger;
+        }>, Type.TObject<{
+            readonly state: Type.TLiteral<"known">;
+            readonly value: Type.TInteger;
+            readonly knownSubmissions: Type.TInteger;
+        }>, Type.TObject<{
+            readonly state: Type.TLiteral<"partial">;
+            readonly value: Type.TInteger;
+            readonly knownSubmissions: Type.TInteger;
+            readonly unknownSubmissions: Type.TInteger;
+        }>]>;
+        readonly durationMs: Type.TUnion<[Type.TObject<{
+            readonly state: Type.TLiteral<"unknown">;
+            readonly unknownSubmissions: Type.TInteger;
+        }>, Type.TObject<{
+            readonly state: Type.TLiteral<"known">;
+            readonly value: Type.TInteger;
+            readonly knownSubmissions: Type.TInteger;
+        }>, Type.TObject<{
+            readonly state: Type.TLiteral<"partial">;
+            readonly value: Type.TInteger;
+            readonly knownSubmissions: Type.TInteger;
+            readonly unknownSubmissions: Type.TInteger;
+        }>]>;
+        readonly cost: Type.TUnion<[Type.TObject<{
+            readonly state: Type.TLiteral<"unknown">;
+            readonly unknownSubmissions: Type.TInteger;
+        }>, Type.TObject<{
+            readonly state: Type.TLiteral<"known">;
+            readonly byCurrency: Type.TArray<Type.TObject<{
+                readonly currency: Type.TString;
+                readonly amount: Type.TNumber;
+                readonly submissions: Type.TInteger;
+            }>>;
+        }>, Type.TObject<{
+            readonly state: Type.TLiteral<"partial">;
+            readonly byCurrency: Type.TArray<Type.TObject<{
+                readonly currency: Type.TString;
+                readonly amount: Type.TNumber;
+                readonly submissions: Type.TInteger;
+            }>>;
+            readonly unknownSubmissions: Type.TInteger;
+        }>]>;
+    }>;
+    readonly attempts: Type.TArray<Type.TObject<{
+        readonly agentId: Type.TString;
+        readonly attemptId: Type.TString;
+        /** Absent while the attempt has no recorded terminal outcome. */
+        readonly outcome: Type.TOptional<Type.TEnum<["succeeded", "failed", "cancelled", "unknown"]>>;
+        readonly totals: Type.TObject<{
+            /** Counted submission-owned records only: superseded records and inclusive Flow aggregates are excluded. */
+            readonly submissions: Type.TInteger;
+            readonly input: Type.TUnion<[Type.TObject<{
+                readonly state: Type.TLiteral<"unknown">;
+                readonly unknownSubmissions: Type.TInteger;
+            }>, Type.TObject<{
+                readonly state: Type.TLiteral<"known">;
+                readonly value: Type.TInteger;
+                readonly knownSubmissions: Type.TInteger;
+            }>, Type.TObject<{
+                readonly state: Type.TLiteral<"partial">;
+                readonly value: Type.TInteger;
+                readonly knownSubmissions: Type.TInteger;
+                readonly unknownSubmissions: Type.TInteger;
+            }>]>;
+            readonly output: Type.TUnion<[Type.TObject<{
+                readonly state: Type.TLiteral<"unknown">;
+                readonly unknownSubmissions: Type.TInteger;
+            }>, Type.TObject<{
+                readonly state: Type.TLiteral<"known">;
+                readonly value: Type.TInteger;
+                readonly knownSubmissions: Type.TInteger;
+            }>, Type.TObject<{
+                readonly state: Type.TLiteral<"partial">;
+                readonly value: Type.TInteger;
+                readonly knownSubmissions: Type.TInteger;
+                readonly unknownSubmissions: Type.TInteger;
+            }>]>;
+            readonly cacheRead: Type.TUnion<[Type.TObject<{
+                readonly state: Type.TLiteral<"unknown">;
+                readonly unknownSubmissions: Type.TInteger;
+            }>, Type.TObject<{
+                readonly state: Type.TLiteral<"known">;
+                readonly value: Type.TInteger;
+                readonly knownSubmissions: Type.TInteger;
+            }>, Type.TObject<{
+                readonly state: Type.TLiteral<"partial">;
+                readonly value: Type.TInteger;
+                readonly knownSubmissions: Type.TInteger;
+                readonly unknownSubmissions: Type.TInteger;
+            }>]>;
+            readonly cacheWrite: Type.TUnion<[Type.TObject<{
+                readonly state: Type.TLiteral<"unknown">;
+                readonly unknownSubmissions: Type.TInteger;
+            }>, Type.TObject<{
+                readonly state: Type.TLiteral<"known">;
+                readonly value: Type.TInteger;
+                readonly knownSubmissions: Type.TInteger;
+            }>, Type.TObject<{
+                readonly state: Type.TLiteral<"partial">;
+                readonly value: Type.TInteger;
+                readonly knownSubmissions: Type.TInteger;
+                readonly unknownSubmissions: Type.TInteger;
+            }>]>;
+            readonly reasoning: Type.TUnion<[Type.TObject<{
+                readonly state: Type.TLiteral<"unknown">;
+                readonly unknownSubmissions: Type.TInteger;
+            }>, Type.TObject<{
+                readonly state: Type.TLiteral<"known">;
+                readonly value: Type.TInteger;
+                readonly knownSubmissions: Type.TInteger;
+            }>, Type.TObject<{
+                readonly state: Type.TLiteral<"partial">;
+                readonly value: Type.TInteger;
+                readonly knownSubmissions: Type.TInteger;
+                readonly unknownSubmissions: Type.TInteger;
+            }>]>;
+            readonly totalTokens: Type.TUnion<[Type.TObject<{
+                readonly state: Type.TLiteral<"unknown">;
+                readonly unknownSubmissions: Type.TInteger;
+            }>, Type.TObject<{
+                readonly state: Type.TLiteral<"known">;
+                readonly value: Type.TInteger;
+                readonly knownSubmissions: Type.TInteger;
+            }>, Type.TObject<{
+                readonly state: Type.TLiteral<"partial">;
+                readonly value: Type.TInteger;
+                readonly knownSubmissions: Type.TInteger;
+                readonly unknownSubmissions: Type.TInteger;
+            }>]>;
+            readonly durationMs: Type.TUnion<[Type.TObject<{
+                readonly state: Type.TLiteral<"unknown">;
+                readonly unknownSubmissions: Type.TInteger;
+            }>, Type.TObject<{
+                readonly state: Type.TLiteral<"known">;
+                readonly value: Type.TInteger;
+                readonly knownSubmissions: Type.TInteger;
+            }>, Type.TObject<{
+                readonly state: Type.TLiteral<"partial">;
+                readonly value: Type.TInteger;
+                readonly knownSubmissions: Type.TInteger;
+                readonly unknownSubmissions: Type.TInteger;
+            }>]>;
+            readonly cost: Type.TUnion<[Type.TObject<{
+                readonly state: Type.TLiteral<"unknown">;
+                readonly unknownSubmissions: Type.TInteger;
+            }>, Type.TObject<{
+                readonly state: Type.TLiteral<"known">;
+                readonly byCurrency: Type.TArray<Type.TObject<{
+                    readonly currency: Type.TString;
+                    readonly amount: Type.TNumber;
+                    readonly submissions: Type.TInteger;
+                }>>;
+            }>, Type.TObject<{
+                readonly state: Type.TLiteral<"partial">;
+                readonly byCurrency: Type.TArray<Type.TObject<{
+                    readonly currency: Type.TString;
+                    readonly amount: Type.TNumber;
+                    readonly submissions: Type.TInteger;
+                }>>;
+                readonly unknownSubmissions: Type.TInteger;
+            }>]>;
+        }>;
+    }>>;
+    /** Appended correction records that replaced an earlier record; they are retained and contribute zero. */
+    readonly supersededRecords: Type.TInteger;
+    /** Inclusive Flow aggregate records: listed by search, contribute zero to totals. */
+    readonly inclusiveAggregateRecords: Type.TInteger;
+    readonly coverage: Type.TObject<{
+        readonly state: Type.TEnum<["captured", "redacted", "truncated", "unavailable", "not-applicable", "inferred"]>;
+        readonly reason: Type.TOptional<Type.TEnum<["secret_redacted", "policy_redacted", "size_limit", "producer_lost", "worker_exited_before_flush", "legacy_producer", "not_captured_by_version", "provider_hidden", "not_applicable", "derived_from_summary"]>>;
+    }>;
+}>;
+export type DhUsageResponse = Static<ReturnType<typeof usageResponseSchema>>;
+export declare const parseDhUsageResponse: (value: unknown) => {
+    readonly schema: "dh.usage-response/1";
+    readonly generationId: string;
+    readonly captureCutoff: string;
+    readonly totals: {
+        readonly submissions: number;
+        readonly input: {
+            readonly state: "unknown";
+            readonly unknownSubmissions: number;
+        } | {
+            readonly state: "known";
+            readonly value: number;
+            readonly knownSubmissions: number;
+        } | {
+            readonly state: "partial";
+            readonly value: number;
+            readonly knownSubmissions: number;
+            readonly unknownSubmissions: number;
+        };
+        readonly output: {
+            readonly state: "unknown";
+            readonly unknownSubmissions: number;
+        } | {
+            readonly state: "known";
+            readonly value: number;
+            readonly knownSubmissions: number;
+        } | {
+            readonly state: "partial";
+            readonly value: number;
+            readonly knownSubmissions: number;
+            readonly unknownSubmissions: number;
+        };
+        readonly cacheRead: {
+            readonly state: "unknown";
+            readonly unknownSubmissions: number;
+        } | {
+            readonly state: "known";
+            readonly value: number;
+            readonly knownSubmissions: number;
+        } | {
+            readonly state: "partial";
+            readonly value: number;
+            readonly knownSubmissions: number;
+            readonly unknownSubmissions: number;
+        };
+        readonly cacheWrite: {
+            readonly state: "unknown";
+            readonly unknownSubmissions: number;
+        } | {
+            readonly state: "known";
+            readonly value: number;
+            readonly knownSubmissions: number;
+        } | {
+            readonly state: "partial";
+            readonly value: number;
+            readonly knownSubmissions: number;
+            readonly unknownSubmissions: number;
+        };
+        readonly reasoning: {
+            readonly state: "unknown";
+            readonly unknownSubmissions: number;
+        } | {
+            readonly state: "known";
+            readonly value: number;
+            readonly knownSubmissions: number;
+        } | {
+            readonly state: "partial";
+            readonly value: number;
+            readonly knownSubmissions: number;
+            readonly unknownSubmissions: number;
+        };
+        readonly totalTokens: {
+            readonly state: "unknown";
+            readonly unknownSubmissions: number;
+        } | {
+            readonly state: "known";
+            readonly value: number;
+            readonly knownSubmissions: number;
+        } | {
+            readonly state: "partial";
+            readonly value: number;
+            readonly knownSubmissions: number;
+            readonly unknownSubmissions: number;
+        };
+        readonly durationMs: {
+            readonly state: "unknown";
+            readonly unknownSubmissions: number;
+        } | {
+            readonly state: "known";
+            readonly value: number;
+            readonly knownSubmissions: number;
+        } | {
+            readonly state: "partial";
+            readonly value: number;
+            readonly knownSubmissions: number;
+            readonly unknownSubmissions: number;
+        };
+        readonly cost: {
+            readonly state: "unknown";
+            readonly unknownSubmissions: number;
+        } | {
+            readonly state: "known";
+            readonly byCurrency: {
+                readonly currency: string;
+                readonly amount: number;
+                readonly submissions: number;
+            }[];
+        } | {
+            readonly state: "partial";
+            readonly byCurrency: {
+                readonly currency: string;
+                readonly amount: number;
+                readonly submissions: number;
+            }[];
+            readonly unknownSubmissions: number;
+        };
+    };
+    readonly attempts: {
+        readonly agentId: string;
+        readonly attemptId: string;
+        readonly outcome?: "cancelled" | "failed" | "succeeded" | "unknown" | undefined;
+        readonly totals: {
+            readonly submissions: number;
+            readonly input: {
+                readonly state: "unknown";
+                readonly unknownSubmissions: number;
+            } | {
+                readonly state: "known";
+                readonly value: number;
+                readonly knownSubmissions: number;
+            } | {
+                readonly state: "partial";
+                readonly value: number;
+                readonly knownSubmissions: number;
+                readonly unknownSubmissions: number;
+            };
+            readonly output: {
+                readonly state: "unknown";
+                readonly unknownSubmissions: number;
+            } | {
+                readonly state: "known";
+                readonly value: number;
+                readonly knownSubmissions: number;
+            } | {
+                readonly state: "partial";
+                readonly value: number;
+                readonly knownSubmissions: number;
+                readonly unknownSubmissions: number;
+            };
+            readonly cacheRead: {
+                readonly state: "unknown";
+                readonly unknownSubmissions: number;
+            } | {
+                readonly state: "known";
+                readonly value: number;
+                readonly knownSubmissions: number;
+            } | {
+                readonly state: "partial";
+                readonly value: number;
+                readonly knownSubmissions: number;
+                readonly unknownSubmissions: number;
+            };
+            readonly cacheWrite: {
+                readonly state: "unknown";
+                readonly unknownSubmissions: number;
+            } | {
+                readonly state: "known";
+                readonly value: number;
+                readonly knownSubmissions: number;
+            } | {
+                readonly state: "partial";
+                readonly value: number;
+                readonly knownSubmissions: number;
+                readonly unknownSubmissions: number;
+            };
+            readonly reasoning: {
+                readonly state: "unknown";
+                readonly unknownSubmissions: number;
+            } | {
+                readonly state: "known";
+                readonly value: number;
+                readonly knownSubmissions: number;
+            } | {
+                readonly state: "partial";
+                readonly value: number;
+                readonly knownSubmissions: number;
+                readonly unknownSubmissions: number;
+            };
+            readonly totalTokens: {
+                readonly state: "unknown";
+                readonly unknownSubmissions: number;
+            } | {
+                readonly state: "known";
+                readonly value: number;
+                readonly knownSubmissions: number;
+            } | {
+                readonly state: "partial";
+                readonly value: number;
+                readonly knownSubmissions: number;
+                readonly unknownSubmissions: number;
+            };
+            readonly durationMs: {
+                readonly state: "unknown";
+                readonly unknownSubmissions: number;
+            } | {
+                readonly state: "known";
+                readonly value: number;
+                readonly knownSubmissions: number;
+            } | {
+                readonly state: "partial";
+                readonly value: number;
+                readonly knownSubmissions: number;
+                readonly unknownSubmissions: number;
+            };
+            readonly cost: {
+                readonly state: "unknown";
+                readonly unknownSubmissions: number;
+            } | {
+                readonly state: "known";
+                readonly byCurrency: {
+                    readonly currency: string;
+                    readonly amount: number;
+                    readonly submissions: number;
+                }[];
+            } | {
+                readonly state: "partial";
+                readonly byCurrency: {
+                    readonly currency: string;
+                    readonly amount: number;
+                    readonly submissions: number;
+                }[];
+                readonly unknownSubmissions: number;
+            };
+        };
+    }[];
+    readonly supersededRecords: number;
+    readonly inclusiveAggregateRecords: number;
+    readonly coverage: {
+        readonly state: "captured" | "inferred" | "not-applicable" | "redacted" | "truncated" | "unavailable";
+        readonly reason?: "derived_from_summary" | "legacy_producer" | "not_applicable" | "not_captured_by_version" | "policy_redacted" | "producer_lost" | "provider_hidden" | "secret_redacted" | "size_limit" | "worker_exited_before_flush" | undefined;
+    };
+};
+declare function usageRecordSchema(): Type.TObject<{
+    readonly usageId: Type.TString;
+    readonly eventId: Type.TString;
+    readonly generationId: Type.TString;
+    readonly agentId: Type.TString;
+    /** Required for submission-owned records so failed and retried attempts stay separable. */
+    readonly attemptId: Type.TOptional<Type.TString>;
+    readonly origin: Type.TUnion<[Type.TObject<{
+        readonly owner: Type.TLiteral<"submission">;
+        readonly submissionId: Type.TString;
+    }>, Type.TObject<{
+        readonly owner: Type.TLiteral<"flow-aggregate">;
+        readonly inclusive: Type.TLiteral<true>;
+    }>]>;
+    readonly measurement: Type.TUnion<[Type.TObject<{
+        readonly state: Type.TLiteral<"unknown">;
+    }>, Type.TObject<{
+        readonly state: Type.TLiteral<"reported">;
+        readonly input: Type.TOptional<Type.TInteger>;
+        readonly output: Type.TOptional<Type.TInteger>;
+        readonly cacheRead: Type.TOptional<Type.TInteger>;
+        readonly cacheWrite: Type.TOptional<Type.TInteger>;
+        readonly reasoning: Type.TOptional<Type.TInteger>;
+        readonly totalTokens: Type.TOptional<Type.TInteger>;
+        readonly durationMs: Type.TOptional<Type.TInteger>;
+        readonly cost: Type.TUnion<[Type.TObject<{
+            readonly state: Type.TLiteral<"unknown">;
+        }>, Type.TObject<{
+            readonly state: Type.TLiteral<"known">;
+            readonly amount: Type.TNumber;
+            readonly currency: Type.TString;
+            readonly priceProvenance: Type.TString;
+        }>]>;
+    }>]>;
+    /** True only for a submission-owned record that no correction supersedes. */
+    readonly counted: Type.TBoolean;
+    readonly supersedesUsageId: Type.TOptional<Type.TString>;
+    /** Query-time pointer to the correction that replaced this record; the stored record is never mutated. */
+    readonly supersededByUsageId: Type.TOptional<Type.TString>;
+}>;
+export type DhUsageRecord = Static<ReturnType<typeof usageRecordSchema>>;
+export declare const parseDhUsageRecord: (value: unknown) => {
+    readonly usageId: string;
+    readonly eventId: string;
+    readonly generationId: string;
+    readonly agentId: string;
+    readonly attemptId?: string | undefined;
+    readonly origin: {
+        readonly owner: "submission";
+        readonly submissionId: string;
+    } | {
+        readonly owner: "flow-aggregate";
+        readonly inclusive: true;
+    };
+    readonly measurement: {
+        readonly state: "unknown";
+    } | {
+        readonly state: "reported";
+        readonly input?: number | undefined;
+        readonly output?: number | undefined;
+        readonly cacheRead?: number | undefined;
+        readonly cacheWrite?: number | undefined;
+        readonly reasoning?: number | undefined;
+        readonly totalTokens?: number | undefined;
+        readonly durationMs?: number | undefined;
+        readonly cost: {
+            readonly state: "unknown";
+        } | {
+            readonly state: "known";
+            readonly amount: number;
+            readonly currency: string;
+            readonly priceProvenance: string;
+        };
+    };
+    readonly counted: boolean;
+    readonly supersedesUsageId?: string | undefined;
+    readonly supersededByUsageId?: string | undefined;
+};
+declare function usageSearchPageSchema(): Type.TObject<{
+    readonly schema: Type.TLiteral<"dh.usage-search-page/1">;
+    readonly generationId: Type.TString;
+    readonly captureCutoff: Type.TString;
+    readonly filterSha256: Type.TString;
+    readonly nextCursor: Type.TUnion<[Type.TNull, Type.TString]>;
+    readonly items: Type.TArray<Type.TObject<{
+        readonly usageId: Type.TString;
+        readonly eventId: Type.TString;
+        readonly generationId: Type.TString;
+        readonly agentId: Type.TString;
+        /** Required for submission-owned records so failed and retried attempts stay separable. */
+        readonly attemptId: Type.TOptional<Type.TString>;
+        readonly origin: Type.TUnion<[Type.TObject<{
+            readonly owner: Type.TLiteral<"submission">;
+            readonly submissionId: Type.TString;
+        }>, Type.TObject<{
+            readonly owner: Type.TLiteral<"flow-aggregate">;
+            readonly inclusive: Type.TLiteral<true>;
+        }>]>;
+        readonly measurement: Type.TUnion<[Type.TObject<{
+            readonly state: Type.TLiteral<"unknown">;
+        }>, Type.TObject<{
+            readonly state: Type.TLiteral<"reported">;
+            readonly input: Type.TOptional<Type.TInteger>;
+            readonly output: Type.TOptional<Type.TInteger>;
+            readonly cacheRead: Type.TOptional<Type.TInteger>;
+            readonly cacheWrite: Type.TOptional<Type.TInteger>;
+            readonly reasoning: Type.TOptional<Type.TInteger>;
+            readonly totalTokens: Type.TOptional<Type.TInteger>;
+            readonly durationMs: Type.TOptional<Type.TInteger>;
+            readonly cost: Type.TUnion<[Type.TObject<{
+                readonly state: Type.TLiteral<"unknown">;
+            }>, Type.TObject<{
+                readonly state: Type.TLiteral<"known">;
+                readonly amount: Type.TNumber;
+                readonly currency: Type.TString;
+                readonly priceProvenance: Type.TString;
+            }>]>;
+        }>]>;
+        /** True only for a submission-owned record that no correction supersedes. */
+        readonly counted: Type.TBoolean;
+        readonly supersedesUsageId: Type.TOptional<Type.TString>;
+        /** Query-time pointer to the correction that replaced this record; the stored record is never mutated. */
+        readonly supersededByUsageId: Type.TOptional<Type.TString>;
+    }>>;
+}>;
+export type DhUsageSearchPage = Static<ReturnType<typeof usageSearchPageSchema>>;
+export declare const parseDhUsageSearchPage: (value: unknown) => {
+    readonly schema: "dh.usage-search-page/1";
+    readonly generationId: string;
+    readonly captureCutoff: string;
+    readonly filterSha256: string;
+    readonly nextCursor: string | null;
+    readonly items: {
+        readonly usageId: string;
+        readonly eventId: string;
+        readonly generationId: string;
+        readonly agentId: string;
+        readonly attemptId?: string | undefined;
+        readonly origin: {
+            readonly owner: "submission";
+            readonly submissionId: string;
+        } | {
+            readonly owner: "flow-aggregate";
+            readonly inclusive: true;
+        };
+        readonly measurement: {
+            readonly state: "unknown";
+        } | {
+            readonly state: "reported";
+            readonly input?: number | undefined;
+            readonly output?: number | undefined;
+            readonly cacheRead?: number | undefined;
+            readonly cacheWrite?: number | undefined;
+            readonly reasoning?: number | undefined;
+            readonly totalTokens?: number | undefined;
+            readonly durationMs?: number | undefined;
+            readonly cost: {
+                readonly state: "unknown";
+            } | {
+                readonly state: "known";
+                readonly amount: number;
+                readonly currency: string;
+                readonly priceProvenance: string;
+            };
+        };
+        readonly counted: boolean;
+        readonly supersedesUsageId?: string | undefined;
+        readonly supersededByUsageId?: string | undefined;
+    }[];
+};
+declare function usageCorrectionSchema(): Type.TObject<{
+    readonly schema: Type.TLiteral<"dh.usage-correction/1">;
+    /** The new record's id. Append-only: it never reuses the superseded id. */
+    readonly usageId: Type.TString;
+    readonly supersedesUsageId: Type.TString;
+    readonly generationId: Type.TString;
+    readonly agentId: Type.TString;
+    readonly attemptId: Type.TString;
+    readonly submissionId: Type.TString;
+    readonly reason: Type.TEnum<["provider-reconciliation", "price-correction", "capture-error", "duplicate-owner"]>;
+    readonly recordedAt: Type.TString;
+    /** Replacement measurement. An explicit unknown retracts a value; zero is never implied. */
+    readonly measurement: Type.TUnion<[Type.TObject<{
+        readonly state: Type.TLiteral<"unknown">;
+    }>, Type.TObject<{
+        readonly state: Type.TLiteral<"reported">;
+        readonly input: Type.TOptional<Type.TInteger>;
+        readonly output: Type.TOptional<Type.TInteger>;
+        readonly cacheRead: Type.TOptional<Type.TInteger>;
+        readonly cacheWrite: Type.TOptional<Type.TInteger>;
+        readonly reasoning: Type.TOptional<Type.TInteger>;
+        readonly totalTokens: Type.TOptional<Type.TInteger>;
+        readonly durationMs: Type.TOptional<Type.TInteger>;
+        readonly cost: Type.TUnion<[Type.TObject<{
+            readonly state: Type.TLiteral<"unknown">;
+        }>, Type.TObject<{
+            readonly state: Type.TLiteral<"known">;
+            readonly amount: Type.TNumber;
+            readonly currency: Type.TString;
+            readonly priceProvenance: Type.TString;
+        }>]>;
+    }>]>;
+}>;
+export type DhUsageCorrection = Static<ReturnType<typeof usageCorrectionSchema>>;
+export declare const parseDhUsageCorrection: (value: unknown) => {
+    readonly schema: "dh.usage-correction/1";
+    readonly usageId: string;
+    readonly supersedesUsageId: string;
+    readonly generationId: string;
+    readonly agentId: string;
+    readonly attemptId: string;
+    readonly submissionId: string;
+    readonly reason: "capture-error" | "duplicate-owner" | "price-correction" | "provider-reconciliation";
+    readonly recordedAt: string;
+    readonly measurement: {
+        readonly state: "unknown";
+    } | {
+        readonly state: "reported";
+        readonly input?: number | undefined;
+        readonly output?: number | undefined;
+        readonly cacheRead?: number | undefined;
+        readonly cacheWrite?: number | undefined;
+        readonly reasoning?: number | undefined;
+        readonly totalTokens?: number | undefined;
+        readonly durationMs?: number | undefined;
+        readonly cost: {
+            readonly state: "unknown";
+        } | {
+            readonly state: "known";
+            readonly amount: number;
+            readonly currency: string;
+            readonly priceProvenance: string;
+        };
+    };
+};
+/**
+ * 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 declare function assertDhUsageCorrection(correctionInput: unknown, supersededInput: unknown, existing?: readonly {
+    usageId: string;
+    supersedesUsageId?: string;
+}[]): void;
+/** DELETE has no body, so this is the path-derived request context, not a wire body. */
+export declare const parseDhGenerationDeleteRequest: (value: unknown) => {
+    readonly schema: "dh.generation-delete-request/1";
+    readonly generationId: string;
+};
+export type DhGenerationDeleteRequest = ReturnType<typeof parseDhGenerationDeleteRequest>;
+/** Path-derived like the delete request; release is explicit and authorized, never implied by deletion. */
+export declare const parseDhLegalHoldReleaseRequest: (value: unknown) => {
+    readonly schema: "dh.legal-hold-release-request/1";
+    readonly generationId: string;
+    readonly holdId: string;
+};
+export type DhLegalHoldReleaseRequest = ReturnType<typeof parseDhLegalHoldReleaseRequest>;
+/** Reason is an enum and matterRef an opaque reference: no free text, so a hold cannot carry content. */
+export declare const parseDhLegalHoldRequest: (value: unknown) => {
+    readonly schema: "dh.legal-hold-request/1";
+    readonly requestId: string;
+    readonly generationId: string;
+    readonly reasonCode: "audit" | "internal-investigation" | "litigation" | "regulatory-inquiry";
+    readonly matterRef?: string | undefined;
+};
+export type DhLegalHoldRequest = ReturnType<typeof parseDhLegalHoldRequest>;
+declare function legalHoldSchema(): Type.TObject<{
+    readonly schema: Type.TLiteral<"dh.legal-hold/1">;
+    readonly holdId: Type.TString;
+    readonly requestId: Type.TString;
+    readonly generationId: Type.TString;
+    readonly state: Type.TEnum<["active", "released"]>;
+    readonly reasonCode: Type.TEnum<["litigation", "regulatory-inquiry", "internal-investigation", "audit"]>;
+    readonly matterRef: Type.TOptional<Type.TString>;
+    readonly placedAt: Type.TString;
+    readonly releasedAt: Type.TOptional<Type.TString>;
+}>;
+export type DhLegalHold = Static<ReturnType<typeof legalHoldSchema>>;
+export declare const parseDhLegalHold: (value: unknown) => {
+    readonly schema: "dh.legal-hold/1";
+    readonly holdId: string;
+    readonly requestId: string;
+    readonly generationId: string;
+    readonly state: "active" | "released";
+    readonly reasonCode: "audit" | "internal-investigation" | "litigation" | "regulatory-inquiry";
+    readonly matterRef?: string | undefined;
+    readonly placedAt: string;
+    readonly releasedAt?: string | undefined;
+};
+declare function generationDeletionSchema(): Type.TObject<{
+    readonly schema: Type.TLiteral<"dh.generation-deletion/1">;
+    readonly generationId: Type.TString;
+    readonly state: Type.TEnum<["blocked-by-hold", "accepted", "claimed", "tombstoned"]>;
+    /** Evidence from the same locked snapshot as the state: held iff blocked-by-hold. */
+    readonly holdCheck: Type.TUnion<[Type.TObject<{
+        readonly state: Type.TLiteral<"clear">;
+    }>, Type.TObject<{
+        readonly state: Type.TLiteral<"held">;
+        readonly holdIds: Type.TArray<Type.TString>;
+    }>]>;
+    /** Durable deletion claim time; present exactly when claimed or tombstoned. */
+    readonly claimedAt: Type.TOptional<Type.TString>;
+}>;
+export type DhGenerationDeletion = Static<ReturnType<typeof generationDeletionSchema>>;
+export declare const parseDhGenerationDeletion: (value: unknown) => {
+    readonly schema: "dh.generation-deletion/1";
+    readonly generationId: string;
+    readonly state: "accepted" | "blocked-by-hold" | "claimed" | "tombstoned";
+    readonly holdCheck: {
+        readonly state: "clear";
+    } | {
+        readonly state: "held";
+        readonly holdIds: string[];
+    };
+    readonly claimedAt?: string | undefined;
+};
+/** A generation with a durable deletion claim cannot accept a new hold. */
+export declare function assertDhHoldPlacementAllowed(deletionInput: unknown): void;
+/**
+ * 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 declare function assertDhHoldPrecedence(deletionInput: unknown, holdInputs: readonly unknown[]): void;
+/** The body must match the route's path generation (and hold). Route params are validated by buildDhRoutePath. */
+export declare function assertDhRecordsRequestForPath(requestInput: unknown, params: Readonly<{
+    generationId: string;
+    holdId?: string;
+}>): void;
+export {};
+//# sourceMappingURL=trace-records.d.ts.map