@intentius/chant 0.44.13 → 0.45.0

package/src/cli/commands/onboard.ts

@@ -6,6 +6,8 @@ import { formatSuccess, formatError, formatWarning } from "../format";
 export interface OnboardOptions {
   name: string;
   verbose?: boolean;
+  /** Monorepo root to patch. Defaults to the root this module lives in. */
+  root?: string;
 }
 
 export interface OnboardResult {
@@ -15,16 +17,66 @@ export interface OnboardResult {
   error?: string;
 }
 
+export interface PatchResult {
+  patched: boolean;
+  reason?: string;
+}
+
 /** Resolve the monorepo root (5 dirs up from packages/core/src/cli/commands/). */
 function findRepoRoot(): string {
   const here = dirname(fileURLToPath(import.meta.url)); // commands/
   return dirname(dirname(dirname(dirname(dirname(here))))); // -> root
 }
 
+/**
+ * A real prepack invocation line: a Dockerfile `RUN`, a workflow `- run:`,
+ * or a bare line inside a `run: |` block. Comments, `echo` messages and
+ * `$lex` / `<lex>` placeholders do not match. Matching those placeholder
+ * substrings was how onboard appended duplicates to Dockerfile.smoke on
+ * every run (#1678).
+ */
+const PREPACK_LINE = /^\s*(?:RUN\s+|-\s*run:\s*)?npm run --prefix lexicons\/[a-z0-9-]+ prepack\s*$/i;
+
+function isPrepackLine(line: string): boolean {
+  return PREPACK_LINE.test(line);
+}
+
+function hasPrepackLine(lines: string[], name: string): boolean {
+  return lines.some((l) => isPrepackLine(l) && l.includes(`lexicons/${name} prepack`));
+}
+
+/** Shell loop header over lexicon names: `for lex in aws gcp k8s; do \`. */
+const LEX_LOOP = /^(\s*(?:RUN\s+)?for lex in )([a-z0-9][a-z0-9 -]*?)(\s*;\s*do\b.*)$/i;
+
+function loopCoversLexicon(lines: string[], name: string): boolean {
+  return lines.some((l) => {
+    const m = l.match(LEX_LOOP);
+    return m !== null && m[2].split(/\s+/).includes(name);
+  });
+}
+
+/**
+ * Append the lexicon to every `for lex in ...` loop list that does not
+ * already contain it. Returns true when at least one list changed.
+ */
+function addToLexiconLoops(lines: string[], name: string): boolean {
+  let changed = false;
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(LEX_LOOP);
+    if (!m) continue;
+    const names = m[2].split(/\s+/).filter(Boolean);
+    if (names.includes(name)) continue;
+    names.push(name);
+    lines[i] = `${m[1]}${names.join(" ")}${m[3]}`;
+    changed = true;
+  }
+  return changed;
+}
+
 /**
  * Patch root package.json to add a workspace dependency for the lexicon.
  */
