@intentius/chant 0.29.0 → 0.30.0

package/src/lifecycle/deep-observe.test.ts

@@ -0,0 +1,174 @@
+import { describe, test, expect, vi } from "vitest";
+import { deepDiffForLexicon, diffDeepObservation, mergeDeepObservations, observeDeep } from "./deep-observe";
+import { deepObservation, type DeepNormalizationHooks } from "../deep-observation";
+import type { ObservationLexicon } from "../lexicon";
+
+const entities = (
+  record: Record<string, { entityType: string; props: Record<string, unknown> }>,
+): Map<string, { entityType: string; props: Record<string, unknown> }> => new Map(Object.entries(record));
+
+/** Minimal plugin shell — only the observation surface matters here. */
+const pluginWith = (over: Partial<ObservationLexicon>): ObservationLexicon =>
+  ({ name: "test", serializer: {} , ...over } as unknown as ObservationLexicon);
+
+describe("observeDeep", () => {
+  test("a lexicon with no deep reader observes nothing and claims nothing", async () => {
+    const result = await observeDeep(pluginWith({}), {
+      environment: "prod",
+      buildOutput: "",
+      entities: entities({ a: { entityType: "T", props: {} } }),
+    });
+    expect(result).toEqual({ resources: {}, unobserved: {} });
+  });
+
+  test("a thrown reader becomes read-failed for every declared entity, never an empty tree", async () => {
+    const result = await observeDeep(
+      pluginWith({
+        observeResourcesDeep: () => Promise.reject(new Error("kubeconfig has no current context")),
+      }),
+      {
+        environment: "prod",
+        buildOutput: "",
+        entities: entities({ a: { entityType: "T", props: {} }, b: { entityType: "U", props: {} } }),
+      },
+    );
+    expect(result.resources).toEqual({});
+    expect(result.unobserved.a).toEqual({
+      type: "T",
+      reason: "read-failed",
+      detail: "kubeconfig has no current context",
+    });
+    expect(Object.keys(result.unobserved)).toEqual(["a", "b"]);
+  });
+
+  test("multi-stack reads merge with present beating not-observed", async () => {
+    const reader = vi.fn(async (opts: { stack?: string }) =>
+      opts.stack === "one"
+        ? deepObservation({}, { a: { reason: "read-failed", detail: "not in this stack" } })
+        : deepObservation({ a: { type: "T", properties: { A: 1 } } }),
+    );
+    const result = await observeDeep(pluginWith({ observeResourcesDeep: reader as never }), {
+      environment: "prod",
+      buildOutput: "",
+      entities: entities({ a: { entityType: "T", props: {} } }),
+      componentStacks: ["one", "two"],
+    });
+    expect(result.unobserved).toEqual({});
+    expect(result.resources.a.properties).toEqual({ A: 1 });
+  });
+
+  test("passes the declared entity names through to the reader", async () => {
+    const reader = vi.fn(async () => deepObservation({}));
+    await observeDeep(pluginWith({ observeResourcesDeep: reader as never }), {
+      environment: "prod",
+      buildOutput: "out",
+      entities: entities({ a: { entityType: "T", props: {} } }),
+      owned: true,
+    });
+    expect(reader).toHaveBeenCalledWith(
+      expect.objectContaining({ environment: "prod", buildOutput: "out", entityNames: ["a"], owned: true }),
+    );
+  });
+});
+
+describe("mergeDeepObservations", () => {
+  test("a resource found in any part is present everywhere", () => {
+    const merged = mergeDeepObservations([
+      { resources: {}, unobserved: { a: { reason: "read-failed" } } },
+      { resources: { a: { type: "T", properties: {} } }, unobserved: {} },
+    ]);
+    expect(merged.unobserved).toEqual({});
+    expect(Object.keys(merged.resources)).toEqual(["a"]);
+  });
+});
+
+describe("diffDeepObservation", () => {
+  const hooks: DeepNormalizationHooks = {
+    prune(node) {
+      // Server-populated everywhere.
+      if (node.pattern === "Arn") return true;
+      // A provider default, subtracted only where source is silent.
+      return node.side === "live" && node.counterpart === "absent" && node.pattern === "Path" && node.value === "/";
+    },
+  };
+
+  test("applies the lexicon's hooks to both sides", () => {
+    const result = diffDeepObservation(
+      entities({ r: { entityType: "AWS::IAM::Role", props: { Arn: "declared-arn", RoleName: "r" } } }),
+      {
+        resources: {
+          r: { type: "AWS::IAM::Role", properties: { Arn: "arn:aws:iam::1:role/r", RoleName: "r", Path: "/" } },
+        },
+        unobserved: {},
+      },
+      hooks,
+    );
+    // Arn pruned on both sides; Path subtracted as an undeclared default.
+    expect(result.drifted).toEqual([]);
+    expect(result.unchanged).toEqual(["r"]);
+  });
+
+  test("a declared property at its default is still compared", () => {
+    const result = diffDeepObservation(
+      entities({ r: { entityType: "AWS::IAM::Role", props: { Path: "/" } } }),
+      { resources: { r: { type: "AWS::IAM::Role", properties: { Path: "/team/" } } }, unobserved: {} },
+      hooks,
+    );
+    expect(result.drifted[0].changes).toEqual([
+      { path: "Path", kind: "changed", declared: "/", live: "/team/" },
+    ]);
+  });
+
+  test("unevaluated declared props never read as drift", () => {
+    class Sub {
+      constructor(readonly t: string) {}
+    }
+    const result = diffDeepObservation(
+      entities({ b: { entityType: "AWS::S3::Bucket", props: { BucketName: new Sub("${AWS::StackName}") } } }),
+      { resources: { b: { type: "AWS::S3::Bucket", properties: { BucketName: "prod-data" } } }, unobserved: {} },
+      hooks,
+    );
+    expect(result.drifted).toEqual([]);
+  });
+});
+
+describe("deepDiffForLexicon", () => {
+  test("an unreadable deep read surfaces as a hole with a reason, not as clean", async () => {
+    const result = await deepDiffForLexicon(
+      pluginWith({
+        observeResourcesDeep: async () =>
+          deepObservation({}, { a: { type: "T", reason: "no-credentials", detail: "token expired" } }),
+      }),
+      {
+        environment: "prod",
+        buildOutput: "",
+        entities: entities({ a: { entityType: "T", props: { A: 1 } } }),
+      },
+    );
+    expect(result.drifted).toEqual([]);
+    expect(result.unobserved).toEqual([
+      { name: "a", type: "T", reason: "no-credentials", detail: "token expired" },
+    ]);
+  });
+
+  test("subtracts the accepted baseline it is handed", async () => {
+    const plugin = pluginWith({
+      observeResourcesDeep: async () =>
+        deepObservation({ a: { type: "T", properties: { Extra: "accepted-value" } } }),
+    });
+    const opts = {
+      environment: "prod",
+      buildOutput: "",
+      entities: entities({ a: { entityType: "T", props: {} } }),
+    };
+    const withoutBaseline = await deepDiffForLexicon(plugin, opts);
+    expect(withoutBaseline.drifted[0].changes[0].path).toBe("Extra");
+
+    const withBaseline = await deepDiffForLexicon(plugin, {
+      ...opts,
+      baseline: { a: { accepted: [{ path: "Extra", value: "accepted-value" }] } },
+    });
+    expect(withBaseline.drifted).toEqual([]);
+    expect(withBaseline.accepted[0].changes[0].path).toBe("Extra");
+  });
+});

