@ybotok/loam 0.1.0-beta.2 → 0.2.0-alpha.1

package/dist/commands/subsystem/sync.js

@@ -0,0 +1,103 @@
+/**
+ * `loam subsystem sync` — the ONE repair for `subsystem.views-stale`:
+ * recompute the generated views file from the tree, write it when it
+ * differs, remove it when the tree has no subsystems, and say which.
+ *
+ * The write goes through the same lock + journaled transaction every docs
+ * writer uses (`commitStaged`), so a predecessor's interrupted commit is
+ * recovered first and a sync killed mid-swap is rolled forward by the next
+ * writer. Idempotent by construction: the expected bytes are a pure function
+ * of the tree and the committed landscape, so a second run reports `current`
+ * and writes nothing.
+ *
+ * The expected bytes come from `./txn/views.ts` — the same module every
+ * writer verb renders from, so sync and the transactions cannot disagree
+ * about what the file should say.
+ */
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { emitJson, fail } from "../../core/envelope/json.js";
+import { subsystemViewsPath } from "../../core/repo/paths.js";
+import { listFleetTree } from "../../core/repo/repo.js";
+import { stageWrites } from "../../core/staging/commit.js";
+import { InterruptedCommitError } from "../../core/staging/interrupted.js";
+import { acquireDocsLockWaiting, DocsBusyError, LOCK_WAIT_MS } from "../../core/staging/lock.js";
+import { recoverInterruptedCommit } from "../../core/staging/recovery/recover.js";
+import { commitStaged } from "../../core/staging/txn/transaction.js";
+import { viewsAgree } from "../../core/repo/tree/views.js";
+import { expectedViews } from "./txn/views.js";
+export async function runSync(docsDir, json) {
+    let releaseLock;
+    try {
+        releaseLock = await acquireDocsLockWaiting(docsDir, LOCK_WAIT_MS);
+    }
+    catch (err) {
+        if (!(err instanceof DocsBusyError))
+            throw err;
+        fail(json, "docs-busy", err.message);
+        return;
+    }
+    try {
+        // A predecessor's journal is recovered (or refused) before the tree is
+        // read: the views file itself may be the half-written one.
+        let recovered;
+        try {
+            recovered = await recoverInterruptedCommit(docsDir);
+        }
+        catch (err) {
+            if (!(err instanceof InterruptedCommitError))
+                throw err;
+            fail(json, "commit-interrupted", err.message);
+            return;
+        }
+        const tree = await listFleetTree(docsDir);
+        const expected = await expectedViews(docsDir, tree);
+        const path = subsystemViewsPath(docsDir);
+        const expectedBytes = expected === null ? null : Buffer.from(expected, "utf8");
+        // Content, not bytes: `viewsAgree` records why, beside the generator. A
+        // Windows clone hands this file back CRLF with not one fact changed, and a
+        // byte compare made `sync` answer `updated` and rewrite it LF — after which
+        // git shows the file permanently modified and the next checkout puts the
+        // CRLF back. `validate` stopped demanding that rewrite; `sync` must stop
+        // offering it, or the two disagree about the same file.
+        const actual = existsSync(path) ? await readFile(path, "utf8") : null;
+        if (viewsAgree(actual, expected)) {
+            report(json, { action: "current", subsystems: tree.subsystems.length, recovered });
+            return;
+        }
+        const action = actual === null ? "created" : expectedBytes === null ? "removed" : "updated";
+        const staged = await stageWrites([{ path, content: expectedBytes }]);
+        const committed = await commitStaged({ root: docsDir, command: "subsystem", rerun: "loam subsystem sync", target: "subsystems" }, staged, "synced");
+        if (!committed.ok) {
+            fail(json, committed.code, committed.message);
+            return;
+        }
+        report(json, { action, subsystems: tree.subsystems.length, recovered });
+    }
+    finally {
+        await releaseLock();
+    }
+}
+function report(json, out) {
+    if (json) {
+        emitJson({
+            command: "subsystem",
+            path: "architecture/subsystems.likec4",
+            action: out.action,
+            subsystems: out.subsystems,
+            ...(out.recovered === null ? {} : { recovered: out.recovered }),
+        });
+        return;
+    }
+    if (out.recovered !== null && out.recovered.outcome !== "consistent") {
+        console.log(`note: recovered an interrupted \`loam ${out.recovered.command}\` commit first (${out.recovered.outcome}).`);
+    }
+    const sentence = {
+        current: `architecture/subsystems.likec4 is current (${out.subsystems} subsystem(s)) — nothing to write.`,
+        created: `wrote architecture/subsystems.likec4 — ${out.subsystems} subsystem view(s).`,
+        updated: `updated architecture/subsystems.likec4 — ${out.subsystems} subsystem view(s).`,
+        removed: `removed architecture/subsystems.likec4 — the tree has no subsystems, so the generated file must be absent.`,
+    };
+    console.log(sentence[out.action]);
+}
+//# sourceMappingURL=sync.js.map

