@intentius/chant 0.62.0 → 0.64.0

package/src/fold/fold.ts

@@ -21,6 +21,16 @@ import { isFoldableHelperName } from "./foldable-helpers";
 /**
  * fold — static AST value reducer (chant #1026/#1021/#1024, part of epic #1019)
  *
+ * Implements judgment J1 (`F-Eval-*`, `spec/judgments.md`) and the value domain
+ * (`F-Val-*`, `spec/values.md`) of the TypeScript-as-Data specification at
+ * https://github.com/INTENTIUS/typescript-as-data, which is normative for the
+ * subset since INTENTIUS/typescript-as-data#33. Each branch of {@link fold}
+ * below is one F-Eval rule — the identifier branch is F-Eval-Ident, the
+ * property-access branch F-Eval-Member (its numbered steps match), the call
+ * branch F-Eval-CallHelper / CallIntrinsic / CallLocal / CallEager / CallMethod
+ * in that order — and the envelope types here are F-Val-Domain's cases.
+ * Subset changes go spec-first; see subset.ts's module doc for the process.
+ *
  * Reduces a single-file TypeScript expression AST to a value with NO
  * module execution. The node-kind/operator/key subset it covers — literals,
  * template interpolation, object/array literals (incl. spread), `const`
@@ -784,6 +794,87 @@ function attrRefOnFoldedResource(
   );
 }
 
+/**
+ * chant #2328 — the marker an optional-chain link leaves behind when it
+ * short-circuits, carried up the rest of the chain and unwrapped to
+ * `undefined` at its end.
+ *
+ * `a?.b` on a nullish `a` is DEFINED to be `undefined` in JavaScript, and so
+ * is every link after it: `a?.b.c` is `undefined` too, not a `TypeError` on
+ * `undefined.c`. A non-optional `a.b` on a nullish `a` throws. Both shapes
+ * reach the property-access branch below with the same nullish object, so
+ * telling them apart needs the answer to "did an EARLIER link short-circuit?"
+ * — which a plain `undefined` return cannot carry, because a genuine
+ * `undefined` looks identical: `({}).b.c` is `undefined` at the first link
+ * and running it DOES throw at the second.
+ *
+ * This marker carries it. {@link shortCircuited} produces it only where
+ * {@link continuesOptionalChain} says the parent node is the next link of the
+ * same chain, so the parent always consumes it, and turns it back into
+ * `undefined` at the last link — which is where JavaScript's own
+ * short-circuit lands. It never escapes {@link fold}'s return to a caller.
+ */
+const CHAIN_SHORT_CIRCUIT = Symbol("chant.fold.optional-chain-short-circuit");
+
+/** True when `value` is the {@link CHAIN_SHORT_CIRCUIT} marker. */
+function isChainShortCircuit(value: FoldedValue): boolean {
+  return (value as unknown) === CHAIN_SHORT_CIRCUIT;
+}
+
+/**
+ * The value a chain that short-circuited at or before `node` has AT `node`:
+ * the {@link CHAIN_SHORT_CIRCUIT} marker while another link follows,
+ * `undefined` once `node` is the last one.
+ */
+function shortCircuited(node: ts.Expression): FoldedValue {
+  return continuesOptionalChain(node) ? (CHAIN_SHORT_CIRCUIT as unknown as FoldedValue) : undefined;
+}
+
+/**
+ * True when `node`'s parent is the next link of the SAME optional chain, so a
+ * short-circuit at `node` must keep travelling rather than becoming
+ * `undefined` here.
+ *
+ * TypeScript flags every access/call node after a `?.` as part of that chain
+ * and stops flagging at the first construct that ends it, so this needs no
+ * bookkeeping of its own: `(a?.b).c` — where the parentheses end the chain
+ * and running really does throw on `.c` — is not a continuation, and neither
+ * is `(a?.b as X).c`. A `NonNullChain` (`a?.b!.c`) is transparent, exactly as
+ * {@link fold}'s own non-null unwrapping is.
+ */
+function continuesOptionalChain(node: ts.Node): boolean {
+  const parent: ts.Node | undefined = node.parent;
+  if (parent === undefined) return false;
+  if (ts.isNonNullExpression(parent) && ts.isOptionalChain(parent)) return continuesOptionalChain(parent);
+  return (
+    (ts.isPropertyAccessExpression(parent) || ts.isElementAccessExpression(parent) || ts.isCallExpression(parent)) &&
+    parent.expression === node &&
+    ts.isOptionalChain(parent)
+  );
+}
+
+/**
+ * chant #2328 — a property or element read whose object folded to `null` or
+ * `undefined`. Folding it to `undefined` (what both branches did from #1026
+ * until now) drops the property from the output and lets the build carry on,
+ * while RUNNING the same expression throws `TypeError: Cannot read properties
+ * of undefined` — the fold/run disagreement #1535 already ruled unacceptable
+ * one branch over, where an attribute read on a resource envelope folded away
+ * and a trust policy shipped as `Principal: {}`.
+ *
+ * So it refuses, and the file falls back to run — where the real `TypeError`
+ * happens at the line that caused it, naming the property the way it would
+ * without `--fold` at all. The usual cause is a typo in a nested path
+ * (`cfg.nett.vpcId`); a genuinely optional read says so with `?.`, which
+ * short-circuits above instead of reaching this message.
+ */
+function nullishAccessMessage(member: string, obj: null | undefined): string {
+  return (
+    `property "${member}" read on ${String(obj)} is not foldable — running this expression throws a TypeError, ` +
+    `so the file falls back to run (write \`?.\` if the value is genuinely optional)`
+  );
+}
+
 /**
  * True when `node` is an identifier, or a dotted/bracketed access chain
  * rooted at an identifier, that neither `consts` nor `externals` can resolve
@@ -1074,7 +1165,14 @@ export function fold(
       };
     }
     const obj = fold(node.expression, consts, intrinsics, externals);
-    if (obj === null || obj === undefined) return undefined;
+    // chant #2328 — see {@link nullishAccessMessage}. An earlier `?.` that
+    // short-circuited carries the whole chain to `undefined`; a `?.` here does
+    // the same for a nullish object; a plain `.` on one is the refusal.
+    if (isChainShortCircuit(obj)) return shortCircuited(node);
+    if (obj === null || obj === undefined) {
+      if (node.questionDotToken) return shortCircuited(node);
+      throw foldError(node, nullishAccessMessage(node.name.text, obj));
+    }
     if (isFoldedResource(obj)) return attrRefOnFoldedResource(node, node.name.text);
     return (obj as { [key: string]: FoldedValue })[node.name.text];
   }
@@ -1085,7 +1183,13 @@ export function fold(
       return { __attrRef: { entity: node.expression.text, attribute: key } };
     }
     const obj = fold(node.expression, consts, intrinsics, externals);
-    if (obj === null || obj === undefined) return undefined;
+    // chant #2328 — identical to the property-access branch above; `a?.["k"]`
+    // is the bracketed spelling of the same short-circuit.
+    if (isChainShortCircuit(obj)) return shortCircuited(node);
+    if (obj === null || obj === undefined) {
+      if (node.questionDotToken) return shortCircuited(node);
+      throw foldError(node, nullishAccessMessage(key, obj));
+    }
     if (isFoldedResource(obj)) return attrRefOnFoldedResource(node, key);
     return (obj as { [key: string]: FoldedValue })[key];
   }
@@ -1310,7 +1414,13 @@ export function fold(
     if (ts.isPropertyAccessExpression(node.expression)) {
       const methodName = node.expression.name.text;
       const receiver = fold(node.expression.expression, consts, intrinsics, externals);
+      // chant #2328 — a call is a link of an optional chain like any other:
+      // `a?.b()` and `a?.b.c()` on a nullish `a` are `undefined` in
+      // JavaScript, not a call on nothing. Only a non-optional receiver keeps
+      // the refusal this branch has made since #1966.
+      if (isChainShortCircuit(receiver)) return shortCircuited(node);
       if (receiver === null || receiver === undefined) {
+        if (node.expression.questionDotToken) return shortCircuited(node);
         throw foldError(node, `cannot call ".${methodName}(...)" on ${String(receiver)}`);
       }
       if (isFoldSymbolicEnvelope(receiver)) {

package/src/fold/subset-doc-parity.test.ts

@@ -3,7 +3,7 @@ import * as ts from "typescript";
 import { readFileSync } from "fs";
 import { fileURLToPath } from "url";
 import { join } from "path";
-import { collectConsts } from "./fold";
+import { collectConsts, fold, FoldError } from "./fold";
 import { findSubsetViolation } from "./subset";
 
 /**
@@ -50,6 +50,20 @@ import { findSubsetViolation } from "./subset";
  *     module boundary, or not at all (subset.ts's module doc, point 1) — a
  *     documented, intentional asymmetry, not something this guard can
  *     usefully narrow further without a binding resolver of its own.
+ *
+ * One doc claim below is checked against `fold()` instead of
+ * `findSubsetViolation` — chant #2306. "Unregistered tagged template
+ * intrinsics" is a claim `findSubsetViolation` structurally cannot decide:
+ * subset.ts treats every tagged template's interior as shape-valid
+ * regardless of tag registration (its own module doc explains why — EVL has
+ * no intrinsic registry at lint time), so registered vs. unregistered is
+ * indistinguishable at that layer no matter which heading the claim sits
+ * under. The registry check lives in `fold()` (`foldTaggedTemplate`), so
+ * that is what this one test calls instead. This is also why the doc bullet
+ * survived as long as it did in unfenced prose (chant #2306's own issue
+ * comment): moving it under a `###` heading with a fenced block, the shape
+ * every other case here uses, was necessary but not sufficient — the
+ * fixture still has to be run through the right function.
  */
 
 const repoRoot = fileURLToPath(new URL("../../../../", import.meta.url));
