@intentius/chant 0.45.0 → 0.49.0

package/src/lifecycle/observation-baseline.ts

@@ -37,6 +37,7 @@
 
 import { readBlobFromPath, writeBlobToPath } from "./git";
 import { sortedJsonReplacer } from "../utils";
+import { EFFECT_RECEIPT_ENTITY_TYPE } from "../effect-receipt";
 
 /** The file name under `<environment>/` on the orphan branch. */
 export const OBSERVATION_BASELINE_FILE = "observation-baseline.json";
@@ -140,19 +141,50 @@ export interface DeviationToAccept {
   note?: string;
 }
 
+/** Options for {@link acceptDeviations}. */
+export interface AcceptDeviationsOptions {
+  /** ISO timestamp to stamp instead of the wall clock (tests, replays). */
+  now?: string;
+  /**
+   * Entity names the caller recognized as effect receipts (#1833) — the
+   * marker-based read (`collectEffectReceipts`, ../effect-receipt.ts) over
+   * the build's entities, which is how a lexicon-materialized receipt row is
+   * caught even though its `entityType` is the row's own. Core-typed
+   * receipts are refused regardless, via {@link DeviationToAccept.type}.
+   */
+  receipts?: ReadonlySet<string>;
+}
+
 /**
  * Record deviations as accepted, returning a new baseline (the input is not
  * mutated). An existing acceptance for the same entity+path is replaced — that
  * is how re-accepting after a deliberate change works, and it keeps the file
  * from growing a second entry for every value a path has ever held.
+ *
+ * REFUSES a deviation on an effect receipt (#1833, epic #1703), throwing
+ * before anything is recorded: a receipt is the declared witness that its
+ * effect ran, and the `effect()` step is its only writer — baselining a
+ * receipt's live value would accept "the effect never fired" as the new
+ * normal and silently defuse the effect. The whole acceptance aborts, not
+ * just the receipt's row, so a partial baseline never lands.
  */
 export function acceptDeviations(
   baseline: ObservationBaseline,
   lexicon: string,
   deviations: readonly DeviationToAccept[],
-  opts?: { now?: string },
+  opts?: AcceptDeviationsOptions,
 ): ObservationBaseline {
   if (deviations.length === 0) return baseline;
+  for (const dev of deviations) {
+    if (dev.type === EFFECT_RECEIPT_ENTITY_TYPE || opts?.receipts?.has(dev.entity)) {
+      throw new Error(
+        `cannot accept drift on effect receipt "${dev.entity}" (path ${dev.path}): ` +
+          `the effect() step is the receipt's only writer — accepting the live value would ` +
+          `silently defuse the effect. Re-run the effect (or change its inputs) instead of ` +
+          `baselining the receipt.`,
+      );
+    }
+  }
   const now = opts?.now ?? new Date().toISOString();
   const lexicons: Record<string, BaselineLexicon> = { ...baseline.lexicons };
   const entities: BaselineLexicon = { ...(lexicons[lexicon] ?? {}) };

package/src/lifecycle/receipt-plan.test.ts

@@ -0,0 +1,250 @@
+import { describe, it, expect } from "vitest";
+import {
+  planReceipts,
+  mergeReceiptEntries,
+  observedValueResolver,
+  readReceiptValue,
+  type ReceiptReading,
+} from "./receipt-plan";
+import { buildChangeSet, renderChangeSet, summarize, type ChangeSet } from "./change-set";
+import {
+  EffectReceipt,
+  EXISTENCE_EXPECTATION,
+  receiptExpectation,
+  resolveReceiptExpectation,
+  collectEffectReceipts,
+  type EffectReceiptDeclaration,
+} from "../effect-receipt";
+import { AttrRef } from "../attrref";
+import type { ResourceMetadata } from "../lexicon";
+import type { ReceiptInputResolver } from "../effect-receipt";
+
+const noRefs: ReceiptInputResolver = (_ref, path) => {
+  throw new Error(`unexpected reference at ${path}`);
+};
+
+function receiptsOf(...decls: Array<[string, EffectReceiptDeclaration]>): Map<string, EffectReceiptDeclaration> {
+  return new Map(decls);
+}
+
+describe("planReceipts", () => {
+  it("absent receipt proposes the fire", () => {
+    const r = EffectReceipt("dbMigrated", { effect: "db-migrate", flavor: "existence" });
+    const readings = new Map<string, ReceiptReading>([
+      ["dbMigrated", { observed: true, present: false, lexicon: "aws" }],
+    ]);
+
+    const entries = planReceipts(receiptsOf(["dbMigrated", r]), readings, noRefs);
+
+    expect(entries).toHaveLength(1);
+    expect(entries[0].action).toBe("effect");
+    expect(entries[0].effect).toBe("db-migrate");
+    expect(entries[0].effectReason).toBe("receipt-absent");
+    expect(entries[0].evidence).toEqual({ declared: true, inSnapshot: false, live: false, observed: true });
+  });
+
+  it("stale hash proposes the fire, with both values in the detail", () => {
+    const r = EffectReceipt("seeded", { effect: "seed", flavor: "hash", inputs: { rows: 10 } });
+    const expected = receiptExpectation(r);
+    const readings = new Map<string, ReceiptReading>([
+      ["seeded", { observed: true, present: true, value: "sha256:0000", lexicon: "aws" }],
+    ]);
+
+    const entries = planReceipts(receiptsOf(["seeded", r]), readings, noRefs);
+
+    expect(entries[0].action).toBe("effect");
+    expect(entries[0].effectReason).toBe("receipt-stale");
+    expect(entries[0].effectDetail).toContain("sha256:0000");
+    expect(entries[0].effectDetail).toContain(expected);
+  });
+
+  it("matching receipt is a clean noop", () => {
+    const r = EffectReceipt("seeded", { effect: "seed", flavor: "hash", inputs: { rows: 10 } });
+    const readings = new Map<string, ReceiptReading>([
+      ["seeded", { observed: true, present: true, value: receiptExpectation(r), lexicon: "aws" }],
+    ]);
+
+    const entries = planReceipts(receiptsOf(["seeded", r]), readings, noRefs);
+
+    expect(entries[0].action).toBe("noop");
+    expect(entries[0].effect).toBe("seed");
+  });
+
+  it("matching existence receipt is a clean noop", () => {
+    const r = EffectReceipt("bootstrapped", { effect: "bootstrap", flavor: "existence" });
+    const readings = new Map<string, ReceiptReading>([
+      ["bootstrapped", { observed: true, present: true, value: EXISTENCE_EXPECTATION }],
+    ]);
+
+    expect(planReceipts(receiptsOf(["bootstrapped", r]), readings, noRefs)[0].action).toBe("noop");
+  });
+
+  it("a lexicon that could not look yields unobserved with its reason, never a clean row", () => {
+    const r = EffectReceipt("dbMigrated", { effect: "db-migrate", flavor: "existence" });
+    const readings = new Map<string, ReceiptReading>([
+      ["dbMigrated", { observed: false, present: false, unobservedReason: "no-credentials", unobservedDetail: "no AWS credentials" }],
+    ]);
+
+    const entries = planReceipts(receiptsOf(["dbMigrated", r]), readings, noRefs);
+
+    expect(entries[0].action).toBe("unobserved");
+    expect(entries[0].unobservedReason).toBe("no-credentials");
+    expect(entries[0].unobservedDetail).toBe("no AWS credentials");
+  });
+
+  it("a receipt no lexicon observes yields unobserved, loudly, never silently clean", () => {
+    const r = EffectReceipt("dbMigrated", { effect: "db-migrate", flavor: "existence" });
+
+    const entries = planReceipts(receiptsOf(["dbMigrated", r]), new Map(), noRefs);
+
+    expect(entries[0].action).toBe("unobserved");
+    expect(entries[0].unobservedReason).toBe("unsupported-kind");
+    expect(entries[0].unobservedDetail).toContain("db-migrate");
+    expect(entries[0].unobservedDetail).toContain("unknown, not clean");
+  });
+
+  it("a reference that cannot resolve at plan time proposes the fire with an unresolved-input note", () => {
+    const parent = { entityType: "Test::Db" };
+    const ref = new AttrRef(parent, "endpoint");
+    ref._setLogicalName("db");
+    const r = EffectReceipt("seeded", { effect: "seed", flavor: "hash", inputs: { endpoint: ref } });
+    const readings = new Map<string, ReceiptReading>([
+      ["seeded", { observed: true, present: true, value: "sha256:live" }],
+    ]);
+
+    // Resolver over observed values that do NOT include db.endpoint.
+    const entries = planReceipts(receiptsOf(["seeded", r]), readings, observedValueResolver({}));
+
+    expect(entries[0].action).toBe("effect");
+    expect(entries[0].effectReason).toBe("unresolved-input");
+    expect(entries[0].effectDetail).toContain("unresolved input");
+    expect(entries[0].effectDetail).toContain("db.endpoint");
+  });
+
+  it("a reference input resolves against observed values and the comparison uses the resolved digest", () => {
+    const parent = { entityType: "Test::Db" };
+    const ref = new AttrRef(parent, "endpoint");
+    ref._setLogicalName("db");
+    const r = EffectReceipt("seeded", { effect: "seed", flavor: "hash", inputs: { endpoint: ref } });
+
+    const observed: Record<string, ResourceMetadata> = {
+      db: { type: "Test::Db", status: "ok", attributes: { endpoint: "db.example.internal:5432" } },
+    };
+    const resolver = observedValueResolver(observed);
+    const expected = resolveReceiptExpectation(r, resolver);
+    const readings = new Map<string, ReceiptReading>([
+      ["seeded", { observed: true, present: true, value: expected }],
+    ]);
+
+    expect(planReceipts(receiptsOf(["seeded", r]), readings, resolver)[0].action).toBe("noop");
+  });
+
+  it("crash between effect and receipt write: the stale receipt re-proposes the fire on the next plan", () => {
+    // Run 1 wrote the receipt for inputs { schema: 1 }. The effect for
+    // { schema: 2 } ran, then the process died before the receipt write —
+    // the live value still carries run 1's digest.
+    const run1 = EffectReceipt("migrated", { effect: "migrate", flavor: "hash", inputs: { schema: 1 } });
+    const run2 = EffectReceipt("migrated", { effect: "migrate", flavor: "hash", inputs: { schema: 2 } });
+    const readings = new Map<string, ReceiptReading>([
+      ["migrated", { observed: true, present: true, value: receiptExpectation(run1) }],
+    ]);
+
+    const entries = planReceipts(receiptsOf(["migrated", run2]), readings, noRefs);
+
+    expect(entries[0].action).toBe("effect");
+    expect(entries[0].effectReason).toBe("receipt-stale");
+
+    // The first-run variant of the same crash: the effect ran, the write
+    // never happened, the receipt is absent — the fire is proposed again.
+    const absent = new Map<string, ReceiptReading>([["migrated", { observed: true, present: false }]]);
+    expect(planReceipts(receiptsOf(["migrated", run2]), absent, noRefs)[0].effectReason).toBe("receipt-absent");
+  });
+});
+
+describe("mergeReceiptEntries", () => {
+  it("replaces the generic create proposed for an absent receipt with the effect row", () => {
+    const r = EffectReceipt("dbMigrated", { effect: "db-migrate", flavor: "existence" });
+    const receipts = receiptsOf(["dbMigrated", r]);
+
+    // The generic classification knows nothing about receipts: declared and
+    // confirmed absent classifies as create.
+    const cs = buildChangeSet("prod", {
+      declared: new Set(["dbMigrated", "bucket"]),
+      observedNow: { bucket: { type: "Test::Bucket", status: "ok" } },
+      observedThen: undefined,
+    });
+    expect(cs.entries.find((e) => e.name === "dbMigrated")?.action).toBe("create");
+
+    const entries = planReceipts(receipts, new Map([["dbMigrated", { observed: true, present: false } as ReceiptReading]]), noRefs);
+    mergeReceiptEntries(cs, receipts, entries);
+
+    const row = cs.entries.filter((e) => e.name === "dbMigrated");
+    expect(row).toHaveLength(1);
+    expect(row[0].action).toBe("effect");
+    expect(summarize(cs).create).toBe(0);
+  });
+
+  it("a live receipt is never a prune candidate: the generic delete is replaced", () => {
+    const r = EffectReceipt("dbMigrated", { effect: "db-migrate", flavor: "existence" });
+    const receipts = receiptsOf(["dbMigrated", r]);
+
+    // Worst case for the write-exclusion: the receipt is live and owned but
+    // missing from the declared axis the change set saw (exactly what
+    // withholding it from the apply-bound set produces) — the generic
+    // classification proposes delete, the prune candidacy a receipt must
+    // never have.
+    const cs = buildChangeSet("prod", {
+      declared: new Set<string>(),
+      observedNow: {
+        dbMigrated: { type: "AWS::SSM::Parameter", status: "ok", ownership: "owned" },
+      },
+      observedThen: undefined,
+    });
+    expect(cs.entries.find((e) => e.name === "dbMigrated")?.action).toBe("delete");
+
+    const entries = planReceipts(
+      receipts,
+      new Map([["dbMigrated", { observed: true, present: true, value: EXISTENCE_EXPECTATION } as ReceiptReading]]),
+      noRefs,
+    );
+    mergeReceiptEntries(cs, receipts, entries);
+
+    expect(cs.entries.filter((e) => e.action === "delete")).toHaveLength(0);
+    expect(cs.entries.filter((e) => e.action === "adopt")).toHaveLength(0);
+    expect(cs.entries.find((e) => e.name === "dbMigrated")?.action).toBe("noop");
+  });
+});
+
+describe("renderChangeSet with effect entries", () => {
+  it('renders "effect will fire: <effect>"', () => {
+    const r = EffectReceipt("dbMigrated", { effect: "db-migrate", flavor: "existence" });
+    const cs: ChangeSet = { env: "prod", entries: [] };
+    mergeReceiptEntries(
+      cs,
+      receiptsOf(["dbMigrated", r]),
+      planReceipts(receiptsOf(["dbMigrated", r]), new Map([["dbMigrated", { observed: true, present: false } as ReceiptReading]]), noRefs),
+    );
+
+    const rendered = renderChangeSet(cs);
+    expect(rendered).toContain("effect will fire: db-migrate");
+    expect(rendered).toContain("1 effect");
+    expect(rendered).toContain("the generic apply never writes a receipt");
+  });
+});
+
+describe("readReceiptValue", () => {
+  it("reads value, falling back to the provider's Value casing", () => {
+    expect(readReceiptValue({ value: "a" })).toBe("a");
+    expect(readReceiptValue({ Value: "b" })).toBe("b");
+    expect(readReceiptValue({ value: "a", Value: "b" })).toBe("a");
+    expect(readReceiptValue(undefined)).toBeUndefined();
+  });
+});
+
+describe("collectEffectReceipts over a mixed entity map", () => {
+  it("finds only marker-carrying entities", () => {
+    const r = EffectReceipt("dbMigrated", { effect: "db-migrate", flavor: "existence" });
+    const entities = new Map<string, EffectReceiptDeclaration>([["dbMigrated", r]]);
+    expect([...collectEffectReceipts(entities).keys()]).toEqual(["dbMigrated"]);
+  });
+});

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. */