package/dist/commands/subsystem/sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync.js","sourceRoot":"","sources":["../../../src/commands/subsystem/sync.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `loam subsystem sync` — the ONE repair for `subsystem.views-stale`:\n * recompute the generated views file from the tree, write it when it\n * differs, remove it when the tree has no subsystems, and say which.\n *\n * The write goes through the same lock + journaled transaction every docs\n * writer uses (`commitStaged`), so a predecessor's interrupted commit is\n * recovered first and a sync killed mid-swap is rolled forward by the next\n * writer. Idempotent by construction: the expected bytes are a pure function\n * of the tree and the committed landscape, so a second run reports `current`\n * and writes nothing.\n *\n * The expected bytes come from `./txn/views.ts` — the same module every\n * writer verb renders from, so sync and the transactions cannot disagree\n * about what the file should say.\n */\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport type { DocsDir } from \"../../core/kernel/ids/dirs.js\";\nimport { emitJson, fail } from \"../../core/envelope/json.js\";\nimport { subsystemViewsPath } from \"../../core/repo/paths.js\";\nimport { listFleetTree } from \"../../core/repo/repo.js\";\nimport { stageWrites } from \"../../core/staging/commit.js\";\nimport { type CommitRecovery, InterruptedCommitError } from \"../../core/staging/interrupted.js\";\nimport { acquireDocsLockWaiting, DocsBusyError, LOCK_WAIT_MS } from \"../../core/staging/lock.js\";\nimport { recoverInterruptedCommit } from \"../../core/staging/recovery/recover.js\";\nimport { commitStaged } from \"../../core/staging/txn/transaction.js\";\nimport { viewsAgree } from \"../../core/repo/tree/views.js\";\nimport { expectedViews } from \"./txn/views.js\";\n\n/** What one sync did to the file. */\ntype SyncAction = \"current\" | \"created\" | \"updated\" | \"removed\";\n\nexport async function runSync(docsDir: DocsDir, json: boolean): Promise<void> {\n  let releaseLock: () => Promise<void>;\n  try {\n    releaseLock = await acquireDocsLockWaiting(docsDir, LOCK_WAIT_MS);\n  } catch (err) {\n    if (!(err instanceof DocsBusyError)) throw err;\n    fail(json, \"docs-busy\", err.message);\n    return;\n  }\n  try {\n    // A predecessor's journal is recovered (or refused) before the tree is\n    // read: the views file itself may be the half-written one.\n    let recovered: CommitRecovery | null;\n    try {\n      recovered = await recoverInterruptedCommit(docsDir);\n    } catch (err) {\n      if (!(err instanceof InterruptedCommitError)) throw err;\n      fail(json, \"commit-interrupted\", err.message);\n      return;\n    }\n\n    const tree = await listFleetTree(docsDir);\n    const expected = await expectedViews(docsDir, tree);\n    const path = subsystemViewsPath(docsDir);\n    const expectedBytes = expected === null ? null : Buffer.from(expected, \"utf8\");\n    // Content, not bytes: `viewsAgree` records why, beside the generator. A\n    // Windows clone hands this file back CRLF with not one fact changed, and a\n    // byte compare made `sync` answer `updated` and rewrite it LF — after which\n    // git shows the file permanently modified and the next checkout puts the\n    // CRLF back. `validate` stopped demanding that rewrite; `sync` must stop\n    // offering it, or the two disagree about the same file.\n    const actual = existsSync(path) ? await readFile(path, \"utf8\") : null;\n    if (viewsAgree(actual, expected)) {\n      report(json, { action: \"current\", subsystems: tree.subsystems.length, recovered });\n      return;\n    }\n    const action: SyncAction = actual === null ? \"created\" : expectedBytes === null ? \"removed\" : \"updated\";\n    const staged = await stageWrites([{ path, content: expectedBytes }]);\n    const committed = await commitStaged(\n      { root: docsDir, command: \"subsystem\", rerun: \"loam subsystem sync\", target: \"subsystems\" },\n      staged,\n      \"synced\",\n    );\n    if (!committed.ok) {\n      fail(json, committed.code, committed.message);\n      return;\n    }\n    report(json, { action, subsystems: tree.subsystems.length, recovered });\n  } finally {\n    await releaseLock();\n  }\n}\n\nfunction report(\n  json: boolean,\n  out: { action: SyncAction; subsystems: number; recovered: CommitRecovery | null },\n): void {\n  if (json) {\n    emitJson({\n      command: \"subsystem\",\n      path: \"architecture/subsystems.likec4\",\n      action: out.action,\n      subsystems: out.subsystems,\n      ...(out.recovered === null ? {} : { recovered: out.recovered }),\n    });\n    return;\n  }\n  if (out.recovered !== null && out.recovered.outcome !== \"consistent\") {\n    console.log(\n      `note: recovered an interrupted \\`loam ${out.recovered.command}\\` commit first (${out.recovered.outcome}).`,\n    );\n  }\n  const sentence: Record<SyncAction, string> = {\n    current: `architecture/subsystems.likec4 is current (${out.subsystems} subsystem(s)) — nothing to write.`,\n    created: `wrote architecture/subsystems.likec4 — ${out.subsystems} subsystem view(s).`,\n    updated: `updated architecture/subsystems.likec4 — ${out.subsystems} subsystem view(s).`,\n    removed: `removed architecture/subsystems.likec4 — the tree has no subsystems, so the generated file must be absent.`,\n  };\n  console.log(sentence[out.action]);\n}\n"]}

package/dist/commands/subsystem/txn/txn.js

@@ -0,0 +1,94 @@
+/**
+ * The shared commit window every subsystem WRITE verb goes through — `new`,
+ * `rm`, `move` and `rename` all land here: lock, recover a predecessor's
+ * journal, plan against the walked tree, regenerate the views file from the
+ * PLANNED post-state, commit through the journaled transaction (directory
+ * renames included), report. One window, because the views file must land in
+ * the same commit as whatever changed the tree — a marker without its view,
+ * or renames without theirs, is exactly the `subsystem.views-stale` state
+ * the generated file's contract refuses to leave between two commits.
+ */
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { fail } from "../../../core/envelope/json.js";
+import { subsystemViewsPath } from "../../../core/repo/paths.js";
+import { listFleetTree } from "../../../core/repo/repo.js";
+import { stageWrites } from "../../../core/staging/commit.js";
+import { InterruptedCommitError } from "../../../core/staging/interrupted.js";
+import { acquireDocsLock, DocsBusyError } from "../../../core/staging/lock.js";
+import { recoverInterruptedCommit } from "../../../core/staging/recovery/recover.js";
+import { commitStaged } from "../../../core/staging/txn/transaction.js";
+import {} from "../../../core/staging/writes.js";
+import { viewsAgree } from "../../../core/repo/tree/views.js";
+import { expectedViews } from "./views.js";
+/** The text tail a verb's success line carries about the generated file. */
+export function reportViews(views) {
+    return views === "current" ? "" : ` — architecture/subsystems.likec4 ${views}`;
+}
+/**
+ * Lock → recover → plan → stage (views included) → journaled commit → report.
+ * `plan` returning null means it already reported a refusal; nothing was
+ * staged and nothing is written.
+ */
+export async function commitWindow(docsDir, json, plan) {
+    let releaseLock;
+    try {
+        releaseLock = await acquireDocsLock(docsDir);
+    }
+    catch (err) {
+        if (!(err instanceof DocsBusyError))
+            throw err;
+        fail(json, "docs-busy", err.message);
+        return;
+    }
+    try {
+        let recovered;
+        try {
+            recovered = await recoverInterruptedCommit(docsDir);
+        }
+        catch (err) {
+            if (!(err instanceof InterruptedCommitError))
+                throw err;
+            fail(json, "commit-interrupted", err.message);
+            return;
+        }
+        const txn = await plan(await listFleetTree(docsDir));
+        if (txn === null)
+            return;
+        const path = subsystemViewsPath(docsDir);
+        const expected = await expectedViews(docsDir, txn.tree);
+        const bytes = expected === null ? null : Buffer.from(expected, "utf8");
+        // Content, not bytes — `viewsAgree` carries the reason. Without it every
+        // subsystem move on a Windows clone folded a rewrite of this file into its
+        // transaction that changed not one fact, and journalled it.
+        const current = existsSync(path) ? await readFile(path, "utf8") : null;
+        let views = "current";
+        const writes = [...txn.writes];
+        if (!viewsAgree(current, expected)) {
+            views = current === null ? "created" : bytes === null ? "removed" : "updated";
+            writes.push({ path, content: bytes });
+        }
+        const staged = await stageWrites(writes);
+        const committed = await commitStaged({
+            root: docsDir,
+            command: "subsystem",
+            rerun: "loam subsystem sync",
+            target: txn.target,
+            ...(txn.moves === undefined ? {} : { moves: txn.moves }),
+        }, staged, txn.what);
+        if (!committed.ok) {
+            const code = committed.code === "rollback-incomplete"
+                ? committed.code
+                : committed.raced
+                    ? (txn.racedCode ?? txn.failedCode ?? committed.code)
+                    : (txn.failedCode ?? committed.code);
+            fail(json, code, committed.message);
+            return;
+        }
+        await txn.report(views, recovered);
+    }
+    finally {
+        await releaseLock();
+    }
+}
+//# sourceMappingURL=txn.js.map

