@humain/humain-code-contracts 0.3.2 → 0.4.0

package/dist/flow-common.js

@@ -0,0 +1,282 @@
+import { Type } from "typebox";
+import { Compile } from "typebox/compile";
+/**
+ * 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 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 const FLOW_MODEL_ID_PATTERN = "^(?=.{1,128}$)[a-z0-9][a-z0-9_.:-]*(?:/[a-z0-9][a-z0-9_.:-]*)?$";
+export const FLOW_DIGEST_PATTERN = "^[a-f0-9]{64}$";
+const FLOW_TS_PATTERN = "^\\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\\d|3[01])T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d{1,9})?(?:Z|[+-](?:[01]\\d|2[0-3]):[0-5]\\d)$";
+export const FLOW_CONTRACT_ERROR_CODES = {
+    profile_invalid: "Invalid flow profile",
+    admission_invalid: "Invalid flow run admission",
+    event_invalid: "Invalid flow event",
+    command_invalid: "Invalid flow control command",
+    receipt_invalid: "Invalid flow control receipt",
+    status_invalid: "Invalid flow status",
+    digest_mismatch: "Flow digest mismatch",
+    digest_unverifiable: "Flow digest cannot be verified",
+    canonical_invalid: "Flow data cannot be canonicalized",
+    receipt_conflict: "Flow receipt conflicts with the first receipt",
+};
+/** Messages are constants chosen by contract code from `code`; rejected input is never echoed. */
+export class FlowContractError extends Error {
+    code;
+    constructor(code) {
+        super(FLOW_CONTRACT_ERROR_CODES[code]);
+        this.name = "FlowContractError";
+        this.code = code;
+    }
+}
+/** Union of string literals with a precise Static type (a mapped array would infer `never`). */
+export const lit = (...values) => Type.Union(values.map((value) => Type.Literal(value)));
+export const StrictObject = (properties) => Type.Object(properties, { additionalProperties: false });
+export const FlowIdSchema = Type.String({ pattern: FLOW_ID_PATTERN });
+export const FlowDigestSchema = Type.String({ pattern: FLOW_DIGEST_PATTERN });
+const DAYS_IN_MONTH = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+/** Pattern-valid timestamps only: rejects impossible calendar dates such as 2026-02-31 or a non-leap Feb 29. */
+function isRealCalendarDate(timestamp) {
+    const year = Number(timestamp.slice(0, 4));
+    const month = Number(timestamp.slice(5, 7));
+    const day = Number(timestamp.slice(8, 10));
+    const leap = (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+    return day <= (month === 2 && leap ? 29 : (DAYS_IN_MONTH[month - 1] ?? 0));
+}
+export const FlowTimestampSchema = Type.Refine(Type.String({ pattern: FLOW_TS_PATTERN }), isRealCalendarDate);
+export const FlowMicrousdSchema = Type.Integer({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER });
+export const FlowCountSchema = Type.Integer({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER });
+export const FlowPositiveIntSchema = Type.Integer({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER });
+export const FlowModelRefSchema = StrictObject({
+    provider: FlowIdSchema,
+    model: Type.String({ pattern: FLOW_MODEL_ID_PATTERN }),
+});
+export const FLOW_ROLES = [
+    "scout",
+    "worker",
+    "implementer",
+    "lead",
+    "lead_large",
+    "architect",
+    "reviewer",
+    "security_reviewer",
+    "qa",
+    "triage",
+];
+export const FlowRoleSchema = Type.Union([
+    Type.Literal("scout"),
+    Type.Literal("worker"),
+    Type.Literal("implementer"),
+    Type.Literal("lead"),
+    Type.Literal("lead_large"),
+    Type.Literal("architect"),
+    Type.Literal("reviewer"),
+    Type.Literal("security_reviewer"),
+    Type.Literal("qa"),
+    Type.Literal("triage"),
+]);
+/** `Partial<Record<FlowRole, T>>` as a strict object. */
+export const partialByRole = (schema) => StrictObject({
+    scout: Type.Optional(schema),
+    worker: Type.Optional(schema),
+    implementer: Type.Optional(schema),
+    lead: Type.Optional(schema),
+    lead_large: Type.Optional(schema),
+    architect: Type.Optional(schema),
+    reviewer: Type.Optional(schema),
+    security_reviewer: Type.Optional(schema),
+    qa: Type.Optional(schema),
+    triage: Type.Optional(schema),
+});
+export const FLOW_SIZES = ["small", "medium", "large"];
+export const FlowSizeSchema = Type.Union([Type.Literal("small"), Type.Literal("medium"), Type.Literal("large")]);
+export const FLOW_FAILURE_CLASSES = [
+    "provider_error",
+    "rate_limit",
+    "timeout",
+    "check_failed",
+    "review_rejected",
+    "qa_failed",
+    "budget_stop",
+    "cancelled",
+    "crash",
+    "unsafe_scope",
+    "stalled",
+    "config_invalid",
+    "internal",
+];
+export const FlowFailureClassSchema = Type.Union([
+    Type.Literal("provider_error"),
+    Type.Literal("rate_limit"),
+    Type.Literal("timeout"),
+    Type.Literal("check_failed"),
+    Type.Literal("review_rejected"),
+    Type.Literal("qa_failed"),
+    Type.Literal("budget_stop"),
+    Type.Literal("cancelled"),
+    Type.Literal("crash"),
+    Type.Literal("unsafe_scope"),
+    Type.Literal("stalled"),
+    Type.Literal("config_invalid"),
+    Type.Literal("internal"),
+]);
+export const FlowReasonClassSchema = Type.Union([FlowFailureClassSchema, Type.Literal("size_underestimated")]);
+export const FlowProfileRefSchema = StrictObject({
+    id: FlowIdSchema,
+    version: FlowPositiveIntSchema,
+    digest: FlowDigestSchema,
+});
+/** True when `sha256Hex(text)` equals `expected`. A missing, throwing or non-string hasher is a constant error. */
+export function verifyFlowDigest(hasher, text, expected) {
+    let actual;
+    try {
+        actual = hasher.sha256Hex(text);
+    }
+    catch {
+        throw new FlowContractError("digest_unverifiable");
+    }
+    if (typeof actual !== "string")
+        throw new FlowContractError("digest_unverifiable");
+    return actual === expected;
+}
+const MAX_SNAPSHOT_DEPTH = 16;
+const MAX_SNAPSHOT_NODES = 10_000;
+const MAX_SNAPSHOT_STRING = 65_536;
+function isIndexKey(key, length) {
+    const index = Number(key);
+    return Number.isInteger(index) && index >= 0 && index < length && String(index) === key;
+}
+function snapshotValue(value, depth, budget) {
+    budget.nodes += 1;
+    if (depth > MAX_SNAPSHOT_DEPTH || budget.nodes > MAX_SNAPSHOT_NODES)
+        throw new Error("bounds");
+    if (value === null || typeof value === "boolean")
+        return value;
+    if (typeof value === "string") {
+        if (value.length > MAX_SNAPSHOT_STRING || !value.isWellFormed())
+            throw new Error("string");
+        return value;
+    }
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new Error("number");
+        return value;
+    }
+    if (typeof value !== "object")
+        throw new Error("type");
+    if (Array.isArray(value)) {
+        const length = value.length;
+        if (length > MAX_SNAPSHOT_NODES)
+            throw new Error("bounds");
+        for (const key of Reflect.ownKeys(value)) {
+            if (typeof key !== "string" || (key !== "length" && !isIndexKey(key, length)))
+                throw new Error("array");
+        }
+        const out = [];
+        for (let index = 0; index < length; index += 1) {
+            const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+            if (descriptor === undefined || !("value" in descriptor))
+                throw new Error("array");
+            out.push(snapshotValue(descriptor.value, depth + 1, budget));
+        }
+        return out;
+    }
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== null && Object.getPrototypeOf(proto) !== null)
+        throw new Error("prototype");
+    const out = {};
+    for (const key of Reflect.ownKeys(value)) {
+        if (typeof key !== "string" || !key.isWellFormed())
+            throw new Error("key");
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (descriptor === undefined || !("value" in descriptor) || descriptor.enumerable !== true)
+            throw new Error("property");
+        if (descriptor.value === undefined)
+            continue; // JSON semantics: an undefined property is absent
+        Object.defineProperty(out, key, {
+            value: snapshotValue(descriptor.value, depth + 1, budget),
+            enumerable: true,
+            writable: true,
+            configurable: true,
+        });
+    }
+    return out;
+}
+/**
+ * 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 function snapshotFlowData(input) {
+    return snapshotValue(input, 0, { nodes: 0 });
+}
+/**
+ * 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 function parseFlowData(code, input, validate) {
+    const snapshot = trySnapshotFlowData(code, input);
+    if (!validate(snapshot))
+        throw new FlowContractError(code);
+    return snapshot;
+}
+/** `snapshotFlowData` whose every failure is a new `FlowContractError(code)`; the thrown value is not inspected. */
+export function trySnapshotFlowData(code, input) {
+    try {
+        return snapshotFlowData(input);
+    }
+    catch {
+        throw new FlowContractError(code);
+    }
+}
+export function compileFlow(schema) {
+    return Compile(schema);
+}
+export function modelKey(ref) {
+    return `${ref.provider}\u0000${ref.model}`;
+}
+export function hasDuplicateModels(refs) {
+    return new Set(refs.map(modelKey)).size !== refs.length;
+}
+/**
+ * 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 function canonicalFlowJson(value) {
+    if (value === null || typeof value === "boolean")
+        return JSON.stringify(value);
+    if (typeof value === "string") {
+        if (!value.isWellFormed())
+            throw new FlowContractError("canonical_invalid");
+        return JSON.stringify(value);
+    }
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new FlowContractError("canonical_invalid");
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value))
+        return `[${value.map(canonicalFlowJson).join(",")}]`;
+    if (typeof value !== "object")
+        throw new FlowContractError("canonical_invalid");
+    const record = value;
+    const parts = [];
+    for (const key of Object.keys(record).sort()) {
+        if (!key.isWellFormed())
+            throw new FlowContractError("canonical_invalid");
+        if (record[key] === undefined)
+            continue;
+        parts.push(`${JSON.stringify(key)}:${canonicalFlowJson(record[key])}`);
+    }
+    return `{${parts.join(",")}}`;
+}
+/** Canonical text of `doc` without the property `omit`. */
+export function canonicalWithout(doc, omit) {
+    const copy = { ...doc };
+    delete copy[omit];
+    return canonicalFlowJson(copy);
+}
+//# sourceMappingURL=flow-common.js.map

