@intentius/chant 0.124.51 → 0.124.54

package/src/lifecycle/query.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "vitest";
 import type { LedgerReadPort } from "./ledger-port";
-import { firstWord, formatQueryResult, loadQueryData, QUERY_SCHEMA_VERSION, QUERY_TABLES, QueryError, runQuery, SCHEMA_TABLE } from "./query";
+import { NEXT_RELEASE } from "../release-floors";
+import { firstWord, formatQueryResult, loadQueryData, QUERY_OWNERSHIP_COLUMNS_FLOOR, QUERY_SCHEMA_VERSION, QUERY_TABLES, QueryError, runQuery, SCHEMA_TABLE } from "./query";
 import { makeRelease } from "./release-store";
 
 /** A port over a map of `<dir>/<file>` to text, the shape `gitLedgerReadPort` reads. */
@@ -88,4 +89,71 @@ describe("chant query (#4297)", () => {
     await expect(runQuery("SELECT nope FROM runs", load)).rejects.toThrow(/does not run/);
     expect(firstWord("-- note\n /* c */ select 1")).toBe("select");
   });
+
+  describe("ownership columns on resources (#4534)", () => {
+    // A choudoufu live root read through the terraform lexicon, and a k8s
+    // root whose labels name the stack and env. Engine facts are the
+    // snapshot's `facts`; chant's marker is its `marker`.
+    const owned = port({
+      "prod/estate__terraform.json": JSON.stringify({
+        lexicon: "terraform",
+        environment: "prod",
+        commit: "d".repeat(40),
+        timestamp: "2026-10-26T00:00:00Z",
+        resources: {
+          "aws_s3_bucket.logs": { type: "aws_s3_bucket", status: "bound", physicalId: "acme-logs", ownership: "owned", marker: { stack: "acme", env: "aws_s3_bucket.logs" }, facts: { ownership: "bound", ownedBy: "marker" } },
+          "aws_sqs_queue.jobs": { type: "aws_sqs_queue", status: "unowned", ownership: "foreign", facts: { ownership: "unowned" } },
+          "aws_eip.pool": { type: "aws_eip", status: "bound", ownership: "owned", facts: { ownership: "bound", ownedBy: "record" } },
+        },
+      }),
+      "prod/shop__k8s.json": JSON.stringify({
+        lexicon: "k8s",
+        environment: "prod",
+        commit: "e".repeat(40),
+        timestamp: "2026-10-26T00:00:00Z",
+        resources: { web: { type: "K8s::Apps::Deployment", status: "Available", physicalId: "default/web", ownership: "owned", marker: { stack: "shop", env: "prod" } } },
+      }),
+    });
+
+    test("are listed in schema v1, after the existing columns", async () => {
+      const cols = QUERY_TABLES.resources.map(([c]) => c);
+      expect(cols.slice(0, 13)).toEqual(["member", "env", "stack", "lexicon", "name", "type", "physical_id", "status", "last_updated", "ownership", "attributes", "git_sha", "observed_at"]);
+      expect(cols.slice(13)).toEqual(["marker_stack", "marker_env", "engine_ownership", "engine_owned_by"]);
+      const load = await loadQueryData([]);
+      const r = await runQuery(`SELECT column_name, version FROM ${SCHEMA_TABLE} WHERE table_name = 'resources' AND column_name IN ('ownership', 'marker_stack', 'marker_env', 'engine_ownership', 'engine_owned_by') ORDER BY position`, load);
+      expect(r.rows.map((x) => x.column_name)).toEqual(["ownership", "marker_stack", "marker_env", "engine_ownership", "engine_owned_by"]);
+      expect(new Set(r.rows.map((x) => x.version))).toEqual(new Set([1]));
+    });
+
+    test("project the snapshot's marker and engine facts, NULL when unknown", async () => {
+      const load = await loadQueryData([{ member: null, port: owned }]);
+      const by = Object.fromEntries(load.data.resources.map((r) => [r.name, r]));
+      expect(by["aws_s3_bucket.logs"]).toMatchObject({ ownership: "owned", marker_stack: "acme", marker_env: "aws_s3_bucket.logs", engine_ownership: "bound", engine_owned_by: "marker" });
+      expect(by["aws_sqs_queue.jobs"]).toMatchObject({ ownership: "foreign", marker_stack: null, marker_env: null, engine_ownership: "unowned", engine_owned_by: null });
+      expect(by.web).toMatchObject({ lexicon: "k8s", ownership: "owned", marker_stack: "shop", marker_env: "prod", engine_ownership: null, engine_owned_by: null });
+    });
+
+    test("are NULL on a snapshot that predates them", async () => {
+      const load = await loadQueryData([{ member: null, port: ledger }]);
+      for (const r of load.data.resources) {
+        expect(r).toMatchObject({ marker_stack: null, marker_env: null, engine_ownership: null, engine_owned_by: null });
+      }
+    });
+
+    test("count by both verdicts without the graph peer", async () => {
+      const load = await loadQueryData([{ member: null, port: owned }]);
+      const r = await runQuery("SELECT lexicon, ownership, engine_ownership, count(*) AS n FROM resources GROUP BY 1, 2, 3 ORDER BY 1, 2, 3", load);
+      expect(r.rows).toEqual([
+        { lexicon: "k8s", ownership: "owned", engine_ownership: null, n: 1 },
+        { lexicon: "terraform", ownership: "foreign", engine_ownership: "unowned", n: 1 },
+        { lexicon: "terraform", ownership: "owned", engine_ownership: "bound", n: 2 },
+      ]);
+      const who = await runQuery("SELECT stack, name, marker_stack FROM resources WHERE physical_id = 'default/web'", load);
+      expect(who.rows).toEqual([{ stack: "shop", name: "web", marker_stack: "shop" }]);
+    });
+
+    test("carry their floor at the next release", () => {
+      expect(QUERY_OWNERSHIP_COLUMNS_FLOOR).toBe(NEXT_RELEASE);
+    });
+  });
 });

