@intentius/chant 0.45.0 → 0.49.0

package/src/lifecycle/teardown.ts

@@ -0,0 +1,359 @@
+/**
+ * Teardown planning (#1222) — the enumeration half of
+ * `chant lifecycle teardown <env>`.
+ *
+ * Answers one question: which live resources carry THIS project's ownership
+ * marker for THIS environment? Selection is marker-scoped by construction —
+ * managed-by present, stack equal to the project's `ownership.stack`, env
+ * equal to the argument — so a foreign stack's resources, another env's
+ * resources, and unmarked resources are out of scope by shape, not by
+ * filtering discipline someone has to remember.
+ *
+ * Stateless: live markers only. No build, no snapshot, no ledger — the
+ * ownership record lives on the cloud resource (see ../ownership.ts), and this
+ * module reads it back from there.
+ *
+ * Two paths per lexicon:
+ * - the `teardownOwned` capability, where the lexicon enumerates its own
+ *   would-delete set (and can use a read shaped for deletion — aws's
+ *   stack-level path, k8s's prune selector);
+ * - a fallback over `describeResources` + the {@link ResourceMetadata.marker}
+ *   field (#1222 PR 1), for lexicons that have not implemented the capability
+ *   yet. Best-effort: a lexicon whose thin read only resolves declared names
+ *   returns nothing here, which the plan reports as a skip, not as clean.
+ *
+ * Whichever path ran, core re-checks every candidate's marker and drops
+ * mismatches — an implementation bug can narrow the set, never widen it.
+ *
+ * The execution half is {@link executeTeardown}: it drives each lexicon's
+ * `executeTeardown` capability over the planned set, then runs one bounded
+ * retry pass over the failures. Both halves are exported as functions —
+ * #1224's test-env harness calls them in-process, not only through the verb.
+ */
+
+import { normalizeObservation, unobservedAll } from "../observation";
+import type { ObservationLexicon, TeardownCandidate, TeardownHole, TeardownOutcome } from "../lexicon";
+import type { OwnershipMarker } from "../ownership";
+
+/** One would-delete row in a teardown plan, attributed to its lexicon. */
+export interface TeardownPlanEntry extends TeardownCandidate {
+  lexicon: string;
+}
+
+/** One hole in a teardown plan (#1089), attributed to its lexicon. */
+export interface TeardownPlanHole extends TeardownHole {
+  lexicon: string;
+}
+
+/** The plan `chant lifecycle teardown <env>` prints and #1224 consumes. */
+export interface TeardownPlan {
+  environment: string;
+  /** The project's ownership stack — the identity everything was selected on. */
+  stack: string;
+  /** The would-delete set. Every entry's marker equals `{ stack, env: environment }`. */
+  entries: TeardownPlanEntry[];
+  /** What could not be read (#1089). A plan with holes is incomplete, not clean. */
+  holes: TeardownPlanHole[];
+  /**
+   * Lexicons that took part in neither path — no `teardownOwned`, no
+   * `describeResources`. Reported so "nothing to delete" can never quietly
+   * mean "nobody looked".
+   */
+  skipped: string[];
+}
+
+export interface PlanTeardownOptions {
+  /** The environment being torn down — the marker env to select on. */
+  environment: string;
+  /** This project's ownership stack (`ownership.stack` in chant.config). */
+  stack: string;
+  plugins: ObservationLexicon[];
+  /** Deployed stack name, for a multi-stack project. */
+  deployedStack?: string;
+  /** Region that stack is deployed in. */
+  region?: string;
+  /**
+   * Every deployed stack a multi-stack project declares (`stacks` in
+   * chant.config), for a lexicon whose teardown is stack-shaped (aws
+   * enumerates and deletes whole stacks). Forwarded to `teardownOwned` /
+   * `executeTeardown` as `stacks`.
+   */
+  deployedStacks?: Array<{ name: string; region?: string }>;
+}
+
+/** True when `marker` is exactly the identity this plan selects on. */
+function markerMatches(marker: OwnershipMarker | undefined, stack: string, env: string): boolean {
+  return marker !== undefined && marker.stack === stack && marker.env === env;
+}
+
+/**
+ * Enumerate what `chant lifecycle teardown <env>` would delete. Read-only —
+ * this function never deletes and never will; execution composes on top of the
+ * plan it returns.
+ */
+export async function planTeardown(opts: PlanTeardownOptions): Promise<TeardownPlan> {
+  const marker: OwnershipMarker = { stack: opts.stack, env: opts.environment };
+  const entries: TeardownPlanEntry[] = [];
+  const holes: TeardownPlanHole[] = [];
+  const skipped: string[] = [];
+
+  for (const plugin of opts.plugins) {
+    if (plugin.teardownOwned) {
+      let enumeration;
+      try {
+        enumeration = await plugin.teardownOwned({
+          environment: opts.environment,
+          marker,
+          ...(opts.deployedStack ? { stack: opts.deployedStack } : {}),
+          ...(opts.region ? { region: opts.region } : {}),
+          ...(opts.deployedStacks && opts.deployedStacks.length > 0 ? { stacks: opts.deployedStacks } : {}),
+        });
+      } catch (err) {
+        // A failed enumeration is a hole over the whole lexicon, not a clean
+        // lexicon (#1089): nothing was read, so nothing is known.
+        holes.push({
+          lexicon: plugin.name,
+          name: "*",
+          reason: "read-failed",
+          detail: err instanceof Error ? err.message : String(err),
+        });
+        continue;
+      }
+      for (const candidate of enumeration.candidates) {
+        // Defense in depth: the contract says every candidate carries the
+        // requested identity; a candidate that does not is dropped here so an
+        // implementation bug cannot widen the delete set.
+        if (!markerMatches(candidate.marker, opts.stack, opts.environment)) continue;
+        entries.push({ lexicon: plugin.name, ...candidate });
+      }
+      for (const hole of enumeration.holes ?? []) {
+        holes.push({ lexicon: plugin.name, ...hole });
+      }
+      continue;
+    }
+
+    if (plugin.describeResources) {
+      let observed;
+      try {
+        observed = normalizeObservation(
+          await plugin.describeResources({
+            environment: opts.environment,
+            buildOutput: "",
+            entityNames: [],
+            entities: new Map(),
+            owned: true,
+            ...(opts.deployedStack ? { stack: opts.deployedStack } : {}),
+            ...(opts.region ? { region: opts.region } : {}),
+          }),
+        );
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        observed = {
+          resources: {},
+          unobserved: unobservedAll(["*"], "read-failed", message),
+          queried: {},
+          notes: [],
+        };
+      }
+      for (const [name, meta] of Object.entries(observed.resources)) {
+        // Marker-scoped by construction: no marker, foreign stack, or foreign
+        // env means not a candidate — a resource with no readable identity is
+        // never promoted to a delete.
+        if (!markerMatches(meta.marker, opts.stack, opts.environment)) continue;
+        entries.push({
+          lexicon: plugin.name,
+          name,
+          type: meta.type,
+          ...(meta.physicalId ? { physicalId: meta.physicalId } : {}),
+          marker: meta.marker!,
+        });
+      }
+      for (const [name, u] of Object.entries(observed.unobserved)) {
+        holes.push({
+          lexicon: plugin.name,
+          name,
+          ...(u.type ? { type: u.type } : {}),
+          reason: u.reason,
+          ...(u.detail ? { detail: u.detail } : {}),
+        });
+      }
+      continue;
+    }
+
+    skipped.push(plugin.name);
+  }
+
+  entries.sort((a, b) => a.lexicon.localeCompare(b.lexicon) || a.name.localeCompare(b.name));
+  return { environment: opts.environment, stack: opts.stack, entries, holes, skipped };
+}
+
+/** One planned entry's fate after execution, attributed to its lexicon. */
+export interface TeardownOutcomeEntry extends TeardownPlanEntry {
+  /**
+   * `skipped` is core's verdict for a candidate whose lexicon implements no
+   * `executeTeardown` yet; the others come from the lexicon (see
+   * {@link TeardownOutcome}). `retained` is the loud keep (#1365 decision 5):
+   * owned, no longer declared, deliberately not deleted — a `generated-once`
+   * secret survives every sweep and says so with a row.
+   */
+  outcome: "deleted" | "failed" | "not-prunable" | "retained" | "skipped";
+  /** The error for `failed`, the reason for `not-prunable`/`retained`/`skipped`. */
+  detail?: string;
+  /** True when this final outcome came from the bounded retry pass. */
+  retried?: boolean;
+}
+
+/** What `chant lifecycle teardown <env> --yes` prints and #1224 consumes. */
+export interface TeardownReport {
+  environment: string;
+  stack: string;
+  /** The plan that was executed — holes and skipped lexicons included. */
+  plan: TeardownPlan;
+  /** One row per planned entry. Never fewer: silence is never success. */
+  outcomes: TeardownOutcomeEntry[];
+  /** Lexicons whose candidates were skipped for lack of an `executeTeardown`. */
+  unimplemented: string[];
+}
+
+export interface ExecuteTeardownOptions extends PlanTeardownOptions {
+  /**
+   * A plan already computed (the one just shown to the user). Recomputed from
+   * a fresh live read when omitted.
+   */
+  plan?: TeardownPlan;
+}
+
+/**
+ * Run one execution pass over a lexicon's candidates and return exactly one
+ * outcome per candidate: what the lexicon reported, `failed` for anything it
+ * stayed silent about, and `failed` across the board when the call threw.
+ * Outcomes the lexicon volunteers for names core never asked about are
+ * dropped — an implementation cannot widen the set by reporting on it.
+ */
+async function executePass(
+  plugin: ObservationLexicon,
+  candidates: TeardownCandidate[],
+  opts: ExecuteTeardownOptions,
+  marker: OwnershipMarker,
+): Promise<Map<string, TeardownOutcome>> {
+  const byName = new Map<string, TeardownOutcome>();
+  let reported: TeardownOutcome[];
+  try {
+    const execution = await plugin.executeTeardown!({
+      environment: opts.environment,
+      marker,
+      candidates,
+      ...(opts.deployedStack ? { stack: opts.deployedStack } : {}),
+      ...(opts.region ? { region: opts.region } : {}),
+      ...(opts.deployedStacks && opts.deployedStacks.length > 0 ? { stacks: opts.deployedStacks } : {}),
+    });
+    reported = execution.outcomes;
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    for (const candidate of candidates) {
+      byName.set(candidate.name, { name: candidate.name, outcome: "failed", detail });
+    }
+    return byName;
+  }
+  const asked = new Set(candidates.map((c) => c.name));
+  for (const outcome of reported) {
+    if (!asked.has(outcome.name)) continue;
+    byName.set(outcome.name, outcome);
+  }
+  for (const candidate of candidates) {
+    if (byName.has(candidate.name)) continue;
+    byName.set(candidate.name, {
+      name: candidate.name,
+      outcome: "failed",
+      detail: "the lexicon reported no outcome for this candidate",
+    });
+  }
+  return byName;
+}
+
+/**
+ * Execute a teardown: delete every planned candidate through its lexicon's
+ * `executeTeardown`, then retry the failures once. Per-lexicon ordering only —
+ * each lexicon deletes its own set in the order its target requires (k8s
+ * deletes namespaces last, fly deletes apps last); there is no global
+ * reverse-dependency ordering in v1, the bounded retry pass covers the
+ * cross-lexicon cases it would.
+ *
+ * Every planned entry comes back with an outcome. A lexicon that enumerates
+ * but implements no execution reports its candidates as `skipped` — loudly,
+ * never as clean. Failures that survive the retry stay `failed` in the
+ * report; nothing here ever swallows one.
+ */
+export async function executeTeardown(opts: ExecuteTeardownOptions): Promise<TeardownReport> {
+  const marker: OwnershipMarker = { stack: opts.stack, env: opts.environment };
+  const plan = opts.plan ?? (await planTeardown(opts));
+
+  const byLexicon = new Map<string, TeardownPlanEntry[]>();
+  for (const entry of plan.entries) {
+    const list = byLexicon.get(entry.lexicon) ?? [];
+    list.push(entry);
+    byLexicon.set(entry.lexicon, list);
+  }
+
+  const outcomes: TeardownOutcomeEntry[] = [];
+  const unimplemented: string[] = [];
+
+  // Plugin registration order, so a project's lexicon ordering is stable.
+  for (const plugin of opts.plugins) {
+    const entries = byLexicon.get(plugin.name);
+    if (!entries) continue;
+    byLexicon.delete(plugin.name);
+
+    if (!plugin.executeTeardown) {
+      unimplemented.push(plugin.name);
+      for (const entry of entries) {
+        outcomes.push({
+          ...entry,
+          outcome: "skipped",
+          detail: `the ${plugin.name} lexicon does not implement teardown execution yet`,
+        });
+      }
+      continue;
+    }
+
+    const candidates: TeardownCandidate[] = entries.map(({ lexicon: _lexicon, ...candidate }) => candidate);
+    const first = await executePass(plugin, candidates, opts, marker);
+
+    // One bounded retry pass over this lexicon's failures — transient errors
+    // and ordering hiccups get a second chance, nothing gets an infinite one.
+    const failedNames = new Set(
+      [...first.values()].filter((o) => o.outcome === "failed").map((o) => o.name),
+    );
+    const retried =
+      failedNames.size > 0
+        ? await executePass(plugin, candidates.filter((c) => failedNames.has(c.name)), opts, marker)
+        : new Map<string, TeardownOutcome>();
+
+    for (const entry of entries) {
+      const second = retried.get(entry.name);
+      const outcome = second ?? first.get(entry.name)!;
+      outcomes.push({
+        ...entry,
+        outcome: outcome.outcome,
+        ...(outcome.detail !== undefined ? { detail: outcome.detail } : {}),
+        ...(second !== undefined ? { retried: true } : {}),
+      });
+    }
+  }
+
+  // A planned entry attributed to a lexicon that is not in `plugins` at
+  // execution time (a plan handed in from elsewhere). Nobody can delete it,
+  // and silence is never success.
+  for (const entries of byLexicon.values()) {
+    for (const entry of entries) {
+      outcomes.push({
+        ...entry,
+        outcome: "skipped",
+        detail: `no loaded lexicon named "${entry.lexicon}" to execute this candidate`,
+      });
+    }
+  }
+
+  outcomes.sort((a, b) => a.lexicon.localeCompare(b.lexicon) || a.name.localeCompare(b.name));
+  return { environment: opts.environment, stack: opts.stack, plan, outcomes, unimplemented };
+}