package/src/lifecycle/deep-observe.ts

@@ -0,0 +1,173 @@
+/**
+ * Deep observation orchestration (#1014) — call one lexicon's
+ * `observeResourcesDeep()`, put the declared trees in the same shape, and diff.
+ *
+ * The sibling of ./observe.ts on the thin path, and it inherits that path's
+ * rules: a reader that throws does not vanish, it reports every declared entity
+ * NOT-OBSERVED with `read-failed` (#1089); a multi-stack read merges with
+ * present > not-observed > absent. A deep read that fails is a hole with a
+ * reason, never a thin-but-clean answer.
+ *
+ * The normalization is applied here, on both sides, with the lexicon's own
+ * hooks. The reader already normalized what it returned — that is the contract
+ * — but only core can normalize the *declared* tree, and only core knows which
+ * paths exist on the other side, which is what
+ * {@link import("../deep-observation").DeepNode.counterpart} needs for default
+ * subtraction. Re-running the pass over an already-normalized live tree is
+ * idempotent for every hook that does not consult `counterpart`.
+ */
+
+import type { ObservationLexicon } from "../lexicon";
+import {
+  deepPathSet,
+  normalizeDeepObservation,
+  normalizeDeepProperties,
+  type DeepNormalizationHooks,
+  type DeepResourceObservation,
+  type NormalizedDeepObservation,
+} from "../deep-observation";
+import { unobservedAll, type UnobservedEntity } from "../observation";
+import { diffDeep, type DeclaredDeepEntity, type DeepDiffResult } from "./deep-diff";
+import type { BaselineLexicon } from "./observation-baseline";
+
+/** Declared entities for one lexicon, in the shape the observe paths pass around. */
+export type DeclaredEntities = Map<string, { entityType: string; props: Record<string, unknown> }>;
+
+export interface DeepObserveOptions {
+  environment: string;
+  buildOutput: string;
+  entities: DeclaredEntities;
+  /** Deployed stack for a multi-stack project (#932). */
+  stack?: string;
+  /** Component projects deploy one stack per component; read them all and merge. */
+  componentStacks?: string[];
+  owned?: boolean;
+}
+
+/**
+ * Merge several deep observations of the same lexicon (the multi-stack read).
+ * Precedence matches the thin contract: present > not-observed > absent.
+ */
+export function mergeDeepObservations(
+  parts: Iterable<NormalizedDeepObservation>,
+): NormalizedDeepObservation {
+  const resources: Record<string, DeepResourceObservation> = {};
+  const unobserved: Record<string, UnobservedEntity> = {};
+  for (const part of parts) {
+    Object.assign(resources, part.resources);
+    Object.assign(unobserved, part.unobserved);
+  }
+  for (const name of Object.keys(resources)) delete unobserved[name];
+  return { resources, unobserved };
+}
+
+/**
+ * Read one lexicon's live property trees. Never throws: a thrown reader becomes
+ * a NOT-OBSERVED verdict for every declared entity, with the error as the
+ * detail, so the caller sees a hole rather than an empty tree that reads as
+ * "no properties drifted".
+ */
+export async function observeDeep(
+  plugin: ObservationLexicon,
+  opts: DeepObserveOptions,
+): Promise<NormalizedDeepObservation> {
+  const entityNames = Array.from(opts.entities.keys());
+  if (!plugin.observeResourcesDeep) {
+    return { resources: {}, unobserved: {} };
+  }
+  const base = {
+    environment: opts.environment,
+    buildOutput: opts.buildOutput,
+    entityNames,
+    entities: opts.entities,
+    ...(opts.owned !== undefined ? { owned: opts.owned } : {}),
+  };
+  try {
+    if (opts.componentStacks && opts.componentStacks.length > 0) {
+      const parts: NormalizedDeepObservation[] = [];
+      for (const stack of opts.componentStacks) {
+        parts.push(normalizeDeepObservation(await plugin.observeResourcesDeep({ ...base, stack })));
+      }
+      return mergeDeepObservations(parts);
+    }
+    return normalizeDeepObservation(
+      await plugin.observeResourcesDeep({ ...base, ...(opts.stack ? { stack: opts.stack } : {}) }),
+    );
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      resources: {},
+      unobserved: unobservedAll(entityNames, "read-failed", message, opts.entities),
+    };
+  }
+}
+
+/**
+ * Normalize both sides into the same shape, then diff.
+ *
+ * Split out from {@link deepDiffForLexicon} so the pure half is testable
+ * without a plugin: given declared entities, a live observation and a baseline,
+ * this is a deterministic function.
+ */
+export function diffDeepObservation(
+  entities: DeclaredEntities,
+  live: NormalizedDeepObservation,
+  hooks?: DeepNormalizationHooks,
+  baseline?: BaselineLexicon,
+): DeepDiffResult {
+  const declared: Record<string, DeclaredDeepEntity> = {};
+  const normalizedLive: Record<string, DeepResourceObservation> = {};
+
+  for (const [name, entity] of entities) {
+    const liveEntity = live.resources[name];
+    const declaredRaw = entity.props ?? {};
+    const liveRaw = liveEntity?.properties ?? {};
+    const declaredPaths = deepPathSet(declaredRaw);
+    const livePaths = deepPathSet(liveRaw);
+
+    declared[name] = {
+      type: entity.entityType,
+      properties: normalizeDeepProperties(declaredRaw, {
+        entityType: entity.entityType,
+        side: "declared",
+        hooks,
+        counterpartPaths: livePaths,
+      }),
+    };
+    if (liveEntity) {
+      normalizedLive[name] = {
+        type: liveEntity.type || entity.entityType,
+        ...(liveEntity.physicalId ? { physicalId: liveEntity.physicalId } : {}),
+        properties: normalizeDeepProperties(liveRaw, {
+          entityType: liveEntity.type || entity.entityType,
+          side: "live",
+          hooks,
+          counterpartPaths: declaredPaths,
+        }),
+      };
+    }
+  }
+
+  // Live entities nobody declared keep their reader-normalized trees — there is
+  // no declared side to normalize them against, and `diffDeep` reports them as
+  // undeclared entities rather than diffing their properties.
+  for (const [name, liveEntity] of Object.entries(live.resources)) {
+    if (!normalizedLive[name]) normalizedLive[name] = liveEntity;
+  }
+
+  return diffDeep({
+    declared,
+    live: { resources: normalizedLive, unobserved: live.unobserved },
+    baseline,
+    hooks,
+  });
+}
+
+/** Read one lexicon deeply and diff it against source and the accepted baseline. */
+export async function deepDiffForLexicon(
+  plugin: ObservationLexicon,
+  opts: DeepObserveOptions & { baseline?: BaselineLexicon },
+): Promise<DeepDiffResult> {
+  const live = await observeDeep(plugin, opts);
+  return diffDeepObservation(opts.entities, live, plugin.deepNormalizationHooks, opts.baseline);
+}

