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

package/dist/commands/{unarchive.js → unarchive/restore.js}

@@ -1,79 +1,27 @@
-import { existsSync, lstatSync } from "node:fs";
-import { readdir, readFile, rename, rmdir } from "node:fs/promises";
-import { dirname, join, relative } from "node:path";
-import { loadConfig } from "../core/config.js";
-import { emitJson, fail, repoPath, reportNoConfig } from "../core/json.js";
-import { resolveInside, resolvePortableFileInside } from "../core/path-safety.js";
-import { isRecord } from "../core/records.js";
-import { archiveDir as archiveRoot, featuresDir as featuresRoot, resolveFeature } from "../core/repo.js";
-import { sayRecovery } from "./archive.js";
-import { acquireDocsLock, clearCommitIntent, DocsBusyError, InterruptedCommitError, message, planWrite, quietRm, recoverInterruptedCommit, rollbackError, rollbackStaged, sha256, stageWrites, swapStaged, writeCommitIntent, SNAPSHOT_DIR, SNAPSHOT_MANIFEST, SNAPSHOT_VERSION, } from "../core/staging.js";
 /**
- * A commit-phase failure with its stable `--json` code attached — the mirror of
- * archive's discipline. `restore-failed` answers "can I trust the repo?" with
- * yes: nothing was restored, or everything was rolled back, and re-running can
- * work. `rollback-incomplete` is the code that demands a human: the restore
- * failed AND some files could not be put back — the message lists them.
- * Anything ELSE that escapes runUnarchive never touched the commit phase, so
- * the action handler reports it as `restore-failed`.
+ * Putting the docs back: read the snapshot, verify every pre-image, then write.
+ *
+ * The whole restore runs under the docs lock, and the verification is the point
+ * of the split — `unarchive` says "I put your docs back", and that sentence must
+ * never be sayable over a pre-image that was edited in the archived feature
+ * directory since. Each entry carries both the digest of what archive WROTE and
+ * the digest of what it will RESTORE, and a mismatch on either refuses.
  */
