@intentius/chant 0.122.0 → 0.123.0

package/src/lifecycle/gate-ledger.ts

@@ -42,13 +42,21 @@
  * `"resolution"` is the default reading).
  */
 import { isNeverOverMcpGateOp } from "../op/gate-name";
-import { samePlanDigest } from "./plan-digest";
 import { sortedJsonReplacer } from "../utils";
 import { currentGateOrigin, type GateOrigin } from "./gate-origin";
 import type { GateApprover, GatePolicyDecision, ResolvedGateApproval } from "../op/gate-approval";
 import type { GateRunLocator } from "../op/gate-resume";
 import { readBlobFromPath, readPathSha, readBlobBySha, writeBlobToPath, RefCASConflictError } from "./git";
 
+// The selection rules a gate decides by live apart, so a bundle can import them without git (#3763).
+export {
+  isPendingGateExpired,
+  latestPendingGate,
+  latestResolutionForPlan,
+  latestResolutionSince,
+  type PlanBoundResolution,
+} from "./gate-ledger-select";
+
 const DIR = "_gates";
 
 /** The directory on the `chant/lifecycle` branch that holds gate ledgers, under a member's prefix when it has one. */
@@ -337,11 +345,6 @@ export type GateLedgerRecord = GateResolutionRecord | PendingGateRecord;
 /** The default a gate's pending fact expires after when its `GateStep` declares no `timeout` — the same 48h `GateStep.timeout` documents as its own default. */
 export const DEFAULT_GATE_EXPIRY = "48h";
 
-/** Whether a pending fact has aged out of relevance at `nowIso`. */
-export function isPendingGateExpired(record: PendingGateRecord, nowIso: string): boolean {
-  return new Date(record.expiresAt).getTime() <= new Date(nowIso).getTime();
-}
-
 function filename(op: string): string {
   return `${op}.jsonl`;
 }
@@ -504,101 +507,3 @@ export async function readGateResolutions(
   const { resolutions, malformed } = await readGateLedger(op, opts);
   return { records: resolutions, malformed };
 }
