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

package/dist/core/{path-safety.js → kernel/path-safety.js}

@@ -22,6 +22,44 @@ export function isPathInside(root, target) {
     const rel = relative(resolve(root), resolve(target));
     return rel === "" || (!isAbsolute(rel) && rel !== ".." && !rel.startsWith(`..${sep}`));
 }
+/**
+ * Where `target` is once the directory `from` has been renamed to `to`: its
+ * image under `to` when it is inside `from`, `target` itself when it is not.
+ * Absolute paths in and out. The question every reader of a directory move
+ * asks of one path: the link rewrites of both renames loam makes (`subsystem
+ * move`, and `archive` for the feature's own documents), and the archive's
+ * snapshot, crash repair and `unarchive`'s report, which meet those documents
+ * on either side of the move.
+ */
+export function acrossRename(target, from, to) {
+    return isPathInside(from, target) ? resolve(to, relative(resolve(from), resolve(target))) : target;
+}
+/**
+ * `path` in the spelling every other path here has: the Win32 file-namespace
+ * prefix taken off a drive or UNC path (`\\?\C:\x` → `C:\x`,
+ * `\\?\UNC\host\share\x` → `\\host\share\x`), anything else unchanged.
+ *
+ * Measured 2026-10-21 on Node 24.13.0, Windows 11: `mkdir(dir, { recursive:
+ * true })` — and `mkdirSync` — reports the first directory it created as
+ * `\\?\C:\…\features\archive` for a `dir` of `C:\…\features\archive`, at short
+ * and long path lengths alike; `mkdtemp` and `realpath` return the plain
+ * spelling. `resolve()` keeps the prefix and `relative()` between the two
+ * spellings is an absolute path, so `isPathInside` judged
+ * `C:\…\features\archive` to lie outside `\\?\C:\…\features\archive` — and every
+ * rollback that pruned "up to the directory mkdir created" pruned nothing,
+ * leaving an empty `features/archive/` or `services/<new-service>/` behind at a
+ * clean `merge-failed`. Linux never reports the prefix, so CI could not see it.
+ *
+ * Only the drive and UNC forms are taken off: `\\?\Volume{…}\` and
+ * `\\?\GLOBALROOT\…` have no plain spelling, and stripping theirs would leave a
+ * relative path. A POSIX absolute path starts with `/` and never matches.
+ */
+export function withoutNamespacePrefix(path) {
+    const unc = /^\\\\\?\\UNC\\/i.exec(path);
+    if (unc !== null)
+        return `\\\\${path.slice(unc[0].length)}`;
+    return /^\\\\\?\\[A-Za-z]:(?:\\|$)/.test(path) ? path.slice(4) : path;
+}
 /**
  * Resolve a relative path beneath `root`, rejecting absolute paths, explicit
  * parent traversal, and symlink escape. The final path may be absent: its
@@ -73,9 +111,10 @@ export function resolveInside(root, candidate, label = "path") {
 /**
  * Snapshot manifests are portable data, so their path spelling is stricter
  * than an interactive path: forward slashes, no redundant components, and a
- * file (not directory) name at the end.
+ * file (not directory) name at the end. The one constructor of `PortablePath`,
+ * because these checks are what the brand asserts.
  */
