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

package/dist/core/doctor/doctor.js

@@ -0,0 +1,275 @@
+/**
+ * The preflight: can loam run here at all, and can its answers be trusted?
+ *
+ * The walk only. Each question it asks lives in its own module — `./config.ts`
+ * for the config and the fleet map, `./agents.ts` for the agent surface,
+ * `./residue.ts` for what a killed writer left — and every one of them returns
+ * findings rather than printing. That is the whole contract this module keeps:
+ * `doctor` is the command that must be able to describe a broken repository
+ * without becoming the next thing that breaks in it.
+ */
+import { constants, existsSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { CONFIG_FILENAME, configPath } from "../envelope/config.js";
+import { LOAM_VERSION } from "../envelope/version.js";
+import { landscapePath } from "../repo/paths.js";
+import { docsRepoState } from "../repo/state.js";
+import { listFeatures, listServices } from "../repo/repo.js";
+import { LIKEC4_PROJECT_CONFIG, LIKEC4_PROJECT_FILENAME } from "../docs.js";
+import { gherkinRoot } from "../gherkin/stamp.js";
+import { UnsafePathError } from "../kernel/path-safety.js";
+import { scanWritePathResidue } from "../staging/recovery/residue.js";
+import {} from "./report.js";
+import { canAccess, inspectConfig, inspectLandscape } from "./config.js";
+import { inspectAgentSurface } from "./agents.js";
+import { gradeWritePathResidue } from "./residue.js";
+export async function diagnose(cwd = process.cwd()) {
+    const inspected = await inspectConfig(cwd);
+    const path = configPath(cwd);
+    const findings = [];
+    if (inspected.status === "missing") {
+        findings.push({
+            severity: "blocker",
+            code: "doctor.config-missing",
+            message: `No ${CONFIG_FILENAME} found at or above ${cwd}.`,
+            fix: "Run `loam init --docs <path-to-docs-repo>` here (add `--create` to make a new docs repo).",
+        });
+    }
+    else if (inspected.status === "invalid") {
+        findings.push({
+            severity: "blocker",
+            code: "doctor.config-invalid",
+            message: `Invalid ${CONFIG_FILENAME}: ${inspected.error ?? "unknown error"}`,
+            fix: `Repair ${path} — or delete it and re-run \`loam init\`.`,
+        });
+    }
+    const docsDir = inspected.config?.docsDir ?? null;
+    const state = docsDir === null ? null : docsRepoState(docsDir);
+    const exists = state !== null && state.kind !== "missing";
+    const readable = exists && docsDir !== null ? await canAccess(docsDir, constants.R_OK) : false;
+    const writable = exists && docsDir !== null ? await canAccess(docsDir, constants.W_OK) : false;
+    const servicesDir = state?.kind === "ok";
+    const landscapeFile = docsDir === null ? null : landscapePath(docsDir);
+    const landscape = landscapeFile === null ? false : await canAccess(landscapeFile, constants.F_OK);
+    // The docs-repo verdict comes from `docsRepoState`, the same function
+    // `listServices` refuses on, so doctor cannot call a repo healthy that the
+    // enumeration will not read.
+    if (state?.kind === "missing") {
+        findings.push({
+            severity: "blocker",
+            code: "doctor.docs-missing",
+            message: `Configured docsDir is missing or is not a directory: ${docsDir}`,
+            fix: `Fix "docsDir" in ${path}, clone the docs repo to ${docsDir}, or run \`loam init --docs <dir> --create\`.`,
+        });
+    }
+    else if (state?.kind === "no-services") {
+        findings.push({
+            severity: "blocker",
+            code: "doctor.services-missing",
+            message: `Required services/ directory is missing under ${docsDir} — that path is not a docs repo.`,
+            fix: `Point "docsDir" in ${path} at the shared docs repo, or run \`loam init --docs ${docsDir} --create\`.`,
+        });
+    }
+    // An absolute docsDir in a committed config names a directory that exists on
+    // exactly one machine. It is a warning and not a blocker because it works
+    // perfectly — for the person who ran `loam init`, and for nobody who clones
+    // the repo afterwards.
+    const asWritten = inspected.config?.docsDirAsWritten;
+    const configRoot = inspected.config?.root;
+    if (asWritten !== undefined
+        && configRoot !== undefined
+        && isAbsolute(asWritten)
+        && resolve(asWritten) !== resolve(configRoot)) {
+        findings.push({
+            severity: "warning",
+            code: "doctor.docs-absolute",
+            message: `"docsDir" is stored as an absolute path (${asWritten}); ` +
+                `${CONFIG_FILENAME} is committed, so it will not resolve on anyone else's machine.`,
+            fix: `Rewrite "docsDir" in ${path} as a path relative to that file (e.g. "../docs").`,
+        });
+    }
+    if (exists && !readable) {
+        findings.push({
+            severity: "warning",
+            code: "doctor.docs-unreadable",
+            message: `docsDir is not readable by this process: ${docsDir}`,
+            fix: `Grant read access to ${docsDir} (check ownership and mode).`,
+        });
+    }
+    if (exists && !writable) {
+        findings.push({
+            severity: "warning",
+            code: "doctor.docs-readonly",
+            message: `docsDir is not writable; read-only commands work, archive/init do not: ${docsDir}`,
+            fix: `Grant write access to ${docsDir} if you need \`loam new\`, \`loam adopt\` or \`loam archive\`.`,
+        });
+    }
+    if (exists && !landscape) {
+        findings.push({
+            severity: "warning",
+            code: "doctor.landscape-missing",
+            message: `${landscapeFile} is missing — nothing cross-service can be checked without it.`,
+            fix: "Create architecture/landscape.likec4 with one element per service and an edge per call (`loam init --create` writes the empty map).",
+        });
+    }
+    else if (exists && landscapeFile !== null && readable) {
+        await inspectLandscape(landscapeFile, findings);
+    }
+    // The renderer's view of the repo, which is not loam's. loam parses every
+    // `.likec4` file ALONE, so each one declares its own `specification` block and
+    // re-declares whatever elements it names; LikeC4's own workspace loader merges
+    // the whole tree into one model, and those declarations then collide. The
+    // result was two tools disagreeing in the most confusing possible direction:
+    // `loam validate --all` reported zero errors on a tree where `npx likec4
+    // start` — the command loam's own brief recommends — refused to load at all.
+    // `loam init --create` writes the project file that scopes the root project to
+    // the landscape; a docs repo created before it exists has to be told, because
+    // nothing else will ever mention it. A warning, not a blocker: no loam check
+    // reads this file, and a repo without it is only unrenderable.
+    if (docsDir !== null && exists && readable && !existsSync(join(docsDir, LIKEC4_PROJECT_FILENAME))) {
+        findings.push({
+            severity: "warning",
+            code: "doctor.likec4-config-missing",
+            message: `${docsDir}/${LIKEC4_PROJECT_FILENAME} is missing, so this tree is not a loadable LikeC4 workspace — `
+                + "every service model and feature delta declares its own `specification` block, and pointing a "
+                + "renderer at the repo root merges them into one model and reports every declaration as a duplicate.",
+            fix: `Write ${docsDir}/${LIKEC4_PROJECT_FILENAME} with:\n${LIKEC4_PROJECT_CONFIG.trimEnd()}\n`
+                + "That scopes the root project to architecture/, so `npx likec4 start` in the docs repo renders "
+                + "the fleet map. A service model or feature delta is rendered by pointing the renderer at its own "
+                + "directory (`npx likec4 start services/<id>`) — being readable alone is what those files are for.",
+        });
+    }
+    // What a killed writer left behind. Read from `scanWritePathResidue`, whose
+    // spellings of `.loam-lock` / `.loam-commit` / the temp-file pattern are
+    // staging's own — doctor grades, it does not re-spell. This is the surface
+    // that used to report `healthy: true` over half-merged docs.
+    const writePath = docsDir !== null && exists && readable
+        ? await scanWritePathResidue(docsDir)
+        : null;
+    if (docsDir !== null && writePath !== null)
+        gradeWritePathResidue(docsDir, writePath, findings);
+    // The one writer whose journal is NOT in the docs repo: `loam gherkin`
+    // commits into the service repo's owned `<gherkinDir>/loam/` root, with the
+    // same lock and journal files. When this repo IS a service repo, that root
+    // gets the same scan and the same grades — the codes are the contract, the
+    // prose says where — because "doctor reports an interrupted commit until
+    // recovery succeeds" has to hold for every writer, not only the docs-repo
+    // ones. Scanning it is cheap: the root is loam's own flat directory.
+    let serviceWritePath = null;
+    if (inspected.config?.service !== undefined && inspected.config.root !== undefined) {
+        try {
+            const emissionRoot = gherkinRoot(inspected.config.root, inspected.config.gherkinDir);
+            if (existsSync(emissionRoot)) {
+                serviceWritePath = await scanWritePathResidue(emissionRoot);
+                gradeWritePathResidue(emissionRoot, serviceWritePath, findings);
+            }
+        }
+        catch (err) {
+            // An unsafe gherkinDir is `loam gherkin`'s refusal to make, with its own
+            // sentence; doctor only declines to scan what it cannot trust.
+            if (!(err instanceof UnsafePathError))
+                throw err;
+        }
+    }
+    let services = [];
+    let activeFeatures = [];
+    // Whether the fleet was actually READ, which is a narrower question than
+    // whether reading it was attempted — hence set inside the try and not from
+    // the guard, so an enumeration that threw leaves this false alongside its own
+    // `doctor.inventory-unreadable`.
+    let inventoried = false;
+    if (docsDir !== null && readable && servicesDir) {
+        try {
+            [services, activeFeatures] = await Promise.all([
+                listServices(docsDir),
+                listFeatures(docsDir),
+            ]);
+            inventoried = true;
+        }
+        catch (error) {
+            findings.push({
+                severity: "warning",
+                code: "doctor.inventory-unreadable",
+                message: `Could not inventory the docs repo: ${error instanceof Error ? error.message : String(error)}`,
+                fix: `Check that ${docsDir}/services and ${docsDir}/features are readable directories.`,
+            });
+        }
+    }
+    const configuredService = inspected.config?.service ?? null;
+    const currentService = configuredService === null
+        ? { configured: null, status: "unbound" }
+        : services.some((service) => service.id === configuredService)
+            ? { configured: configuredService, status: "matched" }
+            : { configured: configuredService, status: "unknown" };
+    // Standing INSIDE the docs repo, an absent service binding is the correct
+    // state, not a gap: the docs repo is the fleet, it is not any one service, and
+    // the fix this finding prints — `loam init --service <id>` — would bind the
+    // shared repo to one of the services it holds, which is not a thing loam has
+    // a meaning for. doctor already knew where it was standing (it prints the
+    // fleet count two lines up) and reported the warning anyway, so the first
+    // preflight anyone ran in a freshly created docs repo came back yellow with
+    // advice that made it worse. The docs repo's own loam.json is the one that
+    // resolves `docsDir` to the directory holding it — that identity, not a
+    // filename, is the test.
+    const inDocsRepo = configRoot !== undefined && docsDir !== null
+        && resolve(configRoot) === resolve(docsDir);
+    if (currentService.status === "unbound" && !inDocsRepo) {
+        findings.push({
+            severity: "warning",
+            code: "doctor.service-unbound",
+            message: "loam.json has no service binding; service-repo checks need `service`.",
+            fix: `Run \`loam init --docs ${inspected.config?.docsDirAsWritten ?? "<dir>"} --service <id>\` here.`,
+        });
+    }
+    else if (currentService.status === "unknown" && inventoried) {
+        // Only when there was an inventory to be absent from. This finding is a
+        // claim about a fleet that was read; with no docsDir, an unreadable one, or
+        // an enumeration that threw, `services` is empty for a reason that has
+        // nothing to do with `service`, and doctor pointed the reader at the one
+        // config field that was fine while the blocker it had already filed named
+        // the real one. `currentService.status` still reports `unknown` — the
+        // envelope describes what loam could and could not match, and an unread
+        // fleet matches nothing.
+        findings.push({
+            severity: "warning",
+            code: "doctor.service-unknown",
+            message: `Configured service '${configuredService}' is not present under services/.`,
+            // `--service <id>`, not a positional: `loam adopt` takes no argument, so
+            // the spelling this finding used to print was refused by commander with
+            // "too many arguments" — as the FIRST instruction a freshly bound service
+            // repo ever receives. test/agent-commands-runnable.test.ts parses every
+            // `loam …` loam prints against the real program so it cannot recur.
+            fix: `Run \`loam adopt --service ${configuredService}\` to onboard it, or fix "service" in ${path}.`,
+        });
+    }
+    // The slash commands (and everything else `init` lays down for a tool) belong
+    // to the repo `init` ran in — the directory holding loam.json, which is not
+    // the cwd now that config discovery walks upward.
+    const agents = await inspectAgentSurface(dirname(path), inspected.config, docsDir, findings);
+    return {
+        healthy: !findings.some((finding) => finding.severity === "blocker"),
+        runtime: {
+            package: "@ybotok/loam",
+            version: LOAM_VERSION,
+            node: process.version,
+            platform: process.platform,
+            arch: process.arch,
+        },
+        config: { path, status: inspected.status, error: inspected.error },
+        docs: {
+            path: docsDir,
+            exists,
+            readable,
+            writable,
+            servicesDir,
+            landscape,
+        },
+        counts: { services: services.length, activeFeatures: activeFeatures.length },
+        currentService,
+        agents,
+        writePath,
+        serviceWritePath,
+        findings,
+    };
+}
+//# sourceMappingURL=doctor.js.map

package/dist/core/doctor/doctor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../../../src/core/doctor/doctor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The preflight: can loam run here at all, and can its answers be trusted?\n *\n * The walk only. Each question it asks lives in its own module — `./config.ts`\n * for the config and the fleet map, `./agents.ts` for the agent surface,\n * `./residue.ts` for what a killed writer left — and every one of them returns\n * findings rather than printing. That is the whole contract this module keeps:\n * `doctor` is the command that must be able to describe a broken repository\n * without becoming the next thing that breaks in it.\n */\nimport { constants, existsSync } from \"node:fs\";\nimport { dirname, isAbsolute, join, resolve } from \"node:path\";\nimport { CONFIG_FILENAME, configPath } from \"../envelope/config.js\";\nimport { LOAM_VERSION } from \"../envelope/version.js\";\nimport { landscapePath } from \"../repo/paths.js\";\nimport { docsRepoState } from \"../repo/state.js\";\nimport { listFeatures, listServices } from \"../repo/repo.js\";\nimport { LIKEC4_PROJECT_CONFIG, LIKEC4_PROJECT_FILENAME } from \"../docs.js\";\nimport { gherkinRoot } from \"../gherkin/stamp.js\";\nimport { UnsafePathError } from \"../kernel/path-safety.js\";\nimport { scanWritePathResidue } from \"../staging/recovery/residue.js\";\nimport { type DoctorFinding, type DoctorReport } from \"./report.js\";\nimport { canAccess, inspectConfig, inspectLandscape } from \"./config.js\";\nimport { inspectAgentSurface } from \"./agents.js\";\nimport { gradeWritePathResidue } from \"./residue.js\";\n\nexport async function diagnose(cwd = process.cwd()): Promise<DoctorReport> {\n  const inspected = await inspectConfig(cwd);\n  const path = configPath(cwd);\n  const findings: DoctorFinding[] = [];\n  if (inspected.status === \"missing\") {\n    findings.push({\n      severity: \"blocker\",\n      code: \"doctor.config-missing\",\n      message: `No ${CONFIG_FILENAME} found at or above ${cwd}.`,\n      fix: \"Run `loam init --docs <path-to-docs-repo>` here (add `--create` to make a new docs repo).\",\n    });\n  } else if (inspected.status === \"invalid\") {\n    findings.push({\n      severity: \"blocker\",\n      code: \"doctor.config-invalid\",\n      message: `Invalid ${CONFIG_FILENAME}: ${inspected.error ?? \"unknown error\"}`,\n      fix: `Repair ${path} — or delete it and re-run \\`loam init\\`.`,\n    });\n  }\n\n  const docsDir = inspected.config?.docsDir ?? null;\n  const state = docsDir === null ? null : docsRepoState(docsDir);\n  const exists = state !== null && state.kind !== \"missing\";\n  const readable = exists && docsDir !== null ? await canAccess(docsDir, constants.R_OK) : false;\n  const writable = exists && docsDir !== null ? await canAccess(docsDir, constants.W_OK) : false;\n  const servicesDir = state?.kind === \"ok\";\n  const landscapeFile = docsDir === null ? null : landscapePath(docsDir);\n  const landscape = landscapeFile === null ? false : await canAccess(landscapeFile, constants.F_OK);\n\n  // The docs-repo verdict comes from `docsRepoState`, the same function\n  // `listServices` refuses on, so doctor cannot call a repo healthy that the\n  // enumeration will not read.\n  if (state?.kind === \"missing\") {\n    findings.push({\n      severity: \"blocker\",\n      code: \"doctor.docs-missing\",\n      message: `Configured docsDir is missing or is not a directory: ${docsDir}`,\n      fix: `Fix \"docsDir\" in ${path}, clone the docs repo to ${docsDir}, or run \\`loam init --docs <dir> --create\\`.`,\n    });\n  } else if (state?.kind === \"no-services\") {\n    findings.push({\n      severity: \"blocker\",\n      code: \"doctor.services-missing\",\n      message: `Required services/ directory is missing under ${docsDir} — that path is not a docs repo.`,\n      fix: `Point \"docsDir\" in ${path} at the shared docs repo, or run \\`loam init --docs ${docsDir} --create\\`.`,\n    });\n  }\n\n  // An absolute docsDir in a committed config names a directory that exists on\n  // exactly one machine. It is a warning and not a blocker because it works\n  // perfectly — for the person who ran `loam init`, and for nobody who clones\n  // the repo afterwards.\n  const asWritten = inspected.config?.docsDirAsWritten;\n  const configRoot = inspected.config?.root;\n  if (\n    asWritten !== undefined\n    && configRoot !== undefined\n    && isAbsolute(asWritten)\n    && resolve(asWritten) !== resolve(configRoot)\n  ) {\n    findings.push({\n      severity: \"warning\",\n      code: \"doctor.docs-absolute\",\n      message:\n        `\"docsDir\" is stored as an absolute path (${asWritten}); ` +\n        `${CONFIG_FILENAME} is committed, so it will not resolve on anyone else's machine.`,\n      fix: `Rewrite \"docsDir\" in ${path} as a path relative to that file (e.g. \"../docs\").`,\n    });\n  }\n\n  if (exists && !readable) {\n    findings.push({\n      severity: \"warning\",\n      code: \"doctor.docs-unreadable\",\n      message: `docsDir is not readable by this process: ${docsDir}`,\n      fix: `Grant read access to ${docsDir} (check ownership and mode).`,\n    });\n  }\n  if (exists && !writable) {\n    findings.push({\n      severity: \"warning\",\n      code: \"doctor.docs-readonly\",\n      message: `docsDir is not writable; read-only commands work, archive/init do not: ${docsDir}`,\n      fix: `Grant write access to ${docsDir} if you need \\`loam new\\`, \\`loam adopt\\` or \\`loam archive\\`.`,\n    });\n  }\n  if (exists && !landscape) {\n    findings.push({\n      severity: \"warning\",\n      code: \"doctor.landscape-missing\",\n      message: `${landscapeFile} is missing — nothing cross-service can be checked without it.`,\n      fix: \"Create architecture/landscape.likec4 with one element per service and an edge per call (`loam init --create` writes the empty map).\",\n    });\n  } else if (exists && landscapeFile !== null && readable) {\n    await inspectLandscape(landscapeFile, findings);\n  }\n\n  // The renderer's view of the repo, which is not loam's. loam parses every\n  // `.likec4` file ALONE, so each one declares its own `specification` block and\n  // re-declares whatever elements it names; LikeC4's own workspace loader merges\n  // the whole tree into one model, and those declarations then collide. The\n  // result was two tools disagreeing in the most confusing possible direction:\n  // `loam validate --all` reported zero errors on a tree where `npx likec4\n  // start` — the command loam's own brief recommends — refused to load at all.\n  // `loam init --create` writes the project file that scopes the root project to\n  // the landscape; a docs repo created before it exists has to be told, because\n  // nothing else will ever mention it. A warning, not a blocker: no loam check\n  // reads this file, and a repo without it is only unrenderable.\n  if (docsDir !== null && exists && readable && !existsSync(join(docsDir, LIKEC4_PROJECT_FILENAME))) {\n    findings.push({\n      severity: \"warning\",\n      code: \"doctor.likec4-config-missing\",\n      message:\n        `${docsDir}/${LIKEC4_PROJECT_FILENAME} is missing, so this tree is not a loadable LikeC4 workspace — `\n        + \"every service model and feature delta declares its own `specification` block, and pointing a \"\n        + \"renderer at the repo root merges them into one model and reports every declaration as a duplicate.\",\n      fix:\n        `Write ${docsDir}/${LIKEC4_PROJECT_FILENAME} with:\\n${LIKEC4_PROJECT_CONFIG.trimEnd()}\\n`\n        + \"That scopes the root project to architecture/, so `npx likec4 start` in the docs repo renders \"\n        + \"the fleet map. A service model or feature delta is rendered by pointing the renderer at its own \"\n        + \"directory (`npx likec4 start services/<id>`) — being readable alone is what those files are for.\",\n    });\n  }\n\n  // What a killed writer left behind. Read from `scanWritePathResidue`, whose\n  // spellings of `.loam-lock` / `.loam-commit` / the temp-file pattern are\n  // staging's own — doctor grades, it does not re-spell. This is the surface\n  // that used to report `healthy: true` over half-merged docs.\n  const writePath = docsDir !== null && exists && readable\n    ? await scanWritePathResidue(docsDir)\n    : null;\n  if (docsDir !== null && writePath !== null) gradeWritePathResidue(docsDir, writePath, findings);\n\n  // The one writer whose journal is NOT in the docs repo: `loam gherkin`\n  // commits into the service repo's owned `<gherkinDir>/loam/` root, with the\n  // same lock and journal files. When this repo IS a service repo, that root\n  // gets the same scan and the same grades — the codes are the contract, the\n  // prose says where — because \"doctor reports an interrupted commit until\n  // recovery succeeds\" has to hold for every writer, not only the docs-repo\n  // ones. Scanning it is cheap: the root is loam's own flat directory.\n  let serviceWritePath = null;\n  if (inspected.config?.service !== undefined && inspected.config.root !== undefined) {\n    try {\n      const emissionRoot = gherkinRoot(inspected.config.root, inspected.config.gherkinDir);\n      if (existsSync(emissionRoot)) {\n        serviceWritePath = await scanWritePathResidue(emissionRoot);\n        gradeWritePathResidue(emissionRoot, serviceWritePath, findings);\n      }\n    } catch (err) {\n      // An unsafe gherkinDir is `loam gherkin`'s refusal to make, with its own\n      // sentence; doctor only declines to scan what it cannot trust.\n      if (!(err instanceof UnsafePathError)) throw err;\n    }\n  }\n\n  let services: Awaited<ReturnType<typeof listServices>> = [];\n  let activeFeatures: Awaited<ReturnType<typeof listFeatures>> = [];\n  // Whether the fleet was actually READ, which is a narrower question than\n  // whether reading it was attempted — hence set inside the try and not from\n  // the guard, so an enumeration that threw leaves this false alongside its own\n  // `doctor.inventory-unreadable`.\n  let inventoried = false;\n  if (docsDir !== null && readable && servicesDir) {\n    try {\n      [services, activeFeatures] = await Promise.all([\n        listServices(docsDir),\n        listFeatures(docsDir),\n      ]);\n      inventoried = true;\n    } catch (error) {\n      findings.push({\n        severity: \"warning\",\n        code: \"doctor.inventory-unreadable\",\n        message: `Could not inventory the docs repo: ${error instanceof Error ? error.message : String(error)}`,\n        fix: `Check that ${docsDir}/services and ${docsDir}/features are readable directories.`,\n      });\n    }\n  }\n\n  const configuredService = inspected.config?.service ?? null;\n  const currentService: DoctorReport[\"currentService\"] = configuredService === null\n    ? { configured: null, status: \"unbound\" }\n    : services.some((service) => service.id === configuredService)\n      ? { configured: configuredService, status: \"matched\" }\n      : { configured: configuredService, status: \"unknown\" };\n  // Standing INSIDE the docs repo, an absent service binding is the correct\n  // state, not a gap: the docs repo is the fleet, it is not any one service, and\n  // the fix this finding prints — `loam init --service <id>` — would bind the\n  // shared repo to one of the services it holds, which is not a thing loam has\n  // a meaning for. doctor already knew where it was standing (it prints the\n  // fleet count two lines up) and reported the warning anyway, so the first\n  // preflight anyone ran in a freshly created docs repo came back yellow with\n  // advice that made it worse. The docs repo's own loam.json is the one that\n  // resolves `docsDir` to the directory holding it — that identity, not a\n  // filename, is the test.\n  const inDocsRepo = configRoot !== undefined && docsDir !== null\n    && resolve(configRoot) === resolve(docsDir);\n  if (currentService.status === \"unbound\" && !inDocsRepo) {\n    findings.push({\n      severity: \"warning\",\n      code: \"doctor.service-unbound\",\n      message: \"loam.json has no service binding; service-repo checks need `service`.\",\n      fix: `Run \\`loam init --docs ${inspected.config?.docsDirAsWritten ?? \"<dir>\"} --service <id>\\` here.`,\n    });\n  } else if (currentService.status === \"unknown\" && inventoried) {\n    // Only when there was an inventory to be absent from. This finding is a\n    // claim about a fleet that was read; with no docsDir, an unreadable one, or\n    // an enumeration that threw, `services` is empty for a reason that has\n    // nothing to do with `service`, and doctor pointed the reader at the one\n    // config field that was fine while the blocker it had already filed named\n    // the real one. `currentService.status` still reports `unknown` — the\n    // envelope describes what loam could and could not match, and an unread\n    // fleet matches nothing.\n    findings.push({\n      severity: \"warning\",\n      code: \"doctor.service-unknown\",\n      message: `Configured service '${configuredService}' is not present under services/.`,\n      // `--service <id>`, not a positional: `loam adopt` takes no argument, so\n      // the spelling this finding used to print was refused by commander with\n      // \"too many arguments\" — as the FIRST instruction a freshly bound service\n      // repo ever receives. test/agent-commands-runnable.test.ts parses every\n      // `loam …` loam prints against the real program so it cannot recur.\n      fix: `Run \\`loam adopt --service ${configuredService}\\` to onboard it, or fix \"service\" in ${path}.`,\n    });\n  }\n\n  // The slash commands (and everything else `init` lays down for a tool) belong\n  // to the repo `init` ran in — the directory holding loam.json, which is not\n  // the cwd now that config discovery walks upward.\n  const agents = await inspectAgentSurface(dirname(path), inspected.config, docsDir, findings);\n\n  return {\n    healthy: !findings.some((finding) => finding.severity === \"blocker\"),\n    runtime: {\n      package: \"@ybotok/loam\",\n      version: LOAM_VERSION,\n      node: process.version,\n      platform: process.platform,\n      arch: process.arch,\n    },\n    config: { path, status: inspected.status, error: inspected.error },\n    docs: {\n      path: docsDir,\n      exists,\n      readable,\n      writable,\n      servicesDir,\n      landscape,\n    },\n    counts: { services: services.length, activeFeatures: activeFeatures.length },\n    currentService,\n    agents,\n    writePath,\n    serviceWritePath,\n    findings,\n  };\n}\n"]}

