@intentius/chant 0.46.0 → 0.50.0

package/src/lifecycle/scenario.ts

@@ -0,0 +1,321 @@
+/**
+ * Plan scenarios (chant #1292): a declared expectation about what a change
+ * SHOULD do, checkable offline against a fixture snapshot.
+ *
+ * Everything else chant validates is about shape — is this declaration
+ * well-formed, does this reference resolve. Nothing answers "what will this
+ * change do" as something source can assert about itself, until now. A
+ * `Scenario` pairs a `given` (a stand-in for live observation) with an
+ * `expect` (a claim about the resulting change set) — `chant scenario check`
+ * (../cli/handlers/scenario.ts) builds the project, replays `given` in place
+ * of a live read, and evaluates `expect` against the resulting `ChangeSet`
+ * (./change-set.ts) via `evaluateScenario` (./scenario-eval.ts).
+ *
+ * Modeled precisely on the other non-resource Declarables (../effect-receipt.ts,
+ * ../secret-provenance.ts): discovery collects a `Scenario` like any entity
+ * (it is a Declarable), but it carries no resource payload and no serializer
+ * ever emits it — `partitionByLexicon` (../build.ts) excludes it from every
+ * lexicon's partition, the same way it excludes a secret declaration.
+ *
+ * This module is pure and does no I/O: `snapshot()` records where the fixture
+ * comes from without reading it, and the factory validates and freezes. The
+ * CLI handler is where the fixture is actually read, replayed, and compared —
+ * the same synthesis/plan split every other lifecycle primitive here follows.
+ */
+
+import { DECLARABLE_MARKER, type Declarable } from "../declarable";
+import type { Ownership } from "./change-set";
+
+/** Marker symbol identifying a scenario declaration. `Symbol.for` so it
+ * survives the entity-wire codec, the same reason ../effect-receipt.ts and
+ * ../secret-provenance.ts use `Symbol.for` for their markers. */
+export const SCENARIO_MARKER = Symbol.for("chant.scenario");
+
+/** The `entityType` every scenario declaration carries. */
+export const SCENARIO_ENTITY_TYPE = "Chant::Scenario";
+
+/**
+ * `given: snapshot("fixtures/prod-baseline.json")` — a checked-in fixture, in
+ * the same {@link LifecycleSnapshot} JSON shape `chant lifecycle snapshot`
+ * writes (a single lexicon's recorded resources). Path-relative to the
+ * project root, read at check time — never here.
+ */
+export interface ScenarioGivenFile {
+  readonly kind: "file";
+  /** Repo-relative path to the fixture JSON file. */
+  readonly path: string;
+}
+
+/**
+ * `given: snapshot("prod")` — the last snapshot recorded for that environment
+ * on the `chant/lifecycle` orphan branch (one file per lexicon, read via
+ * `readSnapshot`/`readEnvironmentSnapshots`, ../lifecycle/git.ts), replayed
+ * exactly as `chant lifecycle plan` reads its own prior snapshot.
+ */
+export interface ScenarioGivenEnv {
+  readonly kind: "env";
+  /** Environment name, matching a `chant.config.ts` `environments` entry. */
+  readonly env: string;
+}
+
+/** What a scenario's `given` stands in for — a fixture file or a recorded environment. */
+export type ScenarioGiven = ScenarioGivenFile | ScenarioGivenEnv;
+
+/**
+ * Declare `given` from a single string. Pure and offline: no filesystem
+ * access, no git — the factory only classifies the string's SHAPE, never
+ * checks whether it exists. That is what keeps `Scenario` foldable under
+ * `--sandbox`, the same discipline `declareSecret`'s committed-encrypted path
+ * validation follows (../secret-provenance.ts).
+ *
+ * The classification is structural: a string containing a path separator or
+ * ending in `.json` is a fixture file; anything else (a bare token like
+ * `"prod"`) is an environment name. A `chant.config.ts` environment name that
+ * happens to contain a slash or end in `.json` is not supported by this
+ * heuristic — pass `{ kind: "env", env }` directly in that unlikely case.
+ */
+export function snapshot(source: string): ScenarioGiven {
+  if (typeof source !== "string" || source.length === 0) {
+    throw new Error("snapshot: `source` must be a non-empty string");
+  }
+  const looksLikeFile = source.includes("/") || source.includes("\\") || source.toLowerCase().endsWith(".json");
+  return looksLikeFile ? { kind: "file", path: source } : { kind: "env", env: source };
+}
+
+/** One named delete an `expect.deletes` clause requires — the resource must
+ * be proposed for deletion, and with exactly this ownership verdict. */
+export interface ScenarioDeleteExpectation {
+  /** The change-set entry name (ChangeSetEntry.name) expected to delete. */
+  readonly name: string;
+  /** The ownership verdict (./change-set.ts's `Ownership`) the delete must carry. */
+  readonly ownership: Ownership;
+}
+
+/**
+ * How a scenario treats the change set's `unobserved` rows (#1089):
+ *
+ * - `"refuse"` — any unobserved entry fails the scenario. The plan admitting
+ *   a hole is never a pass, the same fail-closed instinct
+ *   `evaluateUnobservedGate`'s default takes (./unobserved-gate.ts).
+ * - `{ allow: [names] }` — the named entities may be unobserved without
+ *   failing the scenario; any unobserved entity NOT in the list still fails
+ *   it. Unlike `evaluateUnobservedGate`'s policy (which allows by *reason*),
+ *   this allows by entity *name* — the natural unit for a scenario written
+ *   against one fixture, where "this specific resource has no binding in the
+ *   fixture" is a known, accepted gap rather than a class of reason to trust
+ *   everywhere.
+ */
+export type ScenarioUnobservedPolicy = "refuse" | { readonly allow: readonly string[] };
+
+/**
+ * The assertion vocabulary (#1292 research, settled shape). Every clause is
+ * independently optional and clauses compose within one `expect` object — a
+ * scenario can assert `noop`, exact counts, specific named deletes, and an
+ * unobserved policy together. At least one clause must be present; an empty
+ * `expect` asserts nothing and is refused as a likely mistake.
+ */
+export interface ScenarioExpect {
+  /** The plan proposes no create, update, or delete, and no declared effect
+   * receipt (#1832) fires — the majority-value case (refactors, upgrades,
+   * no-op deploys). Equivalent to `{ create: 0, update: 0, delete: 0 }` plus
+   * "no receipt classifies as `effect`", but reads as the specific claim it
+   * is: a pending effect fire is a real proposed action even though it never
+   * joins the create/update/delete triad. */
+  readonly noop?: true;
+  /** Exact count of `create` rows the plan must propose. Omitted = unconstrained. */
+  readonly create?: number;
+  /** Exact count of `update` rows the plan must propose. Omitted = unconstrained. */
+  readonly update?: number;
+  /** Exact count of `delete` rows the plan must propose. Omitted = unconstrained. */
+  readonly delete?: number;
+  /** Exactly these resources must delete, each with the stated ownership —
+   * and no OTHER delete may be proposed. The highest-value assertion in the
+   * vocabulary: "this plan deletes nothing foreign", made precise per-name. */
+  readonly deletes?: readonly ScenarioDeleteExpectation[];
+  /** How the scenario treats unobserved rows. Omitted = unconstrained (an
+   * unobserved entity neither passes nor fails the scenario on its own). */
+  readonly unobserved?: ScenarioUnobservedPolicy;
+}
+
+/** Every recognized `expect` clause key — for the excess-key check below and
+ * for exhaustiveness at call sites. */
+const EXPECT_KEYS = ["noop", "create", "update", "delete", "deletes", "unobserved"] as const;
+
+const OWNERSHIP_VALUES: readonly Ownership[] = ["owned", "foreign", "unknown"];
+
+/**
+ * A scenario declaration — a Declarable, so discovery collects it and `chant
+ * list` shows it, but it carries no resource payload: `partitionByLexicon`
+ * (../build.ts) excludes it from every serializer partition, so no lexicon
+ * ever emits it and no apply-bound document ever contains one.
+ */
+export interface ScenarioDeclaration extends Declarable {
+  readonly [SCENARIO_MARKER]: true;
+  readonly lexicon: "chant";
+  readonly entityType: typeof SCENARIO_ENTITY_TYPE;
+  /** The scenario's own name — what `chant scenario check` reports pass/fail against. */
+  readonly name: string;
+  readonly given: ScenarioGiven;
+  readonly expect: ScenarioExpect;
+}
+
+/** Factory options for {@link Scenario}. */
+export interface ScenarioOptions {
+  /** What stands in for live observation — a fixture file or a recorded environment. */
+  readonly given: ScenarioGiven;
+  /** The claim about the resulting change set. At least one clause required. */
+  readonly expect: ScenarioExpect;
+}
+
+/**
+ * Declare a plan scenario. The returned object is a locked Declarable:
+ * declared fields are immutable and nested structures are frozen, the same
+ * shape ../effect-receipt.ts and ../secret-provenance.ts lock down; the
+ * top-level object stays extensible so discovery can still stamp its own
+ * symbol-keyed metadata.
+ */
+export function Scenario(name: string, options: ScenarioOptions): ScenarioDeclaration {
+  if (typeof name !== "string" || name.length === 0) {
+    throw new Error("Scenario: `name` must be a non-empty string");
+  }
+  const given = validateGiven(name, options?.given);
+  const expect = validateExpect(name, options?.expect);
+
+  const decl: ScenarioDeclaration = {
+    [DECLARABLE_MARKER]: true,
+    [SCENARIO_MARKER]: true,
+    lexicon: "chant",
+    entityType: SCENARIO_ENTITY_TYPE,
+    name,
+    given,
+    expect,
+  };
+  for (const key of Object.keys(decl)) {
+    Object.defineProperty(decl, key, { writable: false, configurable: false });
+  }
+  return decl;
+}
+
+function validateGiven(name: string, given: unknown): ScenarioGiven {
+  if (typeof given !== "object" || given === null) {
+    throw new Error(`Scenario("${name}"): \`given\` is required — use snapshot(path) or snapshot(env)`);
+  }
+  const g = given as Partial<ScenarioGiven>;
+  if (g.kind === "file") {
+    if (typeof g.path !== "string" || g.path.length === 0) {
+      throw new Error(`Scenario("${name}"): \`given\` of kind "file" requires a non-empty \`path\``);
+    }
+    return Object.freeze({ kind: "file", path: g.path });
+  }
+  if (g.kind === "env") {
+    if (typeof g.env !== "string" || g.env.length === 0) {
+      throw new Error(`Scenario("${name}"): \`given\` of kind "env" requires a non-empty \`env\``);
+    }
+    return Object.freeze({ kind: "env", env: g.env });
+  }
+  throw new Error(
+    `Scenario("${name}"): \`given\` must come from snapshot(path) or snapshot(env), got kind "${String((g as { kind?: unknown }).kind)}"`,
+  );
+}
+
+function validateExpect(name: string, expect: unknown): ScenarioExpect {
+  if (typeof expect !== "object" || expect === null || Array.isArray(expect)) {
+    throw new Error(`Scenario("${name}"): \`expect\` must be a plain object`);
+  }
+  const e = expect as Record<string, unknown>;
+  for (const key of Object.keys(e)) {
+    if (!(EXPECT_KEYS as readonly string[]).includes(key)) {
+      throw new Error(
+        `Scenario("${name}"): unknown \`expect\` clause "${key}" — expected one of ${EXPECT_KEYS.join(", ")}`,
+      );
+    }
+  }
+  if (Object.keys(e).length === 0) {
+    throw new Error(
+      `Scenario("${name}"): \`expect\` must include at least one clause (${EXPECT_KEYS.join(", ")}) — an empty expect asserts nothing`,
+    );
+  }
+
+  const out: Record<string, unknown> = {};
+
+  if ("noop" in e) {
+    if (e.noop !== true) {
+      throw new Error(`Scenario("${name}"): \`expect.noop\`, when present, must be exactly \`true\``);
+    }
+    out.noop = true;
+  }
+  for (const countKey of ["create", "update", "delete"] as const) {
+    if (countKey in e) {
+      const v = e[countKey];
+      if (typeof v !== "number" || !Number.isInteger(v) || v < 0) {
+        throw new Error(`Scenario("${name}"): \`expect.${countKey}\`, when present, must be a non-negative integer`);
+      }
+      out[countKey] = v;
+    }
+  }
+  if ("deletes" in e) {
+    if (!Array.isArray(e.deletes)) {
+      throw new Error(`Scenario("${name}"): \`expect.deletes\` must be an array`);
+    }
+    out.deletes = Object.freeze(
+      e.deletes.map((d, i) => {
+        if (typeof d !== "object" || d === null) {
+          throw new Error(`Scenario("${name}"): \`expect.deletes[${i}]\` must be an object`);
+        }
+        const { name: deleteName, ownership } = d as Record<string, unknown>;
+        if (typeof deleteName !== "string" || deleteName.length === 0) {
+          throw new Error(`Scenario("${name}"): \`expect.deletes[${i}].name\` must be a non-empty string`);
+        }
+        if (!(OWNERSHIP_VALUES as readonly unknown[]).includes(ownership)) {
+          throw new Error(
+            `Scenario("${name}"): \`expect.deletes[${i}].ownership\` must be one of ${OWNERSHIP_VALUES.join(", ")}`,
+          );
+        }
+        return Object.freeze({ name: deleteName, ownership: ownership as Ownership });
+      }),
+    );
+  }
+  if ("unobserved" in e) {
+    const u = e.unobserved;
+    if (u === "refuse") {
+      out.unobserved = "refuse";
+    } else if (typeof u === "object" && u !== null && Array.isArray((u as { allow?: unknown }).allow)) {
+      const allow = (u as { allow: unknown[] }).allow;
+      allow.forEach((entry, i) => {
+        if (typeof entry !== "string" || entry.length === 0) {
+          throw new Error(`Scenario("${name}"): \`expect.unobserved.allow[${i}]\` must be a non-empty string`);
+        }
+      });
+      out.unobserved = Object.freeze({ allow: Object.freeze([...allow]) });
+    } else {
+      throw new Error(
+        `Scenario("${name}"): \`expect.unobserved\` must be "refuse" or { allow: [names] }`,
+      );
+    }
+  }
+
+  return Object.freeze(out) as ScenarioExpect;
+}
+
+/** Type guard for a scenario declaration. */
+export function isScenario(value: unknown): value is ScenarioDeclaration {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    SCENARIO_MARKER in value &&
+    (value as Record<symbol, unknown>)[SCENARIO_MARKER] === true
+  );
+}
+
+/**
+ * Extract the scenario declarations from a discovered entity map — the read
+ * surface `chant scenario check` (../cli/handlers/scenario.ts) uses. Keyed by
+ * entity name (export name), the same key `DiscoveryResult.entities` uses.
+ */
+export function collectScenarios(entities: ReadonlyMap<string, Declarable>): Map<string, ScenarioDeclaration> {
+  const out = new Map<string, ScenarioDeclaration>();
+  for (const [name, entity] of entities) {
+    if (isScenario(entity)) out.set(name, entity);
+  }
+  return out;
+}

