@intentius/chant-lexicon-terraform 0.57.0

package/src/plugin.test.ts

@@ -0,0 +1,271 @@
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { isLexiconPlugin } from "@intentius/chant/lexicon";
+import { validateLexiconConfig } from "@intentius/chant/lexicon-config";
+import type { ChantConfig } from "@intentius/chant/config";
+import { isDeclarable, isResourceDeclarable, type Declarable } from "@intentius/chant/declarable";
+import { terraformPlugin } from "./plugin";
+import { terraformConfigSchema } from "./config";
+import {
+  DATA_TYPE,
+  PROVIDER_TYPE,
+  RESOURCE_TYPE,
+  TERRAFORM_TYPE,
+  VARIABLE_TYPE,
+  parseTerraformRootContent,
+} from "./hcl/parse";
+
+const fixtures = join(dirname(fileURLToPath(import.meta.url)), "__fixtures__");
+
+/** The `props` of a parsed entity, narrowed through the guard the checks use. */
+function propsOf(entity: Declarable | undefined): Record<string, unknown> {
+  if (!entity || !isResourceDeclarable(entity)) throw new Error("not a ResourceDeclarable");
+  return entity.props as Record<string, unknown>;
+}
+
+/** `buildRoots` is optional on the contract; every test here needs it present. */
+function buildRoots(
+  projectRoot: string,
+  config: Record<string, unknown>,
+): Promise<{ entities: Map<string, Declarable>; warnings?: string[] }> {
+  const hook = terraformPlugin.buildRoots;
+  if (!hook) throw new Error("terraformPlugin.buildRoots is not registered");
+  return hook({ projectRoot, config, entities: new Map() });
+}
+
+describe("terraform plugin", () => {
+  it("is a valid LexiconPlugin", () => {
+    expect(isLexiconPlugin(terraformPlugin)).toBe(true);
+  });
+
+  it("has the correct name", () => {
+    expect(terraformPlugin.name).toBe("terraform");
+  });
+
+  it("has a serializer with the TF rule prefix", () => {
+    expect(terraformPlugin.serializer.name).toBe("terraform");
+    expect(terraformPlugin.serializer.rulePrefix).toBe("TF");
+  });
+
+  it("declares its config schema", () => {
+    expect(terraformPlugin.configSchema).toBe(terraformConfigSchema);
+  });
+
+  it("returns at least one lint rule and one post-synth check", () => {
+    expect(terraformPlugin.lintRules?.().length).toBeGreaterThan(0);
+    expect(terraformPlugin.postSynthChecks?.().length).toBeGreaterThan(0);
+  });
+
+  it("registers the LSP providers and docs", () => {
+    expect(typeof terraformPlugin.completionProvider).toBe("function");
+    expect(typeof terraformPlugin.hoverProvider).toBe("function");
+    expect(typeof terraformPlugin.docs).toBe("function");
+  });
+
+  it("loads the chant-terraform skill with real content", () => {
+    const skills = terraformPlugin.skills?.() ?? [];
+    expect(skills).toHaveLength(1);
+    expect(skills[0].name).toBe("chant-terraform");
+    expect(skills[0].content.length).toBeGreaterThan(0);
+    expect(skills[0].content).toContain("TerraformApplyOp");
+  });
+});
+
+describe("terraform config schema", () => {
+  it("accepts a root with every optional field", () => {
+    const parsed = terraformConfigSchema.parse({
+      binary: "tofu",
+      roots: {
+        app: {
+          dir: "./terraform/app",
+          workspace: "prod",
+          varFiles: ["prod.tfvars"],
+          backendConfig: { bucket: "tfstate" },
+        },
+      },
+    });
+    expect(parsed.roots.app.workspace).toBe("prod");
+  });
+
+  it("rejects an unknown key at the namespace level", () => {
+    expect(() => terraformConfigSchema.parse({ roots: {}, binaries: "tofu" })).toThrow();
+  });
+
+  it("rejects an unknown key inside a root", () => {
+    expect(() => terraformConfigSchema.parse({ roots: { app: { dir: ".", varfiles: [] } } })).toThrow();
+  });
+
+  it("rejects a binary that is neither terraform nor tofu", () => {
+    expect(() => terraformConfigSchema.parse({ binary: "pulumi", roots: {} })).toThrow();
+  });
+});
+
+describe("config load through the plugin's configSchema", () => {
+  /** What `chant build` does with the namespace before anything else runs. */
+  function validate(config: Record<string, unknown>): ReturnType<typeof validateLexiconConfig> {
+    return validateLexiconConfig([terraformPlugin], config as unknown as ChantConfig);
+  }
+
+  it("accepts a well-formed namespace", () => {
+    expect(validate({ terraform: { roots: { app: { dir: "./terraform" } } } })).toEqual([]);
+  });
+
+  // Zod 4 reports an unrecognized key at the path of the object that carries
+  // it, naming the key in the message rather than in the path.
+  it("fails an unknown key under terraform", () => {
+    const problems = validate({ terraform: { roots: {}, workspaces: ["prod"] } });
+    expect(problems).toHaveLength(1);
+    expect(problems[0].path).toBe("terraform");
+    expect(problems[0].lexicon).toBe("terraform");
+    expect(problems[0].message).toContain("workspaces");
+  });
+
+  it("fails an unknown key inside a root", () => {
+    const problems = validate({ terraform: { roots: { app: { dir: ".", varfiles: [] } } } });
+    expect(problems.map((p) => p.path)).toEqual(["terraform.roots.app"]);
+    expect(problems[0].message).toContain("varfiles");
+  });
+
+  it("fails a root with no dir", () => {
+    const problems = validate({ terraform: { roots: { app: {} } } });
+    expect(problems.map((p) => p.path)).toEqual(["terraform.roots.app.dir"]);
+  });
+
+  it("says nothing about a project that declares no terraform namespace", () => {
+    expect(validate({ lexicons: ["terraform"] })).toEqual([]);
+  });
+});
+
+describe("buildRoots", () => {
+  it("returns one entity per block for the with-backend fixture", async () => {
+    const { entities, warnings } = await buildRoots(fixtures, {
+      terraform: { roots: { app: { dir: "./with-backend" } } },
+    });
+
+    expect(warnings ?? []).toEqual([]);
+    expect([...entities.keys()].sort()).toEqual([
+      "app/null_resource.first",
+      "app/null_resource.second",
+      "app/provider.null",
+      "app/terraform",
+    ]);
+
+    const terraformBlock = entities.get("app/terraform")!;
+    expect(terraformBlock.entityType).toBe(TERRAFORM_TYPE);
+    expect(terraformBlock.lexicon).toBe("terraform");
+    expect(isDeclarable(terraformBlock)).toBe(true);
+    expect(isResourceDeclarable(terraformBlock)).toBe(true);
+
+    const props = propsOf(terraformBlock);
+    expect(props.address).toBe("terraform");
+    expect(props.file).toBe("main.tf");
+    expect(props.root).toBe("app");
+    expect((props.body as Record<string, unknown>).backend).toBeDefined();
+
+    expect(entities.get("app/provider.null")!.entityType).toBe(PROVIDER_TYPE);
+    expect(entities.get("app/null_resource.first")!.entityType).toBe(RESOURCE_TYPE);
+  });
+
+  it("parses the no-backend fixture with no backend on the terraform block", async () => {
+    const { entities } = await buildRoots(fixtures, {
+      terraform: { roots: { legacy: { dir: "./no-backend" } } },
+    });
+
+    expect([...entities.keys()].sort()).toEqual([
+      "legacy/null_resource.first",
+      "legacy/null_resource.second",
+      "legacy/provider.null",
+      "legacy/terraform",
+    ]);
+    const body = propsOf(entities.get("legacy/terraform")).body as Record<string, unknown>;
+    expect(body.backend).toBeUndefined();
+    expect(body.required_version).toBe(">= 1.5.0");
+  });
+
+  it("keys both roots apart when they are configured together", async () => {
+    const { entities } = await buildRoots(fixtures, {
+      terraform: {
+        roots: { app: { dir: "./with-backend" }, legacy: { dir: "./no-backend" } },
+      },
+    });
+    expect(entities.size).toBe(8);
+    expect(entities.has("app/terraform")).toBe(true);
+    expect(entities.has("legacy/terraform")).toBe(true);
+  });
+
+  it("resolves a relative dir against projectRoot, not the cwd", async () => {
+    const { entities, warnings } = await buildRoots(join(fixtures, "with-backend"), {
+      terraform: { roots: { app: { dir: "." } } },
+    });
+    expect(warnings ?? []).toEqual([]);
+    expect(entities.has("app/terraform")).toBe(true);
+  });
+
+  it("warns instead of throwing for a missing directory", async () => {
+    const { entities, warnings } = await buildRoots(fixtures, {
+      terraform: { roots: { gone: { dir: "./does-not-exist" } } },
+    });
+    expect(entities.size).toBe(0);
+    expect(warnings).toHaveLength(1);
+    expect(warnings![0]).toContain("terraform.roots.gone");
+    expect(warnings![0]).toContain("directory not found");
+  });
+
+  it("keeps the other roots when one is missing", async () => {
+    const { entities, warnings } = await buildRoots(fixtures, {
+      terraform: { roots: { gone: { dir: "./does-not-exist" }, app: { dir: "./with-backend" } } },
+    });
+    expect(warnings).toHaveLength(1);
+    expect(entities.has("app/terraform")).toBe(true);
+  });
+
+  it("contributes nothing when the namespace is absent", async () => {
+    const { entities, warnings } = await buildRoots(fixtures, {});
+    expect(entities.size).toBe(0);
+    expect(warnings ?? []).toEqual([]);
+  });
+});
+
+describe("auditEntities (#2085, parse-to-graph for chant audit)", () => {
+  it("parses a joined `# file:` bundle into entities", async () => {
+    const hook = terraformPlugin.auditEntities;
+    if (!hook) throw new Error("terraformPlugin.auditEntities is not registered");
+    const content = '# file: main.tf\nresource "null_resource" "root" {}';
+    const entities = await hook(content);
+    expect([...entities.keys()]).toEqual(["audit-root/null_resource.root"]);
+  });
+
+  it("never throws on malformed input; returns an empty map instead", async () => {
+    const hook = terraformPlugin.auditEntities;
+    if (!hook) throw new Error("terraformPlugin.auditEntities is not registered");
+    const entities = await hook("resource null_resource root { this is not valid hcl {{{");
+    expect(entities.size).toBe(0);
+  });
+});
+
+describe("parseTerraformRootContent", () => {
+  it("reads the joined `# file:` bundle form chant audit produces", async () => {
+    const content = [
+      '# file: main.tf\nresource "null_resource" "root" {}',
+      '# file: variables.tf\nvariable "region" {\n  type = string\n}',
+    ].join("\n");
+
+    const entities = await parseTerraformRootContent(content, ".");
+    expect([...entities.keys()].sort()).toEqual([`./null_resource.root`, `./var.region`]);
+    expect(entities.get("./var.region")!.entityType).toBe(VARIABLE_TYPE);
+    expect(propsOf(entities.get("./null_resource.root")).file).toBe("main.tf");
+    expect(propsOf(entities.get("./var.region")).file).toBe("variables.tf");
+  });
+
+  it("parses a bare .tf string with no marker at all", async () => {
+    const entities = await parseTerraformRootContent('data "null_data_source" "d" {}', "app");
+    expect(entities.get("app/data.null_data_source.d")!.entityType).toBe(DATA_TYPE);
+  });
+
+  it("numbers two blocks that share an address rather than dropping one", async () => {
+    const content = "# file: a.tf\nlocals {\n  x = 1\n}\n# file: b.tf\nlocals {\n  y = 2\n}";
+    const entities = await parseTerraformRootContent(content, "app");
+    expect([...entities.keys()]).toEqual(["app/locals", "app/locals~2"]);
+  });
+});