package/src/lifecycle/unobserved-gate.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, test } from "vitest";
+import { buildChangeSet } from "./change-set";
+import { evaluateUnobservedGate } from "./unobserved-gate";
+import type { ChangeSet } from "./change-set";
+import type { UnobservedReason } from "../observation";
+
+const cleanChangeSet = (env = "prod"): ChangeSet =>
+  buildChangeSet(env, {
+    declared: new Set(["bucket"]),
+    observedNow: { bucket: { type: "Fake::Bucket", status: "OK" } },
+    observedThen: undefined,
+  });
+
+const unobservedChangeSet = (reason: UnobservedReason, detail?: string): ChangeSet =>
+  buildChangeSet("prod", {
+    declared: new Set(["queue"]),
+    observedNow: {},
+    observedThen: undefined,
+    unobserved: { queue: { reason, ...(detail ? { detail } : {}) } },
+  });
+
+describe("evaluateUnobservedGate (#1568)", () => {
+  test("a clean change set passes under every policy", () => {
+    const cs = cleanChangeSet();
+    expect(evaluateUnobservedGate(cs)).toEqual({ pass: true, escalate: false, findings: [] });
+    expect(evaluateUnobservedGate(cs, "escalate")).toEqual({ pass: true, escalate: false, findings: [] });
+    expect(evaluateUnobservedGate(cs, { allow: [] })).toEqual({ pass: true, escalate: false, findings: [] });
+  });
+
+  test("default policy (no argument) refuses a plan with an unobserved entity", () => {
+    const cs = unobservedChangeSet("no-credentials", "aws sts get-caller-identity: access denied");
+    const verdict = evaluateUnobservedGate(cs);
+    expect(verdict.pass).toBe(false);
+    expect(verdict.escalate).toBe(false);
+    expect(verdict.findings).toEqual([
+      { name: "queue", reason: "no-credentials", detail: "aws sts get-caller-identity: access denied" },
+    ]);
+    expect(verdict.detail).toContain("queue");
+    expect(verdict.detail).toContain("no credentials");
+  });
+
+  test('explicit "refuse" behaves the same as the default', () => {
+    const cs = unobservedChangeSet("read-failed");
+    expect(evaluateUnobservedGate(cs, "refuse").pass).toBe(false);
+  });
+
+  test('"escalate" does not fail the gate but flags escalate with the findings', () => {
+    const cs = unobservedChangeSet("no-binding");
+    const verdict = evaluateUnobservedGate(cs, "escalate");
+    expect(verdict.pass).toBe(true);
+    expect(verdict.escalate).toBe(true);
+    expect(verdict.findings).toHaveLength(1);
+    expect(verdict.findings[0].reason).toBe("no-binding");
+    expect(verdict.detail).toBeDefined();
+  });
+
+  test("an allowed reason passes cleanly and is not counted as a finding", () => {
+    const cs = unobservedChangeSet("filtered");
+    const verdict = evaluateUnobservedGate(cs, { allow: ["filtered"] });
+    expect(verdict).toEqual({ pass: true, escalate: false, findings: [] });
+  });
+
+  test("a reason outside the allow list still refuses", () => {
+    const cs = unobservedChangeSet("no-credentials");
+    const verdict = evaluateUnobservedGate(cs, { allow: ["filtered"] });
+    expect(verdict.pass).toBe(false);
+    expect(verdict.findings[0].reason).toBe("no-credentials");
+  });
+
+  test("a mixed change set with one allowed and one unallowed reason only reports the unallowed one", () => {
+    const cs = buildChangeSet("prod", {
+      declared: new Set(["a", "b"]),
+      observedNow: {},
+      observedThen: undefined,
+      unobserved: {
+        a: { reason: "filtered" },
+        b: { reason: "unsupported-kind" },
+      },
+    });
+    const verdict = evaluateUnobservedGate(cs, { allow: ["filtered"] });
+    expect(verdict.pass).toBe(false);
+    expect(verdict.findings).toEqual([{ name: "b", reason: "unsupported-kind" }]);
+  });
+
+  test("never escalates or refuses on create/update/delete/adopt/noop — only `unobserved` counts", () => {
+    const cs = buildChangeSet("prod", {
+      declared: new Set(["created", "updated"]),
+      observedNow: {
+        updated: { type: "Fake::Resource", status: "DRIFTED" },
+        orphan: { type: "Fake::Resource", status: "OK" },
+      },
+      observedThen: { updated: { type: "Fake::Resource", status: "OK" } },
+    });
+    expect(evaluateUnobservedGate(cs)).toEqual({ pass: true, escalate: false, findings: [] });
+  });
+
+  test("carries type and detail through into the finding when present", () => {
+    const cs = buildChangeSet("prod", {
+      declared: new Set(["disk"]),
+      observedNow: {},
+      observedThen: undefined,
+      unobserved: { disk: { reason: "unsupported-kind", detail: "no describe support for this kind yet", type: "Fake::Disk" } },
+    });
+    const verdict = evaluateUnobservedGate(cs);
+    expect(verdict.findings).toEqual([
+      { name: "disk", type: "Fake::Disk", reason: "unsupported-kind", detail: "no describe support for this kind yet" },
+    ]);
+  });
+});