-export function resolvePortableFileInside(root, candidate, label = "path") {
+export function portablePathOf(candidate, label = "path") {
     if (candidate.includes("\\")) {
         throw new UnsafePathError(candidate, `${label} must use forward slashes`);
     }
@@ -83,7 +122,20 @@ export function resolvePortableFileInside(root, candidate, label = "path") {
     if (parts.some((part) => part === "" || part === "." || part === "..")) {
         throw new UnsafePathError(candidate, `${label} must be a canonical relative file path`);
     }
-    return resolveInside(root, candidate, label);
+    // The cast, on the line immediately after the checks that earn it.
+    return candidate;
+}
+/**
+ * Containment for a path that already EARNED the portable spelling — the one
+ * signature that demands the brand, so `PortablePath` has a consumer the
+ * compiler checks rather than a comment claiming the order of two calls.
+ */
+function resolvePortableInside(root, portable, label) {
+    return resolveInside(root, portable, label);
+}
+/** The portable spelling checks, then `resolveInside`'s containment proof — the ONE spelling of the pair. */
+export function resolvePortableFileInside(root, candidate, label = "path") {
+    return resolvePortableInside(root, portablePathOf(candidate, label), label);
 }
 /**
  * The same portable spelling rules, with containment judged LEXICALLY — for a
@@ -99,7 +151,7 @@ export function resolvePortableFileInside(root, candidate, label = "path") {
  * between two checkouts — is a supported layout that every walk of the repo
  * FOLLOWS rather than refuses (repo.ts's `entryIs` says so in full), and that
  * `archive` already writes through: its living-document writes are planned from
- * `servicePaths()` and never see this file. With the realpath test in force on
+ * `unfiledServicePaths()`/`servicePathsAt()` and never see this file. With the realpath test in force on
  * the manifest's `path` field, a `services/<svc>/` mounted that way made an
  * interrupted archive permanently unrepairable — the retry was told the
  * snapshot could not be read when it was perfectly intact, and the half-merge it

package/dist/core/kernel/path-safety.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-safety.js","sourceRoot":"","sources":["../../../src/core/kernel/path-safety.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Resolve caller-controlled paths without letting them leave an owned tree.\n *\n * A lexical `relative()` check is not enough: an existing component may be a\n * symlink whose target lives elsewhere. Conversely, checking only the final\n * path misses destinations that do not exist yet but whose nearest existing\n * parent is a symlink. This helper checks both views before a caller reads,\n * writes, walks, or removes anything.\n */\nimport { lstatSync, realpathSync } from \"node:fs\";\nimport { dirname, isAbsolute, relative, resolve, sep, win32 } from \"node:path\";\n\nexport class UnsafePathError extends Error {\n  constructor(\n    readonly candidate: string,\n    message: string,\n  ) {\n    super(message);\n    this.name = \"UnsafePathError\";\n  }\n}\n\n/** True when `target` is `root` or one of its descendants. */\nexport function isPathInside(root: string, target: string): boolean {\n  const rel = relative(resolve(root), resolve(target));\n  return rel === \"\" || (!isAbsolute(rel) && rel !== \"..\" && !rel.startsWith(`..${sep}`));\n}\n\n/**\n * Where `target` is once the directory `from` has been renamed to `to`: its\n * image under `to` when it is inside `from`, `target` itself when it is not.\n * Absolute paths in and out. The question every reader of a directory move\n * asks of one path: the link rewrites of both renames loam makes (`subsystem\n * move`, and `archive` for the feature's own documents), and the archive's\n * snapshot, crash repair and `unarchive`'s report, which meet those documents\n * on either side of the move.\n */\nexport function acrossRename(target: string, from: string, to: string): string {\n  return isPathInside(from, target) ? resolve(to, relative(resolve(from), resolve(target))) : target;\n}\n\n/**\n * `path` in the spelling every other path here has: the Win32 file-namespace\n * prefix taken off a drive or UNC path (`\\\\?\\C:\\x` → `C:\\x`,\n * `\\\\?\\UNC\\host\\share\\x` → `\\\\host\\share\\x`), anything else unchanged.\n *\n * Measured 2026-10-21 on Node 24.13.0, Windows 11: `mkdir(dir, { recursive:\n * true })` — and `mkdirSync` — reports the first directory it created as\n * `\\\\?\\C:\\…\\features\\archive` for a `dir` of `C:\\…\\features\\archive`, at short\n * and long path lengths alike; `mkdtemp` and `realpath` return the plain\n * spelling. `resolve()` keeps the prefix and `relative()` between the two\n * spellings is an absolute path, so `isPathInside` judged\n * `C:\\…\\features\\archive` to lie outside `\\\\?\\C:\\…\\features\\archive` — and every\n * rollback that pruned \"up to the directory mkdir created\" pruned nothing,\n * leaving an empty `features/archive/` or `services/<new-service>/` behind at a\n * clean `merge-failed`. Linux never reports the prefix, so CI could not see it.\n *\n * Only the drive and UNC forms are taken off: `\\\\?\\Volume{…}\\` and\n * `\\\\?\\GLOBALROOT\\…` have no plain spelling, and stripping theirs would leave a\n * relative path. A POSIX absolute path starts with `/` and never matches.\n */\nexport function withoutNamespacePrefix(path: string): string {\n  const unc = /^\\\\\\\\\\?\\\\UNC\\\\/i.exec(path);\n  if (unc !== null) return `\\\\\\\\${path.slice(unc[0].length)}`;\n  return /^\\\\\\\\\\?\\\\[A-Za-z]:(?:\\\\|$)/.test(path) ? path.slice(4) : path;\n}\n\n/**\n * Resolve a relative path beneath `root`, rejecting absolute paths, explicit\n * parent traversal, and symlink escape. The final path may be absent: its\n * nearest existing ancestor is checked in that case.\n */\nexport function resolveInside(root: string, candidate: string, label = \"path\"): string {\n  if (candidate.length === 0) {\n    throw new UnsafePathError(candidate, `${label} must not be empty`);\n  }\n  // win32.isAbsolute is intentional even on POSIX. Persisted/configured paths\n  // may be moved between operating systems, and `C:\\\\...` must never turn into\n  // an innocuous relative filename merely because validation ran on Linux.\n  if (isAbsolute(candidate) || win32.isAbsolute(candidate)) {\n    throw new UnsafePathError(candidate, `${label} must be relative to its owning directory`);\n  }\n  if (candidate.split(/[\\\\/]/).includes(\"..\")) {\n    throw new UnsafePathError(candidate, `${label} must not contain '..' path segments`);\n  }\n\n  const rootAbs = resolve(root);\n  const target = resolve(rootAbs, candidate);\n  if (!isPathInside(rootAbs, target)) {\n    throw new UnsafePathError(candidate, `${label} resolves outside its owning directory`);\n  }\n\n  let rootReal: string;\n  let existing: string;\n  try {\n    rootReal = realpathSync(rootAbs);\n    existing = nearestExisting(target, rootAbs);\n  } catch (err) {\n    const detail = err instanceof Error ? err.message : String(err);\n    throw new UnsafePathError(candidate, `${label} cannot be resolved safely: ${detail}`);\n  }\n\n  let existingReal: string;\n  try {\n    existingReal = realpathSync(existing);\n  } catch (err) {\n    // A broken symlink is an existing path according to lstat, but realpath\n    // cannot prove where a later write through it would land. Refuse it.\n    const detail = err instanceof Error ? err.message : String(err);\n    throw new UnsafePathError(candidate, `${label} crosses an unreadable or broken symlink: ${detail}`);\n  }\n  if (!isPathInside(rootReal, existingReal)) {\n    throw new UnsafePathError(candidate, `${label} crosses a symlink outside its owning directory`);\n  }\n  return target;\n}\n\n/**\n * A relative file path in the portable spelling — forward slashes, no\n * redundant components. The brand's provenance is `portablePathOf` below: the\n * spelling checks there are the only way to construct one, so a value carrying\n * it has demonstrably passed them. Deliberately thin: it says nothing about\n * containment (that stays `resolveInside`'s question, asked per root), and it\n * is consumed by `resolvePortableInside` below — the one signature that\n * demands it — and every boundary (verify's evidence, unarchive's manifests)\n * reaches it through `resolvePortableFileInside`, the pair's one spelling.\n * The staging manifests keep their plain strings until the writer work that\n * owns those formats re-keys them.\n */\ndeclare const portable: unique symbol;\nexport type PortablePath = string & { readonly [portable]: true };\n\n/**\n * Snapshot manifests are portable data, so their path spelling is stricter\n * than an interactive path: forward slashes, no redundant components, and a\n * file (not directory) name at the end. The one constructor of `PortablePath`,\n * because these checks are what the brand asserts.\n */\nexport function portablePathOf(candidate: string, label = \"path\"): PortablePath {\n  if (candidate.includes(\"\\\\\")) {\n    throw new UnsafePathError(candidate, `${label} must use forward slashes`);\n  }\n  const parts = candidate.split(\"/\");\n  if (parts.some((part) => part === \"\" || part === \".\" || part === \"..\")) {\n    throw new UnsafePathError(candidate, `${label} must be a canonical relative file path`);\n  }\n  // The cast, on the line immediately after the checks that earn it.\n  return candidate as PortablePath;\n}\n\n/**\n * Containment for a path that already EARNED the portable spelling — the one\n * signature that demands the brand, so `PortablePath` has a consumer the\n * compiler checks rather than a comment claiming the order of two calls.\n */\nfunction resolvePortableInside(root: string, portable: PortablePath, label: string): string {\n  return resolveInside(root, portable, label);\n}\n\n/** The portable spelling checks, then `resolveInside`'s containment proof — the ONE spelling of the pair. */\nexport function resolvePortableFileInside(root: string, candidate: string, label = \"path\"): string {\n  return resolvePortableInside(root, portablePathOf(candidate, label), label);\n}\n\n/**\n * The same portable spelling rules, with containment judged LEXICALLY — for a\n * path that names a file the docs repo itself mounts.\n *\n * Every spelling defence above is kept, and for its reason: a snapshot manifest\n * is loam's own file, but a corrupted or hostile one could carry `..` segments,\n * an absolute path or a `C:\\` spelling, and what comes out of this join is a\n * path a caller then goes and reads.\n *\n * What is deliberately not applied is the realpath test. Composing a docs repo\n * out of symlinks — a worktree, a submodule, one service's directory shared\n * between two checkouts — is a supported layout that every walk of the repo\n * FOLLOWS rather than refuses (repo.ts's `entryIs` says so in full), and that\n * `archive` already writes through: its living-document writes are planned from\n * `unfiledServicePaths()`/`servicePathsAt()` and never see this file. With the realpath test in force on\n * the manifest's `path` field, a `services/<svc>/` mounted that way made an\n * interrupted archive permanently unrepairable — the retry was told the\n * snapshot could not be read when it was perfectly intact, and the half-merge it\n * was the only record of could never be repaired.\n *\n * This is only ever safe on a READ. A symlink that leaves the repo is\n * lexically indistinguishable from a service directory the operator mounted on\n * purpose — `escape/owned.txt` and `services/<svc>/spec.md` are both \"inside\n * docsDir\" until something resolves them — so the realpath test is the only\n * check that can refuse the first, at the price of also refusing the second.\n * A caller that goes on to WRITE through the path must pay that price and use\n * `resolvePortableFileInside`; `unarchive` does, and says so where it does.\n * A caller that only reads a file and compares a digest it never discloses\n * gains nothing from refusing, and loses the operator's ability to repair an\n * interrupted archive.\n */\nexport function resolvePortableFileInsideLexically(root: string, candidate: string, label = \"path\"): string {\n  if (candidate.length === 0) {\n    throw new UnsafePathError(candidate, `${label} must not be empty`);\n  }\n  if (candidate.includes(\"\\\\\")) {\n    throw new UnsafePathError(candidate, `${label} must use forward slashes`);\n  }\n  const parts = candidate.split(\"/\");\n  if (parts.some((part) => part === \"\" || part === \".\" || part === \"..\")) {\n    throw new UnsafePathError(candidate, `${label} must be a canonical relative file path`);\n  }\n  // win32.isAbsolute is intentional even on POSIX, for the reason `resolveInside`\n  // gives: a snapshot travels with its feature directory between operating\n  // systems, and `C:\\...` must never turn into an innocuous relative filename\n  // merely because the question was asked on Linux.\n  if (isAbsolute(candidate) || win32.isAbsolute(candidate)) {\n    throw new UnsafePathError(candidate, `${label} must be relative to its owning directory`);\n  }\n  const rootAbs = resolve(root);\n  const target = resolve(rootAbs, ...parts);\n  // Already implied by the segment test above, and asked anyway: this line is\n  // the containment claim itself, so a later loosening of the spelling rules\n  // cannot quietly stop making it.\n  if (!isPathInside(rootAbs, target)) {\n    throw new UnsafePathError(candidate, `${label} resolves outside its owning directory`);\n  }\n  return target;\n}\n\n/** Find the closest lexically contained path that exists, including symlinks. */\nfunction nearestExisting(target: string, root: string): string {\n  let current = target;\n  for (;;) {\n    try {\n      lstatSync(current);\n      return current;\n    } catch (err) {\n      const code = (err as NodeJS.ErrnoException).code;\n      if (code !== \"ENOENT\" && code !== \"ENOTDIR\") throw err;\n    }\n    if (current === root) return root;\n    const parent = dirname(current);\n    if (parent === current || !isPathInside(root, parent)) return root;\n    current = parent;\n  }\n}\n"]}