package/src/plugin.ts

@@ -0,0 +1,157 @@
+import type { LexiconPlugin } from "@intentius/chant/lexicon";
+import type { CompletionContext, HoverContext } from "@intentius/chant/lsp/types";
+import type { Declarable } from "@intentius/chant/declarable";
+import { createSkillsLoader } from "@intentius/chant/lexicon-plugin-helpers";
+import { terraformSerializer } from "./serializer";
+import { rules } from "./lint/rules";
+import { postSynthChecks } from "./lint/post-synth";
+import { terraformAuditCatalog } from "./lint/audit-catalog";
+import { completions } from "./lsp/completions";
+import { hover } from "./lsp/hover";
+import { terraformConfigSchema, type TerraformConfig } from "./config";
+import { renderTerraformRoots } from "./hcl/roots";
+import { parseTerraformRootContent } from "./hcl/parse";
+import { TERRAFORM_STATE_OWNERSHIP_KEYS } from "./state-ownership";
+
+const loadSkills = createSkillsLoader(import.meta.url, [
+  {
+    file: "chant-terraform.md",
+    name: "chant-terraform",
+    description:
+      "Read an existing Terraform root module into chant's build and audit, and drive it with the init/plan/apply Ops",
+  },
+]);
+
+/**
+ * terraform lexicon plugin.
+ *
+ * There is no upstream schema to pin here: Terraform's resource surface lives
+ * in provider registries, one schema per provider, and this lexicon reads the
+ * HCL an estate already has rather than generating types for it. So `spec/`
+ * and `codegen/` stay near-empty and there is no `upstreamPin`.
+ */
+export const terraformPlugin: LexiconPlugin = {
+  name: "terraform",
+  serializer: terraformSerializer,
+  configSchema: terraformConfigSchema,
+
+  // ── Required lifecycle methods ────────────────────────────────
+
+  async generate(options?: { verbose?: boolean }): Promise<void> {
+    const { generate } = await import("./codegen/generate");
+    await generate(options);
+  },
+
+  async validate(_options?: { verbose?: boolean }): Promise<void> {
+    const { validate } = await import("./validate");
+    const { printValidationResult } = await import("@intentius/chant/codegen/validate");
+    const result = await validate();
+    printValidationResult(result);
+  },
+
+  async coverage(_options?: { verbose?: boolean; minOverall?: number }): Promise<void> {
+    // No upstream spec to measure against. See the note on the plugin.
+    console.error("Coverage analysis not applicable: this lexicon generates no types from an upstream spec");
+  },
+
+  async package(options?: { verbose?: boolean; force?: boolean }): Promise<void> {
+    const { packageLexicon } = await import("./codegen/package");
+    const { writeBundleSpec } = await import("@intentius/chant/codegen/package");
+    const { join, dirname } = await import("path");
+    const { fileURLToPath } = await import("url");
+
+    const { spec, stats } = await packageLexicon(options);
+    const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+    writeBundleSpec(spec, join(pkgDir, "dist"));
+
+    console.error(`Packaged ${stats.resources} resources, ${stats.ruleCount} rules, ${stats.skillCount} skills`);
+  },
+
+  // ── Optional extensions ────────────────────────────────────
+
+  /**
+   * Terraform's ownership channel is the state file, not a tag or a label
+   * (#2087). Every address `terraform show -json` returns is `owned`;
+   * everything else is `unknown`. Declaring the channel is what makes that a
+   * claim the conformance suite checks rather than a silent degradation.
+   * See `./describe-resources.ts` and `docs/pages/observation.mdx`.
+   */
+  ownershipChannel: {
+    keys: TERRAFORM_STATE_OWNERSHIP_KEYS,
+    reads: ["describeResources"],
+  },
+
+  async describeResources(options) {
+    const { describeResources } = await import("./describe-resources");
+    return describeResources(options);
+  },
+
+  /**
+   * Each entry in `terraform.roots` is a root module directory that parses at
+   * build time into one entity per HCL block. The render lives in
+   * `./hcl/roots.ts`; this member only reads the namespace and hands over the
+   * project root, which is what relative `dir` paths resolve against.
+   */
+  async buildRoots(ctx): Promise<{ entities: Map<string, Declarable>; warnings: string[] }> {
+    const roots = (ctx.config as { terraform?: TerraformConfig }).terraform?.roots ?? {};
+    if (Object.keys(roots).length === 0) return { entities: new Map(), warnings: [] };
+    return renderTerraformRoots({ projectRoot: ctx.projectRoot, roots });
+  },
+
+  lintRules() {
+    return rules;
+  },
+
+  postSynthChecks() {
+    return postSynthChecks;
+  },
+
+  auditCatalog() {
+    return terraformAuditCatalog;
+  },
+
+  /**
+   * Parse-to-graph for `chant audit` (#1567, #2085). `content` is the
+   * `# file: <name>`-joined bundle discovery builds for one discovered root
+   * module (`classifyTerraform`, `packages/core/src/audit/core.ts`); the root
+   * name itself isn't threaded through this hook's single-argument contract,
+   * so a fixed placeholder ("audit-root") stands in for it. TF001 only uses
+   * the root name to group and de-duplicate diagnostics within one parse, so
+   * this is enough for the same graph-reading check that fires on `chant
+   * build` to fire here too. Never throws: malformed HCL yields an empty map.
+   */
+  async auditEntities(content: string): Promise<Map<string, Declarable>> {
+    try {
+      return await parseTerraformRootContent(content, "audit-root");
+    } catch {
+      return new Map();
+    }
+  },
+
+  skills: loadSkills,
+
+  mcpTools() {
+    return []; // TODO: Implement MCP tools
+  },
+
+  mcpResources() {
+    return []; // TODO: Implement MCP resources
+  },
+
+  detectTemplate(_data: unknown) {
+    return false; // TODO: Detect if a template belongs to this lexicon
+  },
+
+  completionProvider(ctx: CompletionContext) {
+    return completions(ctx);
+  },
+
+  hoverProvider(ctx: HoverContext) {
+    return hover(ctx);
+  },
+
+  async docs(options?) {
+    const { generateDocs } = await import("./codegen/docs");
+    return generateDocs(options);
+  },
+};

