@intentius/chant 0.79.0 → 0.81.0

package/src/lifecycle/member-ledger.ts

@@ -0,0 +1,145 @@
+/**
+ * Where a project's lifecycle ledger lives on the `chant/lifecycle` branch
+ * (#2538, #2524 D7, ws-036).
+ *
+ * A workspace member writes every lifecycle store under
+ * `_members/<member>/` on the one existing branch: releases, snapshots, runs,
+ * converge records and observation baselines under `<env>/`, gates under
+ * `_gates/`, build records under `_builds/`. Its operator leases move the same
+ * way, to `refs/chant/lease/_members/<member>/<op>`. Push, fetch, lease and
+ * staleness code are untouched: they still see one branch and plain refs.
+ *
+ * Everything else keeps today's flat layout, byte for byte:
+ *
+ * - a project with no `chant.workspace.json` between it and the git root
+ *   (level 0);
+ * - the root member `.`;
+ * - a directory no member owns;
+ * - an example group's match, since a group has no ledger of its own (ws-051).
+ *
+ * A member of kind `workspace` holds a nested declaration. The nested
+ * workspace's ledgers sit inside the outer member's, so its member `api` in
+ * the outer member `platform` writes under `_members/platform/_members/api/`,
+ * and the nested root member `.` writes under `_members/platform/`.
+ *
+ * Level 0 pays one upward `existsSync` walk here and nothing more. The
+ * declaration reader under `../workspace/` is imported only once a
+ * declaration has been found, so a project without one never loads workspace
+ * code (#2525 rule 5, pinned by #2526's goldens).
+ */
+
+import { existsSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { findWorkspaceRoot } from "../project-root";
+
+/** The directory on `chant/lifecycle` that holds every member's ledger. */
+export const MEMBERS_DIR = "_members";
+
+/**
+ * The first chant that writes member ledgers. A member whose own toolchain
+ * resolves an older chant still writes the flat layout; `chant workspace
+ * check` fails when two flat writers share an environment name (#2524 D7).
+ */
+export const MEMBER_LEDGER_FLOOR = "0.81.0";
+
+/** Where one project's ledger lives. */
+export interface MemberLedger {
+  /**
+   * The owning member's path of names, outermost first: `["api"]`, or
+   * `["platform", "api"]` inside a nested workspace. Empty for the flat
+   * layout.
+   */
+  members: string[];
+  /** The directory prefix on the branch: `""`, or `_members/<member>/` per level. */
+  prefix: string;
+}
+
+const FLAT: MemberLedger = { members: [], prefix: "" };
+
+/** The branch prefix for a path of member names. */
+export function memberLedgerPrefix(members: readonly string[]): string {
+  return members.map((m) => `${MEMBERS_DIR}/${m}/`).join("");
+}
+
+/**
+ * Thrown when a project sits in a workspace whose declaration cannot be read.
+ * Writing the flat layout then could land in another member's ledger, so no
+ * lifecycle store guesses.
+ */
+export class MemberLedgerError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "MemberLedgerError";
+  }
+}
+
+const cache = new Map<string, Promise<MemberLedger>>();
+
+/**
+ * The ledger of the project at `projectDir` (any directory inside it will do;
+ * ownership goes to the deepest member directory holding it). Results are
+ * cached per directory for the life of the process.
+ */
+export function resolveMemberLedger(projectDir: string): Promise<MemberLedger> {
+  const dir = resolve(projectDir);
+  let hit = cache.get(dir);
+  if (!hit) {
+    hit = resolveUncached(dir);
+    cache.set(dir, hit);
+    // A failure is not remembered: the next call reads the declaration again.
+    hit.catch(() => cache.delete(dir));
+  }
+  return hit;
+}
+
+/** Forget cached resolutions, for tests that write a declaration mid-run. */
+export function clearMemberLedgerCache(): void {
+  cache.clear();
+}
+
+function treePath(root: string, dir: string): string {
+  const rel = relative(root, dir);
+  return rel === "" ? "" : rel.split(sep).join("/");
+}
+
+async function resolveUncached(dir: string): Promise<MemberLedger> {
+  const found = findWorkspaceRoot(dir);
+  if (!found) return FLAT;
+  return ledgerIn(found.dir, dir);
+}
+
+/**
+ * The ledger of `dir` in the workspace whose declaration sits in `root`. When
+ * that workspace is nested, its whole ledger sits inside the ledger of the
+ * outer member holding `root`. The git root ends the walk outwards, as it
+ * ends {@link findWorkspaceRoot}'s.
+ */
+async function ledgerIn(root: string, dir: string): Promise<MemberLedger> {
+  // Only now does workspace code load.
+  const { readDeclaration, resolveGroups, ownerOf, WorkspaceReadError } = await import("../workspace/declaration");
+  const { workingTree } = await import("../workspace/tree");
+
+  let own: string[];
+  try {
+    const tree = workingTree(root);
+    const declaration = readDeclaration(tree);
+    const owner = ownerOf(declaration, resolveGroups(declaration, tree), treePath(root, dir));
+    own = owner && "member" in owner && owner.member.dir !== "." ? [owner.member.name] : [];
+  } catch (err) {
+    if (!(err instanceof WorkspaceReadError)) throw err;
+    throw new MemberLedgerError(
+      `cannot place this project's lifecycle ledger: ${err.describe()}. ` +
+        `A project inside a workspace writes under ${MEMBERS_DIR}/<member>/ on chant/lifecycle, ` +
+        `and chant does not guess the member. Fix the declaration and retry.`,
+    );
+  }
+
+  let outer: MemberLedger = FLAT;
+  const parent = dirname(root);
+  if (parent !== root && !existsSync(join(root, ".git"))) {
+    const outerFound = findWorkspaceRoot(parent);
+    if (outerFound) outer = await ledgerIn(outerFound.dir, root);
+  }
+  const members = [...outer.members, ...own];
+  return { members, prefix: memberLedgerPrefix(members) };
+}

