@humain/humain-code-contracts 0.3.2 → 0.4.0

package/CHANGELOG.md

@@ -1,6 +1,30 @@
 # Changelog
 
-## [Unreleased]
+## [0.4.0] - 2026-10-09
+
+### Added
+
+- Add the agent activity trace contracts (`./trace`): packed trace records, batch and control schemas, constant-diagnostic validation of hostile input, and artifact descriptors.
+- Add usage and legal-hold trace records, with checks for usage supersession and legal-hold precedence (0.3.3).
+- Add the public `./flow-common` subpath exporting `FLOW_ID_PATTERN`, `FLOW_DIGEST_PATTERN`, `FLOW_MODEL_ID_PATTERN`, `FlowContractError`, `FlowModelRef`/`FlowModelRefSchema` and `FlowProfileRefV1`/`FlowProfileRefSchema` (also re-exported from the package root).
+- Add `dh.usage-response/1`, `dh.usage-search-page/1` and `dh.usage-correction/1`
+  for submission-owned usage: failed-attempt usage is retained and summed,
+  inclusive Flow aggregates contribute zero, unknown usage or price stays explicit
+  unknown, and corrections append a record that names the record it supersedes.
+- Add `dh.generation-delete-request/1`, `dh.generation-deletion/1`,
+  `dh.legal-hold-request/1`, `dh.legal-hold/1` and
+  `dh.legal-hold-release-request/1`, with `assertDhHoldPrecedence` and
+  `assertDhHoldPlacementAllowed`: an active legal hold takes precedence over
+  deletion.
+- Add decisions D18 and D19 to the trace decision record, the `dh-records-v1`
+  conformance vectors and 8 schema IDs to the implemented registry (53 total).
+
+### Changed
+
+- Origin contractVersion stays 1. Existing `/2` DTOs, `DH_ROUTES` and
+  `dh.batch/1-proposal` are unchanged.
+- Flow `ModelRef.model` accepts provider-qualified ids (`anthropic/claude-sonnet`: lowercase, at most one `/`, at most 128 characters). `provider` keeps the plain id pattern.
+- Version `0.4.0`: the Flow contract line, built on 0.3.3. It keeps every 0.3.3 export, record and subpath (including the frozen `./trace` DTOs) unchanged and adds only the `./flow-*` subpaths and additive RPC Flow types.
 
 ## [0.3.1] - 2026-10-01
 

package/README.md

@@ -31,10 +31,19 @@ use `/2`. Parser success is not authentication, registry admission or durable re
 Callers supply authenticated ownership and committed amendment context for retry
 eligibility; missing authority cannot resolve an unknown terminal.
 
-Package version `0.3.2` records the disabled-by-default C0 technical
+Package version `0.3.3` records the disabled-by-default C0 technical
 resolution, not production approval. Batch ingress remains exclusively
 `dh.batch/1-proposal` (`resolved-synthetic-local`); origin contractVersion stays 1.
 
+Usage and records policy (0.3.3, additions only): `dh.usage-response/1`,
+`dh.usage-search-page/1` and the append-only `dh.usage-correction/1` expose
+submission-owned usage. Failed attempts are summed, inclusive Flow aggregates add
+zero, and unknown usage or price is an explicit unknown, never zero.
+`dh.generation-delete-request/1`, `dh.generation-deletion/1`,
+`dh.legal-hold-request/1`, `dh.legal-hold/1` and
+`dh.legal-hold-release-request/1` cover generation delete and legal holds; an
+active hold always wins over deletion. See decisions D18 and D19.
+
 Read pages and complete cursor bindings use `/2`. A `dh.snapshot-cutoff/1`
 committed receipt ordinal fixes the snapshot; captureCutoff is display time only.
 Bindings include the immutable generation root (or project mapping for lists),

package/dist/flow-admission.d.ts

