@intentius/chant 0.61.0 → 0.63.0

package/src/components/driver.test.ts

@@ -14,6 +14,7 @@ import { describe, expect, it } from "vitest";
 import { CapabilityRegistry, type DeployContext } from "./capability";
 import { stubCapability } from "./verbs/stub";
 import { memoryGateLedgerPort } from "../op/gate";
+import type { PendingGateInput } from "../lifecycle/gate-ledger";
 import {
   DependencyCycleError,
   DriverRunFailure,
@@ -259,6 +260,36 @@ describe("runComponentDeploy — gate as fact (#2119)", () => {
     ]);
   });
 
+  // #2310: the driver's own `pushLifecycle` swallow — the same shape
+  // `../op/gate.ts`'s `appendPending` had — a component still ends `gated`
+  // when its own append fails to reach the remote (the local fact is still
+  // correct), but the result now says so instead of staying silent.
+  it("still ends gated when the push is rejected, and reports it on the result", async () => {
+    const { registry, calls } = registryWithCalls();
+    const rejectingPort = {
+      async read() {
+        return { resolutions: [], pending: [] };
+      },
+      async appendPending(input: PendingGateInput) {
+        return {
+          record: { version: 1 as const, kind: "pending" as const, ...input },
+          pushed: false,
+          pushWarning: "chant/lifecycle remote branch has moved since this run started",
+        };
+      },
+    };
+    const result = await runComponentDeploy(
+      gatedComponent(), { env: "dev", component: "neo4j-cluster" }, registry, {}, undefined,
+      { port: rejectingPort, now: NOW },
+    );
+
+    expect(result.status).toBe("gated");
+    expect(result.gate).toMatchObject({ op: "neo4j-cluster", gate: "approve-node-1" });
+    expect(result.gatePushed).toBe(false);
+    expect(result.gatePushWarning).toBe("chant/lifecycle remote branch has moved since this run started");
+    expect(calls).toEqual(["cfn-deploy"]);
+  });
+
   // #2202: `signalName` was the key that named a component gate through 0.58.0
   // and is still read, so a component on the old key gates identically.
   it("still reads a gate step's deprecated `signalName` key", async () => {

package/src/components/driver.ts

@@ -159,6 +159,14 @@ export interface DriverComponentResult {
   records: DriverStepRecord[];
   /** Present when `status === "gated"`: the pending fact this component stopped on. */
   gate?: PendingGateRecord;
+  /**
+   * Present when `status === "gated"` and this run's own append tried to
+   * push: whether it reached the remote (#2310). Absent when the component
+   * stopped on a pending fact an earlier run had already recorded.
+   */
+  gatePushed?: boolean;
+  /** Set when `gatePushed` is false: why, in one line. */
+  gatePushWarning?: string;
 }
 
 export interface DriverRunResult {
@@ -176,6 +184,10 @@ export interface DriverRunResult {
   gatedComponent?: string;
   /** The pending fact the run stopped on, when `status === "gated"`. */
   gate?: PendingGateRecord;
+  /** Present when `status === "gated"`: whether the gated component's own append reached the remote (#2310). */
+  gatePushed?: boolean;
+  /** Set when `gatePushed` is false: why, in one line. */
+  gatePushWarning?: string;
   /**
    * The accumulated cross-component/cross-stack outputs after the run — each
    * component's `publish` output and, for an applied stack, its `cfn-deploy`
@@ -355,6 +367,9 @@ class GateStop extends Error {
     public readonly records: DriverStepRecord[],
     public readonly executed: ExecutedStep[],
     public readonly pending: PendingGateRecord,
+    /** Whether this run's own append reached the remote — see {@link DriverComponentResult.gatePushed} (#2310). */
+    public readonly pushed?: boolean,
+    public readonly pushWarning?: string,
   ) {
     super(`gate "${pending.gate}" is pending approval`);
     this.name = "GateStop";
@@ -462,7 +477,7 @@ async function runPhase(
         for (const skipped of phaseDef.steps.filter((s): s is DriverStep | DriverPhase => !isGateStep(s))) {
           gateRecords.push(skippedRecord(skipped));
         }
-        throw new GateStop(gateRecords, [], check.pending);
+        throw new GateStop(gateRecords, [], check.pending, check.pushed, check.pushWarning);
       }
       gateRecords.push({
         ...base,
@@ -483,7 +498,14 @@ async function runPhase(
 
   const runEntry = async (
     entry: DriverStep | DriverPhase,
-  ): Promise<{ records: DriverStepRecord[]; executed: ExecutedStep[]; failed: boolean; pending?: PendingGateRecord }> => {
+  ): Promise<{
+    records: DriverStepRecord[];
+    executed: ExecutedStep[];
+    failed: boolean;
+    pending?: PendingGateRecord;
+    pushed?: boolean;
+    pushWarning?: string;
+  }> => {
     if (isPhaseStep(entry)) {
       try {
         const nested = await runPhase(entry, ctx, registry, phaseOutputs, componentOutputs, gates, onProgress);
@@ -493,7 +515,14 @@ async function runPhase(
         // A nested fan-out phase's gate stops the whole component, but the
         // records it produced before the gate still belong in the run.
         if (err instanceof GateStop) {
-          return { records: err.records, executed: err.executed, failed: false, pending: err.pending };
+          return {
+            records: err.records,
+            executed: err.executed,
+            failed: false,
+            pending: err.pending,
+            pushed: err.pushed,
+            pushWarning: err.pushWarning,
+          };
         }
         throw err;
       }
@@ -539,8 +568,10 @@ async function runPhase(
       const results = await Promise.all(entries.map(runEntry));
       const records = gateRecords.concat(results.flatMap((r) => r.records));
       const executed = results.flatMap((r) => r.executed);
-      const pending = results.find((r) => r.pending)?.pending;
-      if (pending) throw new GateStop(records, executed, pending);
+      const withPending = results.find((r) => r.pending);
+      if (withPending?.pending) {
+        throw new GateStop(records, executed, withPending.pending, withPending.pushed, withPending.pushWarning);
+      }
       if (results.some((r) => r.failed)) throw new StepFailure(records, executed);
       return { records, executed };
     }
@@ -553,7 +584,7 @@ async function runPhase(
       executed.push(...result.executed);
       if (result.pending) {
         for (const skipped of entries.slice(i + 1)) records.push(skippedRecord(skipped));
-        throw new GateStop(records, executed, result.pending);
+        throw new GateStop(records, executed, result.pending, result.pushed, result.pushWarning);
       }
       if (result.failed) {
         for (const skipped of entries.slice(i + 1)) records.push(skippedRecord(skipped));
@@ -681,7 +712,15 @@ export async function runComponentDeploy(
     // them would make every gated run a no-op with a rollback attached.
     if (err instanceof GateStop) {
       records.push(...err.records);
-      return { component: component.name, ok: false, status: "gated", records, gate: err.pending };
+      return {
+        component: component.name,
+        ok: false,
+        status: "gated",
+        records,
+        gate: err.pending,
+        ...(err.pushed !== undefined ? { gatePushed: err.pushed } : {}),
+        ...(err.pushWarning ? { gatePushWarning: err.pushWarning } : {}),
+      };
     }
 
     if (err instanceof StepFailure) {
@@ -912,7 +951,14 @@ export async function runInterpretDriver(
   onProgress?.({ type: "run-done", status: progressStatus(status) });
   const result: DriverRunResult = {
     order, waves, results, ok, status, failedComponent, componentOutputs,
-    ...(gated ? { gatedComponent: gated.component, gate: gated.gate } : {}),
+    ...(gated
+      ? {
+          gatedComponent: gated.component,
+          gate: gated.gate,
+          ...(gated.gatePushed !== undefined ? { gatePushed: gated.gatePushed } : {}),
+          ...(gated.gatePushWarning ? { gatePushWarning: gated.gatePushWarning } : {}),
+        }
+      : {}),
   };
   if (status === "fail") throw new DriverRunFailure(result);
   return result;

package/src/discovery/fold-import.test.ts

@@ -262,6 +262,61 @@ describe("tryFoldFile", () => {
     expect(result.reason).toBe("no foldable resource exports");
   });
 
+  // chant #2328 — the cross-file shape of the nullish property read. A
+  // sibling file's `export const region = undefined;` resolves through the
+  // module graph like any other imported const, so `externals.has("region")`
+  // is true and `get("region")` is `undefined`; the importer's `region.name`
+  // then folded to `undefined` and the prop vanished from the built resource,
+  // while running the same two files throws `TypeError: Cannot read
+  // properties of undefined (reading 'name')`. It must fall back instead.
+  test("falls back when a property is read off an imported binding whose value is undefined (#2328)", async () => {
+    await writeResourceDefs();
+    await writeFile(join(testDir, "config.ts"), `export const region = undefined;`);
+    const file = join(testDir, "main.ts");
+    await writeFile(
+      file,
+      `
+        import { Bucket } from "./resources";
+        import { region } from "./config";
+        export const bucket = new Bucket({ name: region.name });
+      `,
+    );
+
+    const result = await tryFoldFile(file);
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.reason).toContain('property "name" read on undefined is not foldable');
+  });
+
+  // The same file with the read written optionally is genuinely `undefined`
+  // in JavaScript, so it keeps folding — the refusal above is about the
+  // non-optional read, not about nullish imports.
+  test("an optional read off the same undefined import still folds (#2328)", async () => {
+    await writeResourceDefs();
+    await writeFile(join(testDir, "config.ts"), `export const region = undefined;`);
+    const file = join(testDir, "main.ts");
+    await writeFile(
+      file,
+      `
+        import { Bucket } from "./resources";
+        import { region } from "./config";
+        throw new Error("must never execute — sentinel for #2328");
+        export const bucket = new Bucket({ name: "b", region: region?.name });
+      `,
+    );
+
+    const result = await tryFoldFile(file);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const [, entity] = result.entities[0];
+    expect((entity as unknown as { props: Record<string, unknown> }).props).toEqual({
+      name: "b",
+      region: undefined,
+    });
+  });
+
   // chant #1020: a plain-value-only export now folds too (contributing
   // nothing to `entities` — only Declarable/CompositeInstance land there —
   // but recorded in `exportedValues`). This is intentional, not a relaxed

package/src/fold/fold.test.ts

@@ -253,6 +253,158 @@ describe("fold — element access", () => {
   });
 });
 
+// chant #2328 — a property or element read whose object folded to `null` or
+// `undefined` returned `undefined`, so a mistyped nested path folded away and
+// the build carried on emitting a resource with the property missing, while
+// RUNNING the same file throws a TypeError at that expression. Both branches
+// now refuse, and the file falls back to run — with `?.`, which JavaScript
+// DEFINES as `undefined` on a nullish object, still folding.
+describe("fold — property/element access on a nullish object (#2328)", () => {
+  test("a mistyped nested path throws a located FoldError rather than folding the property away", () => {
+    const src = `
+      const cfg = { net: { vpcId: "vpc-1" } };
+      const vpcId = cfg.nett.vpcId;
+    `;
+    let error: unknown;
+    try {
+      foldConst(src, "vpcId");
+    } catch (e) {
+      error = e;
+    }
+    expect(error).toBeInstanceOf(FoldError);
+    expect((error as FoldError).message).toContain('property "vpcId" read on undefined is not foldable');
+    expect((error as FoldError).message).toContain("throws a TypeError");
+    // Located at the failing access itself — line 3 of the snippet above.
+    expect((error as FoldError).line).toBe(3);
+  });
+
+  test("the message points at `?.` as the way to say the value is genuinely optional", () => {
+    const src = `
+      const cfg = {};
+      const x = cfg.net.vpcId;
+    `;
+    expect(() => foldConst(src, "x")).toThrow(/write `\?\.` if the value is genuinely optional/);
+  });
+
+  test("a read on null refuses the same way a read on undefined does", () => {
+    const src = `
+      const cfg = null;
+      const x = cfg.vpcId;
+    `;
+    expect(() => foldConst(src, "x")).toThrow(/property "vpcId" read on null is not foldable/);
+  });
+
+  test("element access on a nullish object refuses too, naming the bracketed key", () => {
+    const src = `
+      const cfg = { net: { vpcId: "vpc-1" } };
+      const x = cfg["nett"]["vpcId"];
+    `;
+    expect(() => foldConst(src, "x")).toThrow(FoldError);
+    expect(() => foldConst(src, "x")).toThrow(/property "vpcId" read on undefined is not foldable/);
+  });
+
+  // The cross-file shape #2328 names: a sibling file's `export const a =
+  // undefined;` puts `a -> undefined` in the importer's externals, so
+  // `externals.has("a")` is true and `get("a")` is `undefined`. Held here at
+  // the `fold()` seam; ../discovery/fold-import.test.ts runs the real
+  // two-file version through `tryFoldFile`.
+  test("an imported binding whose value is undefined refuses on a property read, not folds", () => {
+    const src = `const x = a.vpcId;`;
+    const consts = parseConsts(src);
+    const externals = new Map<string, unknown>([["a", undefined]]);
+    expect(() => fold(consts.get("x") as ts.Expression, consts, [], externals)).toThrow(
+      /property "vpcId" read on undefined is not foldable/,
+    );
+  });
+
+  test("a method call on a nullish receiver keeps refusing, as it has since #1966", () => {
+    const src = `
+      const cfg = undefined;
+      const x = cfg.toString();
+    `;
+    expect(() => foldConst(src, "x")).toThrow(/cannot call "\.toString\(\.\.\.\)" on undefined/);
+  });
+});
+
+// chant #2328 — `a?.b` on a nullish `a` is DEFINED to be `undefined` in
+// JavaScript, and so is every link that follows it in the same chain. Fold
+// has to agree with that as exactly as it now disagrees with a plain `.`.
+describe("fold — optional chaining short-circuits rather than refusing (#2328)", () => {
+  test("`a?.b` on a nullish object folds to undefined", () => {
+    const src = `
+      const a = undefined;
+      const x = a?.b;
+    `;
+    expect(foldConst(src, "x")).toBeUndefined();
+  });
+
+  test("a `?.` earlier in the chain carries the whole chain to undefined", () => {
+    const src = `
+      const a = undefined;
+      const x = a?.b.c.d;
+    `;
+    expect(foldConst(src, "x")).toBeUndefined();
+  });
+
+  test("the bracketed spelling short-circuits identically", () => {
+    const src = `
+      const a = null;
+      const x = a?.["b"]["c"];
+    `;
+    expect(foldConst(src, "x")).toBeUndefined();
+  });
+
+  test("a non-null assertion inside the chain is transparent to the short-circuit", () => {
+    const src = `
+      const a = undefined;
+      const x = a?.b!.c;
+    `;
+    expect(foldConst(src, "x")).toBeUndefined();
+  });
+
+  test("an optional call link short-circuits with the rest of the chain", () => {
+    const src = `
+      const a = undefined;
+      const x = a?.b();
+      const y = a?.b.c();
+    `;
+    expect(foldConst(src, "x")).toBeUndefined();
+    expect(foldConst(src, "y")).toBeUndefined();
+  });
+
+  test("`?.` on a present object still indexes it — the short-circuit is not a blanket undefined", () => {
+    const src = `
+      const a = { b: { c: "deep" } };
+      const x = a?.b.c;
+    `;
+    expect(foldConst(src, "x")).toBe("deep");
+  });
+
+  test("parentheses end the chain, so the access after them refuses exactly as running it throws", () => {
+    const src = `
+      const a = undefined;
+      const x = (a?.b).c;
+    `;
+    expect(() => foldConst(src, "x")).toThrow(/property "c" read on undefined is not foldable/);
+  });
+
+  test("a genuine undefined mid-chain is not a short-circuit — the next plain link refuses", () => {
+    const src = `
+      const a = { b: undefined };
+      const x = a?.b.c;
+    `;
+    expect(() => foldConst(src, "x")).toThrow(/property "c" read on undefined is not foldable/);
+  });
+
+  test("...and the same read written optionally folds to undefined", () => {
+    const src = `
+      const a = { b: undefined };
+      const x = a?.b?.c;
+    `;
+    expect(foldConst(src, "x")).toBeUndefined();
+  });
+});
+
 describe("fold — intrinsic tagged templates", () => {
   const SUB: IntrinsicDef = { name: "Sub", isTag: true, outputKey: "Fn::Sub" };
 

package/src/fold/fold.ts

@@ -784,6 +784,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 +1155,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 +1173,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 +1404,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.ts

@@ -44,6 +44,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/lexicon.ts

@@ -465,6 +465,25 @@ export interface ComponentPipelineOptions {
   image?: string;
   /** Top-level CI `variables:` block. */
   variables?: Record<string, string>;
+  /**
+   * The stage every generated Op job runs in, and (on GitLab) the default
+   * base of the generated file's own name (#2293). GitLab-only: a GitHub or
+   * Forgejo Op workflow is one file per Op with no shared stage, so this does
+   * nothing there. Default `"ops"` — every trigger kind (cron, merge-request,
+   * push) a project mixes into one Op pipeline lands under the same stage,
+   * unlike the pre-#2293 constant `"scheduled-ops"`, which named only the
+   * cron-only pipeline the generator used to emit. See `opsFileName` for the
+   * file name, which follows this unless overridden separately.
+   */
+  opsStage?: string;
+  /**
+   * The generated Op pipeline file's name — GitLab only (#2293). Defaults to
+   * `` `${opsStage}.gitlab-ci.yml` `` (`ops.gitlab-ci.yml` with no `opsStage`
+   * override), so setting `opsStage` alone renames both the stage GitLab's UI
+   * groups jobs under and the file a consumer's `include:` line names. Set
+   * this too when the file should land under some other name than its stage.
+   */
+  opsFileName?: string;
 }
 
 /** The synthesized CI pipeline for a component graph (generate mode). */
@@ -638,6 +657,38 @@ export interface ScheduledOpSpec {
    * own gate.
    */
   environment?: OpEnvironment;
+  /**
+   * Variables and secrets for this Op's generated job alone (#2290). Same
+   * shape as {@link ComponentPipelineOptions.variables} — chant draws no
+   * type-level line between a plain value and a credential, both are strings
+   * a generator drops into the job's environment — but scoped to one Op's job
+   * rather than the whole generated file, for the reason `setup` and
+   * `permissions` are per-Op already: what a job may hold is a property of
+   * that job. A `live-check` plan job that makes no cloud call declares none
+   * of this and inherits none of it.
+   *
+   * **The rule where both are set** (#2290): `ComponentPipelineOptions.variables`
+   * (forge-wide) keeps landing on the workflow/file-level `env:`
+   * (github/forgejo) or top-level `variables:` (gitlab) exactly as it always
+   * has — every caller that declares nothing here sees byte-identical output.
+   * This field lands one level down, on the job itself — github/forgejo emit
+   * it as the job's own `env:` mapping, gitlab merges it into the job's own
+   * `variables:` — and a key present in both wins at the job, the same
+   * last-one-wins precedence GitHub Actions and GitLab CI already give
+   * step/job env over workflow env. Declaring a credential here rather than
+   * in the forge-wide options is therefore how a caller keeps it off every
+   * *other* Op's job: nothing about the forge-wide options changes shape,
+   * only which of a project's own Ops asks for the credential at all.
+   *
+   * Supported everywhere a per-Op `env:`/`variables:` block is expressible:
+   * github and forgejo both emit job-level `env:`; gitlab merges these into
+   * the job's own `variables:` block (already used there for the gated
+   * apply's `CHANT_GATE_SUMMARY`, so the merge is native rather than bolted
+   * on). No generator refuses this option — unlike `setup`'s `uses:` shape or
+   * an additive `permissions` scope, every forge chant targets has some
+   * per-job environment mapping to put a value in.
+   */
+  variables?: Record<string, string>;
 }
 
 /**