@mmnto/totem 1.88.0 → 1.90.0

package/dist/spine/frozen-split.d.ts

@@ -0,0 +1,541 @@
+import { z } from 'zod';
+import { type SplitArtifact } from './split.js';
+/** The content-addressed frozen-split reference form (codex fold-3). */
+export declare const SPLIT_REF_RE: RegExp;
+/** Filename of the frozen split artifact inside its gate dir (the tracked-public home). */
+export declare const FROZEN_SPLIT_FILE = "frozen-split.json";
+/**
+ * The selection-rule derivation PINS — the exact inputs the freeze derived the
+ * corpus from, recorded so materialize can RE-DERIVE the split and assert byte
+ * equality (detect-never-repair; re-derivation is a detector, never a source).
+ */
+export declare const SelectionPinsSchema: z.ZodObject<{
+    predicate: z.ZodEffects<z.ZodString, string, string>;
+    window: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+        type: z.ZodLiteral<"all">;
+    }, "strip", z.ZodTypeAny, {
+        type: "all";
+    }, {
+        type: "all";
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"bounded">;
+        n: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        type: "bounded";
+        n: number;
+    }, {
+        type: "bounded";
+        n: number;
+    }>]>;
+    codePathClassifier: z.ZodObject<{
+        includeGlobs: z.ZodArray<z.ZodString, "many">;
+        excludeGlobs: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        includeGlobs: string[];
+        excludeGlobs: string[];
+    }, {
+        includeGlobs: string[];
+        excludeGlobs: string[];
+    }>;
+    excludeRevertPairs: z.ZodBoolean;
+    excludeBotPrs: z.ZodBoolean;
+}, "strict", z.ZodTypeAny, {
+    predicate: string;
+    window: {
+        type: "all";
+    } | {
+        type: "bounded";
+        n: number;
+    };
+    codePathClassifier: {
+        includeGlobs: string[];
+        excludeGlobs: string[];
+    };
+    excludeRevertPairs: boolean;
+    excludeBotPrs: boolean;
+}, {
+    predicate: string;
+    window: {
+        type: "all";
+    } | {
+        type: "bounded";
+        n: number;
+    };
+    codePathClassifier: {
+        includeGlobs: string[];
+        excludeGlobs: string[];
+    };
+    excludeRevertPairs: boolean;
+    excludeBotPrs: boolean;
+}>;
+export type SelectionPins = z.infer<typeof SelectionPinsSchema>;
+/**
+ * The `totem spine freeze-split` INPUT (the curated freeze decisions). Everything
+ * else — `asOfCommit` (lc HEAD at freeze, Q3 derived-at-freeze), the corpus, the
+ * split membership, `frozenAt`, the stamps — is DERIVED at freeze and pinned in
+ * the artifact. `cutIndex` is the recorded build-choice under the held-out ≥ 0.5
+ * floor (#804).
+ */
+export declare const FreezeSplitParamsSchema: z.ZodObject<{
+    gate: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
+    repo: z.ZodEffects<z.ZodString, string, string>;
+    selectionRule: z.ZodObject<{
+        predicate: z.ZodEffects<z.ZodString, string, string>;
+        window: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+            type: z.ZodLiteral<"all">;
+        }, "strip", z.ZodTypeAny, {
+            type: "all";
+        }, {
+            type: "all";
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"bounded">;
+            n: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            type: "bounded";
+            n: number;
+        }, {
+            type: "bounded";
+            n: number;
+        }>]>;
+        codePathClassifier: z.ZodObject<{
+            includeGlobs: z.ZodArray<z.ZodString, "many">;
+            excludeGlobs: z.ZodArray<z.ZodString, "many">;
+        }, "strip", z.ZodTypeAny, {
+            includeGlobs: string[];
+            excludeGlobs: string[];
+        }, {
+            includeGlobs: string[];
+            excludeGlobs: string[];
+        }>;
+        excludeRevertPairs: z.ZodBoolean;
+        excludeBotPrs: z.ZodBoolean;
+    }, "strict", z.ZodTypeAny, {
+        predicate: string;
+        window: {
+            type: "all";
+        } | {
+            type: "bounded";
+            n: number;
+        };
+        codePathClassifier: {
+            includeGlobs: string[];
+            excludeGlobs: string[];
+        };
+        excludeRevertPairs: boolean;
+        excludeBotPrs: boolean;
+    }, {
+        predicate: string;
+        window: {
+            type: "all";
+        } | {
+            type: "bounded";
+            n: number;
+        };
+        codePathClassifier: {
+            includeGlobs: string[];
+            excludeGlobs: string[];
+        };
+        excludeRevertPairs: boolean;
+        excludeBotPrs: boolean;
+    }>;
+    split: z.ZodObject<{
+        cutIndex: z.ZodNumber;
+        excludedPrs: z.ZodDefault<z.ZodArray<z.ZodNumber, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        excludedPrs: number[];
+        cutIndex: number;
+    }, {
+        cutIndex: number;
+        excludedPrs?: number[] | undefined;
+    }>;
+    label: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    split: {
+        excludedPrs: number[];
+        cutIndex: number;
+    };
+    repo: string;
+    gate: string;
+    selectionRule: {
+        predicate: string;
+        window: {
+            type: "all";
+        } | {
+            type: "bounded";
+            n: number;
+        };
+        codePathClassifier: {
+            includeGlobs: string[];
+            excludeGlobs: string[];
+        };
+        excludeRevertPairs: boolean;
+        excludeBotPrs: boolean;
+    };
+    label?: string | undefined;
+}, {
+    split: {
+        cutIndex: number;
+        excludedPrs?: number[] | undefined;
+    };
+    repo: string;
+    gate: string;
+    selectionRule: {
+        predicate: string;
+        window: {
+            type: "all";
+        } | {
+            type: "bounded";
+            n: number;
+        };
+        codePathClassifier: {
+            includeGlobs: string[];
+            excludeGlobs: string[];
+        };
+        excludeRevertPairs: boolean;
+        excludeBotPrs: boolean;
+    };
+    label?: string | undefined;
+}>;
+export type FreezeSplitParams = z.infer<typeof FreezeSplitParamsSchema>;
+/**
+ * The frozen split artifact. `.strict()` — an unknown field is tamper/corruption,
+ * never silently carried. `split.frozenAt` is REQUIRED here (the freeze IS the
+ * event that mints it) even though `SplitArtifactSchema` keeps it optional for
+ * the mined/legacy shape.
+ */
+export declare const FrozenSplitArtifactSchema: z.ZodEffects<z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    gate: z.ZodEffects<z.ZodString, string, string>;
+    repo: z.ZodEffects<z.ZodString, string, string>;
+    selectionPins: z.ZodObject<{
+        predicate: z.ZodEffects<z.ZodString, string, string>;
+        window: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+            type: z.ZodLiteral<"all">;
+        }, "strip", z.ZodTypeAny, {
+            type: "all";
+        }, {
+            type: "all";
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"bounded">;
+            n: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            type: "bounded";
+            n: number;
+        }, {
+            type: "bounded";
+            n: number;
+        }>]>;
+        codePathClassifier: z.ZodObject<{
+            includeGlobs: z.ZodArray<z.ZodString, "many">;
+            excludeGlobs: z.ZodArray<z.ZodString, "many">;
+        }, "strip", z.ZodTypeAny, {
+            includeGlobs: string[];
+            excludeGlobs: string[];
+        }, {
+            includeGlobs: string[];
+            excludeGlobs: string[];
+        }>;
+        excludeRevertPairs: z.ZodBoolean;
+        excludeBotPrs: z.ZodBoolean;
+    }, "strict", z.ZodTypeAny, {
+        predicate: string;
+        window: {
+            type: "all";
+        } | {
+            type: "bounded";
+            n: number;
+        };
+        codePathClassifier: {
+            includeGlobs: string[];
+            excludeGlobs: string[];
+        };
+        excludeRevertPairs: boolean;
+        excludeBotPrs: boolean;
+    }, {
+        predicate: string;
+        window: {
+            type: "all";
+        } | {
+            type: "bounded";
+            n: number;
+        };
+        codePathClassifier: {
+            includeGlobs: string[];
+            excludeGlobs: string[];
+        };
+        excludeRevertPairs: boolean;
+        excludeBotPrs: boolean;
+    }>;
+    /** The resolved split (single home for membership + `frozenAt`; `asOfCommit` lives inside). */
+    split: z.ZodEffects<z.ZodObject<{
+        asOfCommit: z.ZodString;
+        trainPrs: z.ZodArray<z.ZodNumber, "many">;
+        heldOutPrs: z.ZodArray<z.ZodNumber, "many">;
+        excludedPrs: z.ZodArray<z.ZodNumber, "many">;
+        positiveControlPrs: z.ZodArray<z.ZodNumber, "many">;
+        negativeControlPrs: z.ZodArray<z.ZodNumber, "many">;
+        splitRule: z.ZodObject<{
+            predicate: z.ZodEffects<z.ZodString, string, string>;
+            cutIndex: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            predicate: string;
+            cutIndex: number;
+        }, {
+            predicate: string;
+            cutIndex: number;
+        }>;
+        frozenAt: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        asOfCommit: string;
+        trainPrs: number[];
+        heldOutPrs: number[];
+        excludedPrs: number[];
+        positiveControlPrs: number[];
+        negativeControlPrs: number[];
+        splitRule: {
+            predicate: string;
+            cutIndex: number;
+        };
+        frozenAt?: string | undefined;
+    }, {
+        asOfCommit: string;
+        trainPrs: number[];
+        heldOutPrs: number[];
+        excludedPrs: number[];
+        positiveControlPrs: number[];
+        negativeControlPrs: number[];
+        splitRule: {
+            predicate: string;
+            cutIndex: number;
+        };
+        frozenAt?: string | undefined;
+    }>, {
+        asOfCommit: string;
+        trainPrs: number[];
+        heldOutPrs: number[];
+        excludedPrs: number[];
+        positiveControlPrs: number[];
+        negativeControlPrs: number[];
+        splitRule: {
+            predicate: string;
+            cutIndex: number;
+        };
+        frozenAt?: string | undefined;
+    }, {
+        asOfCommit: string;
+        trainPrs: number[];
+        heldOutPrs: number[];
+        excludedPrs: number[];
+        positiveControlPrs: number[];
+        negativeControlPrs: number[];
+        splitRule: {
+            predicate: string;
+            cutIndex: number;
+        };
+        frozenAt?: string | undefined;
+    }>;
+    /**
+     * The LAST train PR's merge commit — the §5.4 author-sandbox root derives
+     * from THIS (an lc worktree at the cut boundary), never from an
+     * author-supplied knob (the judgedBy≠author independence axiom applied to
+     * config — codex sandbox note).
+     */
+    cutBoundarySha: z.ZodString;
+    /** sha256 over the canonical corpus enumeration (PRs + merge commits) — the (b) commitment leg. */
+    corpusIntegrity: z.ZodString;
+    /** Content address of the canonical payload (all fields except splitRef/freezeCommitment/label). */
+    splitRef: z.ZodString;
+    /** `sha256(splitRef · frozenAt · corpusIntegrity)` — chained into every ledger entry's material. */
+    freezeCommitment: z.ZodString;
+    /** Optional human handle — NEVER load-bearing (resolution goes by `splitRef`). */
+    label: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    split: {
+        asOfCommit: string;
+        trainPrs: number[];
+        heldOutPrs: number[];
+        excludedPrs: number[];
+        positiveControlPrs: number[];
+        negativeControlPrs: number[];
+        splitRule: {
+            predicate: string;
+            cutIndex: number;
+        };
+        frozenAt?: string | undefined;
+    };
+    schemaVersion: 1;
+    repo: string;
+    splitRef: string;
+    freezeCommitment: string;
+    gate: string;
+    selectionPins: {
+        predicate: string;
+        window: {
+            type: "all";
+        } | {
+            type: "bounded";
+            n: number;
+        };
+        codePathClassifier: {
+            includeGlobs: string[];
+            excludeGlobs: string[];
+        };
+        excludeRevertPairs: boolean;
+        excludeBotPrs: boolean;
+    };
+    cutBoundarySha: string;
+    corpusIntegrity: string;
+    label?: string | undefined;
+}, {
+    split: {
+        asOfCommit: string;
+        trainPrs: number[];
+        heldOutPrs: number[];
+        excludedPrs: number[];
+        positiveControlPrs: number[];
+        negativeControlPrs: number[];
+        splitRule: {
+            predicate: string;
+            cutIndex: number;
+        };
+        frozenAt?: string | undefined;
+    };
+    schemaVersion: 1;
+    repo: string;
+    splitRef: string;
+    freezeCommitment: string;
+    gate: string;
+    selectionPins: {
+        predicate: string;
+        window: {
+            type: "all";
+        } | {
+            type: "bounded";
+            n: number;
+        };
+        codePathClassifier: {
+            includeGlobs: string[];
+            excludeGlobs: string[];
+        };
+        excludeRevertPairs: boolean;
+        excludeBotPrs: boolean;
+    };
+    cutBoundarySha: string;
+    corpusIntegrity: string;
+    label?: string | undefined;
+}>, {
+    split: {
+        asOfCommit: string;
+        trainPrs: number[];
+        heldOutPrs: number[];
+        excludedPrs: number[];
+        positiveControlPrs: number[];
+        negativeControlPrs: number[];
+        splitRule: {
+            predicate: string;
+            cutIndex: number;
+        };
+        frozenAt?: string | undefined;
+    };
+    schemaVersion: 1;
+    repo: string;
+    splitRef: string;
+    freezeCommitment: string;
+    gate: string;
+    selectionPins: {
+        predicate: string;
+        window: {
+            type: "all";
+        } | {
+            type: "bounded";
+            n: number;
+        };
+        codePathClassifier: {
+            includeGlobs: string[];
+            excludeGlobs: string[];
+        };
+        excludeRevertPairs: boolean;
+        excludeBotPrs: boolean;
+    };
+    cutBoundarySha: string;
+    corpusIntegrity: string;
+    label?: string | undefined;
+}, {
+    split: {
+        asOfCommit: string;
+        trainPrs: number[];
+        heldOutPrs: number[];
+        excludedPrs: number[];
+        positiveControlPrs: number[];
+        negativeControlPrs: number[];
+        splitRule: {
+            predicate: string;
+            cutIndex: number;
+        };
+        frozenAt?: string | undefined;
+    };
+    schemaVersion: 1;
+    repo: string;
+    splitRef: string;
+    freezeCommitment: string;
+    gate: string;
+    selectionPins: {
+        predicate: string;
+        window: {
+            type: "all";
+        } | {
+            type: "bounded";
+            n: number;
+        };
+        codePathClassifier: {
+            includeGlobs: string[];
+            excludeGlobs: string[];
+        };
+        excludeRevertPairs: boolean;
+        excludeBotPrs: boolean;
+    };
+    cutBoundarySha: string;
+    corpusIntegrity: string;
+    label?: string | undefined;
+}>;
+export type FrozenSplitArtifact = z.infer<typeof FrozenSplitArtifactSchema>;
+/** The freeze-time inputs `assembleFrozenSplitArtifact` derives the stamps from. */
+export interface FrozenSplitAssembly {
+    gate: string;
+    repo: string;
+    selectionPins: SelectionPins;
+    split: SplitArtifact;
+    cutBoundarySha: string;
+    corpusIntegrity: string;
+    label?: string;
+}
+/**
+ * sha256 over the canonical corpus enumeration: the sorted PR list + each PR's
+ * merge commit. Deterministic from the pinned inputs; a post-freeze change to
+ * either (t7 content injection) breaks the commitment chain loudly.
+ */
+export declare function computeCorpusIntegrity(corpus: readonly number[], mergeCommitByPr: ReadonlyMap<number, string>): string;
+/** `split:<sha256(canonical payload)>` — codex fold-3: the ref is the artifact's content address. */
+export declare function computeFrozenSplitRef(a: FrozenSplitAssembly): string;
+/** The (b) hash-commitment: `sha256(splitRef · frozenAt · corpusIntegrity)` over the canonical tuple. */
+export declare function computeFreezeCommitment(splitRef: string, frozenAt: string, corpusIntegrity: string): string;
+/**
+ * Derive splitRef + freezeCommitment from the freeze-time inputs and return the
+ * validated artifact. Throws (Zod) if the assembly is malformed — a malformed
+ * freeze never produces an artifact (Tenet 4).
+ */
+export declare function assembleFrozenSplitArtifact(a: FrozenSplitAssembly): FrozenSplitArtifact;
+/** Result of recomputing an artifact's content address + commitment from its own fields. */
+export interface FreezeIntegrityCheck {
+    ok: boolean;
+    expectedSplitRef: string;
+    expectedCommitment: string;
+}
+/**
+ * Recompute splitRef + freezeCommitment from the artifact's own payload and
+ * compare — the pure half of tamper detection (any in-place edit to a pinned
+ * field breaks one or both). Consumers throw a distinct fail-loud row on `!ok`;
+ * this stays a sensor (Tenet 13).
+ */
+export declare function verifyFreezeIntegrity(artifact: FrozenSplitArtifact): FreezeIntegrityCheck;
+//# sourceMappingURL=frozen-split.d.ts.map