package/src/lifecycle/index.ts

@@ -3,6 +3,9 @@ export * from "./git";
 export * from "./digest";
 export * from "./snapshot";
 export * from "./live-diff";
+export * from "./deep-diff";
+export * from "./deep-observe";
+export * from "./observation-baseline";
 export * from "./change-set";
 export * from "./affected";
 export * from "./release-ledger";

package/src/lifecycle/observation-baseline.test.ts

@@ -0,0 +1,99 @@
+import { describe, test, expect } from "vitest";
+import {
+  acceptDeviations,
+  acceptedDeviation,
+  baselineForLexicon,
+  countAccepted,
+  emptyBaseline,
+  isObservationBaseline,
+  parseBaseline,
+  serializeBaseline,
+} from "./observation-baseline";
+
+describe("the baseline document", () => {
+  test("round-trips through serialize/parse", () => {
+    const b = acceptDeviations(emptyBaseline("prod"), "aws", [
+      { entity: "Assets", type: "AWS::S3::Bucket", path: "Tags[0].Value", value: "platform", note: "org policy" },
+    ], { now: "2026-07-27T00:00:00.000Z" });
+    const parsed = parseBaseline(serializeBaseline(b));
+    expect(parsed).toEqual(b);
+  });
+
+  test("serializes with sorted keys and a trailing newline, so the commit diff reads cleanly", () => {
+    const json = serializeBaseline(emptyBaseline("prod"));
+    expect(json.endsWith("\n")).toBe(true);
+    expect(JSON.parse(json)).toEqual({ baseline: "v1", environment: "prod", lexicons: {} });
+  });
+
+  test("refuses to read anything that is not a versioned baseline", () => {
+    expect(parseBaseline(null)).toBeNull();
+    expect(parseBaseline("")).toBeNull();
+    expect(parseBaseline("{ not json")).toBeNull();
+    expect(parseBaseline('{"baseline":"v2","lexicons":{}}')).toBeNull();
+    expect(parseBaseline('{"lexicons":{}}')).toBeNull();
+    expect(isObservationBaseline({ baseline: "v1", lexicons: {} })).toBe(true);
+  });
+});
+
+describe("acceptDeviations", () => {
+  const now = "2026-07-27T00:00:00.000Z";
+
+  test("records a deviation bound to the value that was accepted", () => {
+    const b = acceptDeviations(emptyBaseline("prod"), "aws", [
+      { entity: "Role", type: "AWS::IAM::Role", path: "MaxSessionDuration", value: 7200 },
+    ], { now });
+    expect(baselineForLexicon(b, "aws")).toEqual({
+      Role: {
+        type: "AWS::IAM::Role",
+        accepted: [{ path: "MaxSessionDuration", value: 7200, recordedAt: now }],
+      },
+    });
+    expect(b.updated).toBe(now);
+  });
+
+  test("does not mutate the input", () => {
+    const before = emptyBaseline("prod");
+    acceptDeviations(before, "aws", [{ entity: "R", path: "A", value: 1 }], { now });
+    expect(before.lexicons).toEqual({});
+  });
+
+  test("re-accepting the same path replaces the entry rather than appending a second", () => {
+    let b = acceptDeviations(emptyBaseline("prod"), "aws", [{ entity: "R", path: "A", value: 1 }], { now });
+    b = acceptDeviations(b, "aws", [{ entity: "R", path: "A", value: 2 }], { now });
+    expect(baselineForLexicon(b, "aws").R.accepted).toEqual([{ path: "A", value: 2, recordedAt: now }]);
+  });
+
+  test("keeps deviations from other entities and other lexicons", () => {
+    let b = acceptDeviations(emptyBaseline("prod"), "aws", [{ entity: "R1", path: "A", value: 1 }], { now });
+    b = acceptDeviations(b, "aws", [{ entity: "R2", path: "B", value: 2 }], { now });
+    b = acceptDeviations(b, "k8s", [{ entity: "D", path: "spec.replicas", value: 3 }], { now });
+    expect(Object.keys(baselineForLexicon(b, "aws")).sort()).toEqual(["R1", "R2"]);
+    expect(countAccepted(b)).toBe(3);
+  });
+
+  test("accepted paths sort, so the committed file is stable across runs", () => {
+    const b = acceptDeviations(emptyBaseline("prod"), "aws", [
+      { entity: "R", path: "Z", value: 1 },
+      { entity: "R", path: "A", value: 2 },
+    ], { now });
+    expect(baselineForLexicon(b, "aws").R.accepted.map((a) => a.path)).toEqual(["A", "Z"]);
+  });
+
+  test("an empty accept list is a no-op", () => {
+    const b = emptyBaseline("prod");
+    expect(acceptDeviations(b, "aws", [])).toBe(b);
+  });
+
+  test("lookup is by entity and path", () => {
+    const b = acceptDeviations(emptyBaseline("prod"), "aws", [{ entity: "R", path: "A", value: 1 }], { now });
+    const lex = baselineForLexicon(b, "aws");
+    expect(acceptedDeviation(lex, "R", "A")?.value).toBe(1);
+    expect(acceptedDeviation(lex, "R", "B")).toBeUndefined();
+    expect(acceptedDeviation(lex, "Other", "A")).toBeUndefined();
+  });
+
+  test("a missing baseline reads as nothing accepted", () => {
+    expect(baselineForLexicon(null, "aws")).toEqual({});
+    expect(countAccepted(null)).toBe(0);
+  });
+});

