@intentius/chant 0.41.19 → 0.42.1

package/src/okf.test.ts

@@ -0,0 +1,169 @@
+import { describe, test, expect } from "vitest";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { buildOkfBundle, okfConformanceProblems, splitFrontmatter, OKF_VERSION, type OkfFile } from "./okf";
+import { DECLARABLE_MARKER, type Declarable } from "./declarable";
+import { setProvenance } from "./provenance";
+import { parseYAML } from "./yaml";
+import { discover } from "./discovery/index";
+
+function decl<T extends object>(base: T): Declarable & T {
+  return { [DECLARABLE_MARKER]: true, ...base } as Declarable & T;
+}
+
+function fileMap(bundle: OkfFile[]): Map<string, string> {
+  return new Map(bundle.map((f) => [f.path, f.content]));
+}
+
+/**
+ * Assert the four OKF v0.2 conformance criteria (spec §11) over a bundle via
+ * the shared checker (`okfConformanceProblems`) — the same one the lexicon
+ * bundle tests (#1060) run — plus the version pin our own emitter guarantees.
+ */
+function assertConformant(bundle: OkfFile[]): void {
+  expect(okfConformanceProblems(bundle)).toEqual([]);
+  const index = bundle.find((f) => f.path === "index.md");
+  expect(index).toBeDefined();
+  const split = splitFrontmatter(index!.content);
+  expect(split).toBeDefined();
+  expect(parseYAML(split!.frontmatter)).toEqual({ okf_version: OKF_VERSION });
+}
+
+describe("buildOkfBundle", () => {
+  test("emits one concept per entity with parseable frontmatter and a non-empty type", () => {
+    const bucket = decl({ lexicon: "aws", entityType: "AWS::S3::Bucket", kind: "resource" as const });
+    setProvenance(bucket, { sourceFile: "/proj/src/storage.ts" });
+    const vpc = decl({ lexicon: "gcp", entityType: "Vpc" });
+    const entities = new Map<string, Declarable>([
+      ["myBucket", bucket],
+      ["vpc", vpc],
+    ]);
+
+    const bundle = buildOkfBundle({ entities, dependencies: new Map() }, "/proj");
+    const files = fileMap(bundle);
+    expect([...files.keys()]).toEqual(["aws/myBucket.md", "gcp/vpc.md", "index.md"]);
+
+    const concept = splitFrontmatter(files.get("aws/myBucket.md")!)!;
+    const front = parseYAML(concept.frontmatter);
+    expect(front.type).toBe("AWS::S3::Bucket");
+    expect(front.title).toBe("myBucket");
+    expect(front.lexicon).toBe("aws");
+    expect(front.kind).toBe("resource");
+    expect(front.source).toBe("src/storage.ts");
+    expect(concept.body).toContain("Declared in `src/storage.ts`.");
+  });
+
+  test("dependency edges become bundle-relative markdown links, both directions", () => {
+    const vpc = decl({ lexicon: "gcp", entityType: "Vpc" });
+    const subnet = decl({ lexicon: "gcp", entityType: "Subnet" });
+    const entities = new Map<string, Declarable>([
+      ["vpc", vpc],
+      ["subnet", subnet],
+    ]);
+    const dependencies = new Map([["subnet", new Set(["vpc"])]]);
+
+    const files = fileMap(buildOkfBundle({ entities, dependencies }));
+    expect(files.get("gcp/subnet.md")).toContain("## Depends on");
+    expect(files.get("gcp/subnet.md")).toContain("- [vpc](/gcp/vpc.md)");
+    expect(files.get("gcp/vpc.md")).toContain("## Referenced by");
+    expect(files.get("gcp/vpc.md")).toContain("- [subnet](/gcp/subnet.md)");
+  });
+
+  test("an unresolved dependency emits a link rather than failing — broken links are permitted", () => {
+    const app = decl({ lexicon: "k8s", entityType: "Deployment" });
+    const entities = new Map<string, Declarable>([["app", app]]);
+    const dependencies = new Map([["app", new Set(["ghost"])]]);
+
+    const bundle = buildOkfBundle({ entities, dependencies });
+    expect(fileMap(bundle).get("k8s/app.md")).toContain("- [ghost](/ghost.md)");
+    assertConformant(bundle);
+  });
+
+  test("index.md groups entities into per-lexicon sections with okf_version frontmatter", () => {
+    const bucket = decl({ lexicon: "aws", entityType: "AWS::S3::Bucket" });
+    const job = decl({ lexicon: "gitlab", entityType: "GitLab::Job" });
+    const entities = new Map<string, Declarable>([
+      ["assets", bucket],
+      ["buildJob", job],
+    ]);
+
+    const index = fileMap(buildOkfBundle({ entities, dependencies: new Map() })).get("index.md")!;
+    expect(index).toContain(`okf_version: '${OKF_VERSION}'`);
+    expect(index).toContain("# Lexicon: aws");
+    expect(index).toContain("# Lexicon: gitlab");
+    expect(index).toContain("* [assets](/aws/assets.md) - aws resource of type AWS::S3::Bucket");
+    expect(index).toContain("* [buildJob](/gitlab/buildJob.md) - gitlab resource of type GitLab::Job");
+  });
+
+  test("composite provenance rides along as extra frontmatter keys", () => {
+    const dep = decl({ lexicon: "k8s", entityType: "K8s::Apps::Deployment" });
+    setProvenance(dep, { sourceFile: "/proj/src/web.ts", composite: "WebApp", compositeInstance: "prodApp" });
+    const entities = new Map<string, Declarable>([["prodAppDeployment", dep]]);
+
+    const front = parseYAML(
+      splitFrontmatter(fileMap(buildOkfBundle({ entities, dependencies: new Map() }, "/proj")).get("k8s/prodAppDeployment.md")!)!.frontmatter,
+    );
+    expect(front.composite).toBe("WebApp");
+    expect(front.composite_instance).toBe("prodApp");
+  });
+
+  test("entity names that slug to the same path are deduped, never overwritten", () => {
+    const a = decl({ lexicon: "aws", entityType: "AWS::S3::Bucket" });
+    const b = decl({ lexicon: "aws", entityType: "AWS::S3::Bucket" });
+    const entities = new Map<string, Declarable>([
+      ["my/bucket", a],
+      ["my-bucket", b],
+    ]);
+
+    const paths = buildOkfBundle({ entities, dependencies: new Map() }).map((f) => f.path);
+    expect(new Set(paths).size).toBe(paths.length);
+    expect(paths).toContain("aws/my-bucket.md");
+    expect(paths).toContain("aws/my-bucket-2.md");
+  });
+
+  test("an empty project still emits a conformant bundle (just the index)", () => {
+    const bundle = buildOkfBundle({ entities: new Map(), dependencies: new Map() });
+    expect(bundle.map((f) => f.path)).toEqual(["index.md"]);
+    assertConformant(bundle);
+  });
+
+  test("deterministic: the same input yields byte-identical files", () => {
+    const vpc = decl({ lexicon: "gcp", entityType: "Vpc" });
+    const subnet = decl({ lexicon: "gcp", entityType: "Subnet" });
+    const entities = new Map<string, Declarable>([
+      ["vpc", vpc],
+      ["subnet", subnet],
+    ]);
+    const dependencies = new Map([["subnet", new Set(["vpc"])]]);
+
+    expect(buildOkfBundle({ entities, dependencies })).toEqual(buildOkfBundle({ entities, dependencies }));
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Shipped examples, spanning lexicons (#1058 acceptance): each bundle is
+// asserted conformant against the four v0.2 criteria and snapshot-tested.
+// ---------------------------------------------------------------------------
+
+const repoRoot = resolve(fileURLToPath(import.meta.url), "../../../..");
+
+const exampleCases: Array<[string, string]> = [
+  ["k8s layered-config", "lexicons/k8s/examples/layered-config/src"],
+  ["aws lambda-s3", "lexicons/aws/examples/lambda-s3/src"],
+  ["gitlab node-pipeline", "lexicons/gitlab/examples/node-pipeline/src"],
+];
+
+describe("buildOkfBundle over shipped examples", () => {
+  for (const [name, rel] of exampleCases) {
+    test(`${name} emits a conformant, snapshot-stable bundle`, async () => {
+      const projectPath = resolve(repoRoot, rel);
+      const result = await discover(projectPath);
+      expect(result.errors).toEqual([]);
+      expect(result.entities.size).toBeGreaterThan(0);
+
+      const bundle = buildOkfBundle(result, projectPath);
+      assertConformant(bundle);
+      expect(bundle).toMatchSnapshot();
+    });
+  }
+});

package/src/okf.ts

@@ -0,0 +1,308 @@
+import { relative, isAbsolute } from "node:path";
+import type { Declarable } from "./declarable";
+import { buildGraphIr } from "./graph-ir";
+import { isLexiconOutput, type LexiconOutput } from "./lexicon-output";
+import { getProvenance } from "./provenance";
+import { emitYAML, parseYAML } from "./yaml";
+
+/**
+ * OKF bundle emitter (#1058, epic #1057) — projects a discovered entity graph
+ * into an Open Knowledge Format v0.2 bundle: a directory of markdown files
+ * with YAML frontmatter, per the spec at
+ * https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md
+ *
+ * One concept document per entity, `type` carrying the entity's resource type
+ * string, dependency edges as bundle-relative markdown links (the form the
+ * spec recommends for stability), and a root `index.md` grouping concepts into
+ * per-lexicon sections. Emit-only: OKF as project *input* is #1059.
+ */
+
+export const OKF_VERSION = "0.2";
+
+/** One file of an OKF bundle: a bundle-relative path and its full content. */
+export interface OkfFile {
+  /** Bundle-relative path, e.g. "aws/myBucket.md" or "index.md". */
+  path: string;
+  content: string;
+}
+
+/** The subset of a discovery result the emitter reads. */
+export interface OkfBundleInput {
+  entities: Map<string, Declarable>;
+  dependencies: Map<string, Set<string>>;
+}
+
+/** Make an entity or lexicon name safe as a single path segment. */
+export function slug(name: string): string {
+  const cleaned = name.replace(/[^A-Za-z0-9._-]/g, "-").replace(/^\.+/, "");
+  return cleaned === "" ? "unnamed" : cleaned;
+}
+
+function relFile(file: string | undefined, projectPath?: string): string | undefined {
+  if (!file) return undefined;
+  if (projectPath && isAbsolute(file)) {
+    const rel = relative(projectPath, file);
+    return rel.startsWith("..") ? file : rel;
+  }
+  return file;
+}
+
+/**
+ * Render a flat frontmatter mapping as a YAML block. Keys with undefined
+ * values are dropped; scalar quoting is `emitYAML`'s.
+ */
+export function frontmatter(fields: Record<string, string | undefined>): string {
+  const lines: string[] = ["---"];
+  for (const [key, value] of Object.entries(fields)) {
+    if (value === undefined) continue;
+    lines.push(`${key}: ${emitYAML(value, 0)}`);
+  }
+  lines.push("---");
+  return lines.join("\n");
+}
+
+/**
+ * Split a concept document into its frontmatter block and body. Returns
+ * undefined when the document does not start with a `---` delimited block.
+ * Exported for the conformance tests (and any future OKF consumer, #1059).
+ */
+export function splitFrontmatter(content: string): { frontmatter: string; body: string } | undefined {
+  const lines = content.split("\n");
+  if (lines[0] !== "---") return undefined;
+  const end = lines.indexOf("---", 1);
+  if (end === -1) return undefined;
+  return {
+    frontmatter: lines.slice(1, end).join("\n"),
+    body: lines.slice(end + 1).join("\n"),
+  };
+}
+
+/**
+ * Check a bundle against the OKF v0.2 conformance criteria (spec §11) and
+ * return every violation found: parseable frontmatter on every non-reserved
+ * `.md`, a non-empty `type` everywhere, a well-formed root `index.md`, and
+ * generated cross-link entries that are bundle-absolute (or external URLs).
+ * Empty result means conformant. Shared by the project-bundle tests (#1058)
+ * and every lexicon's bundle tests (#1060).
+ */
+export function okfConformanceProblems(files: OkfFile[]): string[] {
+  const problems: string[] = [];
+  const reserved = new Set(["index.md", "log.md"]);
+  const linkTarget = /\]\(([^)]+)\)/g;
+  const externalOrAbsolute = (target: string): boolean =>
+    target.startsWith("/") || /^[a-z][a-z0-9+.-]*:/i.test(target);
+
+  for (const file of files) {
+    if (!file.path.endsWith(".md")) problems.push(`${file.path}: not a markdown file`);
+    if (file.path.startsWith("/") || file.path.includes("..")) {
+      problems.push(`${file.path}: path is not bundle-relative`);
+    }
+    if (reserved.has(file.path.split("/").pop()!)) continue;
+
+    const split = splitFrontmatter(file.content);
+    if (!split) {
+      problems.push(`${file.path}: no frontmatter block`);
+      continue;
+    }
+    let parsed: unknown;
+    try {
+      parsed = parseYAML(split.frontmatter);
+    } catch {
+      problems.push(`${file.path}: unparseable frontmatter`);
+      continue;
+    }
+    if (typeof parsed !== "object" || parsed === null) {
+      problems.push(`${file.path}: frontmatter is not a mapping`);
+      continue;
+    }
+    const type = (parsed as Record<string, unknown>).type;
+    if (typeof type !== "string" || type.length === 0) {
+      problems.push(`${file.path}: frontmatter has no non-empty type`);
+    }
+    // Cross-link entries (the "- [name](target)" lines the emitters generate)
+    // must point inside the bundle or at an external URL. Broken targets are
+    // permitted (not-yet-written knowledge); malformed ones are not. Free-text
+    // knowledge bodies may carry arbitrary links and are not checked.
+    for (const line of split.body.split("\n")) {
+      if (!line.trimStart().startsWith("- [")) continue;
+      for (const match of line.matchAll(linkTarget)) {
+        if (!externalOrAbsolute(match[1])) {
+          problems.push(`${file.path}: link target "${match[1]}" is neither bundle-absolute nor external`);
+        }
+      }
+    }
+  }
+
+  const index = files.find((f) => f.path === "index.md");
+  if (!index) {
+    problems.push("bundle has no root index.md");
+    return problems;
+  }
+  const split = splitFrontmatter(index.content);
+  if (!split) {
+    problems.push("index.md: no frontmatter block");
+    return problems;
+  }
+  const parsed = parseYAML(split.frontmatter);
+  for (const key of Object.keys(parsed ?? {})) {
+    if (key !== "okf_version") problems.push(`index.md: frontmatter carries "${key}" — okf_version is the only key an index is allowed`);
+  }
+  for (const line of split.body.split("\n")) {
+    if (line.startsWith("*") && !/^\* \[[^\]]+\]\([^)]+\) - .+$/.test(line)) {
+      problems.push(`index.md: malformed entry line: ${line}`);
+    }
+  }
+  return problems;
+}
+
+interface Concept {
+  name: string;
+  entity: Declarable;
+  /** Bundle-relative concept path, e.g. "aws/myBucket.md". */
+  path: string;
+  lexicon: string;
+  /** The frontmatter `type` — the entity's resource type string. */
+  type: string;
+  kind: string;
+}
+
+/**
+ * The `type`/`lexicon`/`kind` a concept carries. Most entities state all
+ * three; a `LexiconOutput` (an `output(...)` bridge) carries none of them
+ * directly, so its facts come from its producing side — `type` must be
+ * non-empty for the bundle to conform, never blank.
+ */
+function conceptFacts(entity: Declarable): { type: string; lexicon: string; kind: string } {
+  if (isLexiconOutput(entity)) {
+    const out = entity as unknown as LexiconOutput;
+    return { type: "Output", lexicon: out.sourceLexicon || "unknown", kind: "output" };
+  }
+  return {
+    type: entity.entityType || "Entity",
+    lexicon: entity.lexicon || "unknown",
+    kind: entity.kind ?? "resource",
+  };
+}
+
+/**
+ * Build the OKF bundle for a discovered graph. Pure and deterministic: the
+ * same entities yield byte-identical files, so bundles are diffable and
+ * snapshot-testable. `projectPath` relativizes source-file paths so the
+ * bundle is portable.
+ */
+export function buildOkfBundle(input: OkfBundleInput, projectPath?: string): OkfFile[] {
+  // Assign each entity a stable concept path: <lexicon>/<name>.md, deduped
+  // when slugging collides two distinct names.
+  const concepts = new Map<string, Concept>();
+  const takenPaths = new Set<string>();
+  const names = [...input.entities.keys()].sort((a, b) => a.localeCompare(b));
+  for (const name of names) {
+    const entity = input.entities.get(name)!;
+    const facts = conceptFacts(entity);
+    const base = `${slug(facts.lexicon)}/${slug(name)}`;
+    let path = `${base}.md`;
+    for (let n = 2; takenPaths.has(path); n++) path = `${base}-${n}.md`;
+    takenPaths.add(path);
+    concepts.set(name, { name, entity, path, ...facts });
+  }
+
+  // Dependency edges: the graph IR's AttrRef/Ref-derived edges (the same
+  // derivation `chant graph --format ir` ships) unioned with discovery's
+  // declared dependency map — the map alone misses references that live only
+  // in attribute values.
+  const dependsOn = new Map<string, Set<string>>();
+  const addEdge = (from: string, to: string): void => {
+    if (!dependsOn.has(from)) dependsOn.set(from, new Set());
+    dependsOn.get(from)!.add(to);
+  };
+  for (const edge of buildGraphIr(input.entities, projectPath).edges) addEdge(edge.from, edge.to);
+  for (const [from, deps] of input.dependencies) for (const to of deps) addEdge(from, to);
+
+  // Reverse edges: who references each entity.
+  const referencedBy = new Map<string, string[]>();
+  for (const [from, deps] of dependsOn) {
+    for (const to of deps) {
+      if (!referencedBy.has(to)) referencedBy.set(to, []);
+      referencedBy.get(to)!.push(from);
+    }
+  }
+
+  const files: OkfFile[] = [];
+
+  for (const name of names) {
+    const concept = concepts.get(name)!;
+    const { entity } = concept;
+    const prov = getProvenance(entity);
+    const source = relFile(prov?.sourceFile, projectPath);
+
+    const head = frontmatter({
+      type: concept.type,
+      title: name,
+      description: `${concept.lexicon} ${concept.kind} of type ${concept.type}`,
+      name,
+      lexicon: concept.lexicon,
+      kind: concept.kind,
+      source,
+      composite: prov?.composite,
+      composite_instance: prov?.compositeInstance,
+    });
+
+    const body: string[] = [""];
+    body.push(source ? `Declared in \`${source}\`.` : `Declared by the ${concept.lexicon} lexicon.`);
+
+    // Cross-resource references become bundle-relative links. A dependency
+    // whose target is not in the bundle still emits a link — the spec permits
+    // broken links (not-yet-written knowledge), so unresolved never fails.
+    const deps = [...(dependsOn.get(name) ?? [])].sort((a, b) => a.localeCompare(b));
+    if (deps.length > 0) {
+      body.push("", "## Depends on", "");
+      for (const dep of deps) {
+        const target = concepts.get(dep)?.path ?? `${slug(dep)}.md`;
+        body.push(`- [${dep}](/${target})`);
+      }
+    }
+
+    const consumers = (referencedBy.get(name) ?? []).sort((a, b) => a.localeCompare(b));
+    if (consumers.length > 0) {
+      body.push("", "## Referenced by", "");
+      for (const consumer of consumers) {
+        const target = concepts.get(consumer)?.path ?? `${slug(consumer)}.md`;
+        body.push(`- [${consumer}](/${target})`);
+      }
+    }
+
+    body.push("");
+    files.push({ path: concept.path, content: head + body.join("\n") });
+  }
+
+  files.push({ path: "index.md", content: buildIndex(concepts, names) });
+  files.sort((a, b) => a.path.localeCompare(b.path));
+  return files;
+}
+
+/**
+ * The bundle-root `index.md` (spec §8): one section per lexicon, each entry a
+ * bundle-relative link plus the concept's description — the spec's
+ * progressive-disclosure mechanism. Root indexes may carry `okf_version`
+ * frontmatter (spec §12), the only frontmatter an index is allowed.
+ */
+function buildIndex(concepts: Map<string, Concept>, names: string[]): string {
+  const byLexicon = new Map<string, Concept[]>();
+  for (const name of names) {
+    const concept = concepts.get(name)!;
+    if (!byLexicon.has(concept.lexicon)) byLexicon.set(concept.lexicon, []);
+    byLexicon.get(concept.lexicon)!.push(concept);
+  }
+
+  const lines: string[] = ["---", `okf_version: '${OKF_VERSION}'`, "---", ""];
+  const lexicons = [...byLexicon.keys()].sort((a, b) => a.localeCompare(b));
+  for (const lexicon of lexicons) {
+    lines.push(`# Lexicon: ${lexicon}`, "");
+    for (const concept of byLexicon.get(lexicon)!) {
+      lines.push(`* [${concept.name}](/${concept.path}) - ${lexicon} ${concept.kind} of type ${concept.type}`);
+    }
+    lines.push("");
+  }
+  if (lexicons.length === 0) lines.push("No entities discovered.", "");
+  return lines.join("\n");
+}

package/src/reconcile.ts

@@ -19,6 +19,8 @@
  * only part that drives I/O (through the provider's `Cycle` implementations).
  */
 
+import { GOVERNANCE_VERBS, type GovernanceVerb } from "./governance.js";
+
 // ---------------------------------------------------------------------------
 // Change-set model
 // ---------------------------------------------------------------------------
@@ -38,6 +40,12 @@ export interface ChangeSetEntry {
   kind: ChangeKind;
   /** High-level resource category (e.g. "team", "member", "branch-protection"). */
   resourceType: string;
+  /**
+   * Cross-provider governance category (#790). `resourceType` stays the
+   * provider-specific display string; the verb is the shared grammar SCM and
+   * cloud plans group by. Stamped by `runReconcile` from the cycle's `verb`.
+   */
+  verb?: GovernanceVerb;
   /**
    * Unique key identifying this resource within its type.
    * - For top-level resources: a single name (team slug, member login, …).
@@ -211,8 +219,17 @@ export function renderChangeSet(cs: ChangeSet): string {
 
   const ORDER: ChangeKind[] = ["create", "update", "delete"];
   for (const kind of ORDER) {
-    const group = byKind[kind];
+    let group = byKind[kind];
     if (group.length === 0) continue;
+    // Verb-aware grouping (#790): when entries carry governance verbs, order
+    // each section by verb (vocabulary order, unverbed entries last) so mixed
+    // plans read category-by-category. Stable, and line format is unchanged —
+    // a verbless change set renders exactly as before.
+    if (group.some((e) => e.verb)) {
+      const rank = (e: ChangeSetEntry): number =>
+        e.verb ? GOVERNANCE_VERBS.indexOf(e.verb) : GOVERNANCE_VERBS.length;
+      group = [...group].sort((a, b) => rank(a) - rank(b));
+    }
     lines.push(`\n${kind.toUpperCase()}:`);
     for (const e of group) {
       lines.push(`  [${e.resourceType}] ${e.key}`);
@@ -399,6 +416,12 @@ class MutableRateBudget implements RateBudget {
 export interface Cycle<TClient, TConfig, TLive, TScope = unknown> {
   /** Human-readable name, e.g. "branch-protection". */
   name: string;
+  /**
+   * Cross-provider governance category this cycle reconciles (#790). Every
+   * SCM warden cycle stamps one; cloud cycles (epic #787 C2) must. Optional
+   * only so provider-external Cycle implementations don't break.
+   */
+  verb?: GovernanceVerb;
   fetchLive(client: TClient, scopeId: string, scope: TScope, budget: RateBudget): Promise<TLive>;
   buildDesired(config: TConfig, scopeId: string, scope: TScope): TConfig;
   apply(
@@ -413,6 +436,8 @@ export interface Cycle<TClient, TConfig, TLive, TScope = unknown> {
 /** Per-cycle outcome recorded in the run result. */
 export interface CycleResult {
   name: string;
+  /** The cycle's governance verb (#790), when it stamps one. */
+  verb?: GovernanceVerb;
   /** Scope id this result is for (e.g. an org login). */
   org: string;
   counts: { create: number; update: number; delete: number };
@@ -535,6 +560,11 @@ export async function runReconcile<TClient, TConfig, TLive, TScope = unknown>(
       }
 
       const changeSet = diffFn(scopeId, desired, live, diffOptions);
+      // Stamp the cycle's governance verb (#790) onto entries that don't
+      // carry one, so provider diffs stay verb-unaware.
+      if (cycle.verb) {
+        for (const e of changeSet.entries) e.verb ??= cycle.verb;
+      }
       const guardrailResult = guardrails(changeSet, live);
 
       const counts = { create: 0, update: 0, delete: 0 };
@@ -542,6 +572,7 @@ export async function runReconcile<TClient, TConfig, TLive, TScope = unknown>(
 
       const cycleResult: CycleResult = {
         name: cycle.name,
+        verb: cycle.verb,
         org: scopeId,
         counts,
         guardrails: guardrailResult,

package/src/terraform/__fixtures__/build-graph.ts

@@ -0,0 +1,25 @@
+import { buildGraph, collectExpressions, type ExpressionRefs } from "../graph";
+import type { Hcl2JsonTree, TfGraph } from "../types";
+
+/**
+ * Test-only stand-in for the hcl2json expression AST (`parse.ts`'s
+ * `resolveExpressionRefs`). Fixture expressions are simple `${<accessor>}`
+ * templates, so each one's accessor list is just its interpolation bodies.
+ * Production never takes this path — `parseTerraformDir` resolves every
+ * expression through `getReferencesInExpression`.
+ */
+export function fixtureExprRefs(tree: Hcl2JsonTree): ExpressionRefs {
+  const refs = new Map<string, string[]>();
+  for (const expr of collectExpressions(tree)) {
+    refs.set(
+      expr,
+      [...expr.matchAll(/\$\{([^}]+)\}/g)].map((m) => m[1].trim()),
+    );
+  }
+  return refs;
+}
+
+/** `buildGraph` over a hand-written fixture tree, accessors derived per {@link fixtureExprRefs}. */
+export function buildFixtureGraph(tree: Hcl2JsonTree): TfGraph {
+  return buildGraph(tree, fixtureExprRefs(tree));
+}

package/src/terraform/adopt-state.test.ts

@@ -1,5 +1,5 @@
 import { describe, test, expect } from "vitest";
-import { adoptFromState, canAdoptFromState, supportedStateAdoptionTypes } from "./adopt-state";
+import { adoptFromState, canAdoptFromState, supportedStateAdoptionTypes, type DeferredParam } from "./adopt-state";
 import type { StateResource } from "./state";
 
 describe("adoptFromState", () => {
@@ -45,6 +45,39 @@ describe("adoptFromState", () => {
     expect(out.content).toContain("RetentionInDays: 30");
   });
 
+  test("a deferred input renders as a params reference, not the state literal (#998)", () => {
+    const subnet: StateResource = {
+      type: "aws_subnet",
+      name: "a",
+      attributes: { id: "subnet-0aa", vpc_id: "vpc-0abc", cidr_block: "10.0.1.0/24" },
+    };
+    const params: DeferredParam[] = [
+      { name: "vpc_id", tfAttr: "vpc_id", survivor: "aws_vpc.main", attrs: ["id"], default: "vpc-0abc" },
+    ];
+    const out = adoptFromState(subnet, params)!;
+    expect(out.parameterized).toEqual(["vpc_id"]);
+    expect(out.content).toContain('import { params } from "@intentius/chant/params";');
+    expect(out.content).toContain("VpcId: params.vpc_id as string,");
+    expect(out.content).not.toContain('VpcId: "vpc-0abc"');
+    // Non-deferred props keep their state literals.
+    expect(out.content).toContain('CidrBlock: "10.0.1.0/24"');
+  });
+
+  test("a deferred input on an unmapped attribute leaves the source alone", () => {
+    const lambda: StateResource = {
+      type: "aws_lambda_function",
+      name: "api",
+      attributes: { id: "myapp-api", function_name: "myapp-api", environment: [{ variables: { B: "b" } }] },
+    };
+    const params: DeferredParam[] = [
+      { name: "environment", tfAttr: "environment", survivor: "aws_s3_bucket.assets", attrs: ["bucket"] },
+    ];
+    const out = adoptFromState(lambda, params)!;
+    expect(out.parameterized).toEqual([]);
+    expect(out.content).not.toContain("@intentius/chant/params");
+    expect(out.content).toContain('FunctionName: "myapp-api"');
+  });
+
   test("canAdoptFromState gates on a known native constructor", () => {
     expect(canAdoptFromState("aws_s3_bucket")).toBe(true);
     expect(canAdoptFromState("random_pet")).toBe(false);