@intentius/chant 0.72.3 → 0.72.5

package/src/discovery/sandbox/fork-diagnostic.test.ts

@@ -0,0 +1,125 @@
+import { describe, test, expect } from "vitest";
+import { fork } from "node:child_process";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runFallbackFilesSandboxed } from "./run";
+
+/**
+ * chant#2461 — a child that ends without a usable result says which way it did.
+ *
+ * The parent had one sentence for three unrelated situations: `child exited
+ * before reporting results (code N, signal S)`. The one seen in the wild is the
+ * hardest to read — exit code 0, empty stderr, no message — because it reads as
+ * if the child was cut off, and it was not. It ran to completion and sent
+ * nothing.
+ *
+ * These tests pin the two mechanisms that produce that signature, against real
+ * forked children rather than a mock, because the whole question is what Node
+ * actually does:
+ *
+ *   - an `await` that never settles, which drains the loop and exits 0
+ *   - a payload the parent's `isResponse` refuses, which used to be dropped in
+ *     silence and then reported as though nothing had been sent
+ *
+ * A third mechanism was proposed in the issue and is NOT covered, because it
+ * was measured and does not happen: `process.send` racing the child's reap so
+ * that `exit` is dispatched before an already-queued `message`. With the parent
+ * blocked so both were certainly pending, `message` won 60 times out of 60. The
+ * live IPC channel keeps the child alive until the payload flushes, and the
+ * driver has no `process.exit()` to cut that short. The last test here records
+ * that, so the disproof is not lost with the transcript.
+ */
+function runChild(source: string): Promise<{ code: number | null; message: unknown; stderr: string }> {
+  const dir = mkdtempSync(join(tmpdir(), "chant-fork-diag-"));
+  const file = join(dir, "child.mjs");
+  writeFileSync(file, source);
+  return new Promise((resolve) => {
+    const child = fork(file, [], { stdio: ["ignore", "pipe", "pipe", "ipc"] });
+    let stderr = "";
+    let message: unknown;
+    child.stderr?.on("data", (d: Buffer) => { stderr += d.toString(); });
+    child.on("message", (m) => { message = m; });
+    child.on("exit", (code) => {
+      rmSync(dir, { recursive: true, force: true });
+      resolve({ code, message, stderr });
+    });
+  });
+}
+
+describe("why a sandboxed child ends without a result (chant#2461)", () => {
+  test("an await that never settles exits 0, silently, having sent nothing", async () => {
+    // The observed signature, reproduced. `main().catch(...)` catches a
+    // REJECTION; a promise that never settles is not one, so the driver's own
+    // fatal-payload path never runs either.
+    const r = await runChild(
+      'async function main() { await new Promise(() => {}); process.send({ ok: true }); }\n' +
+        "main().catch((e) => process.send({ fatal: String(e) }));\n",
+    );
+
+    expect(r.code).toBe(0);
+    expect(r.message).toBeUndefined();
+    expect(r.stderr.trim()).toBe("");
+  });
+
+  test("a child that sends and falls off the end always gets its message through", async () => {
+    // The disproof, kept as a test. If this ever fails, the race the issue
+    // proposed is real after all and the diagnostic's wording needs revisiting.
+    const results = await Promise.all(
+      Array.from({ length: 12 }, () => runChild("process.send({ ok: true });\n")),
+    );
+
+    for (const r of results) {
+      expect(r.code).toBe(0);
+      expect(r.message).toEqual({ ok: true });
+    }
+  });
+
+  test("a rejection still reaches the parent, so the fatal path is not what broke", async () => {
+    // Establishes the contrast: the driver's catch works. It is specifically an
+    // unsettled promise that escapes it.
+    const r = await runChild(
+      'async function main() { throw new Error("boom"); }\n' +
+        "main().catch((e) => process.send({ fatal: String(e) }));\n",
+    );
+
+    expect(r.message).toEqual({ fatal: "Error: boom" });
+  });
+
+  test("a project file with an unsettled top-level await reproduces it end to end", async () => {
+    // The run path's real mechanism, not a stand-in. `main()` does
+    // `await import(<project file>)` per run-fallback file, module scope is
+    // arbitrary project source, and a top level that awaits something which
+    // never settles makes that import never complete. Nothing keeps the loop
+    // alive, so Node exits 0 having sent nothing.
+    //
+    // This is what the diagnostic's wording is checked against. Before
+    // chant#2461 it said only "child exited before reporting results", which
+    // gave a reader nothing to look at.
+    const root = mkdtempSync(join(tmpdir(), "chant-tla-"));
+    try {
+      mkdirSync(join(root, "src"), { recursive: true });
+      writeFileSync(
+        join(root, "src", "hangs.ts"),
+        "await new Promise<void>(() => {});\nexport const never = { reached: true };\n",
+      );
+
+      const result = await runFallbackFilesSandboxed([join(root, "src", "hangs.ts")], root);
+
+      const message = result.errors.map((e) => e.message).join("\n");
+      expect(message).toContain("child exited before reporting results (code 0, signal null)");
+
+      // chant#2461's user-facing half: the child names the file it was
+      // importing when its loop drained. It cannot `process.send` from an exit
+      // handler — that is asynchronous and the channel will never be serviced —
+      // so it writes synchronously to stderr, which the parent captures and
+      // forwards. Without this the build dies silently and nothing anywhere
+      // says which file.
+      expect(message).toContain("never finished evaluating");
+      expect(message).toContain("hangs.ts");
+      expect(message).toContain("top-level");
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  }, 120_000);
+});

package/src/discovery/sandbox/fork.ts

@@ -125,6 +125,86 @@ function lineBuffered(emit: (line: string) => void) {
  * resolve with the first IPC message that satisfies `isResponse` (or reject
  * on crash / timeout / fork error).
  */
+/**
+ * Why a child ended without a usable result, in terms a reader can act on.
+ *
+ * chant#2461 — this used to be one sentence, `child exited before reporting
+ * results (code N, signal S)`, for three unrelated situations. The one that
+ * was observed in the wild is the hardest to read: exit code 0, empty stderr,
+ * no message. That reads like the child was cut off, and it was not — it ran
+ * to completion and sent nothing.
+ *
+ * Two mechanisms produce it, and the driver decides which is possible.
+ *
+ * The first is an `await` that never settles. `main().catch(...)` catches a
+ * REJECTION, and a promise that never settles is not one, so if nothing keeps
+ * the loop alive Node drains it and exits 0 having sent nothing and written
+ * nothing. Nothing else in the process reports that.
+ *
+ * On the RUN path that is not hypothetical, and it is reproducible: the driver
+ * does `await import(<project file>)` for each run-fallback file, module scope
+ * is arbitrary project source, and a file whose top level awaits something that
+ * never settles makes that import never complete. A fixture doing exactly that
+ * yields this error, which is how the wording here was checked rather than
+ * guessed.
+ *
+ * The second is the payload being lost between `process.send` and exit.
+ *
+ * For the CONFIG driver the first is impossible, which is worth stating because
+ * it was the working hypothesis until the bundle was read. Its `await
+ * import(configPath)` bundles to `await Promise.resolve().then(() =>
+ * (init_chant_config(), chant_config_exports))` — one microtask over
+ * synchronous code — and the bundle has no runtime imports, no dynamic
+ * `import(`, and exactly one `process.send`. There is nothing there to hang on.
+ * So a config child that exits 0 with nothing sent DID send, and the payload
+ * did not arrive.
+ *
+ * The exit/message race originally proposed in chant#2461 is a third thing and
+ * is not it: with the parent blocked so a queued payload and the reap were both
+ * pending, `message` was dispatched first 60 times out of 60, because the live
+ * IPC channel keeps the child alive until the payload flushes.
+ */
+function describeSilentExit(
+  label: string,
+  code: number | null,
+  signal: NodeJS.Signals | null,
+  stderrBuf: string,
+  unrecognised: readonly unknown[],
+): string {
+  const stderr = stderrBuf.trim();
+  const head = `${label}: child exited before reporting results (code ${code}, signal ${signal})`;
+
+  if (unrecognised.length > 0) {
+    // It DID send. The parent refused the shape, which is a bug in one of them
+    // and not the child dying early.
+    const shapes = unrecognised
+      .map((m) => (m && typeof m === "object" ? `{${Object.keys(m as object).join(", ")}}` : typeof m))
+      .join(", ");
+    return (
+      `${head}. It sent ${unrecognised.length} message(s) the parent did not recognise (${shapes}), ` +
+      `so the payload shape and the parent's check disagree` +
+      (stderr ? `: ${stderr}` : "")
+    );
+  }
+
+  if (stderr) return `${head}: ${stderr}`;
+  if (code !== 0 || signal !== null) return head;
+
+  // Exit 0, nothing on stderr, nothing sent. The child finished normally and
+  // the parent has nothing. Two mechanisms produce exactly this, and which one
+  // it is depends on the driver — see this function's doc.
+  return (
+    `${head}. It exited cleanly with nothing on stderr and sent no message, so the child drained ` +
+    `its loop without sending: something it awaited never settled. On the run path the usual ` +
+    `cause is a project file with a top-level \`await\` that does not settle — module scope is ` +
+    `arbitrary project source, and an import of such a file never completes. A promise that ` +
+    `never settles is not a rejection, so the driver's own \`main().catch\` does not see it ` +
+    `either, which is why nothing is written anywhere. The config driver bundles to one ` +
+    `microtask over synchronous code with no runtime I/O, so on THAT path nothing can hang and ` +
+    `the payload was lost between \`process.send\` and exit instead (chant#2461).`
+  );
+}
+
 export function forkSandboxed<T>(
   options: SandboxForkOptions,
   isResponse: (value: unknown) => value is T,
@@ -144,6 +224,8 @@ export function forkSandboxed<T>(
 
     let settled = false;
     let stderrBuf = "";
+    /** Messages the child sent that `isResponse` refused — see the `message` handler. */
+    const unrecognised: unknown[] = [];
 
     const timeout = setTimeout(() => {
       if (settled) return;
@@ -185,7 +267,15 @@ export function forkSandboxed<T>(
     child.stderr?.on("end", () => stderrForwarder.flush());
 
     child.on("message", (msg: unknown) => {
-      if (settled || !isResponse(msg)) return;
+      if (settled) return;
+      if (!isResponse(msg)) {
+        // chant#2461 — remember it rather than dropping it. A child that sent
+        // something the parent does not recognise is a different failure from
+        // a child that sent nothing, and both used to arrive as "exited before
+        // reporting results" with no way to tell them apart.
+        unrecognised.push(msg);
+        return;
+      }
       settled = true;
       clearTimeout(timeout);
       // chant #1131 — the child's entire job is to send this one message, so
@@ -212,11 +302,7 @@ export function forkSandboxed<T>(
       if (settled) return;
       settled = true;
       clearTimeout(timeout);
-      reject(
-        new Error(
-          `${label}: child exited before reporting results (code ${code}, signal ${signal})${stderrBuf.trim() ? `: ${stderrBuf.trim()}` : ""}`,
-        ),
-      );
+      reject(new Error(describeSilentExit(label, code, signal, stderrBuf, unrecognised)));
     });
   });
 }

package/src/fold/subset.ts

@@ -210,13 +210,25 @@ import { intrinsicCallFolds, intrinsicCallFoldsEagerly, type IntrinsicDef } from
  *   binding whatever an invoked factory returns is what chant never checked
  *   (`L8.19`), and a declarator reaching a call through a const alias is what
  *   chant resolves while refusing a call nested elsewhere (`L2.18`).
+ * - **1.7** put `F-Eval-CallLocal` before the two registered call shapes, so a
+ *   call through a name the project bound is the project function's call
+ *   whatever the registry says. That is what chant's whole-build fold already
+ *   did, and the reason the specification moved rather than chant: probes with
+ *   chant's own `output` showed the binding-first order living in
+ *   `resolveCallExpression`, while `L2.11` described the expression
+ *   classifier. The two were never required to share an order.
+ * - **1.8** added `ι = executing`, and chant carries it as of `0.72.3`
+ *   (#2455) — `FoldProjectOptions.executing`, mutually exclusive with
+ *   `sandbox`. `open` stays the default and stays strict (#2453).
  *
  * `scripts/check-docs-citations.ts` refuses to run when this constant and the
  * pinned specification disagree, so `.github/workflows/docs-check.yml` pins the
- * `spec-1.6` commit and the two move together. That coupling is deliberate: it
- * is what stops the docs being gated against a rule set nobody writes against.
+ * `spec-1.8` commit and the two move together. That coupling is deliberate: it
+ * is what stops the docs being gated against a rule set nobody writes against
+ * — which is exactly what happened while this sat at `1.0` through six
+ * versions, passing because both sides were equally stale.
  */
-export const SPEC_VERSION = "1.6";
+export const SPEC_VERSION = "1.8";
 
 /** The two EVL rule ids a shape violation can be attributed to. */
 export type SubsetRuleId = "EVL001" | "EVL003";

package/src/observation.ts

@@ -57,14 +57,33 @@ export type UnobservedReason =
   | "unsupported-kind"
   | "filtered";
 
-/** Every legal {@link UnobservedReason}, for validation and conformance checks. */
-export const UNOBSERVED_REASONS: readonly UnobservedReason[] = [
-  "read-failed",
-  "no-credentials",
-  "no-binding",
-  "unsupported-kind",
-  "filtered",
-];
+/**
+ * Every legal {@link UnobservedReason}, for validation and conformance checks.
+ *
+ * Derived from a witness keyed off the union rather than written out beside it
+ * (chant#2366). A hand-maintained array is only ever checked for holding legal
+ * members, never for holding ALL of them, so a reason added to the type left
+ * the array silently short — `tsc` clean, every observation test green, and a
+ * value the type permits that `observation-conformance.ts` refuses. A lexicon
+ * could construct a value its own suite rejected.
+ *
+ * Keying a `Record` off the union makes the omission a compile error at the
+ * point of the omission. This is the construction #2365 applied to all four
+ * closed sets in `./behaviour.ts`; `BEHAVIOUR_UNPREDICTED_REASONS` derives from
+ * this very type, so that module was already protected against a change here
+ * while this module was not.
+ */
+const UNOBSERVED_REASON_WITNESS: Record<UnobservedReason, true> = {
+  "read-failed": true,
+  "no-credentials": true,
+  "no-binding": true,
+  "unsupported-kind": true,
+  filtered: true,
+};
+
+export const UNOBSERVED_REASONS: readonly UnobservedReason[] = Object.keys(
+  UNOBSERVED_REASON_WITNESS,
+) as UnobservedReason[];
 
 /** True when `value` is a legal {@link UnobservedReason}. */
 export function isUnobservedReason(value: unknown): value is UnobservedReason {

package/src/op/activities/converge-push.test.ts

@@ -0,0 +1,101 @@
+import { describe, test, expect, vi, beforeEach } from "vitest";
+
+/**
+ * chant#2337 — a converge tick says whether its record reached the remote.
+ *
+ * `convergeTick` ended with `await pushLifecycle().catch(() => undefined)`, the
+ * last instance of the idiom #2310 was filed about. The append is local-first
+ * and always lands, so the tick's own result was correct either way — what was
+ * missing is whether anyone else can see it.
+ *
+ * Softer than the gate's version of the same bug, which #2336 fixed: a lost
+ * tick record is an informational log rather than an approval, so nobody is
+ * left waiting on a fact they cannot see. It is still not success, and a
+ * converge loop reporting a clean tick while its ledger never leaves the
+ * machine is telling an operator something untrue.
+ */
+const execMock = vi.fn();
+vi.mock("node:child_process", () => ({
+  exec: (cmd: string, _opts: unknown, cb: (e: Error | null, r: { stdout: string; stderr: string }) => void) =>
+    cb(null, { stdout: execMock(cmd) as string, stderr: "" }),
+}));
+
+const pushLifecycle = vi.fn();
+vi.mock("../../lifecycle/git", () => ({
+  fetchLifecycle: vi.fn(async () => undefined),
+  pushLifecycle: (...args: unknown[]) => pushLifecycle(...args) as Promise<boolean>,
+}));
+
+vi.mock("../../lifecycle/converge-ledger", async (orig) => {
+  const actual = (await orig()) as Record<string, unknown>;
+  return {
+    ...actual,
+    readConvergeLedger: vi.fn(async () => ({ records: [] })),
+    appendConvergeRecord: vi.fn(async (record: Record<string, unknown>) => ({
+      record: { ...record, id: "tick-1" },
+    })),
+  };
+});
+
+const { convergeTick } = await import("./converge");
+
+/** A tick with nothing to do: no drift, no rules, so only the ledger write matters. */
+async function tick(): Promise<Awaited<ReturnType<typeof convergeTick>>> {
+  return convergeTick({ opName: "demo", env: "prod", rules: [], dial: "report" } as never);
+}
+
+describe("a converge tick reports its push outcome (chant#2337)", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    execMock.mockImplementation((cmd: string) =>
+      cmd.includes("lifecycle plan")
+        ? JSON.stringify({ env: "prod", entries: [] })
+        : JSON.stringify([]),
+    );
+  });
+
+  test("a push that lands reports pushed, with no warning", async () => {
+    pushLifecycle.mockResolvedValue(true);
+
+    const result = await tick();
+
+    expect(result.pushed).toBe(true);
+    expect(result.pushWarning).toBeUndefined();
+  });
+
+  test("a REJECTED push is reported, not swallowed", async () => {
+    // Red before chant#2337: `.catch(() => undefined)` meant the tick returned
+    // the same shape whether or not the record left the machine.
+    pushLifecycle.mockRejectedValue(new Error("remote rejected: chant/lifecycle has moved"));
+
+    const result = await tick();
+
+    expect(result.pushed).toBe(false);
+    expect(result.pushWarning).toContain("remote rejected");
+  });
+
+  test("no remote configured is reported too, and says which it is", async () => {
+    // `pushLifecycle` returns false rather than throwing when there is no
+    // remote. That is not an error, but it is not a push either, and the two
+    // reasons are worth telling apart in the warning.
+    pushLifecycle.mockResolvedValue(false);
+
+    const result = await tick();
+
+    expect(result.pushed).toBe(false);
+    expect(result.pushWarning).toMatch(/no remote/i);
+  });
+
+  test("the tick's own findings are unaffected by a failed push", async () => {
+    // The append is local-first and always lands. A push failure must not make
+    // the tick misreport what it observed, or the fix would have traded one
+    // wrong answer for another.
+    pushLifecycle.mockRejectedValue(new Error("nope"));
+
+    const result = await tick();
+
+    expect(result.id).toBe("tick-1");
+    expect(result.drifted).toBe(false);
+    expect(typeof result.log).toBe("string");
+  });
+});

package/src/op/activities/converge.ts

@@ -104,6 +104,22 @@ export interface ConvergeTickResult {
   gated: number;
   /** The one human-readable summary line this tick produced. */
   log: string;
+  /**
+   * Whether this tick's ledger record reached the remote (chant#2337).
+   *
+   * The append is local-first and always lands, so the tick's own result is
+   * correct either way — this says whether anyone else can see it. Before
+   * this, the push was `.catch(() => undefined)` and the tick reported success
+   * whether or not the record left the machine, which is the last instance of
+   * the idiom #2310 was filed about.
+   *
+   * Softer than the gate's version of the same bug (#2336): a lost tick record
+   * is an informational log rather than an approval, so nobody is stranded
+   * waiting on a fact they cannot see. It is still not success.
+   */
+  pushed: boolean;
+  /** Why the record did not reach the remote, when `pushed` is false. */
+  pushWarning?: string;
 }
 
 function shellQuote(s: string): string {
@@ -442,7 +458,19 @@ export async function convergeTick(args: ConvergeTickArgs, signal?: AbortSignal)
     },
     log,
   });
-  await pushLifecycle().catch(() => undefined);
+  // chant#2337 — reported rather than swallowed, the way #2336 does it for the
+  // gate. A push that did not land leaves a correct local record nobody else
+  // can read, and the caller is the only one positioned to say so.
+  let pushed = false;
+  let pushWarning: string | undefined;
+  try {
+    pushed = await pushLifecycle();
+    if (!pushed) {
+      pushWarning = "no remote is configured for chant/lifecycle — the tick record was recorded locally only";
+    }
+  } catch (err) {
+    pushWarning = err instanceof Error ? err.message : String(err);
+  }
 
   return {
     id: record.id,
@@ -455,5 +483,7 @@ export async function convergeTick(args: ConvergeTickArgs, signal?: AbortSignal)
     unobserved: record.summary.unobserved,
     adopted: record.summary.adopted,
     log: record.log,
+    pushed,
+    ...(pushWarning !== undefined ? { pushWarning } : {}),
   };
 }