@@ -208,3 +222,23 @@ describe("subset-doc-parity — unsupported patterns in typescript-as-data.mdx c
     expect(findSubsetViolation(resourceArg(consts, "store"))).toBeDefined();
   });
 });
+
+describe("subset-doc-parity — fold()-decided claim in typescript-as-data.mdx (#2306)", () => {
+  test("Unregistered tagged template intrinsics", () => {
+    // findSubsetViolation cannot decide this one — see this file's module
+    // doc. Fold the doc's own example with an empty intrinsics list (no tag
+    // registered at all, the same as no lexicon opting `unknownTag` in) and
+    // check the real rejection, `foldTaggedTemplate` in ./fold.ts, fires.
+    const consts = parseConsts(extractFencedBlock("Unregistered tagged template intrinsics"));
+    const arg = resourceArg(consts, "store");
+    let error: unknown;
+    try {
+      fold(arg, consts, []);
+    } catch (e) {
+      error = e;
+    }
+    expect(error).toBeInstanceOf(FoldError);
+    expect((error as FoldError).message).toContain("unregistered tagged template intrinsic");
+    expect((error as FoldError).message).toContain("unknownTag");
+  });
+});

package/src/fold/subset-public-export.test.ts

@@ -0,0 +1,27 @@
+import { describe, test, expect } from "vitest";
+import * as ts from "typescript";
+import * as chant from "../index";
+
+/**
+ * The shape classifier is part of the public entry so a conformance adapter
+ * (INTENTIUS/typescript-as-data#11) and downstream tooling can ask "will this
+ * fold?" without running a fold. This pins the export and its two answers.
+ */
+describe("findSubsetViolation is exported from the package entry", () => {
+  const initializerOf = (src: string) => {
+    const sf = ts.createSourceFile("x.ts", src, ts.ScriptTarget.Latest, true);
+    return (sf.statements[0] as ts.VariableStatement).declarationList.declarations[0].initializer!;
+  };
+  test("is a function on the public namespace", () => {
+    expect(typeof chant.findSubsetViolation).toBe("function");
+    expect(typeof chant.checkObjectMember).toBe("function");
+  });
+  test("classifies a call as EVL001 and a literal as clean", () => {
+    const call = chant.findSubsetViolation(initializerOf("export const x = getId();"));
+    expect(call?.ruleId).toBe("EVL001");
+    expect(chant.findSubsetViolation(initializerOf('export const x = "ok";'))).toBeUndefined();
+  });
+  test("classifies a dynamic element-access key as EVL003", () => {
+    expect(chant.findSubsetViolation(initializerOf("export const x = cfg[key];"))?.ruleId).toBe("EVL003");
+  });
+});