package/src/lifecycle/unobserved-gate.ts

@@ -0,0 +1,102 @@
+/**
+ * The unobserved gate predicate (#1568): a plan containing unobserved
+ * entities must not pass as clean.
+ *
+ * `buildChangeSet` (./change-set.ts) already refuses to guess when a lexicon
+ * could not look (#1089) — entries land as `action: "unobserved"`, carrying a
+ * total `unobservedReason` (`read-failed`, `no-credentials`, `no-binding`,
+ * `unsupported-kind`, `filtered`; see ../observation.ts). But nothing
+ * downstream is *required* to look: a gate that checks lint-clean,
+ * owned-only, and a blast-radius budget can walk right past a change set
+ * whose live read partially failed and call it clean, because none of those
+ * checks reads `unobserved` at all. A gate over an incomplete read is a gate
+ * over a guess.
+ *
+ * This is a reusable predicate, not a runtime — evaluate a `ChangeSet`
+ * against a policy and get back a verdict; the caller (a `lint.policies`
+ * check routed through `policyGate`, an Op step, #1487's gate-as-fact once it
+ * lands) decides what to do with a refusal (throw, diagnostic, a durable
+ * gated-run fact). Same instinct #1484 already adopts for `unknown` in the
+ * operating loop ("`unknown` never remediates"), surfaced here as something
+ * any gate can declare rather than a property of one runtime.
+ */
+import type { ChangeSet } from "./change-set";
+import { unobservedReasonText, type UnobservedReason } from "../observation";
+
+/**
+ * How the gate treats the change set's unobserved set.
+ *
+ * - `"refuse"` (the default) — any unobserved entry not covered by `allow`
+ *   fails the gate outright. Fail-closed, the right default for a policy set
+ *   aimed at agent-proposed change sets: a hole must never launder into a
+ *   clean verdict just because nobody configured otherwise.
+ * - `"escalate"` — the gate does not fail here; instead the verdict reports
+ *   `escalate: true` so a caller can route the plan to a stricter gate class
+ *   rather than the ordinary path (the same shape of routing decision #1569
+ *   makes for pipeline changes).
+ * - `{ allow: [...] }` — the listed reasons are tolerated (e.g. `"filtered"`,
+ *   intentional in a scoped run) and never fail or escalate the gate; any
+ *   reason NOT in the list still refuses. `no-credentials` — a hole that must
+ *   never launder into a clean verdict — should never appear in an `allow`
+ *   list for a policy aimed at agent-proposed change sets.
+ */
+export type UnobservedGatePolicy = "refuse" | "escalate" | { allow: UnobservedReason[] };
+
+/** One unobserved hole the gate found, carried into the refusal. */
+export interface UnobservedGateFinding {
+  name: string;
+  type?: string;
+  reason: UnobservedReason;
+  detail?: string;
+}
+
+export interface UnobservedGateVerdict {
+  /** False when the policy is `"refuse"` (default) and an unallowed unobserved entry exists. */
+  pass: boolean;
+  /** True when the policy is `"escalate"` and an unallowed unobserved entry exists — route to a stricter gate instead of failing here. */
+  escalate: boolean;
+  /** Every unobserved entry the policy did not allow. Empty when `pass` is true and `escalate` is false. */
+  findings: UnobservedGateFinding[];
+  /** Human-readable summary carrying the reasons into a refusal — the message a caller can surface as-is. Undefined when `findings` is empty. */
+  detail?: string;
+}
+
+/**
+ * Evaluate a `ChangeSet`'s unobserved set against `policy`. Pure — reads only
+ * `cs.entries`, no I/O. Defaults to `"refuse"`.
+ */
+export function evaluateUnobservedGate(
+  cs: ChangeSet,
+  policy: UnobservedGatePolicy = "refuse",
+): UnobservedGateVerdict {
+  const allowed = typeof policy === "object" ? new Set(policy.allow) : undefined;
+
+  const findings: UnobservedGateFinding[] = [];
+  for (const e of cs.entries) {
+    if (e.action !== "unobserved" || e.unobservedReason === undefined) continue;
+    if (allowed?.has(e.unobservedReason)) continue;
+    findings.push({
+      name: e.name,
+      ...(e.type ? { type: e.type } : {}),
+      reason: e.unobservedReason,
+      ...(e.unobservedDetail ? { detail: e.unobservedDetail } : {}),
+    });
+  }
+
+  if (findings.length === 0) {
+    return { pass: true, escalate: false, findings: [] };
+  }
+
+  const detail =
+    `plan contains ${findings.length} unobserved ${findings.length === 1 ? "entity" : "entities"} — ` +
+    findings
+      .map((f) => `${f.name}${f.type ? ` (${f.type})` : ""}: ${unobservedReasonText(f.reason)}${f.detail ? ` (${f.detail})` : ""}`)
+      .join(", ");
+
+  if (policy === "escalate") {
+    return { pass: true, escalate: true, findings, detail };
+  }
+
+  // "refuse" (default) and `{ allow }` both fail closed on anything not allowed.
+  return { pass: false, escalate: false, findings, detail };
+}