package/dist/core/doctor/report.js

@@ -0,0 +1,13 @@
+/**
+ * What a diagnosis IS: the finding shape, the report shape, and the agent
+ * surface inside it.
+ *
+ * A module of its own because five checks fill this in and the command prints
+ * it, so every one of them agrees about what a blocker means here — something
+ * that stops loam running at all, as against a warning, which is something a
+ * person should know before trusting an answer. That distinction is the whole
+ * value of `doctor`, and it lives in the type rather than in five checks'
+ * judgement.
+ */
+import {} from "../staging/recovery/residue.js";
+//# sourceMappingURL=report.js.map

package/dist/core/doctor/report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../../../src/core/doctor/report.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAyB,MAAM,gCAAgC,CAAC","sourcesContent":["/**\n * What a diagnosis IS: the finding shape, the report shape, and the agent\n * surface inside it.\n *\n * A module of its own because five checks fill this in and the command prints\n * it, so every one of them agrees about what a blocker means here — something\n * that stops loam running at all, as against a warning, which is something a\n * person should know before trusting an answer. That distinction is the whole\n * value of `doctor`, and it lives in the type rather than in five checks'\n * judgement.\n */\nimport { type WritePathResidue } from \"../staging/recovery/residue.js\";\n\nexport type DoctorSeverity = \"blocker\" | \"warning\";\n\nexport interface DoctorFinding {\n  severity: DoctorSeverity;\n  code: string;\n  message: string;\n  /**\n   * The next command or edit that clears this finding. Mandatory, not optional:\n   * a diagnostic that names a problem without naming its fix is a diagnostic\n   * the reader has to research, and `doctor` is what someone runs precisely\n   * because they do not yet know what loam wants from them.\n   */\n  fix: string;\n}\n\nexport interface DoctorReport {\n  healthy: boolean;\n  runtime: {\n    package: \"@ybotok/loam\";\n    version: string;\n    node: string;\n    platform: NodeJS.Platform;\n    arch: string;\n  };\n  config: {\n    path: string;\n    status: \"missing\" | \"invalid\" | \"valid\";\n    error: string | null;\n  };\n  docs: {\n    path: string | null;\n    exists: boolean;\n    readable: boolean;\n    writable: boolean;\n    servicesDir: boolean;\n    landscape: boolean;\n  };\n  counts: { services: number; activeFeatures: number };\n  currentService: {\n    configured: string | null;\n    status: \"unbound\" | \"matched\" | \"unknown\";\n  };\n  /** The agent surface of this repo — see `inspectAgentSurface`. */\n  agents: AgentSurface;\n  /**\n   * What a write that did not finish left in the docs repo, or null when\n   * `docsDir` never resolved. Reported as state, like `docs` and `counts`: a\n   * lock somebody is legitimately holding right now is a fact, not a complaint.\n   */\n  writePath: WritePathResidue | null;\n  /**\n   * The same scan over the service repo's owned `<gherkinDir>/loam/` root —\n   * the one writer whose journal is not in the docs repo. Null when this repo\n   * is not a service repo, or the root does not exist. Additive: a consumer\n   * of the original envelope never sees a key it did not ask about removed.\n   */\n  serviceWritePath: WritePathResidue | null;\n  findings: DoctorFinding[];\n}\n\nexport interface AgentSurface {\n  /** Tool ids this repo has an agent surface for. Empty is legal (`init --no-commands`). */\n  tools: string[];\n  /** Workflow subset managed for those tools. */\n  profile: \"full\" | \"service\" | \"docs\";\n  /** Whether `tools` came from loam.json's own record or from what is on disk. */\n  toolsSource: \"config\" | \"disk\";\n  /** How many files the running binary would lay down for `tools`. */\n  plannedFiles: number;\n  /** Repo-relative paths of those files that are not there. */\n  missingFiles: string[];\n  /**\n   * Repo-relative paths of the ones that ARE there carrying no version stamp,\n   * or one older than this binary — see `staleAgentFiles`.\n   */\n  staleFiles: string[];\n  stamp: {\n    /** Where the docs repo's AGENTS.md is, or null when `docsDir` did not resolve. */\n    path: string | null;\n    /** Whether it could be read at all — absent and unstamped are different facts. */\n    present: boolean;\n    /** The version the stamp names, null when there is none (or an unparseable one). */\n    version: string | null;\n    /** Whether `agents.stale` fired: the stamp is missing or trails this binary. */\n    stale: boolean;\n  };\n}\n"]}