package/src/lifecycle/plan-digest.ts

@@ -36,8 +36,8 @@
  * The identity is therefore a claim about consequence, not about provenance.
  * That is the claim an approver is actually making.
  */
-import { sortedJsonReplacer } from "../utils";
-import { getRuntime } from "../runtime-adapter";
+import { canonicalJson } from "../effect-receipt";
+import { contentDigest } from "../content-digest";
 
 /** The hash a plan digest is taken with, and the prefix every digest carries. */
 export const PLAN_DIGEST_ALGORITHM = "sha256";
@@ -54,15 +54,15 @@ const PLAN_DIGEST_PATTERN = /^sha256:[0-9a-f]{64}$/;
  * to a terraform plan must not be satisfiable by a lifecycle diff that
  * happened to serialize identically.
  *
- * `subject` is canonicalised by {@link sortedJsonReplacer}, so object key
- * order — which neither terraform's JSON writer nor `JSON.parse` guarantees
- * across versions — does not change the answer. It is the caller's job to
+ * `subject` is put in canonical form by `canonicalJson` (../effect-receipt.ts)
+ * and hashed by `contentDigest` (../content-digest.ts), so object key order,
+ * which neither terraform's JSON writer nor `JSON.parse` guarantees across
+ * versions, does not change the answer. It is the caller's job to
  * hand in a projection that already excludes the volatile fields this
  * module's doc comment lists.
  */
 export function computePlanDigest(kind: string, subject: unknown): string {
-  const canonical = JSON.stringify({ kind, subject }, sortedJsonReplacer);
-  return `${PLAN_DIGEST_ALGORITHM}:${getRuntime().hash(canonical)}`;
+  return contentDigest(canonicalJson({ kind, subject }));
 }
 
 /**

package/src/lifecycle/release-ledger.test.ts

@@ -297,5 +297,25 @@ describe("release-ledger", () => {
         expect(records[0].runOrigin).toEqual(input.runOrigin);
       });
     });
+
+    test("a redeploy record round-trips and stays the current release (#2604)", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const first = makeInput({ runId: "run-1", timestamp: "2026-01-01T00:00:00.000Z" });
+        const redeploy = makeInput({
+          runId: "run-2",
+          timestamp: "2026-01-02T00:00:00.000Z",
+          redeploys: { env: first.env, runId: "run-1", timestamp: "2026-01-01T00:00:00.000Z" },
+        });
+        await appendReleaseRecord(first, { cwd: dir });
+        await appendReleaseRecord(redeploy, { cwd: dir });
+        const { records, malformed } = await readReleaseLedger(first.env, { cwd: dir });
+        expect(malformed).toBe(0);
+        expect(records[1].redeploys).toEqual(redeploy.redeploys);
+        const current = latestPerComponent(records).get(first.component)!;
+        expect(current.runId).toBe("run-2");
+        expect(current.digest).toBe(first.digest);
+      });
+    });
   });
 });

package/src/lifecycle/release-ledger.ts

@@ -29,6 +29,7 @@
  */
 
 import { sortedJsonReplacer } from "../utils";