package/src/fold/subset.ts

@@ -3,8 +3,32 @@ import { isFoldableHelperName } from "./foldable-helpers";
 import { intrinsicCallFolds, intrinsicCallFoldsEagerly, type IntrinsicDef } from "../lexicon";
 
 /**
- * subset — the single canonical definition of chant's statically-foldable
- * expression subset (chant #1024, epic #1019).
+ * subset — chant's implementation of the SHAPE layer of the TypeScript-as-Data
+ * specification (chant #1024, epic #1019).
+ *
+ * ## The specification is normative; this file implements it
+ *
+ * Since INTENTIUS/typescript-as-data#33 (2026-09-10) the subset is defined by
+ * the specification at https://github.com/INTENTIUS/typescript-as-data, not by
+ * this file. The rules this module implements are the `S-*` productions of
+ * `spec/grammar.md` §2 — S-Unwrap, S-Literal, S-Ident, S-Template, S-Tagged,
+ * S-Object (S-Prop / S-Shorthand / S-SpreadProp), S-Array, S-Member, S-Index,
+ * S-Unary, S-Binary, S-Conditional, S-New, the S-Call forms (S-CallHelper,
+ * S-CallIntrinsic, S-CallEager, S-CallMethod, S-CompositeStep) and S-Reject —
+ * and the direction rule `F-Direction` of `spec/divergence.md`: this classifier
+ * may accept what `fold()` rejects, never the reverse, outside the two named
+ * exceptions F-Exc-Lazy and F-Exc-Registry. The "environment-dependent
+ * exceptions" enumerated below are `spec/divergence.md`'s F-Div-* rows, kept
+ * here as implementation notes on WHY each resolution is out of this module's
+ * reach.
+ *
+ * Changing the subset goes spec-first: propose and land the rule there (with a
+ * fixture), then implement it here citing the identifier, then release. The
+ * provisional path for a change needed before the rule can be written: land it
+ * with the affected rule marked PROVISIONAL in this doc naming the spec issue;
+ * a provisional marker may survive at most one release, and the docs may not
+ * describe the change as supported until the rule exists. See
+ * `spec/README.md` "Ownership" and chant #2354.
  *
  * `fold()` ({@link "./fold"}, the enforcement layer — a construct outside
  * this subset simply has no case there) and EVL001/EVL003
@@ -44,6 +68,16 @@ import { intrinsicCallFolds, intrinsicCallFoldsEagerly, type IntrinsicDef } from
  *      re-folding the initializer would construct a duplicate of a resource
  *      discovery has already registered. Shape cannot see the difference, and
  *      the rejection is a fall-back-to-run, never a wrong value.
+ *
+ *      chant #2328 adds another, in the same direction and for the same
+ *      reason: a property or element read whose OBJECT resolves to `null` or
+ *      `undefined` (`cfg.nett.vpcId`, a typo in a nested path). Running it
+ *      throws a `TypeError`, so `fold()` refuses rather than answering
+ *      `undefined` and letting the build carry on with the property dropped.
+ *      What the object resolves to is exactly the resolution this module
+ *      does not do, so `cfg.nett.vpcId` stays shape-valid here — and a
+ *      genuinely optional `cfg.net?.vpcId`, which folds to `undefined`
+ *      because JavaScript defines it that way, is shape-valid in both.
  *   2. Tagged-template *tag registration* — needs a lexicon's intrinsics
  *      manifest, which isn't available to a syntax-only lint rule. `fold()`
  *      alone checks it; this module treats any tag name as shape-valid and

package/src/index.ts

@@ -39,6 +39,11 @@ export * from "./graph-layout";
 export * from "./graph-lens";
 export * from "./detectLexicon";
 export * from "./fold/fold";
+// The shape classifier is the predicate downstream tooling asks "will this
+// fold?" of without running a fold (subset.ts module doc, point 2c), and the
+// half of the fold subset a conformance adapter needs that `fold()` alone
+// does not expose. INTENTIUS/typescript-as-data#11.
+export { findSubsetViolation, checkObjectMember, type SubsetViolation, type SubsetRuleId } from "./fold/subset";
 export * from "./lint/parser";
 export * from "./lint/rule";
 export * from "./lint/rules";

package/src/lifecycle/gate-ledger.test.ts

@@ -6,7 +6,8 @@ import { join } from "node:path";
 import {
   appendGateResolution, appendPendingGate, readGateResolutions, readGateLedger,
   latestResolutionSince, latestPendingGate, isPendingGateExpired,
-  resolveApprovalUrl, isApprovalUrl, type PendingGateRecord,
+  resolveApprovalUrl, isApprovalUrl, latestResolutionForPlan,
+  type PendingGateRecord, type GateResolutionRecord,
 } from "./gate-ledger";
 import { readBlobFromPath, writeBlobToPath } from "./git";
 
@@ -253,3 +254,134 @@ describe("lifecycle/gate-ledger — pending facts (#2119)", () => {
     });
   });
 });
+
+/**
+ * #2300. `latestResolutionSince` asks "is there a newer approval", which a run
+ * answers yes to however much has changed since it was written. That is the
+ * rule INTENTIUS/choudoufu#1026 measured applying a renamed resource without
+ * complaint. `latestResolutionForPlan` asks "is there an approval of *this*",
+ * with recency demoted from the criterion to the tiebreak.
+ */
+describe("latestResolutionForPlan (#2300)", () => {
+  const EPOCH = new Date(0).toISOString();
+  const PLAN_A = `sha256:${"a".repeat(64)}`;
+  const PLAN_B = `sha256:${"b".repeat(64)}`;
+
+  const resolution = (over: Partial<GateResolutionRecord>): GateResolutionRecord => ({
+    version: 1, op: "live-apply", gate: "approve-live-apply", resolvedBy: "alex",
+    timestamp: "2026-01-02T00:00:00.000Z", ...over,
+  });
+
+  test("a resolution for this plan answers the gate", () => {
+    const found = latestResolutionForPlan([resolution({ planDigest: PLAN_A })], "approve-live-apply", EPOCH, PLAN_A);
+    expect(found.resolution?.resolvedBy).toBe("alex");
+    expect(found.mismatched).toBeUndefined();
+  });
+
+  test("a resolution for another plan does not, and comes back named", () => {
+    const found = latestResolutionForPlan([resolution({ planDigest: PLAN_B })], "approve-live-apply", EPOCH, PLAN_A);
+    expect(found.resolution).toBeUndefined();
+    expect(found.mismatched?.planDigest).toBe(PLAN_B);
+  });
+
+  // The migration, and the safe reading of it: a record with no digest proves
+  // someone approved something, and nothing about what.
+  test("a resolution written before #2300 never matches a plan-bound gate", () => {
+    const found = latestResolutionForPlan([resolution({})], "approve-live-apply", EPOCH, PLAN_A);
+    expect(found.resolution).toBeUndefined();
+    expect(found.mismatched).toBeDefined();
+    expect(found.mismatched?.planDigest).toBeUndefined();
+  });
+
+  // Recency is the tiebreak, not the criterion: a newer approval of the wrong
+  // plan does not shadow an older approval of the right one.
+  test("an older resolution for this plan beats a newer one for another", () => {
+    const found = latestResolutionForPlan(
+      [
+        resolution({ planDigest: PLAN_A, resolvedBy: "right", timestamp: "2026-01-02T00:00:00.000Z" }),
+        resolution({ planDigest: PLAN_B, resolvedBy: "wrong", timestamp: "2026-01-09T00:00:00.000Z" }),
+      ],
+      "approve-live-apply", EPOCH, PLAN_A,
+    );
+    expect(found.resolution?.resolvedBy).toBe("right");
+  });
+
+  test("among several for this plan, the newest wins", () => {
+    const found = latestResolutionForPlan(
+      [
+        resolution({ planDigest: PLAN_A, resolvedBy: "first", timestamp: "2026-01-02T00:00:00.000Z" }),
+        resolution({ planDigest: PLAN_A, resolvedBy: "second", timestamp: "2026-01-03T00:00:00.000Z" }),
+      ],
+      "approve-live-apply", EPOCH, PLAN_A,
+    );
+    expect(found.resolution?.resolvedBy).toBe("second");
+  });
+
+  test("the staleness rule still applies — a resolution older than the pending fact is no answer to it", () => {
+    const found = latestResolutionForPlan(
+      [resolution({ planDigest: PLAN_A, timestamp: "2026-01-01T00:00:00.000Z" })],
+      "approve-live-apply", "2026-01-05T00:00:00.000Z", PLAN_A,
+    );
+    expect(found.resolution).toBeUndefined();
+    expect(found.mismatched).toBeUndefined();
+  });
+
+  test("a gate that binds no plan decides exactly as latestResolutionSince does", () => {
+    const records = [resolution({}), resolution({ resolvedBy: "newer", timestamp: "2026-01-04T00:00:00.000Z" })];
+    expect(latestResolutionForPlan(records, "approve-live-apply", EPOCH, undefined).resolution?.resolvedBy)
+      .toBe(latestResolutionSince(records, "approve-live-apply", EPOCH)?.resolvedBy);
+  });
+
+  test("another gate's resolutions are not read as this one's", () => {
+    const found = latestResolutionForPlan(
+      [resolution({ gate: "approve-live-adopt", planDigest: PLAN_A })],
+      "approve-live-apply", EPOCH, PLAN_A,
+    );
+    expect(found.resolution).toBeUndefined();
+    expect(found.mismatched).toBeUndefined();
+  });
+});
+
+/**
+ * A `planDigest` that is present but not a string is a malformed line, not a
+ * line with a field to ignore (#2300) — ignoring it would demote a plan-bound
+ * record to a digest-less one, which is the shape a plan-bound gate refuses.
+ */
+describe("readGateLedger — a corrupted planDigest is malformed (#2300)", () => {
+  test("a non-string planDigest is counted, not read as an approval of nothing", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      await writeBlobToPath(
+        "_gates", "live-apply.jsonl",
+        JSON.stringify({
+          version: 1, op: "live-apply", gate: "g", resolvedBy: "alex",
+          timestamp: "2026-01-01T00:00:00.000Z", planDigest: { sha: "…" },
+        }),
+        "hand-written",
+        { cwd: dir },
+      );
+      const { resolutions, malformed } = await readGateLedger("live-apply", { cwd: dir });
+      expect(malformed).toBe(1);
+      expect(resolutions).toEqual([]);
+    });
+  });
+
+  test("a string planDigest round-trips onto both kinds of record", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      const digest = `sha256:${"a".repeat(64)}`;
+      await appendPendingGate(
+        { op: "live-apply", gate: "g", timestamp: "2026-01-01T00:00:00.000Z", expiresAt: "2026-01-03T00:00:00.000Z", planDigest: digest },
+        { cwd: dir },
+      );
+      await appendGateResolution(
+        { op: "live-apply", gate: "g", resolvedBy: "alex", timestamp: "2026-01-02T00:00:00.000Z", planDigest: digest },
+        { cwd: dir },
+      );
+      const { resolutions, pending, malformed } = await readGateLedger("live-apply", { cwd: dir });
+      expect(malformed).toBe(0);
+      expect(pending[0].planDigest).toBe(digest);
+      expect(resolutions[0].planDigest).toBe(digest);
+    });
+  });
+});

