@intentius/chant 0.46.0 → 0.49.0

package/src/lifecycle/receipt-plan.ts

@@ -0,0 +1,249 @@
+/**
+ * Receipt planning (#1832, epic #1703) — the plan half of the effect-receipt
+ * contract.
+ *
+ * A receipt is declared, diffed, and observed like any resource, but it is
+ * OBSERVE-ONLY to the generic apply path: the `effect()` step (#1834) is the
+ * sole writer, on success, last (epic decision log, item 3). The plan's job is
+ * therefore not "create the receipt" — it is "say whether the effect will
+ * fire". This module compares each declared receipt's live value against its
+ * resolved expectation and classifies:
+ *
+ * - absent or differing → an `effect` entry ("effect will fire") — including
+ *   the crash-between-effect-and-write case, where a stale or missing receipt
+ *   re-proposes the fire on the next plan. That re-proposal is the whole
+ *   at-least-once guarantee; anything that stamps the receipt on the generic
+ *   path silently converts it into never.
+ * - equal → `noop` — the effect has run for these inputs; the plan is clean.
+ * - unobservable → `unobserved`, loudly. A receipt nobody could read is a
+ *   hole in the plan, never a clean row.
+ * - a reference input that cannot resolve at plan time → an `effect` entry
+ *   with an "unresolved input" note, never a guessed digest. The effect step
+ *   resolves again at run and decides there.
+ *
+ * A receipt name is also stripped out of whatever the generic change-set
+ * classification proposed for it ({@link mergeReceiptEntries}): a receipt is
+ * never a `create`, never an `update`, and never a `delete`/`adopt` prune
+ * candidate — the entries built here are the only rows a receipt gets.
+ *
+ * Pure: no I/O. Live state arrives as {@link ReceiptReading}s the caller
+ * built from its observations; reference inputs resolve through the
+ * caller-supplied resolver ({@link observedValueResolver} builds one over the
+ * plan's merged observed values).
+ */
+import { AttrRef } from "../attrref";
+import {
+  EXISTENCE_EXPECTATION,
+  resolveReceiptExpectation,
+  type EffectReceiptDeclaration,
+  type ReceiptInputResolver,
+} from "../effect-receipt";
+import type { ResourceMetadata } from "../lexicon";
+import type { UnobservedReason } from "../observation";
+import type { ChangeSet, ChangeSetEntry } from "./change-set";
+
+/**
+ * The attribute a materialized receipt's live value is read from. A lexicon
+ * receipt row's observation (#1835) maps the stored value onto
+ * `attributes[RECEIPT_VALUE_ATTRIBUTE]`; `Value` is accepted as a fallback for
+ * observations that keep the provider's own casing (SSM's `Value`).
+ */
+export const RECEIPT_VALUE_ATTRIBUTE = "value";
+
+/** Read a live receipt's stored value off an observation's attributes. */
+export function readReceiptValue(attributes: Record<string, unknown> | undefined): unknown {
+  if (!attributes) return undefined;
+  if (RECEIPT_VALUE_ATTRIBUTE in attributes) return attributes[RECEIPT_VALUE_ATTRIBUTE];
+  return attributes["Value"];
+}
+
+/**
+ * What the plan's observation pass learned about one declared receipt.
+ * Deliberately tri-state, the same shape the change set rests on (#1089):
+ * `observed: false` means "nobody looked", which is a hole — never absence.
+ * A receipt with no reading at all means no loaded lexicon even claims it.
+ */
+export interface ReceiptReading {
+  /** The lexicon actually looked. `false` → the receipt is a plan hole. */
+  observed: boolean;
+  /** Observed present in the live system. Meaningful only when `observed`. */
+  present: boolean;
+  /** The live receipt's stored value ({@link readReceiptValue}). */
+  value?: unknown;
+  /** Live resource type, when reported. */
+  type?: string;
+  /** Provider-assigned physical id, when reported. */
+  physicalId?: string;
+  /** The lexicon whose observation produced this reading. */
+  lexicon?: string;
+  /** Why the read did not happen, when `observed: false`. */
+  unobservedReason?: UnobservedReason;
+  unobservedDetail?: string;
+}
+
+/**
+ * A {@link ReceiptInputResolver} over the plan's merged observed values: an
+ * attr-ref resolves to the referenced entity's observed attribute. Anything
+ * that is not among the observed values throws — which `planReceipts` renders
+ * as an effect-will-fire entry with an "unresolved input" note rather than a
+ * guessed expectation.
+ */
+export function observedValueResolver(
+  resources: Readonly<Record<string, ResourceMetadata>>,
+): ReceiptInputResolver {
+  return (ref, path) => {
+    if (ref instanceof AttrRef) {
+      const entity = ref.getLogicalName();
+      if (!entity) {
+        throw new Error(`unresolved input at ${path}: attr-ref carries no logical name`);
+      }
+      const attrs = resources[entity]?.attributes;
+      if (!attrs || !(ref.attribute in attrs)) {
+        throw new Error(
+          `unresolved input at ${path}: ${entity}.${ref.attribute} is not among the observed values`,
+        );
+      }
+      return attrs[ref.attribute];
+    }
+    throw new Error(`unresolved input at ${path}: reference cannot resolve at plan time`);
+  };
+}
+
+/**
+ * Classify every declared receipt into its change-set entry. See the module
+ * doc for the classification; entries come back sorted by name.
+ */
+export function planReceipts(
+  receipts: ReadonlyMap<string, EffectReceiptDeclaration>,
+  readings: ReadonlyMap<string, ReceiptReading>,
+  resolver: ReceiptInputResolver,
+): ChangeSetEntry[] {
+  const entries: ChangeSetEntry[] = [];
+
+  for (const [name, receipt] of receipts) {
+    const reading = readings.get(name);
+    const base = {
+      name,
+      type: reading?.type ?? receipt.entityType,
+      ...(reading?.lexicon ? { lexicon: reading.lexicon } : {}),
+      ...(reading?.physicalId ? { physicalId: reading.physicalId } : {}),
+      effect: receipt.effect,
+      ownership: "unknown" as const,
+    };
+    const evidence = {
+      declared: true,
+      inSnapshot: false,
+      live: reading?.present ?? false,
+      observed: reading?.observed ?? false,
+    };
+
+    if (!reading) {
+      // No loaded lexicon materializes or observes this receipt — a hole,
+      // said loudly, never a silently clean row (#1089's tri-state).
+      entries.push({
+        ...base,
+        action: "unobserved",
+        evidence,
+        unobservedReason: "unsupported-kind",
+        unobservedDetail:
+          `no loaded lexicon materializes or observes this receipt — ` +
+          `whether effect "${receipt.effect}" has run is unknown, not clean`,
+      });
+      continue;
+    }
+
+    if (!reading.observed) {
+      entries.push({
+        ...base,
+        action: "unobserved",
+        evidence,
+        unobservedReason: reading.unobservedReason ?? "read-failed",
+        ...(reading.unobservedDetail ? { unobservedDetail: reading.unobservedDetail } : {}),
+      });
+      continue;
+    }
+
+    // Resolve the expectation. A reference that cannot resolve at plan time
+    // is never guessed around: the fire is proposed with the note, and the
+    // effect step resolves again at run (epic decision log, item 5).
+    let expectation: string | undefined;
+    let unresolved: string | undefined;
+    try {
+      expectation = resolveReceiptExpectation(receipt, resolver);
+    } catch (err) {
+      unresolved = err instanceof Error ? err.message : String(err);
+    }
+
+    if (!reading.present) {
+      entries.push({
+        ...base,
+        action: "effect",
+        evidence,
+        effectReason: "receipt-absent",
+        effectDetail:
+          `receipt confirmed absent — no run of "${receipt.effect}" is recorded` +
+          (unresolved ? ` (${unresolved})` : ""),
+      });
+      continue;
+    }
+
+    if (expectation === undefined) {
+      entries.push({
+        ...base,
+        action: "effect",
+        evidence,
+        effectReason: "unresolved-input",
+        effectDetail: unresolved,
+      });
+      continue;
+    }
+
+    if (reading.value === expectation) {
+      entries.push({ ...base, action: "noop", evidence });
+      continue;
+    }
+
+    entries.push({
+      ...base,
+      action: "effect",
+      evidence,
+      effectReason: "receipt-stale",
+      effectDetail:
+        receipt.flavor === "existence"
+          ? `live value ${fmtValue(reading.value)} is not the existence marker "${EXISTENCE_EXPECTATION}"`
+          : `live value ${fmtValue(reading.value)} differs from expected ${expectation}`,
+    });
+  }
+
+  entries.sort((a, b) => a.name.localeCompare(b.name));
+  return entries;
+}
+
+/**
+ * Replace whatever the generic classification proposed for the receipts with
+ * the receipt entries built by {@link planReceipts}, in place.
+ *
+ * This is the plan-side write-exclusion (#1832): the generic change set,
+ * knowing nothing about receipts, classifies a declared-but-absent receipt as
+ * `create` and an undeclared-but-live one as `delete`/`adopt` — proposals the
+ * generic apply path must never act on for a receipt, and prune candidacy a
+ * receipt must never have. Every entry named like a receipt is dropped and
+ * the receipt's own entries stand in.
+ */
+export function mergeReceiptEntries(
+  cs: ChangeSet,
+  receipts: ReadonlyMap<string, EffectReceiptDeclaration>,
+  receiptEntries: ChangeSetEntry[],
+): ChangeSet {
+  if (receipts.size === 0) return cs;
+  cs.entries = cs.entries.filter((e) => !receipts.has(e.name));
+  cs.entries.push(...receiptEntries);
+  cs.entries.sort((a, b) => a.name.localeCompare(b.name));
+  return cs;
+}
+
+function fmtValue(v: unknown): string {
+  if (v === undefined) return "<unset>";
+  const s = typeof v === "string" ? v : JSON.stringify(v);
+  return s.length > 72 ? `${s.slice(0, 69)}...` : s;
+}