package/dist/commands/subsystem/txn/txn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"txn.js","sourceRoot":"","sources":["../../../../src/commands/subsystem/txn/txn.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The shared commit window every subsystem WRITE verb goes through — `new`,\n * `rm`, `move` and `rename` all land here: lock, recover a predecessor's\n * journal, plan against the walked tree, regenerate the views file from the\n * PLANNED post-state, commit through the journaled transaction (directory\n * renames included), report. One window, because the views file must land in\n * the same commit as whatever changed the tree — a marker without its view,\n * or renames without theirs, is exactly the `subsystem.views-stale` state\n * the generated file's contract refuses to leave between two commits.\n */\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport type { DocsDir } from \"../../../core/kernel/ids/dirs.js\";\nimport { fail, type ErrorCode } from \"../../../core/envelope/json.js\";\nimport { subsystemViewsPath } from \"../../../core/repo/paths.js\";\nimport { listFleetTree } from \"../../../core/repo/repo.js\";\nimport type { FleetTree } from \"../../../core/repo/tree/walk.js\";\nimport { stageWrites } from \"../../../core/staging/commit.js\";\nimport { type CommitRecovery, InterruptedCommitError } from \"../../../core/staging/interrupted.js\";\nimport { acquireDocsLock, DocsBusyError } from \"../../../core/staging/lock.js\";\nimport { recoverInterruptedCommit } from \"../../../core/staging/recovery/recover.js\";\nimport { commitStaged } from \"../../../core/staging/txn/transaction.js\";\nimport { type PlannedWrite } from \"../../../core/staging/writes.js\";\nimport { viewsAgree } from \"../../../core/repo/tree/views.js\";\nimport { expectedViews } from \"./views.js\";\n\nexport type ViewsAction = \"created\" | \"updated\" | \"removed\" | \"current\";\n\n/** The text tail a verb's success line carries about the generated file. */\nexport function reportViews(views: ViewsAction): string {\n  return views === \"current\" ? \"\" : ` — architecture/subsystems.likec4 ${views}`;\n}\n\n/** What one subsystem verb asks the shared commit window to land. */\nexport interface SubsystemTxn {\n  /** The journal's `target` — what this commit is FOR. */\n  target: string;\n  /** Marker writes (create/delete); the views write is derived and appended. */\n  writes: PlannedWrite[];\n  /** The tree AS THE COMMIT LEAVES IT — the views file is rendered from this. */\n  tree: FleetTree;\n  /** Directory renames, performed after the swaps, in this order. */\n  moves?: { from: string; to: string }[];\n  /** Remap of a RACED commit failure (new: a lost marker create is `already-exists`). */\n  racedCode?: ErrorCode;\n  /** Remap of a rolled-back commit failure (move: `move-failed` — no merge was computed). */\n  failedCode?: ErrorCode;\n  /** The rollback sentence's verb for half-state files. */\n  what: string;\n  report: (views: ViewsAction, recovered: CommitRecovery | null) => void | Promise<void>;\n}\n\n/**\n * Lock → recover → plan → stage (views included) → journaled commit → report.\n * `plan` returning null means it already reported a refusal; nothing was\n * staged and nothing is written.\n */\nexport async function commitWindow(\n  docsDir: DocsDir,\n  json: boolean,\n  plan: (tree: FleetTree) => Promise<SubsystemTxn | null>,\n): Promise<void> {\n  let releaseLock: () => Promise<void>;\n  try {\n    releaseLock = await acquireDocsLock(docsDir);\n  } catch (err) {\n    if (!(err instanceof DocsBusyError)) throw err;\n    fail(json, \"docs-busy\", err.message);\n    return;\n  }\n  try {\n    let recovered: CommitRecovery | null;\n    try {\n      recovered = await recoverInterruptedCommit(docsDir);\n    } catch (err) {\n      if (!(err instanceof InterruptedCommitError)) throw err;\n      fail(json, \"commit-interrupted\", err.message);\n      return;\n    }\n    const txn = await plan(await listFleetTree(docsDir));\n    if (txn === null) return;\n\n    const path = subsystemViewsPath(docsDir);\n    const expected = await expectedViews(docsDir, txn.tree);\n    const bytes = expected === null ? null : Buffer.from(expected, \"utf8\");\n    // Content, not bytes — `viewsAgree` carries the reason. Without it every\n    // subsystem move on a Windows clone folded a rewrite of this file into its\n    // transaction that changed not one fact, and journalled it.\n    const current = existsSync(path) ? await readFile(path, \"utf8\") : null;\n    let views: ViewsAction = \"current\";\n    const writes = [...txn.writes];\n    if (!viewsAgree(current, expected)) {\n      views = current === null ? \"created\" : bytes === null ? \"removed\" : \"updated\";\n      writes.push({ path, content: bytes });\n    }\n    const staged = await stageWrites(writes);\n    const committed = await commitStaged(\n      {\n        root: docsDir,\n        command: \"subsystem\",\n        rerun: \"loam subsystem sync\",\n        target: txn.target,\n        ...(txn.moves === undefined ? {} : { moves: txn.moves }),\n      },\n      staged,\n      txn.what,\n    );\n    if (!committed.ok) {\n      const code =\n        committed.code === \"rollback-incomplete\"\n          ? committed.code\n          : committed.raced\n            ? (txn.racedCode ?? txn.failedCode ?? committed.code)\n            : (txn.failedCode ?? committed.code);\n      fail(json, code, committed.message);\n      return;\n    }\n    await txn.report(views, recovered);\n  } finally {\n    await releaseLock();\n  }\n}\n"]}