package/dist/spine/frozen-split.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frozen-split.d.ts","sourceRoot":"","sources":["../../src/spine/frozen-split.ts"],"names":[],"mappings":"AA6BA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,KAAK,aAAa,EAAuB,MAAM,YAAY,CAAC;AASrE,wEAAwE;AACxE,eAAO,MAAM,YAAY,QAAyB,CAAC;AAEnD,2FAA2F;AAC3F,eAAO,MAAM,iBAAiB,sBAAsB,CAAC;AAErD;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAcrB,CAAC;AACZ,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAazB,CAAC;AACZ,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAMlC,+FAA+F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAE/F;;;;;OAKG;;IAEH,mGAAmG;;IAEnG,oGAAoG;;IAEpG,oGAAoG;;IAEpG,kFAAkF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAYlF,CAAC;AACL,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,oFAAoF;AACpF,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,aAAa,CAAC;IAC7B,KAAK,EAAE,aAAa,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,eAAe,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GAC3C,MAAM,CAKR;AAeD,qGAAqG;AACrG,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,mBAAmB,GAAG,MAAM,CAIpE;AAED,yGAAyG;AACzG,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,MAAM,GACtB,MAAM,CAER;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,CAAC,EAAE,mBAAmB,GAAG,mBAAmB,CAsBvF;AAED,4FAA4F;AAC5F,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,OAAO,CAAC;IACZ,gBAAgB,EAAE,MAAM,CAAC;IACzB,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,mBAAmB,GAAG,oBAAoB,CAsBzF"}