package/src/lifecycle/release-ledger.ts

@@ -78,6 +78,26 @@ export interface ReleaseRecord {
   approver?: string;
   /** Optional: the archive's own manifest digest (../components/verbs/build-archive.ts's `manifestDigest`), when the caller has it — lets a reader recover full build contents/provenance, not just the promoted image digest. */
   manifestDigest?: string;
+  /**
+   * Optional: set when the deploy's capability-profile assertion (chant
+   * #1244, helm lexicon) was deliberately overridden — carries the named
+   * divergences that were bypassed (declared vs live), so the ledger shows
+   * this release knowingly skewed from its declared profile. Absent for a
+   * deploy whose target matched, and for deploys with no declared profile.
+   */
+  profileOverride?: string;
+  /**
+   * Optional: the deploy's input-side digest, when `digest` is a
+   * rendered-content identity rather than an input identity. A pinned helm
+   * deploy (chant #1242) records the render's `contentDigest` as `digest` —
+   * what this cluster actually received — and carries the input digest
+   * (chart, chart version, resolved values, capability facts; chant #1243)
+   * here, because profiles are per cluster: two environments legitimately
+   * render to different bytes, so cross-environment "is prod running what
+   * staging tested" joins on this field while `digest` proves the exact
+   * bytes each cluster got. Absent when `digest` is already input-side.
+   */
+  inputDigest?: string;
 }
 
 /** Required, non-empty-string fields every `ReleaseRecord` must carry. */