package/dist/commands/subsystem/txn/views.js

@@ -0,0 +1,70 @@
+/**
+ * What the generated views file MUST say — the shared answer every subsystem
+ * writer and `subsystem sync` render from. A module beneath the verbs (in the
+ * txn/ subpackage) because the commit window and sync both consume it, and a
+ * second spelling of "what should the views say" would be a second chance to
+ * disagree with `validate`'s staleness check.
+ */
+import { existsSync } from "node:fs";
+import { relative, sep } from "node:path";
+import { loadFile } from "../../../core/c4/likec4.js";
+import { serviceDirOf } from "../../../core/kernel/ids/dirs.js";
+import { landscapePath } from "../../../core/repo/paths.js";
+import { renderSubsystemViews } from "../../../core/repo/tree/views.js";
+/**
+ * The landscape's elements for the member join, or the empty list when the
+ * map is absent or does not parse. Tolerant on purpose: sync must stay
+ * runnable in a repo whose landscape is broken — it renders what the
+ * committed bytes resolve (no includes), deterministically, and the next sync
+ * after the landscape is repaired catches the file up. `validate` skips the
+ * staleness question in exactly those states, so the two never contradict.
+ */
+export async function landscapeElements(docsDir) {
+    const path = landscapePath(docsDir);
+    if (!existsSync(path))
+        return [];
+    try {
+        const doc = await loadFile(path);
+        return doc.errors.length > 0 ? [] : doc.elements;
+    }
+    catch {
+        return [];
+    }
+}
+/** The bytes the views file must hold for this tree, or null for "must be absent". */
+export async function expectedViews(docsDir, tree) {
+    return renderSubsystemViews(tree, await landscapeElements(docsDir));
+}
+/**
+ * The tree AS THE RENAMES LEAVE IT, computed in memory: every dir under a
+ * moved root is remapped by prefix, and each entry's placement chain is
+ * re-derived from its remapped dir. The views file is rendered from this, so
+ * the commit lands file and renames agreeing — never from a re-walk that
+ * would have to happen between two states. Beside `expectedViews` because the
+ * two are one promise: what the commit renames and what the file says must
+ * come from the same in-memory answer.
+ */
+export function movedTree(tree, renames, servicesRoot) {
+    const remap = (dir) => {
+        for (const r of renames) {
+            if (dir === r.from || dir.startsWith(r.from + sep))
+                return r.to + dir.slice(r.from.length);
+        }
+        return dir;
+    };
+    const chainOf = (dir) => relative(servicesRoot, dir).split(sep);
+    return {
+        findings: tree.findings,
+        services: tree.services.map((s) => {
+            const dir = remap(s.dir);
+            // The constructor call records provenance: a readdir-established
+            // directory carried through a rename this same commit performs.
+            return { ...s, dir: serviceDirOf(dir), subsystem: chainOf(dir).slice(0, -1) };
+        }),
+        subsystems: tree.subsystems.map((s) => {
+            const dir = remap(s.dir);
+            return { ...s, dir, path: chainOf(dir) };
+        }),
+    };
+}
+//# sourceMappingURL=views.js.map

package/dist/commands/subsystem/txn/views.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"views.js","sourceRoot":"","sources":["../../../../src/commands/subsystem/txn/views.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAa,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,YAAY,EAAgB,MAAM,kCAAkC,CAAC;AAC9E,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AAGxE;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,OAAgB;IACtD,MAAM,IAAI,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IACpC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IACjC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC;QACjC,OAAO,GAAG,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC;IACnD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,sFAAsF;AACtF,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,OAAgB,EAAE,IAAe;IACnE,OAAO,oBAAoB,CAAC,IAAI,EAAE,MAAM,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC;AACtE,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,SAAS,CAAC,IAAe,EAAE,OAAuC,EAAE,YAAoB;IACtG,MAAM,KAAK,GAAG,CAAC,GAAW,EAAU,EAAE;QACpC,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;YACxB,IAAI,GAAG,KAAK,CAAC,CAAC,IAAI,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,GAAG,GAAG,CAAC;gBAAE,OAAO,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC7F,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC,CAAC;IACF,MAAM,OAAO,GAAG,CAAC,GAAW,EAAY,EAAE,CAAC,QAAQ,CAAC,YAAY,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAClF,OAAO;QACL,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;YAChC,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YACzB,iEAAiE;YACjE,gEAAgE;YAChE,OAAO,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,YAAY,CAAC,GAAG,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAChF,CAAC,CAAC;QACF,UAAU,EAAE,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;YACpC,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YACzB,OAAO,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAC3C,CAAC,CAAC;KACH,CAAC;AACJ,CAAC","sourcesContent":["/**\n * What the generated views file MUST say — the shared answer every subsystem\n * writer and `subsystem sync` render from. A module beneath the verbs (in the\n * txn/ subpackage) because the commit window and sync both consume it, and a\n * second spelling of \"what should the views say\" would be a second chance to\n * disagree with `validate`'s staleness check.\n */\nimport { existsSync } from \"node:fs\";\nimport { relative, sep } from \"node:path\";\nimport { loadFile, type Elem } from \"../../../core/c4/likec4.js\";\nimport { serviceDirOf, type DocsDir } from \"../../../core/kernel/ids/dirs.js\";\nimport { landscapePath } from \"../../../core/repo/paths.js\";\nimport { renderSubsystemViews } from \"../../../core/repo/tree/views.js\";\nimport type { FleetTree } from \"../../../core/repo/tree/walk.js\";\n\n/**\n * The landscape's elements for the member join, or the empty list when the\n * map is absent or does not parse. Tolerant on purpose: sync must stay\n * runnable in a repo whose landscape is broken — it renders what the\n * committed bytes resolve (no includes), deterministically, and the next sync\n * after the landscape is repaired catches the file up. `validate` skips the\n * staleness question in exactly those states, so the two never contradict.\n */\nexport async function landscapeElements(docsDir: DocsDir): Promise<Elem[]> {\n  const path = landscapePath(docsDir);\n  if (!existsSync(path)) return [];\n  try {\n    const doc = await loadFile(path);\n    return doc.errors.length > 0 ? [] : doc.elements;\n  } catch {\n    return [];\n  }\n}\n\n/** The bytes the views file must hold for this tree, or null for \"must be absent\". */\nexport async function expectedViews(docsDir: DocsDir, tree: FleetTree): Promise<string | null> {\n  return renderSubsystemViews(tree, await landscapeElements(docsDir));\n}\n\n/**\n * The tree AS THE RENAMES LEAVE IT, computed in memory: every dir under a\n * moved root is remapped by prefix, and each entry's placement chain is\n * re-derived from its remapped dir. The views file is rendered from this, so\n * the commit lands file and renames agreeing — never from a re-walk that\n * would have to happen between two states. Beside `expectedViews` because the\n * two are one promise: what the commit renames and what the file says must\n * come from the same in-memory answer.\n */\nexport function movedTree(tree: FleetTree, renames: { from: string; to: string }[], servicesRoot: string): FleetTree {\n  const remap = (dir: string): string => {\n    for (const r of renames) {\n      if (dir === r.from || dir.startsWith(r.from + sep)) return r.to + dir.slice(r.from.length);\n    }\n    return dir;\n  };\n  const chainOf = (dir: string): string[] => relative(servicesRoot, dir).split(sep);\n  return {\n    findings: tree.findings,\n    services: tree.services.map((s) => {\n      const dir = remap(s.dir);\n      // The constructor call records provenance: a readdir-established\n      // directory carried through a rename this same commit performs.\n      return { ...s, dir: serviceDirOf(dir), subsystem: chainOf(dir).slice(0, -1) };\n    }),\n    subsystems: tree.subsystems.map((s) => {\n      const dir = remap(s.dir);\n      return { ...s, dir, path: chainOf(dir) };\n    }),\n  };\n}\n"]}