package/src/serializer.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+import type { Declarable } from "@intentius/chant/declarable";
+import { terraformSerializer } from "./serializer";
+import { RESOURCE_TYPE, TERRAFORM_TYPE, terraformEntity } from "./hcl/parse";
+
+describe("terraform serializer", () => {
+  it("has the contract's two required members", () => {
+    expect(terraformSerializer.name).toBe("terraform");
+    expect(terraformSerializer.rulePrefix).toBe("TF");
+  });
+
+  it("emits an empty string for an empty map", () => {
+    expect(terraformSerializer.serialize(new Map())).toBe("");
+  });
+
+  it("emits no output for parsed root entities, the .tf files are the artifact", () => {
+    const entities = new Map<string, Declarable>([
+      ["app/terraform", terraformEntity(TERRAFORM_TYPE, "terraform", {}, "main.tf", "app")],
+      [
+        "app/null_resource.first",
+        terraformEntity(RESOURCE_TYPE, "null_resource.first", { triggers: {} }, "main.tf", "app"),
+      ],
+    ]);
+    expect(terraformSerializer.serialize(entities)).toBe("");
+  });
+});

package/src/serializer.ts

@@ -0,0 +1,26 @@
+import type { Declarable, Serializer } from "@intentius/chant";
+
+/**
+ * terraform serializer.
+ *
+ * A stub, deliberately. The entities this lexicon carries come from `.tf`
+ * files that already exist on disk (`buildRoots()` parses the roots named in
+ * `terraform.roots`), so there is nothing for chant to write back: emitting
+ * HCL here would put a second, generated copy of the estate beside the
+ * authored one. The lexicon's value is what the entities let the rest of
+ * chant do with the root (post-synth checks, `chant audit`, the Op surface),
+ * not a rendered artifact.
+ *
+ * `name` and `rulePrefix` are the two members the `Serializer` contract
+ * requires, and both are load-bearing: `name` is the key `build()` files this
+ * lexicon's output under, and `rulePrefix` is what every `TF*` id is checked
+ * against.
+ */
+export const terraformSerializer: Serializer = {
+  name: "terraform",
+  rulePrefix: "TF",
+
+  serialize(_entities: Map<string, Declarable>): string {
+    return "";
+  },
+};