package/src/lifecycle/symptoms.test.ts

@@ -0,0 +1,116 @@
+import { describe, test, expect } from "vitest";
+import { deriveSymptoms, worstStatus, CONVERGE_SYMPTOM_FIELDS } from "./symptoms";
+import type { ChangeSet, ChangeSetEntry } from "./change-set";
+import type { ComponentStatusRow } from "./status";
+
+function entry(overrides: Partial<ChangeSetEntry> & Pick<ChangeSetEntry, "name" | "action">): ChangeSetEntry {
+  return {
+    ownership: "unknown",
+    evidence: { declared: true, inSnapshot: true, live: true, observed: true },
+    ...overrides,
+  };
+}
+
+function statusRow(component: string, reconciliation: ComponentStatusRow["reconciliation"]): ComponentStatusRow {
+  return { component, env: "staging", reconciliation, detail: "test fixture" };
+}
+
+describe("worstStatus", () => {
+  test("reconciled for no rows", () => {
+    expect(worstStatus([])).toBe("reconciled");
+  });
+
+  test("unknown outranks everything else", () => {
+    const rows = [statusRow("a", "reconciled"), statusRow("b", "drifted"), statusRow("c", "unknown")];
+    expect(worstStatus(rows)).toBe("unknown");
+  });
+
+  test("drifted outranks stale and unrecorded", () => {
+    const rows = [statusRow("a", "stale"), statusRow("b", "unrecorded"), statusRow("c", "drifted")];
+    expect(worstStatus(rows)).toBe("drifted");
+  });
+
+  test("stale outranks unrecorded", () => {
+    expect(worstStatus([statusRow("a", "unrecorded"), statusRow("b", "stale")])).toBe("stale");
+  });
+
+  test("all reconciled -> reconciled", () => {
+    expect(worstStatus([statusRow("a", "reconciled"), statusRow("b", "reconciled")])).toBe("reconciled");
+  });
+});
+
+describe("deriveSymptoms", () => {
+  test("a quiet environment: no entries, all-reconciled rows", () => {
+    const cs: ChangeSet = { env: "staging", entries: [] };
+    const rows = [statusRow("a", "reconciled")];
+    const s = deriveSymptoms("staging", cs, rows);
+    expect(s.env).toBe("staging");
+    expect(s.status).toBe("reconciled");
+    expect(s.createCount).toBe(0);
+    expect(s.updateCount).toBe(0);
+    expect(s.deleteCount).toBe(0);
+    expect(s.adoptCount).toBe(0);
+    expect(s.unobservedCount).toBe(0);
+    expect(s.unobservedReasons).toEqual([]);
+    expect(s.totalCount).toBe(0);
+    expect(s.components).toEqual(rows);
+  });
+
+  test("counts change-set actions per type", () => {
+    const cs: ChangeSet = {
+      env: "staging",
+      entries: [
+        entry({ name: "a", action: "create" }),
+        entry({ name: "b", action: "update" }),
+        entry({ name: "c", action: "update" }),
+        entry({ name: "d", action: "delete", ownership: "owned" }),
+        entry({ name: "e", action: "adopt" }),
+        entry({ name: "f", action: "adopt" }),
+        entry({ name: "g", action: "runtime" }),
+        entry({ name: "h", action: "noop" }),
+      ],
+    };
+    const s = deriveSymptoms("staging", cs, [statusRow("x", "drifted")]);
+    expect(s.createCount).toBe(1);
+    expect(s.updateCount).toBe(2);
+    expect(s.deleteCount).toBe(1);
+    expect(s.adoptCount).toBe(2);
+    expect(s.runtimeCount).toBe(1);
+    expect(s.totalCount).toBe(8);
+    expect(s.status).toBe("drifted");
+  });
+
+  test("unobserved entries surface count and deduplicated, sorted reasons", () => {
+    const cs: ChangeSet = {
+      env: "staging",
+      entries: [
+        entry({ name: "a", action: "unobserved", unobservedReason: "no-credentials" }),
+        entry({ name: "b", action: "unobserved", unobservedReason: "read-failed" }),
+        entry({ name: "c", action: "unobserved", unobservedReason: "no-credentials" }),
+      ],
+    };
+    const s = deriveSymptoms("staging", cs, [statusRow("x", "unknown")]);
+    expect(s.unobservedCount).toBe(3);
+    expect(s.unobservedReasons).toHaveLength(2);
+    expect(s.unobservedReasons).toContain("no-credentials");
+    expect(s.unobservedReasons).toContain("read-failed");
+    expect(s.status).toBe("unknown");
+  });
+
+  test("adopt entries never affect status directly — reported via adoptCount only", () => {
+    const cs: ChangeSet = { env: "staging", entries: [entry({ name: "a", action: "adopt" })] };
+    const s = deriveSymptoms("staging", cs, [statusRow("x", "reconciled")]);
+    expect(s.adoptCount).toBe(1);
+    expect(s.status).toBe("reconciled");
+  });
+});
+
+describe("CONVERGE_SYMPTOM_FIELDS", () => {
+  test("names every field deriveSymptoms actually produces", () => {
+    const cs: ChangeSet = { env: "staging", entries: [] };
+    const s = deriveSymptoms("staging", cs, []);
+    for (const key of Object.keys(s)) {
+      expect(CONVERGE_SYMPTOM_FIELDS.has(key)).toBe(true);
+    }
+  });
+});

