@intentius/chant 0.57.0 → 0.58.0

package/src/lifecycle/run-ledger.ts

@@ -0,0 +1,201 @@
+/**
+ * Op run ledger (#2118, epic #2114) — one immutable record per Op run, on the
+ * `chant/lifecycle` orphan branch, modelled on `./converge-ledger.ts` down to
+ * the CAS-retry loop and the "skip a malformed line, count it" reader.
+ *
+ * ## Why an Op run leaves a record at all
+ *
+ * `OpConfig` used to carry `searchAttributes`, and the generated orchestrator
+ * code upserted `Phase`, `Drift`, `Approver` and `RollbackFailed` into them as
+ * it ran. Those are not properties of the declaration — they are facts about
+ * one run, and they only existed while a cluster held the run's history. Ops
+ * now run on whatever runtime `chant run --on`
+ * selects (#2121), including the plain in-process one, so the outcome has to
+ * be durable somewhere chant owns. Here. What stayed on the declaration is
+ * `OpConfig.labels`, the discovery half of the same field, and it is copied
+ * onto every record so a reader can filter runs the way it filters
+ * declarations.
+ *
+ * The record shape itself lives in `../op/runtime.ts`, beside the provider
+ * contract that reads it back: this is the ledger, not the vocabulary.
+ *
+ * ## Storage
+ *
+ * `<env>/runs__<op>.jsonl`, beside `<env>/converge.jsonl`. The `runs__`
+ * prefix folds what would read as a `runs/` subdirectory into one path
+ * segment: `writeBlobToPath` (./git.ts) builds the orphan branch's tree with
+ * `git mktree` over a flat `<env>/<file>` layout, and mktree rejects a slash
+ * in an entry name outright, so a genuine third level would mean rewriting
+ * that function's tree assembly. `__` is the same separator `./git.ts`'s
+ * `snapshotKey` already uses to fold a stack name into a flat blob name.
+ *
+ * Per-op rather than one file per env because a run ledger's reader almost
+ * always wants one op's history (`chant run <op>`'s own record, the local
+ * runtime's `status`/`log`), and an env with a busy op should not make every
+ * other op's read proportional to it.
+ */
+import { randomUUID } from "node:crypto";
+import { sortedJsonReplacer } from "../utils";
+import type { OpConfig } from "../op/types";
+import type { StepRecord } from "../op/local-executor";
+import type { OpRunRecord, OpRunRecordInput, OpRunPhaseRecord, OpRunStepRecord } from "../op/runtime";
+import { readBlobFromPath, readPathSha, readBlobBySha, writeBlobToPath, RefCASConflictError } from "./git";
+
+/** Prefix folding the per-op run ledgers into one flat name under `<env>/`. See the module doc. */
+const PREFIX = "runs__";
+
+/** Read-modify-append retry budget, same shape and reasoning as `appendConvergeRecord`'s. */
+const APPEND_RETRY_ATTEMPTS = 5;
+
+/** The env a run records against when its Op declares no `labels.Env`. */
+export const DEFAULT_RUN_ENV = "local";
+
+function fileFor(op: string): string {
+  return `${PREFIX}${op}.jsonl`;
+}
+
+/** The env a run records against: the Op's own `labels.Env`, else {@link DEFAULT_RUN_ENV}. */
+export function runEnvOf(config: Pick<OpConfig, "labels">): string {
+  return config.labels?.Env ?? DEFAULT_RUN_ENV;
+}
+
+function phaseStatus(steps: OpRunStepRecord[]): OpRunPhaseRecord["status"] {
+  if (steps.some((s) => s.status === "fail")) return "fail";
+  if (steps.length > 0 && steps.every((s) => s.status === "skipped")) return "skipped";
+  return "ok";
+}
+
+/**
+ * Fold a run's step records into the ledger shape, pure — no clock, no git.
+ * `started`/`ended` are supplied by the caller for the same reason
+ * `ConvergeTickRecord.timestamp` is: library code here never calls
+ * `Date.now()` itself.
+ *
+ * Phases are grouped by `StepRecord.phase` in first-seen order, which is
+ * execution order for the sequential path and the authored order for a
+ * parallel one. A compensation (`onFailure`) phase appears after the phase
+ * that failed, exactly where the executor emitted its records.
+ */
+export function buildRunRecord(
+  config: Pick<OpConfig, "name" | "labels">,
+  records: readonly StepRecord[],
+  times: {
+    started: string;
+    ended: string;
+    status: OpRunRecord["status"];
+    id?: string;
+    gate?: OpRunRecord["gate"];
+  },
+): OpRunRecordInput {
+  const phases: OpRunPhaseRecord[] = [];
+  const byName = new Map<string, OpRunPhaseRecord>();
+  const outcomes: Record<string, unknown> = {};
+
+  for (const record of records) {
+    let phase = byName.get(record.phase);
+    if (!phase) {
+      phase = { name: record.phase, status: "ok", steps: [] };
+      byName.set(record.phase, phase);
+      phases.push(phase);
+    }
+    phase.steps.push({
+      fn: record.fn,
+      status: record.status,
+      durationMs: record.durationMs,
+      ...(record.outcome ? { outcome: record.outcome } : {}),
+      ...(record.approval ? { approval: record.approval } : {}),
+      ...(record.error !== undefined ? { error: record.error } : {}),
+    });
+    if (record.outcome) outcomes[record.outcome.name] = record.outcome.value;
+  }
+  for (const phase of phases) phase.status = phaseStatus(phase.steps);
+
+  return {
+    ...(times.id !== undefined ? { id: times.id } : {}),
+    op: config.name,
+    env: runEnvOf(config),
+    started: times.started,
+    ended: times.ended,
+    status: times.status,
+    labels: { ...(config.labels ?? {}) },
+    outcomes,
+    phases,
+    ...(times.gate ? { gate: times.gate } : {}),
+  };
+}
+
+/**
+ * Append one immutable run record. Does not push to the remote — call
+ * `pushLifecycle` (./git.ts) afterward, the two-step shape every ledger here
+ * uses.
+ *
+ * Mints `record.id` when the input carries none, and retries the whole
+ * read-modify-write on `RefCASConflictError` re-reading fresh each attempt —
+ * see `appendConvergeRecord`'s doc for why both of those live in the append
+ * function rather than in its callers.
+ */
+export async function appendRunRecord(
+  input: OpRunRecordInput,
+  opts?: { cwd?: string },
+): Promise<{ commit: string; record: OpRunRecord }> {
+  const record: OpRunRecord = { version: 1, ...input, id: input.id ?? randomUUID() };
+  const json = JSON.stringify(record, sortedJsonReplacer);
+  const filename = fileFor(record.op);
+
+  let lastErr: unknown;
+  for (let attempt = 1; attempt <= APPEND_RETRY_ATTEMPTS; attempt++) {
+    try {
+      const priorSha = await readPathSha(record.env, filename, opts);
+      const existing = priorSha ? await readBlobBySha(priorSha, opts) : null;
+      const content = existing ? `${existing.replace(/\n$/, "")}\n${json}` : json;
+      const commit = await writeBlobToPath(record.env, filename, content, `Op run record: ${record.op}`, {
+        ...opts,
+        expectPriorPathSha: priorSha,
+      });
+      return { commit, record };
+    } catch (err) {
+      if (!(err instanceof RefCASConflictError)) throw err;
+      lastErr = err;
+    }
+  }
+  throw lastErr;
+}
+
+/**
+ * Read every run record for `op` in `environment`, oldest first. Malformed
+ * lines are skipped and counted, never thrown on — a hand-edited or truncated
+ * ledger degrades to a shorter history, the stance every ledger here takes.
+ */
+export async function readRunLedger(
+  environment: string,
+  op: string,
+  opts?: { cwd?: string },
+): Promise<{ records: OpRunRecord[]; malformed: number }> {
+  const content = await readBlobFromPath(environment, fileFor(op), opts);
+  if (!content) return { records: [], malformed: 0 };
+
+  const lines = content.split("\n").map((l) => l.trim()).filter(Boolean);
+  const records: OpRunRecord[] = [];
+  let malformed = 0;
+  for (const line of lines) {
+    try {
+      const parsed = JSON.parse(line) as Partial<OpRunRecord>;
+      if (
+        parsed.version !== 1 ||
+        typeof parsed.op !== "string" ||
+        typeof parsed.env !== "string" ||
+        typeof parsed.started !== "string" ||
+        typeof parsed.ended !== "string" ||
+        typeof parsed.status !== "string" ||
+        !Array.isArray(parsed.phases)
+      ) {
+        malformed++;
+        continue;
+      }
+      records.push(parsed as OpRunRecord);
+    } catch {
+      malformed++;
+    }
+  }
+  return { records, malformed };
+}

