@intentius/chant 0.124.31 → 0.124.33

package/src/lexicon-dist.e2e.test.ts

@@ -0,0 +1,254 @@
+/**
+ * #3981 — lexicons loaded from compiled JS, with plain node.
+ *
+ * Lexicon packages publish compiled `dist/*.js` as each export's `default`.
+ * This compiles core and a set of real lexicons (aws and helm, which find
+ * their lint rules by directory scan, and the lexicons they import) with tsc
+ * into a scratch `node_modules`, with each lexicon's own package.json. A
+ * plain node process with no
+ * loader then loads each plugin through the compiled core, and must find the
+ * same lint rules, post-synth checks, skills and generated data as the same
+ * plugins loaded from source, without loading tsx or any TypeScript module.
+ * A `chant build` and `chant lint` of a project against the compiled aws
+ * lexicon must work and load none of the lexicon's TypeScript.
+ *
+ * End to end because it runs tsc and spawns node.
+ */
+
+import { execFileSync, spawnSync } from "node:child_process";
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+
+const coreRoot = resolve(import.meta.dirname, "..");
+const repo = resolve(coreRoot, "..", "..");
+const repoModules = join(repo, "node_modules");
+
+/** Compiled and counted. aws and helm discover their lint rules from a directory; the rest are what they import. */
+const LEXICONS = ["aws", "helm", "k8s", "grafana", "otel", "prometheus"];
+
+let scratch: string;
+let modules: string;
+let coreDist: string;
+let project: string;
+
+/**
+ * Loads each named plugin through core and prints what it found. argv[2] is a
+ * JSON object: `core` (the URL of core's ts-loader and cli/plugins modules,
+ * without extension), `ext` (`.js` or `.ts`), `names`, and `taggable` (the
+ * URL of the aws lexicon's taggable module).
+ */
+const COUNT = `
+import { registerHooks } from "node:module";
+const seen = { tsx: 0, typeScript: [] };
+registerHooks({
+  load(url, context, next) {
+    const path = url.replace(/[?#].*$/, "");
+    if (path.includes("/node_modules/tsx/")) seen.tsx++;
+    else if (/\\.[cm]?tsx?$/.test(path)) seen.typeScript.push(path);
+    return next(url, context);
+  },
+});
+const args = JSON.parse(process.argv[2]);
+const { installCompiledCli } = await import(args.core + "/ts-loader" + args.ext);
+installCompiledCli();
+const { loadPlugin } = await import(args.core + "/cli/plugins" + args.ext);
+const plugins = {};
+for (const name of args.names) {
+  const plugin = await loadPlugin(name);
+  const catalogs = {};
+  for (const resource of plugin.mcpResources?.() ?? []) {
+    if (!resource.uri.endsWith(":resource-catalog")) continue;
+    try { catalogs[resource.uri] = JSON.parse(await resource.handler()).length ?? 0; } catch (err) { catalogs[resource.uri] = String(err); }
+  }
+  plugins[name] = {
+    catalogs,
+    lintRules: (plugin.lintRules?.() ?? []).map((r) => r.id).sort(),
+    postSynthChecks: (plugin.postSynthChecks?.() ?? []).map((c) => c.id).sort(),
+    skills: (plugin.skills?.() ?? []).filter((s) => s.content.length > 0).map((s) => s.name).sort(),
+  };
+}
+const { loadTaggableResources } = await import(args.taggable);
+const compiled = globalThis[Symbol.for("chant.compiledCli")];
+process.stdout.write(JSON.stringify({
+  plugins,
+  taggable: loadTaggableResources().size,
+  tsxRegistered: compiled ? compiled.tsx : null,
+  seen,
+}));
+`;
+
+interface Counted {
+  plugins: Record<string, { catalogs: Record<string, number | string>; lintRules: string[]; postSynthChecks: string[]; skills: string[] }>;
+  taggable: number;
+  tsxRegistered: boolean | null;
+  seen: { tsx: number; typeScript: string[] };
+}
+
+function tsc(project: string, outDir: string): void {
+  execFileSync(join(repo, "scripts", "tsc7.sh"), ["-p", project, "--outDir", outDir, "--sourceMap", "false", "--declaration", "false", "--declarationMap", "false"], {
+    cwd: repo,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  execFileSync(process.execPath, [join(repoModules, "tsc-alias", "dist", "bin", "index.js"), "-p", project, "--outDir", outDir], {
+    cwd: repo,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+}
+
+function count(script: string, args: object, nodeArgs: string[] = []): Counted {
+  const r = spawnSync(process.execPath, [...nodeArgs, script, JSON.stringify(args)], { cwd: scratch, encoding: "utf-8", maxBuffer: 16 * 1024 * 1024 });
+  if (r.status !== 0) throw new Error(`count script failed (${r.status}):\n${r.stderr}`);
+  return JSON.parse(r.stdout) as Counted;
+}
+
+beforeAll(() => {
+  scratch = mkdtempSync(join(tmpdir(), "chant-lexicon-dist-"));
+  modules = join(scratch, "node_modules");
+  mkdirSync(join(modules, "@intentius"), { recursive: true });
+  for (const name of readdirSync(repoModules)) {
+    if (name === "@intentius" || name === ".bin") continue;
+    symlinkSync(join(repoModules, name), join(modules, name));
+  }
+
+  // Core as an install has it: its source (the package exports name it, and
+  // the compiled CLI redirects each import of it to dist), and dist.
+  const core = join(modules, "@intentius", "chant");
+  mkdirSync(core);
+  cpSync(join(coreRoot, "package.json"), join(core, "package.json"));
+  cpSync(join(coreRoot, "src"), join(core, "src"), { recursive: true, filter: (p) => !/\.test\.ts$/.test(p) });
+  coreDist = join(core, "dist");
+  tsc(join(coreRoot, "tsconfig.build.json"), coreDist);
+  mkdirSync(join(core, "scripts"));
+  cpSync(join(coreRoot, "scripts", "copy-assets.mjs"), join(core, "scripts", "copy-assets.mjs"));
+  execFileSync(process.execPath, [join(core, "scripts", "copy-assets.mjs")], { stdio: "ignore" });
+
+  for (const name of LEXICONS) {
+    const root = join(repo, "lexicons", name);
+    const pkg = join(modules, "@intentius", `chant-lexicon-${name}`);
+    mkdirSync(pkg);
+    cpSync(join(root, "package.json"), join(pkg, "package.json"));
+    // src/ is published beside dist/, and holds what a module reads beside itself.
+    symlinkSync(join(root, "src"), join(pkg, "src"));
+    if (existsSync(join(root, "node_modules"))) symlinkSync(join(root, "node_modules"), join(pkg, "node_modules"));
+    // The bundle's dist/ (meta.json, manifest.json), then the compiled modules.
+    if (existsSync(join(root, "dist"))) cpSync(join(root, "dist"), join(pkg, "dist"), { recursive: true });
+    tsc(join(root, "tsconfig.build.json"), join(pkg, "dist"));
+  }
+
+  writeFileSync(join(scratch, "count.mjs"), COUNT);
+
+  project = join(scratch, "project");
+  mkdirSync(join(project, "src"), { recursive: true });
+  writeFileSync(join(project, "package.json"), JSON.stringify({ name: "lexicon-dist-e2e", private: true, type: "module" }));
+  writeFileSync(join(project, "chant.config.ts"), `export default { lexicons: ["aws"] };\n`);
+  writeFileSync(
+    join(project, "src", "infra.ts"),
+    `import { Queue } from "@intentius/chant-lexicon-aws";\n` +
+      `export const taskQueue = new Queue({ QueueName: "lexicon-dist-e2e", Tags: [{ Key: "suite", Value: "lexicon-dist" }], SqsManagedSseEnabled: true });\n`,
+  );
+}, 600_000);
+
+afterAll(() => {
+  if (scratch) rmSync(scratch, { recursive: true, force: true });
+});
+
+describe("lexicons loaded from compiled JS (#3981)", () => {
+  let fromSource: Counted;
+  let fromDist: Counted;
+
+  beforeAll(() => {
+    const tsxLoader = pathToFileURL(join(repoModules, "tsx", "dist", "loader.mjs")).href;
+    fromSource = count(
+      join(scratch, "count.mjs"),
+      {
+        core: pathToFileURL(join(coreRoot, "src")).href,
+        ext: ".ts",
+        names: LEXICONS,
+        taggable: pathToFileURL(join(repo, "lexicons", "aws", "src", "taggable.ts")).href,
+      },
+      // The repository's lexicons through their `development` export, src/*.ts, as bin/chant runs from source.
+      ["--conditions=development", "--import", tsxLoader],
+    );
+    fromDist = count(join(scratch, "count.mjs"), {
+      core: pathToFileURL(coreDist).href,
+      ext: ".js",
+      names: LEXICONS,
+      taggable: "@intentius/chant-lexicon-aws/taggable",
+    });
+  }, 300_000);
+
+  test("plain node loads every plugin with no tsx and no TypeScript module", () => {
+    expect(fromDist.tsxRegistered).toBe(false);
+    expect(fromDist.seen.tsx).toBe(0);
+    expect(fromDist.seen.typeScript).toEqual([]);
+    // The comparison run really loads the lexicons' source.
+    expect(fromSource.seen.typeScript.some((path) => path.includes("/lexicons/aws/src/"))).toBe(true);
+  });
+
+  test("the compiled plugins find the same lint rules as the source", () => {
+    for (const name of LEXICONS) {
+      expect(fromDist.plugins[name]!.lintRules, name).toEqual(fromSource.plugins[name]!.lintRules);
+    }
+    // The two that scan a directory for their rules found some.
+    expect(fromDist.plugins.aws!.lintRules.length).toBeGreaterThan(0);
+    expect(fromDist.plugins.helm!.lintRules.length).toBeGreaterThan(0);
+  });
+
+  test("the compiled plugins find the same post-synth checks as the source", () => {
+    for (const name of LEXICONS) {
+      expect(fromDist.plugins[name]!.postSynthChecks, name).toEqual(fromSource.plugins[name]!.postSynthChecks);
+    }
+    expect(fromDist.plugins.aws!.postSynthChecks.length).toBeGreaterThan(0);
+  });
+
+  test("the compiled plugins read their skills from src/", () => {
+    for (const name of LEXICONS) {
+      expect(fromDist.plugins[name]!.skills, name).toEqual(fromSource.plugins[name]!.skills);
+    }
+    expect(fromDist.plugins.aws!.skills.length).toBeGreaterThan(0);
+  });
+
+  test("a compiled module reads the generated JSON under src/", () => {
+    expect(fromSource.taggable).toBeGreaterThan(0);
+    expect(fromDist.taggable).toBe(fromSource.taggable);
+    for (const name of LEXICONS) {
+      expect(fromDist.plugins[name]!.catalogs, name).toEqual(fromSource.plugins[name]!.catalogs);
+      for (const size of Object.values(fromDist.plugins[name]!.catalogs)) expect(typeof size, `${name}: ${size}`).toBe("number");
+    }
+    expect(fromDist.plugins.aws!.catalogs["aws:resource-catalog"]).toBeGreaterThan(0);
+  });
+
+  test("build and lint run against the compiled aws lexicon and load none of its TypeScript", () => {
+    const tracer = join(scratch, "trace.mjs");
+    writeFileSync(
+      tracer,
+      `import { registerHooks } from "node:module";\nimport { appendFileSync } from "node:fs";\n` +
+        `const seen = [];\n` +
+        `registerHooks({ load(url, context, next) { if (/\\/(lexicons|chant-lexicon-[a-z0-9]+)\\/src\\/.*\\.ts$/.test(url)) seen.push(url); return next(url, context); } });\n` +
+        `process.on("exit", () => appendFileSync(process.env.TRACE_OUT, JSON.stringify(seen) + "\\n"));\n`,
+    );
+    const main = join(coreDist, "cli", "main.js");
+    const run = (args: string[]) => {
+      const out = join(scratch, `trace-${args[0]}.jsonl`);
+      const env: NodeJS.ProcessEnv = { ...process.env, TRACE_OUT: out };
+      delete env.CHANT_ENV;
+      const r = spawnSync(process.execPath, ["--import", pathToFileURL(tracer).href, main, ...args], { cwd: project, encoding: "utf-8", env });
+      return { ...r, lexiconTypeScript: JSON.parse(readFileSync(out, "utf-8").trim().split("\n")[0]!) as string[] };
+    };
+
+    const built = run(["build", "src", "-o", "out/template.json"]);
+    expect(built.status, built.stderr).toBe(0);
+    const template = JSON.parse(readFileSync(join(project, "out", "template.json"), "utf-8")) as {
+      Resources: Record<string, { Type: string; Properties: { QueueName?: string } }>;
+    };
+    expect(Object.values(template.Resources).map((r) => [r.Type, r.Properties.QueueName])).toEqual([["AWS::SQS::Queue", "lexicon-dist-e2e"]]);
+    expect(built.lexiconTypeScript).toEqual([]);
+
+    const linted = run(["lint", "src"]);
+    expect(linted.status, linted.stdout + linted.stderr).toBe(0);
+    expect(linted.lexiconTypeScript).toEqual([]);
+  });
+});

package/src/lexicon-module.test.ts

@@ -201,3 +201,50 @@ describe("lexicons declared by module path (#2520)", () => {
     expect(typeof evaluator.evaluateGatePolicy).toBe("function");
   });
 });
+
+describe("tsx only for a lexicon that resolves to TypeScript (#3981)", () => {
+  const STATE = Symbol.for("chant.compiledCli");
+  const global = globalThis as { [STATE]?: { tsx: boolean } };
+  let dir: string;
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), "chant-lexicon-js-"));
+    // Stand in for the compiled CLI before it has registered tsx.
+    global[STATE] = { tsx: false };
+  });
+
+  afterEach(async () => {
+    delete global[STATE];
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  async function jsPackage(root: string, name: string): Promise<void> {
+    const pkg = join(root, "node_modules", "@intentius", `chant-lexicon-${name}`);
+    await mkdir(join(pkg, "dist"), { recursive: true });
+    await writeFile(join(pkg, "package.json"), JSON.stringify({ name: `@intentius/chant-lexicon-${name}`, type: "module", exports: { ".": "./dist/index.js" } }));
+    await writeFile(join(pkg, "dist", "index.js"), `export const marker = ${JSON.stringify(name)};\n`);
+  }
+
+  test("a compiled package the project installs imports with plain node", async () => {
+    await jsPackage(dir, "jsonly");
+    const { importLexiconPackage } = await import("./lexicon-module");
+    const mod = await importLexiconPackage("@intentius/chant-lexicon-jsonly", dir);
+    expect(mod.marker).toBe("jsonly");
+    expect(global[STATE]).toEqual({ tsx: false });
+  });
+
+  test("a compiled module named by absolute path imports with plain node", async () => {
+    const path = join(dir, "lexicon.mjs");
+    await writeFile(path, `export const marker = "by-path";\n`);
+    const { importLexiconPackage } = await import("./lexicon-module");
+    const mod = await importLexiconPackage(path, dir);
+    expect(mod.marker).toBe("by-path");
+    expect(global[STATE]).toEqual({ tsx: false });
+  });
+
+  test("a package missing from the project too rethrows the first error and registers nothing", async () => {
+    const { importLexiconPackage } = await import("./lexicon-module");
+    await expect(importLexiconPackage("@intentius/chant-lexicon-not-installed-3981", dir)).rejects.toThrow(/chant-lexicon-not-installed-3981/);
+    expect(global[STATE]).toEqual({ tsx: false });
+  });
+});

