@intentius/chant 0.124.51 → 0.124.54

package/dist/lifecycle/snapshot-store.js

@@ -0,0 +1,832 @@
+/**
+ * The index store (#4519): one seam for every snapshot and every other index,
+ * with the store chosen per project.
+ *
+ * A snapshot is one kind of index, a chant project's observed resources. The
+ * same store holds what behold indexes from a direct cloud read and the
+ * graphs choudoufu and plunge print (INTENTIUS/behold#1025). Every index is
+ * derived, stamped, never read for a mutation decision, and safe to lose:
+ * losing the store costs history and the cost of observing again, never
+ * correctness. The rule has a test, ./index-store-load-bearing.test.ts.
+ *
+ * ## The seam
+ *
+ * {@link SnapshotStore}: write, read latest, list, read at, for snapshots;
+ * the same four for index versions. Every snapshot read and write in chant
+ * goes through it. The git plumbing in ./git.ts (`readSnapshot` and the rest)
+ * is now the read side of the orphan-branch store and nothing else.
+ *
+ * ## One logical key space, two families
+ *
+ * - `snapshots`: `<env>/<key>.json` and `_members/<member>/<env>/<key>.json`,
+ *   exactly the orphan branch's layout (`snapshotStorageKey`). A snapshot
+ *   keeps one key, and its history is the store's own: commits on a git ref,
+ *   object versions in a versioned bucket.
+ * - `index`: `<source path>/<scope path>/<observedAt>-<digest12>.json`
+ *   (./index-document.ts), one immutable object per read, written once and
+ *   never overwritten, with `scope.json` beside the versions.
+ *
+ * ## Stores
+ *
+ * | kind | snapshots | index versions |
+ * |---|---|---|
+ * | `git-ref` (default) | `refs/chant/snapshots`, root of the ref | `_index/...` on the same ref |
+ * | `local` | `<dir>/snapshots/...` | `<dir>/index/...` |
+ * | `s3` | `<prefix>/snapshots/...` | `<prefix>/index/...` |
+ * | `none` | dropped | dropped |
+ * | `orphan-branch` | read-only: `chant/lifecycle` | none |
+ *
+ * The default `git-ref` store also reads the `chant/lifecycle` branch when
+ * the ref has no answer, so snapshots written before #4519 stay readable. It
+ * never writes there. A project created after #4519 has no `chant/lifecycle`
+ * branch unless it writes an Op record: gates, run ledgers, deploy records,
+ * releases and the other Ops records are not an index and stay on the branch.
+ *
+ * ## Choosing a store
+ *
+ * `snapshots` in chant.config.ts, and these environment variables over it:
+ * `CHANT_SNAPSHOT_STORE` (`git-ref`, `local`, `s3`, `none`, `orphan-branch`),
+ * `CHANT_SNAPSHOT_STORE_DIR` (local), and `CHANT_SNAPSHOT_S3_BUCKET`,
+ * `_PREFIX`, `_REGION`, `_ENDPOINT`, `_ACCESS_KEY_ID`, `_SECRET_ACCESS_KEY`,
+ * `_SESSION_TOKEN` (s3). See ./snapshot-store-s3.ts for the credential rule.
+ *
+ * Secret masking happens before a store sees the data (./snapshot.ts and
+ * ../deep-observation.ts's one list), so no store holds a secret.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync, mkdtempSync, unlinkSync, rmdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { getRuntime } from "../runtime-adapter.js";
+import { NEXT_RELEASE } from "../release-floors.js";
+import { fetchLifecycle, ledgerDir, listFilesInDir, listLedgerTrees, listSnapshots as listOrphanSnapshots, readBlobFromPath, readRefSha, readSnapshotAt as readOrphanSnapshotAt, RefCASConflictError, updateRefCAS, } from "./git.js";
+import { ledgerRecordingOff } from "./no-record.js";
+import { INDEX_SCOPE_FILE, indexVersionName, isIndexVersionName, validateIndexDocument, } from "./index-document.js";
+import { S3Medium } from "./snapshot-store-s3.js";
+/** The first chant that writes snapshots through the store, to `refs/chant/snapshots` by default. */
+export const SNAPSHOT_STORE_FLOOR = NEXT_RELEASE;
+/** The ref the default store writes. */
+export const SNAPSHOT_REF = "refs/chant/snapshots";
+/** Where index versions sit on a git ref. The underscore keeps it clear of every environment name, as `_gates` and `_members` are. */
+export const GIT_INDEX_DIR = "_index";
+/** Every snapshot an environment holds, by key. The old `readEnvironmentSnapshots`, through a store. */
+export async function readEnvironmentSnapshotsFrom(store, environment, at) {
+    const out = new Map();
+    for (const key of await store.keys(environment, at)) {
+        const content = await store.readLatest(environment, key, at);
+        if (content !== null)
+            out.set(key, content);
+    }
+    return out;
+}
+const C_LOCALE = { LC_ALL: "C", LANGUAGE: "" };
+const ISO_TIME_RE = /^\d{4}-\d{2}-\d{2}T/;
+async function git(args, opts) {
+    return getRuntime().spawn(["git", ...args], { ...(opts.cwd ? { cwd: opts.cwd } : {}), ...(opts.stdin !== undefined ? { stdin: opts.stdin } : {}), env: { ...C_LOCALE, ...(opts.env ?? {}) } });
+}
+/** The remote a ref is pushed to: `origin` when it exists, else the first. */
+async function remoteOf(cwd) {
+    const result = await git(["remote"], { cwd });
+    if (result.exitCode !== 0)
+        return null;
+    const names = result.stdout.trim().split("\n").map((n) => n.trim()).filter(Boolean);
+    if (names.length === 0)
+        return null;
+    return names.includes("origin") ? "origin" : names[0];
+}
+/** `user.name`/`user.email` for a checkout that has none, as the ledger's own writes do (#2301). */
+async function identityEnv(cwd) {
+    const probe = await git(["var", "GIT_COMMITTER_IDENT"], { cwd });
+    if (probe.exitCode === 0)
+        return {};
+    const name = process.env.CHANT_LIFECYCLE_COMMITTER_NAME?.trim() || "chant";
+    const email = process.env.CHANT_LIFECYCLE_COMMITTER_EMAIL?.trim() || "chant@localhost";
+    return { GIT_AUTHOR_NAME: name, GIT_AUTHOR_EMAIL: email, GIT_COMMITTER_NAME: name, GIT_COMMITTER_EMAIL: email };
+}
+/**
+ * Commit files onto `ref`, keeping every other path the ref holds, with a
+ * compare-and-swap on the ref. Builds the tree in a scratch index, so the
+ * working tree, the real index and HEAD are never touched. A conflict with
+ * another writer is retried against the new tip: every caller writes a
+ * self-contained replacement or a new path, so a retry is always correct.
+ *
+ * Returns the new commit, or null when every `ifAbsent` file existed.
+ */
+export async function commitFilesToRef(ref, files, message, opts) {
+    const cwd = opts?.cwd;
+    const top = await git(["rev-parse", "--show-toplevel"], { cwd });
+    const root = top.exitCode === 0 && top.stdout.trim() !== "" ? top.stdout.trim() : cwd;
+    const blobs = [];
+    for (const f of files) {
+        if (f.path.split("/").some((s) => s === "" || s === "." || s === ".."))
+            throw new Error(`cannot write ${f.path} on ${ref}: not a clean path`);
+        const h = await git(["hash-object", "-w", "--stdin"], { cwd: root, stdin: f.content });
+        if (h.exitCode !== 0)
+            throw new Error(`cannot write ${f.path} on ${ref}: git hash-object failed: ${h.stderr.trim()}`);
+        blobs.push({ path: f.path, sha: h.stdout.trim(), ifAbsent: !!f.ifAbsent });
+    }
+    const ident = await identityEnv(root);
+    const scratch = mkdtempSync(join(tmpdir(), "chant-store-"));
+    const indexFile = join(scratch, "index");
+    const env = { ...ident, GIT_INDEX_FILE: indexFile };
+    let lastErr;
+    try {
+        for (let attempt = 1; attempt <= 5; attempt++) {
+            // With `parent` the commit builds on that commit (a remote tip) and swaps the ref from whatever it holds now.
+            const current = await readRefSha(ref, { cwd: root });
+            const tip = opts?.parent !== undefined ? opts.parent : current;
+            const read = await git(tip ? ["read-tree", tip] : ["read-tree", "--empty"], { cwd: root, env });
+            if (read.exitCode !== 0)
+                throw new Error(`cannot write ${ref}: git read-tree failed: ${read.stderr.trim()}`);
+            const existed = [];
+            const writes = [];
+            for (const b of blobs) {
+                if (b.ifAbsent && tip) {
+                    const there = await git(["cat-file", "-e", `${tip}:${b.path}`], { cwd: root });
+                    if (there.exitCode === 0) {
+                        existed.push(b.path);
+                        continue;
+                    }
+                }
+                writes.push(b);
+            }
+            if (writes.length === 0)
+                return { commit: null, existed };
+            for (const b of writes) {
+                const u = await git(["update-index", "--add", "--cacheinfo", `100644,${b.sha},${b.path}`], { cwd: root, env });
+                if (u.exitCode !== 0)
+                    throw new Error(`cannot write ${b.path} on ${ref}: git update-index failed: ${u.stderr.trim()}`);
+            }
+            const tree = await git(["write-tree"], { cwd: root, env });
+            if (tree.exitCode !== 0)
+                throw new Error(`cannot write ${ref}: git write-tree failed: ${tree.stderr.trim()}`);
+            const commit = await git(["commit-tree", ...(tip ? ["-p", tip] : []), "-m", message, tree.stdout.trim()], { cwd: root, env: ident });
+            if (commit.exitCode !== 0)
+                throw new Error(`cannot write ${ref}: git commit-tree failed: ${commit.stderr.trim()}`);
+            const sha = commit.stdout.trim();
+            try {
+                await updateRefCAS(ref, sha, current, { cwd: root });
+                return { commit: sha, existed };
+            }
+            catch (err) {
+                if (!(err instanceof RefCASConflictError))
+                    throw err;
+                lastErr = err;
+            }
+        }
+        throw lastErr;
+    }
+    finally {
+        try {
+            if (existsSync(indexFile))
+                unlinkSync(indexFile);
+            rmdirSync(scratch);
+        }
+        catch {
+            // A scratch directory left in tmpdir is harmless.
+        }
+    }
+}
+/** `refs/chant/snapshots` → `refs/chant/remote/snapshots`: where a fetch lands, so a read never rewinds local writes. */
+function trackingRefOf(ref) {
+    return ref.replace(/^refs\/chant\//, "refs/chant/remote/");
+}
+/**
+ * Fetch `ref` and fast-forward the local ref when it is behind. A local ref
+ * ahead of or diverged from the remote is kept as it is: its writes go out
+ * on the next {@link publishRef}, which rebases them.
+ */
+export async function fetchRefFastForward(ref, opts) {
+    const cwd = opts?.cwd;
+    const remote = await remoteOf(cwd);
+    if (!remote)
+        return "no-remote";
+    const tracking = trackingRefOf(ref);
+    const f = await git(["fetch", "--no-tags", remote, `+${ref}:${tracking}`], { cwd });
+    if (f.exitCode !== 0)
+        return /couldn't find remote ref|no such ref was fetched/i.test(f.stderr ?? "") ? "missing" : "failed";
+    const remoteSha = await readRefSha(tracking, { cwd });
+    if (!remoteSha)
+        return "missing";
+    const local = await readRefSha(ref, { cwd });
+    if (local === remoteSha)
+        return "fetched";
+    if (local === null) {
+        await updateRefCAS(ref, remoteSha, null, { cwd }).catch(() => undefined);
+        return "fetched";
+    }
+    const behind = await git(["merge-base", "--is-ancestor", local, remoteSha], { cwd });
+    if (behind.exitCode === 0) {
+        await updateRefCAS(ref, remoteSha, local, { cwd }).catch(() => undefined);
+        return "fetched";
+    }
+    return "kept";
+}
+/**
+ * Push `ref` under a lease on the remote tip last fetched. A refused push
+ * (another machine pushed first) fetches, commits `pending` again on the
+ * remote tip, and pushes once more, up to three times.
+ */
+export async function publishRef(ref, pending, message, opts) {
+    const cwd = opts?.cwd;
+    if (ledgerRecordingOff())
+        return { status: "nothing", detail: "recording is off for this run" };
+    const local = await readRefSha(ref, { cwd });
+    if (!local)
+        return { status: "nothing" };
+    const remote = await remoteOf(cwd);
+    if (!remote)
+        return { status: "local", detail: "no remote configured" };
+    const tracking = trackingRefOf(ref);
+    for (let attempt = 1; attempt <= 3; attempt++) {
+        const expected = await readRefSha(tracking, { cwd });
+        const tip = await readRefSha(ref, { cwd });
+        if (tip === expected)
+            return { status: "pushed", detail: `${remote} ${ref}` };
+        const push = await git(["push", "--no-verify", `--force-with-lease=${ref}:${expected ?? ""}`, remote, `${ref}:${ref}`], { cwd });
+        if (push.exitCode === 0) {
+            if (tip)
+                await git(["update-ref", tracking, tip], { cwd });
+            return { status: "pushed", detail: `${remote} ${ref}` };
+        }
+        // Refused: bring the remote in and put this process's writes on top of it.
+        const fetched = await fetchRefFastForward(ref, { cwd });
+        if (fetched === "failed")
+            return { status: "failed", detail: (push.stderr ?? "").trim().split("\n")[0] };
+        const remoteTip = await readRefSha(tracking, { cwd });
+        if (pending.size === 0 || !remoteTip)
+            return { status: "stale", detail: (push.stderr ?? "").trim().split("\n")[0] };
+        const files = [...pending].map(([path, content]) => ({ path, content }));
+        // Local commits that are not this process's writes are dropped here: a snapshot is observed again, never needed.
+        const rebuilt = await commitFilesToRef(ref, files, message, { cwd, parent: remoteTip });
+        if (rebuilt.commit === null)
+            return { status: "pushed", detail: `${remote} ${ref}` };
+    }
+    return { status: "stale", detail: `${remote} kept moving; run the command again` };
+}
+class GitRefMedium {
+    constructor(ref, cwd) {
+        this.ref = ref;
+        this.cwd = cwd;
+        /** This process's writes, by path, for {@link publishRef} to replay on a refused push. */
+        this.pending = new Map();
+    }
+    async get(path) {
+        const r = await git(["cat-file", "blob", `${this.ref}:${path}`], { cwd: this.cwd });
+        return r.exitCode === 0 ? r.stdout : null;
+    }
+    async put(path, content, opts) {
+        if (ledgerRecordingOff())
+            throw new NotRecorded();
+        const { commit, existed } = await commitFilesToRef(this.ref, [{ path, content, ifAbsent: opts?.ifAbsent }], opts?.message ?? "Index store write", { cwd: this.cwd });
+        if (existed.includes(path))
+            return { exists: true };
+        this.pending.set(path, content);
+        return { exists: false, ...(commit ? { version: commit } : {}) };
+    }
+    async list(dir) {
+        const tip = await readRefSha(this.ref, { cwd: this.cwd });
+        if (!tip)
+            return { files: [], dirs: [] };
+        const r = await git(["ls-tree", "--full-tree", dir === "" ? tip : `${tip}:${dir}`], { cwd: this.cwd });
+        const out = { files: [], dirs: [] };
+        if (r.exitCode !== 0)
+            return out;
+        for (const line of r.stdout.split("\n")) {
+            const m = line.match(/^\d+\s+(\w+)\s+[0-9a-f]+\t(.+)$/);
+            if (!m)
+                continue;
+            (m[1] === "tree" ? out.dirs : out.files).push(m[2]);
+        }
+        return out;
+    }
+    async history(dir) {
+        const tip = await readRefSha(this.ref, { cwd: this.cwd });
+        if (!tip)
+            return [];
+        const r = await git(["log", "--format=%H %aI %s", tip, ...(dir === "" ? [] : ["--", `:(top)${dir}`])], { cwd: this.cwd });
+        if (r.exitCode !== 0)
+            return [];
+        return r.stdout.trim().split("\n").filter(Boolean).map((line) => {
+            const [version, date, ...rest] = line.split(" ");
+            return { version, date, message: rest.join(" ") };
+        });
+    }
+    async getAt(path, version) {
+        const r = await git(["cat-file", "blob", `${version}:${path}`], { cwd: this.cwd });
+        return r.exitCode === 0 ? r.stdout : null;
+    }
+    async fetch() {
+        try {
+            await fetchRefFastForward(this.ref, { cwd: this.cwd });
+        }
+        catch {
+            // A fetch that fails leaves local history as it is, which every reader handles.
+        }
+    }
+    async publish() {
+        try {
+            return await publishRef(this.ref, this.pending, "Index store write", { cwd: this.cwd });
+        }
+        catch (err) {
+            return { status: "failed", detail: err instanceof Error ? err.message : String(err) };
+        }
+    }
+}
+class NotRecorded extends Error {
+}
+class LocalMedium {
+    constructor(root) {
+        this.root = root;
+    }
+    async get(path) {
+        try {
+            return readFileSync(join(this.root, path), "utf8");
+        }
+        catch {
+            return null;
+        }
+    }
+    async put(path, content, opts) {
+        const file = join(this.root, path);
+        mkdirSync(dirname(file), { recursive: true });
+        if (opts?.ifAbsent) {
+            try {
+                writeFileSync(file, content, { flag: "wx" });
+            }
+            catch (err) {
+                if (err.code === "EEXIST")
+                    return { exists: true };
+                throw err;
+            }
+        }
+        else {
+            const tmp = `${file}.${process.pid}.tmp`;
+            writeFileSync(tmp, content);
+            renameSync(tmp, file);
+        }
+        return { exists: false, version: statSync(file).mtime.toISOString() };
+    }
+    async list(dir) {
+        const out = { files: [], dirs: [] };
+        try {
+            for (const e of readdirSync(join(this.root, dir), { withFileTypes: true })) {
+                if (e.name.endsWith(".tmp"))
+                    continue;
+                (e.isDirectory() ? out.dirs : out.files).push(e.name);
+            }
+        }
+        catch {
+            // Absent: nothing there.
+        }
+        return out;
+    }
+    /** A directory keeps no history: one entry per file there now, at its modification time. */
+    async history(dir) {
+        const out = [];
+        const walk = async (d) => {
+            const l = await this.list(d);
+            for (const f of l.files) {
+                const rel = d === "" ? f : `${d}/${f}`;
+                const date = statSync(join(this.root, rel)).mtime.toISOString();
+                out.push({ version: date, date, message: rel, key: rel });
+            }
+            for (const sub of l.dirs)
+                await walk(d === "" ? sub : `${d}/${sub}`);
+        };
+        await walk(dir);
+        return out.sort((a, b) => (a.date < b.date ? 1 : a.date > b.date ? -1 : 0));
+    }
+    /** `latest`, or a time: the file as it is now, when it was written at or before that time. */
+    async getAt(path, version) {
+        const content = await this.get(path);
+        if (content === null || version === "latest")
+            return content;
+        if (!ISO_TIME_RE.test(version))
+            return null;
+        return statSync(join(this.root, path)).mtime.toISOString() <= new Date(version).toISOString() ? content : null;
+    }
+    async fetch() { }
+    async publish() {
+        return { status: "local", detail: this.root };
+    }
+}
+class S3StoreMedium {
+    constructor(s3) {
+        this.s3 = s3;
+    }
+    get(path) {
+        return this.s3.get(path);
+    }
+    async put(path, content, opts) {
+        const r = await this.s3.put(path, content, opts);
+        return { exists: r.exists, ...(r.versionId ? { version: r.versionId } : {}) };
+    }
+    async list(dir) {
+        const out = { files: [], dirs: [] };
+        for (const name of await this.s3.list(dir.replace(/\/$/, ""))) {
+            if (name.endsWith("/"))
+                out.dirs.push(name.slice(0, -1));
+            else
+                out.files.push(name);
+        }
+        return out;
+    }
+    /** The bucket's object versions under `dir`. Without versioning on, only the latest of each key. */
+    async history(dir) {
+        return (await this.s3.versions(dir.replace(/\/$/, ""))).map((v) => ({ version: v.versionId, date: v.lastModified, message: v.key, key: v.key }));
+    }
+    /** A version id, or a time: the newest version written at or before it. */
+    async getAt(path, version) {
+        if (!ISO_TIME_RE.test(version))
+            return this.s3.get(path, version);
+        const at = new Date(version).toISOString();
+        const versions = (await this.s3.versions(dirname(path))).filter((v) => v.key === path && new Date(v.lastModified).toISOString() <= at);
+        return versions.length === 0 ? null : this.s3.get(path, versions[0].versionId);
+    }
+    async fetch() { }
+    async publish() {
+        return { status: "pushed", detail: this.s3.where };
+    }
+}
+const isSnapshotFile = (name) => name.endsWith(".json") && name !== "observation-baseline.json";
+/** A store over one medium, for the `git-ref`, `local` and `s3` kinds. */
+class MediumStore {
+    constructor(kind, where, medium, layout, cwd) {
+        this.kind = kind;
+        this.where = where;
+        this.medium = medium;
+        this.layout = layout;
+        this.cwd = cwd;
+        this.writable = true;
+    }
+    loc(at) {
+        return { ...(this.cwd ? { cwd: this.cwd } : {}), ...(at ?? {}) };
+    }
+    async envDir(environment, at) {
+        return `${this.layout.snapshots}${await ledgerDir(environment, this.loc(at))}`;
+    }
+    async write(environment, key, json, at) {
+        const path = `${await this.envDir(environment, at)}/${key}.json`;
+        try {
+            const r = await this.medium.put(path, json, { message: "State snapshot" });
+            return { written: true, path, ...(r.version ? { version: r.version } : {}) };
+        }
+        catch (err) {
+            if (err instanceof NotRecorded)
+                return { written: false, path, reason: "recording is off for this run" };
+            throw err;
+        }
+    }
+    async readLatest(environment, key, at) {
+        return this.medium.get(`${await this.envDir(environment, at)}/${key}.json`);
+    }
+    async readAt(environment, key, version, at) {
+        return this.medium.getAt(`${await this.envDir(environment, at)}/${key}.json`, version);
+    }
+    async list(opts) {
+        const { environment, ...at } = opts ?? {};
+        const base = `${this.layout.snapshots}${await ledgerDir(environment ?? "", this.loc(at))}`.replace(/\/$/, "");
+        const all = await this.medium.history(base);
+        // A git ref's root also holds the index family; its commits are not snapshots.
+        return all.filter((v) => !(v.key ?? "").startsWith(this.layout.index) && v.message !== "Index version");
+    }
+    async keys(environment, at) {
+        const l = await this.medium.list(await this.envDir(environment, at));
+        return l.files.filter(isSnapshotFile).map((f) => f.slice(0, -".json".length)).sort();
+    }
+    async environments(at) {
+        const base = `${this.layout.snapshots}${await ledgerDir("", this.loc(at))}`.replace(/\/$/, "");
+        return (await this.medium.list(base)).dirs.filter((d) => !d.startsWith("_")).sort();
+    }
+    async writeIndex(doc) {
+        validateIndexDocument(doc);
+        const { stamp } = doc;
+        const dir = `${this.layout.index}${stamp.scopeKey}`;
+        const path = `${dir}/${indexVersionName(stamp.observedAt, stamp.digest)}`;
+        try {
+            await this.medium.put(`${dir}/${INDEX_SCOPE_FILE}`, `${JSON.stringify(stamp.scope, null, 2)}\n`, { ifAbsent: true, message: "Index version" });
+            const r = await this.medium.put(path, `${JSON.stringify(doc, null, 2)}\n`, { ifAbsent: true, message: "Index version" });
+            if (r.exists)
+                return { written: false, path, reason: "this version is already in the store, and a version is never overwritten" };
+            return { written: true, path, ...(r.version ? { version: r.version } : {}) };
+        }
+        catch (err) {
+            if (err instanceof NotRecorded)
+                return { written: false, path, reason: "recording is off for this run" };
+            throw err;
+        }
+    }
+    async listIndex(scopeKey) {
+        return (await this.medium.list(`${this.layout.index}${scopeKey}`)).files.filter(isIndexVersionName).sort();
+    }
+    async readIndexAt(scopeKey, version) {
+        if (!isIndexVersionName(version))
+            return null;
+        const text = await this.medium.get(`${this.layout.index}${scopeKey}/${version}`);
+        return text === null ? null : JSON.parse(text);
+    }
+    async readIndexLatest(scopeKey) {
+        const versions = await this.listIndex(scopeKey);
+        return versions.length === 0 ? null : this.readIndexAt(scopeKey, versions[versions.length - 1]);
+    }
+    async readIndexScope(scopeKey) {
+        const text = await this.medium.get(`${this.layout.index}${scopeKey}/${INDEX_SCOPE_FILE}`);
+        return text === null ? null : JSON.parse(text);
+    }
+    fetch() {
+        return this.medium.fetch();
+    }
+    publish() {
+        return this.medium.publish();
+    }
+}
+/** `none`: every write is dropped and every read is empty, which is every reader's fallback. */
+class NoneStore {
+    constructor() {
+        this.kind = "none";
+        this.where = "nowhere (snapshots are off)";
+        this.writable = false;
+        this.dropped = (path) => ({ written: false, ...(path ? { path } : {}), reason: "the snapshot store is none" });
+    }
+    async write(environment, key) {
+        return this.dropped(`${environment}/${key}.json`);
+    }
+    async readLatest() {
+        return null;
+    }
+    async readAt() {
+        return null;
+    }
+    async list() {
+        return [];
+    }
+    async keys() {
+        return [];
+    }
+    async environments() {
+        return [];
+    }
+    async writeIndex(doc) {
+        validateIndexDocument(doc);
+        return this.dropped();
+    }
+    async listIndex() {
+        return [];
+    }
+    async readIndexAt() {
+        return null;
+    }
+    async readIndexLatest() {
+        return null;
+    }
+    async readIndexScope() {
+        return null;
+    }
+    async fetch() { }
+    async publish() {
+        return { status: "nothing" };
+    }
+}
+/** `orphan-branch`: the snapshots on `chant/lifecycle`, read-only, so the ones written before #4519 stay readable. */
+class OrphanBranchStore {
+    constructor(cwd) {
+        this.cwd = cwd;
+        this.kind = "orphan-branch";
+        this.where = "chant/lifecycle (read-only)";
+        this.writable = false;
+    }
+    loc(at) {
+        return { ...(this.cwd ? { cwd: this.cwd } : {}), ...(at ?? {}) };
+    }
+    async write(environment, key) {
+        return { written: false, path: `${environment}/${key}.json`, reason: "the orphan-branch store is read-only; snapshots are written to refs/chant/snapshots" };
+    }
+    readLatest(environment, key, at) {
+        return readBlobFromPath(environment, `${key}.json`, this.loc(at));
+    }
+    readAt(environment, key, version, at) {
+        return readOrphanSnapshotAt(environment, key, version, this.loc(at));
+    }
+    async list(opts) {
+        const { environment: _env, ...at } = opts ?? {};
+        return (await listOrphanSnapshots(this.loc(at)))
+            .filter((e) => e.message === "State snapshot")
+            .map((e) => ({ version: e.commit, date: e.date, message: e.message }));
+    }
+    async keys(environment, at) {
+        return (await listFilesInDir(environment, this.loc(at))).filter(isSnapshotFile).map((f) => f.slice(0, -".json".length)).sort();
+    }
+    async environments(at) {
+        const out = [];
+        for (const t of await listLedgerTrees(this.loc(at))) {
+            if (t.startsWith("_"))
+                continue;
+            if ((await this.keys(t, at)).length > 0)
+                out.push(t);
+        }
+        return out.sort();
+    }
+    async writeIndex(doc) {
+        validateIndexDocument(doc);
+        return { written: false, reason: "the orphan-branch store is read-only and never held an index" };
+    }
+    async listIndex() {
+        return [];
+    }
+    async readIndexAt() {
+        return null;
+    }
+    async readIndexLatest() {
+        return null;
+    }
+    async readIndexScope() {
+        return null;
+    }
+    async fetch() {
+        try {
+            await fetchLifecycle(this.loc());
+        }
+        catch {
+            // Unreadable remote: local history is what there is.
+        }
+    }
+    async publish() {
+        return { status: "nothing" };
+    }
+}
+/**
+ * A store that writes to `primary` and reads `legacy` when `primary` has no
+ * answer: the default, `refs/chant/snapshots` over the old orphan branch.
+ */
+class FallbackStore {
+    constructor(primary, legacy) {
+        this.primary = primary;
+        this.legacy = legacy;
+    }
+    get kind() {
+        return this.primary.kind;
+    }
+    get where() {
+        return `${this.primary.where} (reading ${this.legacy.where} for older snapshots)`;
+    }
+    get writable() {
+        return this.primary.writable;
+    }
+    write(environment, key, json, at) {
+        return this.primary.write(environment, key, json, at);
+    }
+    async readLatest(environment, key, at) {
+        return (await this.primary.readLatest(environment, key, at)) ?? this.legacy.readLatest(environment, key, at);
+    }
+    async readAt(environment, key, version, at) {
+        // Both are git commits with the same layout, so one version id reads from either history.
+        return (await this.primary.readAt(environment, key, version, at)) ?? this.legacy.readAt(environment, key, version, at);
+    }
+    async list(opts) {
+        const merged = [...(await this.primary.list(opts)), ...(await this.legacy.list(opts))];
+        return merged.sort((a, b) => (a.date < b.date ? 1 : a.date > b.date ? -1 : 0));
+    }
+    async keys(environment, at) {
+        return [...new Set([...(await this.primary.keys(environment, at)), ...(await this.legacy.keys(environment, at))])].sort();
+    }
+    async environments(at) {
+        return [...new Set([...(await this.primary.environments(at)), ...(await this.legacy.environments(at))])].sort();
+    }
+    writeIndex(doc) {
+        return this.primary.writeIndex(doc);
+    }
+    listIndex(scopeKey) {
+        return this.primary.listIndex(scopeKey);
+    }
+    readIndexAt(scopeKey, version) {
+        return this.primary.readIndexAt(scopeKey, version);
+    }
+    readIndexLatest(scopeKey) {
+        return this.primary.readIndexLatest(scopeKey);
+    }
+    readIndexScope(scopeKey) {
+        return this.primary.readIndexScope(scopeKey);
+    }
+    async fetch(at) {
+        await this.primary.fetch(at);
+        await this.legacy.fetch(at);
+    }
+    publish(at) {
+        return this.primary.publish(at);
+    }
+}
+export const SNAPSHOT_STORE_KINDS = ["git-ref", "orphan-branch", "local", "s3", "none"];
+/** Default directory of a `local` store, relative to the project. */
+export const DEFAULT_LOCAL_STORE_DIR = ".chant/store";
+/**
+ * The store configuration in effect: `CHANT_SNAPSHOT_STORE` and its
+ * companions over `snapshots` in chant.config.ts over the default `git-ref`.
+ */
+export function snapshotStoreConfig(configured, env = process.env) {
+    const base = (configured && typeof configured === "object" ? configured : {});
+    const kind = (env.CHANT_SNAPSHOT_STORE?.trim() || base.store || "git-ref");
+    if (!SNAPSHOT_STORE_KINDS.includes(kind)) {
+        throw new Error(`snapshot store "${kind}" is not one of ${SNAPSHOT_STORE_KINDS.join(", ")}`);
+    }
+    const fromBase = base.store === kind ? base : {};
+    switch (kind) {
+        case "git-ref":
+            return { store: "git-ref", ...(typeof fromBase.ref === "string" ? { ref: fromBase.ref } : {}), ...(fromBase.readOrphanBranch === false ? { readOrphanBranch: false } : {}) };
+        case "orphan-branch":
+            return { store: "orphan-branch" };
+        case "none":
+            return { store: "none" };
+        case "local": {
+            const dir = env.CHANT_SNAPSHOT_STORE_DIR?.trim() || (typeof fromBase.dir === "string" ? fromBase.dir : undefined);
+            return { store: "local", ...(dir ? { dir } : {}) };
+        }
+        case "s3": {
+            const pick = (envName, key) => env[envName]?.trim() || (typeof fromBase[key] === "string" ? fromBase[key] : undefined);
+            const bucket = pick("CHANT_SNAPSHOT_S3_BUCKET", "bucket");
+            if (!bucket)
+                throw new Error("the s3 snapshot store needs a bucket: snapshots.bucket in chant.config.ts or CHANT_SNAPSHOT_S3_BUCKET");
+            const prefix = pick("CHANT_SNAPSHOT_S3_PREFIX", "prefix");
+            const region = pick("CHANT_SNAPSHOT_S3_REGION", "region");
+            const endpoint = pick("CHANT_SNAPSHOT_S3_ENDPOINT", "endpoint");
+            const creds = fromBase.credentials;
+            return {
+                store: "s3",
+                bucket,
+                ...(prefix ? { prefix } : {}),
+                ...(region ? { region } : {}),
+                ...(endpoint ? { endpoint } : {}),
+                ...(typeof fromBase.forcePathStyle === "boolean" ? { forcePathStyle: fromBase.forcePathStyle } : {}),
+                ...(creds ? { credentials: creds } : {}),
+            };
+        }
+    }
+}
+/** Build a store from its configuration. `cwd` is the project directory. */
+export function createSnapshotStore(config, opts) {
+    const cwd = opts?.cwd;
+    switch (config.store) {
+        case "git-ref": {
+            const ref = config.ref ?? SNAPSHOT_REF;
+            const store = new MediumStore("git-ref", ref, new GitRefMedium(ref, cwd), { snapshots: "", index: `${GIT_INDEX_DIR}/` }, cwd);
+            return config.readOrphanBranch === false ? store : new FallbackStore(store, new OrphanBranchStore(cwd));
+        }
+        case "orphan-branch":
+            return new OrphanBranchStore(cwd);
+        case "local": {
+            const root = resolve(cwd ?? process.cwd(), config.dir ?? DEFAULT_LOCAL_STORE_DIR);
+            return new MediumStore("local", root, new LocalMedium(root), { snapshots: "snapshots/", index: "index/" }, cwd);
+        }
+        case "s3": {
+            const { store: _s, ...settings } = config;
+            const s3 = new S3Medium(settings, { ...(opts?.fetch ? { fetch: opts.fetch } : {}), ...(opts?.env ? { env: opts.env } : {}) });
+            return new MediumStore("s3", s3.where, new S3StoreMedium(s3), { snapshots: "snapshots/", index: "index/" }, cwd);
+        }
+        case "none":
+            return new NoneStore();
+    }
+}
+const resolved = new Map();
+/**
+ * The project's store, built once per directory and configuration so a
+ * write and the publish after it share one instance. `config` is the
+ * project's loaded chant.config; without it the config is loaded from `cwd`
+ * upward, and a directory with none uses the default.
+ */
+export async function resolveSnapshotStore(opts) {
+    const cwd = resolve(opts?.cwd ?? process.cwd());
+    let configured = opts?.config?.snapshots;
+    if (opts?.config === undefined) {
+        try {
+            const { loadChantConfigUpward } = await import("../config.js");
+            configured = (await loadChantConfigUpward(cwd)).config.snapshots;
+        }
+        catch {
+            configured = undefined;
+        }
+    }
+    const config = snapshotStoreConfig(configured);
+    const cacheKey = `${cwd}\0${JSON.stringify(config)}`;
+    let store = resolved.get(cacheKey);
+    if (!store) {
+        store = createSnapshotStore(config, { cwd });
+        resolved.set(cacheKey, store);
+    }
+    return store;
+}
+/** Forget every resolved store. For tests. */
+export function resetResolvedSnapshotStores() {
+    resolved.clear();
+}
+/**
+ * The snapshot family as a {@link import("./ledger-port.js").LedgerReadPort}:
+ * `trees` are the environments, `list(env)` the snapshot files, `read` a file.
+ * `chant query` reads its `resources` and `snapshots` tables through this, so
+ * the tables are the same whichever store holds them.
+ */
+export function snapshotReadPort(store, at) {
+    return {
+        read: async (dir, file) => (file.endsWith(".json") ? store.readLatest(dir, file.slice(0, -".json".length), at) : null),
+        list: async (dir) => (await store.keys(dir, at)).map((k) => `${k}.json`),
+        trees: () => store.environments(at),
+    };
+}