package/src/skills/chant-terraform.md

@@ -0,0 +1,92 @@
+---
+skill: chant-terraform
+description: Read an existing Terraform root module into chant's build and audit, and drive it with the init/plan/apply Ops
+user-invocable: true
+---
+
+# Terraform as an Existing Estate
+
+## What this lexicon covers
+
+There is no generated resource surface here, and nothing is written back over the HCL. Terraform's own `.tf` files stay the only source of truth, and `terraform apply` keeps working exactly as before. What chant adds is: one entity per HCL block, read at build time, so the post-synth checks and `chant audit` have something to see; and Op activities that drive `init`/`plan`/`apply`/`show` against a saved plan.
+
+## Naming your roots
+
+Add the `terraform` namespace to `chant.config.ts`. Importing the package brings the key into `ChantConfig`.
+
+```ts
+import type { ChantConfig } from "@intentius/chant/config";
+import "@intentius/chant-lexicon-terraform";
+
+export default {
+  lexicons: ["terraform"],
+  terraform: {
+    binary: "terraform", // or "tofu" — the two are wire-compatible for everything this lexicon does
+    roots: {
+      app: { dir: "./terraform/app", workspace: "prod", varFiles: ["prod.tfvars"] },
+    },
+  },
+} satisfies ChantConfig;
+```
+
+`dir` is the only required field, resolved against the project root (where `chant.config.ts` lives), not against the cwd a step happens to run from. The root's name (`app` above) is the entity-key prefix and the string every Op step and builder takes as `root` — keep it stable once other declarations reference it.
+
+## What a build produces
+
+Every block of every configured root becomes one entity, keyed `<root>/<address>`: `terraform { }` -> `Terraform::Terraform`, `provider "x" {}` -> `Terraform::Provider`, `resource "x" "y" {}` -> `Terraform::Resource`, `data "x" "y" {}` -> `Terraform::Data`, `module "x" {}` -> `Terraform::Module`, `variable "x" {}` -> `Terraform::Variable`, `output "x" {}` -> `Terraform::Output`, `locals {}` -> `Terraform::Locals`. Each carries `props.address`, `props.body` (the block, verbatim), `props.file` and `props.root`. A root whose `dir` doesn't exist, or whose HCL the parser refuses, warns and contributes no entities — the rest of the build is unaffected.
+
+## The one thing to check before anything else
+
+`TF001` fires once per root whose `terraform` block declares neither a `backend "<type>"` nor a `cloud {}`. That root's state is a local `terraform.tfstate`: unshared, unlocked, holding every resource attribute in plaintext. Add a real backend before anything else touches this root:
+
+```hcl
+terraform {
+  backend "s3" {
+    bucket = "acme-tfstate"
+    key    = "app/terraform.tfstate"
+    region = "us-east-1"
+  }
+}
+```
+
+`TF101` is the second rule, and it's about the Ops below: a `terraformApply` step's `planFile` must reference the output of a preceding `terraformPlan` step (`plan.out.planFile`), never a literal path. Applying an unreviewed plan, or a plan somebody hand-edited on disk, is exactly what a saved-plan discipline exists to prevent.
+
+## Driving a root with an Op
+
+`TerraformApplyOp` is Init, Plan, an optional approval Gate, then Apply — Init and Plan on the `longInfra` profile, the Gate's `show` step on `fastIdempotent`:
+
+```ts
+import { TerraformApplyOp } from "@intentius/chant-lexicon-terraform";
+
+export const { op } = TerraformApplyOp({
+  name: "app-apply",
+  root: "app",
+  gate: "on-destroy", // default — "always" gates every apply, "never" drops the Gate phase entirely
+});
+```
+
+`gate: "never"` is what makes the Op runnable under the local executor (`chant run`); any other mode emits a Gate phase, and a gate is durable-runtime work the local executor refuses. The Gate phase always shows the saved plan first and reports its `destroys` count as a `Destroys` search attribute, because `GateStep` carries no condition to branch on at build time — the approver sees what's at stake before approving, rather than the Op deciding for them.
+
+Terraform has no automatic rollback, so `compensate: true` with no command throws at build time, naming the Op, rather than warning once an apply has already half-run:
+
+```ts
+export const { op } = TerraformApplyOp({
+  name: "app-apply-gated",
+  root: "app",
+  gate: "always",
+  compensate: { command: "terraform destroy -auto-approve" },
+});
+```
+
+Reach for the four builders directly (`terraformInit`, `terraformPlan`, `terraformApply`, `terraformShow`) when a phase shape other than Init/Plan/Gate/Apply is needed — `plan.out.planFile` is how a later step references an earlier Plan step's saved output, and it only resolves when the Plan step carries an `id`.
+
+## Where a running estate's ownership answer lives
+
+Terraform's own state file is the ownership answer for what it manages — this lexicon doesn't add a second one. See the lexicon's "Live Observation" doc page for how a scheduled watch reads that state.
+
+## Rules
+
+| Rule | Severity | What it catches |
+|---|---|---|
+| TF001 | error (post-synth) | root module declares no remote backend |
+| TF101 | error | `terraformApply`'s `planFile` isn't a preceding `terraformPlan` step's output |