package/dist/core/{records.js → kernel/records.js}

@@ -16,6 +16,17 @@ export function isRecord(value) {
 export function asRecord(value) {
     return isRecord(value) ? value : null;
 }
+/**
+ * A list of strings. `Array.isArray` narrows an `unknown` to `any[]`, so an
+ * element check written below it proved nothing to tsc and the elements had to
+ * be asserted back to `string` at the point of use — how a checked element
+ * type went on being asserted back in a line later. Deciding both halves in
+ * one predicate makes the narrowing carry the check. (It was written twice,
+ * once in the OpenSpec scan and once in the migration's mapping reader.)
+ */
+export function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
 /**
  * A map whose keys come from a document somebody else wrote.
  *

package/dist/core/kernel/records.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"records.js","sourceRoot":"","sources":["../../../src/core/kernel/records.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,+DAA+D;AAC/D,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AACxC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC;AACjF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,UAAU;IACxB,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAsB,CAAC;AAClD,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,QAAQ,CAAI,MAAyB,EAAE,GAAW;IAChE,OAAO,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACrF,CAAC","sourcesContent":["/**\n * The shapes an unknown parsed document is asked about, in one place.\n *\n * Every YAML and JSON file loam reads arrives as `unknown`, and every reader\n * has to answer the same first question before it can look at a key: is this an\n * object at all? Six modules each carried their own copy of the answer, two of\n * them spelled with a cast — and a cast is exactly what this test exists to\n * make unnecessary, since the predicate form hands the caller a narrowed type\n * that tsc keeps checking. A leaf with no imports, so any layer can ask.\n */\n\n/** An object with string keys — not null, and not an array. */\nexport function isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\n/** The same question where the answer is used rather than branched on. */\nexport function asRecord(value: unknown): Record<string, unknown> | null {\n  return isRecord(value) ? value : null;\n}\n\n/**\n * A list of strings. `Array.isArray` narrows an `unknown` to `any[]`, so an\n * element check written below it proved nothing to tsc and the elements had to\n * be asserted back to `string` at the point of use — how a checked element\n * type went on being asserted back in a line later. Deciding both halves in\n * one predicate makes the narrowing carry the check. (It was written twice,\n * once in the OpenSpec scan and once in the migration's mapping reader.)\n */\nexport function isStringArray(value: unknown): value is string[] {\n  return Array.isArray(value) && value.every((item) => typeof item === \"string\");\n}\n\n/**\n * A map whose keys come from a document somebody else wrote.\n *\n * `Object.create(null)` rather than `{}` because a key read out of untrusted\n * YAML can be `__proto__` or `constructor`, and on a normal object those either\n * mutate the prototype or read back a function that was never in the file.\n */\nexport function dictionary<T>(): Record<string, T> {\n  return Object.create(null) as Record<string, T>;\n}\n\n/** The value a record actually holds for `key`, never one it inherited. */\nexport function ownValue<T>(record: Record<string, T>, key: string): T | undefined {\n  return Object.prototype.hasOwnProperty.call(record, key) ? record[key] : undefined;\n}\n"]}

package/dist/core/links/backlinks.js

@@ -0,0 +1,66 @@
+/**
+ * Who links to what, across the whole repository — the link graph read
+ * backwards.
+ *
+ * `link.unresolved` asks each document about its own links. This asks the
+ * opposite question, and it is the one the glossary is built on: "which
+ * documents use this term" is exactly "which documents link to `glossary/<term>.md`",
+ * and no single target can answer it. A term is cited from a service's spec, a
+ * capability document and a feature's intent, so the index is fleet-scope by
+ * construction.
+ *
+ * IT IS THE SAME WALK AS THE FINDING, deliberately — `resolveLinks` produces
+ * both halves of one answer, and the corpus is `core/links/corpus.ts`'s single
+ * definition. An index built from a second enumeration would report a term as
+ * unused while the document citing it was being graded one target over.
+ *
+ * AN UNREADABLE DOCUMENT IS RETURNED, not swallowed. A term can only be shown as
+ * cited by nobody if loam actually read everybody, and a UTF-16 spec.md would
+ * otherwise turn into a silently missing citation. Under `validate` the same
+ * file already earns `link.unreadable`; `loam list` has no such finding, so it
+ * needs the list to say what it did not read.
+ */
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { repoPath } from "../envelope/json.js";
+import { pathCaseIndex } from "./case.js";
+import { allAuthoredDocuments } from "./corpus.js";
+import { resolveLinks } from "./findings.js";
+/**
+ * Build the index over every authored document in the repository.
+ *
+ * One `pathCaseIndex` for the whole walk, because this one really is fleet-wide
+ * and the same directories are asked about hundreds of times. Still not a
+ * module-level cache: it lives exactly as long as this call.
+ */
+export async function backlinkIndex(docsDir, fleet) {
+    const linkers = new Map();
+    const unreadable = [];
+    const scope = { docsDir, cases: pathCaseIndex() };
+    for (const path of await allAuthoredDocuments(docsDir, fleet)) {
+        if (!existsSync(path))
+            continue;
+        let text;
+        try {
+            text = await fleet.readText(path);
+        }
+        catch {
+            unreadable.push(repoPath(docsDir, path));
+            continue;
+        }
+        const from = repoPath(docsDir, path);
+        for (const { target } of resolveLinks({ path, text }, scope).resolved) {
+            const key = resolve(target);
+            let sources = linkers.get(key);
+            if (sources === undefined)
+                linkers.set(key, (sources = new Set()));
+            sources.add(from);
+        }
+    }
+    unreadable.sort();
+    return {
+        linkersOf: (target) => [...(linkers.get(resolve(target)) ?? [])].sort(),
+        unreadable,
+    };
+}
+//# sourceMappingURL=backlinks.js.map

package/dist/core/links/backlinks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backlinks.js","sourceRoot":"","sources":["../../../src/core/links/backlinks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAG/C,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAS7C;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,OAAgB,EAAE,KAAmB;IACvE,MAAM,OAAO,GAAG,IAAI,GAAG,EAAuB,CAAC;IAC/C,MAAM,UAAU,GAAa,EAAE,CAAC;IAChC,MAAM,KAAK,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,EAAE,CAAC;IAClD,KAAK,MAAM,IAAI,IAAI,MAAM,oBAAoB,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,CAAC;QAC9D,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,SAAS;QAChC,IAAI,IAAY,CAAC;QACjB,IAAI,CAAC;YACH,IAAI,GAAG,MAAM,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QACpC,CAAC;QAAC,MAAM,CAAC;YACP,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC;YACzC,SAAS;QACX,CAAC;QACD,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QACrC,KAAK,MAAM,EAAE,MAAM,EAAE,IAAI,YAAY,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,KAAK,CAAC,CAAC,QAAQ,EAAE,CAAC;YACtE,MAAM,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;YAC5B,IAAI,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC/B,IAAI,OAAO,KAAK,SAAS;gBAAE,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,OAAO,GAAG,IAAI,GAAG,EAAE,CAAC,CAAC,CAAC;YACnE,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACpB,CAAC;IACH,CAAC;IACD,UAAU,CAAC,IAAI,EAAE,CAAC;IAClB,OAAO;QACL,SAAS,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE;QACvE,UAAU;KACX,CAAC;AACJ,CAAC","sourcesContent":["/**\n * Who links to what, across the whole repository — the link graph read\n * backwards.\n *\n * `link.unresolved` asks each document about its own links. This asks the\n * opposite question, and it is the one the glossary is built on: \"which\n * documents use this term\" is exactly \"which documents link to `glossary/<term>.md`\",\n * and no single target can answer it. A term is cited from a service's spec, a\n * capability document and a feature's intent, so the index is fleet-scope by\n * construction.\n *\n * IT IS THE SAME WALK AS THE FINDING, deliberately — `resolveLinks` produces\n * both halves of one answer, and the corpus is `core/links/corpus.ts`'s single\n * definition. An index built from a second enumeration would report a term as\n * unused while the document citing it was being graded one target over.\n *\n * AN UNREADABLE DOCUMENT IS RETURNED, not swallowed. A term can only be shown as\n * cited by nobody if loam actually read everybody, and a UTF-16 spec.md would\n * otherwise turn into a silently missing citation. Under `validate` the same\n * file already earns `link.unreadable`; `loam list` has no such finding, so it\n * needs the list to say what it did not read.\n */\nimport { existsSync } from \"node:fs\";\nimport { resolve } from \"node:path\";\nimport { repoPath } from \"../envelope/json.js\";\nimport type { FleetContext } from \"../fleet-context.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\nimport { pathCaseIndex } from \"./case.js\";\nimport { allAuthoredDocuments } from \"./corpus.js\";\nimport { resolveLinks } from \"./findings.js\";\n\nexport interface BacklinkIndex {\n  /** Repo-relative paths of the documents linking to `target`, ordered, without duplicates. */\n  linkersOf(target: string): string[];\n  /** Repo-relative paths of documents whose links could not be read at all. */\n  unreadable: string[];\n}\n\n/**\n * Build the index over every authored document in the repository.\n *\n * One `pathCaseIndex` for the whole walk, because this one really is fleet-wide\n * and the same directories are asked about hundreds of times. Still not a\n * module-level cache: it lives exactly as long as this call.\n */\nexport async function backlinkIndex(docsDir: DocsDir, fleet: FleetContext): Promise<BacklinkIndex> {\n  const linkers = new Map<string, Set<string>>();\n  const unreadable: string[] = [];\n  const scope = { docsDir, cases: pathCaseIndex() };\n  for (const path of await allAuthoredDocuments(docsDir, fleet)) {\n    if (!existsSync(path)) continue;\n    let text: string;\n    try {\n      text = await fleet.readText(path);\n    } catch {\n      unreadable.push(repoPath(docsDir, path));\n      continue;\n    }\n    const from = repoPath(docsDir, path);\n    for (const { target } of resolveLinks({ path, text }, scope).resolved) {\n      const key = resolve(target);\n      let sources = linkers.get(key);\n      if (sources === undefined) linkers.set(key, (sources = new Set()));\n      sources.add(from);\n    }\n  }\n  unreadable.sort();\n  return {\n    linkersOf: (target) => [...(linkers.get(resolve(target)) ?? [])].sort(),\n    unreadable,\n  };\n}\n"]}