package/src/lifecycle/query.ts

@@ -1,12 +1,14 @@
 /**
- * `chant query "<sql>"` (#4297): one read-only SQL statement over what
- * `chant/lifecycle` holds, run in this process with no server.
+ * `chant query "<sql>"` (#4297): one read-only SQL statement over the
+ * snapshots and the Ops records, run in this process with no server.
  *
  * The rows come from the ledgers chant already writes:
  *
  * - the snapshots, `<env>/<lexicon>.json` and `<env>/<stack>__<lexicon>.json`
  *   (`./git.ts` `snapshotStorageKey`), each lexicon's `describeResources`
- *   read, so the inventory works for every lexicon;
+ *   read, so the inventory works for every lexicon. They are read through the
+ *   index store (./snapshot-store.ts, #4519) when the ledger names one, so
+ *   the tables are the same whichever store holds them;
  * - the Op run ledgers, `<env>/runs__<op>.jsonl` (`./run-ledger.ts`);
  * - the gate ledgers, `_gates/<op>.jsonl` (`./gate-ledger.ts`);
  * - the deploy records, `<env>/releases.jsonl` (`./release-read.ts`);
@@ -34,6 +36,7 @@ import { parseReleaseLedger, releaseLedgerLines } from "./release-read";
 import { CUTS_FILE, parseCuts, parseRelease, RELEASES_DIR, verifyReleaseDigest } from "./release-store";
 import { opOfRunLedgerFile, parseRunLedger } from "./run-ledger";
 import type { LifecycleSnapshot } from "./types";
+import { NEXT_RELEASE } from "../release-floors";
 
 /** The version of the table schema below. */
 export const QUERY_SCHEMA_VERSION = 1;