-class RestoreFailure extends Error {
-    code;
-    constructor(code, msg) {
-        super(msg);
-        this.code = code;
-    }
-}
-export function registerUnarchive(program) {
-    program
-        .command("unarchive")
-        .argument("<featureId>", "feature id, e.g. FEAT-101")
-        .description("Take back a `loam archive`: restore the living docs and re-open the feature")
-        .option("--json", "emit the machine contract instead of the human view")
-        .option("--force", "restore even if the living docs changed after the archive (discards those changes)")
-        .action(async (featureId, opts) => {
-        const json = opts.json === true;
-        try {
-            await runUnarchive(featureId, json, opts.force === true);
-        }
-        catch (err) {
-            const code = err instanceof RestoreFailure
-                ? err.code
-                : err instanceof InterruptedCommitError
-                    ? "commit-interrupted"
-                    : "restore-failed";
-            fail(json, code, `unarchive ${featureId} failed: ${message(err)}`);
-        }
-    });
-}
-async function runUnarchive(featureId, json, force) {
-    const config = await loadConfig();
-    if (!config) {
-        reportNoConfig(json);
-        return;
-    }
-    // The same lock archive takes, for the same reason: unarchive rewrites the
-    // living spec, contract and landscape from a snapshot, and an archive landing
-    // inside that window would have its merge silently reverted by our restore —
-    // or ours by its merge. One writer per docs repo, whichever direction it
-    // writes in.
-    let release;
-    try {
-        release = await acquireDocsLock(config.docsDir);
-    }
-    catch (err) {
-        if (err instanceof DocsBusyError)
-            throw new RestoreFailure("docs-busy", err.message);
-        throw err;
-    }
-    try {
-        await unarchiveLocked(config.docsDir, featureId, json, force);
-    }
-    finally {
-        await release();
-    }
-}
-async function unarchiveLocked(docsDir, featureId, json, force) {
+import { existsSync } from "node:fs";
+import { readdir, readFile, rename, rmdir } from "node:fs/promises";
+import { dirname, join, relative } from "node:path";
+import { emitJson, fail, repoPath } from "../../core/envelope/json.js";
+import { archiveDir as archiveRoot, featuresDir as featuresRoot } from "../../core/repo/paths.js";
+import { listServices, resolveFeature } from "../../core/repo/repo.js";
+import { docsRepoState } from "../../core/repo/state.js";
+import { sayRecovery } from "../archive/plan/refusal.js";
+import { quietRm, rollbackError, rollbackStaged, stageWrites, swapStaged, } from "../../core/staging/commit.js";
+import { clearCommitIntent, writeCommitIntent } from "../../core/staging/recovery/intent.js";
+import { recoverInterruptedCommit } from "../../core/staging/recovery/recover.js";
+import { SNAPSHOT_DIR } from "../../core/staging/snapshot.js";
+import { planWrite, sha256 } from "../../core/staging/writes.js";
+import { readManifest, RestoreFailure } from "./manifest.js";
+export async function unarchiveLocked(docsDir, featureId, json, force) {
     // Same first move as archive, under the same lock: a commit killed between two
     // renames is exactly the state an undo must not be computed on top of.
     const recovered = await recoverInterruptedCommit(docsDir);
@@ -97,7 +45,24 @@ async function unarchiveLocked(docsDir, featureId, json, force) {
         fail(json, "feature-active", `unarchive ${feature.id} — BLOCKED: features/${name} already exists. Remove or rename it, then re-run.`);
         return;
     }
-    const manifest = await readManifest(feature.dir, docsDir, feature.id, feature.dirName);
+    // The restore-time half of the snapshot's (service, artifact) re-keying: a
+    // version-3 entry restores into wherever its service lives TODAY, and the
+    // enumeration is the only thing that may say where that is. Built once here,
+    // as a map, so the manifest validation stays a pure question of one file
+    // against one repo state. "no-services" is tolerated the way `listFeatures`
+    // tolerates it: a docs repo whose `services/` is gone still restores by the
+    // literal paths (every id resolves to null), and it is `doctor`'s job to say
+    // the directory is missing — refusing the undo here would add a second,
+    // contradictory diagnosis.
+    const enumerated = docsRepoState(docsDir).kind === "ok" ? await listServices(docsDir) : [];
+    const serviceDirs = new Map(enumerated.map((s) => [s.id, repoPath(docsDir, s.dir)]));
+    const manifest = await readManifest({
+        featureDir: feature.dir,
+        docsDir,
+        featureId: feature.id,
+        dirName: feature.dirName,
+        serviceDirOf: (service) => serviceDirs.get(service) ?? null,
+    });
     if (manifest === null) {
         fail(json, "snapshot-missing", `unarchive ${feature.id} — BLOCKED: features/archive/${feature.dirName}/${SNAPSHOT_DIR}/ is missing or was written by a different loam. ` +
             `It was archived before loam recorded what it overwrote, and the previous text of a MODIFIED requirement exists nowhere else — ` +
@@ -196,6 +161,7 @@ async function unarchiveLocked(docsDir, featureId, json, force) {
     const removed = writes.filter((w) => w.content === null).map((w) => repoPath(docsDir, w.path));
     if (json) {
         emitJson({
+            command: "unarchive",
             feature: feature.id,
             dirName: feature.dirName,
             path: repoPath(docsDir, dest),
@@ -213,90 +179,11 @@ async function unarchiveLocked(docsDir, featureId, json, force) {
     console.log(`\n  reopened: features/archive/${feature.dirName} → features/${feature.dirName}`);
     console.log("  the living docs are back to what they said before the archive.");
 }
-async function readManifest(featureDir, docsDir, featureId, dirName) {
-    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;
-        if (parsed.version !== SNAPSHOT_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 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, raw.path, `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 {
-            version: SNAPSHOT_VERSION,
-            feature: featureId,
-            dirName,
-            archivedAt: parsed.archivedAt,
-            files,
-        };
-    }
-    catch {
-        return null;
-    }
-}
-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. */
+/**
+ * The snapshot manifest, or null when there is nothing this command can honour —
+ * absent, unreadable, or a layout version it would have to guess at. All three are
+ * the same answer to the caller: this feature cannot be unarchived automatically.
+ */
 async function pruneEmptyDirs(dir, stopAt) {
     let cur = dir;
     for (;;) {
@@ -314,4 +201,4 @@ async function pruneEmptyDirs(dir, stopAt) {
         cur = dirname(cur);
     }
 }
-//# sourceMappingURL=unarchive.js.map
+//# sourceMappingURL=restore.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"restore.js","sourceRoot":"","sources":["../../../src/commands/unarchive/restore.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Putting the docs back: read the snapshot, verify every pre-image, then write.\n *\n * The whole restore runs under the docs lock, and the verification is the point\n * of the split — `unarchive` says \"I put your docs back\", and that sentence must\n * never be sayable over a pre-image that was edited in the archived feature\n * directory since. Each entry carries both the digest of what archive WROTE and\n * the digest of what it will RESTORE, and a mismatch on either refuses.\n */\nimport { existsSync } from \"node:fs\";\nimport { readdir, readFile, rename, rmdir } from \"node:fs/promises\";\nimport { dirname, join, relative } from \"node:path\";\nimport { emitJson, fail, repoPath } from \"../../core/envelope/json.js\";\nimport { archiveDir as archiveRoot, featuresDir as featuresRoot } from \"../../core/repo/paths.js\";\nimport { listServices, resolveFeature } from \"../../core/repo/repo.js\";\nimport { docsRepoState } from \"../../core/repo/state.js\";\nimport { sayRecovery } from \"../archive/plan/refusal.js\";\nimport {\n  quietRm,\n  rollbackError,\n  rollbackStaged,\n  stageWrites,\n  swapStaged,\n} from \"../../core/staging/commit.js\";\nimport { clearCommitIntent, writeCommitIntent } from \"../../core/staging/recovery/intent.js\";\nimport { recoverInterruptedCommit } from \"../../core/staging/recovery/recover.js\";\nimport { SNAPSHOT_DIR } from \"../../core/staging/snapshot.js\";\nimport { planWrite, sha256, type PlannedWrite } from \"../../core/staging/writes.js\";\nimport { readManifest, RestoreFailure } from \"./manifest.js\";\nimport type { DocsDir } from \"../../core/kernel/ids/dirs.js\";\n\nexport async function unarchiveLocked(\n  docsDir: DocsDir,\n  featureId: string,\n  json: boolean,\n  force: boolean,\n): Promise<void> {\n  // Same first move as archive, under the same lock: a commit killed between two\n  // renames is exactly the state an undo must not be computed on top of.\n  const recovered = await recoverInterruptedCommit(docsDir);\n  if (recovered !== null && !json) sayRecovery(recovered);\n\n  const featuresDir = featuresRoot(docsDir);\n  const archiveDir = archiveRoot(docsDir);\n\n  const feature = await resolveFeature(docsDir, featureId, \"only\");\n  if (!feature) {\n    fail(json, \"unknown-target\", `No archived feature '${featureId}' under ${archiveDir}.`);\n    return;\n  }\n  const dest = join(featuresDir, feature.dirName);\n\n  // Refuse to clobber. A feature that is active again carries its own delta, and\n  // dropping the archived copy on top of it would bury work in flight. Resolved\n  // by the feature's OWN id, not the raw argument — the collision is with\n  // whatever answers to this feature's name, however the caller spelled it.\n  const active = await resolveFeature(docsDir, feature.id, \"exclude\");\n  if (active !== null || existsSync(dest)) {\n    const name = active?.dirName ?? feature.dirName;\n    fail(\n      json,\n      \"feature-active\",\n      `unarchive ${feature.id} — BLOCKED: features/${name} already exists. Remove or rename it, then re-run.`,\n    );\n    return;\n  }\n\n  // The restore-time half of the snapshot's (service, artifact) re-keying: a\n  // version-3 entry restores into wherever its service lives TODAY, and the\n  // enumeration is the only thing that may say where that is. Built once here,\n  // as a map, so the manifest validation stays a pure question of one file\n  // against one repo state. \"no-services\" is tolerated the way `listFeatures`\n  // tolerates it: a docs repo whose `services/` is gone still restores by the\n  // literal paths (every id resolves to null), and it is `doctor`'s job to say\n  // the directory is missing — refusing the undo here would add a second,\n  // contradictory diagnosis.\n  const enumerated = docsRepoState(docsDir).kind === \"ok\" ? await listServices(docsDir) : [];\n  const serviceDirs = new Map<string, string>(enumerated.map((s) => [s.id, repoPath(docsDir, s.dir)]));\n  const manifest = await readManifest({\n    featureDir: feature.dir,\n    docsDir,\n    featureId: feature.id,\n    dirName: feature.dirName,\n    serviceDirOf: (service: string): string | null => serviceDirs.get(service) ?? null,\n  });\n  if (manifest === null) {\n    fail(\n      json,\n      \"snapshot-missing\",\n      `unarchive ${feature.id} — BLOCKED: features/archive/${feature.dirName}/${SNAPSHOT_DIR}/ is missing or was written by a different loam. ` +\n        `It was archived before loam recorded what it overwrote, and the previous text of a MODIFIED requirement exists nowhere else — ` +\n        `restore the living docs from version control instead.`,\n    );\n    return;\n  }\n\n  // What archive wrote is recorded, so a file edited since can be told from one\n  // this archive is still the top of. Restoring over a later change is silent data\n  // loss, so it takes --force to say it was meant.\n  const writes: PlannedWrite[] = [];\n  const drifted: string[] = [];\n  // Pre-images whose bytes are not the bytes archive wrote down. Collected\n  // whole, then refused together: \"which files\" is what makes the message\n  // actionable, and no destination is staged until every one is accounted for.\n  const corrupt: string[] = [];\n  for (const entry of manifest.files) {\n    const current = existsSync(entry.target) ? await readFile(entry.target) : null;\n    const now = current === null ? null : sha256(current);\n    // Drift is \"restoring this would destroy something\", so a file already\n    // holding its OWN pre-image is not drifted — putting it back writes the\n    // same bytes. It is also the state an interrupted restore leaves behind\n    // (the repair finishes the swaps it can, then this command re-runs): the\n    // narrower test used to call every repaired file a later change and demand\n    // `--force` to discard this command's own half-finished undo.\n    const restored = entry.existed ? now === entry.before : now === null;\n    if (now !== entry.after && !restored) drifted.push(entry.path);\n    let before: Buffer | null = null;\n    if (entry.snapshot !== null) {\n      before = await readFile(entry.snapshot);\n      // The one check that was missing entirely. `after` describes what archive\n      // WROTE and is checked above; nothing described the bytes it would\n      // RESTORE, so a pre-image edited inside the archived feature — a bad\n      // merge, a rebase, an editor — was written back verbatim and this command\n      // said \"the living docs are back to what they said before the archive\"\n      // over text nobody ever wrote.\n      if (sha256(before) !== entry.before) corrupt.push(entry.path);\n    }\n    // A restore whose destination is GONE is a create, and takes the same\n    // no-clobber swap an archive's creates take: between the manifest read and\n    // the swap, another writer may have put that path back, and a rename would\n    // bury it. The same helper both commands use, so neither can decide\n    // differently about the same file.\n    writes.push(planWrite(entry.target, before));\n  }\n  if (corrupt.length > 0) {\n    fail(\n      json,\n      \"snapshot-corrupt\",\n      `unarchive ${feature.id} — BLOCKED: ${corrupt.length} snapshot pre-image(s) no longer match the digest archive ` +\n        `recorded for them, so restoring them would write text nobody authored: ${corrupt.join(\", \")}. ` +\n        `--force does not override this — it discards LATER changes to the living docs, and the damage here is to the ` +\n        `undo itself. Restore the living docs from version control instead.`,\n    );\n    return;\n  }\n  if (drifted.length > 0 && !force) {\n    fail(\n      json,\n      \"snapshot-stale\",\n      `unarchive ${feature.id} — BLOCKED: ${drifted.length} file(s) changed since the archive, so this is no longer an undo: ` +\n        `${drifted.join(\", \")}. Re-run with --force to restore anyway, discarding those changes.`,\n    );\n    return;\n  }\n\n  if (!json) {\n    console.log(`unarchive ${feature.id}\\n`);\n    if (drifted.length > 0) {\n      console.log(`⚠ discarding later changes to ${drifted.length} file(s) (--force):`);\n      for (const p of drifted) console.log(`  ⚠ ${p}`);\n      console.log(\"\");\n    }\n  }\n\n  const staged = await stageWrites(writes);\n  try {\n    // The same journal archive writes, in the other direction: a restore killed\n    // between two renames leaves the docs half-back, and the merged text it was\n    // replacing is recorded nowhere — so a repair FINISHES this restore rather\n    // than undoing it, from the same digest-checked pre-images.\n    await writeCommitIntent(\n      docsDir,\n      { command: \"unarchive\", restore: \"after\", feature: feature.id, moveFrom: feature.dir, moveTo: dest },\n      staged,\n    );\n    await swapStaged(staged);\n    await rename(feature.dir, dest);\n    await clearCommitIntent(docsDir);\n  } catch (err) {\n    // The code is a caller's answer to \"can I trust the repo?\": restore-failed\n    // means yes (rolled back), rollback-incomplete means look at it by hand —\n    // rollbackError's message lists the files that need one.\n    const failures = await rollbackStaged(staged);\n    await clearCommitIntent(docsDir);\n    const wrapped = rollbackError(err, failures);\n    throw new RestoreFailure(failures.length > 0 ? \"rollback-incomplete\" : \"restore-failed\", wrapped.message);\n  }\n\n  // The snapshot describes an archive that no longer exists; the empty directories\n  // are what the merge left behind. Both are tidying — neither can fail the undo.\n  await quietRm(join(dest, SNAPSHOT_DIR));\n  for (const w of writes) if (w.content === null) await pruneEmptyDirs(dirname(w.path), docsDir);\n  await pruneEmptyDirs(archiveDir, docsDir);\n\n  const restored = writes.filter((w) => w.content !== null).map((w) => repoPath(docsDir, w.path));\n  const removed = writes.filter((w) => w.content === null).map((w) => repoPath(docsDir, w.path));\n\n  if (json) {\n    emitJson({\n      command: \"unarchive\",\n      feature: feature.id,\n      dirName: feature.dirName,\n      path: repoPath(docsDir, dest),\n      restored,\n      removed,\n      discarded: drifted,\n      ...(recovered === null ? {} : { recovered }),\n    });\n    return;\n  }\n  for (const p of restored) console.log(`  restored: ${p}`);\n  for (const p of removed) console.log(`  removed:  ${p}`);\n  console.log(`\\n  reopened: features/archive/${feature.dirName} → features/${feature.dirName}`);\n  console.log(\"  the living docs are back to what they said before the archive.\");\n}\n\n/**\n * The snapshot manifest, or null when there is nothing this command can honour —\n * absent, unreadable, or a layout version it would have to guess at. All three are\n * the same answer to the caller: this feature cannot be unarchived automatically.\n */\n\nasync function pruneEmptyDirs(dir: string, stopAt: string): Promise<void> {\n  let cur = dir;\n  for (;;) {\n    const rel = relative(stopAt, cur);\n    if (rel === \"\" || rel.startsWith(\"..\")) return;\n    try {\n      if ((await readdir(cur)).length > 0) return;\n      await rmdir(cur);\n    } catch {\n      return;\n    }\n    cur = dirname(cur);\n  }\n}\n"]}

package/dist/commands/unarchive/unarchive.js

@@ -0,0 +1,67 @@
+import { loadConfig } from "../../core/envelope/config.js";
+import { fail, reportNoConfig } from "../../core/envelope/json.js";
+import { message } from "../../core/staging/commit.js";
+import { acquireDocsLock, DocsBusyError } from "../../core/staging/lock.js";
+import { InterruptedCommitError } from "../../core/staging/interrupted.js";
+import { unarchiveLocked } from "./restore.js";
+import { RestoreFailure } from "./manifest.js";
+/**
+ * A commit-phase failure with its stable `--json` code attached — the mirror of
+ * archive's discipline. `restore-failed` answers "can I trust the repo?" with
+ * yes: nothing was restored, or everything was rolled back, and re-running can
+ * work. `rollback-incomplete` is the code that demands a human: the restore
+ * failed AND some files could not be put back — the message lists them.
+ * Anything ELSE that escapes runUnarchive never touched the commit phase, so
+ * the action handler reports it as `restore-failed`.
+ */
+export function registerUnarchive(program) {
+    program
+        .command("unarchive")
+        .argument("<featureId>", "feature id, e.g. FEAT-101")
+        .description("Take back a `loam archive`: restore the living docs and re-open the feature")
+        .option("--json", "emit the machine contract instead of the human view")
+        .option("--force", "restore even if the living docs changed after the archive (discards those changes)")
+        .action(async (featureId, opts) => {
+        const json = opts.json === true;
+        try {
+            await runUnarchive(featureId, json, opts.force === true);
+        }
+        catch (err) {
+            const code = err instanceof RestoreFailure
+                ? err.code
+                : err instanceof InterruptedCommitError
+                    ? "commit-interrupted"
+                    : "restore-failed";
+            fail(json, code, `unarchive ${featureId} failed: ${message(err)}`);
+        }
+    });
+}
+async function runUnarchive(featureId, json, force) {
+    const loaded = await loadConfig();
+    if (loaded.kind !== "loaded") {
+        reportNoConfig(json, loaded);
+        return;
+    }
+    const config = loaded.config;
+    // The same lock archive takes, for the same reason: unarchive rewrites the
+    // living spec, contract and landscape from a snapshot, and an archive landing
+    // inside that window would have its merge silently reverted by our restore —
+    // or ours by its merge. One writer per docs repo, whichever direction it
+    // writes in.
+    let release;
+    try {
+        release = await acquireDocsLock(config.docsDir);
+    }
+    catch (err) {
+        if (err instanceof DocsBusyError)
+            throw new RestoreFailure("docs-busy", err.message);
+        throw err;
+    }
+    try {
+        await unarchiveLocked(config.docsDir, featureId, json, force);
+    }
+    finally {
+        await release();
+    }
+}
+//# sourceMappingURL=unarchive.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"unarchive.js","sourceRoot":"","sources":["../../../src/commands/unarchive/unarchive.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAC3D,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,OAAO,EAAE,MAAM,8BAA8B,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC5E,OAAO,EAAE,sBAAsB,EAAE,MAAM,mCAAmC,CAAC;AAC3E,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAuB/C;;;;;;;;GAQG;AAEH,MAAM,UAAU,iBAAiB,CAAC,OAAgB;IAChD,OAAO;SACJ,OAAO,CAAC,WAAW,CAAC;SACpB,QAAQ,CAAC,aAAa,EAAE,2BAA2B,CAAC;SACpD,WAAW,CAAC,6EAA6E,CAAC;SAC1F,MAAM,CAAC,QAAQ,EAAE,qDAAqD,CAAC;SACvE,MAAM,CAAC,SAAS,EAAE,oFAAoF,CAAC;SACvG,MAAM,CAAC,KAAK,EAAE,SAAiB,EAAE,IAAsB,EAAE,EAAE;QAC1D,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC;QAChC,IAAI,CAAC;YACH,MAAM,YAAY,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC;QAC3D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,GAAG,GAAG,YAAY,cAAc;gBACxC,CAAC,CAAC,GAAG,CAAC,IAAI;gBACV,CAAC,CAAC,GAAG,YAAY,sBAAsB;oBACrC,CAAC,CAAC,oBAAoB;oBACtB,CAAC,CAAC,gBAAgB,CAAC;YACvB,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,aAAa,SAAS,YAAY,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACrE,CAAC;IACH,CAAC,CAAC,CAAC;AACP,CAAC;AAED,KAAK,UAAU,YAAY,CAAC,SAAiB,EAAE,IAAa,EAAE,KAAc;IAC1E,MAAM,MAAM,GAAG,MAAM,UAAU,EAAE,CAAC;IAClC,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC7B,OAAO;IACT,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAC7B,2EAA2E;IAC3E,8EAA8E;IAC9E,6EAA6E;IAC7E,yEAAyE;IACzE,aAAa;IACb,IAAI,OAA4B,CAAC;IACjC,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,eAAe,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAClD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,aAAa;YAAE,MAAM,IAAI,cAAc,CAAC,WAAW,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;QACrF,MAAM,GAAG,CAAC;IACZ,CAAC;IACD,IAAI,CAAC;QACH,MAAM,eAAe,CAAC,MAAM,CAAC,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;IAChE,CAAC;YAAS,CAAC;QACT,MAAM,OAAO,EAAE,CAAC;IAClB,CAAC;AACH,CAAC","sourcesContent":["import type { Command } from \"commander\";\nimport { loadConfig } from \"../../core/envelope/config.js\";\nimport { fail, reportNoConfig } from \"../../core/envelope/json.js\";\nimport { message } from \"../../core/staging/commit.js\";\nimport { acquireDocsLock, DocsBusyError } from \"../../core/staging/lock.js\";\nimport { InterruptedCommitError } from \"../../core/staging/interrupted.js\";\nimport { unarchiveLocked } from \"./restore.js\";\nimport { RestoreFailure } from \"./manifest.js\";\n\n/**\n * `loam unarchive <FEAT>` — take back a `loam archive`.\n *\n * Not an inverse merge, and it cannot be one. Undoing the requirements axis would\n * mean restoring a MODIFIED requirement's PREVIOUS text, which appears nowhere:\n * the delta records what the requirement became, never what it was. The landscape\n * axis is no better — the merge drops the feature tags, so the added lines are\n * indistinguishable from lines that were always there. Anything reconstructed\n * from the archived feature would be a plausible guess at the old docs, which is\n * exactly the kind of quiet fiction the rest of loam exists to prevent.\n *\n * So archive writes the bytes down instead (`<feature>/.loam-before/`), and this\n * command puts them back. The snapshot is optional on restore: a feature archived\n * before it existed fails with a clear message rather than a crash.\n */\n\ninterface UnarchiveOptions {\n  json?: boolean;\n  force?: boolean;\n}\n\n/**\n * A commit-phase failure with its stable `--json` code attached — the mirror of\n * archive's discipline. `restore-failed` answers \"can I trust the repo?\" with\n * yes: nothing was restored, or everything was rolled back, and re-running can\n * work. `rollback-incomplete` is the code that demands a human: the restore\n * failed AND some files could not be put back — the message lists them.\n * Anything ELSE that escapes runUnarchive never touched the commit phase, so\n * the action handler reports it as `restore-failed`.\n */\n\nexport function registerUnarchive(program: Command): void {\n  program\n    .command(\"unarchive\")\n    .argument(\"<featureId>\", \"feature id, e.g. FEAT-101\")\n    .description(\"Take back a `loam archive`: restore the living docs and re-open the feature\")\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    .option(\"--force\", \"restore even if the living docs changed after the archive (discards those changes)\")\n    .action(async (featureId: string, opts: UnarchiveOptions) => {\n      const json = opts.json === true;\n      try {\n        await runUnarchive(featureId, json, opts.force === true);\n      } catch (err) {\n        const code = err instanceof RestoreFailure\n          ? err.code\n          : err instanceof InterruptedCommitError\n            ? \"commit-interrupted\"\n            : \"restore-failed\";\n        fail(json, code, `unarchive ${featureId} failed: ${message(err)}`);\n      }\n    });\n}\n\nasync function runUnarchive(featureId: string, json: boolean, force: boolean): Promise<void> {\n  const loaded = await loadConfig();\n  if (loaded.kind !== \"loaded\") {\n    reportNoConfig(json, loaded);\n    return;\n  }\n  const config = loaded.config;\n  // The same lock archive takes, for the same reason: unarchive rewrites the\n  // living spec, contract and landscape from a snapshot, and an archive landing\n  // inside that window would have its merge silently reverted by our restore —\n  // or ours by its merge. One writer per docs repo, whichever direction it\n  // writes in.\n  let release: () => Promise<void>;\n  try {\n    release = await acquireDocsLock(config.docsDir);\n  } catch (err) {\n    if (err instanceof DocsBusyError) throw new RestoreFailure(\"docs-busy\", err.message);\n    throw err;\n  }\n  try {\n    await unarchiveLocked(config.docsDir, featureId, json, force);\n  } finally {\n    await release();\n  }\n}\n"]}

package/dist/commands/validate/arch-coverage.js

@@ -0,0 +1,204 @@
+/**
+ * Whether the architecture a delta INTRODUCES is covered by a requirement that
+ * will actually merge.
+ *
+ * Three findings, one question asked three ways: `archedge.uncovered` (a
+ * scenario names the new edge — heuristic, warn-only), `c4.uncovered` (an
+ * arch.spec.md requirement covers the new element or edge — mechanical), and
+ * `covers.unknown` (the `Covers:` line resolves to something real). This is
+ * where agent-built code cuts its corners — the outbox, the retries, the alerts
+ * — because no business scenario was ever going to mention them.
+ *
+ * Split out of `validateFeature` because it is the only part of the feature
+ * target that needs the LIVING landscape: everything else there reads the
+ * feature directory alone. Keeping the lazy load and its two exemption sets in
+ * one module is what stops "new" being decided differently in three places.
+ */
+import { existsSync } from "node:fs";
+import { loadFile } from "../../core/c4/likec4.js";
+import { elementService, serviceResolver } from "../../core/c4/resolve/service.js";
+import {} from "../../core/kernel/ids/service.js";
+import { landscapePath as landscapeFile } from "../../core/repo/paths.js";
+import { locateServicePaths } from "../../core/repo/service-target.js";
+import { enumeratedServiceIds } from "../../core/repo/service-target.js";
+import {} from "../../core/vocabulary/report.js";
+import {} from "../../core/document/spec.js";
+import { coversEdge, coversElement } from "../../core/c4/arch.js";
+import { readHealth } from "../../core/vocabulary/health.js";
+import { FleetContext } from "../../core/fleet-context.js";
+import { ACTOR_KINDS, EXTERNAL_TAG } from "../../core/vocabulary/maturity.js";
+import { coversEntries, coversUnknownFindings } from "./checks/requirements.js";
+export async function deltaArchCoverage(delta) {
+    const { docsDir, elements, relationships, taggedEls, taggedRels, archDeltas, featureServices, scenarioText, preloadedLand, fleet, } = delta;
+    const findings = [];
+    // The delta's own element→service resolver, built once for the whole feature.
+    // `serviceOf` is a one-shot wrapper that rebuilds its index on every call, and
+    // the two loops below ask it up to five times per tagged edge — so a delta
+    // over a large model paid for one Map of every element per question asked.
+    // The enumerated fleet — `services/` plus the feature's own `specs/` names,
+    // where a service it introduces lives — rides into it, and into `baseSvcOf`
+    // below, which MUST resolve the same way or the already-living exemption
+    // keys never match: so an edge drawn into a modelled container
+    // (`payment.api`) grades against the service that owns it instead of a
+    // service called "api" that has never existed. An unenumerable services/
+    // degrades to the feature's own names, exactly what every caller got before
+    // the set existed.
+    const known = new Set([
+        ...(await enumeratedServiceIds(docsDir, fleet)),
+        ...featureServices,
+    ]);
+    const svcOf = serviceResolver(elements, known);
+    // Arch-edge coverage (heuristic, warn-only): each new tagged edge should be named by a scenario.
+    for (const r of taggedRels) {
+        const target = svcOf(r.target);
+        const covered = edgeCovered(target, r.title, scenarioText);
+        findings.push({
+            severity: covered ? "ok" : "warn",
+            code: covered ? "archedge.covered" : "archedge.uncovered",
+            subject: target,
+            message: `${svcOf(r.source)} → ${target}  "${r.title ?? ""}"${covered ? "" : "  — no scenario names it"}`,
+            text: { indent: 4, header: "arch-edge coverage (heuristic):" },
+        });
+    }
+    // The architecture spec axis, feature scope — the mechanical counterpart of
+    // the heuristic above. Every NEW tagged element and edge in the delta wants a
+    // `Covers:` line in one of the feature's arch.spec.md deltas (c4.uncovered):
+    // this is where agent-built code cuts its corners — the outbox, the retries,
+    // the alerts — because no business scenario was ever going to mention them.
+    // Grouping-only elements take the same exemptions the fleet map applies
+    // (person kinds, #external) — one set, in checks/vocabulary.ts, so "not a
+    // service" cannot mean two things. Warnings, never archive gates; `--strict`
+    // escalates.
+    //
+    // Only requirements the archive will MERGE grant coverage here. In a delta,
+    // BASE means "the living state, quoted": it merges nothing, emits no
+    // .feature, and yields no scenario.tested claim — so a Covers: line under a
+    // plain `## Requirements` quote is an obligation that ships nowhere, and
+    // counting it silenced c4.uncovered for free. (The service-scope pass keeps
+    // the unfiltered call: a LIVING spec is legitimately all BASE.)
+    const activeCovers = archDeltas.flatMap(({ reqs }) => coversEntries(reqs.filter((r) => r.kind === "ADDED" || r.kind === "MODIFIED")));
+    // What the living landscape ALREADY holds. A delta has to re-declare the
+    // elements its new edges attach to, and authors tag those re-declarations
+    // along with everything else — so a requirements-only feature that touches an
+    // existing service was told to write `Covers:` lines for architecture it is
+    // not adding. c4.uncovered is an obligation on NEW architecture; an element
+    // the living landscape already resolves is not new, whatever the tag says.
+    // Loaded lazily: a delta with nothing tagged never pays for the parse.
+    let living = preloadedLand;
+    const livingLandscape = async () => {
+        if (living === undefined) {
+            const lp = landscapeFile(docsDir);
+            living = existsSync(lp)
+                ? fleet === undefined
+                    ? await loadFile(lp)
+                    : await fleet.loadLikeC4(lp)
+                : null;
+        }
+        return living;
+    };
+    const alreadyLiving = async () => {
+        if (taggedEls.length === 0 && taggedRels.length === 0)
+            return null;
+        const doc = await livingLandscape();
+        return doc !== null && doc.errors.length === 0 ? doc : null;
+    };
+    const base = await alreadyLiving();
+    const baseSvcOf = base === null ? null : serviceResolver(base.elements, known);
+    const baseIds = new Set(base?.elements.map((e) => e.id) ?? []);
+    const baseServices = new Set((base?.elements ?? []).map(elementService));
+    // How a service→service pair is keyed, spelled ONCE. The two sides used to
+    // join with different separators — a NUL where the set was built, a space
+    // where it was queried — so the exemption never matched anything, and every
+    // edge a delta re-declares verbatim (which it must, to attach anything to
+    // it) was reported as new architecture nobody covers. The join is structural
+    // rather than a separator character: the last one was a NUL, and a raw NUL in
+    // a template literal makes the source read as binary to `file` and invisible
+    // to `grep` — which is how a one-character mismatch survived review.
+    const edgeKey = (source, target) => JSON.stringify([source, target]);
+    const baseEdges = new Set((base?.relationships ?? []).map((r) => edgeKey(baseSvcOf(r.source), baseSvcOf(r.target))));
+    for (const e of taggedEls) {
+        if (ACTOR_KINDS.has(e.kind.toLowerCase()) || e.tags.includes(EXTERNAL_TAG))
+            continue;
+        if (baseIds.has(e.id) || baseServices.has(elementService(e)))
+            continue;
+        if (activeCovers.some((c) => coversElement(c, e)))
+            continue;
+        findings.push({
+            severity: "warn",
+            code: "c4.uncovered",
+            subject: elementService(e),
+            message: `delta adds '${e.title}' (${e.id}) but no arch requirement covers it — add 'Covers: ${e.id}' to a specs/<svc>/arch.spec.md delta, or its architectural obligations ship unchecked`,
+        });
+    }
+    for (const r of taggedRels) {
+        if (baseEdges.has(edgeKey(svcOf(r.source), svcOf(r.target))))
+            continue;
+        if (activeCovers.some((c) => coversEdge(c, r, elements, known)))
+            continue;
+        findings.push({
+            severity: "warn",
+            code: "c4.uncovered",
+            subject: svcOf(r.target),
+            message: `delta adds edge ${svcOf(r.source)} → ${svcOf(r.target)} ("${r.title ?? ""}") but no arch requirement covers it — add 'Covers: ${r.source} -> ${r.target}' to a specs/<svc>/arch.spec.md delta`,
+        });
+    }
+    // covers.unknown, feature scope. Resolution looks at the delta itself, the
+    // living landscape, the service's own model and its health.yaml — a delta's
+    // arch requirement may cover an element it adds, one that already exists, or
+    // an alert the service declares. The landscape and each model are loaded
+    // lazily, and only when an entry fails against what is already in hand: the
+    // clean path never pays for a workspace spin.
+    if (archDeltas.some(({ reqs }) => coversEntries(reqs).length > 0)) {
+        const land = await livingLandscape();
+        const landParses = land !== null && land.errors.length === 0 ? land : null;
+        const baseElements = [...elements, ...(landParses?.elements ?? [])];
+        const baseRels = [...relationships, ...(landParses?.relationships ?? [])];
+        // A feature never brings topology through `delta.likec4` — a `deployment { }`
+        // block in one is refused by the merge — so the living map is the whole
+        // scope for a `node:` entry in a delta, exactly as it is in service scope.
+        const baseDeployment = landParses?.deployment;
+        for (const { service: svc, reqs } of archDeltas) {
+            // An unreadable living health.yaml mutes the alert:/sli: entries here
+            // exactly as in service scope — the health.invalid finding itself
+            // belongs to the service target, which owns the file's diagnosis.
+            const health = await readHealth((await locateServicePaths(docsDir, svc, fleet)).health);
+            let scope = {
+                elements: baseElements,
+                relationships: baseRels,
+                ...(baseDeployment === undefined ? {} : { deployment: baseDeployment }),
+                health: health.ids,
+                known,
+            };
+            const unresolved = coversUnknownFindings(reqs, { where: `${svc}: arch.spec.md`, subject: svc }, scope, health.unreadable);
+            if (unresolved.length > 0) {
+                const modelPath = (await locateServicePaths(docsDir, svc, fleet)).model;
+                const model = existsSync(modelPath)
+                    ? fleet === undefined
+                        ? await loadFile(modelPath)
+                        : await fleet.loadLikeC4(modelPath)
+                    : null;
+                if (model !== null && model.errors.length === 0) {
+                    scope = {
+                        elements: [...baseElements, ...model.elements],
+                        relationships: [...baseRels, ...model.relationships],
+                        health: health.ids,
+                        known,
+                    };
+                }
+                findings.push(...coversUnknownFindings(reqs, { where: `${svc}: arch.spec.md`, subject: svc }, scope, health.unreadable));
+            }
+        }
+    }
+    return findings;
+}
+/** Heuristic: an edge is "covered" if a scenario names the target or a keyword from the edge title. */
+function edgeCovered(target, title, scenarioText) {
+    if (scenarioText.includes(target.toLowerCase()))
+        return true;
+    for (const token of (title ?? "").split(/[^A-Za-z0-9]+/)) {
+        if (token.length >= 5 && scenarioText.includes(token.toLowerCase()))
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=arch-coverage.js.map

package/dist/commands/validate/arch-coverage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"arch-coverage.js","sourceRoot":"","sources":["../../../src/commands/validate/arch-coverage.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Whether the architecture a delta INTRODUCES is covered by a requirement that\n * will actually merge.\n *\n * Three findings, one question asked three ways: `archedge.uncovered` (a\n * scenario names the new edge — heuristic, warn-only), `c4.uncovered` (an\n * arch.spec.md requirement covers the new element or edge — mechanical), and\n * `covers.unknown` (the `Covers:` line resolves to something real). This is\n * where agent-built code cuts its corners — the outbox, the retries, the alerts\n * — because no business scenario was ever going to mention them.\n *\n * Split out of `validateFeature` because it is the only part of the feature\n * target that needs the LIVING landscape: everything else there reads the\n * feature directory alone. Keeping the lazy load and its two exemption sets in\n * one module is what stops \"new\" being decided differently in three places.\n */\nimport { existsSync } from \"node:fs\";\nimport { loadFile, type Elem, type LoadedDoc, type Rel } from \"../../core/c4/likec4.js\";\nimport { elementService, serviceResolver } from \"../../core/c4/resolve/service.js\";\nimport { type PathableService } from \"../../core/kernel/ids/service.js\";\nimport { landscapePath as landscapeFile } from \"../../core/repo/paths.js\";\nimport { locateServicePaths } from \"../../core/repo/service-target.js\";\nimport { enumeratedServiceIds } from \"../../core/repo/service-target.js\";\nimport { type Finding } from \"../../core/vocabulary/report.js\";\nimport { type Requirement } from \"../../core/document/spec.js\";\nimport { coversEdge, coversElement, type CoverageScope } from \"../../core/c4/arch.js\";\nimport { readHealth } from \"../../core/vocabulary/health.js\";\nimport { FleetContext } from \"../../core/fleet-context.js\";\nimport { ACTOR_KINDS, EXTERNAL_TAG } from \"../../core/vocabulary/maturity.js\";\nimport { coversEntries, coversUnknownFindings } from \"./checks/requirements.js\";\nimport type { DocsDir } from \"../../core/kernel/ids/dirs.js\";\n\n/** One feature delta's architecture, and everything needed to decide what in it is new. */\nexport interface DeltaArch {\n  docsDir: DocsDir;\n  /** Every element the delta declares — the resolver's index, and `coversEdge`'s scope. */\n  elements: Elem[];\n  /** Every relationship the delta declares. */\n  relationships: Rel[];\n  /** The delta's own additions: elements and edges carrying the feature id as a tag. */\n  taggedEls: Elem[];\n  taggedRels: Rel[];\n  /** Each addressed service's arch.spec.md delta, in enumeration order. */\n  archDeltas: Array<{ service: PathableService; reqs: Requirement[] }>;\n  /**\n   * Every service the feature's `specs/` addresses — not just the ones with an\n   * arch delta. The resolver's fleet set unions these in because a service the\n   * feature INTRODUCES has no `services/` directory yet, and without its name\n   * an edge into that service's own modelled container resolved to the\n   * container's title — a phantom the fleet half alone cannot rule out.\n   */\n  featureServices: PathableService[];\n  /** Every scenario the feature's deltas carry, lowercased — the heuristic's haystack. */\n  scenarioText: string;\n  /** The living landscape under --all; undefined means \"load it if you need it\", null \"there is none\". */\n  preloadedLand?: LoadedDoc | null;\n  fleet?: FleetContext;\n}\n\nexport async function deltaArchCoverage(delta: DeltaArch): Promise<Finding[]> {\n  const {\n    docsDir,\n    elements,\n    relationships,\n    taggedEls,\n    taggedRels,\n    archDeltas,\n    featureServices,\n    scenarioText,\n    preloadedLand,\n    fleet,\n  } = delta;\n  const findings: Finding[] = [];\n\n  // The delta's own element→service resolver, built once for the whole feature.\n  // `serviceOf` is a one-shot wrapper that rebuilds its index on every call, and\n  // the two loops below ask it up to five times per tagged edge — so a delta\n  // over a large model paid for one Map of every element per question asked.\n  // The enumerated fleet — `services/` plus the feature's own `specs/` names,\n  // where a service it introduces lives — rides into it, and into `baseSvcOf`\n  // below, which MUST resolve the same way or the already-living exemption\n  // keys never match: so an edge drawn into a modelled container\n  // (`payment.api`) grades against the service that owns it instead of a\n  // service called \"api\" that has never existed. An unenumerable services/\n  // degrades to the feature's own names, exactly what every caller got before\n  // the set existed.\n  const known: ReadonlySet<string> = new Set<string>([\n    ...(await enumeratedServiceIds(docsDir, fleet)),\n    ...featureServices,\n  ]);\n  const svcOf = serviceResolver(elements, known);\n\n  // Arch-edge coverage (heuristic, warn-only): each new tagged edge should be named by a scenario.\n  for (const r of taggedRels) {\n    const target = svcOf(r.target);\n    const covered = edgeCovered(target, r.title, scenarioText);\n    findings.push({\n      severity: covered ? \"ok\" : \"warn\",\n      code: covered ? \"archedge.covered\" : \"archedge.uncovered\",\n      subject: target,\n      message: `${svcOf(r.source)} → ${target}  \"${r.title ?? \"\"}\"${covered ? \"\" : \"  — no scenario names it\"}`,\n      text: { indent: 4, header: \"arch-edge coverage (heuristic):\" },\n    });\n  }\n\n  // The architecture spec axis, feature scope — the mechanical counterpart of\n  // the heuristic above. Every NEW tagged element and edge in the delta wants a\n  // `Covers:` line in one of the feature's arch.spec.md deltas (c4.uncovered):\n  // this is where agent-built code cuts its corners — the outbox, the retries,\n  // the alerts — because no business scenario was ever going to mention them.\n  // Grouping-only elements take the same exemptions the fleet map applies\n  // (person kinds, #external) — one set, in checks/vocabulary.ts, so \"not a\n  // service\" cannot mean two things. Warnings, never archive gates; `--strict`\n  // escalates.\n  //\n  // Only requirements the archive will MERGE grant coverage here. In a delta,\n  // BASE means \"the living state, quoted\": it merges nothing, emits no\n  // .feature, and yields no scenario.tested claim — so a Covers: line under a\n  // plain `## Requirements` quote is an obligation that ships nowhere, and\n  // counting it silenced c4.uncovered for free. (The service-scope pass keeps\n  // the unfiltered call: a LIVING spec is legitimately all BASE.)\n  const activeCovers = archDeltas.flatMap(({ reqs }) =>\n    coversEntries(reqs.filter((r) => r.kind === \"ADDED\" || r.kind === \"MODIFIED\")),\n  );\n\n  // What the living landscape ALREADY holds. A delta has to re-declare the\n  // elements its new edges attach to, and authors tag those re-declarations\n  // along with everything else — so a requirements-only feature that touches an\n  // existing service was told to write `Covers:` lines for architecture it is\n  // not adding. c4.uncovered is an obligation on NEW architecture; an element\n  // the living landscape already resolves is not new, whatever the tag says.\n  // Loaded lazily: a delta with nothing tagged never pays for the parse.\n  let living: LoadedDoc | null | undefined = preloadedLand;\n  const livingLandscape = async (): Promise<LoadedDoc | null> => {\n    if (living === undefined) {\n      const lp = landscapeFile(docsDir);\n      living = existsSync(lp)\n        ? fleet === undefined\n          ? await loadFile(lp)\n          : await fleet.loadLikeC4(lp)\n        : null;\n    }\n    return living;\n  };\n  const alreadyLiving = async (): Promise<LoadedDoc | null> => {\n    if (taggedEls.length === 0 && taggedRels.length === 0) return null;\n    const doc = await livingLandscape();\n    return doc !== null && doc.errors.length === 0 ? doc : null;\n  };\n  const base = await alreadyLiving();\n  const baseSvcOf = base === null ? null : serviceResolver(base.elements, known);\n  const baseIds = new Set(base?.elements.map((e) => e.id) ?? []);\n  const baseServices = new Set((base?.elements ?? []).map(elementService));\n  // How a service→service pair is keyed, spelled ONCE. The two sides used to\n  // join with different separators — a NUL where the set was built, a space\n  // where it was queried — so the exemption never matched anything, and every\n  // edge a delta re-declares verbatim (which it must, to attach anything to\n  // it) was reported as new architecture nobody covers. The join is structural\n  // rather than a separator character: the last one was a NUL, and a raw NUL in\n  // a template literal makes the source read as binary to `file` and invisible\n  // to `grep` — which is how a one-character mismatch survived review.\n  const edgeKey = (source: string, target: string): string => JSON.stringify([source, target]);\n  const baseEdges = new Set(\n    (base?.relationships ?? []).map((r) => edgeKey(baseSvcOf!(r.source), baseSvcOf!(r.target))),\n  );\n\n  for (const e of taggedEls) {\n    if (ACTOR_KINDS.has(e.kind.toLowerCase()) || e.tags.includes(EXTERNAL_TAG)) continue;\n    if (baseIds.has(e.id) || baseServices.has(elementService(e))) continue;\n    if (activeCovers.some((c) => coversElement(c, e))) continue;\n    findings.push({\n      severity: \"warn\",\n      code: \"c4.uncovered\",\n      subject: elementService(e),\n      message: `delta adds '${e.title}' (${e.id}) but no arch requirement covers it — add 'Covers: ${e.id}' to a specs/<svc>/arch.spec.md delta, or its architectural obligations ship unchecked`,\n    });\n  }\n  for (const r of taggedRels) {\n    if (baseEdges.has(edgeKey(svcOf(r.source), svcOf(r.target)))) continue;\n    if (activeCovers.some((c) => coversEdge(c, r, elements, known))) continue;\n    findings.push({\n      severity: \"warn\",\n      code: \"c4.uncovered\",\n      subject: svcOf(r.target),\n      message: `delta adds edge ${svcOf(r.source)} → ${svcOf(r.target)} (\"${r.title ?? \"\"}\") but no arch requirement covers it — add 'Covers: ${r.source} -> ${r.target}' to a specs/<svc>/arch.spec.md delta`,\n    });\n  }\n\n  // covers.unknown, feature scope. Resolution looks at the delta itself, the\n  // living landscape, the service's own model and its health.yaml — a delta's\n  // arch requirement may cover an element it adds, one that already exists, or\n  // an alert the service declares. The landscape and each model are loaded\n  // lazily, and only when an entry fails against what is already in hand: the\n  // clean path never pays for a workspace spin.\n  if (archDeltas.some(({ reqs }) => coversEntries(reqs).length > 0)) {\n    const land = await livingLandscape();\n    const landParses = land !== null && land.errors.length === 0 ? land : null;\n    const baseElements = [...elements, ...(landParses?.elements ?? [])];\n    const baseRels = [...relationships, ...(landParses?.relationships ?? [])];\n    // A feature never brings topology through `delta.likec4` — a `deployment { }`\n    // block in one is refused by the merge — so the living map is the whole\n    // scope for a `node:` entry in a delta, exactly as it is in service scope.\n    const baseDeployment = landParses?.deployment;\n    for (const { service: svc, reqs } of archDeltas) {\n      // An unreadable living health.yaml mutes the alert:/sli: entries here\n      // exactly as in service scope — the health.invalid finding itself\n      // belongs to the service target, which owns the file's diagnosis.\n      const health = await readHealth((await locateServicePaths(docsDir, svc, fleet)).health);\n      let scope: CoverageScope = {\n        elements: baseElements,\n        relationships: baseRels,\n        ...(baseDeployment === undefined ? {} : { deployment: baseDeployment }),\n        health: health.ids,\n        known,\n      };\n      const unresolved = coversUnknownFindings(reqs, { where: `${svc}: arch.spec.md`, subject: svc }, scope, health.unreadable);\n      if (unresolved.length > 0) {\n        const modelPath = (await locateServicePaths(docsDir, svc, fleet)).model;\n        const model = existsSync(modelPath)\n          ? fleet === undefined\n            ? await loadFile(modelPath)\n            : await fleet.loadLikeC4(modelPath)\n          : null;\n        if (model !== null && model.errors.length === 0) {\n          scope = {\n            elements: [...baseElements, ...model.elements],\n            relationships: [...baseRels, ...model.relationships],\n            health: health.ids,\n            known,\n          };\n        }\n        findings.push(...coversUnknownFindings(reqs, { where: `${svc}: arch.spec.md`, subject: svc }, scope, health.unreadable));\n      }\n    }\n  }\n\n  return findings;\n}\n\n/** Heuristic: an edge is \"covered\" if a scenario names the target or a keyword from the edge title. */\nfunction edgeCovered(target: string, title: string | undefined, scenarioText: string): boolean {\n  if (scenarioText.includes(target.toLowerCase())) return true;\n  for (const token of (title ?? \"\").split(/[^A-Za-z0-9]+/)) {\n    if (token.length >= 5 && scenarioText.includes(token.toLowerCase())) return true;\n  }\n  return false;\n}\n"]}