package/dist/core/links/case.js

@@ -0,0 +1,74 @@
+/**
+ * Is a path spelled the way it is stored — the half of "does this link resolve"
+ * that `existsSync` cannot answer.
+ *
+ * `[Order](Order.md)` beside a file called `order.md` resolves on Windows and
+ * macOS and 404s on GitHub, which renders these documents and is
+ * case-sensitive, as is every Linux CI runner. That is the exact shape loam
+ * refuses everywhere else: a check that is green on the author's machine and red
+ * where the work is actually read. `link.unresolved` shipped without it as a
+ * recorded limit; this closes it.
+ *
+ * THE ANSWER IS A DIRECTORY LISTING, not a filesystem probe, because a probe is
+ * what is already wrong: on a case-insensitive volume every spelling of a name
+ * stats successfully, so the only place the true spelling exists is the parent's
+ * own listing. Each path segment between the docs root and the target is
+ * checked against that listing, verbatim.
+ *
+ * THE INDEX IS PER-INVOCATION AND PASSED, never module-level. A cached listing
+ * that outlived one command would answer for a directory that has since
+ * changed, and in this repository's forked test processes a module-level memo
+ * leaks between fixtures — `AGENTS.md` names that hazard directly. Cost is one
+ * `readdir` per distinct directory a link points into, which for a docs repo is
+ * a handful.
+ */
+import { readdirSync } from "node:fs";
+import { relative, resolve, sep } from "node:path";
+/** A fresh index. One per command invocation — see the module note on why it is not shared. */
+export function pathCaseIndex() {
+    const listings = new Map();
+    const namesIn = (dir) => {
+        let names = listings.get(dir);
+        if (names === undefined) {
+            try {
+                names = new Set(readdirSync(dir));
+            }
+            catch {
+                // An unreadable directory answers nothing, and the honest reading is
+                // "not disproved": the target stat'ed, so something is there. Refusing
+                // a link because its parent denied a listing would convict the author
+                // for a permission bit.
+                names = new Set();
+            }
+            listings.set(dir, names);
+        }
+        return names;
+    };
+    return {
+        spelledExactly(root, target) {
+            const rootAbs = resolve(root);
+            const rel = relative(rootAbs, resolve(target));
+            if (rel === "")
+                return true;
+            let dir = rootAbs;
+            for (const segment of rel.split(sep)) {
+                const names = namesIn(dir);
+                // The empty set is the unreadable-directory case above: stop asking
+                // rather than convict every segment beneath it.
+                if (names.size > 0 && !names.has(segment))
+                    return false;
+                dir = resolve(dir, segment);
+            }
+            return true;
+        },
+        storedAs(dir, name) {
+            const wanted = name.toLowerCase();
+            for (const stored of namesIn(resolve(dir))) {
+                if (stored !== name && stored.toLowerCase() === wanted)
+                    return stored;
+            }
+            return undefined;
+        },
+    };
+}
+//# sourceMappingURL=case.js.map