-
-/** The most recent pending fact for `gate`, expired or not — the anchor {@link latestResolutionSince} measures a resolution against. `undefined` when the gate has never been recorded pending. */
-export function latestPendingGate(
-  records: PendingGateRecord[],
-  gate: string,
-): PendingGateRecord | undefined {
-  let latest: PendingGateRecord | undefined;
-  for (const r of records) {
-    if (r.gate !== gate) continue;
-    if (!latest || new Date(r.timestamp).getTime() >= new Date(latest.timestamp).getTime()) latest = r;
-  }
-  return latest;
-}
-
-/** The most recent resolution for `gate` recorded after `sinceIso` (a gated tick's own timestamp) — what `chant operator status` uses to tell a resolved gate from a still-pending one. `undefined` when no such resolution exists. */
-export function latestResolutionSince(
-  records: GateResolutionRecord[],
-  gate: string,
-  sinceIso: string,
-): GateResolutionRecord | undefined {
-  const since = new Date(sinceIso).getTime();
-  let latest: GateResolutionRecord | undefined;
-  for (const r of records) {
-    if (r.gate !== gate) continue;
-    if (new Date(r.timestamp).getTime() < since) continue;
-    if (!latest || new Date(r.timestamp).getTime() >= new Date(latest.timestamp).getTime()) latest = r;
-  }
-  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 (an Op `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 (samePlanDigest(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/override-ledger.test.ts

@@ -0,0 +1,63 @@
+/**
+ * #3760: the override gate's lines on chant/lifecycle. A denial is an
+ * ordinary pending fact on `_gates/policy-override.jsonl`, and applied
+ * records sit beside it where no gate reader lists them.
+ */
+import { describe, expect, test } from "vitest";
+import { withTestDir } from "@intentius/chant-test-utils";
+import { spawnSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { appendGateResolution, readGateLedger } from "./gate-ledger";
+import { readOverrideLedger, recordOverrideDenial, recordOverridesApplied } from "./override-ledger";
+import { appliedOverride, decideOverride, overrideDigest, OVERRIDE_OP } from "../override-gate";
+import { readBlobFromPath } from "./git";
+
+function initRepo(dir: string): void {
+  const git = (args: string[]) => spawnSync("git", args, { cwd: dir, encoding: "utf-8" });
+  git(["init", "-q", "-b", "main"]);
+  git(["config", "user.email", "test@chant.dev"]);
+  git(["config", "user.name", "Test"]);
+  writeFileSync(join(dir, "README.md"), "fixture\n");
+  git(["add", "README.md"]);
+  git(["commit", "-q", "-m", "init"]);
+}
+
+const PLAN = `sha256:${"a".repeat(64)}`;
+
+describe("lifecycle/override-ledger", () => {
+  test("a denial, its override and the applied record round-trip, and the override is spent", async () => {
+    await withTestDir(async (dir) => {
+      initRepo(dir);
+      const opts = { cwd: dir };
+      const { record: denial } = await recordOverrideDenial(
+        { subject: "prod", planDigest: PLAN, rules: ["no-drop"], timestamp: "2026-10-11T10:00:00.000Z", expiresAt: "2026-10-13T00:00:00.000Z" },
+        opts,
+      );
+      expect(denial).toMatchObject({ op: OVERRIDE_OP, gate: "prod", plan: PLAN, rules: ["no-drop"], planDigest: overrideDigest("prod", PLAN, ["no-drop"]), neverOverMcp: true });
+      await appendGateResolution(
+        { op: OVERRIDE_OP, gate: "prod", resolvedBy: "github:alice", timestamp: "2026-10-11T11:00:00.000Z", planDigest: denial.planDigest, note: "the column is unused since 0.6" },
+        opts,
+      );
+
+      const ledger = await readOverrideLedger(opts);
+      const input = { ledger, applied: ledger.applied, subject: "prod", planDigest: PLAN, rules: ["no-drop"], overriders: ["github:alice"], now: "2026-10-11T12:00:00.000Z" };
+      const decided = decideOverride(input);
+      expect(decided.status).toBe("overridden");
+      if (decided.status !== "overridden") return;
+
+      await recordOverridesApplied([appliedOverride(decided.override, { timestamp: "2026-10-11T12:00:00.000Z" })], opts);
+      await recordOverridesApplied([], opts);
+      const after = await readOverrideLedger(opts);
+      expect(after.applied).toHaveLength(1);
+      expect(decideOverride({ ...input, ledger: after, applied: after.applied }).status).toBe("none");
+
+      // The gate ledger reads the denial and the override, and nothing in the applied file.
+      const gates = await readGateLedger(OVERRIDE_OP, opts);
+      expect(gates).toMatchObject({ malformed: 0 });
+      expect(gates.pending).toHaveLength(1);
+      expect(gates.resolutions).toHaveLength(1);
+      expect(await readBlobFromPath(`_gates/${OVERRIDE_OP}`, "applied.jsonl", opts)).toContain('"kind":"applied"');
+    });
+  });
+});

package/src/lifecycle/override-ledger.ts

@@ -0,0 +1,69 @@
+/**
+ * The override gate's lines on `chant/lifecycle` (#3760): read the denials,
+ * overrides and applied records, record a denial, and record that a run
+ * applied under an override, which spends it. The decision is
+ * `../override-gate.ts`'s, which bundles without this module's git code.
+ *
+ * Denials and overrides share `_gates/policy-override.jsonl` with the
+ * ordinary gate line shapes, so `chant approve`, `chant operator status` and
+ * the audit reader read them as they read any gate. Applied records live in
+ * `_gates/policy-override/applied.jsonl`, which no gate reader lists.
+ */
+
+import { sortedJsonReplacer } from "../utils";
+import { appendPendingGate, readGateLedger, type GateResolutionRecord, type PendingGateRecord } from "./gate-ledger";
+import { readBlobBySha, readBlobFromPath, readPathSha, RefCASConflictError, writeBlobToPath } from "./git";
+import {
+  OVERRIDE_OP,
+  parseAppliedOverrides,
+  overridePending,
+  type AppliedOverrideRecord,
+  type OverridePendingInput,
+  type OverridePendingRecord,
+} from "../override-gate";
+
+const APPLIED_DIR = `_gates/${OVERRIDE_OP}`;
+const APPLIED_FILE = "applied.jsonl";
+const APPEND_RETRY_ATTEMPTS = 5;
+
+export interface OverrideLedger {
+  resolutions: GateResolutionRecord[];
+  pending: PendingGateRecord[];
+  applied: AppliedOverrideRecord[];
+}
+
+/** The override ledger and its applied records, oldest first. Empty when nothing is recorded. */
+export async function readOverrideLedger(opts?: { cwd?: string }): Promise<OverrideLedger> {
+  const { resolutions, pending } = await readGateLedger(OVERRIDE_OP, opts);
+  const text = await readBlobFromPath(APPLIED_DIR, APPLIED_FILE, opts);
+  return { resolutions, pending, applied: text ? parseAppliedOverrides(text) : [] };
+}
+
+/** Append a denial's pending fact ({@link overridePending}). Does not push. */
+export async function recordOverrideDenial(input: OverridePendingInput, opts?: { cwd?: string }): Promise<{ commit: string; record: OverridePendingRecord }> {
+  const { version: _v, kind: _k, ...rest } = overridePending(input);
+  const { commit, record } = await appendPendingGate(rest, opts);
+  return { commit, record: record as OverridePendingRecord };
+}
+
+/** Append applied records, spending the overrides they name. Write them before applying; a write that fails should stop the run. Does not push. */
+export async function recordOverridesApplied(records: readonly AppliedOverrideRecord[], opts?: { cwd?: string }): Promise<string | undefined> {
+  if (records.length === 0) return undefined;
+  const lines = records.map((r) => JSON.stringify(r, sortedJsonReplacer)).join("\n");
+  let lastErr: unknown;
+  for (let attempt = 1; attempt <= APPEND_RETRY_ATTEMPTS; attempt++) {
+    try {
+      const priorSha = await readPathSha(APPLIED_DIR, APPLIED_FILE, opts);
+      const existing = priorSha ? await readBlobBySha(priorSha, opts) : null;
+      const content = existing ? `${existing.replace(/\n$/, "")}\n${lines}` : lines;
+      return await writeBlobToPath(APPLIED_DIR, APPLIED_FILE, content, `Applied under override: ${records.map((r) => r.gate).join(", ")}`, {
+        ...opts,
+        expectPriorPathSha: priorSha,
+      });
+    } catch (err) {
+      if (!(err instanceof RefCASConflictError)) throw err;
+      lastErr = err;
+    }
+  }
+  throw lastErr;
+}

package/src/lifecycle/rollback.ts

@@ -12,6 +12,7 @@ import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { ghHostEnv } from "../op/activities/gh-host";
 
 const execFileAsync = promisify(execFile);
 
@@ -106,10 +107,13 @@ export async function rollbackToRevision(opts: {
 
     await git(["commit", "-m", rollbackTitle(env, ref)], wt);
     await git(["push", "-u", "origin", branch], wt);
+    // `gh pr create` names no host: tell it the one `origin` is on, or the
+    // CI job's forge, so a GitHub Enterprise Server or Forgejo checkout is not
+    // sent to github.com (#3780).
     const { stdout } = await execFileAsync(
       "gh",
       ["pr", "create", "--title", rollbackTitle(env, ref), "--body", rollbackBody(env, ref, sourceDir), "--head", branch],
-      { cwd: wt },
+      { cwd: wt, env: await ghHostEnv(process.env, wt) },
     );
     return { noop: false, branch, prUrl: stdout.trim() };
   } finally {

package/src/lifecycle/work-item-id.test.ts

@@ -0,0 +1,71 @@
+/**
+ * #2815 — a work item id has to be a ref path segment git accepts. The cases
+ * are checked against `git check-ref-format` itself, in every ref the id lands in.
+ */
+import { describe, expect, test } from "vitest";
+import { spawnSync } from "node:child_process";
+import { isWorkItemId, workItemIdProblem } from "./work-item-id";
+
+function gitAccepts(ref: string): boolean {
+  return spawnSync("git", ["check-ref-format", ref]).status === 0;
+}
+
+const REF_SHAPES = [
+  (id: string) => `refs/chant/lease/work/${id}`,
+  (id: string) => `refs/chant/lease/_members/api/work/${id}`,
+  (id: string) => `refs/chant/kept/api/${id}/0123abcd`,
+  (id: string) => `refs/heads/chant/work/api/${id}`,
+];
+
+const ACCEPTED = ["W-001", "upgrade-1", "a", "0", "a.b", "a_b", "v1.2.3", "x.lock2", "lock", "a.lockb", "A".repeat(100)];
+const REFUSED = [
+  "upgrade-.",
+  ".",
+  "x.",
+  "x.lock",
+  "x.LOCK",
+  "x.Lock",
+  "a..b",
+  "..",
+  ".hidden",
+  "-lead",
+  "_lead",
+  "a/b",
+  "a b",
+  "a~b",
+  "a^b",
+  "a:b",
+  "a?b",
+  "a*b",
+  "a[b",
+  "a\\b",
+  "a@{b",
+  "@",
+  "",
+  "a\tb",
+  "A".repeat(101),
+];
+
+describe("work item id (#2815)", () => {
+  test.each(ACCEPTED)("%s keys a lease, and git takes it in every ref it lands in", (id) => {
+    expect(workItemIdProblem(id)).toBeUndefined();
+    expect(isWorkItemId(id)).toBe(true);
+    for (const shape of REF_SHAPES) expect(gitAccepts(shape(id)), shape(id)).toBe(true);
+  });
+
+  test.each(REFUSED)("%j is refused", (id) => {
+    expect(workItemIdProblem(id)).toMatch(/can't key a work lease/);
+    expect(isWorkItemId(id)).toBe(false);
+  });
+
+  test("everything git refuses in the lease ref is refused here", () => {
+    for (const id of REFUSED.filter((i) => i !== "" && !i.includes("\t") && i.length <= 100)) {
+      if (!gitAccepts(`refs/chant/lease/work/${id}`)) expect(isWorkItemId(id), id).toBe(false);
+    }
+  });
+
+  test("a non-string is refused", () => {
+    expect(workItemIdProblem(undefined)).toMatch(/not a string/);
+    expect(isWorkItemId(42)).toBe(false);
+  });
+});

package/src/lifecycle/work-item-id.ts

@@ -0,0 +1,35 @@
+/**
+ * What a work item id has to be to key a work lease (#2815). The id lands in
+ * refs (`refs/chant/lease/work/<id>`, `refs/chant/kept/.../<item>/<token>`,
+ * the work branch `chant/work/.../<id>`) and in a file name
+ * (`_leases/<id>.jsonl`), so it has to be a valid ref path segment under
+ * `git check-ref-format`, and git's check is stricter than a character class.
+ *
+ * Kept free of imports so `Op()`, `declareSteward` and the CLI can all call it
+ * without loading the lease machinery.
+ */
+
+/** The characters an id may use: letters, digits, ".", "_" and "-", starting with a letter or digit, at most 100. */
+export const WORK_ITEM_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
+
+/**
+ * Why `id` can't key a work lease, or `undefined` when it can. On top of
+ * {@link WORK_ITEM_ID_PATTERN}, git refuses a ref component that has `..`,
+ * ends in `.`, or ends in `.lock` (git's own lock file for the ref; matched
+ * case-insensitively here since a case-folding filesystem would collide).
+ */
+export function workItemIdProblem(id: unknown): string | undefined {
+  if (typeof id !== "string") return `${JSON.stringify(id)} is not a string`;
+  if (!WORK_ITEM_ID_PATTERN.test(id)) {
+    return `${JSON.stringify(id)} can't key a work lease: use letters, digits, ".", "_" and "-", starting with a letter or digit, at most 100 characters`;
+  }
+  if (id.includes("..")) return `${JSON.stringify(id)} can't key a work lease: git refuses ".." in a ref name`;
+  if (id.endsWith(".")) return `${JSON.stringify(id)} can't key a work lease: git refuses a ref name ending in "."`;
+  if (id.toLowerCase().endsWith(".lock")) return `${JSON.stringify(id)} can't key a work lease: git refuses a ref name ending in ".lock"`;
+  return undefined;
+}
+
+/** Whether `id` can key a work lease. */
+export function isWorkItemId(id: unknown): id is string {
+  return workItemIdProblem(id) === undefined;
+}