+import { flagLegacyDigest, warnOnLegacyDigests, withoutReadFlags, type LegacyDigestFlag } from "./legacy-digest";
 import { appendReleaseRecordLine, readReleaseLedgerLines, listLedgerEnvironments as gitListLedgerEnvironments } from "./git";
 
 /**
@@ -50,6 +51,20 @@ export interface RunOrigin {
   url?: string;
 }
 
+/**
+ * Points at one earlier release record (#2530, #2531, #2604). A record has no id of its own,
+ * so it is named by the environment whose ledger holds it plus the run id and
+ * timestamp it was written with, which is enough to find the line again.
+ */
+export interface ReleaseRef {
+  /** The environment whose ledger holds the referenced record. */
+  env: string;
+  /** The referenced record's `runId`. */
+  runId: string;
+  /** The referenced record's `timestamp`. */
+  timestamp: string;
+}
+
 /**
  * One immutable deploy record: `(component, env, artifact digest, git sha,
  * run id, timestamp, actor)`, referencing the build archive by digest — the
@@ -128,6 +143,33 @@ export interface ReleaseRecord {
    * bytes each cluster got. Absent when `digest` is already input-side.
    */
   inputDigest?: string;
+  /**
+   * Optional: set when this release was a promotion (`chant components
+   * promote`, #2530). Names the source environment's release whose digest
+   * was deployed here without a build. Absent on every other record.
+   */
+  promotedFrom?: ReleaseRef;
+  /**
+   * Optional: set when this release was a rollback (`chant components
+   * rollback`, #2531). Names the earlier release of the same environment
+   * whose digest was deployed again. Absent on every other record.
+   */
+  restores?: ReleaseRef;
+  /**
+   * Set on read, never written. `["legacy-digest"]` when `digest`,
+   * `manifestDigest` or `inputDigest` was recorded by the 32-bit hash chant
+   * used before real SHA-256 (#2514). Such a record is kept exactly as it
+   * was written, never re-keyed, and is accepted through
+   * `LEGACY_DIGEST_ACCEPTED_THROUGH` (./legacy-digest.ts).
+   */
+  flags?: LegacyDigestFlag[];
+  /**
+   * Optional: set when this release was a redeploy (`chant components
+   * redeploy`, #2604). Names the release the ledger recorded as current,
+   * whose digest was deployed again, usually after a deploy that failed
+   * partway. Absent on every other record.
+   */
+  redeploys?: ReleaseRef;
 }
 
 /** Required, non-empty-string fields every `ReleaseRecord` must carry. */
@@ -160,7 +202,7 @@ export function validateReleaseRecord(record: Partial<ReleaseRecord>): string[]
 }
 
 /** Input a caller supplies to record one deploy — `version` is filled in, everything else is required (see `ReleaseRecord`). */