package/src/lifecycle/gate-ledger.ts

@@ -22,6 +22,13 @@
  * `chant approve` locally can write one, the same trust boundary a local
  * commit already has.
  *
+ * Since #2300 both halves also carry a plan identity (`./plan-digest.ts`): a
+ * run records the plan it reached the gate with, `chant approve` records the
+ * plan it approves, and {@link latestResolutionForPlan} matches on that
+ * rather than on recency alone. Before it, an approval authorised the next
+ * run of an op rather than the plan its approver had read
+ * (INTENTIUS/choudoufu#1026).
+ *
  * Since #2119 the file carries both halves of the loop. A `gate` step the
  * local executor reaches (`../op/local-executor.ts`) appends a
  * {@link PendingGateRecord} and ends that run with status `gated`; `chant
@@ -119,6 +126,18 @@ export interface GateResolutionRecord {
    * URL — see {@link isApprovalUrl}.
    */
   url?: string;
+  /**
+   * The plan this approval is for (#2300) — `computePlanDigest`'s output
+   * (`./plan-digest.ts`), normally copied off the {@link PendingGateRecord}
+   * this resolution answers.
+   *
+   * Absent on every resolution written before #2300, and on one written for a
+   * gate that binds no plan. Absent is not a wildcard: {@link
+   * latestResolutionForPlan} refuses a digest-less resolution against a
+   * plan-bound gate rather than letting it through, because the only thing
+   * such a record proves is that somebody approved *something*.
+   */
+  planDigest?: string;
 }
 
 export type GateResolutionInput = Omit<GateResolutionRecord, "version" | "kind">;
@@ -154,6 +173,16 @@ export interface PendingGateRecord {
   expiresAt: string;
   /** The address approval happens at, when the run knew one — see {@link resolveApprovalUrl}. */
   url?: string;
+  /**
+   * The plan the run reached this gate with (#2300) — `computePlanDigest`'s
+   * output (`./plan-digest.ts`). This is what `chant approve` copies onto the
+   * resolution by default, so approving the standing fact approves the plan
+   * the approver was shown rather than the next run's.
+   *
+   * Absent when the gate binds no plan (a component gate, an authored `gate`
+   * step with no `plan`), which is the shape every gate had before #2300.
+   */
+  planDigest?: string;
 }
 
 export type PendingGateInput = Omit<PendingGateRecord, "version" | "kind">;
@@ -262,6 +291,16 @@ export async function readGateLedger(
         malformed++;
         continue;
       }
+      // #2300: a `planDigest` that is present but not a string is a
+      // malformed line, not a line with a field to ignore. Ignoring it would
+      // silently demote a plan-bound record to a digest-less one, which is
+      // the shape `latestResolutionForPlan` refuses — a corrupted approval
+      // must not read as an approval of anything at all.
+      const rawDigest: unknown = (parsed as { planDigest?: unknown }).planDigest;
+      if (rawDigest !== undefined && typeof rawDigest !== "string") {
+        malformed++;
+        continue;
+      }
       if (parsed.kind === "pending") {
         if (typeof parsed.expiresAt !== "string") {
           malformed++;
@@ -319,3 +358,72 @@ export function latestResolutionSince(
   }
   return latest;
 }
+
+/** What {@link latestResolutionForPlan} found for the plan a run is holding. */
+export interface PlanBoundResolution {
+  /** The resolution that answers this gate for this plan. Absent when nothing does. */
+  resolution?: GateResolutionRecord;
+  /**
+   * Present instead of {@link PlanBoundResolution.resolution} when a
+   * resolution stands for this gate but for a different plan — the newest
+   * such record, so a refusal can name who approved what and when. Its
+   * `planDigest` is `undefined` for a record written before #2300.
+   */
+  mismatched?: GateResolutionRecord;
+}
+
+/**
+ * The resolution that answers `gate` for the plan `planDigest` identifies
+ * (#2300).
+ *
+ * The criterion is the digest; recency is only the tiebreak between several
+ * resolutions that all match it. That inversion is the whole point of the
+ * issue: {@link latestResolutionSince} asks "is there a newer approval",
+ * which a run answers yes to no matter what has changed since, and this asks
+ * "is there an approval of *this*".
+ *
+ * - `planDigest` `undefined` — the gate binds no plan (a component gate, a
+ *   `gate` step authored with no `plan`). Falls straight through to
+ *   {@link latestResolutionSince}: gates that never claimed to bind a plan
+ *   behave exactly as they did before #2300.
+ * - A resolution whose `planDigest` equals `planDigest` answers the gate.
+ * - A resolution for a different plan does not, and comes back as
+ *   `mismatched` so the caller can name both digests.
+ * - A resolution with no `planDigest` at all — every record written before
+ *   #2300 — does not either, and comes back as `mismatched` with an absent
+ *   `planDigest`. This is the safe reading of the migration: such a record
+ *   proves someone approved something, and nothing about what. Accepting it
+ *   once would silently apply the very change this check exists to catch, on
+ *   exactly the estates that have been running longest. The cost is one
+ *   further `chant approve` per gate after the upgrade, which the refusal
+ *   says out loud.
+ */
+export function latestResolutionForPlan(
+  records: GateResolutionRecord[],
+  gate: string,
+  sinceIso: string,
+  planDigest: string | undefined,
+): PlanBoundResolution {
+  if (planDigest === undefined) {
+    const resolution = latestResolutionSince(records, gate, sinceIso);
+    return resolution ? { resolution } : {};
+  }
+
+  const since = new Date(sinceIso).getTime();
+  let matched: GateResolutionRecord | undefined;
+  let mismatched: GateResolutionRecord | undefined;
+  for (const r of records) {
+    if (r.gate !== gate) continue;
+    if (new Date(r.timestamp).getTime() < since) continue;
+    const newest = (best: GateResolutionRecord | undefined) =>
+      !best || new Date(r.timestamp).getTime() >= new Date(best.timestamp).getTime();
+    if (r.planDigest === planDigest) {
+      if (newest(matched)) matched = r;
+    } else if (newest(mismatched)) {
+      mismatched = r;
+    }
+  }
+
+  if (matched) return { resolution: matched };
+  return mismatched ? { mismatched } : {};
+}

package/src/lifecycle/index.ts

@@ -23,3 +23,4 @@ export * from "./converge-ledger";
 export * from "./run-ledger";
 export * from "./scenario";
 export * from "./scenario-eval";
+export * from "./plan-digest";

package/src/lifecycle/plan-digest.test.ts

@@ -0,0 +1,49 @@
+import { describe, test, expect } from "vitest";
+import { computePlanDigest, isPlanDigest, describePlanDigest } from "./plan-digest";
+
+describe("computePlanDigest", () => {
+  test("the same change set digests the same, whatever order its keys arrived in", () => {
+    const a = computePlanDigest("terraform-plan", { address: "aws_s3_bucket.a", actions: ["create"] });
+    const b = computePlanDigest("terraform-plan", { actions: ["create"], address: "aws_s3_bucket.a" });
+    expect(a).toBe(b);
+  });
+
+  test("a changed address changes it", () => {
+    expect(computePlanDigest("terraform-plan", { address: "aws_s3_bucket.a" })).not.toBe(
+      computePlanDigest("terraform-plan", { address: "aws_s3_bucket.b" }),
+    );
+  });
+
+  // The kind is hashed alongside the subject so a gate bound to a terraform
+  // plan cannot be satisfied by another kind of plan that happened to
+  // serialize identically.
+  test("two kinds of plan over identical data do not collide", () => {
+    expect(computePlanDigest("terraform-plan", { x: 1 })).not.toBe(
+      computePlanDigest("lifecycle-diff", { x: 1 }),
+    );
+  });
+
+  test("it is a sha256 digest, in the shape isPlanDigest accepts", () => {
+    const digest = computePlanDigest("terraform-plan", {});
+    expect(digest).toMatch(/^sha256:[0-9a-f]{64}$/);
+    expect(isPlanDigest(digest)).toBe(true);
+  });
+});
+
+describe("isPlanDigest", () => {
+  test("refuses everything a copy-paste or a path could be", () => {
+    expect(isPlanDigest("chant.tfplan")).toBe(false);
+    expect(isPlanDigest(`sha256:${"a".repeat(63)}`)).toBe(false);
+    expect(isPlanDigest("a".repeat(64))).toBe(false);
+    expect(isPlanDigest(`sha256:${"A".repeat(64)}`)).toBe(false);
+    expect(isPlanDigest(undefined)).toBe(false);
+    expect(isPlanDigest(12)).toBe(false);
+  });
+});
+
+describe("describePlanDigest", () => {
+  test("an absent digest reads as the pre-#2300 record it is, never as undefined", () => {
+    expect(describePlanDigest(undefined)).toBe("(none — recorded before plan-bound gates)");
+    expect(describePlanDigest("sha256:abc")).toBe("sha256:abc");
+  });
+});