package/src/state-ownership.ts

@@ -0,0 +1,32 @@
+/**
+ * Terraform's ownership channel (#2087): the state file.
+ *
+ * Its own module, and a tiny one, for the same reason cedar's
+ * `src/avp/ownership.ts` is: `plugin.ts` declares `ownershipChannel` eagerly
+ * while `describeResources` is behind a dynamic import, so the keys cannot
+ * live in the reader without dragging the reader (and `node:child_process`
+ * with it) into every plugin load.
+ *
+ * The design record is the module doc of `./describe-resources.ts` and the
+ * reader-facing version is `docs/pages/observation.mdx`. The short form:
+ * chant elsewhere answers "is this mine?" from a marker it stamped onto the
+ * live resource; terraform answers it from the state file, which already
+ * records exactly which addresses a configuration manages. Nothing is ever
+ * stamped, so nothing is ever written back over an estate's own tags.
+ */
+
+import type { ChannelKeys } from "@intentius/chant/ownership";
+
+/**
+ * Where the verdict is read from, rather than what is written.
+ *
+ * {@link ChannelKeys} names tag or label keys everywhere else, because
+ * everywhere else the marker is a key/value pair on the resource. These three
+ * name the state file, the configured root that owns that state, and the
+ * workspace the root selects.
+ */
+export const TERRAFORM_STATE_OWNERSHIP_KEYS: ChannelKeys = {
+  managedBy: "terraform.state",
+  stack: "terraform.root",
+  env: "terraform.workspace",
+};

package/src/validate-cli.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env tsx
+import { validate } from "./validate";
+
+// `validate` takes an optional { basePath }; defaults to the lexicon root.
+await validate();

package/src/validate.ts

@@ -0,0 +1,28 @@
+/**
+ * Validate generated lexicon-terraform artifacts.
+ *
+ * Thin wrapper around the core validation framework
+ * with terraform-specific configuration.
+ */
+
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+import { validateLexiconArtifacts, type ValidateResult } from "@intentius/chant/codegen/validate";
+
+export type { ValidateCheck, ValidateResult } from "@intentius/chant/codegen/validate";
+
+// TODO: Add names of required entities for your lexicon
+const REQUIRED_NAMES: string[] = [];
+
+/**
+ * Validate the generated lexicon-terraform artifacts.
+ */
+export async function validate(opts?: { basePath?: string }): Promise<ValidateResult> {
+  const basePath = opts?.basePath ?? dirname(dirname(fileURLToPath(import.meta.url)));
+
+  return validateLexiconArtifacts({
+    lexiconJsonFilename: "lexicon-terraform.json",
+    requiredNames: REQUIRED_NAMES,
+    basePath,
+  });
+}