-export type ReleaseRecordInput = Omit<ReleaseRecord, "version">;
+export type ReleaseRecordInput = Omit<ReleaseRecord, "version" | "flags">;
 
 /**
  * Resolve a run id and its origin from the same environment, in one step, so
@@ -227,7 +269,8 @@ export async function appendReleaseRecord(
   const missing = validateReleaseRecord(input);
   if (missing.length > 0) throw new InvalidReleaseRecordError(missing);
 
-  const record: ReleaseRecord = { version: 1, ...input };
+  // `flags` are read-side only (#2514); a record passed back in never persists them.
+  const record: ReleaseRecord = { version: 1, ...withoutReadFlags(input as ReleaseRecordInput & { flags?: unknown }) };
   const json = JSON.stringify(record, sortedJsonReplacer);
   const commit = await appendReleaseRecordLine(record.env, json, opts);
   return { commit, record };
@@ -253,11 +296,18 @@ export async function readReleaseLedger(
         malformed++;
         continue;
       }
-      records.push(parsed);
+      // chant #2514 — a digest from before real SHA-256 is flagged, never re-keyed.
+      records.push(flagLegacyDigest(parsed, [parsed.digest, parsed.manifestDigest, parsed.inputDigest]));
     } catch {
       malformed++;
     }
   }
+  // chant #2514 — say once that this ledger holds values in the old form.
+  warnOnLegacyDigests(
+    records.flatMap((r) => [r.digest, r.manifestDigest, r.inputDigest]),
+    "release ledger",
+    opts?.cwd,
+  );
   return { records, malformed };
 }
 

package/src/lifecycle/status.test.ts

@@ -7,9 +7,11 @@ import {
   mergeLiveEvidence,
   type LiveComponentEvidence,
   type LiveNameMapping,
+  type EntityLiveRead,
 } from "./status";
 import type { ReleaseRecord } from "./release-ledger";
-import type { ChangeSet } from "./change-set";
+import type { ChangeSet, ChangeSetEntry } from "./change-set";
+import type { ResourceMetadata } from "../lexicon";
 import type { BuildLedgerEntry, ComponentBomSummary } from "./build-ledger";
 
 function record(overrides?: Partial<ReleaseRecord>): ReleaseRecord {
@@ -631,3 +633,151 @@ describe("partial unit presence is said, not rounded down to nothing (#1528)", (
     expect(merged.get("operator")!.partial).toEqual(partial);
   });
 });
+
+// ── Live evidence that contradicts the recorded release (#2513) ─────────────
+
+describe("drifted: live evidence contradicts the recorded release (#2513)", () => {
+  const released = record({ component: "svc", digest: "sha256:released", gitSha: "1111111aaaaaaa", timestamp: "2026-02-01T00:00:00.000Z" });
+  const live = (meta: Partial<ResourceMetadata> = {}): ResourceMetadata => ({ type: "T", status: "ACTIVE", ownership: "owned", ...meta });
+  const entry = (overrides: Partial<ChangeSetEntry> = {}): ChangeSetEntry => ({
+    name: "svc",
+    type: "T",
+    action: "noop",
+    evidence: { declared: true, inSnapshot: true, live: true, observed: true },
+    ownership: "owned",
+    ...overrides,
+  });
+  const reconcile = (entries: ChangeSetEntry[], reads: Map<string, EntityLiveRead>, rec: ReleaseRecord = released) =>
+    reconcileStatus("prod", [rec], {
+      liveEvidence: liveEvidenceFromChangeSet({ env: "prod", entries }, undefined, { observations: reads }),
+    })[0];
+
+  test("reconciled: the reported identity matches digest and (abbreviated) git sha", () => {
+    const row = reconcile([entry()], new Map([["svc", { now: live({ attributes: { digest: "sha256:released", gitSha: "1111111" } }) }]]));
+    expect(row.reconciliation).toBe("reconciled");
+  });
+
+  test("reconciled: a bare hex digest names the same digest as its sha256: form", () => {
+    const row = reconcile([entry()], new Map([["svc", { now: live({ attributes: { digest: "released" } }) }]]));
+    expect(row.reconciliation).toBe("reconciled");
+  });
+
+  test("reconciled: a pinned record's inputDigest is an accepted identity", () => {
+    const row = reconcile(
+      [entry()],
+      new Map([["svc", { now: live({ attributes: { digest: "sha256:input" } }) }]]),
+      { ...released, inputDigest: "sha256:input" },
+    );
+    expect(row.reconciliation).toBe("reconciled");
+  });
+
+  test("drifted: a foreign digest", () => {
+    const row = reconcile([entry()], new Map([["svc", { now: live({ attributes: { digest: "sha256:other" } }) }]]));
+    expect(row.reconciliation).toBe("drifted");
+    expect(row.detail).toContain("sha256:other");
+    expect(row.live).toBe(true);
+  });
+
+  test("drifted: an unknown git sha", () => {
+    const row = reconcile([entry()], new Map([["svc", { now: live({ attributes: { gitSha: "2222222" } }) }]]));
+    expect(row.reconciliation).toBe("drifted");
+  });
+
+  test("drifted: an update against a snapshot taken at or after the release", () => {
+    const row = reconcile(
+      [entry({ action: "update", deltas: [{ path: "attributes.revision", oldValue: "6", newValue: "7" }] })],
+      new Map([["svc", { now: live(), then: live(), thenAt: "2026-02-01T00:00:00.000Z" }]]),
+    );
+    expect(row.reconciliation).toBe("drifted");
+    expect(row.detail).toContain("attributes.revision");
+  });
+
+  test("reconciled: an update against a snapshot older than the release is the release itself", () => {
+    const row = reconcile(
+      [entry({ action: "update", deltas: [{ path: "lastUpdated", oldValue: "a", newValue: "b" }] })],
+      new Map([["svc", { now: live(), then: live(), thenAt: "2026-01-31T23:59:59.000Z" }]]),
+    );
+    expect(row.reconciliation).toBe("reconciled");
+  });
+
+  test("drifted: owned at the snapshot, foreign now", () => {
+    const row = reconcile(
+      [entry({ ownership: "foreign" })],
+      new Map([["svc", { now: live({ ownership: "foreign" }), then: live({ ownership: "owned" }), thenAt: "2026-02-02T00:00:00.000Z" }]]),
+    );
+    expect(row.reconciliation).toBe("drifted");
+  });
+
+  test("drifted: the ownership marker now names a different stack", () => {
+    const row = reconcile(
+      [entry()],
+      new Map([["svc", {
+        now: live({ marker: { stack: "other", env: "prod" } }),
+        then: live({ marker: { stack: "app", env: "prod" } }),
+        thenAt: "2026-02-02T00:00:00.000Z",
+      }]]),
+    );
+    expect(row.reconciliation).toBe("drifted");
+    expect(row.detail).toContain("app/prod");
+  });
+
+  test("reconciled: ownership going to unknown is not a contradiction", () => {
+    const row = reconcile(
+      [entry({ ownership: "unknown" })],
+      new Map([["svc", { now: live({ ownership: "unknown" }), then: live({ ownership: "owned" }), thenAt: "2026-02-02T00:00:00.000Z" }]]),
+    );
+    expect(row.reconciliation).toBe("reconciled");
+  });
+
+  test("stale: confirmed absent, whatever the snapshot said", () => {
+    const row = reconcile(
+      [entry({ action: "create", evidence: { declared: true, inSnapshot: true, live: false, observed: true } })],
+      new Map([["svc", { then: live({ attributes: { digest: "sha256:other" } }), thenAt: "2026-02-02T00:00:00.000Z" }]]),
+    );
+    expect(row.reconciliation).toBe("stale");
+  });
+
+  test("unknown: not observed never becomes drifted", () => {
+    const row = reconcile(
+      [entry({ action: "unobserved", unobservedReason: "read-failed", evidence: { declared: true, inSnapshot: true, live: false, observed: false } })],
+      new Map([["svc", { then: live({ attributes: { digest: "sha256:other" } }), thenAt: "2026-02-02T00:00:00.000Z" }]]),
+    );
+    expect(row.reconciliation).toBe("unknown");
+    expect(row.live).toBeUndefined();
+  });
+
+  test("a mapped component drifts when any of its live resources contradicts the record", () => {
+    const evidence = liveEvidenceFromChangeSet(
+      { env: "prod", entries: [entry({ name: "svc-a" }), entry({ name: "svc-b" })] },
+      new Map([["svc", ["svc-a", "svc-b"]]]),
+      {
+        observations: new Map([
+          ["svc-a", { now: live({ attributes: { digest: "sha256:released" } }) }],
+          ["svc-b", { now: live({ attributes: { digest: "sha256:other" } }) }],
+        ]),
+      },
+    );
+    const row = reconcileStatus("prod", [released], { liveEvidence: evidence })[0];
+    expect(row.reconciliation).toBe("drifted");
+    expect(row.detail).toContain("svc-b");
+  });
+
+  test("identity and drift signals survive the stack-presence overlay", () => {
+    const base = liveEvidenceFromChangeSet({ env: "prod", entries: [entry()] }, undefined, {
+      observations: new Map([["svc", { now: live({ attributes: { digest: "sha256:other" } }) }]]),
+    });
+    const merged = mergeLiveEvidence(base, new Map([["svc", { live: true, ownership: "owned" }]]));
+    const row = reconcileStatus("prod", [released], { liveEvidence: merged })[0];
+    expect(row.reconciliation).toBe("drifted");
+  });
+
+  test("without per-entity reads the evidence is unchanged from before (no new fields)", () => {
+    const evidence = liveEvidenceFromChangeSet({ env: "prod", entries: [entry()] });
+    expect(evidence.get("svc")).toEqual({
+      live: true,
+      action: "noop",
+      ownership: "owned",
+      rollup: { total: 1, present: 1, absent: 0, unobserved: 0 },
+    });
+  });
+});