package/src/lifecycle/observation-baseline.ts

@@ -0,0 +1,217 @@
+/**
+ * The accepted-observation baseline (#1014) — a committed record of deviations
+ * somebody looked at and accepted, so they stop re-alerting.
+ *
+ * Deep observation reports every property that differs between source and
+ * cloud, including properties nobody ever declared. Some of those are real
+ * findings. Many are permanent facts of the account — a platform team's
+ * mandatory tag, a bucket setting an org policy flips on, a role an operator
+ * attached by hand and everyone agreed to keep. Without somewhere to record
+ * "yes, we know, leave it", a deep diff is a report nobody reads twice.
+ *
+ * The model is cdk-real-drift's `.cdkrd`: a snapshot of accepted *undeclared*
+ * values that the diff subtracts. Accepting is an explicit act with a git
+ * commit behind it, and the acceptance is value-bound — accept
+ * `VersioningConfiguration.Status = Enabled` and a later change to `Suspended`
+ * is drift again, because what was accepted was that value, not that path.
+ *
+ * ## What this is not
+ *
+ * Not state. The baseline never tells a deploy what to do and is never read on
+ * the write path; deleting it costs you noise suppression and nothing else.
+ * Which is also why it is safe for it to be incomplete or stale.
+ *
+ * ## Where it lives
+ *
+ * `<environment>/observation-baseline.json` on the `chant/lifecycle` orphan
+ * branch — the epic's named candidate home, and the same storage the snapshots
+ * (`<env>/<lexicon>.json`), the release ledger (`<env>/releases.jsonl`) and the
+ * build archive (`_builds/<digest>.json`) already use, through the same
+ * `writeBlobToPath`/`readBlobFromPath` plumbing. One env-keyed namespace for
+ * everything chant records *about* an environment rather than *for* it.
+ *
+ * The parse/serialize/update half below is pure and storage-free, so the
+ * decision is one function call deep if a repo-committed file (`.chant/`) turns
+ * out to be the better review surface.
+ */
+
+import { readBlobFromPath, writeBlobToPath } from "./git";
+import { sortedJsonReplacer } from "../utils";
+
+/** The file name under `<environment>/` on the orphan branch. */
+export const OBSERVATION_BASELINE_FILE = "observation-baseline.json";
+
+/** One deviation somebody accepted, bound to the value they accepted. */
+export interface AcceptedDeviation {
+  /** Property path within the entity's normalized tree (`Tags[0].Value`, `Policy.Statement[1].Effect`). */
+  path: string;
+  /** The live value at the moment of acceptance. A different live value later is drift again. */
+  value: unknown;
+  /** Free-text justification, written by whoever accepted it. */
+  note?: string;
+  /** ISO timestamp of acceptance. */
+  recordedAt?: string;
+}
+
+/** Every accepted deviation for one declared entity. */
+export interface BaselineEntity {
+  /** Entity type at acceptance time, for readability in the committed file. */
+  type?: string;
+  accepted: AcceptedDeviation[];
+}
+
+/** Accepted deviations for one lexicon, keyed by chant entity name. */
+export type BaselineLexicon = Record<string, BaselineEntity>;
+
+/** The committed baseline document for one environment. */
+export interface ObservationBaseline {
+  /** Discriminant + wire version. */
+  readonly baseline: "v1";
+  environment: string;
+  /** ISO timestamp of the last `--update-baseline`. */
+  updated?: string;
+  /** lexicon → entity → accepted deviations. */
+  lexicons: Record<string, BaselineLexicon>;
+}
+
+/** An environment with nothing accepted yet. */
+export function emptyBaseline(environment: string): ObservationBaseline {
+  return { baseline: "v1", environment, lexicons: {} };
+}
+
+/** True when `value` is a well-formed {@link ObservationBaseline}. */
+export function isObservationBaseline(value: unknown): value is ObservationBaseline {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as { baseline?: unknown }).baseline === "v1" &&
+    typeof (value as { lexicons?: unknown }).lexicons === "object" &&
+    (value as { lexicons?: unknown }).lexicons !== null
+  );
+}
+
+/**
+ * Parse a baseline document. Returns `null` for unparseable or unrecognized
+ * content — a corrupt baseline degrades to "nothing is accepted", which is
+ * noisy but never wrong. Silently treating garbage as a baseline would
+ * suppress real drift.
+ */
+export function parseBaseline(content: string | null | undefined): ObservationBaseline | null {
+  if (!content) return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    return null;
+  }
+  if (!isObservationBaseline(parsed)) return null;
+  return parsed;
+}
+
+/** Deterministic on-disk form: sorted keys, trailing newline, reviewable diff. */
+export function serializeBaseline(baseline: ObservationBaseline): string {
+  return `${JSON.stringify(baseline, sortedJsonReplacer, 2)}\n`;
+}
+
+/** The accepted deviations for one lexicon, or an empty map. */
+export function baselineForLexicon(
+  baseline: ObservationBaseline | null | undefined,
+  lexicon: string,
+): BaselineLexicon {
+  return baseline?.lexicons?.[lexicon] ?? {};
+}
+
+/** Look up one accepted deviation by entity + path. */
+export function acceptedDeviation(
+  lexiconBaseline: BaselineLexicon,
+  entity: string,
+  path: string,
+): AcceptedDeviation | undefined {
+  return lexiconBaseline[entity]?.accepted.find((a) => a.path === path);
+}
+
+/** One deviation to record as accepted. */
+export interface DeviationToAccept {
+  entity: string;
+  type?: string;
+  path: string;
+  /** The live value being accepted. */
+  value: unknown;
+  note?: 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.
+ */
+export function acceptDeviations(
+  baseline: ObservationBaseline,
+  lexicon: string,
+  deviations: readonly DeviationToAccept[],
+  opts?: { now?: string },
+): ObservationBaseline {
+  if (deviations.length === 0) return baseline;
+  const now = opts?.now ?? new Date().toISOString();
+  const lexicons: Record<string, BaselineLexicon> = { ...baseline.lexicons };
+  const entities: BaselineLexicon = { ...(lexicons[lexicon] ?? {}) };
+
+  for (const dev of deviations) {
+    const existing = entities[dev.entity];
+    const accepted = (existing?.accepted ?? []).filter((a) => a.path !== dev.path);
+    accepted.push({
+      path: dev.path,
+      value: dev.value,
+      ...(dev.note ? { note: dev.note } : {}),
+      recordedAt: now,
+    });
+    accepted.sort((a, b) => a.path.localeCompare(b.path));
+    entities[dev.entity] = {
+      ...(dev.type ?? existing?.type ? { type: dev.type ?? existing?.type } : {}),
+      accepted,
+    };
+  }
+
+  lexicons[lexicon] = entities;
+  return { baseline: "v1", environment: baseline.environment, updated: now, lexicons };
+}
+
+/** Total accepted deviations across every lexicon — for the "N accepted" line. */
+export function countAccepted(baseline: ObservationBaseline | null | undefined): number {
+  if (!baseline) return 0;
+  let n = 0;
+  for (const entities of Object.values(baseline.lexicons)) {
+    for (const entity of Object.values(entities)) n += entity.accepted.length;
+  }
+  return n;
+}
+
+// ── Storage (chant/lifecycle orphan branch) ─────────────────────────────────
+
+/**
+ * Read the accepted baseline for an environment. Returns `null` when the branch,
+ * the environment, or the file does not exist — every one of which means
+ * "nothing accepted yet", the normal state before anyone runs
+ * `--update-baseline`.
+ */
+export async function readObservationBaseline(
+  environment: string,
+  opts?: { cwd?: string },
+): Promise<ObservationBaseline | null> {
+  return parseBaseline(await readBlobFromPath(environment, OBSERVATION_BASELINE_FILE, opts));
+}
+
+/** Write the accepted baseline to the orphan branch. Returns the new commit SHA. */
+export async function writeObservationBaseline(
+  baseline: ObservationBaseline,
+  opts?: { cwd?: string },
+): Promise<string> {
+  return writeBlobToPath(
+    baseline.environment,
+    OBSERVATION_BASELINE_FILE,
+    serializeBaseline(baseline),
+    "Accepted observation baseline",
+    opts,
+  );
+}