package/src/lint/engine.ts

@@ -1,4 +1,4 @@
-import type { LintRule, LintDiagnostic, LintContext } from "./rule";
+import type { LintRule, LintDiagnostic, LintContext, LintProjectConfig } from "./rule";
 import type { IntrinsicDef } from "../lexicon";
 import { parseFile } from "./parser";
 import { readFileSync } from "fs";
@@ -203,6 +203,10 @@ function isDiagnosticDisabled(
  *   `IntrinsicDef[]` into the fold path since #1039/#1105. Optional and
  *   defaulting to none, so a caller that hasn't resolved a project's
  *   lexicons (a unit test, `bench.test.ts`) is unaffected.
+ * @param projectConfig - chant #1221 — the project's config slice for
+ *   config-aware rules (COR021 reads `environments` + `ownership`), put on
+ *   every file's `LintContext.projectConfig`. Optional; without it those
+ *   rules stay silent.
  * @returns LintRunResult with diagnostics and suppressed items
  */
 export async function runLint(
@@ -210,6 +214,7 @@ export async function runLint(
   rules: LintRule[],
   ruleOptions?: Map<string, Record<string, unknown>>,
   intrinsics?: readonly IntrinsicDef[],
+  projectConfig?: LintProjectConfig,
 ): Promise<LintRunResult> {
   const allDiagnostics: LintDiagnostic[] = [];
   const allSuppressed: Array<LintDiagnostic & { reason?: string }> = [];
@@ -231,6 +236,7 @@ export async function runLint(
         filePath,
         lexicon: undefined,
         intrinsics,
+        projectConfig,
       };
 
       // Execute each rule

package/src/lint/knowledge-checks.test.ts

@@ -0,0 +1,80 @@
+import { describe, test, expect } from "vitest";
+import { coreKnowledgeChecks, STALE_KNOWLEDGE_BINDING_CHECK_ID } from "./knowledge-checks";
+import { runPostSynthChecks } from "./post-synth";
+import { DECLARABLE_MARKER, type Declarable } from "../declarable";
+import type { OkfBundle, OkfConcept } from "../okf-read";
+
+function entity(): Declarable {
+  return { [DECLARABLE_MARKER]: true, lexicon: "aws", entityType: "AWS::S3::Bucket" } as unknown as Declarable;
+}
+
+function concept(overrides: Partial<OkfConcept> = {}): OkfConcept {
+  return {
+    path: "decisions/example.md",
+    type: "decision",
+    binds: [],
+    frontmatter: {},
+    body: "",
+    ...overrides,
+  };
+}
+
+function run(bundle: OkfBundle, entities: Map<string, Declarable>) {
+  return runPostSynthChecks(coreKnowledgeChecks(bundle), {
+    outputs: new Map(),
+    entities,
+    warnings: [],
+    errors: [],
+    sourceFileCount: 1,
+  });
+}
+
+describe("COR026: stale knowledge binding (#1865)", () => {
+  test("check id", () => {
+    expect(STALE_KNOWLEDGE_BINDING_CHECK_ID).toBe("COR026");
+    expect(coreKnowledgeChecks({ concepts: [] }).map((c) => c.id)).toContain("COR026");
+  });
+
+  test("fires once per unresolved binding, naming the concept path and the unresolved name", () => {
+    const bundle: OkfBundle = {
+      concepts: [concept({ path: "decisions/ghost.md", title: "Stale", binds: ["ghostBucket"] })],
+    };
+    const diags = run(bundle, new Map());
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("COR026");
+    expect(diags[0].severity).toBe("warning");
+    expect(diags[0].message).toContain("decisions/ghost.md");
+    expect(diags[0].message).toContain("ghostBucket");
+  });
+
+  test("fires one diagnostic per unresolved name when a concept binds several", () => {
+    const bundle: OkfBundle = {
+      concepts: [concept({ binds: ["ghostOne", "ghostTwo"] })],
+    };
+    const diags = run(bundle, new Map());
+    expect(diags).toHaveLength(2);
+    expect(diags.map((d) => d.message).join("\n")).toContain("ghostOne");
+    expect(diags.map((d) => d.message).join("\n")).toContain("ghostTwo");
+  });
+
+  test("does not fire when the bound name resolves to a discovered entity", () => {
+    const bundle: OkfBundle = { concepts: [concept({ binds: ["realBucket"] })] };
+    const entities = new Map<string, Declarable>([["realBucket", entity()]]);
+    expect(run(bundle, entities)).toHaveLength(0);
+  });
+
+  test("does not fire for a concept with no binds at all — orphaned knowledge is legitimate", () => {
+    const bundle: OkfBundle = { concepts: [concept({ binds: [] })] };
+    expect(run(bundle, new Map())).toHaveLength(0);
+  });
+
+  test("does not fire for an empty bundle (no knowledge directory)", () => {
+    expect(run({ concepts: [] }, new Map())).toHaveLength(0);
+  });
+
+  test("build and synthesis are unaffected — severity is always warning, never error", () => {
+    const bundle: OkfBundle = { concepts: [concept({ binds: ["ghost"] })] };
+    const diags = run(bundle, new Map());
+    expect(diags.every((d) => d.severity === "warning")).toBe(true);
+  });
+});