package/dist/flow-common.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-common.js","sourceRoot":"","sources":["../src/flow-common.ts"],"names":[],"mappings":"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","sourcesContent":["import { type Static, type TLiteral, type TSchema, type TUnion, Type } from \"typebox\";\nimport { Compile } from \"typebox/compile\";\n\n/**\n * Shared primitives for the `./flow-*` contract subpaths. TypeBox-only and browser-safe: no node:* imports,\n * no hashing (callers inject `sha256Hex`), no free-text string types.\n */\n\nexport const FLOW_ID_PATTERN = \"^[a-z0-9][a-z0-9_.:-]{0,127}$\";\n/** Model ids may be provider-qualified: lowercase, at most one `/`, no empty segment, <= 128 chars in total. */\nexport const FLOW_MODEL_ID_PATTERN = \"^(?=.{1,128}$)[a-z0-9][a-z0-9_.:-]*(?:/[a-z0-9][a-z0-9_.:-]*)?$\";\nexport const FLOW_DIGEST_PATTERN = \"^[a-f0-9]{64}$\";\nconst FLOW_TS_PATTERN =\n\t\"^\\\\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\\\\d|3[01])T(?:[01]\\\\d|2[0-3]):[0-5]\\\\d:[0-5]\\\\d(?:\\\\.\\\\d{1,9})?(?:Z|[+-](?:[01]\\\\d|2[0-3]):[0-5]\\\\d)$\";\n\nexport const FLOW_CONTRACT_ERROR_CODES = {\n\tprofile_invalid: \"Invalid flow profile\",\n\tadmission_invalid: \"Invalid flow run admission\",\n\tevent_invalid: \"Invalid flow event\",\n\tcommand_invalid: \"Invalid flow control command\",\n\treceipt_invalid: \"Invalid flow control receipt\",\n\tstatus_invalid: \"Invalid flow status\",\n\tdigest_mismatch: \"Flow digest mismatch\",\n\tdigest_unverifiable: \"Flow digest cannot be verified\",\n\tcanonical_invalid: \"Flow data cannot be canonicalized\",\n\treceipt_conflict: \"Flow receipt conflicts with the first receipt\",\n} as const;\nexport type FlowContractErrorCode = keyof typeof FLOW_CONTRACT_ERROR_CODES;\n\n/** Messages are constants chosen by contract code from `code`; rejected input is never echoed. */\nexport class FlowContractError extends Error {\n\treadonly code: FlowContractErrorCode;\n\tconstructor(code: FlowContractErrorCode) {\n\t\tsuper(FLOW_CONTRACT_ERROR_CODES[code]);\n\t\tthis.name = \"FlowContractError\";\n\t\tthis.code = code;\n\t}\n}\n\n/** Union of string literals with a precise Static type (a mapped array would infer `never`). */\nexport const lit = <const T extends readonly string[]>(...values: T) =>\n\tType.Union(values.map((value) => Type.Literal(value))) as unknown as TUnion<{\n\t\t-readonly [K in keyof T]: TLiteral<T[K]>;\n\t}>;\n\nexport const StrictObject = <const T extends Parameters<typeof Type.Object>[0]>(properties: T) =>\n\tType.Object(properties, { additionalProperties: false });\n\nexport const FlowIdSchema = Type.String({ pattern: FLOW_ID_PATTERN });\nexport const FlowDigestSchema = Type.String({ pattern: FLOW_DIGEST_PATTERN });\nconst DAYS_IN_MONTH = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31] as const;\n\n/** Pattern-valid timestamps only: rejects impossible calendar dates such as 2026-02-31 or a non-leap Feb 29. */\nfunction isRealCalendarDate(timestamp: string): boolean {\n\tconst year = Number(timestamp.slice(0, 4));\n\tconst month = Number(timestamp.slice(5, 7));\n\tconst day = Number(timestamp.slice(8, 10));\n\tconst leap = (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;\n\treturn day <= (month === 2 && leap ? 29 : (DAYS_IN_MONTH[month - 1] ?? 0));\n}\n\nexport const FlowTimestampSchema = Type.Refine(Type.String({ pattern: FLOW_TS_PATTERN }), isRealCalendarDate);\nexport const FlowMicrousdSchema = Type.Integer({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER });\nexport const FlowCountSchema = Type.Integer({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER });\nexport const FlowPositiveIntSchema = Type.Integer({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER });\n\nexport const FlowModelRefSchema = StrictObject({\n\tprovider: FlowIdSchema,\n\tmodel: Type.String({ pattern: FLOW_MODEL_ID_PATTERN }),\n});\nexport type FlowModelRef = Static<typeof FlowModelRefSchema>;\n\nexport const FLOW_ROLES = [\n\t\"scout\",\n\t\"worker\",\n\t\"implementer\",\n\t\"lead\",\n\t\"lead_large\",\n\t\"architect\",\n\t\"reviewer\",\n\t\"security_reviewer\",\n\t\"qa\",\n\t\"triage\",\n] as const;\nexport type FlowRole = (typeof FLOW_ROLES)[number];\nexport const FlowRoleSchema = Type.Union([\n\tType.Literal(\"scout\"),\n\tType.Literal(\"worker\"),\n\tType.Literal(\"implementer\"),\n\tType.Literal(\"lead\"),\n\tType.Literal(\"lead_large\"),\n\tType.Literal(\"architect\"),\n\tType.Literal(\"reviewer\"),\n\tType.Literal(\"security_reviewer\"),\n\tType.Literal(\"qa\"),\n\tType.Literal(\"triage\"),\n]);\n\n/** `Partial<Record<FlowRole, T>>` as a strict object. */\nexport const partialByRole = <T extends TSchema>(schema: T) =>\n\tStrictObject({\n\t\tscout: Type.Optional(schema),\n\t\tworker: Type.Optional(schema),\n\t\timplementer: Type.Optional(schema),\n\t\tlead: Type.Optional(schema),\n\t\tlead_large: Type.Optional(schema),\n\t\tarchitect: Type.Optional(schema),\n\t\treviewer: Type.Optional(schema),\n\t\tsecurity_reviewer: Type.Optional(schema),\n\t\tqa: Type.Optional(schema),\n\t\ttriage: Type.Optional(schema),\n\t});\n\nexport const FLOW_SIZES = [\"small\", \"medium\", \"large\"] as const;\nexport type FlowSize = (typeof FLOW_SIZES)[number];\nexport const FlowSizeSchema = Type.Union([Type.Literal(\"small\"), Type.Literal(\"medium\"), Type.Literal(\"large\")]);\n\nexport const FLOW_FAILURE_CLASSES = [\n\t\"provider_error\",\n\t\"rate_limit\",\n\t\"timeout\",\n\t\"check_failed\",\n\t\"review_rejected\",\n\t\"qa_failed\",\n\t\"budget_stop\",\n\t\"cancelled\",\n\t\"crash\",\n\t\"unsafe_scope\",\n\t\"stalled\",\n\t\"config_invalid\",\n\t\"internal\",\n] as const;\nexport type FlowFailureClass = (typeof FLOW_FAILURE_CLASSES)[number];\nexport const FlowFailureClassSchema = Type.Union([\n\tType.Literal(\"provider_error\"),\n\tType.Literal(\"rate_limit\"),\n\tType.Literal(\"timeout\"),\n\tType.Literal(\"check_failed\"),\n\tType.Literal(\"review_rejected\"),\n\tType.Literal(\"qa_failed\"),\n\tType.Literal(\"budget_stop\"),\n\tType.Literal(\"cancelled\"),\n\tType.Literal(\"crash\"),\n\tType.Literal(\"unsafe_scope\"),\n\tType.Literal(\"stalled\"),\n\tType.Literal(\"config_invalid\"),\n\tType.Literal(\"internal\"),\n]);\n\nexport const FlowReasonClassSchema = Type.Union([FlowFailureClassSchema, Type.Literal(\"size_underestimated\")]);\nexport type FlowReasonClass = Static<typeof FlowReasonClassSchema>;\n\nexport const FlowProfileRefSchema = StrictObject({\n\tid: FlowIdSchema,\n\tversion: FlowPositiveIntSchema,\n\tdigest: FlowDigestSchema,\n});\nexport type FlowProfileRefV1 = Static<typeof FlowProfileRefSchema>;\n\n/** Hasher injected by the host; keeps contracts free of node:crypto. Required by every digest-verifying parser. */\nexport type FlowDigestHasher = { sha256Hex: (text: string) => string };\n\n/** True when `sha256Hex(text)` equals `expected`. A missing, throwing or non-string hasher is a constant error. */\nexport function verifyFlowDigest(hasher: FlowDigestHasher, text: string, expected: string): boolean {\n\tlet actual: unknown;\n\ttry {\n\t\tactual = hasher.sha256Hex(text);\n\t} catch {\n\t\tthrow new FlowContractError(\"digest_unverifiable\");\n\t}\n\tif (typeof actual !== \"string\") throw new FlowContractError(\"digest_unverifiable\");\n\treturn actual === expected;\n}\n\nconst MAX_SNAPSHOT_DEPTH = 16;\nconst MAX_SNAPSHOT_NODES = 10_000;\nconst MAX_SNAPSHOT_STRING = 65_536;\n\nfunction isIndexKey(key: string, length: number): boolean {\n\tconst index = Number(key);\n\treturn Number.isInteger(index) && index >= 0 && index < length && String(index) === key;\n}\n\nfunction snapshotValue(value: unknown, depth: number, budget: { nodes: number }): unknown {\n\tbudget.nodes += 1;\n\tif (depth > MAX_SNAPSHOT_DEPTH || budget.nodes > MAX_SNAPSHOT_NODES) throw new Error(\"bounds\");\n\tif (value === null || typeof value === \"boolean\") return value;\n\tif (typeof value === \"string\") {\n\t\tif (value.length > MAX_SNAPSHOT_STRING || !value.isWellFormed()) throw new Error(\"string\");\n\t\treturn value;\n\t}\n\tif (typeof value === \"number\") {\n\t\tif (!Number.isFinite(value)) throw new Error(\"number\");\n\t\treturn value;\n\t}\n\tif (typeof value !== \"object\") throw new Error(\"type\");\n\tif (Array.isArray(value)) {\n\t\tconst length = value.length;\n\t\tif (length > MAX_SNAPSHOT_NODES) throw new Error(\"bounds\");\n\t\tfor (const key of Reflect.ownKeys(value)) {\n\t\t\tif (typeof key !== \"string\" || (key !== \"length\" && !isIndexKey(key, length))) throw new Error(\"array\");\n\t\t}\n\t\tconst out: unknown[] = [];\n\t\tfor (let index = 0; index < length; index += 1) {\n\t\t\tconst descriptor = Object.getOwnPropertyDescriptor(value, String(index));\n\t\t\tif (descriptor === undefined || !(\"value\" in descriptor)) throw new Error(\"array\");\n\t\t\tout.push(snapshotValue(descriptor.value, depth + 1, budget));\n\t\t}\n\t\treturn out;\n\t}\n\tconst proto = Object.getPrototypeOf(value);\n\tif (proto !== null && Object.getPrototypeOf(proto) !== null) throw new Error(\"prototype\");\n\tconst out: Record<string, unknown> = {};\n\tfor (const key of Reflect.ownKeys(value)) {\n\t\tif (typeof key !== \"string\" || !key.isWellFormed()) throw new Error(\"key\");\n\t\tconst descriptor = Object.getOwnPropertyDescriptor(value, key);\n\t\tif (descriptor === undefined || !(\"value\" in descriptor) || descriptor.enumerable !== true)\n\t\t\tthrow new Error(\"property\");\n\t\tif (descriptor.value === undefined) continue; // JSON semantics: an undefined property is absent\n\t\tObject.defineProperty(out, key, {\n\t\t\tvalue: snapshotValue(descriptor.value, depth + 1, budget),\n\t\t\tenumerable: true,\n\t\t\twritable: true,\n\t\t\tconfigurable: true,\n\t\t});\n\t}\n\treturn out;\n}\n\n/**\n * Plain-data snapshot of untrusted input: own enumerable data properties only (accessors, symbols, exotic and\n * non-plain objects are rejected), bounded depth/size, finite numbers, well-formed strings. Each property is read\n * exactly once, so the snapshot cannot change after it has been validated.\n */\nexport function snapshotFlowData(input: unknown): unknown {\n\treturn snapshotValue(input, 0, { nodes: 0 });\n}\n\n/**\n * Snapshot `input`, validate the snapshot, return the snapshot. Anything thrown while inspecting hostile input\n * (getters, proxy traps, forged FlowContractError objects) is discarded and replaced by a NEW constant `code` error;\n * the thrown value is never read, compared or rethrown. Only our own validation, after the snapshot exists, may throw.\n */\nexport function parseFlowData<T>(\n\tcode: FlowContractErrorCode,\n\tinput: unknown,\n\tvalidate: (snapshot: unknown) => snapshot is T,\n): T {\n\tconst snapshot = trySnapshotFlowData(code, input);\n\tif (!validate(snapshot)) throw new FlowContractError(code);\n\treturn snapshot;\n}\n\n/** `snapshotFlowData` whose every failure is a new `FlowContractError(code)`; the thrown value is not inspected. */\nexport function trySnapshotFlowData(code: FlowContractErrorCode, input: unknown): unknown {\n\ttry {\n\t\treturn snapshotFlowData(input);\n\t} catch {\n\t\tthrow new FlowContractError(code);\n\t}\n}\n\nexport function compileFlow<T extends TSchema>(schema: T) {\n\treturn Compile(schema);\n}\n\nexport function modelKey(ref: FlowModelRef): string {\n\treturn `${ref.provider}\\u0000${ref.model}`;\n}\n\nexport function hasDuplicateModels(refs: readonly FlowModelRef[]): boolean {\n\treturn new Set(refs.map(modelKey)).size !== refs.length;\n}\n\n/**\n * Canonical JSON text (RFC 8785 JCS subset): object keys sorted by UTF-16 code unit, no whitespace, `undefined`\n * properties omitted, numbers as ECMAScript Number toString (`JSON.stringify`; -0 prints 0, 1e21 prints 1e+21).\n * Lone surrogates (keys or strings), non-finite numbers and non-JSON values are rejected with a constant error.\n */\nexport function canonicalFlowJson(value: unknown): string {\n\tif (value === null || typeof value === \"boolean\") return JSON.stringify(value);\n\tif (typeof value === \"string\") {\n\t\tif (!value.isWellFormed()) throw new FlowContractError(\"canonical_invalid\");\n\t\treturn JSON.stringify(value);\n\t}\n\tif (typeof value === \"number\") {\n\t\tif (!Number.isFinite(value)) throw new FlowContractError(\"canonical_invalid\");\n\t\treturn JSON.stringify(value);\n\t}\n\tif (Array.isArray(value)) return `[${value.map(canonicalFlowJson).join(\",\")}]`;\n\tif (typeof value !== \"object\") throw new FlowContractError(\"canonical_invalid\");\n\tconst record = value as Record<string, unknown>;\n\tconst parts: string[] = [];\n\tfor (const key of Object.keys(record).sort()) {\n\t\tif (!key.isWellFormed()) throw new FlowContractError(\"canonical_invalid\");\n\t\tif (record[key] === undefined) continue;\n\t\tparts.push(`${JSON.stringify(key)}:${canonicalFlowJson(record[key])}`);\n\t}\n\treturn `{${parts.join(\",\")}}`;\n}\n\n/** Canonical text of `doc` without the property `omit`. */\nexport function canonicalWithout(doc: object, omit: string): string {\n\tconst copy: Record<string, unknown> = { ...doc };\n\tdelete copy[omit];\n\treturn canonicalFlowJson(copy);\n}\n"]}