package/dist/core/links/case.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"case.js","sourceRoot":"","sources":["../../../src/core/links/case.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACtC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAsBnD,+FAA+F;AAC/F,MAAM,UAAU,aAAa;IAC3B,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAuB,CAAC;IAChD,MAAM,OAAO,GAAG,CAAC,GAAW,EAAe,EAAE;QAC3C,IAAI,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,IAAI,CAAC;gBACH,KAAK,GAAG,IAAI,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC;YACpC,CAAC;YAAC,MAAM,CAAC;gBACP,qEAAqE;gBACrE,uEAAuE;gBACvE,sEAAsE;gBACtE,wBAAwB;gBACxB,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;YAC5B,CAAC;YACD,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC3B,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;IAEF,OAAO;QACL,cAAc,CAAC,IAAI,EAAE,MAAM;YACzB,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;YAC9B,MAAM,GAAG,GAAG,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;YAC/C,IAAI,GAAG,KAAK,EAAE;gBAAE,OAAO,IAAI,CAAC;YAC5B,IAAI,GAAG,GAAG,OAAO,CAAC;YAClB,KAAK,MAAM,OAAO,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;gBACrC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;gBAC3B,oEAAoE;gBACpE,gDAAgD;gBAChD,IAAI,KAAK,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC;oBAAE,OAAO,KAAK,CAAC;gBACxD,GAAG,GAAG,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;YAC9B,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;QACD,QAAQ,CAAC,GAAG,EAAE,IAAI;YAChB,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;YAClC,KAAK,MAAM,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;gBAC3C,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,CAAC,WAAW,EAAE,KAAK,MAAM;oBAAE,OAAO,MAAM,CAAC;YACxE,CAAC;YACD,OAAO,SAAS,CAAC;QACnB,CAAC;KACF,CAAC;AACJ,CAAC","sourcesContent":["/**\n * Is a path spelled the way it is stored — the half of \"does this link resolve\"\n * that `existsSync` cannot answer.\n *\n * `[Order](Order.md)` beside a file called `order.md` resolves on Windows and\n * macOS and 404s on GitHub, which renders these documents and is\n * case-sensitive, as is every Linux CI runner. That is the exact shape loam\n * refuses everywhere else: a check that is green on the author's machine and red\n * where the work is actually read. `link.unresolved` shipped without it as a\n * recorded limit; this closes it.\n *\n * THE ANSWER IS A DIRECTORY LISTING, not a filesystem probe, because a probe is\n * what is already wrong: on a case-insensitive volume every spelling of a name\n * stats successfully, so the only place the true spelling exists is the parent's\n * own listing. Each path segment between the docs root and the target is\n * checked against that listing, verbatim.\n *\n * THE INDEX IS PER-INVOCATION AND PASSED, never module-level. A cached listing\n * that outlived one command would answer for a directory that has since\n * changed, and in this repository's forked test processes a module-level memo\n * leaks between fixtures — `AGENTS.md` names that hazard directly. Cost is one\n * `readdir` per distinct directory a link points into, which for a docs repo is\n * a handful.\n */\nimport { readdirSync } from \"node:fs\";\nimport { relative, resolve, sep } from \"node:path\";\n\nexport interface PathCaseIndex {\n  /**\n   * True when every segment of `target` below `root` is spelled exactly as the\n   * filesystem stores it. `target` must already be known to lie inside `root`;\n   * this asks only about spelling.\n   */\n  spelledExactly(root: string, target: string): boolean;\n  /**\n   * The name `dir` actually stores for `name`, when one differs from it only by\n   * case — the hint that turns \"resolves to nothing\" into \"you spelled it\n   * `Order.md` and it is stored as `order.md`\".\n   *\n   * Asked on both platforms and not only the case-insensitive one, which is the\n   * whole point: on Linux the same link fails `existsSync` outright and on\n   * Windows it fails `spelledExactly`, and a diagnosis that differed by\n   * operating system would be a machine contract that does not hold.\n   */\n  storedAs(dir: string, name: string): string | undefined;\n}\n\n/** A fresh index. One per command invocation — see the module note on why it is not shared. */\nexport function pathCaseIndex(): PathCaseIndex {\n  const listings = new Map<string, Set<string>>();\n  const namesIn = (dir: string): Set<string> => {\n    let names = listings.get(dir);\n    if (names === undefined) {\n      try {\n        names = new Set(readdirSync(dir));\n      } catch {\n        // An unreadable directory answers nothing, and the honest reading is\n        // \"not disproved\": the target stat'ed, so something is there. Refusing\n        // a link because its parent denied a listing would convict the author\n        // for a permission bit.\n        names = new Set<string>();\n      }\n      listings.set(dir, names);\n    }\n    return names;\n  };\n\n  return {\n    spelledExactly(root, target) {\n      const rootAbs = resolve(root);\n      const rel = relative(rootAbs, resolve(target));\n      if (rel === \"\") return true;\n      let dir = rootAbs;\n      for (const segment of rel.split(sep)) {\n        const names = namesIn(dir);\n        // The empty set is the unreadable-directory case above: stop asking\n        // rather than convict every segment beneath it.\n        if (names.size > 0 && !names.has(segment)) return false;\n        dir = resolve(dir, segment);\n      }\n      return true;\n    },\n    storedAs(dir, name) {\n      const wanted = name.toLowerCase();\n      for (const stored of namesIn(resolve(dir))) {\n        if (stored !== name && stored.toLowerCase() === wanted) return stored;\n      }\n      return undefined;\n    },\n  };\n}\n"]}

package/dist/core/links/corpus.js

@@ -0,0 +1,118 @@
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { featureGlossary } from "../glossary/delta.js";
+import { readGlossary } from "../glossary/tree.js";
+import { featurePaths, featureSpecPaths, fleetAdrsDir, servicePathsAt } from "../repo/paths.js";
+import { glossaryDir } from "../repo/authored/paths.js";
+import { featureSpecServices, listFeatures, listServices } from "../repo/repo.js";
+import { markdownFiles } from "../repo/tree/fs.js";
+/**
+ * One service's authored documents: the two requirement specs, the runbook, and
+ * every ADR. The specs cost nothing extra: the run's `FleetContext` has already
+ * read both to parse their requirements, and the memo hands back the same text.
+ */
+export async function serviceDocuments(paths) {
+    return [paths.spec, paths.archSpec, paths.runbook, ...(await markdownFiles(paths.adrsDir))];
+}
+/**
+ * One feature's authored documents: the intent, each addressed service's two
+ * spec deltas, every ADR, and each capability delta document.
+ */
+export async function featureDocuments(featureDir, fleet) {
+    const paths = featurePaths(featureDir);
+    const docs = [paths.intent, ...(await markdownFiles(paths.adrsDir))];
+    for (const svc of await featureSpecServices(featureDir, fleet)) {
+        const spec = featureSpecPaths(featureDir, svc);
+        docs.push(spec.spec, spec.archSpec);
+    }
+    const capabilities = await fleet.featureCapabilityDeltas(featureDir);
+    docs.push(...capabilities.docs.map((d) => d.spec));
+    // The definitions this feature introduces. Their own links are graded like
+    // any other document's — a term that cites a term the feature is not adding
+    // is a broken join whether or not it has shipped yet.
+    docs.push(...(await featureGlossary(featureDir)).terms.map((t) => t.path));
+    return docs;
+}
+/**
+ * The documents that belong to no service and no feature: the fleet's own
+ * decision records, the living capability tree, and the glossary.
+ *
+ * Graded at fleet scope, so `validate --all` reports them once. A single-target
+ * run says nothing about them — the rule `permissions.unenforced` and
+ * `capability.invalid` already follow, and for the same reason: a finding about
+ * the fleet repeated on every service target is the report.
+ */
+export async function fleetDocuments(docsDir, fleet) {
+    const capabilities = (await fleet.capabilities(docsDir)).tree;
+    const glossary = await readGlossary(glossaryDir(docsDir));
+    return [
+        ...(await markdownFiles(fleetAdrsDir(docsDir))),
+        ...capabilities.docs.map((d) => d.spec),
+        ...glossary.terms.map((t) => t.path),
+    ];
+}
+/**
+ * Every authored document in the repository — the union of the three above over
+ * every service and every in-flight feature.
+ *
+ * ARCHIVED FEATURES ARE OUT, and the omission is the point rather than an
+ * oversight. `features/archive/<FEAT>/` is the evolution history: its documents
+ * describe a change that already shipped, its links point at whatever the tree
+ * looked like then, and grading them would make every directory rename a
+ * retroactive error against a record nobody may edit. `listFeatures` excludes
+ * them by default, which is the same judgement one enumeration up. "Then" is
+ * the commit that archived the feature, and not the one before it: the archive
+ * re-expresses the links in the documents it moves (`movedMarkdown` below,
+ * `commands/archive/plan/document/links.ts`), because its own rename is the one
+ * change to the tree it knows exactly and makes in the same breath.
+ */
+export async function allAuthoredDocuments(docsDir, fleet) {
+    const docs = await fleetDocuments(docsDir, fleet);
+    for (const service of await listServices(docsDir, fleet)) {
+        docs.push(...(await serviceDocuments(servicePathsAt(service.dir))));
+    }
+    for (const feature of await listFeatures(docsDir, {}, fleet)) {
+        docs.push(...(await featureDocuments(feature.dir, fleet)));
+    }
+    return docs;
+}
+/**
+ * Every `.md` file under `dir`, at any depth, sorted — the documents a rename
+ * of `dir` carries with it, which is a different list from the corpus above:
+ * a rename moves a runbook, a subsystem's own notes, a feature's
+ * `legacy/proposal.md` exactly as it moves an ADR, and owes them all the same
+ * link correction whether or not anything grades them.
+ *
+ * Real directories and files only: a symlink is not followed — what it points
+ * at is not moved by the rename — and dot-directories and `node_modules` are
+ * machinery, never authored documents, exactly as every other walk in loam
+ * treats them. The archive's own `.loam-before/` is one of them: its
+ * pre-images are bytes to put back, not documents to correct.
+ *
+ * Two callers, the two directory renames loam makes: `subsystem move`
+ * (`commands/subsystem/txn/links.ts`) and `archive`
+ * (`commands/archive/plan/document/links.ts`). Here, below both, because the
+ * rule for "what does the rename carry" is one rule.
+ */
+export async function movedMarkdown(dir) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const entry of entries) {
+        const path = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (!entry.name.startsWith(".") && entry.name !== "node_modules")
+                out.push(...(await movedMarkdown(path)));
+        }
+        else if (entry.isFile() && entry.name.endsWith(".md")) {
+            out.push(path);
+        }
+    }
+    return out.sort();
+}
+//# sourceMappingURL=corpus.js.map