package/src/lifecycle/symptoms.ts

@@ -0,0 +1,126 @@
+/**
+ * Symptom derivation (#1484, epic #1487 feature 5) — one typed record joining
+ * the status join (./status.ts), change-set summaries (./change-set.ts), and
+ * unobserved evidence (../observation.ts) into the shape `ConvergeOp`'s rule
+ * table evaluates against.
+ *
+ * Derive-only, per the issue's leaning on its own open question 4: no new
+ * `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.
+ *
+ * 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
+ * over, and epic feature 5 calls it "one typed record" (singular). A
+ * multi-component environment still resolves to one record per tick —
+ * `components` carries the per-component detail behind the aggregate for
+ * reporting, and `status` is the worst verdict across all of them (see
+ * {@link worstStatus}), so "any component is unknown" is enough to trip
+ * `unknown never remediates` for the whole tick.
+ */
+import type { ChangeAction, ChangeSet } from "./change-set";
+import { summarize } from "./change-set";
+import type { ComponentStatusRow } from "./status";
+import { unobservedReasonText, type UnobservedReason } from "../observation";
+
+/**
+ * Verdict priority, most-cautious first: if anything is `unknown`, the tick
+ * as a whole must be treated as `unknown` — "unknown never remediates" is a
+ * whole-tick property, not a per-component one, since a rule table has no
+ * way to act on "some of the environment" only. `drifted` outranks `stale`/
+ * `unrecorded` because it is the actionable case ApplyOp's re-apply fixes;
+ * `reconciled` is the quiet-environment default.
+ */
+const STATUS_PRIORITY: readonly ComponentStatusRow["reconciliation"][] = [
+  "unknown",
+  "drifted",
+  "stale",
+  "unrecorded",
+  "reconciled",
+];
+
+/** The worst (most-cautious) reconciliation verdict across a set of component rows. `"reconciled"` for an empty set — nothing to converge is a quiet environment. */
+export function worstStatus(rows: ComponentStatusRow[]): ComponentStatusRow["reconciliation"] {
+  const present = new Set(rows.map((r) => r.reconciliation));
+  for (const candidate of STATUS_PRIORITY) {
+    if (present.has(candidate)) return candidate;
+  }
+  return "reconciled";
+}
+
+/**
+ * One tick's typed symptom record. Every field a `ConvergeOp` rule may
+ * reference — see `../op/converge-rule.ts`'s `SymptomPredicate<S>`, where
+ * `S` is this interface, so a rule whose predicate names a field outside
+ * this shape fails TypeScript at the author's call site (the "symptom field
+ * nothing produces" build-time refusal).
+ */
+export interface ConvergeSymptom {
+  env: string;
+  /** The worst reconciliation verdict across every component row this tick observed (see {@link worstStatus}). */
+  status: ComponentStatusRow["reconciliation"];
+  /** Per-component detail behind `status`, for reporting — never read by a rule predicate directly (rules read the flat counts below). */
+  components: ComponentStatusRow[];
+  /** Change-set action counts for the tick (./change-set.ts's `summarize`). */
+  createCount: number;
+  updateCount: number;
+  deleteCount: number;
+  /** Live but undeclared, ownership unestablished — a candidate to adopt into source. Never auto-claimed; see the issue's "adopt is reported, never auto-claimed" honesty requirement. */
+  adoptCount: number;
+  runtimeCount: number;
+  effectCount: number;
+  /** Declared, but the lexicon could not observe it (#1089) — the count backing `status: "unknown"`. */
+  unobservedCount: number;
+  /** Every distinct reason behind `unobservedCount`, for a report action's detail. */
+  unobservedReasons: UnobservedReason[];
+  /** Total resource count under change-set evidence for this tick (sum of the six counts above). */
+  totalCount: number;
+}
+
+/**
+ * Join a `ChangeSet` and `ComponentStatusRow[]` for one tick into a
+ * `ConvergeSymptom`. Pure — no I/O.
+ */
+export function deriveSymptoms(env: string, cs: ChangeSet, statusRows: ComponentStatusRow[]): ConvergeSymptom {
+  const counts: Record<ChangeAction, number> = summarize(cs);
+  const unobservedReasons = [
+    ...new Set(
+      cs.entries
+        .filter((e): e is typeof e & { unobservedReason: UnobservedReason } => e.action === "unobserved" && e.unobservedReason !== undefined)
+        .map((e) => e.unobservedReason),
+    ),
+  ].sort((a, b) => unobservedReasonText(a).localeCompare(unobservedReasonText(b)));
+
+  return {
+    env,
+    status: worstStatus(statusRows),
+    components: statusRows,
+    createCount: counts.create,
+    updateCount: counts.update,
+    deleteCount: counts.delete,
+    adoptCount: counts.adopt,
+    runtimeCount: counts.runtime,
+    effectCount: counts.effect,
+    unobservedCount: counts.unobserved,
+    unobservedReasons,
+    totalCount: cs.entries.length,
+  };
+}
+
+/** 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). */
+export const CONVERGE_SYMPTOM_FIELDS: ReadonlySet<string> = new Set([
+  "env",
+  "status",
+  "components",
+  "createCount",
+  "updateCount",
+  "deleteCount",
+  "adoptCount",
+  "runtimeCount",
+  "effectCount",
+  "unobservedCount",
+  "unobservedReasons",
+  "totalCount",
+]);

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;