package/src/lifecycle/teardown.test.ts

@@ -281,6 +281,37 @@ describe("executeTeardown — the execution half (#1222)", () => {
     expect(report.unimplemented).toEqual([]);
   });
 
+  test("a retained outcome (#1830) passes through as the loud keep — reported, never retried, never counted failed", async () => {
+    const candidateSecret = { name: "prod/master-key", type: "K8s::Core::Secret", marker: { stack: "shop", env: "dev" } };
+    const execute = vi.fn(async (): Promise<TeardownExecution> => ({
+      outcomes: [
+        { name: "prod/master-key", outcome: "retained", detail: "generated-once secret — deliberately kept, never swept" },
+      ],
+    }));
+    const report = await executeTeardown({
+      environment: "dev",
+      stack: "shop",
+      plugins: [
+        createMockPlugin({
+          name: "k8s",
+          teardownOwned: async () => ({ candidates: [candidateSecret] }),
+          executeTeardown: execute,
+        }),
+      ],
+    });
+
+    // One pass only: retained is a verdict, not a failure to retry.
+    expect(execute).toHaveBeenCalledTimes(1);
+    expect(report.outcomes).toEqual([
+      {
+        lexicon: "k8s",
+        ...candidateSecret,
+        outcome: "retained",
+        detail: "generated-once secret — deliberately kept, never swept",
+      },
+    ]);
+  });
+
   test("reuses a handed-in plan instead of re-reading", async () => {
     const teardownOwned = vi.fn();
     const execute = vi.fn(async (): Promise<TeardownExecution> => ({

package/src/lifecycle/teardown.ts

@@ -191,11 +191,13 @@ export async function planTeardown(opts: PlanTeardownOptions): Promise<TeardownP
 export interface TeardownOutcomeEntry extends TeardownPlanEntry {
   /**
    * `skipped` is core's verdict for a candidate whose lexicon implements no
-   * `executeTeardown` yet; the other three come from the lexicon (see
-   * {@link TeardownOutcome}).
+   * `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" | "skipped";
-  /** The error for `failed`, the reason for `not-prunable`/`skipped`. */
+  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;

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/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);
+  });
+});