package/dist/core/doctor/residue.js

@@ -0,0 +1,110 @@
+/**
+ * What an unfinished write means for the health of the repo.
+ *
+ * `core/staging/recovery/residue.ts` reports what is on disk; this decides how
+ * bad it is. A held lock and an interrupted commit are blockers because the docs
+ * are, or may be, half-merged: a SIGKILL between two of archive's renames once
+ * left `doctor: healthy: true` over a merged spec.md and an unmerged landscape,
+ * and the next `loam archive` reported loam's own half-merge as the author's
+ * bug. Temp files are the exception — a `.loam-*.tmp` was never linked into
+ * place, so nothing reads it. Litter, not damage.
+ */
+import { join } from "node:path";
+import {} from "../staging/recovery/residue.js";
+import {} from "./report.js";
+export function gradeWritePathResidue(docsDir, residue, findings) {
+    if (residue.lock !== null) {
+        const lockFile = join(docsDir, residue.lock.path);
+        // Three grades of one file. Held by a live process is a fact about right
+        // now — wait and re-run. Held by a dead process is damage: nothing will
+        // ever release it. And a lock that cannot NAME a holder — empty bytes from
+        // a crash between create and flush, or JSON nothing understands — is the
+        // same damage wearing a live lock's face: `breakStaleLock` rightly refuses
+        // to guess about it, so "wait" is advice that can never work, while every
+        // writer (archive, unarchive, rebase, verify --record) refuses `docs-busy`
+        // forever.
+        const unbreakable = residue.lock.stale || residue.lock.unreadable;
+        findings.push({
+            severity: unbreakable ? "blocker" : "warning",
+            code: "doctor.docs-locked",
+            message: residue.lock.unreadable
+                ? `${residue.lock.path} exists but cannot be read as a lock record — no process can be identified as its holder, so nothing is ever going to release it, and every writing command refuses with \`docs-busy\` while it is there.`
+                : residue.lock.stale
+                    ? `${residue.lock.path} is held by ${residue.lock.holder}, a process that no longer exists on this host — every command that writes through this root will refuse with \`docs-busy\` until it is gone.`
+                    : `${residue.lock.path} is held by ${residue.lock.holder}; another loam command is writing through this root.`,
+            fix: unbreakable
+                ? `Delete ${lockFile} — ${residue.lock.unreadable ? "it names no holder, so nothing is going to release it" : "its holder is dead, so nothing is going to release it"}. Check \`loam doctor\` again afterwards for an interrupted commit.`
+                : "Wait for it to finish and re-run; nothing is read or written while it is held.",
+        });
+    }
+    if (residue.intentUnreadable) {
+        findings.push({
+            severity: "blocker",
+            code: "doctor.commit-unreadable",
+            message: `${docsDir} holds a .loam-commit that cannot be read — a commit was interrupted and the one record of which files it had already written is unreadable.`,
+            fix: "Hand this to a human: compare this root's files against version control before running any loam command that writes here. Every journaled writer refuses with `commit-interrupted` while it is there.",
+        });
+    }
+    else if (residue.intent !== null && "rerun" in residue.intent) {
+        // Version 2 — the smaller journaled transaction (rebase, vouch, new,
+        // gherkin, and any writer after them). Its stored `rerun` IS the repair:
+        // that command recovers first, rolling the staged bytes forward. The
+        // string is journal data, so agent-commands-runnable cannot parse it here;
+        // test/staging-txn.test.ts parses every writer's rerun template against
+        // the real program instead.
+        const i = residue.intent;
+        // Both halves of the journal are named, because a version-3 record can be
+        // rename-only (`subsystem move` where the views bytes did not change): a
+        // blocker that said "0 file(s) may be half-written" and named nothing sent
+        // the operator hunting for files while the pending damage was directories.
+        const halves = [
+            ...(i.files.length > 0 ? [`${i.files.length} file(s) may be half-written: ${i.files.map((f) => f.path).join(", ")}`] : []),
+            ...(i.moves.length > 0
+                ? [`${i.moves.length} directory move(s) pending: ${i.moves.map((m) => `${m.from} -> ${m.to}`).join(", ")}`]
+                : []),
+        ];
+        findings.push({
+            severity: "blocker",
+            code: "doctor.commit-interrupted",
+            message: `A \`${i.rerun}\` was killed mid-commit (${i.host}, pid ${i.pid}, ${i.at}) — `
+                + (halves.length > 0 ? halves.join("; ") : "its journal records no pending file or directory"),
+            fix: `Re-run \`${i.rerun}\` — it recovers first, rolling the staged bytes forward, and refuses with \`commit-interrupted\` rather than guessing if a file has been edited since.`,
+        });
+    }
+    else if (residue.intent !== null) {
+        const i = residue.intent;
+        // The command is spelled out per branch rather than interpolated into one
+        // sentence: `loam ${i.command} ${i.feature}` reads fine to a person and is
+        // opaque to test/agent-commands-runnable.test.ts, which parses the commands
+        // loam prints against the real program. Same discipline as spelling `code:`
+        // literally — be visible to your own guard.
+        const repair = i.command === "archive"
+            ? `\`loam archive ${i.feature}\` — it recovers first, under the lock, putting the half-written files back from the snapshot`
+            : `\`loam unarchive ${i.feature}\` — it recovers first, under the lock, finishing the restore (an interrupted restore is FINISHED, never undone: the merged text it was replacing is written down nowhere)`;
+        findings.push({
+            severity: "blocker",
+            code: "doctor.commit-interrupted",
+            message: `A ${i.command === "archive" ? `\`loam archive ${i.feature}\`` : `\`loam unarchive ${i.feature}\``} `
+                + `was killed mid-commit (${i.host}, pid ${i.pid}, ${i.at}) — `
+                + `${i.files.length} file(s) may be half-written: ${i.files.map((f) => f.path).join(", ")}`,
+            fix: `Re-run ${repair}, and refuses with \`commit-interrupted\` rather than guessing if a file has been edited since.`,
+        });
+    }
+    // A version-2 journal's recorded temps are NOT litter: they are the only
+    // durable copy of the after-bytes its roll-forward recovery renames in.
+    // Advising their deletion beside a blocker that says "re-run to recover"
+    // converted a one-command repair into a manual VCS restore.
+    const journalTemps = new Set(residue.intent !== null && "rerun" in residue.intent
+        ? residue.intent.files.flatMap((f) => (f.tmp === null ? [] : [f.tmp]))
+        : []);
+    const litter = residue.temps.filter((t) => !journalTemps.has(t));
+    if (litter.length > 0) {
+        findings.push({
+            severity: "warning",
+            code: "doctor.staging-temps",
+            message: `${litter.length} orphaned staging file(s) under ${docsDir}: ${litter.join(", ")} — a killed writer's scratch, never linked into place.`,
+            fix: "The next journaled writer through this root removes its own; delete any that remain. Nothing reads them, so they cost disk and nothing else.",
+        });
+    }
+}
+//# sourceMappingURL=residue.js.map