package/dist/core/links/corpus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"corpus.js","sourceRoot":"","sources":["../../../src/core/links/corpus.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * WHICH documents loam reads links out of — the corpus, spelled once.\n *\n * Two readers need it and must not disagree. `commands/validate/links/` grades\n * each target's own documents for `link.unresolved`; `core/links/backlinks.ts`\n * reads the WHOLE fleet's, because \"which documents use this term\" is a question\n * no single target can answer. A corpus that differed between them would report\n * a term as unused while the very document citing it was being graded one target\n * over. The two directory renames read it too — `subsystem move`\n * (`commands/subsystem/txn/links.ts`) and `archive`\n * (`commands/archive/plan/document/links.ts`) rewrite the links INTO what they\n * move from every document here — for the same reason from the other side: a\n * document `validate` grades that a rename did not relink is `link.unresolved`\n * the commit after.\n *\n * THE CORPUS IS EVERY AUTHORED MARKDOWN DOCUMENT, and the word doing the work is\n * authored. `AGENTS.md` and the scaffolded `README.md` are excluded because loam\n * WRITES them: a finding against generated prose names a defect its reader\n * cannot fix by editing, since the next `loam init` restores it. Their links are\n * loam's own problem, held on this side of the boundary by\n * `test/docs-facts.test.ts` and `test/package-docs.test.ts`.\n *\n * ADRs AND RUNBOOKS ARE IN IT, and they are the reason the convention was\n * written down at all: an ADR that supersedes another says which, by linking to\n * it. They are also the first documents loam reads that it previously only\n * counted, which is what `link.unreadable` exists for.\n *\n * `delta.likec4` IS NOT, and neither is any YAML: this is a markdown question.\n * The one thing a delta holds that addresses another file — `metadata { op }` —\n * has its own resolution and its own findings.\n */\nimport type { Dirent } from \"node:fs\";\nimport { readdir } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport type { FleetContext } from \"../fleet-context.js\";\nimport { featureGlossary } from \"../glossary/delta.js\";\nimport { readGlossary } from \"../glossary/tree.js\";\nimport type { DocsDir, FeatureDir } from \"../kernel/ids/dirs.js\";\nimport { featurePaths, featureSpecPaths, fleetAdrsDir, servicePathsAt, type ServicePaths } from \"../repo/paths.js\";\nimport { glossaryDir } from \"../repo/authored/paths.js\";\nimport { featureSpecServices, listFeatures, listServices } from \"../repo/repo.js\";\nimport { markdownFiles } from \"../repo/tree/fs.js\";\n\n/**\n * One service's authored documents: the two requirement specs, the runbook, and\n * every ADR. The specs cost nothing extra: the run's `FleetContext` has already\n * read both to parse their requirements, and the memo hands back the same text.\n */\nexport async function serviceDocuments(paths: ServicePaths): Promise<string[]> {\n  return [paths.spec, paths.archSpec, paths.runbook, ...(await markdownFiles(paths.adrsDir))];\n}\n\n/**\n * One feature's authored documents: the intent, each addressed service's two\n * spec deltas, every ADR, and each capability delta document.\n */\nexport async function featureDocuments(featureDir: FeatureDir, fleet: FleetContext): Promise<string[]> {\n  const paths = featurePaths(featureDir);\n  const docs = [paths.intent, ...(await markdownFiles(paths.adrsDir))];\n  for (const svc of await featureSpecServices(featureDir, fleet)) {\n    const spec = featureSpecPaths(featureDir, svc);\n    docs.push(spec.spec, spec.archSpec);\n  }\n  const capabilities = await fleet.featureCapabilityDeltas(featureDir);\n  docs.push(...capabilities.docs.map((d) => d.spec));\n  // The definitions this feature introduces. Their own links are graded like\n  // any other document's — a term that cites a term the feature is not adding\n  // is a broken join whether or not it has shipped yet.\n  docs.push(...(await featureGlossary(featureDir)).terms.map((t) => t.path));\n  return docs;\n}\n\n/**\n * The documents that belong to no service and no feature: the fleet's own\n * decision records, the living capability tree, and the glossary.\n *\n * Graded at fleet scope, so `validate --all` reports them once. A single-target\n * run says nothing about them — the rule `permissions.unenforced` and\n * `capability.invalid` already follow, and for the same reason: a finding about\n * the fleet repeated on every service target is the report.\n */\nexport async function fleetDocuments(docsDir: DocsDir, fleet: FleetContext): Promise<string[]> {\n  const capabilities = (await fleet.capabilities(docsDir)).tree;\n  const glossary = await readGlossary(glossaryDir(docsDir));\n  return [\n    ...(await markdownFiles(fleetAdrsDir(docsDir))),\n    ...capabilities.docs.map((d) => d.spec),\n    ...glossary.terms.map((t) => t.path),\n  ];\n}\n\n/**\n * Every authored document in the repository — the union of the three above over\n * every service and every in-flight feature.\n *\n * ARCHIVED FEATURES ARE OUT, and the omission is the point rather than an\n * oversight. `features/archive/<FEAT>/` is the evolution history: its documents\n * describe a change that already shipped, its links point at whatever the tree\n * looked like then, and grading them would make every directory rename a\n * retroactive error against a record nobody may edit. `listFeatures` excludes\n * them by default, which is the same judgement one enumeration up. \"Then\" is\n * the commit that archived the feature, and not the one before it: the archive\n * re-expresses the links in the documents it moves (`movedMarkdown` below,\n * `commands/archive/plan/document/links.ts`), because its own rename is the one\n * change to the tree it knows exactly and makes in the same breath.\n */\nexport async function allAuthoredDocuments(docsDir: DocsDir, fleet: FleetContext): Promise<string[]> {\n  const docs = await fleetDocuments(docsDir, fleet);\n  for (const service of await listServices(docsDir, fleet)) {\n    docs.push(...(await serviceDocuments(servicePathsAt(service.dir))));\n  }\n  for (const feature of await listFeatures(docsDir, {}, fleet)) {\n    docs.push(...(await featureDocuments(feature.dir, fleet)));\n  }\n  return docs;\n}\n\n/**\n * Every `.md` file under `dir`, at any depth, sorted — the documents a rename\n * of `dir` carries with it, which is a different list from the corpus above:\n * a rename moves a runbook, a subsystem's own notes, a feature's\n * `legacy/proposal.md` exactly as it moves an ADR, and owes them all the same\n * link correction whether or not anything grades them.\n *\n * Real directories and files only: a symlink is not followed — what it points\n * at is not moved by the rename — and dot-directories and `node_modules` are\n * machinery, never authored documents, exactly as every other walk in loam\n * treats them. The archive's own `.loam-before/` is one of them: its\n * pre-images are bytes to put back, not documents to correct.\n *\n * Two callers, the two directory renames loam makes: `subsystem move`\n * (`commands/subsystem/txn/links.ts`) and `archive`\n * (`commands/archive/plan/document/links.ts`). Here, below both, because the\n * rule for \"what does the rename carry\" is one rule.\n */\nexport async function movedMarkdown(dir: string): Promise<string[]> {\n  let entries: Dirent[];\n  try {\n    entries = await readdir(dir, { withFileTypes: true });\n  } catch {\n    return [];\n  }\n  const out: string[] = [];\n  for (const entry of entries) {\n    const path = join(dir, entry.name);\n    if (entry.isDirectory()) {\n      if (!entry.name.startsWith(\".\") && entry.name !== \"node_modules\") out.push(...(await movedMarkdown(path)));\n    } else if (entry.isFile() && entry.name.endsWith(\".md\")) {\n      out.push(path);\n    }\n  }\n  return out.sort();\n}\n"]}