-function patchRootPackageJson(root: string, name: string): { patched: boolean; reason?: string } {
+function patchRootPackageJson(root: string, name: string): PatchResult {
   const pkgPath = join(root, "package.json");
   if (!existsSync(pkgPath)) return { patched: false, reason: "root package.json not found" };
 
@@ -49,23 +101,53 @@ function patchRootPackageJson(root: string, name: string): { patched: boolean; r
   return { patched: true };
 }
 
+/**
+ * Patch the root tsconfig.json `paths` map (#1614).
+ *
+ * The whole-repo typecheck runs with `moduleResolution: node`, which never
+ * reads package exports maps, so every lexicon needs a bare + subpath
+ * mapping here or an example importing the package fails to resolve.
+ */
+export function patchRootTsconfigPaths(root: string, name: string): PatchResult {
+  const tsconfigPath = join(root, "tsconfig.json");
+  if (!existsSync(tsconfigPath)) return { patched: false, reason: "root tsconfig.json not found" };
+
+  const cfg = JSON.parse(readFileSync(tsconfigPath, "utf-8"));
+  cfg.compilerOptions = cfg.compilerOptions ?? {};
+  const paths: Record<string, string[]> = (cfg.compilerOptions.paths = cfg.compilerOptions.paths ?? {});
+
+  const bare = `@intentius/chant-lexicon-${name}`;
+  const wanted: Record<string, string[]> = {
+    [bare]: [`lexicons/${name}/src/index.ts`],
+    [`${bare}/*`]: [`lexicons/${name}/src/*`],
+  };
+
+  let changed = false;
+  for (const [key, value] of Object.entries(wanted)) {
+    if (Array.isArray(paths[key]) && paths[key].length > 0) continue;
+    paths[key] = value;
+    changed = true;
+  }
+
+  if (!changed) return { patched: false, reason: `${bare} already in paths` };
+
+  writeFileSync(tsconfigPath, JSON.stringify(cfg, null, 2) + "\n");
+  return { patched: true };
+}
+
 /**
  * Insert a new prepack line after the last prepack line in each contiguous group
  * of 2+ lines. Single standalone lines (like YAML `run:` values) are ignored.
- * Used for multi-line `run: |` blocks in workflows and Dockerfile RUN sequences.
+ * Used for multi-line `run: |` blocks in workflows.
  */
 function insertPrepackInContiguousGroups(lines: string[], name: string): boolean {
-  const newFragment = `lexicons/${name} prepack`;
-  if (lines.some((l) => l.includes(newFragment))) return false;
+  if (hasPrepackLine(lines, name)) return false;
 
   // Identify contiguous groups of prepack lines
   const groups: { start: number; end: number }[] = [];
   let groupStart = -1;
   for (let i = 0; i <= lines.length; i++) {
-    const isPrepack =
-      i < lines.length &&
-      lines[i].includes("npm run --prefix lexicons/") &&
-      lines[i].includes("prepack");
+    const isPrepack = i < lines.length && isPrepackLine(lines[i]);
     if (isPrepack && groupStart === -1) {
       groupStart = i;
     } else if (!isPrepack && groupStart !== -1) {
@@ -89,19 +171,15 @@ function insertPrepackInContiguousGroups(lines: string[], name: string): boolean
 
 /**
  * Insert a new prepack line after every last-in-group prepack line (groups of 1+).
- * Used for Dockerfiles and publish.yml where all occurrences should get a new line.
+ * Used for publish.yml and Dockerfiles that list one RUN per lexicon.
  */
-function insertPrepackAfterEach(lines: string[], name: string): boolean {
-  const newFragment = `lexicons/${name} prepack`;
-  if (lines.some((l) => l.includes(newFragment))) return false;
+export function insertPrepackAfterEach(lines: string[], name: string): boolean {
+  if (hasPrepackLine(lines, name)) return false;
 
   const insertAfter: number[] = [];
   for (let i = 0; i < lines.length; i++) {
-    if (!lines[i].includes("npm run --prefix lexicons/") || !lines[i].includes("prepack")) continue;
-    const nextIsAlsoPrepack =
-      i + 1 < lines.length &&
-      lines[i + 1].includes("npm run --prefix lexicons/") &&
-      lines[i + 1].includes("prepack");
+    if (!isPrepackLine(lines[i])) continue;
+    const nextIsAlsoPrepack = i + 1 < lines.length && isPrepackLine(lines[i + 1]);
     if (!nextIsAlsoPrepack) {
       insertAfter.push(i);
     }
@@ -127,20 +205,19 @@ function insertPrepackAfterEach(lines: string[], name: string): boolean {
  *
  * We only insert into pattern 1 (contiguous groups) and separately add a new pattern 2 step.
  */
-function patchCiWorkflow(root: string, name: string): { patched: boolean; reason?: string } {
+function patchCiWorkflow(root: string, name: string): PatchResult {
   const filePath = join(root, ".github/workflows/chant.yml");
   if (!existsSync(filePath)) return { patched: false, reason: "chant.yml not found" };
 
   const content = readFileSync(filePath, "utf-8");
-  if (content.includes(`lexicons/${name} prepack`)) {
+  const lines = content.split("\n");
+  if (hasPrepackLine(lines, name)) {
     return { patched: false, reason: `${name} already in chant.yml` };
   }
 
-  const lines = content.split("\n");
-
-  // 1. Insert into multi-line `run: |` blocks only (contiguous prepack groups of 3+).
+  // 1. Insert into multi-line `run: |` blocks only (contiguous prepack groups of 2+).
   //    The validate job has standalone steps that are NOT contiguous, so they won't match.
-  insertPrepackInContiguousGroups(lines, name);
+  let changed = insertPrepackInContiguousGroups(lines, name);
 
   // 2. Add a named validate step after the last "Generate and validate" step
   const displayName = name.charAt(0).toUpperCase() + name.slice(1);
@@ -163,9 +240,11 @@ function patchCiWorkflow(root: string, name: string): { patched: boolean; reason
         `        run: npm run --prefix lexicons/${name} prepack`,
       ];
       lines.splice(lastValidateRunIdx + 1, 0, ...block);
+      changed = true;
     }
   }
 
+  if (!changed) return { patched: false, reason: "no prepack block found to anchor on" };
   writeFileSync(filePath, lines.join("\n"));
   return { patched: true };
 }
@@ -179,34 +258,43 @@ function patchCiWorkflow(root: string, name: string): { patched: boolean; reason
  * were how k8s-client (#1177) and fountain (#1253) each shipped a package
  * the release pipeline could not publish.
  */
-function patchPublishWorkflow(root: string, name: string): { patched: boolean; reason?: string } {
+function patchPublishWorkflow(root: string, name: string): PatchResult {
   const filePath = join(root, ".github/workflows/publish.yml");
   if (!existsSync(filePath)) return { patched: false, reason: "publish.yml not found" };
 
-  const content = readFileSync(filePath, "utf-8");
-  if (content.includes(`lexicons/${name} prepack`)) {
+  const lines = readFileSync(filePath, "utf-8").split("\n");
+  if (hasPrepackLine(lines, name)) {
     return { patched: false, reason: `prepack for ${name} already present` };
   }
 
-  const lines = content.split("\n");
-  insertPrepackAfterEach(lines, name);
+  if (!insertPrepackAfterEach(lines, name)) {
+    return { patched: false, reason: "no prepack line found to anchor on" };
+  }
   writeFileSync(filePath, lines.join("\n"));
   return { patched: true };
 }
 
 /**
- * Patch a Dockerfile to add a prepack RUN line.
+ * Patch a smoke Dockerfile so it covers the lexicon.
+ *
+ * Two layouts exist. Loop-based files (`for lex in aws gcp ...; do`) get the
+ * name appended to every loop list. Per-lexicon files (`RUN npm run --prefix
+ * lexicons/<x> prepack` lines) get one more RUN line. A file that already
+ * covers the lexicon either way is reported as such and left untouched.
  */
-function patchDockerfile(filePath: string, name: string): { patched: boolean; reason?: string } {
+export function patchDockerfile(filePath: string, name: string): PatchResult {
   if (!existsSync(filePath)) return { patched: false, reason: `${filePath} not found` };
 
-  const content = readFileSync(filePath, "utf-8");
-  if (content.includes(`lexicons/${name} prepack`)) {
-    return { patched: false, reason: `prepack for ${name} already in Dockerfile` };
+  const lines = readFileSync(filePath, "utf-8").split("\n");
+  if (loopCoversLexicon(lines, name) || hasPrepackLine(lines, name)) {
+    return { patched: false, reason: `already covers ${name}` };
+  }
+
+  const changed = addToLexiconLoops(lines, name) || insertPrepackAfterEach(lines, name);
+  if (!changed) {
+    return { patched: false, reason: "no lexicon loop or prepack line found to anchor on" };
   }
 
-  const lines = content.split("\n");
-  insertPrepackAfterEach(lines, name);
   writeFileSync(filePath, lines.join("\n"));
   return { patched: true };
 }
@@ -215,36 +303,34 @@ function patchDockerfile(filePath: string, name: string): { patched: boolean; re
  * Execute the onboard command — patches monorepo infrastructure for a new lexicon.
  */
 export function onboardCommand(options: OnboardOptions): OnboardResult {
-  const root = findRepoRoot();
+  const root = options.root ?? findRepoRoot();
   const patched: string[] = [];
   const skipped: string[] = [];
 
-  // 1. Root package.json
-  const pkgResult = patchRootPackageJson(root, options.name);
-  if (pkgResult.patched) patched.push("package.json (root dependency)");
-  else skipped.push(`package.json: ${pkgResult.reason}`);
+  const record = (label: string, summary: string, result: PatchResult) => {
+    if (result.patched) patched.push(`${label} (${summary})`);
+    else skipped.push(`${label}: ${result.reason}`);
+  };
 
-  // 2. CI workflow
-  const ciResult = patchCiWorkflow(root, options.name);
-  if (ciResult.patched) patched.push("chant.yml (prepack + validate)");
-  else skipped.push(`chant.yml: ${ciResult.reason}`);
+  // 1. Root package.json
+  record("package.json", "root dependency", patchRootPackageJson(root, options.name));
 
-  // 3. Publish workflow
-  const pubResult = patchPublishWorkflow(root, options.name);
-  if (pubResult.patched) patched.push("publish.yml (prepack)");
-  else skipped.push(`publish.yml: ${pubResult.reason}`);
+  // 2. Root tsconfig.json paths (#1614)
+  record("tsconfig.json", "paths mapping", patchRootTsconfigPaths(root, options.name));
 
-  // 4. Dockerfiles
-  const dockerBun = join(root, "test/Dockerfile.smoke");
-  const dockerNpm = join(root, "test/Dockerfile.smoke-npm");
+  // 3. CI workflow
+  record("chant.yml", "prepack + validate", patchCiWorkflow(root, options.name));
 
-  const db = patchDockerfile(dockerBun, options.name);
-  if (db.patched) patched.push("Dockerfile.smoke (prepack)");
-  else skipped.push(`Dockerfile.smoke: ${db.reason}`);
+  // 4. Publish workflow
+  record("publish.yml", "prepack", patchPublishWorkflow(root, options.name));
 
-  const dn = patchDockerfile(dockerNpm, options.name);
-  if (dn.patched) patched.push("Dockerfile.smoke-npm (prepack)");
-  else skipped.push(`Dockerfile.smoke-npm: ${dn.reason}`);
+  // 5. Dockerfiles
+  record("Dockerfile.smoke", "lexicon list", patchDockerfile(join(root, "test/Dockerfile.smoke"), options.name));
+  record(
+    "Dockerfile.smoke-npm",
+    "lexicon list",
+    patchDockerfile(join(root, "test/Dockerfile.smoke-npm"), options.name),
+  );
 
   return { success: true, patched, skipped };
 }
@@ -267,7 +353,7 @@ export async function printOnboardResult(result: OnboardResult, name: string): P
 
   if (result.skipped.length > 0) {
     console.log("");
-    console.log("Skipped (already configured):");
+    console.log("Skipped (already covered):");
     for (const s of result.skipped) {
       console.log(`  ${s}`);
     }

package/src/cli/handlers/build.test.ts

@@ -88,9 +88,9 @@ describe("runBuild --components --generate (chant #1108 build-time parameters)",
       undefined,
       [{ name: "tier", value: "light", source: "default" }],
     );
-    // A parameter at its default collapses into the count line now; the
-    // provenance forwarded above is where its value is asserted.
-    expect(stderr.join("\n")).toContain("at their defaults");
+    // The echo is a one-line count (#1424); the provenance forwarded above
+    // is where the value is asserted.
+    expect(stderr.join("\n")).toContain("1 build parameter resolved (1 default)");
     vi.restoreAllMocks();
   });
 

package/src/cli/handlers/build.ts

@@ -37,6 +37,7 @@ async function runGenerateComponents(ctx: CommandContext): Promise<number> {
   const paramsResolution = resolveCliBuildParams(config.buildParams, {
     cli: parseParamFlags(args.param),
     paramsFile: args.paramsFile,
+    verbose: args.verbose,
   });
   if (!paramsResolution.success) {
     for (const message of paramsResolution.errors) console.error(message);
@@ -125,6 +126,7 @@ export async function runBuild(ctx: CommandContext): Promise<number> {
       plugins,
       fold: args.fold,
       sandbox: args.sandbox,
+      verbose: args.verbose,
       params,
       paramsFile: args.paramsFile,
     });

package/src/cli/handlers/components.ts

@@ -430,14 +430,14 @@ export async function runComponentsStatus(ctx: CommandContext): Promise<number>
             // rather than "stale" (recorded, and nothing live).
             const message = err instanceof Error ? err.message : String(err);
             console.error(formatWarning({ message: `${plugin.name}: describeResources failed — ${message} (components in this lexicon report unknown, not stale)` }));
-            observed = { resources: {}, unobserved: unobservedAll(declared, "read-failed", message, entities), queried: {} };
+            observed = { resources: {}, unobserved: unobservedAll(declared, "read-failed", message, entities), queried: {}, notes: [] };
           }
           const cs = buildChangeSet(environment, {
             declared,
             observedNow: observed.resources,
             observedThen: undefined,
             unobserved: observed.unobserved,
-          });
+          }, { lexicon: plugin.name });
           merged.entries.push(...cs.entries);
         }
         liveEvidence = liveEvidenceFromChangeSet(merged, liveNameMapping);

package/src/cli/handlers/graph.test.ts

@@ -145,6 +145,8 @@ describe("runGraph", () => {
     vi.spyOn(console, "log").mockImplementation((s: string) => { stdoutBuf.push(s); });
     vi.spyOn(console, "error").mockImplementation((s: string) => { stderrBuf.push(s); });
     discoverOpsMock.mockReset();
+    // Default: no git-root ops — the IR views join these into the entity map (#1675).
+    discoverOpsMock.mockResolvedValue({ ops: new Map(), errors: [] });
     discoverMock.mockReset();
     lintMock.mockReset();
     layoutMock.mockReset();
@@ -223,6 +225,48 @@ describe("runGraph", () => {
       expect(ir.edges).toContainEqual({ from: "subnet", to: "vpc", kind: "ref", viaAttr: "network" });
     });
 
+    // #1675 — discovery scans sourceDir, but ops live beside it (project root,
+    // `ops/`) and are found by discoverOps from the git root. The IR joins them.
+    describe("ops outside sourceDir reach the IR (#1675)", () => {
+      const rootOp = (file: string) => ({
+        config: { name: "deploy", phases: [{ name: "Apply", steps: [{ kind: "activity", fn: "build" }] }], depends: ["infra"] },
+        filePath: file,
+      });
+
+      test("an op discoverOps finds at the project root becomes a Temporal::Op node", async () => {
+        lintClean(); discovered();
+        discoverOpsMock.mockResolvedValue({ ops: new Map([["deploy", rootOp("/proj/deploy.op.ts")]]), errors: [] });
+        const exit = await runGraph({ args: makeArgs({ format: "ir", path: "/proj", detail: 3 }), plugins: [], serializers: [] });
+        expect(exit).toBe(0);
+        const ir = JSON.parse(stdoutBuf.join("\n"));
+        const node = ir.nodes.find((n: { id: string }) => n.id === "deploy");
+        expect(node).toMatchObject({ kind: "Temporal::Op", lexicon: "temporal", sourceLoc: { file: "deploy.op.ts" } });
+        expect(node.attrs.phases[0].name).toBe("Apply");
+        expect(node.attrs.depends).toEqual(["infra"]);
+      });
+
+      test("an op discovery already loaded from sourceDir is not added twice", async () => {
+        lintClean();
+        const entities = sampleEntities();
+        entities.set("deploy", decl({ lexicon: "temporal", entityType: "Temporal::Op", props: { name: "deploy", phases: [] } }));
+        discoverMock.mockResolvedValue({ entities, errors: [], dependencies: new Map(), sourceFiles: ["/proj/src/deploy.op.ts"] });
+        discoverOpsMock.mockResolvedValue({ ops: new Map([["deploy", rootOp("/proj/src/deploy.op.ts")]]), errors: [] });
+        const exit = await runGraph({ args: makeArgs({ format: "ir", path: "/proj", detail: 3 }), plugins: [], serializers: [] });
+        expect(exit).toBe(0);
+        const ir = JSON.parse(stdoutBuf.join("\n"));
+        expect(ir.nodes.filter((n: { id: string }) => n.id === "deploy")).toHaveLength(1);
+        expect(ir.nodes.find((n: { id: string }) => n.id === "deploy").attrs.phases).toEqual([]);
+      });
+
+      test("op-discovery errors are warnings, not a refusal", async () => {
+        lintClean(); discovered();
+        discoverOpsMock.mockResolvedValue({ ops: new Map(), errors: ["ops/bad.op.ts: boom"] });
+        const exit = await runGraph({ args: makeArgs({ format: "ir" }), plugins: [], serializers: [] });
+        expect(exit).toBe(0);
+        expect(stderrBuf.join("\n")).toContain("ops/bad.op.ts: boom");
+      });
+    });
+
     // #1339 — `chant graph` discovered source with `params.*` empty, so a
     // declaration conditioned on a build parameter always took its default:
     // the graph showed one shape whatever `--param` or a declared `env:`

package/src/cli/handlers/graph.ts

@@ -4,6 +4,7 @@ import { discover } from "../../discovery/index";
 import { partitionByLexicon, computeStackGraph, build, mergeBuildRootEntities } from "../../build";
 import { buildGraphIr, buildLiveGraphIr, collectUnobserved, overlayGraphs, sourceOverlayGraphs, type GraphIR, type IRPipeline, type LiveObservation } from "../../graph-ir";
 import { buildDeclaredPerStack } from "../../graph-declared";
+import { mergeProjectOps } from "../../graph-ops";
 import { reconstructEdges, mergeCatalogs, containmentGroups, type ReferenceCatalog, type ContainmentPair } from "../../graph-refs";
 import { observeResources } from "../../lifecycle/observe";
 import { replaySnapshots, hasSnapshot } from "../../lifecycle/replay";
@@ -48,6 +49,7 @@ async function graphBuildParams(
   const resolution = resolveCliBuildParams(config.buildParams, {
     cli: parseParamFlags(ctx.args.param),
     paramsFile: ctx.args.paramsFile,
+    verbose: ctx.args.verbose,
   });
   if (!resolution.success) {
     for (const message of resolution.errors) console.error(message);
@@ -119,6 +121,17 @@ async function mergeGraphBuildRoots(
   return true;
 }
 
+/** #1675 — join git-root ops into a discovered entity map; op-discovery
+ * errors are warnings here (the lint gate never saw those files). */
+async function mergeGraphOps(
+  entities: Map<string, import("../../declarable").Declarable>,
+  sourceFiles: readonly string[],
+  projectPath: string,
+): Promise<void> {
+  const { errors } = await mergeProjectOps(entities, sourceFiles, projectPath);
+  for (const e of errors) console.error(formatWarning({ message: e }));
+}
+
 /**
  * `chant graph` — the Op dependency graph by default; `--stacks` renders the
  * cross-stack apply-ordering graph (edges, order, waves) chant computes from
@@ -307,7 +320,7 @@ async function runGraphLive(
         ...(args.namespace ? { namespace: args.namespace } : {}),
       });
       observations = observeResult.observations;
-      const { errors, warnings } = observeResult;
+      const { errors, warnings, notes = [] } = observeResult;
       for (const e of errors) console.error(formatWarning({ message: e }));
       // Unobserved entities (#1089) arrive as warnings — a node missing from the
       // live graph because nobody looked is a different fact from one that isn't
@@ -320,7 +333,9 @@ async function runGraphLive(
         console.error(formatWarning({
           message: `... and ${warnings.length - WARN_CAP} more entity(ies) not observed — run \`chant lifecycle diff ${environment} --live\` for the full list`,
         }));
-    }
+      }
+      // Run-level notes (#1265): one line each, outside the per-entity cap.
+      for (const n of notes) console.error(formatWarning({ message: n }));
     }
 
     // Both paths land here: a replay rejoins the live pipeline at exactly this
@@ -409,6 +424,7 @@ async function runGraphLive(
       } else if (!(await mergeGraphBuildRoots(declared.entities, buildRoots))) {
         console.error(formatWarning({ message: "overlay: a build root failed to render — showing the provisioned graph without the declared overlay" }));
       } else {
+        await mergeGraphOps(declared.entities, declared.sourceFiles, projectPath);
         const declaredIr = buildGraphIr(declared.entities, projectPath);
         ir =
           args.overlayAnchor === "live"
@@ -675,6 +691,10 @@ async function runGraphView(
     return 1;
   }
 
+  // #1675 — ops live outside sourceDir by convention; join the ones
+  // `discoverOps` finds from the git root so the IR carries the declared DAG.
+  await mergeGraphOps(result.entities, result.sourceFiles, projectPath);
+
   // Build the base IR, focus with a lens (declarable-level, most precise), then
   // apply the detail tier — so e.g. blast:<resource> works before any collapse.
   let ir: GraphIR = buildGraphIr(result.entities, projectPath);

package/src/cli/handlers/lifecycle.test.ts

@@ -2,6 +2,7 @@ import { describe, test, expect, vi, beforeEach, afterEach } from "vitest";
 import { sep } from "node:path";
 import { createMockPlugin, staticDescribeResources, staticObservation, staticDeepObservation, staticListArtifacts } from "@intentius/chant-test-utils";
 import type { LexiconPlugin, ResourceMetadata } from "../../lexicon";
+import { deepObservation } from "../../deep-observation";
 import type { BuildResult } from "../../build";
 import type { ParsedArgs } from "../registry";
 
@@ -300,6 +301,81 @@ describe("runLifecycleDiff --live", () => {
     expect(readKeys).toContain("loom-agents__aws");
   });
 
+  // #1264 — each stack declares the region it deploys to. The diff dropped it
+  // on the way to the live read, so a multi-region estate compared every stack
+  // against the ambient region and reported the out-of-region ones as absent.
+  test("multi-stack: each stack's declared region reaches the thin and deep reads", async () => {
+    buildMock.mockResolvedValue(makeBuildResult({ aws: ["bucket"] }));
+    fetchLifecycleMock.mockResolvedValue(undefined);
+    readSnapshotMock.mockResolvedValue(null);
+    loadChantConfigMock.mockResolvedValue({ config: { stacks: [
+      { name: "app-us-east-1", src: "src/us-east-1", region: "us-east-1" },
+      { name: "app-us-west-2", src: "src/us-west-2", region: "us-west-2" },
+    ] } });
+
+    const thinReads: Array<{ stack?: string; region?: string }> = [];
+    const deepReads: Array<{ stack?: string; region?: string }> = [];
+    const plugins: LexiconPlugin[] = [
+      createMockPlugin({
+        name: "aws",
+        emulator: awsEmulatorStub,
+        describeResources: async (options: { stack?: string; region?: string }) => {
+          thinReads.push({ stack: options.stack, region: options.region });
+          return {};
+        },
+        observeResourcesDeep: async (options: { stack?: string; region?: string }) => {
+          deepReads.push({ stack: options.stack, region: options.region });
+          return deepObservation({});
+        },
+      }),
+    ];
+
+    const exit = await runLifecycleDiff({
+      args: makeArgs({ path: "diff", extraPositional: "prod", live: true }),
+      plugins,
+      serializers: plugins.map((p) => p.serializer),
+    });
+
+    expect(exit).toBe(0);
+    expect(thinReads).toEqual([
+      { stack: "app-us-east-1", region: "us-east-1" },
+      { stack: "app-us-west-2", region: "us-west-2" },
+    ]);
+    expect(deepReads).toEqual([
+      { stack: "app-us-east-1", region: "us-east-1" },
+      { stack: "app-us-west-2", region: "us-west-2" },
+    ]);
+  });
+
+  test("stack without a declared region: no region reaches the live read", async () => {
+    buildMock.mockResolvedValue(makeBuildResult({ aws: ["bucket"] }));
+    fetchLifecycleMock.mockResolvedValue(undefined);
+    readSnapshotMock.mockResolvedValue(null);
+    loadChantConfigMock.mockResolvedValue({ config: { stacks: [{ name: "app", src: "src/app" }] } });
+
+    const reads: Array<Record<string, unknown>> = [];
+    const plugins: LexiconPlugin[] = [
+      createMockPlugin({
+        name: "aws",
+        emulator: awsEmulatorStub,
+        describeResources: async (options: Record<string, unknown>) => {
+          reads.push(options);
+          return {};
+        },
+      }),
+    ];
+
+    await runLifecycleDiff({
+      args: makeArgs({ path: "diff", extraPositional: "prod", live: true }),
+      plugins,
+      serializers: plugins.map((p) => p.serializer),
+    });
+
+    expect(reads).toHaveLength(1);
+    expect(reads[0].stack).toBe("app");
+    expect("region" in reads[0]).toBe(false);
+  });
+
   test("warns and skips lexicons without describeResources", async () => {
     buildMock.mockResolvedValue(makeBuildResult({ k8s: ["pod"] }));
     fetchLifecycleMock.mockResolvedValue(undefined);
@@ -704,6 +780,47 @@ describe("runLifecyclePlan", () => {
     expect(web.queried).toBe("/apis/apps/v1/namespaces/default/deployments/web");
   });
 
+  // #1674 — the plan merges every lexicon's change set into one flat
+  // `entries[]`; each row must still say which lexicon observed it, and carry
+  // the provider's physical id so an adopt/delete/runtime row named by a live
+  // key can be told apart from a declared entity name.
+  test("--json carries lexicon attribution and physicalId per entry across the merge", async () => {
+    buildMock.mockResolvedValue(makeBuildResult({ aws: ["bucket"], k8s: ["web"] }));
+    const plugins: LexiconPlugin[] = [
+      createMockPlugin({
+        name: "aws",
+        emulator: awsEmulatorStub,
+        describeResources: async () => ({
+          observation: "v1" as const,
+          resources: {
+            bucket: meta({ type: "AWS::S3::Bucket", physicalId: "arn:aws:s3:::my-bucket" }),
+            "sg-0abc123": meta({ type: "AWS::EC2::SecurityGroup", physicalId: "sg-0abc123", ownership: "foreign" }),
+          },
+        }),
+      }),
+      createMockPlugin({
+        name: "k8s",
+        describeResources: async () => ({
+          observation: "v1" as const,
+          resources: { web: meta({ type: "K8s::Apps::Deployment", physicalId: "default/web" }) },
+        }),
+      }),
+    ];
+    const exit = await runLifecyclePlan({
+      args: makeArgs({ path: "plan", extraPositional: "prod", json: true }),
+      plugins,
+      serializers: plugins.map((p) => p.serializer),
+    });
+    expect(exit).toBe(0);
+    const plan = JSON.parse(stdoutBuf.join("\n"));
+    const byName = Object.fromEntries(plan.entries.map((e: { name: string }) => [e.name, e]));
+    expect(byName.bucket).toMatchObject({ lexicon: "aws", physicalId: "arn:aws:s3:::my-bucket", action: "noop" });
+    expect(byName["sg-0abc123"]).toMatchObject({ lexicon: "aws", physicalId: "sg-0abc123", action: "adopt" });
+    expect(byName.web).toMatchObject({ lexicon: "k8s", physicalId: "default/web", action: "noop" });
+    // `name` is untouched: the adopt row is still keyed by the live key.
+    expect(byName["sg-0abc123"].name).toBe("sg-0abc123");
+  });
+
   // #1166 — plan is always a live read (no `--live` flag of its own), so a
   // declared environment endpoint applies here exactly as it does for
   // `chant graph --live` / `chant lifecycle diff --live`.