@@ -0,0 +1,209 @@
+import { type Static, Type } from "typebox";
+import { type FlowDigestHasher } from "./flow-common.ts";
+export declare const FlowRunAdmissionV1Schema: Type.TObject<{
+    readonly schema: Type.TLiteral<"humain-flow-admission">;
+    readonly schemaVersion: Type.TLiteral<1>;
+    readonly runId: Type.TString;
+    readonly surface: Type.TUnion<[Type.TLiteral<"cli">, Type.TLiteral<"web">]>;
+    readonly tenantId: Type.TOptional<Type.TString>;
+    readonly projectId: Type.TOptional<Type.TString>;
+    readonly mode: Type.TUnion<[Type.TLiteral<"auto">, Type.TLiteral<"direct">]>;
+    readonly profile: Type.TObject<{
+        readonly schema: Type.TLiteral<"humain-flow-profile">;
+        readonly schemaVersion: Type.TLiteral<1>;
+        readonly id: Type.TString;
+        readonly version: Type.TInteger;
+        readonly digest: Type.TString;
+        readonly kind: Type.TUnion<[Type.TLiteral<"direct">, Type.TLiteral<"flow">]>;
+        readonly label: Type.TString;
+        readonly description: Type.TOptional<Type.TString>;
+        readonly direct: Type.TOptional<Type.TObject<{
+            readonly model: Type.TObject<{
+                readonly provider: Type.TString;
+                readonly model: Type.TString;
+            }>;
+            readonly fallbacks: Type.TArray<Type.TObject<{
+                readonly provider: Type.TString;
+                readonly model: Type.TString;
+            }>>;
+        }>>;
+        readonly roles: Type.TOptional<Type.TObject<{
+            readonly scout: Type.TOptional<Type.TObject<{
+                readonly primary: Type.TObject<{
+                    readonly provider: Type.TString;
+                    readonly model: Type.TString;
+                }>;
+                readonly backups: Type.TArray<Type.TObject<{
+                    readonly provider: Type.TString;
+                    readonly model: Type.TString;
+                }>>;
+                readonly effort: Type.TUnion<[Type.TLiteral<"low">, Type.TLiteral<"medium">, Type.TLiteral<"high">]>;
+            }>>;
+            readonly worker: Type.TOptional<Type.TObject<{
+                readonly primary: Type.TObject<{
+                    readonly provider: Type.TString;
+                    readonly model: Type.TString;
+                }>;
+                readonly backups: Type.TArray<Type.TObject<{
+                    readonly provider: Type.TString;
+                    readonly model: Type.TString;
+                }>>;
+                readonly effort: Type.TUnion<[Type.TLiteral<"low">, Type.TLiteral<"medium">, Type.TLiteral<"high">]>;
+            }>>;
+            readonly implementer: Type.TOptional<Type.TObject<{
+                readonly primary: Type.TObject<{
+                    readonly provider: Type.TString;
+                    readonly model: Type.TString;
+                }>;
+                readonly backups: Type.TArray<Type.TObject<{
+                    readonly provider: Type.TString;
+                    readonly model: Type.TString;
+                }>>;
+                readonly effort: Type.TUnion<[Type.TLiteral<"low">, Type.TLiteral<"medium">, Type.TLiteral<"high">]>;
+            }>>;
+            readonly lead: Type.TOptional<Type.TObject<{
+                readonly primary: Type.TObject<{
+                    readonly provider: Type.TString;
+                    readonly model: Type.TString;
+                }>;
+                readonly backups: Type.TArray<Type.TObject<{
+                    readonly provider: Type.TString;
+                    readonly model: Type.TString;
+                }>>;
+                readonly effort: Type.TUnion<[Type.TLiteral<"low">, Type.TLiteral<"medium">, Type.TLiteral<"high">]>;
+            }>>;
+            readonly lead_large: Type.TOptional<Type.TObject<{
+                readonly primary: Type.TObject<{
+                    readonly provider: Type.TString;
+                    readonly model: Type.TString;
+                }>;
+                readonly backups: Type.TArray<Type.TObject<{
+                    readonly provider: Type.TString;
+                    readonly model: Type.TString;
+                }>>;
+                readonly effort: Type.TUnion<[Type.TLiteral<"low">, Type.TLiteral<"medium">, Type.TLiteral<"high">]>;
+            }>>;
+            readonly architect: Type.TOptional<Type.TObject<{
+                readonly primary: Type.TObject<{
+                    readonly provider: Type.TString;
+                    readonly model: Type.TString;
+                }>;
+                readonly backups: Type.TArray<Type.TObject<{
+                    readonly provider: Type.TString;
+                    readonly model: Type.TString;
+                }>>;
+                readonly effort: Type.TUnion<[Type.TLiteral<"low">, Type.TLiteral<"medium">, Type.TLiteral<"high">]>;
+            }>>;
+            readonly reviewer: Type.TOptional<Type.TObject<{
+                readonly primary: Type.TObject<{
+                    readonly provider: Type.TString;
+                    readonly model: Type.TString;
+                }>;
+                readonly backups: Type.TArray<Type.TObject<{
+                    readonly provider: Type.TString;
+                    readonly model: Type.TString;
+                }>>;
+                readonly effort: Type.TUnion<[Type.TLiteral<"low">, Type.TLiteral<"medium">, Type.TLiteral<"high">]>;
+            }>>;
+            readonly security_reviewer: Type.TOptional<Type.TObject<{
+                readonly primary: Type.TObject<{
+                    readonly provider: Type.TString;
+                    readonly model: Type.TString;
+                }>;
+                readonly backups: Type.TArray<Type.TObject<{
+                    readonly provider: Type.TString;
+                    readonly model: Type.TString;
+                }>>;
+                readonly effort: Type.TUnion<[Type.TLiteral<"low">, Type.TLiteral<"medium">, Type.TLiteral<"high">]>;
+            }>>;
+            readonly qa: Type.TOptional<Type.TObject<{
+                readonly primary: Type.TObject<{
+                    readonly provider: Type.TString;
+                    readonly model: Type.TString;
+                }>;
+                readonly backups: Type.TArray<Type.TObject<{
+                    readonly provider: Type.TString;
+                    readonly model: Type.TString;
+                }>>;
+                readonly effort: Type.TUnion<[Type.TLiteral<"low">, Type.TLiteral<"medium">, Type.TLiteral<"high">]>;
+            }>>;
+            readonly triage: Type.TOptional<Type.TObject<{
+                readonly primary: Type.TObject<{
+                    readonly provider: Type.TString;
+                    readonly model: Type.TString;
+                }>;
+                readonly backups: Type.TArray<Type.TObject<{
+                    readonly provider: Type.TString;
+                    readonly model: Type.TString;
+                }>>;
+                readonly effort: Type.TUnion<[Type.TLiteral<"low">, Type.TLiteral<"medium">, Type.TLiteral<"high">]>;
+            }>>;
+        }>>;
+        readonly sizing: Type.TOptional<Type.TObject<{
+            readonly classifierPolicyId: Type.TString;
+            readonly thresholds: Type.TObject<{
+                readonly mediumAt: Type.TNumber;
+                readonly largeAt: Type.TNumber;
+            }>;
+            readonly triageRole: Type.TLiteral<"triage">;
+            readonly maxEscalations: Type.TUnion<[Type.TLiteral<0>, Type.TLiteral<1>]>;
+        }>>;
+        readonly limits: Type.TObject<{
+            readonly maxAgents: Type.TInteger;
+            readonly maxConcurrent: Type.TInteger;
+            readonly maxDepth: Type.TInteger;
+            readonly maxRetries: Type.TInteger;
+            readonly inactivityMs: Type.TInteger;
+            readonly ciWaitMs: Type.TInteger;
+        }>;
+        readonly spend: Type.TObject<{
+            readonly runCapMicrousd: Type.TInteger;
+            readonly warnAtPct: Type.TInteger;
+            readonly perRoleCapMicrousd: Type.TOptional<Type.TObject<{
+                readonly scout: Type.TOptional<Type.TInteger>;
+                readonly worker: Type.TOptional<Type.TInteger>;
+                readonly implementer: Type.TOptional<Type.TInteger>;
+                readonly lead: Type.TOptional<Type.TInteger>;
+                readonly lead_large: Type.TOptional<Type.TInteger>;
+                readonly architect: Type.TOptional<Type.TInteger>;
+                readonly reviewer: Type.TOptional<Type.TInteger>;
+                readonly security_reviewer: Type.TOptional<Type.TInteger>;
+                readonly qa: Type.TOptional<Type.TInteger>;
+                readonly triage: Type.TOptional<Type.TInteger>;
+            }>>;
+        }>;
+        readonly providers: Type.TOptional<Type.TObject<{
+            readonly preference: Type.TArray<Type.TString>;
+        }>>;
+        readonly approval: Type.TOptional<Type.TObject<{
+            readonly approvedBy: Type.TString;
+            readonly approvedAt: Type.TRefine<Type.TString>;
+        }>>;
+        readonly builtIn: Type.TOptional<Type.TLiteral<true>>;
+    }>;
+    readonly sizeOverride: Type.TOptional<Type.TUnion<[Type.TLiteral<"small">, Type.TLiteral<"medium">, Type.TLiteral<"large">]>>;
+    readonly directModel: Type.TOptional<Type.TObject<{
+        readonly provider: Type.TString;
+        readonly model: Type.TString;
+    }>>;
+    readonly spendCapMicrousd: Type.TInteger;
+    readonly inputs: Type.TArray<Type.TObject<{
+        readonly kind: Type.TUnion<[Type.TLiteral<"plan">, Type.TLiteral<"sketch">]>;
+        readonly ref: Type.TString;
+        readonly sha256: Type.TString;
+        readonly path: Type.TString;
+    }>>;
+    readonly issuedAt: Type.TRefine<Type.TString>;
+    readonly admissionDigest: Type.TString;
+}>;
+export type FlowRunAdmissionV1 = Static<typeof FlowRunAdmissionV1Schema>;
+/** Canonical text hashed (sha256 hex) to produce `admissionDigest`: the document without `admissionDigest`. */
+export declare function flowAdmissionDigestInput(doc: FlowRunAdmissionV1): string;
+/**
+ * SHAPE ONLY: validates structure and the embedded profile's cross-field rules but does NOT verify
+ * `admissionDigest` or the embedded profile digest. Prefer {@link parseFlowRunAdmissionV1}.
+ */
+export declare function parseFlowRunAdmissionV1Shape(input: unknown): FlowRunAdmissionV1;
+/** Shape validation plus verification of the embedded profile digest and `admissionDigest` (integrity, not authentication). */
+export declare function parseFlowRunAdmissionV1(input: unknown, hasher: FlowDigestHasher): FlowRunAdmissionV1;
+//# sourceMappingURL=flow-admission.d.ts.map