package/dist/core/links/findings.js

@@ -0,0 +1,110 @@
+/**
+ * `link.unresolved` — a markdown link in an authored document whose target is
+ * not there, or is there under a different spelling.
+ *
+ * The convention this grades has been written down since the fleet-ADR work and
+ * said, in both `SCHEMA.md` and the generated `AGENTS.md`, that nothing
+ * validated it. This module is what makes that sentence false, and the reason
+ * the convention was chosen is the reason it can: the target of a standard
+ * markdown link is a real relative path, so "does this resolve" has a
+ * filesystem answer, where a wikilink would need Obsidian's
+ * shortest-unique-path search reimplemented — guessing, which loam does not do.
+ *
+ * ERROR, and the severity is the decision the maintainer took against the
+ * alternative of warning outside `glossary/`. A link is a join of the same kind
+ * as `Operations:` and `Covers:`, both of which error when they resolve to
+ * nothing; the fact that this one is written in prose changes who typed it, not
+ * whether it points at something. A fleet adopting loam with rotted links sees
+ * them on its first run — a user-visible widening of the same class as the two
+ * the use-case and business axes shipped, and recorded in CHANGELOG as one.
+ *
+ * ONE FINDING PER DOCUMENT, with every broken link in `details`. A document
+ * whose links have rotted is one editing session and one reviewer, not ten
+ * separate breaches, and per-link findings would let a single stale directory
+ * rename fill a `validate --all` report with the same fix restated.
+ *
+ * THE RESOLUTION IS EXPORTED SEPARATELY from the finding, because a second
+ * reader needs the other half of the answer: the glossary grades a term by who
+ * links TO it, which is this same walk read forwards instead of backwards.
+ */
+import { existsSync } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+import { repoPath } from "../envelope/json.js";
+import { isPathInside } from "../kernel/path-safety.js";
+import { pathCaseIndex } from "./case.js";
+import { documentLinks } from "./parse.js";
+/**
+ * Every link in one document, resolved against the docs repo.
+ *
+ * TARGETS OUTSIDE THE DOCS REPO ARE NEITHER RESOLVED NOR BROKEN, and the
+ * exclusion is honesty rather than leniency. A docs repo is routinely checked
+ * out beside nothing else, so `../../payments-svc/README.md` is a path loam
+ * cannot answer for: the file's absence here is evidence about this checkout,
+ * not about the link. Only a target that stays inside `docsDir` gets a verdict,
+ * which is the same boundary every other reader in loam observes and the reason
+ * the finding below can afford to be an error at all.
+ *
+ * CASE COUNTS, and it must, because the alternative is a check that passes on
+ * the author's machine and fails where the work is read. `existsSync` is
+ * case-insensitive on Windows and macOS; GitHub's renderer and every Linux CI
+ * runner are not. So a resolving link is one that exists AND is spelled the way
+ * the filesystem stores it — and when it is not, `storedAs` carries the real
+ * name into the message, on every platform alike, so the diagnosis does not
+ * depend on which operating system ran the check.
+ */
+export function resolveLinks(doc, scope) {
+    const cases = scope.cases ?? pathCaseIndex();
+    const dir = dirname(doc.path);
+    const linkage = { resolved: [], broken: [] };
+    for (const link of documentLinks(doc.text)) {
+        const target = resolve(dir, link.path);
+        if (!isPathInside(scope.docsDir, target))
+            continue;
+        // The overlay is checked FIRST and without the spelling test: the file is
+        // not on disk, so there is no stored name to compare against, and the id it
+        // came from was a `readdir` entry in the feature's own tree.
+        if (scope.overlay?.has(resolve(target)) === true) {
+            linkage.resolved.push({ link, target });
+            continue;
+        }
+        if (existsSync(target) && cases.spelledExactly(scope.docsDir, target)) {
+            linkage.resolved.push({ link, target });
+            continue;
+        }
+        const storedAs = cases.storedAs(dirname(target), basename(target));
+        linkage.broken.push({ link, ...(storedAs === undefined ? {} : { storedAs }) });
+    }
+    return linkage;
+}
+/** The links in one document that resolve to nothing, as at most one finding. */
+export function unresolvedLinkFindings(doc, scope) {
+    const where = repoPath(scope.docsDir, doc.path);
+    const { broken } = resolveLinks(doc, scope);
+    if (broken.length === 0)
+        return [];
+    return [
+        {
+            severity: "error",
+            code: "link.unresolved",
+            ...(scope.subject === undefined ? {} : { subject: scope.subject }),
+            message: `${where}: ${broken.length} markdown link(s) resolve to nothing. ` +
+                "A link between documents here is a join — fix the path, or write the document it points at. " +
+                "Targets outside the docs repo and links to a heading (`#section`) are not graded.",
+            details: broken.map((one) => detail(where, one)),
+        },
+    ];
+}
+/**
+ * One broken link, spelled so the author can find it: the file and line first,
+ * then the link exactly as written. `raw` rather than the decoded path, because
+ * the decoded form is not the string that is in the document.
+ *
+ * The stored spelling is appended when the only thing wrong is case, because
+ * without it the message reads as a lie — the file the author is being told to
+ * write is already sitting beside the one they linked from.
+ */
+function detail(where, one) {
+    const line = `${where}:${one.link.line}: [${one.link.text}](${one.link.raw})`;
+    return one.storedAs === undefined ? line : `${line} — stored as '${one.storedAs}'`;
+}
+//# sourceMappingURL=findings.js.map