package/dist/core/doctor/residue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"residue.js","sourceRoot":"","sources":["../../../src/core/doctor/residue.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What an unfinished write means for the health of the repo.\n *\n * `core/staging/recovery/residue.ts` reports what is on disk; this decides how\n * bad it is. A held lock and an interrupted commit are blockers because the docs\n * are, or may be, half-merged: a SIGKILL between two of archive's renames once\n * left `doctor: healthy: true` over a merged spec.md and an unmerged landscape,\n * and the next `loam archive` reported loam's own half-merge as the author's\n * bug. Temp files are the exception — a `.loam-*.tmp` was never linked into\n * place, so nothing reads it. Litter, not damage.\n */\nimport { join } from \"node:path\";\nimport { type WritePathResidue } from \"../staging/recovery/residue.js\";\nimport { type DoctorFinding } from \"./report.js\";\n\nexport function gradeWritePathResidue(\n  docsDir: string,\n  residue: WritePathResidue,\n  findings: DoctorFinding[],\n): void {\n  if (residue.lock !== null) {\n    const lockFile = join(docsDir, residue.lock.path);\n    // Three grades of one file. Held by a live process is a fact about right\n    // now — wait and re-run. Held by a dead process is damage: nothing will\n    // ever release it. And a lock that cannot NAME a holder — empty bytes from\n    // a crash between create and flush, or JSON nothing understands — is the\n    // same damage wearing a live lock's face: `breakStaleLock` rightly refuses\n    // to guess about it, so \"wait\" is advice that can never work, while every\n    // writer (archive, unarchive, rebase, verify --record) refuses `docs-busy`\n    // forever.\n    const unbreakable = residue.lock.stale || residue.lock.unreadable;\n    findings.push({\n      severity: unbreakable ? \"blocker\" : \"warning\",\n      code: \"doctor.docs-locked\",\n      message: residue.lock.unreadable\n        ? `${residue.lock.path} exists but cannot be read as a lock record — no process can be identified as its holder, so nothing is ever going to release it, and every writing command refuses with \\`docs-busy\\` while it is there.`\n        : residue.lock.stale\n          ? `${residue.lock.path} is held by ${residue.lock.holder}, a process that no longer exists on this host — every command that writes through this root will refuse with \\`docs-busy\\` until it is gone.`\n          : `${residue.lock.path} is held by ${residue.lock.holder}; another loam command is writing through this root.`,\n      fix: unbreakable\n        ? `Delete ${lockFile} — ${residue.lock.unreadable ? \"it names no holder, so nothing is going to release it\" : \"its holder is dead, so nothing is going to release it\"}. Check \\`loam doctor\\` again afterwards for an interrupted commit.`\n        : \"Wait for it to finish and re-run; nothing is read or written while it is held.\",\n    });\n  }\n\n  if (residue.intentUnreadable) {\n    findings.push({\n      severity: \"blocker\",\n      code: \"doctor.commit-unreadable\",\n      message: `${docsDir} holds a .loam-commit that cannot be read — a commit was interrupted and the one record of which files it had already written is unreadable.`,\n      fix: \"Hand this to a human: compare this root's files against version control before running any loam command that writes here. Every journaled writer refuses with `commit-interrupted` while it is there.\",\n    });\n  } else if (residue.intent !== null && \"rerun\" in residue.intent) {\n    // Version 2 — the smaller journaled transaction (rebase, vouch, new,\n    // gherkin, and any writer after them). Its stored `rerun` IS the repair:\n    // that command recovers first, rolling the staged bytes forward. The\n    // string is journal data, so agent-commands-runnable cannot parse it here;\n    // test/staging-txn.test.ts parses every writer's rerun template against\n    // the real program instead.\n    const i = residue.intent;\n    // Both halves of the journal are named, because a version-3 record can be\n    // rename-only (`subsystem move` where the views bytes did not change): a\n    // blocker that said \"0 file(s) may be half-written\" and named nothing sent\n    // the operator hunting for files while the pending damage was directories.\n    const halves = [\n      ...(i.files.length > 0 ? [`${i.files.length} file(s) may be half-written: ${i.files.map((f) => f.path).join(\", \")}`] : []),\n      ...(i.moves.length > 0\n        ? [`${i.moves.length} directory move(s) pending: ${i.moves.map((m) => `${m.from} -> ${m.to}`).join(\", \")}`]\n        : []),\n    ];\n    findings.push({\n      severity: \"blocker\",\n      code: \"doctor.commit-interrupted\",\n      message:\n        `A \\`${i.rerun}\\` was killed mid-commit (${i.host}, pid ${i.pid}, ${i.at}) — `\n        + (halves.length > 0 ? halves.join(\"; \") : \"its journal records no pending file or directory\"),\n      fix: `Re-run \\`${i.rerun}\\` — it recovers first, rolling the staged bytes forward, and refuses with \\`commit-interrupted\\` rather than guessing if a file has been edited since.`,\n    });\n  } else if (residue.intent !== null) {\n    const i = residue.intent;\n    // The command is spelled out per branch rather than interpolated into one\n    // sentence: `loam ${i.command} ${i.feature}` reads fine to a person and is\n    // opaque to test/agent-commands-runnable.test.ts, which parses the commands\n    // loam prints against the real program. Same discipline as spelling `code:`\n    // literally — be visible to your own guard.\n    const repair = i.command === \"archive\"\n      ? `\\`loam archive ${i.feature}\\` — it recovers first, under the lock, putting the half-written files back from the snapshot`\n      : `\\`loam unarchive ${i.feature}\\` — it recovers first, under the lock, finishing the restore (an interrupted restore is FINISHED, never undone: the merged text it was replacing is written down nowhere)`;\n    findings.push({\n      severity: \"blocker\",\n      code: \"doctor.commit-interrupted\",\n      message:\n        `A ${i.command === \"archive\" ? `\\`loam archive ${i.feature}\\`` : `\\`loam unarchive ${i.feature}\\``} `\n        + `was killed mid-commit (${i.host}, pid ${i.pid}, ${i.at}) — `\n        + `${i.files.length} file(s) may be half-written: ${i.files.map((f) => f.path).join(\", \")}`,\n      fix: `Re-run ${repair}, and refuses with \\`commit-interrupted\\` rather than guessing if a file has been edited since.`,\n    });\n  }\n\n  // A version-2 journal's recorded temps are NOT litter: they are the only\n  // durable copy of the after-bytes its roll-forward recovery renames in.\n  // Advising their deletion beside a blocker that says \"re-run to recover\"\n  // converted a one-command repair into a manual VCS restore.\n  const journalTemps = new Set(\n    residue.intent !== null && \"rerun\" in residue.intent\n      ? residue.intent.files.flatMap((f) => (f.tmp === null ? [] : [f.tmp]))\n      : [],\n  );\n  const litter = residue.temps.filter((t) => !journalTemps.has(t));\n  if (litter.length > 0) {\n    findings.push({\n      severity: \"warning\",\n      code: \"doctor.staging-temps\",\n      message: `${litter.length} orphaned staging file(s) under ${docsDir}: ${litter.join(\", \")} — a killed writer's scratch, never linked into place.`,\n      fix: \"The next journaled writer through this root removes its own; delete any that remain. Nothing reads them, so they cost disk and nothing else.\",\n    });\n  }\n}\n"]}