package/dist/commands/unarchive/manifest.js

@@ -0,0 +1,160 @@
+/**
+ * The snapshot manifest, validated before a single byte is written back.
+ *
+ * `unarchive` says "I put your docs back", and that sentence must never be
+ * sayable over a pre-image edited in the archived feature directory since. Each
+ * entry carries the digest of what archive WROTE and the digest of what will be
+ * RESTORED, and this is where both are checked — version, timestamp, feature
+ * name, duplicate paths and all — so the restore below it can assume the file
+ * describes the archive it claims to.
+ */
+import { existsSync, lstatSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import {} from "../../core/envelope/json.js";
+import { resolveInside, resolvePortableFileInside } from "../../core/kernel/path-safety.js";
+import { isRecord } from "../../core/kernel/records.js";
+import { SNAPSHOT_COMPAT_VERSION, SNAPSHOT_DIR, SNAPSHOT_MANIFEST, SNAPSHOT_VERSION, } from "../../core/staging/snapshot.js";
+export class RestoreFailure extends Error {
+    code;
+    constructor(code, msg) {
+        super(msg);
+        this.code = code;
+    }
+}
+export async function readManifest(request) {
+    const { featureDir, docsDir, featureId, dirName } = request;
+    try {
+        const path = resolveInside(featureDir, join(SNAPSHOT_DIR, SNAPSHOT_MANIFEST), "snapshot manifest path");
+        if (!existsSync(path))
+            return null;
+        const parsed = JSON.parse(await readFile(path, "utf8"));
+        if (!isRecord(parsed))
+            return null;
+        // Version 3 is what archive writes; version 2 is read forever under its own
+        // literal-path rules, because version-2 snapshots already sit in archived
+        // features and travel with them across loam upgrades. Version 1 stays
+        // refused: it records nothing about its restore source.
+        if (typeof parsed.version !== "number")
+            return null;
+        if (parsed.version !== SNAPSHOT_VERSION && parsed.version !== SNAPSHOT_COMPAT_VERSION)
+            return null;
+        if (parsed.feature !== featureId || parsed.dirName !== dirName)
+            return null;
+        if (typeof parsed.archivedAt !== "string" || !isCanonicalIsoDate(parsed.archivedAt))
+            return null;
+        if (!Array.isArray(parsed.files))
+            return null;
+        const seen = new Set();
+        const files = [];
+        for (const raw of parsed.files) {
+            if (!isRecord(raw))
+                return null;
+            if (typeof raw.path !== "string" || typeof raw.existed !== "boolean")
+                return null;
+            if (typeof raw.after !== "string" || !/^[0-9a-f]{64}$/.test(raw.after))
+                return null;
+            // A manifest that claims a pre-image must say what it should hash to, and
+            // one that claims none must not. Either way it is a shape question, so it
+            // is answered here with the rest of them; whether the bytes MATCH is a
+            // different answer with its own code (`snapshot-corrupt`).
+            if (raw.existed ? typeof raw.before !== "string" || !/^[0-9a-f]{64}$/.test(raw.before) : raw.before !== null) {
+                return null;
+            }
+            const before = raw.existed ? raw.before : null;
+            if (seen.has(raw.path))
+                return null;
+            seen.add(raw.path);
+            // The version-3 shape rule, exact in both directions: a `services/` row
+            // carries its (service, artifact) key — that key is what version 3 IS,
+            // and a row without one is not a manifest this loam wrote — while a row
+            // anywhere else carries none, because nothing outside `services/` moves.
+            // Version-2 rows never carry the fields and are not asked to.
+            const key = readServiceKey(parsed.version, raw);
+            if (key === undefined)
+                return null;
+            // Where the file lives NOW. A re-keyed row resolves through the current
+            // enumeration — the whole point of the bump: the bytes land wherever the
+            // service lives today, not where it lived on the day of the archive. An
+            // id the enumeration does not answer falls back to the literal path
+            // (an absent service restores as a create, exactly as before).
+            let targetRel = raw.path;
+            if (key !== null) {
+                const current = request.serviceDirOf(key.service);
+                if (current !== null)
+                    targetRel = `${current}/${key.artifact}`;
+            }
+            // The realpath test stays on this side, and it is not negotiable: this
+            // path is WRITTEN through. A symlink that leaves the repo is
+            // indistinguishable, lexically, from a service directory the operator
+            // mounted on purpose — `escape/owned.txt` and `services/<svc>/spec.md`
+            // are both "inside docsDir" until something resolves them — so the only
+            // check that can refuse the first is the one that also refuses the
+            // second. Restoring is the write; `staging.ts` only reads and compares a
+            // digest, which is why its resolution of this same field can be lexical
+            // and this one cannot.
+            const target = resolvePortableFileInside(docsDir, targetRel, `snapshot path '${raw.path}'`);
+            let snapshot = null;
+            const snapshotRel = `${SNAPSHOT_DIR}/files/${raw.path}`;
+            if (raw.existed) {
+                // Resolve from the feature directory, which always exists. The `files/`
+                // directory legitimately does not exist when every archive write was a
+                // creation; anchoring here permits that case while still inspecting an
+                // existing `files` component for symlink escape.
+                snapshot = resolvePortableFileInside(featureDir, snapshotRel, `snapshot pre-image '${raw.path}'`);
+                // Archive writes plain files. A missing pre-image or a symlink (even an
+                // internally-contained one) is not the byte snapshot this manifest
+                // claims, so refuse before any destination is staged.
+                if (!existsSync(snapshot) || !lstatSync(snapshot).isFile())
+                    return null;
+            }
+            else {
+                const unexpected = resolvePortableFileInside(featureDir, snapshotRel, `snapshot pre-image '${raw.path}'`);
+                if (existsSync(unexpected))
+                    return null;
+            }
+            files.push({ path: raw.path, existed: raw.existed, after: raw.after, before, target, snapshot });
+        }
+        return {
+            // The version as WRITTEN, not as preferred: a caller looking at a
+            // validated manifest deserves to know which rules it was read under.
+            version: parsed.version,
+            feature: featureId,
+            dirName,
+            archivedAt: parsed.archivedAt,
+            files,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The (service, artifact) key of one manifest row, under its version's shape
+ * rule. Three answers: the key; null when the row legitimately carries none (a
+ * non-`services/` row, or any version-2 row — the key postdates version 2);
+ * undefined when the row breaks the rule and the manifest must be refused
+ * whole, because a half-keyed or wrongly-keyed row is not a record this loam
+ * wrote and nothing can say what else in the file to distrust.
+ */
+function readServiceKey(version, raw) {
+    if (version !== SNAPSHOT_VERSION)
+        return null;
+    const under = typeof raw.path === "string" && raw.path.startsWith("services/");
+    if (!under)
+        return raw.service === undefined && raw.artifact === undefined ? null : undefined;
+    // The id is a lookup key into the enumeration and the artifact is joined
+    // under the resolved directory, so the id must be a single path segment; the
+    // artifact's own containment is `resolvePortableFileInside`'s question.
+    if (typeof raw.service !== "string" || raw.service.length === 0 || raw.service.includes("/"))
+        return undefined;
+    if (typeof raw.artifact !== "string" || raw.artifact.length === 0)
+        return undefined;
+    return { service: raw.service, artifact: raw.artifact };
+}
+export function isCanonicalIsoDate(value) {
+    const millis = Date.parse(value);
+    return Number.isFinite(millis) && new Date(millis).toISOString() === value;
+}
+/** Remove `dir` and each empty ancestor, stopping short of `stopAt`. Best effort. */
+//# sourceMappingURL=manifest.js.map

package/dist/commands/unarchive/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../../src/commands/unarchive/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAkB,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,yBAAyB,EAAE,MAAM,kCAAkC,CAAC;AAC5F,OAAO,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AACxD,OAAO,EACL,uBAAuB,EACvB,YAAY,EACZ,iBAAiB,EACjB,gBAAgB,GAEjB,MAAM,gCAAgC,CAAC;AAExC,MAAM,OAAO,cAAe,SAAQ,KAAK;IAE5B,IAAI;IADf,YACW,IAAe,EACxB,GAAW;QAEX,KAAK,CAAC,GAAG,CAAC,CAAC;oBAHF,IAAI;IAIf,CAAC;CACF;AAiCD,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,OAAwB;IACzD,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IAC5D,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,aAAa,CACxB,UAAU,EACV,IAAI,CAAC,YAAY,EAAE,iBAAiB,CAAC,EACrC,wBAAwB,CACzB,CAAC;QACF,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;QACnC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAY,CAAC;QACnE,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;YAAE,OAAO,IAAI,CAAC;QACnC,4EAA4E;QAC5E,0EAA0E;QAC1E,sEAAsE;QACtE,wDAAwD;QACxD,IAAI,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QACpD,IAAI,MAAM,CAAC,OAAO,KAAK,gBAAgB,IAAI,MAAM,CAAC,OAAO,KAAK,uBAAuB;YAAE,OAAO,IAAI,CAAC;QACnG,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS,IAAI,MAAM,CAAC,OAAO,KAAK,OAAO;YAAE,OAAO,IAAI,CAAC;QAC5E,IAAI,OAAO,MAAM,CAAC,UAAU,KAAK,QAAQ,IAAI,CAAC,kBAAkB,CAAC,MAAM,CAAC,UAAU,CAAC;YAAE,OAAO,IAAI,CAAC;QACjG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAE9C,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;QAC/B,MAAM,KAAK,GAA6B,EAAE,CAAC;QAC3C,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;YAC/B,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;gBAAE,OAAO,IAAI,CAAC;YAChC,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,SAAS;gBAAE,OAAO,IAAI,CAAC;YAClF,IAAI,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC;gBAAE,OAAO,IAAI,CAAC;YACpF,0EAA0E;YAC1E,0EAA0E;YAC1E,uEAAuE;YACvE,2DAA2D;YAC3D,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,GAAG,CAAC,MAAM,KAAK,QAAQ,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;gBAC7G,OAAO,IAAI,CAAC;YACd,CAAC;YACD,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,CAAC,CAAE,GAAG,CAAC,MAAiB,CAAC,CAAC,CAAC,IAAI,CAAC;YAC3D,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC;gBAAE,OAAO,IAAI,CAAC;YACpC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAEnB,wEAAwE;YACxE,uEAAuE;YACvE,wEAAwE;YACxE,yEAAyE;YACzE,8DAA8D;YAC9D,MAAM,GAAG,GAAG,cAAc,CAAC,MAAM,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;YAChD,IAAI,GAAG,KAAK,SAAS;gBAAE,OAAO,IAAI,CAAC;YAEnC,wEAAwE;YACxE,yEAAyE;YACzE,wEAAwE;YACxE,oEAAoE;YACpE,+DAA+D;YAC/D,IAAI,SAAS,GAAG,GAAG,CAAC,IAAI,CAAC;YACzB,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;gBACjB,MAAM,OAAO,GAAG,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;gBAClD,IAAI,OAAO,KAAK,IAAI;oBAAE,SAAS,GAAG,GAAG,OAAO,IAAI,GAAG,CAAC,QAAQ,EAAE,CAAC;YACjE,CAAC;YACD,uEAAuE;YACvE,6DAA6D;YAC7D,sEAAsE;YACtE,uEAAuE;YACvE,wEAAwE;YACxE,mEAAmE;YACnE,yEAAyE;YACzE,wEAAwE;YACxE,uBAAuB;YACvB,MAAM,MAAM,GAAG,yBAAyB,CAAC,OAAO,EAAE,SAAS,EAAE,kBAAkB,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC;YAC5F,IAAI,QAAQ,GAAkB,IAAI,CAAC;YACnC,MAAM,WAAW,GAAG,GAAG,YAAY,UAAU,GAAG,CAAC,IAAI,EAAE,CAAC;YACxD,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;gBAChB,wEAAwE;gBACxE,uEAAuE;gBACvE,uEAAuE;gBACvE,iDAAiD;gBACjD,QAAQ,GAAG,yBAAyB,CAAC,UAAU,EAAE,WAAW,EAAE,uBAAuB,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC;gBAClG,wEAAwE;gBACxE,mEAAmE;gBACnE,sDAAsD;gBACtD,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,MAAM,EAAE;oBAAE,OAAO,IAAI,CAAC;YAC1E,CAAC;iBAAM,CAAC;gBACN,MAAM,UAAU,GAAG,yBAAyB,CAAC,UAAU,EAAE,WAAW,EAAE,uBAAuB,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC;gBAC1G,IAAI,UAAU,CAAC,UAAU,CAAC;oBAAE,OAAO,IAAI,CAAC;YAC1C,CAAC;YACD,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;QACnG,CAAC;QAED,OAAO;YACL,kEAAkE;YAClE,qEAAqE;YACrE,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,OAAO,EAAE,SAAS;YAClB,OAAO;YACP,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,KAAK;SACN,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,cAAc,CACrB,OAAe,EACf,GAA4B;IAE5B,IAAI,OAAO,KAAK,gBAAgB;QAAE,OAAO,IAAI,CAAC;IAC9C,MAAM,KAAK,GAAG,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,IAAI,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;IAC/E,IAAI,CAAC,KAAK;QAAE,OAAO,GAAG,CAAC,OAAO,KAAK,SAAS,IAAI,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;IAC9F,yEAAyE;IACzE,6EAA6E;IAC7E,wEAAwE;IACxE,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,IAAI,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAC/G,IAAI,OAAO,GAAG,CAAC,QAAQ,KAAK,QAAQ,IAAI,GAAG,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACpF,OAAO,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,QAAQ,EAAE,GAAG,CAAC,QAAQ,EAAE,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,KAAa;IAC9C,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACjC,OAAO,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,KAAK,KAAK,CAAC;AAC7E,CAAC;AAED,qFAAqF","sourcesContent":["/**\n * The snapshot manifest, validated before a single byte is written back.\n *\n * `unarchive` says \"I put your docs back\", and that sentence must never be\n * sayable over a pre-image edited in the archived feature directory since. Each\n * entry carries the digest of what archive WROTE and the digest of what will be\n * RESTORED, and this is where both are checked — version, timestamp, feature\n * name, duplicate paths and all — so the restore below it can assume the file\n * describes the archive it claims to.\n */\nimport { existsSync, lstatSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport { type ErrorCode } from \"../../core/envelope/json.js\";\nimport { resolveInside, resolvePortableFileInside } from \"../../core/kernel/path-safety.js\";\nimport { isRecord } from \"../../core/kernel/records.js\";\nimport {\n  SNAPSHOT_COMPAT_VERSION,\n  SNAPSHOT_DIR,\n  SNAPSHOT_MANIFEST,\n  SNAPSHOT_VERSION,\n  type SnapshotManifest,\n} from \"../../core/staging/snapshot.js\";\n\nexport class RestoreFailure extends Error {\n  constructor(\n    readonly code: ErrorCode,\n    msg: string,\n  ) {\n    super(msg);\n  }\n}\n\nexport interface ValidatedSnapshotEntry {\n  path: string;\n  existed: boolean;\n  after: string;\n  /** sha256 the pre-image beside the manifest must still have; null when archive created the destination. */\n  before: string | null;\n  /** Contained destination under the docs repo. */\n  target: string;\n  /** Contained pre-image, or null when archive created the destination. */\n  snapshot: string | null;\n}\n\nexport interface ValidatedSnapshotManifest extends Omit<SnapshotManifest, \"files\"> {\n  files: ValidatedSnapshotEntry[];\n}\n\n/**\n * `readManifest`'s inputs, as one object. `serviceDirOf` is the restore-time\n * half of the version-3 re-keying: a service id → its CURRENT docs-relative\n * directory per the enumeration, or null when no such service is enumerated.\n * Injected by the caller (which holds the enumeration) rather than resolved\n * here, so this module keeps validating one file against one repo state.\n */\nexport interface ManifestRequest {\n  featureDir: string;\n  docsDir: string;\n  featureId: string;\n  dirName: string;\n  serviceDirOf: (service: string) => string | null;\n}\n\nexport async function readManifest(request: ManifestRequest): Promise<ValidatedSnapshotManifest | null> {\n  const { featureDir, docsDir, featureId, dirName } = request;\n  try {\n    const path = resolveInside(\n      featureDir,\n      join(SNAPSHOT_DIR, SNAPSHOT_MANIFEST),\n      \"snapshot manifest path\",\n    );\n    if (!existsSync(path)) return null;\n    const parsed = JSON.parse(await readFile(path, \"utf8\")) as unknown;\n    if (!isRecord(parsed)) return null;\n    // Version 3 is what archive writes; version 2 is read forever under its own\n    // literal-path rules, because version-2 snapshots already sit in archived\n    // features and travel with them across loam upgrades. Version 1 stays\n    // refused: it records nothing about its restore source.\n    if (typeof parsed.version !== \"number\") return null;\n    if (parsed.version !== SNAPSHOT_VERSION && parsed.version !== SNAPSHOT_COMPAT_VERSION) return null;\n    if (parsed.feature !== featureId || parsed.dirName !== dirName) return null;\n    if (typeof parsed.archivedAt !== \"string\" || !isCanonicalIsoDate(parsed.archivedAt)) return null;\n    if (!Array.isArray(parsed.files)) return null;\n\n    const seen = new Set<string>();\n    const files: ValidatedSnapshotEntry[] = [];\n    for (const raw of parsed.files) {\n      if (!isRecord(raw)) return null;\n      if (typeof raw.path !== \"string\" || typeof raw.existed !== \"boolean\") return null;\n      if (typeof raw.after !== \"string\" || !/^[0-9a-f]{64}$/.test(raw.after)) return null;\n      // A manifest that claims a pre-image must say what it should hash to, and\n      // one that claims none must not. Either way it is a shape question, so it\n      // is answered here with the rest of them; whether the bytes MATCH is a\n      // different answer with its own code (`snapshot-corrupt`).\n      if (raw.existed ? typeof raw.before !== \"string\" || !/^[0-9a-f]{64}$/.test(raw.before) : raw.before !== null) {\n        return null;\n      }\n      const before = raw.existed ? (raw.before as string) : null;\n      if (seen.has(raw.path)) return null;\n      seen.add(raw.path);\n\n      // The version-3 shape rule, exact in both directions: a `services/` row\n      // carries its (service, artifact) key — that key is what version 3 IS,\n      // and a row without one is not a manifest this loam wrote — while a row\n      // anywhere else carries none, because nothing outside `services/` moves.\n      // Version-2 rows never carry the fields and are not asked to.\n      const key = readServiceKey(parsed.version, raw);\n      if (key === undefined) return null;\n\n      // Where the file lives NOW. A re-keyed row resolves through the current\n      // enumeration — the whole point of the bump: the bytes land wherever the\n      // service lives today, not where it lived on the day of the archive. An\n      // id the enumeration does not answer falls back to the literal path\n      // (an absent service restores as a create, exactly as before).\n      let targetRel = raw.path;\n      if (key !== null) {\n        const current = request.serviceDirOf(key.service);\n        if (current !== null) targetRel = `${current}/${key.artifact}`;\n      }\n      // The realpath test stays on this side, and it is not negotiable: this\n      // path is WRITTEN through. A symlink that leaves the repo is\n      // indistinguishable, lexically, from a service directory the operator\n      // mounted on purpose — `escape/owned.txt` and `services/<svc>/spec.md`\n      // are both \"inside docsDir\" until something resolves them — so the only\n      // check that can refuse the first is the one that also refuses the\n      // second. Restoring is the write; `staging.ts` only reads and compares a\n      // digest, which is why its resolution of this same field can be lexical\n      // and this one cannot.\n      const target = resolvePortableFileInside(docsDir, targetRel, `snapshot path '${raw.path}'`);\n      let snapshot: string | null = null;\n      const snapshotRel = `${SNAPSHOT_DIR}/files/${raw.path}`;\n      if (raw.existed) {\n        // Resolve from the feature directory, which always exists. The `files/`\n        // directory legitimately does not exist when every archive write was a\n        // creation; anchoring here permits that case while still inspecting an\n        // existing `files` component for symlink escape.\n        snapshot = resolvePortableFileInside(featureDir, snapshotRel, `snapshot pre-image '${raw.path}'`);\n        // Archive writes plain files. A missing pre-image or a symlink (even an\n        // internally-contained one) is not the byte snapshot this manifest\n        // claims, so refuse before any destination is staged.\n        if (!existsSync(snapshot) || !lstatSync(snapshot).isFile()) return null;\n      } else {\n        const unexpected = resolvePortableFileInside(featureDir, snapshotRel, `snapshot pre-image '${raw.path}'`);\n        if (existsSync(unexpected)) return null;\n      }\n      files.push({ path: raw.path, existed: raw.existed, after: raw.after, before, target, snapshot });\n    }\n\n    return {\n      // The version as WRITTEN, not as preferred: a caller looking at a\n      // validated manifest deserves to know which rules it was read under.\n      version: parsed.version,\n      feature: featureId,\n      dirName,\n      archivedAt: parsed.archivedAt,\n      files,\n    };\n  } catch {\n    return null;\n  }\n}\n\n/**\n * The (service, artifact) key of one manifest row, under its version's shape\n * rule. Three answers: the key; null when the row legitimately carries none (a\n * non-`services/` row, or any version-2 row — the key postdates version 2);\n * undefined when the row breaks the rule and the manifest must be refused\n * whole, because a half-keyed or wrongly-keyed row is not a record this loam\n * wrote and nothing can say what else in the file to distrust.\n */\nfunction readServiceKey(\n  version: number,\n  raw: Record<string, unknown>,\n): { service: string; artifact: string } | null | undefined {\n  if (version !== SNAPSHOT_VERSION) return null;\n  const under = typeof raw.path === \"string\" && raw.path.startsWith(\"services/\");\n  if (!under) return raw.service === undefined && raw.artifact === undefined ? null : undefined;\n  // The id is a lookup key into the enumeration and the artifact is joined\n  // under the resolved directory, so the id must be a single path segment; the\n  // artifact's own containment is `resolvePortableFileInside`'s question.\n  if (typeof raw.service !== \"string\" || raw.service.length === 0 || raw.service.includes(\"/\")) return undefined;\n  if (typeof raw.artifact !== \"string\" || raw.artifact.length === 0) return undefined;\n  return { service: raw.service, artifact: raw.artifact };\n}\n\nexport function isCanonicalIsoDate(value: string): boolean {\n  const millis = Date.parse(value);\n  return Number.isFinite(millis) && new Date(millis).toISOString() === value;\n}\n\n/** Remove `dir` and each empty ancestor, stopping short of `stopAt`. Best effort. */\n"]}