package/dist/flow-admission.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-admission.d.ts","sourceRoot":"","sources":["../src/flow-admission.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAIN,KAAK,gBAAgB,EAUrB,MAAM,kBAAkB,CAAC;AAG1B,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAuBnC,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAIzE,+GAA+G;AAC/G,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,kBAAkB,GAAG,MAAM,CAExE;AAYD;;;GAGG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,GAAG,kBAAkB,CAE/E;AAED,+HAA+H;AAC/H,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,gBAAgB,GAAG,kBAAkB,CASpG"}

package/dist/flow-admission.js

@@ -0,0 +1,59 @@
+import { Type } from "typebox";
+import { canonicalWithout, compileFlow, FlowContractError, FlowDigestSchema, FlowIdSchema, FlowMicrousdSchema, FlowModelRefSchema, FlowSizeSchema, FlowTimestampSchema, parseFlowData, StrictObject, verifyFlowDigest, } from "./flow-common.js";
+import { FlowProfileV1Schema, flowProfileDigestInput, parseFlowProfileV1Shape } from "./flow-profile.js";
+export const FlowRunAdmissionV1Schema = StrictObject({
+    schema: Type.Literal("humain-flow-admission"),
+    schemaVersion: Type.Literal(1),
+    runId: FlowIdSchema,
+    surface: Type.Union([Type.Literal("cli"), Type.Literal("web")]),
+    tenantId: Type.Optional(FlowIdSchema),
+    projectId: Type.Optional(FlowIdSchema),
+    mode: Type.Union([Type.Literal("auto"), Type.Literal("direct")]),
+    profile: FlowProfileV1Schema,
+    sizeOverride: Type.Optional(FlowSizeSchema),
+    directModel: Type.Optional(FlowModelRefSchema),
+    spendCapMicrousd: FlowMicrousdSchema,
+    inputs: Type.Array(StrictObject({
+        kind: Type.Union([Type.Literal("plan"), Type.Literal("sketch")]),
+        ref: FlowIdSchema,
+        sha256: FlowDigestSchema,
+        path: Type.String({ minLength: 1, maxLength: 1024 }),
+    }), { maxItems: 64 }),
+    issuedAt: FlowTimestampSchema,
+    admissionDigest: FlowDigestSchema,
+});
+const Validator = compileFlow(FlowRunAdmissionV1Schema);
+/** Canonical text hashed (sha256 hex) to produce `admissionDigest`: the document without `admissionDigest`. */
+export function flowAdmissionDigestInput(doc) {
+    return canonicalWithout(doc, "admissionDigest");
+}
+function isAdmissionShape(value) {
+    if (!Validator.Check(value))
+        return false;
+    try {
+        parseFlowProfileV1Shape(value.profile);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * SHAPE ONLY: validates structure and the embedded profile's cross-field rules but does NOT verify
+ * `admissionDigest` or the embedded profile digest. Prefer {@link parseFlowRunAdmissionV1}.
+ */
+export function parseFlowRunAdmissionV1Shape(input) {
+    return parseFlowData("admission_invalid", input, isAdmissionShape);
+}
+/** Shape validation plus verification of the embedded profile digest and `admissionDigest` (integrity, not authentication). */
+export function parseFlowRunAdmissionV1(input, hasher) {
+    const admission = parseFlowRunAdmissionV1Shape(input);
+    if (!verifyFlowDigest(hasher, flowProfileDigestInput(admission.profile), admission.profile.digest)) {
+        throw new FlowContractError("digest_mismatch");
+    }
+    if (!verifyFlowDigest(hasher, flowAdmissionDigestInput(admission), admission.admissionDigest)) {
+        throw new FlowContractError("digest_mismatch");
+    }
+    return admission;
+}
+//# sourceMappingURL=flow-admission.js.map

package/dist/flow-admission.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-admission.js","sourceRoot":"","sources":["../src/flow-admission.ts"],"names":[],"mappings":"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","sourcesContent":["import { type Static, Type } from \"typebox\";\nimport {\n\tcanonicalWithout,\n\tcompileFlow,\n\tFlowContractError,\n\ttype FlowDigestHasher,\n\tFlowDigestSchema,\n\tFlowIdSchema,\n\tFlowMicrousdSchema,\n\tFlowModelRefSchema,\n\tFlowSizeSchema,\n\tFlowTimestampSchema,\n\tparseFlowData,\n\tStrictObject,\n\tverifyFlowDigest,\n} from \"./flow-common.ts\";\nimport { FlowProfileV1Schema, flowProfileDigestInput, parseFlowProfileV1Shape } from \"./flow-profile.ts\";\n\nexport const FlowRunAdmissionV1Schema = StrictObject({\n\tschema: Type.Literal(\"humain-flow-admission\"),\n\tschemaVersion: Type.Literal(1),\n\trunId: FlowIdSchema,\n\tsurface: Type.Union([Type.Literal(\"cli\"), Type.Literal(\"web\")]),\n\ttenantId: Type.Optional(FlowIdSchema),\n\tprojectId: Type.Optional(FlowIdSchema),\n\tmode: Type.Union([Type.Literal(\"auto\"), Type.Literal(\"direct\")]),\n\tprofile: FlowProfileV1Schema,\n\tsizeOverride: Type.Optional(FlowSizeSchema),\n\tdirectModel: Type.Optional(FlowModelRefSchema),\n\tspendCapMicrousd: FlowMicrousdSchema,\n\tinputs: Type.Array(\n\t\tStrictObject({\n\t\t\tkind: Type.Union([Type.Literal(\"plan\"), Type.Literal(\"sketch\")]),\n\t\t\tref: FlowIdSchema,\n\t\t\tsha256: FlowDigestSchema,\n\t\t\tpath: Type.String({ minLength: 1, maxLength: 1024 }),\n\t\t}),\n\t\t{ maxItems: 64 },\n\t),\n\tissuedAt: FlowTimestampSchema,\n\tadmissionDigest: FlowDigestSchema,\n});\nexport type FlowRunAdmissionV1 = Static<typeof FlowRunAdmissionV1Schema>;\n\nconst Validator = compileFlow(FlowRunAdmissionV1Schema);\n\n/** Canonical text hashed (sha256 hex) to produce `admissionDigest`: the document without `admissionDigest`. */\nexport function flowAdmissionDigestInput(doc: FlowRunAdmissionV1): string {\n\treturn canonicalWithout(doc, \"admissionDigest\");\n}\n\nfunction isAdmissionShape(value: unknown): value is FlowRunAdmissionV1 {\n\tif (!Validator.Check(value)) return false;\n\ttry {\n\t\tparseFlowProfileV1Shape(value.profile);\n\t\treturn true;\n\t} catch {\n\t\treturn false;\n\t}\n}\n\n/**\n * SHAPE ONLY: validates structure and the embedded profile's cross-field rules but does NOT verify\n * `admissionDigest` or the embedded profile digest. Prefer {@link parseFlowRunAdmissionV1}.\n */\nexport function parseFlowRunAdmissionV1Shape(input: unknown): FlowRunAdmissionV1 {\n\treturn parseFlowData(\"admission_invalid\", input, isAdmissionShape);\n}\n\n/** Shape validation plus verification of the embedded profile digest and `admissionDigest` (integrity, not authentication). */\nexport function parseFlowRunAdmissionV1(input: unknown, hasher: FlowDigestHasher): FlowRunAdmissionV1 {\n\tconst admission = parseFlowRunAdmissionV1Shape(input);\n\tif (!verifyFlowDigest(hasher, flowProfileDigestInput(admission.profile), admission.profile.digest)) {\n\t\tthrow new FlowContractError(\"digest_mismatch\");\n\t}\n\tif (!verifyFlowDigest(hasher, flowAdmissionDigestInput(admission), admission.admissionDigest)) {\n\t\tthrow new FlowContractError(\"digest_mismatch\");\n\t}\n\treturn admission;\n}\n"]}