package/src/lifecycle/symptoms.ts

@@ -8,8 +8,8 @@
  * `LexiconPlugin.symptoms?()` interface in v1 — everything here is a pure
  * projection of structures chant already computes (`ChangeSet`,
  * `ComponentStatusRow[]`). No I/O in this module; a caller (the `convergeTick`
- * activity, lexicons/temporal/src/op/activities/converge.ts) gathers those
- * inputs and hands them here.
+ * activity, ../op/activities/converge.ts) gathers those inputs and hands them
+ * here.
  *
  * One record per tick, not per component: the issue's own rule sketch reads
  * `s.status`/`s.backupVerifiedAge` as a single symptom `s` a rule closes
@@ -109,7 +109,7 @@ export function deriveSymptoms(env: string, cs: ChangeSet, statusRows: Component
   };
 }
 
-/** Every field name a `ConvergeSymptom` produces — the runtime whitelist `TMP014` (lexicons/temporal) re-validates a serialized rule table's predicates against. Kept in sync with {@link ConvergeSymptom} by hand (deliberately small, changes rarely). */
+/** Every field name a `ConvergeSymptom` produces — the runtime whitelist `OPS014` (packages/core/src/lint/rules/op/ops014-converge-rule-refusals.ts) re-validates a serialized rule table's predicates against. Kept in sync with {@link ConvergeSymptom} by hand (deliberately small, changes rarely). */
 export const CONVERGE_SYMPTOM_FIELDS: ReadonlySet<string> = new Set([
   "env",
   "status",

package/src/lint/config.test.ts

@@ -1,6 +1,7 @@
 import { describe, test, expect, beforeEach, afterEach } from "vitest";
-import { loadConfig, DEFAULT_CONFIG, findProjectRoot, resolveConfiguredSeverity, applyConfiguredSeverity } from "./config";
+import { loadConfig, DEFAULT_CONFIG, findProjectRoot, resolveConfiguredSeverity, applyConfiguredSeverity, resolvePresetIds, applyConfiguredPreset } from "./config";
 import type { PostSynthDiagnostic } from "./post-synth";
+import { auditRule, type RuleMeta } from "../audit/catalog";
 import { writeFileSync, mkdirSync, rmSync } from "fs";
 import { join, resolve } from "path";
 
@@ -755,6 +756,26 @@ describe("resolveConfiguredSeverity", () => {
       resolveConfiguredSeverity({ COR009: ["fatal" as never, { max: 12 }] }, "COR009", "error"),
     ).toThrow(/severity "fatal"/);
   });
+
+  describe("alias resolution (chant #2113, opt-in via `catalog`)", () => {
+    const catalog: Record<string, RuleMeta> = {
+      NEW001: { ...auditRule("NEW001", "report-only", "guidance", "T", "r"), aliases: ["OLD001"] },
+    };
+
+    test("with no catalog, a `rules` key naming an alias does not match, today's behavior, unchanged", () => {
+      expect(resolveConfiguredSeverity({ OLD001: "off" }, "NEW001", "error")).toEqual({ severity: "error" });
+    });
+
+    test("with a catalog, a `rules` key naming an alias resolves to the canonical id", () => {
+      expect(resolveConfiguredSeverity({ OLD001: "off" }, "NEW001", "error", catalog)).toEqual({ severity: "off" });
+    });
+
+    test("a `rules` key already at the canonical id still wins over an alias entry", () => {
+      expect(
+        resolveConfiguredSeverity({ OLD001: "off", NEW001: "warning" }, "NEW001", "error", catalog),
+      ).toEqual({ severity: "warning" });
+    });
+  });
 });
 
 /**
@@ -808,4 +829,64 @@ describe("applyConfiguredSeverity", () => {
   test("an empty diagnostics list is a no-op", () => {
     expect(applyConfiguredSeverity([], { WAW019: "off" })).toEqual({ diagnostics: [], suppressed: [] });
   });
+
+  test("a `rules` key naming a retired rule's alias suppresses the renamed rule's finding, given a catalog (#2113)", () => {
+    const catalog: Record<string, RuleMeta> = {
+      WAW019: { ...auditRule("WAW019", "merge-worthy", "guidance", "T", "r"), aliases: ["WAW019-OLD"] },
+    };
+    const result = applyConfiguredSeverity([diag()], { "WAW019-OLD": "off" }, catalog);
+    expect(result.diagnostics).toEqual([]);
+    expect(result.suppressed).toEqual([diag()]);
+  });
+});
+
+describe("resolvePresetIds (chant #2113)", () => {
+  const presets = { recommended: ["A001", "A002"], all: ["A001", "A002", "A003"] };
+
+  test("a lexicon with no presets at all returns undefined (no filtering)", () => {
+    expect(resolvePresetIds(undefined, "recommended")).toBeUndefined();
+  });
+
+  test("a known preset name resolves to its id set", () => {
+    expect(resolvePresetIds(presets, "recommended")).toEqual(new Set(["A001", "A002"]));
+    expect(resolvePresetIds(presets, "all")).toEqual(new Set(["A001", "A002", "A003"]));
+  });
+
+  test("an unrecognized preset name falls back to unfiltered (undefined), not an empty set", () => {
+    expect(resolvePresetIds(presets, "typo-of-recommended")).toBeUndefined();
+  });
+});
+
+describe("applyConfiguredPreset (chant #2113)", () => {
+  function diag(checkId: string, overrides: Partial<PostSynthDiagnostic> = {}): PostSynthDiagnostic {
+    return { checkId, severity: "warning", message: `finding for ${checkId}`, ...overrides };
+  }
+
+  test("no presetIds (undefined) is a no-op: every diagnostic passes through", () => {
+    const diags = [diag("A001"), diag("Z999")];
+    const result = applyConfiguredPreset(diags, undefined, undefined);
+    expect(result.diagnostics).toEqual(diags);
+    expect(result.suppressed).toEqual([]);
+  });
+
+  test("a report-only rule outside the active preset is not reported, moved to suppressed, not dropped", () => {
+    const recommended = new Set(["A001"]);
+    const result = applyConfiguredPreset([diag("A001"), diag("Z999")], recommended, undefined);
+    expect(result.diagnostics.map((d) => d.checkId)).toEqual(["A001"]);
+    expect(result.suppressed.map((d) => d.checkId)).toEqual(["Z999"]);
+  });
+
+  test("the same rule under a wider preset (e.g. `all`) IS reported", () => {
+    const all = new Set(["A001", "Z999"]);
+    const result = applyConfiguredPreset([diag("A001"), diag("Z999")], all, undefined);
+    expect(result.diagnostics.map((d) => d.checkId).sort()).toEqual(["A001", "Z999"]);
+    expect(result.suppressed).toEqual([]);
+  });
+
+  test("an explicit `lint.rules` entry re-enables a rule the active preset excludes", () => {
+    const recommended = new Set(["A001"]);
+    const result = applyConfiguredPreset([diag("Z999")], recommended, { Z999: "warning" });
+    expect(result.diagnostics.map((d) => d.checkId)).toEqual(["Z999"]);
+    expect(result.suppressed).toEqual([]);
+  });
 });

package/src/lint/config.ts

@@ -5,6 +5,7 @@ import { evaluateProjectConfigSync } from "../config-sandbox";
 import type { Severity, RuleConfig } from "./rule";
 import type { PostSynthDiagnostic } from "./post-synth";
 import { moduleDir, getRuntime } from "../runtime-adapter";
+import { canonicalRuleId, type RuleMeta } from "../audit/catalog";
 import strictPreset from "./presets/strict.json";
 
 // chant #1117 — the upward config-discovery walk moved to a shared module
@@ -38,6 +39,7 @@ export const LintConfigSchema = z.object({
   })).optional(),
   plugins: z.array(z.string()).optional(),
   policies: z.array(z.string()).optional(),
+  presets: z.record(z.string(), z.string()).optional(),
 });
 
 /**
@@ -166,6 +168,23 @@ export interface LintConfig {
    * phase; same engine.
    */
   policies?: string[];