@@ -47,12 +50,28 @@ type ColumnType = "TEXT" | "INTEGER";
  * for a project outside a workspace.
  */
 export const QUERY_TABLES = {
-  /** One row per resource in each environment's newest snapshot. `attributes` is JSON. */
-  resources: [["member", "TEXT"], ["env", "TEXT"], ["stack", "TEXT"], ["lexicon", "TEXT"], ["name", "TEXT"], ["type", "TEXT"], ["physical_id", "TEXT"], ["status", "TEXT"], ["last_updated", "TEXT"], ["ownership", "TEXT"], ["attributes", "TEXT"], ["git_sha", "TEXT"], ["observed_at", "TEXT"]],
+  /**
+   * One row per resource in each environment's newest snapshot. `attributes`
+   * is JSON. `ownership` is chant's marker verdict; `marker_stack` and
+   * `marker_env` (#4534) are the stack and env that marker names, read off
+   * the resource. `engine_ownership` and `engine_owned_by` (#4534) are an
+   * ownership engine's verdict and what bound the node (choudoufu, plunge;
+   * the snapshot's `facts.ownership` and `facts.ownedBy`), shown beside
+   * chant's and never in place of it. NULL means unknown.
+   */
+  resources: [["member", "TEXT"], ["env", "TEXT"], ["stack", "TEXT"], ["lexicon", "TEXT"], ["name", "TEXT"], ["type", "TEXT"], ["physical_id", "TEXT"], ["status", "TEXT"], ["last_updated", "TEXT"], ["ownership", "TEXT"], ["attributes", "TEXT"], ["git_sha", "TEXT"], ["observed_at", "TEXT"], ["marker_stack", "TEXT"], ["marker_env", "TEXT"], ["engine_ownership", "TEXT"], ["engine_owned_by", "TEXT"]],
   /** One row per snapshot file: what was observed, when, and how many resources it holds. */
   snapshots: [["member", "TEXT"], ["env", "TEXT"], ["stack", "TEXT"], ["lexicon", "TEXT"], ["git_sha", "TEXT"], ["observed_at", "TEXT"], ["depth", "TEXT"], ["resources", "INTEGER"], ["unobserved", "INTEGER"]],
-  /** One row per Op run record. `labels` and `outcomes` are JSON. */
-  runs: [["member", "TEXT"], ["id", "TEXT"], ["op", "TEXT"], ["env", "TEXT"], ["started", "TEXT"], ["ended", "TEXT"], ["status", "TEXT"], ["git_sha", "TEXT"], ["forge", "TEXT"], ["run_url", "TEXT"], ["failure_code", "TEXT"], ["failure_reason", "TEXT"], ["failed_phase", "TEXT"], ["gate", "TEXT"], ["steward", "TEXT"], ["labels", "TEXT"], ["outcomes", "TEXT"]],
+  /**
+   * One row per Op run record. `labels` and `outcomes` are JSON. `root_member`
+   * (#4482) is the workspace member whose directory holds the terraform root
+   * a TerraformApplyOp run applied, read off its `TerraformRootPath` outcome.
+   * NULL means unknown (#4508): any other run, outside a workspace, or a run
+   * whose Init step failed before it resolved the root's directory, since the
+   * Op names its root only by key and Init is what resolves it. A run whose
+   * `terraform init` itself failed still names it (#4512).
+   */
+  runs: [["member", "TEXT"], ["id", "TEXT"], ["op", "TEXT"], ["env", "TEXT"], ["started", "TEXT"], ["ended", "TEXT"], ["status", "TEXT"], ["git_sha", "TEXT"], ["forge", "TEXT"], ["run_url", "TEXT"], ["failure_code", "TEXT"], ["failure_reason", "TEXT"], ["failed_phase", "TEXT"], ["gate", "TEXT"], ["steward", "TEXT"], ["labels", "TEXT"], ["outcomes", "TEXT"], ["root_member", "TEXT"]],
   /** One row per gate ledger line: `kind` is `pending` or `resolution`. `signed` is 1 for a sealed approval. */
   gates: [["member", "TEXT"], ["op", "TEXT"], ["gate", "TEXT"], ["kind", "TEXT"], ["timestamp", "TEXT"], ["resolved_by", "TEXT"], ["relayed_by", "TEXT"], ["approver_kind", "TEXT"], ["plan_digest", "TEXT"], ["environment", "TEXT"], ["release_digest", "TEXT"], ["git_sha", "TEXT"], ["run_id", "TEXT"], ["url", "TEXT"], ["note", "TEXT"], ["expires_at", "TEXT"], ["origin", "TEXT"], ["empty", "INTEGER"], ["signed", "INTEGER"]],
   /** One row per deploy record in `<env>/releases.jsonl`. `promoted_from`, `restores` and `redeploys` are JSON. */
@@ -63,6 +82,22 @@ export const QUERY_TABLES = {
   cuts: [["member", "TEXT"], ["release_digest", "TEXT"], ["label", "TEXT"], ["actor", "TEXT"], ["timestamp", "TEXT"], ["run_id", "TEXT"], ["forge", "TEXT"], ["channel", "TEXT"], ["signed", "INTEGER"], ["composed_base", "TEXT"]],
 } as const satisfies Record<string, ReadonlyArray<readonly [string, ColumnType]>>;
 
+/**
+ * The first chant that writes `root_member` on a `runs` row, in `chant query`
+ * and in `chant ledger runs --json` (#4482, #4500). A contract field added
+ * within version 1: a reader treats a row from an older chant as lacking it.
+ */
+export const LEDGER_ROOT_MEMBER_FLOOR = NEXT_RELEASE;
+
+/**
+ * The first chant that writes `marker_stack`, `marker_env`,
+ * `engine_ownership` and `engine_owned_by` on a `resources` row, in
+ * `chant query` and in `chant ledger resources --json` (#4534). Columns added
+ * within version 1: a reader treats a row from an older chant as lacking
+ * them, which reads as unknown.
+ */
+export const QUERY_OWNERSHIP_COLUMNS_FLOOR = NEXT_RELEASE;
+
 export type QueryTable = keyof typeof QUERY_TABLES;
 
 /** The table that describes the others: one row per column, with the schema version. */
@@ -78,6 +113,17 @@ export type QueryData = Record<QueryTable, QueryRow[]>;
 export interface QueryLedger {
   member: string | null;
   port: LedgerReadPort;
+  /**
+   * The snapshot family of the index store (#4519, `snapshotReadPort`). Given,
+   * the `resources` and `snapshots` rows come from it and snapshot files on
+   * `port` are skipped. Absent, they come from `port`, as before the store.
+   */
+  snapshots?: LedgerReadPort;
+  /**
+   * The member whose directory holds a workspace-relative path, or null
+   * (#4482). Given in a workspace; without it `root_member` is NULL.
+   */
+  ownerOfPath?: (path: string) => string | null;
 }
 
 export interface QueryLoad {
@@ -119,7 +165,25 @@ function snapshotRows(member: string | null, env: string, file: string, s: Lifec
   const resources = Object.entries(s.resources);
   data.snapshots.push({ member, env, stack, lexicon: s.lexicon, ...at, depth: s.depth ?? "identity", resources: resources.length, unobserved: Object.keys(s.unobserved ?? {}).length });
   for (const [name, r] of resources) {
-    data.resources.push({ member, env, stack, lexicon: s.lexicon, name, type: str(r?.type), physical_id: str(r?.physicalId), status: str(r?.status), last_updated: str(r?.lastUpdated), ownership: str(r?.ownership), attributes: json(r?.attributes), ...at });
+    data.resources.push({
+      member,
+      env,
+      stack,
+      lexicon: s.lexicon,
+      name,
+      type: str(r?.type),
+      physical_id: str(r?.physicalId),
+      status: str(r?.status),
+      last_updated: str(r?.lastUpdated),
+      ownership: str(r?.ownership),
+      attributes: json(r?.attributes),
+      ...at,
+      // Read as data from the snapshot (#4534): a projection for people, never a decision.
+      marker_stack: str(r?.marker?.stack),
+      marker_env: str(r?.marker?.env),
+      engine_ownership: str(r?.facts?.ownership),
+      engine_owned_by: str(r?.facts?.ownedBy),
+    });
   }
 }
 
@@ -150,6 +214,19 @@ function gateRow(member: string | null, r: GateResolutionRecord | PendingGateRec
   };
 }
 
+/**
+ * The member a run's `TerraformRootPath` outcome falls in (#4482): the
+ * workspace-relative directory of the root a TerraformApplyOp's Init step
+ * resolved. A local `chant run` records under the member that declares the
+ * Op, so this is what names the member whose root it applied when the two
+ * differ, as for a choudoufu member applied from a chant one.
+ */
+function rootMemberOf(outcomes: Record<string, unknown> | undefined, ownerOfPath: ((path: string) => string | null) | undefined): string | null {
+  const path = outcomes?.TerraformRootPath;
+  if (typeof path !== "string" || !ownerOfPath) return null;
+  return ownerOfPath(path);
+}
+
 /**
  * Read every table's rows from the ledgers, in the order given. A ledger
  * whose branch is absent reads as no rows. A line or file that is not its
@@ -159,11 +236,27 @@ function gateRow(member: string | null, r: GateResolutionRecord | PendingGateRec
 export async function loadQueryData(ledgers: readonly QueryLedger[]): Promise<QueryLoad> {
   const data = empty<QueryRow[]>(() => []) as QueryData;
   const malformed = empty(() => 0);
-  for (const { member, port } of ledgers) {
+  for (const { member, port, ownerOfPath, snapshots } of ledgers) {
+    if (snapshots) {
+      for (const env of (await snapshots.trees()).filter((t) => !t.startsWith("_")).sort()) {
+        for (const file of (await snapshots.list(env)).sort()) {
+          if (!file.endsWith(".json")) continue;
+          const text = await snapshots.read(env, file);
+          let parsed: unknown;
+          try {
+            parsed = text === null ? null : JSON.parse(text);
+          } catch {
+            parsed = null;
+          }
+          if (isSnapshot(parsed)) snapshotRows(member, env, file, parsed, data);
+        }
+      }
+    }
     const trees = (await port.trees()).sort();
     for (const env of trees.filter((t) => !t.startsWith("_"))) {
       for (const file of (await port.list(env)).sort()) {
         if (file.endsWith(".json")) {
+          if (snapshots) continue;
           const text = await port.read(env, file);
           let parsed: unknown;
           try {
@@ -189,7 +282,7 @@ export async function loadQueryData(ledgers: readonly QueryLedger[]): Promise<Qu
           const { records, malformed: bad } = parseRunLedger(text);
           malformed.runs += bad;
           for (const r of records) {
-            data.runs.push({ member, id: r.id, op: r.op, env: r.env, started: r.started, ended: r.ended, status: r.status, git_sha: str(r.gitSha), forge: str(r.runOrigin?.forge), run_url: str(r.runOrigin?.url), failure_code: str(r.failure?.code), failure_reason: str(r.failure?.reason), failed_phase: str(r.failure?.phase), gate: str(r.gate?.name), steward: str(r.steward), labels: json(r.labels ?? {}), outcomes: json(r.outcomes ?? {}) });
+            data.runs.push({ member, id: r.id, op: r.op, env: r.env, started: r.started, ended: r.ended, status: r.status, git_sha: str(r.gitSha), forge: str(r.runOrigin?.forge), run_url: str(r.runOrigin?.url), failure_code: str(r.failure?.code), failure_reason: str(r.failure?.reason), failed_phase: str(r.failure?.phase), gate: str(r.gate?.name), steward: str(r.steward), labels: json(r.labels ?? {}), outcomes: json(r.outcomes ?? {}), root_member: rootMemberOf(r.outcomes, ownerOfPath) });
           }
         }
       }

package/src/lifecycle/replay.test.ts

@@ -1,12 +1,16 @@
 import { describe, it, expect, vi, beforeEach } from "vitest";
 import type { LifecycleSnapshot } from "./types";
 
-// `replaySnapshots` reads the orphan branch through this one function, so the
-// stored set is the whole input surface.
+// `replaySnapshots` reads the index store (#4519) through this one function,
+// so the stored set is the whole input surface.
 const stored = new Map<string, string>();
-vi.mock("./git", () => ({
-  readEnvironmentSnapshots: async (): Promise<Map<string, string>> => stored,
-}));
+vi.mock("./snapshot-store", async () => {
+  const { fakeSnapshotStore } = await import("./snapshot-store-fake");
+  return {
+    resolveSnapshotStore: async () => fakeSnapshotStore({ keys: async () => [...stored.keys()] }),
+    readEnvironmentSnapshotsFrom: async (): Promise<Map<string, string>> => stored,
+  };
+});
 
 const { replaySnapshots } = await import("./replay");
 

package/src/lifecycle/replay.ts

@@ -14,7 +14,7 @@
  * answer most questions but never all of them.
  */
 
-import { readEnvironmentSnapshots } from "./git";
+import { readEnvironmentSnapshotsFrom, resolveSnapshotStore, type SnapshotStore } from "./snapshot-store";
 import { unqualifiedKey } from "./identity";
 import type { LiveObservation } from "../graph-ir";
 import type { LifecycleSnapshot, ObservationDepth } from "./types";
@@ -29,7 +29,7 @@ import type { LifecycleSnapshot, ObservationDepth } from "./types";
  * is shared. Nothing downstream needs to know which source it got.
  *
  * `latest` is the only ref for now. A specific commit is the natural extension
- * and the storage already supports it (`readSnapshotAt`), but "answer from what
+ * and the store already supports it (`SnapshotStore.readAt`), but "answer from what
  * is recorded" is the question worth settling first.
  */
 /**
@@ -40,9 +40,10 @@ import type { LifecycleSnapshot, ObservationDepth } from "./types";
  * failure here means the caller says the plain version of the message, never
  * that the command fails.
  */
-export async function hasSnapshot(environment: string): Promise<boolean> {
+export async function hasSnapshot(environment: string, opts?: { store?: SnapshotStore }): Promise<boolean> {
   try {
-    return (await readEnvironmentSnapshots(environment)).size > 0;
+    const store = opts?.store ?? (await resolveSnapshotStore());
+    return (await store.keys(environment)).length > 0;
   } catch {
     return false;
   }
@@ -52,6 +53,8 @@ export async function replaySnapshots(
   environment: string,
   ref: string,
   scopedStacks: Set<string>,
+  /** The index store to read (#4519). Default: the project's. */
+  opts?: { store?: SnapshotStore },
 ): Promise<
   | { observations: LiveObservation[]; commit: string; timestamp: string; depth: ObservationDepth }
   | { error: string; hint?: string }
@@ -62,7 +65,8 @@ export async function replaySnapshots(
       hint: "a specific snapshot commit is not wired up yet",
     };
   }
-  const stored = await readEnvironmentSnapshots(environment);
+  const store = opts?.store ?? (await resolveSnapshotStore());
+  const stored = await readEnvironmentSnapshotsFrom(store, environment);
   if (stored.size === 0) {
     return {
       error: `No snapshots found for environment "${environment}"`,

package/src/lifecycle/scenario.ts

@@ -48,9 +48,10 @@ export interface ScenarioGivenFile {
 
 /**
  * `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.
+ * in the project's index store (one file per lexicon, read through
+ * ./snapshot-store.ts, #4519), replayed exactly as `chant lifecycle plan`
+ * reads its own prior snapshot. With no store (`none`) a scenario names a
+ * checked-in fixture instead.
  */
 export interface ScenarioGivenEnv {
   readonly kind: "env";

package/src/lifecycle/snapshot-store-fake.ts

@@ -0,0 +1,29 @@
+/**
+ * A {@link SnapshotStore} made of the methods a test supplies, every other
+ * method reading as empty (#4519). It imports nothing at runtime, so a
+ * `vi.mock` factory can load it while the modules the real store needs are
+ * themselves mocked.
+ */
+import type { SnapshotStore } from "./snapshot-store";
+
+export function fakeSnapshotStore(parts: Partial<SnapshotStore> = {}): SnapshotStore {
+  return {
+    kind: "git-ref",
+    where: "the test store",
+    writable: true,
+    write: async () => ({ written: true }),
+    readLatest: async () => null,
+    readAt: async () => null,
+    list: async () => [],
+    keys: async () => [],
+    environments: async () => [],
+    writeIndex: async () => ({ written: false, reason: "the test store keeps no index" }),
+    listIndex: async () => [],
+    readIndexAt: async () => null,
+    readIndexLatest: async () => null,
+    readIndexScope: async () => null,
+    fetch: async () => {},
+    publish: async () => ({ status: "local" }),
+    ...parts,
+  };
+}