package/dist/flow-common.d.ts

@@ -0,0 +1,103 @@
+import { type Static, type TLiteral, type TSchema, type TUnion, Type } from "typebox";
+/**
+ * Shared primitives for the `./flow-*` contract subpaths. TypeBox-only and browser-safe: no node:* imports,
+ * no hashing (callers inject `sha256Hex`), no free-text string types.
+ */
+export declare const FLOW_ID_PATTERN = "^[a-z0-9][a-z0-9_.:-]{0,127}$";
+/** Model ids may be provider-qualified: lowercase, at most one `/`, no empty segment, <= 128 chars in total. */
+export declare const FLOW_MODEL_ID_PATTERN = "^(?=.{1,128}$)[a-z0-9][a-z0-9_.:-]*(?:/[a-z0-9][a-z0-9_.:-]*)?$";
+export declare const FLOW_DIGEST_PATTERN = "^[a-f0-9]{64}$";
+export declare const FLOW_CONTRACT_ERROR_CODES: {
+    readonly profile_invalid: "Invalid flow profile";
+    readonly admission_invalid: "Invalid flow run admission";
+    readonly event_invalid: "Invalid flow event";
+    readonly command_invalid: "Invalid flow control command";
+    readonly receipt_invalid: "Invalid flow control receipt";
+    readonly status_invalid: "Invalid flow status";
+    readonly digest_mismatch: "Flow digest mismatch";
+    readonly digest_unverifiable: "Flow digest cannot be verified";
+    readonly canonical_invalid: "Flow data cannot be canonicalized";
+    readonly receipt_conflict: "Flow receipt conflicts with the first receipt";
+};
+export type FlowContractErrorCode = keyof typeof FLOW_CONTRACT_ERROR_CODES;
+/** Messages are constants chosen by contract code from `code`; rejected input is never echoed. */
+export declare class FlowContractError extends Error {
+    readonly code: FlowContractErrorCode;
+    constructor(code: FlowContractErrorCode);
+}
+/** Union of string literals with a precise Static type (a mapped array would infer `never`). */
+export declare const lit: <const T extends readonly string[]>(...values: T) => TUnion<{ -readonly [K in keyof T]: TLiteral<T[K]>; }>;
+export declare const StrictObject: <const T extends Parameters<typeof Type.Object>[0]>(properties: T) => Type.TObject<T>;
+export declare const FlowIdSchema: Type.TString;
+export declare const FlowDigestSchema: Type.TString;
+export declare const FlowTimestampSchema: Type.TRefine<Type.TString>;
+export declare const FlowMicrousdSchema: Type.TInteger;
+export declare const FlowCountSchema: Type.TInteger;
+export declare const FlowPositiveIntSchema: Type.TInteger;
+export declare const FlowModelRefSchema: Type.TObject<{
+    readonly provider: Type.TString;
+    readonly model: Type.TString;
+}>;
+export type FlowModelRef = Static<typeof FlowModelRefSchema>;
+export declare const FLOW_ROLES: readonly ["scout", "worker", "implementer", "lead", "lead_large", "architect", "reviewer", "security_reviewer", "qa", "triage"];
+export type FlowRole = (typeof FLOW_ROLES)[number];
+export declare const FlowRoleSchema: TUnion<[TLiteral<"scout">, TLiteral<"worker">, TLiteral<"implementer">, TLiteral<"lead">, TLiteral<"lead_large">, TLiteral<"architect">, TLiteral<"reviewer">, TLiteral<"security_reviewer">, TLiteral<"qa">, TLiteral<"triage">]>;
+/** `Partial<Record<FlowRole, T>>` as a strict object. */
+export declare const partialByRole: <T extends TSchema>(schema: T) => Type.TObject<{
+    readonly scout: "~optional" extends keyof T ? T : Type.TOptional<T>;
+    readonly worker: "~optional" extends keyof T ? T : Type.TOptional<T>;
+    readonly implementer: "~optional" extends keyof T ? T : Type.TOptional<T>;
+    readonly lead: "~optional" extends keyof T ? T : Type.TOptional<T>;
+    readonly lead_large: "~optional" extends keyof T ? T : Type.TOptional<T>;
+    readonly architect: "~optional" extends keyof T ? T : Type.TOptional<T>;
+    readonly reviewer: "~optional" extends keyof T ? T : Type.TOptional<T>;
+    readonly security_reviewer: "~optional" extends keyof T ? T : Type.TOptional<T>;
+    readonly qa: "~optional" extends keyof T ? T : Type.TOptional<T>;
+    readonly triage: "~optional" extends keyof T ? T : Type.TOptional<T>;
+}>;
+export declare const FLOW_SIZES: readonly ["small", "medium", "large"];
+export type FlowSize = (typeof FLOW_SIZES)[number];
+export declare const FlowSizeSchema: TUnion<[TLiteral<"small">, TLiteral<"medium">, TLiteral<"large">]>;
+export declare const FLOW_FAILURE_CLASSES: readonly ["provider_error", "rate_limit", "timeout", "check_failed", "review_rejected", "qa_failed", "budget_stop", "cancelled", "crash", "unsafe_scope", "stalled", "config_invalid", "internal"];
+export type FlowFailureClass = (typeof FLOW_FAILURE_CLASSES)[number];
+export declare const FlowFailureClassSchema: TUnion<[TLiteral<"provider_error">, TLiteral<"rate_limit">, TLiteral<"timeout">, TLiteral<"check_failed">, TLiteral<"review_rejected">, TLiteral<"qa_failed">, TLiteral<"budget_stop">, TLiteral<"cancelled">, TLiteral<"crash">, TLiteral<"unsafe_scope">, TLiteral<"stalled">, TLiteral<"config_invalid">, TLiteral<"internal">]>;
+export declare const FlowReasonClassSchema: TUnion<[TUnion<[TLiteral<"provider_error">, TLiteral<"rate_limit">, TLiteral<"timeout">, TLiteral<"check_failed">, TLiteral<"review_rejected">, TLiteral<"qa_failed">, TLiteral<"budget_stop">, TLiteral<"cancelled">, TLiteral<"crash">, TLiteral<"unsafe_scope">, TLiteral<"stalled">, TLiteral<"config_invalid">, TLiteral<"internal">]>, TLiteral<"size_underestimated">]>;
+export type FlowReasonClass = Static<typeof FlowReasonClassSchema>;
+export declare const FlowProfileRefSchema: Type.TObject<{
+    readonly id: Type.TString;
+    readonly version: Type.TInteger;
+    readonly digest: Type.TString;
+}>;
+export type FlowProfileRefV1 = Static<typeof FlowProfileRefSchema>;
+/** Hasher injected by the host; keeps contracts free of node:crypto. Required by every digest-verifying parser. */
+export type FlowDigestHasher = {
+    sha256Hex: (text: string) => string;
+};
+/** True when `sha256Hex(text)` equals `expected`. A missing, throwing or non-string hasher is a constant error. */
+export declare function verifyFlowDigest(hasher: FlowDigestHasher, text: string, expected: string): boolean;
+/**
+ * Plain-data snapshot of untrusted input: own enumerable data properties only (accessors, symbols, exotic and
+ * non-plain objects are rejected), bounded depth/size, finite numbers, well-formed strings. Each property is read
+ * exactly once, so the snapshot cannot change after it has been validated.
+ */
+export declare function snapshotFlowData(input: unknown): unknown;
+/**
+ * Snapshot `input`, validate the snapshot, return the snapshot. Anything thrown while inspecting hostile input
+ * (getters, proxy traps, forged FlowContractError objects) is discarded and replaced by a NEW constant `code` error;
+ * the thrown value is never read, compared or rethrown. Only our own validation, after the snapshot exists, may throw.
+ */
+export declare function parseFlowData<T>(code: FlowContractErrorCode, input: unknown, validate: (snapshot: unknown) => snapshot is T): T;
+/** `snapshotFlowData` whose every failure is a new `FlowContractError(code)`; the thrown value is not inspected. */
+export declare function trySnapshotFlowData(code: FlowContractErrorCode, input: unknown): unknown;
+export declare function compileFlow<T extends TSchema>(schema: T): import("typebox/compile").Validator<{}, T, import("typebox").StaticType<[], "Encode", {}, {}, T>, import("typebox").StaticType<[], "Decode", {}, {}, T>>;
+export declare function modelKey(ref: FlowModelRef): string;
+export declare function hasDuplicateModels(refs: readonly FlowModelRef[]): boolean;
+/**
+ * Canonical JSON text (RFC 8785 JCS subset): object keys sorted by UTF-16 code unit, no whitespace, `undefined`
+ * properties omitted, numbers as ECMAScript Number toString (`JSON.stringify`; -0 prints 0, 1e21 prints 1e+21).
+ * Lone surrogates (keys or strings), non-finite numbers and non-JSON values are rejected with a constant error.
+ */
+export declare function canonicalFlowJson(value: unknown): string;
+/** Canonical text of `doc` without the property `omit`. */
+export declare function canonicalWithout(doc: object, omit: string): string;
+//# sourceMappingURL=flow-common.d.ts.map

package/dist/flow-common.d.ts.map

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