+  /**
+   * Lexicon name mapped to a preset name (chant #2113), e.g.
+   * `{ terraform: "recommended" }`. A preset is a lexicon's own bundle of
+   * post-synth check ids. tflint ships `recommended` (a subset) and `all`
+   * for its Terraform-language rules the same way, and a lexicon that ships
+   * one exposes it through its plugin's `lintPresets()` (`../lexicon.ts`).
+   * Naming a preset here changes which of that lexicon's post-synth findings
+   * are reported at all, distinct from `rules`, which changes an
+   * already-reported finding's severity. A rule a preset excludes is not
+   * suppressed (it never runs the severity-override gauntlet in the first
+   * place), but an explicit `rules` entry for it always wins and re-enables
+   * it regardless of the active preset, see `resolvePresetIds`/
+   * `applyConfiguredPreset` below. Unset, or naming a preset the lexicon
+   * does not export, falls back to `"recommended"`. A lexicon that ships no
+   * presets at all is unaffected by this field, same as today.
+   */
+  presets?: Record<string, string>;
 }
 
 /**
@@ -226,15 +245,30 @@ export function parseRuleConfig(value: RuleConfig): ParsedRuleConfig {
  * checks have no per-file scope to begin with (see {@link
  * ./post-synth.ts!PostSynthDiagnostic}'s doc for why), so they always pass
  * `config.rules` directly.
+ *
+ * `catalog` (chant #2113) is optional and off by default: pass a resolved
+ * audit catalog to also honor a `rules` key that names one of `id`'s
+ * `RuleMeta.aliases` rather than `id` itself. A project's
+ * `lint.rules: { OLD_ID: "off" }` then keeps suppressing the rule after it
+ * is renamed/renumbered, instead of silently starting to match nothing. Every
+ * existing call site omits `catalog` and is unaffected; a caller that has one
+ * handy (an audit-shaped consumer, not `chant build`'s post-synth loop, which
+ * has no catalog readily resolved at that point) opts in by passing it.
  */
 export function resolveConfiguredSeverity(
   rules: Record<string, RuleConfig> | undefined,
   id: string,
   defaultSeverity: Severity,
+  catalog?: Record<string, RuleMeta>,
 ): ParsedRuleConfig {
   const configValue = rules?.[id];
-  if (configValue === undefined) return { severity: defaultSeverity };
-  return parseRuleConfig(configValue);
+  if (configValue !== undefined) return parseRuleConfig(configValue);
+  if (catalog && rules) {
+    for (const [key, value] of Object.entries(rules)) {
+      if (canonicalRuleId(key, catalog) === id) return parseRuleConfig(value);
+    }
+  }
+  return { severity: defaultSeverity };
 }
 
 /**
@@ -500,16 +534,30 @@ export interface PostSynthSeverityResult {
  * remove. Config severity (`"off"`) is the one suppression surface this can
  * offer uniformly; a check that wants a per-instance escape hatch can read
  * `ctx.env`/its own options to decide not to emit a diagnostic at all.
+ *
+ * chant #2111 adds a second, narrower surface next to this one:
+ * `./suppressions.ts`'s `applyInlineSuppressions` matches `diag.entity`
+ * against `ctx.entities` (a source-level map key every `PostSynthContext`
+ * carries) instead of a name in the synthesized output, so it sidesteps the
+ * exact mismatch this comment describes. It is opt-in per lexicon (an entity
+ * has to carry a `suppressions` field) and runs as its own pass, right after
+ * this one, in both `chant build` and `chant audit`. See that module's doc
+ * for the full reasoning.
+ *
+ * `catalog` (chant #2113, optional) passes straight through to
+ * `resolveConfiguredSeverity` above for alias resolution; see its doc for
+ * what that buys and why it's opt-in.
  */
 export function applyConfiguredSeverity(
   diagnostics: readonly PostSynthDiagnostic[],
   rules: Record<string, RuleConfig> | undefined,
+  catalog?: Record<string, RuleMeta>,
 ): PostSynthSeverityResult {
   const kept: PostSynthDiagnostic[] = [];
   const suppressed: PostSynthDiagnostic[] = [];
 
   for (const diag of diagnostics) {
-    const resolved = resolveConfiguredSeverity(rules, diag.checkId, diag.severity);
+    const resolved = resolveConfiguredSeverity(rules, diag.checkId, diag.severity, catalog);
     if (resolved.severity === "off") {
       suppressed.push(diag);
       continue;
@@ -519,3 +567,64 @@ export function applyConfiguredSeverity(
 
   return { diagnostics: kept, suppressed };
 }
+
+/**
+ * Result of applying a lexicon preset to a set of post-synth diagnostics.
+ * Shaped like {@link PostSynthSeverityResult} so a caller threading both
+ * through (a preset filter, then a severity override) handles them the same
+ * way. See `applyConfiguredPreset` below.
+ */
+export interface PostSynthPresetResult {
+  /** Diagnostics whose check id the active preset enables (or that `rules` explicitly configures, see below). */
+  diagnostics: PostSynthDiagnostic[];
+  /** Diagnostics the active preset excluded, unaltered. Countable rather than silently dropped, mirroring `PostSynthSeverityResult.suppressed`. */
+  suppressed: PostSynthDiagnostic[];
+}
+
+/**
+ * Resolve `lint.presets`' name for one lexicon into the set of check ids that
+ * preset enables (chant #2113). `presets` is what a lexicon plugin's
+ * `lintPresets()` returns (`../lexicon.ts`). A lexicon that ships none
+ * passes `undefined` here, in which case this returns `undefined` and
+ * `applyConfiguredPreset` below becomes a no-op (every rule reports, exactly
+ * today's behavior for a lexicon this feature doesn't touch).
+ *
+ * An unrecognized preset name (a typo, or a name the lexicon doesn't define)
+ * also returns `undefined` rather than an empty set. Falling back to
+ * unfiltered is the safe failure direction; silently reporting nothing would
+ * not be.
+ */
+export function resolvePresetIds(
+  presets: Record<string, string[]> | undefined,
+  presetName: string,
+): Set<string> | undefined {
+  const ids = presets?.[presetName];
+  return ids ? new Set(ids) : undefined;
+}
+
+/**
+ * Filter post-synth diagnostics down to an active preset's ids (chant
+ * #2113). `presetIds` is `resolvePresetIds`'s output. `undefined` disables
+ * filtering entirely (a lexicon with no presets, or an unresolved preset
+ * name), matching tflint's own precedence chain (`--only` / rule config,
+ * then preset, then `disabled_by_default`, `tflint-ruleset-terraform`'s
+ * config docs): an explicit `lint.rules` entry for a check id always keeps
+ * that id's findings, whether or not the active preset includes it, so a
+ * project can opt a single report-only rule back in under `recommended`
+ * without switching its whole lexicon to `all`.
+ */
+export function applyConfiguredPreset(
+  diagnostics: readonly PostSynthDiagnostic[],
+  presetIds: Set<string> | undefined,
+  rules: Record<string, RuleConfig> | undefined,
+): PostSynthPresetResult {
+  if (!presetIds) return { diagnostics: [...diagnostics], suppressed: [] };
+
+  const kept: PostSynthDiagnostic[] = [];
+  const suppressed: PostSynthDiagnostic[] = [];
+  for (const diag of diagnostics) {
+    if (presetIds.has(diag.checkId) || rules?.[diag.checkId] !== undefined) kept.push(diag);
+    else suppressed.push(diag);
+  }
+  return { diagnostics: kept, suppressed };
+}

package/src/lint/policy.test.ts

@@ -1,6 +1,6 @@
 /**
  * chant #1138 — `evaluateProjectPolicies` (the `policyGate` Op step's entry
- * point, ../../lexicons/temporal/src/op/activities/policy.ts) applies
+ * point, ./op/activities/policy.ts) applies
  * `lint.rules` severity overrides to policy diagnostics the same way `chant
  * build` does (`../cli/commands/build.ts`), so a check `lint.rules` turns
  * "off" no longer gates an apply either — before this fix, only `chant

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

@@ -1,5 +1,7 @@
 import { describe, test, expect } from "vitest";
 import { runPostSynthChecks } from "./post-synth";
+import { activityContract, type ActivityContract } from "../op/activity-contract";
+import { z } from "zod";
 import type { PostSynthCheck, PostSynthContext } from "./post-synth";
 
 function createBuildResult(overrides: Partial<PostSynthContext["buildResult"]> = {}) {
@@ -131,6 +133,35 @@ describe("environment-aware checks (#201)", () => {
   });
 });
 
+describe("cross-lexicon activity contracts (#2101)", () => {
+  // A check shaped like temporal's TMP012/TMP013: it reads the merged
+  // contract map the runner hands it, and behaves as it did before the field
+  // existed when the context carries none.
+  const readsContracts: PostSynthCheck = {
+    id: "CONTRACTS",
+    description: "reports the activity names the context carries contracts for",
+    check(ctx) {
+      const names = [...(ctx.activityContracts?.keys() ?? [])].sort();
+      return [{ checkId: "CONTRACTS", severity: "warning", message: names.join(",") }];
+    },
+  };
+
+  test("the contract map is threaded into the context", () => {
+    const contracts = new Map<string, ActivityContract>([
+      ["terraformPlan", activityContract("terraformPlan", z.strictObject({ root: z.string() }))],
+    ]);
+    const diags = runPostSynthChecks([readsContracts], createBuildResult(), undefined, {
+      activityContracts: contracts,
+    });
+    expect(diags[0].message).toBe("terraformPlan");
+  });
+
+  test("a run with no contracts leaves the field undefined, not an empty map", () => {
+    const diags = runPostSynthChecks([readsContracts], createBuildResult());
+    expect(diags[0].message).toBe("");
+  });
+});
+
 describe("isPostSynthCheck", () => {
   test("accepts a well-formed check and rejects others", async () => {
     const { isPostSynthCheck } = await import("./post-synth");

package/src/lint/post-synth.ts

@@ -1,4 +1,5 @@
 import type { Declarable } from "../declarable";
+import type { ActivityContract } from "../op/activity-contract";
 import type { SerializerResult } from "../serializer";
 import type { Severity } from "./rule";
 import { parseOutputDocs, type OutputDoc } from "./output-docs";
@@ -38,6 +39,22 @@ export interface PostSynthContext {
    * with `ctx.docs ?? []` only when a context's provenance is unknown.
    */
   readonly docs?: OutputDoc[];
+  /**
+   * Activity contracts resolved across every lexicon this build configured
+   * (chant #2101), keyed by activity name — core's own plus whatever each
+   * lexicon contributes at `@intentius/chant-lexicon-<name>/op/activity-contracts`
+   * or through its plugin. Filled in by `chant build`, `chant lint` and
+   * `check-lexicon`'s example harness via `loadActivityContracts`.
+   *
+   * The checks that validate Op steps against contracts (OPS012 and OPS013,
+   * `./rules/op/`) merge this over their own statically imported table with
+   * `mergeActivityContracts`, so an Op calling `terraformPlan` or
+   * `k3sInstall` validates against the contract the owning lexicon declared
+   * instead of failing for the absence of one. Optional, and absent from a
+   * hand-built context: a check must behave as it did before this existed
+   * when it is `undefined`.
+   */
+  readonly activityContracts?: ReadonlyMap<string, ActivityContract>;
   /** Raw build result object */
   buildResult: {
     outputs: Map<string, string | SerializerResult>;
@@ -104,6 +121,14 @@ export function getAdditionalFiles(output: string | SerializerResult): Record<st
  * comment (`chant-disable`) suppression is out of scope for post-synth
  * findings — see `./config.ts`'s `applyConfiguredSeverity` doc for the full
  * reasoning and what suppression surface post-synth findings get instead.
+ *
+ * chant #2111 finds a narrower anchor that does generalize: `./suppressions.ts`'s
+ * `applyInlineSuppressions` matches `entity` against `ctx.entities` (a map key
+ * every context already carries, source-level, before serialization), not
+ * against a name in the synthesized OUTPUT. A lexicon whose entities carry a
+ * `suppressions` field (see that file's module doc) gets inline `# chant-
+ * ignore`-style comments this way; one that doesn't is unaffected, and this
+ * interface's own contract (no `file`/`line`) is unchanged either way.
  */
 export interface PostSynthDiagnostic {
   /** ID of the check that produced this diagnostic */
@@ -120,6 +145,30 @@ export interface PostSynthDiagnostic {
   entity?: string;
   /** Optional lexicon related to this diagnostic */
   lexicon?: string;
+  /**
+   * Set when the finding is that something does not exist, rather than that
+   * something present is wrong (chant #2113). TF001 (no remote backend) is
+   * the motivating case: there is no resource to set `entity` to, only the
+   * scope that is missing one. Snyk's policy-engine spec names this the
+   * "missing-resource" archetype (a `deny` whose `info` carries a
+   * `resource_type` instead of a `resource`, because there is nothing to
+   * attach to) and is the only tool in chant's TF-family survey with a
+   * first-class shape for it; trivy's own inline-ignore comments admit they
+   * cannot suppress an absence finding for exactly this reason. `kind` names
+   * what is missing (a `backend`/`cloud` block, a required resource type);
+   * `scope` names where it is missing (a root module name, a file). Renders
+   * distinctly in all three reporters (stylish/JSON/SARIF, `../cli/commands/
+   * audit.ts` and `../audit/report-model.ts`) instead of falling back to
+   * `entity`, and gives #2111's HCL suppression a block-anchored key to
+   * suppress an absence finding by (the block that *should* declare `kind`
+   * inside `scope`), independent of whatever `entity` this diagnostic sets.
+   */
+  missing?: {
+    /** What kind of thing is absent (e.g. `"backend"`, `"cloud"`). */
+    kind: string;
+    /** Where it is missing from (e.g. a root module name). */
+    scope: string;
+  };
 }
 
 /**
@@ -149,12 +198,15 @@ export function isPostSynthCheck(value: unknown): value is PostSynthCheck {
 
 /**
  * Run a set of post-synthesis checks against a build result. `env` is threaded
- * into the context so a check can branch on the current environment/stack.
+ * into the context so a check can branch on the current environment/stack, and
+ * `opts.activityContracts` (chant #2101) carries the build's cross-lexicon
+ * activity-contract map to the checks that validate Op steps against it.
  */
 export function runPostSynthChecks(
   checks: PostSynthCheck[],
   buildResult: PostSynthContext["buildResult"],
   env?: string,
+  opts?: { activityContracts?: ReadonlyMap<string, ActivityContract> },
 ): PostSynthDiagnostic[] {
   const getDocs = createDocsAccessor(buildResult.outputs);
   const ctx: PostSynthContext = {
@@ -162,6 +214,7 @@ export function runPostSynthChecks(
     entities: buildResult.entities,
     env,
     buildResult,
+    ...(opts?.activityContracts ? { activityContracts: opts.activityContracts } : {}),
     get docs(): OutputDoc[] {
       return getDocs();
     },

package/src/lint/rules/__fixtures__/comp/comp004/pass/neo4j-cluster.component.ts

@@ -1,8 +1,8 @@
-// chant-disable COMP004 -- graduates to `chant run --temporal`; the Node 1 gate is a deliberate human-approval wait, see docs/components/orchestration.mdx
+// chant-disable COMP004 -- the Node 1 gate is a deliberate human-approval wait, cleared with `chant approve neo4j-cluster approve-neo4j-node-1`
 import type { Component } from "../../../../../../components/component";
 import { gate, phase } from "../../../../../../components/component";
 
-/** COMP004 pass case: a genuine gate, opted out via a file-level disable directive with a documented reason — the intended path for a component that graduates to the Temporal backend. */
+/** COMP004 pass case: a genuine gate, opted out via a file-level disable directive with a documented reason — the intended path for a component whose rollout genuinely waits on a person. */
 export const neo4jCluster: Component = {
   name: "neo4j-cluster",
   archetype: "infra",

package/src/lint/rules/__fixtures__/comp/comp004/pass/orders-table.component.ts

@@ -1,7 +1,7 @@
 import type { Component } from "../../../../../../components/component";
 import { phase } from "../../../../../../components/component";
 
-/** COMP004 pass case: no gate step anywhere — nothing requires the durable backend. */
+/** COMP004 pass case: no gate step anywhere — nothing here stops the run for a person. */
 export const ordersTable: Component = {
   name: "orders-table",
   archetype: "infra",