package/dist/flow-control.d.ts

@@ -0,0 +1,107 @@
+import { type Static, Type } from "typebox";
+import type { FlowEventV1 } from "./flow-events.ts";
+export declare const FLOW_MESSAGE_MAX_LENGTH = 16000;
+export declare const FlowControlCommandV1Schema: Type.TUnion<[Type.TObject<{
+    readonly id: Type.TString;
+    readonly type: Type.TLiteral<"flow_status">;
+    readonly runId: Type.TOptional<Type.TString>;
+}>, Type.TObject<{
+    readonly id: Type.TString;
+    readonly type: Type.TLiteral<"flow_pause">;
+    readonly runId: Type.TString;
+}>, Type.TObject<{
+    readonly id: Type.TString;
+    readonly type: Type.TLiteral<"flow_resume">;
+    readonly runId: Type.TString;
+}>, Type.TObject<{
+    readonly id: Type.TString;
+    readonly type: Type.TLiteral<"flow_cancel">;
+    readonly runId: Type.TString;
+    readonly reason: Type.TUnion<[Type.TLiteral<"user">, Type.TLiteral<"budget">, Type.TLiteral<"shutdown">, Type.TLiteral<"kill_switch">]>;
+}>, Type.TObject<{
+    readonly id: Type.TString;
+    readonly type: Type.TLiteral<"flow_message">;
+    readonly runId: Type.TString;
+    readonly messageId: Type.TString;
+    readonly text: Type.TString;
+    readonly target: Type.TOptional<Type.TUnion<[Type.TObject<{
+        readonly taskId: Type.TString;
+    }>, Type.TLiteral<"lead">]>>;
+}>]>;
+export type FlowControlCommandV1 = Static<typeof FlowControlCommandV1Schema>;
+export declare const FlowControlReceiptV1Schema: Type.TObject<{
+    readonly type: Type.TLiteral<"response">;
+    readonly id: Type.TString;
+    readonly command: Type.TUnion<[Type.TLiteral<"flow_status">, Type.TLiteral<"flow_pause">, Type.TLiteral<"flow_resume">, Type.TLiteral<"flow_cancel">]>;
+    readonly state: Type.TUnion<[Type.TLiteral<"accepted">, Type.TLiteral<"applied">, Type.TLiteral<"rejected">]>;
+    readonly reason: Type.TOptional<Type.TUnion<[Type.TUnion<[Type.TLiteral<"provider_error">, Type.TLiteral<"rate_limit">, Type.TLiteral<"timeout">, Type.TLiteral<"check_failed">, Type.TLiteral<"review_rejected">, Type.TLiteral<"qa_failed">, Type.TLiteral<"budget_stop">, Type.TLiteral<"cancelled">, Type.TLiteral<"crash">, Type.TLiteral<"unsafe_scope">, Type.TLiteral<"stalled">, Type.TLiteral<"config_invalid">, Type.TLiteral<"internal">]>, Type.TLiteral<"size_underestimated">]>>;
+    readonly terminationConfirmed: Type.TOptional<Type.TBoolean>;
+}>;
+export type FlowControlReceiptV1 = Static<typeof FlowControlReceiptV1Schema>;
+/** `messageId` is carried so message receipts can be de-duplicated by it. */
+export declare const FlowMessageReceiptV1Schema: Type.TObject<{
+    readonly type: Type.TLiteral<"response">;
+    readonly id: Type.TString;
+    readonly command: Type.TLiteral<"flow_message">;
+    readonly messageId: Type.TString;
+    readonly state: Type.TUnion<[Type.TLiteral<"accepted">, Type.TLiteral<"applied">, Type.TLiteral<"rejected">]>;
+    readonly reason: Type.TOptional<Type.TUnion<[Type.TUnion<[Type.TLiteral<"provider_error">, Type.TLiteral<"rate_limit">, Type.TLiteral<"timeout">, Type.TLiteral<"check_failed">, Type.TLiteral<"review_rejected">, Type.TLiteral<"qa_failed">, Type.TLiteral<"budget_stop">, Type.TLiteral<"cancelled">, Type.TLiteral<"crash">, Type.TLiteral<"unsafe_scope">, Type.TLiteral<"stalled">, Type.TLiteral<"config_invalid">, Type.TLiteral<"internal">]>, Type.TLiteral<"size_underestimated">]>>;
+    readonly disposition: Type.TUnion<[Type.TLiteral<"live">, Type.TLiteral<"queued">, Type.TLiteral<"rejected">]>;
+    readonly deliveredTo: Type.TOptional<Type.TObject<{
+        readonly taskId: Type.TString;
+        readonly role: Type.TUnion<[Type.TLiteral<"scout">, Type.TLiteral<"worker">, Type.TLiteral<"implementer">, Type.TLiteral<"lead">, Type.TLiteral<"lead_large">, Type.TLiteral<"architect">, Type.TLiteral<"reviewer">, Type.TLiteral<"security_reviewer">, Type.TLiteral<"qa">, Type.TLiteral<"triage">]>;
+    }>>;
+}>;
+export type FlowMessageReceiptV1 = Static<typeof FlowMessageReceiptV1Schema>;
+export declare const FlowStatusV1Schema: Type.TObject<{
+    readonly runId: Type.TString;
+    readonly mode: Type.TUnion<[Type.TLiteral<"auto">, Type.TLiteral<"direct">]>;
+    readonly size: Type.TUnion<[Type.TLiteral<"small">, Type.TLiteral<"medium">, Type.TLiteral<"large">]>;
+    readonly state: Type.TUnion<[Type.TLiteral<"starting">, Type.TLiteral<"running">, Type.TLiteral<"paused">, Type.TLiteral<"cancelling">, Type.TLiteral<"settled">]>;
+    readonly stage: Type.TUnion<[Type.TLiteral<"sizing">, Type.TLiteral<"planning">, Type.TLiteral<"implementing">, Type.TLiteral<"reviewing">, Type.TLiteral<"qa">, Type.TLiteral<"settling">]>;
+    readonly agents: Type.TArray<Type.TObject<{
+        readonly taskId: Type.TString;
+        readonly role: Type.TUnion<[Type.TLiteral<"scout">, Type.TLiteral<"worker">, Type.TLiteral<"implementer">, Type.TLiteral<"lead">, Type.TLiteral<"lead_large">, Type.TLiteral<"architect">, Type.TLiteral<"reviewer">, Type.TLiteral<"security_reviewer">, Type.TLiteral<"qa">, Type.TLiteral<"triage">]>;
+        readonly model: Type.TObject<{
+            readonly provider: Type.TString;
+            readonly model: Type.TString;
+        }>;
+        readonly state: Type.TUnion<[Type.TLiteral<"pending">, Type.TLiteral<"running">, Type.TLiteral<"succeeded">, Type.TLiteral<"failed">, Type.TLiteral<"cancelled">]>;
+    }>>;
+    readonly budgetPct: Type.TNumber;
+    readonly warnings: Type.TArray<Type.TUnion<[Type.TUnion<[Type.TLiteral<"provider_error">, Type.TLiteral<"rate_limit">, Type.TLiteral<"timeout">, Type.TLiteral<"check_failed">, Type.TLiteral<"review_rejected">, Type.TLiteral<"qa_failed">, Type.TLiteral<"budget_stop">, Type.TLiteral<"cancelled">, Type.TLiteral<"crash">, Type.TLiteral<"unsafe_scope">, Type.TLiteral<"stalled">, Type.TLiteral<"config_invalid">, Type.TLiteral<"internal">]>, Type.TLiteral<"size_underestimated">]>>;
+}>;
+export type FlowStatusV1 = Static<typeof FlowStatusV1Schema>;
+/** Pushed frames (HC -> host). */
+export type FlowEventFrameV1 = {
+    type: "flow_event";
+    event: FlowEventV1;
+};
+export type FlowStatusFrameV1 = {
+    type: "flow_status";
+    status: FlowStatusV1;
+};
+/** Each parser validates a plain-data snapshot of `input` and returns the snapshot (never the caller's object). */
+export declare function parseFlowControlCommandV1(input: unknown): FlowControlCommandV1;
+export declare function parseFlowControlReceiptV1(input: unknown): FlowControlReceiptV1;
+export declare function parseFlowMessageReceiptV1(input: unknown): FlowMessageReceiptV1;
+export declare function parseFlowStatusV1(input: unknown): FlowStatusV1;
+export type FlowReceiptV1 = FlowControlReceiptV1 | FlowMessageReceiptV1;
+/**
+ * True when `next` is an allowed repeat of `prev`. Same command id => identical receipt. Same messageId
+ * (message receipts) => identical receipt apart from `id`. Unrelated receipts return false. Conflicts throw.
+ */
+export declare function checkFlowReceiptIdempotency(prev: FlowReceiptV1, next: FlowReceiptV1): boolean;
+export type FlowReceiptLedger = {
+    /**
+     * First receipt wins. A repeat (same command id, or same messageId under a new command id) returns a copy of the
+     * first receipt and binds the new command id to it; a conflicting repeat throws. Receipts are validated, stored
+     * frozen, and returned as deep copies.
+     */
+    record(receipt: FlowReceiptV1): {
+        replayed: boolean;
+        receipt: FlowReceiptV1;
+    };
+};
+export declare function createFlowReceiptLedger(): FlowReceiptLedger;
+//# sourceMappingURL=flow-control.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"flow-control.d.ts","sourceRoot":"","sources":["../src/flow-control.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAe5C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,eAAO,MAAM,uBAAuB,QAAS,CAAC;AAE9C,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;IAkBrC,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,MAAM,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAI7E,eAAO,MAAM,0BAA0B;;;;;;;EAOrC,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,MAAM,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE7E,6EAA6E;AAC7E,eAAO,MAAM,0BAA0B;;;;;;;;;;;;EASrC,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,MAAM,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE7E,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;EAiB7B,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE7D,kCAAkC;AAClC,MAAM,MAAM,gBAAgB,GAAG;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,WAAW,CAAA;CAAE,CAAC;AAC1E,MAAM,MAAM,iBAAiB,GAAG;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,YAAY,CAAA;CAAE,CAAC;AAO9E,mHAAmH;AACnH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,oBAAoB,CAS9E;AAUD,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,oBAAoB,CAE9E;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,oBAAoB,CAI9E;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY,CAE9D;AAED,MAAM,MAAM,aAAa,GAAG,oBAAoB,GAAG,oBAAoB,CAAC;AAWxE;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,aAAa,GAAG,OAAO,CAO7F;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC/B;;;;OAIG;IACH,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,aAAa,CAAA;KAAE,CAAC;CAC9E,CAAC;AAUF,wBAAgB,uBAAuB,IAAI,iBAAiB,CAgC3D"}