package/src/lexicon-module.ts

@@ -27,8 +27,9 @@
 import { createRequire } from "node:module";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { pathToFileURL } from "node:url";
-import { ensureTypeScriptLoader } from "./ts-loader";
+import { ensureTypeScriptLoader, ensureTypeScriptLoaderFor, typeScriptLoaderPending } from "./ts-loader";
 import { esModuleNamespace } from "./module-interop";
+import { isJavaScriptModule } from "./module-source";
 
 /**
  * One `lexicons` entry: a package-backed name, or a name plus the module that
@@ -180,6 +181,9 @@ export function resetLexiconModules(): void {
  * `typeScript: false` imports it with plain node, without registering tsx
  * (#3276): tsx's ESM hooks run on a thread of their own, which costs the
  * compiled CLI about 200 MB, so a caller whose module is JavaScript says so.
+ * Left out, the module's extension decides (#3981): a `.js` or `.mjs` module
+ * imports with plain node, and anything else (`.ts`, or no extension, which
+ * only tsx's resolver completes) registers tsx first.
  */
 export async function importLexiconModule(
   name: string,
@@ -188,7 +192,8 @@ export async function importLexiconModule(
   const path = modulePaths.get(name);
   if (path === undefined) return undefined;
   try {
-    if (options.typeScript !== false) ensureTypeScriptLoader();
+    const typeScript = options.typeScript ?? !isJavaScriptModule(path);
+    if (typeScript) ensureTypeScriptLoader();
     return esModuleNamespace((await import(path)) as Record<string, unknown>);
   } catch (err) {
     throw new Error(
@@ -258,6 +263,18 @@ export function resolveFromProject(spec: string, fromDir: string = process.cwd()
   }
 }
 
+/**
+ * #3981 — where `spec` resolves from this module, as `import(spec)` here
+ * would resolve it. Throws as the import would when it cannot be resolved.
+ * An absolute path is its own file URL.
+ */
+function resolveImport(spec: string): string {
+  if (isAbsolute(spec)) return pathToFileURL(spec).href;
+  const resolveMeta = (import.meta as { resolve?: (specifier: string) => string }).resolve;
+  if (typeof resolveMeta === "function") return resolveMeta(spec);
+  return pathToFileURL(createRequire(import.meta.url).resolve(spec)).href;
+}
+
 /**
  * chant#2845 — import a lexicon package, or one of its subpaths, by its bare
  * specifier. chant's own install is tried first, as a bare `import()` always
@@ -266,16 +283,41 @@ export function resolveFromProject(spec: string, fromDir: string = process.cwd()
  * that installs its lexicons in its own node_modules, it is resolved from
  * `fromDir` (the project) and imported from there. Any other failure, and a
  * package the project doesn't have either, rethrows the first error.
+ *
+ * #3981 — tsx is registered only when the module resolves to TypeScript. A
+ * lexicon that ships compiled JS imports with plain node. The module is
+ * resolved before it is imported, because a failed import is cached: one
+ * tried without tsx cannot be tried again with it. A resolution that fails
+ * for any reason but a missing package registers tsx, whose resolver may
+ * still complete it.
  */
 export async function importLexiconPackage(spec: string, fromDir: string = process.cwd()): Promise<Record<string, unknown>> {
+  const pkg = packageNameOf(spec);
+  if (typeScriptLoaderPending()) {
+    let resolved: string | undefined;
+    try {
+      resolved = resolveImport(spec);
+    } catch (err) {
+      if (pkg === undefined || !isPackageNotFound(err, pkg)) {
+        ensureTypeScriptLoader();
+      } else {
+        return importFromProject(spec, fromDir, err);
+      }
+    }
+    if (resolved !== undefined) ensureTypeScriptLoaderFor(resolved);
+  }
   try {
-    ensureTypeScriptLoader();
     return esModuleNamespace((await import(spec)) as Record<string, unknown>);
   } catch (err) {
-    const pkg = packageNameOf(spec);
     if (pkg === undefined || !isPackageNotFound(err, pkg)) throw err;
-    const resolved = resolveFromProject(spec, fromDir);
-    if (resolved === undefined) throw err;
-    return esModuleNamespace((await import(pathToFileURL(resolved).href)) as Record<string, unknown>);
+    return importFromProject(spec, fromDir, err);
   }
 }
+
+/** The project's copy of `spec`, for {@link importLexiconPackage}. Rethrows `err` when the project has none. */
+async function importFromProject(spec: string, fromDir: string, err: unknown): Promise<Record<string, unknown>> {
+  const resolved = resolveFromProject(spec, fromDir);
+  if (resolved === undefined) throw err;
+  ensureTypeScriptLoaderFor(resolved);
+  return esModuleNamespace((await import(pathToFileURL(resolved).href)) as Record<string, unknown>);
+}

package/src/lexicon-plugin-helpers.ts

@@ -7,8 +7,8 @@
  */
 
 import { readFileSync } from "fs";
-import { join, dirname } from "path";
-import { fileURLToPath } from "url";
+import { join } from "path";
+import { moduleSourceDir } from "./module-source";
 import type { SkillDefinition } from "./lexicon";
 import type { McpToolContribution, McpResourceContribution } from "./mcp/types";
 import type { Serializer } from "./serializer";
@@ -44,7 +44,8 @@ export function createSkillsLoader(
   specs: SkillFileSpec[],
 ): () => SkillDefinition[] {
   return () => {
-    const skillsDir = join(dirname(fileURLToPath(importMetaUrl)), "skills");
+    // Skills are markdown beside the source; a compiled plugin finds them under src/ (#3981).
+    const skillsDir = join(moduleSourceDir(importMetaUrl), "skills");
     return specs.map(({ file, ...meta }) => {
       try {
         const content = readFileSync(join(skillsDir, file), "utf-8");
@@ -123,7 +124,8 @@ export function createCatalogResource(
     description,
     mimeType: "application/json",
     async handler(): Promise<string> {
-      const dir = dirname(fileURLToPath(importMetaUrl));
+      // Generated JSON sits beside the source; a compiled plugin finds it under src/ (#3981).
+      const dir = moduleSourceDir(importMetaUrl);
       const lexicon = JSON.parse(
         readFileSync(join(dir, "generated", lexiconJsonFile), "utf-8"),
       ) as Record<string, { resourceType: string; kind: string }>;

package/src/lexicon.ts

@@ -78,6 +78,15 @@ export type {
   UnobservedReason,
 } from "./observation";
 
+// The runtime-health contract (#4177), re-exported so a lexicon's
+// `observeHealth` types itself from the same entry.
+export type {
+  HealthEntry,
+  HealthReadOptions,
+  HealthReadResult,
+  HealthState,
+} from "./health";
+
 // The identity contract (#1982), re-exported from the same entry so a
 // lexicon's `describeIdentity` types itself without a second import path.
 // Runtime helpers live in `@intentius/chant/identity`.
@@ -554,6 +563,8 @@ export interface ComponentPipelineOptions {
    * `wave-<k>` runs `chant components fan-out --wave-gate <gate> --wave <k>`
    * and hands the attempt record to the next job. See
    * `components/gated-wave-pipeline.ts`. Unset, the pipeline is unchanged.
+   * Beside `prLoop` (#4003) it gives the pull request's apply a gate per
+   * wave instead: one apply job per wave (`prLoopWithWaves`).
    */
   gatedWaves?: GatedWavePipelineOptions;
   /**
@@ -689,7 +700,19 @@ export type OpFindingMode = "report" | "issue" | "comment" | "pull-request" | "m
 export type OpTrigger =
   | { kind: "cron"; schedule: string }
   | { kind: "pull_request"; branches?: string[] }
-  | { kind: "push"; branches?: string[] };
+  | {
+      kind: "push";
+      branches?: string[];
+      /**
+       * Which pushes run the Op (#4169), for an Op a `ci.green` phase names
+       * with `build` and the tick reads from chant runs. `every`: each
+       * commit, in a run of its own that no later push cancels. `newest`:
+       * one run at a time, the newest push waiting and the ones between
+       * dropped, plus a run at each `ci/build/<sha>` tag the tick or `ci run
+       * --at` pushes. Absent: one run at a time per Op, as before.
+       */
+      build?: "every" | "newest";
+    };
 
 /**
  * One step a generated Op job runs between the checkout and the
@@ -1797,6 +1820,25 @@ export interface LexiconPlugin {
     owned?: boolean;
   }): Promise<DeepObservationResult>;
 
+  /**
+   * Entity types {@link observeHealth} reads (#4177). Data, not a method, so
+   * core picks the entities a health read applies to without calling it.
+   */
+  healthTypes?: readonly string[];
+
+  /**
+   * Whether each declared entity of a {@link healthTypes} type is up (#4177),
+   * read separately from drift: a service's running count, a health check's
+   * checkers, a revision's running state, a Ready condition.
+   *
+   * Every entity in `options.entities` lands in exactly one of `entities`,
+   * `unobserved` or `absent`. A read that failed is `unobserved` with a reason,
+   * never `unhealthy`: `unhealthy` is something the provider said. Throwing is
+   * the whole-lexicon failure, and core reports every entity `read-failed`.
+   * Endpoint overrides apply as on the other reads, so an emulator answers.
+   */
+  observeHealth?(options: import("./health").HealthReadOptions): Promise<import("./health").HealthReadResult>;
+
   /**
    * This lexicon's noise rules for deep observation (#1014): which fields are
    * read-only / server-populated / controller-managed / provider-defaulted, and

package/src/lifecycle/affected.test.ts

@@ -14,6 +14,7 @@ import {
 import type { StackGraph } from "../build";
 import type { Serializer } from "../serializer";
 import type { Declarable } from "../declarable";
+import { EMPTY_TREE_SHA } from "../components/changed-files";
 
 const execFileAsync = promisify(execFile);
 
@@ -136,6 +137,12 @@ describe("affectedStacks — baseDir (caller-supplied)", () => {
     const r = await affectedStacks({ projectPath: head, baseDir: base, serializers: [fakeSerializer] });
     expect(r.changed).toEqual([]);
   });
+
+  test("the empty tree as the base (a root commit, #4004) builds nothing: every head stack is changed", async () => {
+    const head = srcDir("head", widget("Widget"));
+    const r = await affectedStacks({ projectPath: head, baseRef: EMPTY_TREE_SHA, serializers: [fakeSerializer] });
+    expect(r.changed).toEqual(["fake"]);
+  });
 });
 
 // A second lexicon, so a stack that serializes through two of them can be shown

package/src/lifecycle/affected.ts

@@ -37,6 +37,7 @@ import { tmpdir } from "node:os";
 import { build, type StackGraph } from "../build";
 import { getPrimaryOutput } from "../lint/post-synth";
 import type { Serializer } from "../serializer";
+import { EMPTY_TREE_SHA } from "../components/changed-files";
 import type { Declarable } from "../declarable";
 
 const execFileAsync = promisify(execFile);
@@ -258,7 +259,9 @@ export interface AffectedStacksOptions {
  */
 export async function affectedStacks(opts: AffectedStacksOptions): Promise<AffectedResult> {
   const projectPath = resolve(opts.projectPath);
-  const needsWorktree = Boolean(opts.headRef) || Boolean(opts.baseRef && !opts.baseDir);
+  // The empty tree (#4004) builds nothing, so it needs no worktree.
+  const emptyBase = !opts.baseDir && opts.baseRef === EMPTY_TREE_SHA;
+  const needsWorktree = Boolean(opts.headRef) || Boolean(opts.baseRef && !opts.baseDir && !emptyBase);
   const repoRoot = needsWorktree ? await gitTopLevel(projectPath) : projectPath;
   // Canonicalize via realpath so the worktree-relative path is correct even when
   // the temp dir is a symlink (macOS /var → /private/var) and `git
@@ -293,6 +296,8 @@ export async function affectedStacks(opts: AffectedStacksOptions): Promise<Affec
   let baseMap: Map<string, string>;
   if (opts.baseDir) {
     baseMap = (await readArtifacts(resolve(opts.baseDir), false)).artifacts;
+  } else if (emptyBase) {
+    baseMap = new Map();
   } else if (opts.baseRef) {
     baseMap = await withWorktree(repoRoot, opts.baseRef, async (dir) => (await readArtifacts(join(dir, relProject), false)).artifacts);
   } else {

package/src/lifecycle/merge-record.test.ts

@@ -0,0 +1,111 @@
+/**
+ * Merge records (#4168 step 1) against temp git repos: written under the
+ * commit on chant/lifecycle, rewritten only when the record changed, read
+ * back, and validated against the schema; and where the change came from.
+ */
+
+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 { MERGE_RECORD_CONTRACT, MERGE_RECORD_SCHEMA_ID, MERGES_DIR, mergeRecordFile, mergeSourceOf, readMergeRecord, writeMergeRecord, type MergeRecord } from "./merge-record";
+import { contract, validSchema } from "../workspace/__fixtures__/contract-repo";
+import schema from "../workspace/merge-record.schema.json";
+
+const { expectValid } = contract(schema);
+
+function git(dir: string, ...args: string[]): string {
+  const r = spawnSync("git", args, { cwd: dir, encoding: "utf-8" });
+  if (r.status !== 0) throw new Error(`git ${args.join(" ")}: ${r.stderr}`);
+  return r.stdout.trim();
+}
+
+function initRepo(dir: string): string {
+  git(dir, "init", "-q", "-b", "main");
+  git(dir, "config", "user.email", "test@chant.dev");
+  git(dir, "config", "user.name", "Test");
+  writeFileSync(join(dir, "README.md"), "fixture\n");
+  git(dir, "add", ".");
+  git(dir, "commit", "-q", "-m", "init");
+  return git(dir, "rev-parse", "HEAD");
+}
+
+const record = (commit: string, over: Partial<MergeRecord> = {}): MergeRecord => ({
+  $schema: MERGE_RECORD_SCHEMA_ID,
+  contract: MERGE_RECORD_CONTRACT,
+  commit,
+  base: "b".repeat(40),
+  env: "prod",
+  source: { kind: "pull-request", pr: 12 },
+  op: "pr-12",
+  gate: "pr-apply",
+  digest: `jcs1-sha256:${"1".repeat(64)}`,
+  plan: "approved",
+  approvedBy: ["github:rev"],
+  components: ["net", "app"],
+  recordedAt: "2026-10-20T00:00:00.000Z",
+  ...over,
+});
+
+describe("the merge record schema", () => {
+  test("is a valid schema and names this module's id", () => {
+    expect(validSchema(schema)).toBe(true);
+    expect(schema.$id).toBe(MERGE_RECORD_SCHEMA_ID);
+  });
+
+  test("each source and plan status validates", () => {
+    const sha = "a".repeat(40);
+    expectValid(record(sha));
+    expectValid(record(sha, { source: { kind: "work-item", records: [{ kind: "work", id: "w-7" }] }, op: null, plan: "unapproved", approvedBy: [] }));
+    expectValid(record(sha, { source: { kind: "direct-push" }, op: null, digest: null, plan: "nothing", approvedBy: [], components: [] }));
+    expectValid(record(sha, { plan: "changed", approvedDigest: `jcs1-sha256:${"9".repeat(64)}`, approvedBy: [], authorApproved: ["github:carol"], member: "net" }));
+  });
+});
+
+describe("writeMergeRecord and readMergeRecord", () => {
+  test("writes the record under its commit, leaves the same record alone, and replaces a changed one", async () => {
+    await withTestDir(async (dir) => {
+      const sha = initRepo(dir);
+      expect(await readMergeRecord(sha, { cwd: dir })).toBeNull();
+      expect((await writeMergeRecord(record(sha), { cwd: dir })).written).toBe(true);
+      expect(git(dir, "ls-tree", "--name-only", `chant/lifecycle:${MERGES_DIR}`)).toBe(mergeRecordFile(sha));
+      expect(await readMergeRecord(sha, { cwd: dir })).toEqual(record(sha));
+
+      // The record job ran again: only the time differs, so nothing is written.
+      const tip = git(dir, "rev-parse", "chant/lifecycle");
+      expect((await writeMergeRecord(record(sha, { recordedAt: "2026-10-21T00:00:00.000Z" }), { cwd: dir })).written).toBe(false);
+      expect(git(dir, "rev-parse", "chant/lifecycle")).toBe(tip);
+
+      // A plan that moved since is a new record for the same commit.
+      const moved = record(sha, { plan: "changed", approvedDigest: `jcs1-sha256:${"9".repeat(64)}`, approvedBy: [] });
+      expect((await writeMergeRecord(moved, { cwd: dir })).written).toBe(true);
+      expect(await readMergeRecord(sha, { cwd: dir })).toEqual(moved);
+    });
+  });
+
+  test("a member's record sits under its own prefix", async () => {
+    await withTestDir(async (dir) => {
+      const sha = initRepo(dir);
+      await writeMergeRecord(record(sha, { member: "net" }), { cwd: dir, member: "net" });
+      expect(git(dir, "ls-tree", "-r", "--name-only", "chant/lifecycle")).toBe(`_members/net/${MERGES_DIR}/${mergeRecordFile(sha)}`);
+      expect(await readMergeRecord(sha, { cwd: dir, member: "net" })).toMatchObject({ member: "net" });
+      expect(await readMergeRecord(sha, { cwd: dir })).toBeNull();
+    });
+  });
+});
+
+describe("mergeSourceOf", () => {
+  test("a pull request first, then the work items a commit's trailers name, then a direct push", async () => {
+    await withTestDir(async (dir) => {
+      const plain = initRepo(dir);
+      expect(mergeSourceOf(dir, plain, 12)).toEqual({ kind: "pull-request", pr: 12 });
+      expect(mergeSourceOf(dir, plain, null)).toEqual({ kind: "direct-push" });
+      writeFileSync(join(dir, "a.txt"), "a\n");
+      git(dir, "add", ".");
+      git(dir, "commit", "-q", "-m", "carry out w-7\n\nChant-Record: work:w-7\nChant-Record: decision:d-1\nChant-Record: work:w-8\nChant-Record: work:w-7");
+      expect(mergeSourceOf(dir, git(dir, "rev-parse", "HEAD"), null)).toEqual({ kind: "work-item", records: [{ kind: "work", id: "w-7" }, { kind: "work", id: "w-8" }] });
+      expect(mergeSourceOf(dir, "f".repeat(40), null)).toEqual({ kind: "direct-push" });
+    });
+  });
+});