package/dist/core/document/apply.js

@@ -0,0 +1,77 @@
+/**
+ * A feature's ADDED/MODIFIED/REMOVED requirements folded onto a living set.
+ *
+ * The one thing `loam archive` does to a spec, and a module of its own because
+ * it is where a requirement stops being a delta: `asLiving` drops the
+ * `Based-On:` pin, which is a claim about which living version this was written
+ * against — meaningless once it IS the living version, and poison for the next
+ * feature's baseline, which would otherwise hash the previous feature's pin.
+ */
+import { requirementIdProblems, withoutBaseline } from "./spec.js";
+/**
+ * A delta requirement as it lands in the living document, with the bookkeeping
+ * that belongs to the DELTA left behind: the `Based-On:` pin (a claim about
+ * which living version this was written against — meaningless once it IS the
+ * living version, and poison for the next feature's baseline, which would then
+ * hash the previous feature's pin) and the line it was parsed from.
+ */
+function asLiving(d) {
+    const { line: _dropped, ...rest } = withoutBaseline(d);
+    return { ...rest, kind: "BASE" };
+}
+/** Apply a feature's ADDED/MODIFIED/REMOVED requirements onto a living requirement set. */
+export function applyRequirementDelta(living, delta) {
+    const malformed = [...requirementIdProblems(living), ...requirementIdProblems(delta)];
+    if (malformed.length > 0) {
+        throw new Error("cannot merge requirements with invalid, repeated, or duplicate Requirement-ID declarations");
+    }
+    let result = living.map((r) => ({ ...r, kind: "BASE" }));
+    for (const d of delta) {
+        // BASE is not a delta kind — a requirement outside an ADDED/MODIFIED/REMOVED
+        // section (e.g. quoted under ## Notes) is documentation, not a change.
+        if (d.kind === "BASE")
+            continue;
+        if (d.id !== undefined) {
+            const idMatches = result
+                .map((r, i) => (r.id === d.id ? i : -1))
+                .filter((i) => i >= 0);
+            const nameMatches = result
+                .map((r, i) => (r.name === d.name ? i : -1))
+                .filter((i) => i >= 0);
+            const otherNameMatches = nameMatches.filter((i) => !idMatches.includes(i));
+            if (idMatches.length > 1 || otherNameMatches.length > 0) {
+                throw new Error(`ambiguous requirement identity for '${d.name}' (${d.id}): Requirement-ID and heading select different living requirements`);
+            }
+            if (d.kind === "REMOVED") {
+                const selected = new Set(idMatches);
+                result = result.filter((_, i) => !selected.has(i));
+            }
+            else {
+                const merged = asLiving(d);
+                if (idMatches.length === 1)
+                    result[idMatches[0]] = merged;
+                else
+                    result.push(merged);
+            }
+        }
+        else if (d.kind === "REMOVED") {
+            result = result.filter((r) => r.name !== d.name);
+        }
+        else {
+            const i = result.findIndex((r) => r.name === d.name);
+            // A legacy delta may still modify an ID-bearing living requirement by
+            // its exact heading. Keep the identity while the repository migrates.
+            const inheritedId = i >= 0 ? result[i].id : undefined;
+            const merged = {
+                ...asLiving(d),
+                ...(inheritedId === undefined ? {} : { id: inheritedId }),
+            };
+            if (i >= 0)
+                result[i] = merged;
+            else
+                result.push(merged);
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=apply.js.map

package/dist/core/document/apply.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply.js","sourceRoot":"","sources":["../../../src/core/document/apply.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * A feature's ADDED/MODIFIED/REMOVED requirements folded onto a living set.\n *\n * The one thing `loam archive` does to a spec, and a module of its own because\n * it is where a requirement stops being a delta: `asLiving` drops the\n * `Based-On:` pin, which is a claim about which living version this was written\n * against — meaningless once it IS the living version, and poison for the next\n * feature's baseline, which would otherwise hash the previous feature's pin.\n */\nimport { requirementIdProblems, withoutBaseline, type DeltaKind, type Requirement } from \"./spec.js\";\n\n/**\n * A delta requirement as it lands in the living document, with the bookkeeping\n * that belongs to the DELTA left behind: the `Based-On:` pin (a claim about\n * which living version this was written against — meaningless once it IS the\n * living version, and poison for the next feature's baseline, which would then\n * hash the previous feature's pin) and the line it was parsed from.\n */\nfunction asLiving(d: Requirement): Requirement {\n  const { line: _dropped, ...rest } = withoutBaseline(d);\n  return { ...rest, kind: \"BASE\" };\n}\n\n/** Apply a feature's ADDED/MODIFIED/REMOVED requirements onto a living requirement set. */\nexport function applyRequirementDelta(living: Requirement[], delta: Requirement[]): Requirement[] {\n  const malformed = [...requirementIdProblems(living), ...requirementIdProblems(delta)];\n  if (malformed.length > 0) {\n    throw new Error(\"cannot merge requirements with invalid, repeated, or duplicate Requirement-ID declarations\");\n  }\n  let result: Requirement[] = living.map((r) => ({ ...r, kind: \"BASE\" as DeltaKind }));\n  for (const d of delta) {\n    // BASE is not a delta kind — a requirement outside an ADDED/MODIFIED/REMOVED\n    // section (e.g. quoted under ## Notes) is documentation, not a change.\n    if (d.kind === \"BASE\") continue;\n    if (d.id !== undefined) {\n      const idMatches = result\n        .map((r, i) => (r.id === d.id ? i : -1))\n        .filter((i) => i >= 0);\n      const nameMatches = result\n        .map((r, i) => (r.name === d.name ? i : -1))\n        .filter((i) => i >= 0);\n      const otherNameMatches = nameMatches.filter((i) => !idMatches.includes(i));\n      if (idMatches.length > 1 || otherNameMatches.length > 0) {\n        throw new Error(\n          `ambiguous requirement identity for '${d.name}' (${d.id}): Requirement-ID and heading select different living requirements`,\n        );\n      }\n      if (d.kind === \"REMOVED\") {\n        const selected = new Set(idMatches);\n        result = result.filter((_, i) => !selected.has(i));\n      } else {\n        const merged: Requirement = asLiving(d);\n        if (idMatches.length === 1) result[idMatches[0]!] = merged;\n        else result.push(merged);\n      }\n    } else if (d.kind === \"REMOVED\") {\n      result = result.filter((r) => r.name !== d.name);\n    } else {\n      const i = result.findIndex((r) => r.name === d.name);\n      // A legacy delta may still modify an ID-bearing living requirement by\n      // its exact heading. Keep the identity while the repository migrates.\n      const inheritedId = i >= 0 ? result[i]!.id : undefined;\n      const merged: Requirement = {\n        ...asLiving(d),\n        ...(inheritedId === undefined ? {} : { id: inheritedId }),\n      };\n      if (i >= 0) result[i] = merged;\n      else result.push(merged);\n    }\n  }\n  return result;\n}\n"]}