package/src/lifecycle/work-lease.ts

@@ -50,6 +50,7 @@ import {
 import { dirname } from "node:path";
 import type { ReasonCode } from "../workspace/reason-codes";
 import { resolveMemberLedger } from "./member-ledger";
+import { WORK_ITEM_ID_PATTERN, isWorkItemId, workItemIdProblem } from "./work-item-id";
 
 /** The key prefix of a work lease under the operator lease's ref namespace. */
 export const WORK_LEASE_KEY_PREFIX = "work/";
@@ -60,8 +61,7 @@ export const LEASES_DIR = "_leases";
 /** How long a claim lasts unless renewed: chud's default, which its dispatcher renews at a third of. */
 export const DEFAULT_WORK_LEASE_TTL_MS = 10 * 60_000;
 
-/** A work item id a lease can be keyed by: one ref path segment and one file name. */
-export const WORK_ITEM_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
+export { WORK_ITEM_ID_PATTERN, isWorkItemId, workItemIdProblem };
 
 /** How long a claim waits out another process's lock on the ref before calling it stale. */
 const LOCK_WAIT_MS = 2_000;
@@ -245,9 +245,8 @@ function toWorkLease(item: string, r: LeaseRecord): WorkLease {
 }
 
 function checkId(id: string): void {
-  if (!WORK_ITEM_ID_PATTERN.test(id) || id.includes("..")) {
-    throw new Error(`${JSON.stringify(id)} can't key a work lease: use letters, digits, ".", "_" and "-", starting with a letter or digit`);
-  }
+  const problem = workItemIdProblem(id);
+  if (problem) throw new Error(problem);
 }
 
 const REASONS: Record<string, WorkLeaseRefusal> = {

package/src/lint/post-synth.test.ts

@@ -181,6 +181,35 @@ describe("telemetry attribution (#3375)", () => {
   });
 });
 