package/dist/flow-control.js

@@ -0,0 +1,144 @@
+import { Type } from "typebox";
+import { canonicalFlowJson, compileFlow, FlowContractError, FlowIdSchema, FlowModelRefSchema, FlowReasonClassSchema, FlowRoleSchema, FlowSizeSchema, lit, parseFlowData, StrictObject, trySnapshotFlowData, } from "./flow-common.js";
+export const FLOW_MESSAGE_MAX_LENGTH = 16_000;
+export const FlowControlCommandV1Schema = Type.Union([
+    StrictObject({ id: FlowIdSchema, type: Type.Literal("flow_status"), runId: Type.Optional(FlowIdSchema) }),
+    StrictObject({ id: FlowIdSchema, type: Type.Literal("flow_pause"), runId: FlowIdSchema }),
+    StrictObject({ id: FlowIdSchema, type: Type.Literal("flow_resume"), runId: FlowIdSchema }),
+    StrictObject({
+        id: FlowIdSchema,
+        type: Type.Literal("flow_cancel"),
+        runId: FlowIdSchema,
+        reason: lit("user", "budget", "shutdown", "kill_switch"),
+    }),
+    StrictObject({
+        id: FlowIdSchema,
+        type: Type.Literal("flow_message"),
+        runId: FlowIdSchema,
+        messageId: FlowIdSchema,
+        text: Type.String({ minLength: 1, maxLength: FLOW_MESSAGE_MAX_LENGTH }),
+        target: Type.Optional(Type.Union([StrictObject({ taskId: FlowIdSchema }), Type.Literal("lead")])),
+    }),
+]);
+const State = lit("accepted", "applied", "rejected");
+export const FlowControlReceiptV1Schema = StrictObject({
+    type: Type.Literal("response"),
+    id: FlowIdSchema,
+    command: lit("flow_status", "flow_pause", "flow_resume", "flow_cancel"),
+    state: State,
+    reason: Type.Optional(FlowReasonClassSchema),
+    terminationConfirmed: Type.Optional(Type.Boolean()),
+});
+/** `messageId` is carried so message receipts can be de-duplicated by it. */
+export const FlowMessageReceiptV1Schema = StrictObject({
+    type: Type.Literal("response"),
+    id: FlowIdSchema,
+    command: Type.Literal("flow_message"),
+    messageId: FlowIdSchema,
+    state: State,
+    reason: Type.Optional(FlowReasonClassSchema),
+    disposition: lit("live", "queued", "rejected"),
+    deliveredTo: Type.Optional(StrictObject({ taskId: FlowIdSchema, role: FlowRoleSchema })),
+});
+export const FlowStatusV1Schema = StrictObject({
+    runId: FlowIdSchema,
+    mode: lit("auto", "direct"),
+    size: FlowSizeSchema,
+    state: lit("starting", "running", "paused", "cancelling", "settled"),
+    stage: lit("sizing", "planning", "implementing", "reviewing", "qa", "settling"),
+    agents: Type.Array(StrictObject({
+        taskId: FlowIdSchema,
+        role: FlowRoleSchema,
+        model: FlowModelRefSchema,
+        state: lit("pending", "running", "succeeded", "failed", "cancelled"),
+    }), { maxItems: 64 }),
+    budgetPct: Type.Number({ minimum: 0, maximum: 100 }),
+    warnings: Type.Array(FlowReasonClassSchema, { maxItems: 16 }),
+});
+const CommandValidator = compileFlow(FlowControlCommandV1Schema);
+const ControlReceiptValidator = compileFlow(FlowControlReceiptV1Schema);
+const MessageReceiptValidator = compileFlow(FlowMessageReceiptV1Schema);
+const StatusValidator = compileFlow(FlowStatusV1Schema);
+/** Each parser validates a plain-data snapshot of `input` and returns the snapshot (never the caller's object). */
+export function parseFlowControlCommandV1(input) {
+    // TypeBox may count maxLength in code points; the contract is UTF-16 code units (String.length), like rpc.ts.
+    return parseFlowData("command_invalid", input, (value) => CommandValidator.Check(value) &&
+        (value.type !== "flow_message" || value.text.length <= FLOW_MESSAGE_MAX_LENGTH));
+}
+function isControlReceipt(value) {
+    // terminationConfirmed is meaningful for cancel only.
+    return (ControlReceiptValidator.Check(value) &&
+        (value.terminationConfirmed === undefined || value.command === "flow_cancel"));
+}
+export function parseFlowControlReceiptV1(input) {
+    return parseFlowData("receipt_invalid", input, isControlReceipt);
+}
+export function parseFlowMessageReceiptV1(input) {
+    return parseFlowData("receipt_invalid", input, (value) => MessageReceiptValidator.Check(value));
+}
+export function parseFlowStatusV1(input) {
+    return parseFlowData("status_invalid", input, (value) => StatusValidator.Check(value));
+}
+function withId(receipt, id) {
+    return { ...receipt, id };
+}
+function withoutId(receipt) {
+    const { id: _id, ...rest } = receipt;
+    return canonicalFlowJson(rest);
+}
+/**
+ * True when `next` is an allowed repeat of `prev`. Same command id => identical receipt. Same messageId
+ * (message receipts) => identical receipt apart from `id`. Unrelated receipts return false. Conflicts throw.
+ */
+export function checkFlowReceiptIdempotency(prev, next) {
+    const sameId = prev.id === next.id;
+    const sameMessage = "messageId" in prev && "messageId" in next && prev.messageId === next.messageId;
+    if (!sameId && !sameMessage)
+        return false;
+    const identical = sameId ? canonicalFlowJson(prev) === canonicalFlowJson(next) : withoutId(prev) === withoutId(next);
+    if (!identical)
+        throw new FlowContractError("receipt_conflict");
+    return true;
+}
+function deepFreeze(value) {
+    if (typeof value === "object" && value !== null) {
+        for (const child of Object.values(value))
+            deepFreeze(child);
+        Object.freeze(value);
+    }
+    return value;
+}
+export function createFlowReceiptLedger() {
+    // Every command id seen (including replay aliases) maps to the first receipt it was bound to.
+    const byCommand = new Map();
+    const byMessage = new Map();
+    return {
+        record(input) {
+            // Snapshot first: the discriminant is read from the snapshot, never from the caller's object.
+            const snapshot = trySnapshotFlowData("receipt_invalid", input);
+            const next = snapshot?.command === "flow_message"
+                ? parseFlowMessageReceiptV1(snapshot)
+                : parseFlowControlReceiptV1(snapshot);
+            const priors = [
+                byCommand.get(next.id),
+                "messageId" in next ? byMessage.get(next.messageId) : undefined,
+            ].filter((prior) => prior !== undefined);
+            for (const prior of priors) {
+                if (canonicalFlowJson(withId(prior, next.id)) !== canonicalFlowJson(next)) {
+                    throw new FlowContractError("receipt_conflict");
+                }
+            }
+            const first = priors[0];
+            if (first !== undefined) {
+                byCommand.set(next.id, first);
+                return { replayed: true, receipt: structuredClone(first) };
+            }
+            const stored = deepFreeze(next);
+            byCommand.set(stored.id, stored);
+            if ("messageId" in stored)
+                byMessage.set(stored.messageId, stored);
+            return { replayed: false, receipt: structuredClone(stored) };
+        },
+    };
+}
+//# sourceMappingURL=flow-control.js.map

