@intentius/chant 0.62.0 → 0.63.0

package/src/cli/handlers/run.ts

@@ -385,6 +385,7 @@ export async function runOpApprove(ctx: CommandContext): Promise<number> {
     actor: ctx.args.approver ?? ctx.args.actor,
     note: ctx.args.note,
     url: ctx.args.url,
+    plan: ctx.args.plan,
   });
   if (!outcome.ok) return 1;
 
@@ -744,6 +745,16 @@ export async function runOpComponents(ctx: CommandContext): Promise<number> {
     console.error(formatInfo(`approve : ${approveCommand(gate.op, gate.gate)}`));
     if (gate.url) console.error(formatInfo(`approve at: ${gate.url}`));
     console.error(formatInfo(`expires : ${gate.expiresAt}`));
+    // #2310: this run's own append reached only the local chant/lifecycle
+    // branch. The gate is still right to stand, but an operator elsewhere
+    // cannot see the pending fact to approve it, and nothing else here says
+    // why not.
+    if (result.gated.pushed === false) {
+      console.error(formatWarning({
+        message: `the pending fact was not pushed to the remote: ${result.gated.pushWarning ?? "recorded locally only"}`,
+        hint: "an operator working from a clone of the remote cannot approve it until it does",
+      }));
+    }
     reportGatedRun(
       {
         op: gate.op,
@@ -751,6 +762,8 @@ export async function runOpComponents(ctx: CommandContext): Promise<number> {
         ...(gate.description ? { description: gate.description } : {}),
         expiresAt: gate.expiresAt,
         ...(gate.url ? { url: gate.url } : {}),
+        ...(result.gated.pushed === false ? { pushed: false, pushWarning: result.gated.pushWarning } : {}),
+        ...(gate.planDigest ? { planDigest: gate.planDigest } : {}),
       },
       gatedExit,
     );
@@ -866,6 +879,12 @@ export async function runOpOnRuntime(ctx: CommandContext): Promise<number> {
             ...(pending?.description ? { description: pending.description } : {}),
             ...(pending?.expiresAt ? { expiresAt: pending.expiresAt } : {}),
             ...(pending?.url ? { url: pending.url } : {}),
+            // #2310: the local runtime knows whether this run's own append
+            // reached the remote; a runtime that reports only a state does not.
+            ...(status.result?.gatePushed === false
+              ? { pushed: false, pushWarning: status.result.gatePushWarning }
+              : {}),
+            ...(pending?.planDigest ? { planDigest: pending.planDigest } : {}),
           },
           gatedExit,
         );

package/src/cli/main.ts

@@ -404,6 +404,8 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.note = args[++i];
     } else if (arg === "--expire") {
       result.expire = true;
+    } else if (arg === "--plan") {
+      result.plan = args[++i];
     } else if (arg === "--url") {
       result.url = args[++i];
     } else if (arg === "--op") {

package/src/cli/registry.ts

@@ -318,6 +318,8 @@ export interface ParsedArgs {
   note?: string;
   /** `chant approve <op> <gate> --expire` (#2119) — clear the gate's standing pending fact instead of approving it, so the next run decides the gate from scratch and records a fresh one. Writes no resolution: nothing is approved, the wait is only restarted. */
   expire?: boolean;
+  /** `chant approve <op> <gate> --plan <digest>` (#2300) — the plan this approval is for, as `sha256:<64 hex>`. Omitted, the digest is taken from the gate's standing pending fact, which is the plan the run that stopped at the gate actually produced; pass it to approve a plan explicitly, or to approve one before any run has recorded a pending fact. */
+  plan?: string;
   /** `chant operator log --op <name>` (#2029) — restrict the tick history to one ConvergeOp by name. Omitted, every discovered ConvergeOp's ticks are merged into one timeline. */
   op?: string;
   /** `chant operator log --since <iso>` (#2029) — only entries at or after this ISO-8601 instant. */

package/src/components/cli-support.ts

@@ -425,7 +425,13 @@ export interface RunComponentsResult {
   selected: string[];
   error?: string;
   /** Set when the run stopped at a `gate` nobody has approved (#2119): the component it stopped at and the pending fact recorded for it. */
-  gated?: { component: string; gate: PendingGateRecord };
+  gated?: {
+    component: string;
+    gate: PendingGateRecord;
+    /** Whether this run's own append reached the remote (#2310); absent when the pending fact was already standing. */
+    pushed?: boolean;
+    pushWarning?: string;
+  };
   /** This run's resolved build-time parameters (chant #1108) — the component-driver counterpart of `../cli/commands/build.ts`'s `BuildResult.buildParams`. Present only once the run actually reached dispatch (mirrors `BuildResult.buildParams`, which is likewise absent on an early-error return). */
   buildParams?: BuildParamProvenance[];
 }
@@ -571,7 +577,14 @@ export async function runComponents(
         selected,
         buildParams: options.buildParams,
         ...(run.status === "gated" && run.gate
-          ? { gated: { component: run.gatedComponent ?? selected[0], gate: run.gate } }
+          ? {
+              gated: {
+                component: run.gatedComponent ?? selected[0],
+                gate: run.gate,
+                ...(run.gatePushed !== undefined ? { pushed: run.gatePushed } : {}),
+                ...(run.gatePushWarning ? { pushWarning: run.gatePushWarning } : {}),
+              },
+            }
           : {}),
       };
     }
@@ -613,7 +626,12 @@ export async function runComponents(
       status: componentResult.status,
       failedComponent: componentResult.status === "fail" ? componentResult.component : undefined,
       ...(componentResult.status === "gated"
-        ? { gatedComponent: componentResult.component, gate: componentResult.gate }
+        ? {
+            gatedComponent: componentResult.component,
+            gate: componentResult.gate,
+            ...(componentResult.gatePushed !== undefined ? { gatePushed: componentResult.gatePushed } : {}),
+            ...(componentResult.gatePushWarning ? { gatePushWarning: componentResult.gatePushWarning } : {}),
+          }
         : {}),
       componentOutputs,
     };
@@ -623,7 +641,14 @@ export async function runComponents(
       selected,
       buildParams: options.buildParams,
       ...(componentResult.status === "gated" && componentResult.gate
-        ? { gated: { component: componentResult.component, gate: componentResult.gate } }
+        ? {
+            gated: {
+              component: componentResult.component,
+              gate: componentResult.gate,
+              ...(componentResult.gatePushed !== undefined ? { pushed: componentResult.gatePushed } : {}),
+              ...(componentResult.gatePushWarning ? { pushWarning: componentResult.gatePushWarning } : {}),
+            },
+          }
         : {}),
     };
   } catch (err) {

package/src/components/driver-output.ts

@@ -72,6 +72,16 @@ export function renderDriverHuman(result: DriverRunResult, write: Writer = stder
     write(`interpret run completed (${result.order.length} component(s))`);
   } else if (result.status === "gated") {
     write(`interpret run is gated at component "${result.gatedComponent}"`);
+    // #2310: this run's own append reached only the local chant/lifecycle
+    // branch. The gate still stands correctly — but an operator elsewhere
+    // cannot see the pending fact to approve it.
+    if (result.gatePushed === false) {
+      write(
+        `  warning : the pending fact was not pushed to the remote — ` +
+          (result.gatePushWarning ?? "it exists only in this checkout") +
+          `. An operator elsewhere cannot approve it until it does.`,
+      );
+    }
   } else {
     write(`interpret run failed at component "${result.failedComponent}"`);
   }

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)) {