+describe("project directory (#3751)", () => {
+  const readsDir: PostSynthCheck = {
+    id: "PROJECT_DIR",
+    description: "reports the project directory the context carries",
+    check(ctx) {
+      return [{ checkId: "PROJECT_DIR", severity: "warning", message: JSON.stringify(ctx.projectDir ?? null) }];
+    },
+  };
+
+  test("the build's config directory is threaded into the context", () => {
+    const diags = runPostSynthChecks([readsDir], createBuildResult(), undefined, { projectDir: "/work/app" });
+    expect(diags[0].message).toBe('"/work/app"');
+  });
+
+  test("the loaded config is threaded too", () => {
+    const readsConfig: PostSynthCheck = {
+      id: "PROJECT_CONFIG",
+      description: "reports the config the context carries",
+      check: (ctx) => [{ checkId: "PROJECT_CONFIG", severity: "warning", message: JSON.stringify(ctx.projectConfig ?? null) }],
+    };
+    expect(runPostSynthChecks([readsConfig], createBuildResult(), undefined, { projectConfig: { sourceDir: "src" } })[0].message).toBe('{"sourceDir":"src"}');
+    expect(runPostSynthChecks([readsConfig], createBuildResult())[0].message).toBe("null");
+  });
+
+  test("a hand-built run leaves the field undefined", () => {
+    expect(runPostSynthChecks([readsDir], createBuildResult())[0].message).toBe("null");
+  });
+});
+
 describe("isPostSynthCheck", () => {
   test("accepts a well-formed check and rejects others", async () => {
     const { isPostSynthCheck } = await import("./post-synth");

package/src/lint/post-synth.ts

@@ -63,6 +63,21 @@ export interface PostSynthContext {
    * hand-built context. OTEL118 runs only when it is set.
    */
   readonly telemetry?: TelemetryAttribution;
+  /**
+   * The directory of the project config the build loaded (#3751): where a
+   * relative `sourceDir` resolves, and so where a check looks for a file the
+   * project keeps beside its source (the sql lexicon's `sql-types.d.ts`).
+   * Set by `chant build` and `chant lint`; absent from a hand-built context,
+   * where a check that reads the disk stays silent.
+   */
+  readonly projectDir?: string;
+  /**
+   * The project config the build loaded (#3751), as source lint rules get it
+   * in `LintContext.projectConfig`. A check that renders output again, as the
+   * sql lexicon's does for `sql-types.d.ts`, needs the settings the build ran
+   * with. Absent from a hand-built context.
+   */
+  readonly projectConfig?: Record<string, unknown>;
   /** Raw build result object */
   buildResult: {
     outputs: Map<string, string | SerializerResult>;
@@ -217,13 +232,15 @@ export function isPostSynthCheck(value: unknown): value is PostSynthCheck {
  * into the context so a check can branch on the current environment/stack, and
  * `opts.activityContracts` (chant #2101) carries the build's cross-lexicon
  * activity-contract map to the checks that validate Op steps against it.
- * `opts.telemetry` is the build's resolved telemetry attribution.
+ * `opts.telemetry` is the build's resolved telemetry attribution, and
+ * `opts.projectDir` and `opts.projectConfig` the config the build loaded and
+ * its directory.
  */
 export function runPostSynthChecks(
   checks: PostSynthCheck[],
   buildResult: PostSynthContext["buildResult"],
   env?: string,
-  opts?: { activityContracts?: ReadonlyMap<string, ActivityContract>; telemetry?: TelemetryAttribution },
+  opts?: { activityContracts?: ReadonlyMap<string, ActivityContract>; telemetry?: TelemetryAttribution; projectDir?: string; projectConfig?: Record<string, unknown> },
 ): PostSynthDiagnostic[] {
   const getDocs = createDocsAccessor(buildResult.outputs);
   const ctx: PostSynthContext = {
@@ -233,6 +250,8 @@ export function runPostSynthChecks(
     buildResult,
     ...(opts?.activityContracts ? { activityContracts: opts.activityContracts } : {}),
     ...(opts?.telemetry ? { telemetry: opts.telemetry } : {}),
+    ...(opts?.projectDir ? { projectDir: opts.projectDir } : {}),
+    ...(opts?.projectConfig ? { projectConfig: opts.projectConfig } : {}),
     get docs(): OutputDoc[] {
       return getDocs();
     },

package/src/notify-bundle.test.ts

@@ -0,0 +1,50 @@
+/**
+ * The notify modules bundle small (#3761, ruling #3421).
+ *
+ * terragucci runs its stages in customer CI as one bundled file with no
+ * TypeScript toolchain, and a webhook receiver imports the verifier alone.
+ * So `@intentius/chant/notify` must reach nothing but `node:crypto` and the
+ * verifier, and `@intentius/chant/notify-verify` nothing but `node:crypto`.
+ * This bundles both the way a product and a receiver would and reads
+ * esbuild's own list of what went in.
+ */
+
+import { join } from "node:path";
+import { build } from "esbuild";
+import { describe, expect, test } from "vitest";
+import { REPO } from "./workspace/__fixtures__/contract-repo";
+
+async function bundle(entry: string): Promise<{ inputs: string[]; bytes: number; imports: string[] }> {
+  const result = await build({
+    entryPoints: [join(REPO, "packages", "core", "src", entry)],
+    bundle: true,
+    platform: "node",
+    format: "esm",
+    write: false,
+    metafile: true,
+    outdir: "out",
+    logLevel: "silent",
+  });
+  const imports = Object.values(result.metafile.outputs).flatMap((o) => o.imports.map((i) => i.path));
+  return {
+    inputs: Object.keys(result.metafile.inputs).map((i) => i.replace(/^.*?packages\//, "packages/")).sort(),
+    bytes: result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0),
+    imports: [...new Set(imports)].sort(),
+  };
+}
+
+describe("the notify bundle", () => {
+  test("the sender holds itself and the verifier, and imports only node:crypto", async () => {
+    const { inputs, bytes, imports } = await bundle("notify.ts");
+    expect(inputs).toEqual(["packages/core/src/notify-verify.ts", "packages/core/src/notify.ts"]);
+    expect(imports).toEqual(["node:crypto"]);
+    expect(bytes).toBeLessThan(16 * 1024);
+  });
+
+  test("the verifier holds itself alone, and imports only node:crypto", async () => {
+    const { inputs, bytes, imports } = await bundle("notify-verify.ts");
+    expect(inputs).toEqual(["packages/core/src/notify-verify.ts"]);
+    expect(imports).toEqual(["node:crypto"]);
+    expect(bytes).toBeLessThan(4 * 1024);
+  });
+});

package/src/notify-verify.test.ts

@@ -0,0 +1,59 @@
+import { createHmac } from "node:crypto";
+import { describe, expect, test } from "vitest";
+import { DEFAULT_TOLERANCE_SECONDS, signWebhook, verifyWebhook, webhookHeaderNames } from "./notify-verify";
+
+const KEY = "s3cret";
+const NOW = 1_760_000_000;
+const BODY = JSON.stringify({ schema: "chant.notify/v1", event: "waiting" });
+
+function headers(body = BODY, ts: number | string = NOW, key = KEY, prefix = "x-chant"): Record<string, string> {
+  return { [`${prefix}-timestamp`]: String(ts), [`${prefix}-signature`]: signWebhook(key, ts, body) };
+}
+
+describe("signWebhook", () => {
+  test("is HMAC-SHA256 over <timestamp>.<body>, as sha256=<hex>", () => {
+    const hex = createHmac("sha256", KEY).update(`${NOW}.${BODY}`).digest("hex");
+    expect(signWebhook(KEY, NOW, BODY)).toBe(`sha256=${hex}`);
+  });
+});
+
+describe("verifyWebhook", () => {
+  test("accepts a fresh delivery signed with the key, and returns the event", () => {
+    expect(verifyWebhook({ body: BODY, headers: headers(), key: KEY, now: NOW + 10 })).toEqual({ ok: true, event: JSON.parse(BODY) });
+  });
+
+  test("matches header names without regard to case, and reads a Headers object and a byte body", () => {
+    const upper = Object.fromEntries(Object.entries(headers()).map(([k, v]) => [k.toUpperCase(), v]));
+    expect(verifyWebhook({ body: BODY, headers: upper, key: KEY, now: NOW }).ok).toBe(true);
+    expect(verifyWebhook({ body: new TextEncoder().encode(BODY), headers: new Headers(headers()), key: KEY, now: NOW }).ok).toBe(true);
+  });
+
+  test("refuses another key, a changed body, a moved timestamp and a missing key", () => {
+    expect(verifyWebhook({ body: BODY, headers: headers(BODY, NOW, "other"), key: KEY, now: NOW })).toEqual({ ok: false, reason: "the signature does not match" });
+    expect(verifyWebhook({ body: BODY + " ", headers: headers(), key: KEY, now: NOW }).ok).toBe(false);
+    expect(verifyWebhook({ body: BODY, headers: { ...headers(), "x-chant-timestamp": String(NOW + 1) }, key: KEY, now: NOW }).ok).toBe(false);
+    expect(verifyWebhook({ body: BODY, headers: headers(), key: "", now: NOW })).toEqual({ ok: false, reason: "no key to verify with" });
+    expect(verifyWebhook({ body: BODY, headers: headers(), key: undefined, now: NOW }).ok).toBe(false);
+  });
+
+  test("refuses a replay older than the tolerance, and one from too far ahead", () => {
+    const late = verifyWebhook({ body: BODY, headers: headers(), key: KEY, now: NOW + DEFAULT_TOLERANCE_SECONDS + 1 });
+    expect(late).toEqual({ ok: false, reason: `the timestamp is more than ${DEFAULT_TOLERANCE_SECONDS}s from now` });
+    expect(verifyWebhook({ body: BODY, headers: headers(), key: KEY, now: NOW - 61, toleranceSeconds: 60 }).ok).toBe(false);
+    expect(verifyWebhook({ body: BODY, headers: headers(), key: KEY, now: NOW + DEFAULT_TOLERANCE_SECONDS }).ok).toBe(true);
+  });
+
+  test("refuses missing or malformed headers, and a body that is not JSON", () => {
+    expect(verifyWebhook({ body: BODY, headers: {}, key: KEY, now: NOW })).toEqual({ ok: false, reason: "no x-chant-signature header" });
+    expect(verifyWebhook({ body: BODY, headers: { "x-chant-signature": "sha256=00" }, key: KEY, now: NOW }).ok).toBe(false);
+    expect(verifyWebhook({ body: BODY, headers: headers(BODY, "soon"), key: KEY, now: NOW }).ok).toBe(false);
+    expect(verifyWebhook({ body: "not json", headers: headers("not json"), key: KEY, now: NOW })).toEqual({ ok: false, reason: "the body is not JSON" });
+  });
+
+  test("reads a product's own header prefix", () => {
+    expect(webhookHeaderNames("X-Yodel")).toEqual({ signature: "x-yodel-signature", timestamp: "x-yodel-timestamp", event: "x-yodel-event", delivery: "x-yodel-delivery" });
+    const h = headers(BODY, NOW, KEY, "x-yodel");
+    expect(verifyWebhook({ body: BODY, headers: h, key: KEY, now: NOW, prefix: "x-yodel" }).ok).toBe(true);
+    expect(verifyWebhook({ body: BODY, headers: h, key: KEY, now: NOW }).ok).toBe(false);
+  });
+});