package/dist/core/links/findings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"findings.js","sourceRoot":"","sources":["../../../src/core/links/findings.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `link.unresolved` — a markdown link in an authored document whose target is\n * not there, or is there under a different spelling.\n *\n * The convention this grades has been written down since the fleet-ADR work and\n * said, in both `SCHEMA.md` and the generated `AGENTS.md`, that nothing\n * validated it. This module is what makes that sentence false, and the reason\n * the convention was chosen is the reason it can: the target of a standard\n * markdown link is a real relative path, so \"does this resolve\" has a\n * filesystem answer, where a wikilink would need Obsidian's\n * shortest-unique-path search reimplemented — guessing, which loam does not do.\n *\n * ERROR, and the severity is the decision the maintainer took against the\n * alternative of warning outside `glossary/`. A link is a join of the same kind\n * as `Operations:` and `Covers:`, both of which error when they resolve to\n * nothing; the fact that this one is written in prose changes who typed it, not\n * whether it points at something. A fleet adopting loam with rotted links sees\n * them on its first run — a user-visible widening of the same class as the two\n * the use-case and business axes shipped, and recorded in CHANGELOG as one.\n *\n * ONE FINDING PER DOCUMENT, with every broken link in `details`. A document\n * whose links have rotted is one editing session and one reviewer, not ten\n * separate breaches, and per-link findings would let a single stale directory\n * rename fill a `validate --all` report with the same fix restated.\n *\n * THE RESOLUTION IS EXPORTED SEPARATELY from the finding, because a second\n * reader needs the other half of the answer: the glossary grades a term by who\n * links TO it, which is this same walk read forwards instead of backwards.\n */\nimport { existsSync } from \"node:fs\";\nimport { basename, dirname, resolve } from \"node:path\";\nimport { repoPath } from \"../envelope/json.js\";\nimport { isPathInside } from \"../kernel/path-safety.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\nimport type { Finding } from \"../vocabulary/report.js\";\nimport { pathCaseIndex, type PathCaseIndex } from \"./case.js\";\nimport { documentLinks, type DocumentLink } from \"./parse.js\";\n\n/** One authored document, and the text somebody already read out of it. */\nexport interface LinkedDocument {\n  /** Absolute path of the document — the directory every relative target resolves against. */\n  path: string;\n  text: string;\n}\n\n/** What the finding is filed under, and the tree it may look inside. */\nexport interface LinkScope {\n  docsDir: DocsDir;\n  /** The service or feature the report is about; absent at fleet scope. */\n  subject?: string;\n  /**\n   * The directory-listing memo behind the case check, shared across a whole\n   * run by whoever owns the walk. Omitted, each call builds its own — correct,\n   * just not shared. Never a module-level cache: a listing that outlived one\n   * command would answer for a directory that has since changed.\n   */\n  cases?: PathCaseIndex;\n  /**\n   * Absolute paths that do not exist yet but WILL once an in-flight feature\n   * archives — today, the glossary terms that feature introduces.\n   *\n   * A feature may cite the word it is adding at the word's FUTURE living path,\n   * because that is where the link points once the change lands. Without this\n   * set, the axis would refuse its own headline case — which is exactly the\n   * overlay the capability axis had to add to `Realizes:` after shipping\n   * without one. (Citing the term inside the feature resolves without it, and\n   * archive re-points that spelling when it merges the text that carries it —\n   * SCHEMA \"Conventions\" states the rule.)\n   */\n  overlay?: ReadonlySet<string>;\n}\n\n/** A link that points at a real file inside the docs repo, and the file it points at. */\nexport interface ResolvedLink {\n  link: DocumentLink;\n  /** The absolute path the link names, as `node:path` resolves it. */\n  target: string;\n}\n\n/** One document's links, split by whether the docs repo answers for them. */\nexport interface DocumentLinkage {\n  resolved: ResolvedLink[];\n  /** Links inside the docs repo that name nothing — with the stored spelling, where there is one. */\n  broken: Array<{ link: DocumentLink; storedAs?: string }>;\n}\n\n/**\n * Every link in one document, resolved against the docs repo.\n *\n * TARGETS OUTSIDE THE DOCS REPO ARE NEITHER RESOLVED NOR BROKEN, and the\n * exclusion is honesty rather than leniency. A docs repo is routinely checked\n * out beside nothing else, so `../../payments-svc/README.md` is a path loam\n * cannot answer for: the file's absence here is evidence about this checkout,\n * not about the link. Only a target that stays inside `docsDir` gets a verdict,\n * which is the same boundary every other reader in loam observes and the reason\n * the finding below can afford to be an error at all.\n *\n * CASE COUNTS, and it must, because the alternative is a check that passes on\n * the author's machine and fails where the work is read. `existsSync` is\n * case-insensitive on Windows and macOS; GitHub's renderer and every Linux CI\n * runner are not. So a resolving link is one that exists AND is spelled the way\n * the filesystem stores it — and when it is not, `storedAs` carries the real\n * name into the message, on every platform alike, so the diagnosis does not\n * depend on which operating system ran the check.\n */\nexport function resolveLinks(doc: LinkedDocument, scope: LinkScope): DocumentLinkage {\n  const cases = scope.cases ?? pathCaseIndex();\n  const dir = dirname(doc.path);\n  const linkage: DocumentLinkage = { resolved: [], broken: [] };\n  for (const link of documentLinks(doc.text)) {\n    const target = resolve(dir, link.path);\n    if (!isPathInside(scope.docsDir, target)) continue;\n    // The overlay is checked FIRST and without the spelling test: the file is\n    // not on disk, so there is no stored name to compare against, and the id it\n    // came from was a `readdir` entry in the feature's own tree.\n    if (scope.overlay?.has(resolve(target)) === true) {\n      linkage.resolved.push({ link, target });\n      continue;\n    }\n    if (existsSync(target) && cases.spelledExactly(scope.docsDir, target)) {\n      linkage.resolved.push({ link, target });\n      continue;\n    }\n    const storedAs = cases.storedAs(dirname(target), basename(target));\n    linkage.broken.push({ link, ...(storedAs === undefined ? {} : { storedAs }) });\n  }\n  return linkage;\n}\n\n/** The links in one document that resolve to nothing, as at most one finding. */\nexport function unresolvedLinkFindings(doc: LinkedDocument, scope: LinkScope): Finding[] {\n  const where = repoPath(scope.docsDir, doc.path);\n  const { broken } = resolveLinks(doc, scope);\n  if (broken.length === 0) return [];\n  return [\n    {\n      severity: \"error\",\n      code: \"link.unresolved\",\n      ...(scope.subject === undefined ? {} : { subject: scope.subject }),\n      message:\n        `${where}: ${broken.length} markdown link(s) resolve to nothing. ` +\n        \"A link between documents here is a join — fix the path, or write the document it points at. \" +\n        \"Targets outside the docs repo and links to a heading (`#section`) are not graded.\",\n      details: broken.map((one) => detail(where, one)),\n    },\n  ];\n}\n\n/**\n * One broken link, spelled so the author can find it: the file and line first,\n * then the link exactly as written. `raw` rather than the decoded path, because\n * the decoded form is not the string that is in the document.\n *\n * The stored spelling is appended when the only thing wrong is case, because\n * without it the message reads as a lie — the file the author is being told to\n * write is already sitting beside the one they linked from.\n */\nfunction detail(where: string, one: { link: DocumentLink; storedAs?: string }): string {\n  const line = `${where}:${one.link.line}: [${one.link.text}](${one.link.raw})`;\n  return one.storedAs === undefined ? line : `${line} — stored as '${one.storedAs}'`;\n}\n"]}