package/dist/flow-control.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-control.js","sourceRoot":"","sources":["../src/flow-control.ts"],"names":[],"mappings":"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","sourcesContent":["import { type Static, Type } from \"typebox\";\nimport {\n\tcanonicalFlowJson,\n\tcompileFlow,\n\tFlowContractError,\n\tFlowIdSchema,\n\tFlowModelRefSchema,\n\tFlowReasonClassSchema,\n\tFlowRoleSchema,\n\tFlowSizeSchema,\n\tlit,\n\tparseFlowData,\n\tStrictObject,\n\ttrySnapshotFlowData,\n} from \"./flow-common.ts\";\nimport type { FlowEventV1 } from \"./flow-events.ts\";\n\nexport const FLOW_MESSAGE_MAX_LENGTH = 16_000;\n\nexport const FlowControlCommandV1Schema = Type.Union([\n\tStrictObject({ id: FlowIdSchema, type: Type.Literal(\"flow_status\"), runId: Type.Optional(FlowIdSchema) }),\n\tStrictObject({ id: FlowIdSchema, type: Type.Literal(\"flow_pause\"), runId: FlowIdSchema }),\n\tStrictObject({ id: FlowIdSchema, type: Type.Literal(\"flow_resume\"), runId: FlowIdSchema }),\n\tStrictObject({\n\t\tid: FlowIdSchema,\n\t\ttype: Type.Literal(\"flow_cancel\"),\n\t\trunId: FlowIdSchema,\n\t\treason: lit(\"user\", \"budget\", \"shutdown\", \"kill_switch\"),\n\t}),\n\tStrictObject({\n\t\tid: FlowIdSchema,\n\t\ttype: Type.Literal(\"flow_message\"),\n\t\trunId: FlowIdSchema,\n\t\tmessageId: FlowIdSchema,\n\t\ttext: Type.String({ minLength: 1, maxLength: FLOW_MESSAGE_MAX_LENGTH }),\n\t\ttarget: Type.Optional(Type.Union([StrictObject({ taskId: FlowIdSchema }), Type.Literal(\"lead\")])),\n\t}),\n]);\nexport type FlowControlCommandV1 = Static<typeof FlowControlCommandV1Schema>;\n\nconst State = lit(\"accepted\", \"applied\", \"rejected\");\n\nexport const FlowControlReceiptV1Schema = StrictObject({\n\ttype: Type.Literal(\"response\"),\n\tid: FlowIdSchema,\n\tcommand: lit(\"flow_status\", \"flow_pause\", \"flow_resume\", \"flow_cancel\"),\n\tstate: State,\n\treason: Type.Optional(FlowReasonClassSchema),\n\tterminationConfirmed: Type.Optional(Type.Boolean()),\n});\nexport type FlowControlReceiptV1 = Static<typeof FlowControlReceiptV1Schema>;\n\n/** `messageId` is carried so message receipts can be de-duplicated by it. */\nexport const FlowMessageReceiptV1Schema = StrictObject({\n\ttype: Type.Literal(\"response\"),\n\tid: FlowIdSchema,\n\tcommand: Type.Literal(\"flow_message\"),\n\tmessageId: FlowIdSchema,\n\tstate: State,\n\treason: Type.Optional(FlowReasonClassSchema),\n\tdisposition: lit(\"live\", \"queued\", \"rejected\"),\n\tdeliveredTo: Type.Optional(StrictObject({ taskId: FlowIdSchema, role: FlowRoleSchema })),\n});\nexport type FlowMessageReceiptV1 = Static<typeof FlowMessageReceiptV1Schema>;\n\nexport const FlowStatusV1Schema = StrictObject({\n\trunId: FlowIdSchema,\n\tmode: lit(\"auto\", \"direct\"),\n\tsize: FlowSizeSchema,\n\tstate: lit(\"starting\", \"running\", \"paused\", \"cancelling\", \"settled\"),\n\tstage: lit(\"sizing\", \"planning\", \"implementing\", \"reviewing\", \"qa\", \"settling\"),\n\tagents: Type.Array(\n\t\tStrictObject({\n\t\t\ttaskId: FlowIdSchema,\n\t\t\trole: FlowRoleSchema,\n\t\t\tmodel: FlowModelRefSchema,\n\t\t\tstate: lit(\"pending\", \"running\", \"succeeded\", \"failed\", \"cancelled\"),\n\t\t}),\n\t\t{ maxItems: 64 },\n\t),\n\tbudgetPct: Type.Number({ minimum: 0, maximum: 100 }),\n\twarnings: Type.Array(FlowReasonClassSchema, { maxItems: 16 }),\n});\nexport type FlowStatusV1 = Static<typeof FlowStatusV1Schema>;\n\n/** Pushed frames (HC -> host). */\nexport type FlowEventFrameV1 = { type: \"flow_event\"; event: FlowEventV1 };\nexport type FlowStatusFrameV1 = { type: \"flow_status\"; status: FlowStatusV1 };\n\nconst CommandValidator = compileFlow(FlowControlCommandV1Schema);\nconst ControlReceiptValidator = compileFlow(FlowControlReceiptV1Schema);\nconst MessageReceiptValidator = compileFlow(FlowMessageReceiptV1Schema);\nconst StatusValidator = compileFlow(FlowStatusV1Schema);\n\n/** Each parser validates a plain-data snapshot of `input` and returns the snapshot (never the caller's object). */\nexport function parseFlowControlCommandV1(input: unknown): FlowControlCommandV1 {\n\t// TypeBox may count maxLength in code points; the contract is UTF-16 code units (String.length), like rpc.ts.\n\treturn parseFlowData(\n\t\t\"command_invalid\",\n\t\tinput,\n\t\t(value): value is FlowControlCommandV1 =>\n\t\t\tCommandValidator.Check(value) &&\n\t\t\t(value.type !== \"flow_message\" || value.text.length <= FLOW_MESSAGE_MAX_LENGTH),\n\t);\n}\n\nfunction isControlReceipt(value: unknown): value is FlowControlReceiptV1 {\n\t// terminationConfirmed is meaningful for cancel only.\n\treturn (\n\t\tControlReceiptValidator.Check(value) &&\n\t\t(value.terminationConfirmed === undefined || value.command === \"flow_cancel\")\n\t);\n}\n\nexport function parseFlowControlReceiptV1(input: unknown): FlowControlReceiptV1 {\n\treturn parseFlowData(\"receipt_invalid\", input, isControlReceipt);\n}\n\nexport function parseFlowMessageReceiptV1(input: unknown): FlowMessageReceiptV1 {\n\treturn parseFlowData(\"receipt_invalid\", input, (value): value is FlowMessageReceiptV1 =>\n\t\tMessageReceiptValidator.Check(value),\n\t);\n}\n\nexport function parseFlowStatusV1(input: unknown): FlowStatusV1 {\n\treturn parseFlowData(\"status_invalid\", input, (value): value is FlowStatusV1 => StatusValidator.Check(value));\n}\n\nexport type FlowReceiptV1 = FlowControlReceiptV1 | FlowMessageReceiptV1;\n\nfunction withId(receipt: FlowReceiptV1, id: string): FlowReceiptV1 {\n\treturn { ...receipt, id };\n}\n\nfunction withoutId(receipt: FlowReceiptV1): string {\n\tconst { id: _id, ...rest } = receipt;\n\treturn canonicalFlowJson(rest);\n}\n\n/**\n * True when `next` is an allowed repeat of `prev`. Same command id => identical receipt. Same messageId\n * (message receipts) => identical receipt apart from `id`. Unrelated receipts return false. Conflicts throw.\n */\nexport function checkFlowReceiptIdempotency(prev: FlowReceiptV1, next: FlowReceiptV1): boolean {\n\tconst sameId = prev.id === next.id;\n\tconst sameMessage = \"messageId\" in prev && \"messageId\" in next && prev.messageId === next.messageId;\n\tif (!sameId && !sameMessage) return false;\n\tconst identical = sameId ? canonicalFlowJson(prev) === canonicalFlowJson(next) : withoutId(prev) === withoutId(next);\n\tif (!identical) throw new FlowContractError(\"receipt_conflict\");\n\treturn true;\n}\n\nexport type FlowReceiptLedger = {\n\t/**\n\t * First receipt wins. A repeat (same command id, or same messageId under a new command id) returns a copy of the\n\t * first receipt and binds the new command id to it; a conflicting repeat throws. Receipts are validated, stored\n\t * frozen, and returned as deep copies.\n\t */\n\trecord(receipt: FlowReceiptV1): { replayed: boolean; receipt: FlowReceiptV1 };\n};\n\nfunction deepFreeze<T>(value: T): T {\n\tif (typeof value === \"object\" && value !== null) {\n\t\tfor (const child of Object.values(value)) deepFreeze(child);\n\t\tObject.freeze(value);\n\t}\n\treturn value;\n}\n\nexport function createFlowReceiptLedger(): FlowReceiptLedger {\n\t// Every command id seen (including replay aliases) maps to the first receipt it was bound to.\n\tconst byCommand = new Map<string, FlowReceiptV1>();\n\tconst byMessage = new Map<string, FlowReceiptV1>();\n\treturn {\n\t\trecord(input) {\n\t\t\t// Snapshot first: the discriminant is read from the snapshot, never from the caller's object.\n\t\t\tconst snapshot = trySnapshotFlowData(\"receipt_invalid\", input);\n\t\t\tconst next =\n\t\t\t\t(snapshot as { command?: unknown } | null)?.command === \"flow_message\"\n\t\t\t\t\t? parseFlowMessageReceiptV1(snapshot)\n\t\t\t\t\t: parseFlowControlReceiptV1(snapshot);\n\t\t\tconst priors = [\n\t\t\t\tbyCommand.get(next.id),\n\t\t\t\t\"messageId\" in next ? byMessage.get(next.messageId) : undefined,\n\t\t\t].filter((prior): prior is FlowReceiptV1 => prior !== undefined);\n\t\t\tfor (const prior of priors) {\n\t\t\t\tif (canonicalFlowJson(withId(prior, next.id)) !== canonicalFlowJson(next)) {\n\t\t\t\t\tthrow new FlowContractError(\"receipt_conflict\");\n\t\t\t\t}\n\t\t\t}\n\t\t\tconst first = priors[0];\n\t\t\tif (first !== undefined) {\n\t\t\t\tbyCommand.set(next.id, first);\n\t\t\t\treturn { replayed: true, receipt: structuredClone(first) };\n\t\t\t}\n\t\t\tconst stored = deepFreeze(next);\n\t\t\tbyCommand.set(stored.id, stored);\n\t\t\tif (\"messageId\" in stored) byMessage.set(stored.messageId, stored);\n\t\t\treturn { replayed: false, receipt: structuredClone(stored) };\n\t\t},\n\t};\n}\n"]}