@ybotok/loam 0.2.0-alpha.1 → 0.2.0-alpha.13

package/dist/core/gherkin/stale.js.map

@@ -1 +1 @@
-{"version":3,"file":"stale.js","sourceRoot":"","sources":["../../../src/core/gherkin/stale.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAe,MAAM,SAAS,CAAC;AAC5D,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAEzD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAG/C,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACzD,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,mBAAmB,EAAuB,MAAM,WAAW,CAAC;AAGrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,GAOrC;IACC,IAAI,GAAG,CAAC,OAAO,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IACzC,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,WAAW,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,UAAU,CAAC,CAAC;IAClD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,CAAC,GAAG,YAAY,eAAe,CAAC;YAAE,MAAM,GAAG,CAAC;QACjD,OAAO;YACL;gBACE,QAAQ,EAAE,OAAO;gBACjB,IAAI,EAAE,sBAAsB;gBAC5B,OAAO,EAAE,GAAG,CAAC,OAAO;gBACpB,OAAO,EAAE,4CAA4C,GAAG,CAAC,OAAO,yCAAyC;aAC1G;SACF,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IASjC,MAAM,KAAK,GAAG,MAAM,kBAAkB,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC;IAC5E,MAAM,IAAI,GAAG,IAAI,GAAG,EAAkC,CAAC;IACvD,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;QAC7B,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;QAC9B,MAAM,KAAK,GAAc,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,GAAG,EAAE,EAAE,OAAO,EAAE,IAAI,GAAG,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC;QACrG,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC7B,IAAI,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YACrB,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,KAAK,SAAS;gBAClC,CAAC,CAAC,iBAAiB,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;gBACjD,CAAC,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC;YAC3C,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;gBACrB,IAAI,CAAC,CAAC,IAAI,KAAK,SAAS;oBAAE,SAAS;gBACnC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;gBAC3B,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,CAAC;oBAC5B,MAAM,MAAM,GAAG,cAAc,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;oBAC3D,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;oBAC1B,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;gBAC9D,CAAC;YACH,CAAC;QACH,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IACzB,CAAC;IAED,qEAAqE;IACrE,6EAA6E;IAC7E,qEAAqE;IACrE,iEAAiE;IACjE,MAAM,MAAM,GAAG,IAAI,GAAG,CAAS,CAAC,MAAM,YAAY,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAClG,MAAM,cAAc,GAAG,EAAE,QAAQ,EAAE,IAAI,GAAG,EAAU,EAAE,IAAI,EAAE,IAAI,GAAG,EAAU,EAAE,CAAC;IAChF,MAAM,MAAM,GAA4E,EAAE,CAAC;IAC3F,IAAI,gBAAgB,GAAG,CAAC,CAAC;IACzB,KAAK,MAAM,GAAG,IAAI,MAAM,iBAAiB,CAAC,IAAI,CAAC,EAAE,CAAC;QAChD,MAAM,IAAI,GAAG,mBAAmB,CAAC,MAAM,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC;QAC9D,IAAI,IAAI,KAAK,IAAI;YAAE,SAAS;QAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC;QACtE,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,SAAS;YAAE,cAAc,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QACnE,gBAAgB,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;QAC1C,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,QAAQ,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IACpF,CAAC;IAED,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,MAAM,KAAK,GAAG,4BAA4B,GAAG,CAAC,OAAO,IAAI,CAAC;IAC1D,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC;QACjC,KAAK,MAAM,EAAE,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;YACjC,IAAI,cAAc,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC;gBAAE,SAAS;YAClD,QAAQ,CAAC,IAAI,CAAC;gBACZ,QAAQ,EAAE,MAAM;gBAChB,IAAI,EAAE,iBAAiB;gBACvB,OAAO,EAAE,GAAG,CAAC,OAAO;gBACpB,OAAO,EAAE,GAAG,GAAG,CAAC,OAAO,eAAe,EAAE,CAAC,IAAI,qBAAqB,EAAE,CAAC,GAAG,MAAM,KAAK,CAAC,IAAI,iFAAiF,KAAK,iBAAiB;aAChM,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,KAAK,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,MAAM,EAAE,CAAC;QACzC,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YAAE,SAAS;QACnD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAE,CAAC;QAC9B,IAAI,IAAI,CAAC,WAAW,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;YACvE,QAAQ,CAAC,IAAI,CAAC;gBACZ,QAAQ,EAAE,MAAM;gBAChB,IAAI,EAAE,kBAAkB;gBACxB,OAAO,EAAE,GAAG,CAAC,OAAO;gBACpB,OAAO,EAAE,GAAG,GAAG,CAAC,OAAO,KAAK,GAAG,kBAAkB,IAAI,CAAC,WAAW,IAAI,WAAW,oCAAoC,KAAK,CAAC,IAAI,kCAAkC,KAAK,aAAa;aACnL,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QACD,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YAC/B,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC;gBAAE,SAAS;YAC1C,QAAQ,CAAC,IAAI,CAAC;gBACZ,QAAQ,EAAE,MAAM;gBAChB,IAAI,EAAE,eAAe;gBACrB,OAAO,EAAE,GAAG,CAAC,OAAO;gBACpB,OAAO,EAAE,GAAG,GAAG,CAAC,OAAO,KAAK,GAAG,eAAe,CAAC,CAAC,IAAI,uCAAuC,KAAK,CAAC,IAAI,+CAA+C,KAAK,iBAAiB;aAC3K,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,QAAQ,CAAC,IAAI,CAAC;YACZ,QAAQ,EAAE,IAAI;YACd,IAAI,EAAE,iBAAiB;YACvB,OAAO,EAAE,GAAG,GAAG,CAAC,OAAO,gCAAgC,MAAM,CAAC,MAAM,aAAa,gBAAgB,mDAAmD;SACrJ,CAAC,CAAC;IACL,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,IAAY;IAClD,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,4EAA4E;IAC5E,sEAAsE;IACtE,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAClC,MAAM,IAAI,GAAG,KAAK,EAAE,GAAW,EAAiB,EAAE;QAChD,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,OAAO;QAC7B,IAAI,QAAgB,CAAC;QACrB,IAAI,CAAC;YACH,QAAQ,GAAG,MAAM,QAAQ,CAAC,GAAG,CAAC,CAAC;QACjC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO;QACT,CAAC;QACD,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC;YAAE,OAAO;QAClC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACtB,KAAK,MAAM,KAAK,IAAI,MAAM,OAAO,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;YAChE,IAAI,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;gBAAE,SAAS;YACzC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;YAClC,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YACnC,IAAI,IAAI,KAAK,KAAK;gBAAE,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC;iBAC/B,IAAI,IAAI,KAAK,MAAM,IAAI,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC;gBAAE,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC7E,CAAC;IACH,CAAC,CAAC;IACF,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC;IACjB,OAAO,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACvB,MAAM,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAClC,MAAM,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAClC,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACxC,CAAC,CAAC,CAAC;AACL,CAAC;AAED,kFAAkF;AAClF,SAAS,SAAS,CAAC,GAAW,EAAE,CAAS;IACvC,IAAI,CAAC,CAAC,CAAC,cAAc,EAAE;QAAE,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;IACrF,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;QACxB,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;IAC9D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC","sourcesContent":["/**\n * What `loam validate` reports about a generated suite: which scenarios moved\n * out from under it, and which were never generated at all.\n *\n * Service-repo-scoped, and silent until a suite exists — a service that never\n * ran `loam gherkin` has not opted into the axis and is not failing it. The\n * whole comparison is by digest rather than by name, so a reworded scenario\n * reads as stale rather than as missing plus new.\n */\nimport { existsSync, statSync, type Dirent } from \"node:fs\";\nimport { readdir, readFile, realpath } from \"node:fs/promises\";\nimport { join, relative, sep } from \"node:path\";\nimport { parseRequirements } from \"../document/parse.js\";\nimport type { PathableService } from \"../kernel/ids/service.js\";\nimport { SPEC_AXES } from \"../repo/paths.js\";\nimport { locateServicePaths } from \"../repo/service-target.js\";\nimport { listFeatures } from \"../repo/repo.js\";\nimport type { FleetContext } from \"../fleet-context.js\";\nimport type { Finding } from \"../vocabulary/report.js\";\nimport { UnsafePathError } from \"../kernel/path-safety.js\";\nimport { gherkinRoot, scenarioDigest } from \"./stamp.js\";\nimport { axisLabel } from \"./emit.js\";\nimport { parseStampedFeature, type StampedFeature } from \"./read.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\n\n/**\n * The gherkin freshness chain, service-repo-scoped like `sources.*`: it needs\n * the repo (the suite lives there), and it stays quiet until\n * `<gherkinDir>/loam/` exists — a service that never generated has not opted\n * in, and silence there is honest, not vacuous.\n *\n * The LIVING specs are the reference, with one carve-out. A stamped file\n * tagged with a feature still in flight answers to that feature's delta, not\n * to the living spec its requirements have not merged into yet — so it is\n * skipped here (its regeneration is `loam gherkin <FEAT>`), and the moment the\n * feature archives, its requirements ARE living requirements, digests\n * unchanged, and the same file grades current with no rewrite. A tag naming\n * no active feature (the feature was archived, or abandoned) gets no\n * exemption: the living spec is all there is to answer to.\n *\n * Three warnings, one per way the suite and the spec can disagree, judged\n * digest-first and by requirement name second:\n *\n * - `gherkin.missing` — a living scenario whose digest no stamped scenario of\n *   its axis carries: the suite has no test for these words.\n * - `gherkin.stale` — a stamped scenario whose digest matches no living\n *   scenario while its file's requirement still exists: the spec moved under\n *   the generated file. (A reworded scenario therefore reports both: the old\n *   words are stale, the new words are missing — one regeneration clears\n *   both.)\n * - `gherkin.orphaned` — a whole file whose requirement no longer exists in\n *   its axis's living spec; reported once per file, because every scenario in\n *   it is moot together.\n *\n * Digests are content identity within one service and one axis, deliberately:\n * two identically-worded scenarios of one service's one axis share one digest,\n * so one stamped copy covers both — while the axes stay separate namespaces\n * twice over (every comparison here is axis-scoped, and the recipe salts the\n * arch axis), and the services stay separate because the recipe salts the\n * service too. That last salt is why a stamped file copied out of another\n * service's repository grades `gherkin.orphaned`/`gherkin.stale` here instead\n * of quietly counting as this service's coverage.\n *\n * All warnings — `--strict` is the CI escalation — plus one `ok` confirmation\n * (`gherkin.current`, the `sources.current` pattern) when a generated suite\n * exists and nothing disagrees.\n */\nexport async function gherkinFindings(ctx: {\n  docsDir: DocsDir;\n  service: PathableService;\n  /** The service repo, when loam is standing in it. Undefined disables the chain, like sources.*. */\n  repoDir?: string;\n  gherkinDir?: string;\n  fleet?: FleetContext;\n}): Promise<Finding[]> {\n  if (ctx.repoDir === undefined) return [];\n  let root: string;\n  try {\n    root = gherkinRoot(ctx.repoDir, ctx.gherkinDir);\n  } catch (err) {\n    if (!(err instanceof UnsafePathError)) throw err;\n    return [\n      {\n        severity: \"error\",\n        code: \"gherkin.path-outside\",\n        subject: ctx.service,\n        message: `The configured Gherkin output is unsafe: ${err.message}. It must stay inside the service repo.`,\n      },\n    ];\n  }\n  if (!existsSync(root)) return [];\n\n  // The living reference, per axis: requirement names, and scenario digests.\n  interface AxisState {\n    file: string;\n    reqNames: Set<string>;\n    digests: Set<string>;\n    scenarios: Array<{ req: string; name: string; digest: string }>;\n  }\n  const paths = await locateServicePaths(ctx.docsDir, ctx.service, ctx.fleet);\n  const axes = new Map<\"business\" | \"arch\", AxisState>();\n  for (const axis of SPEC_AXES) {\n    const label = axisLabel(axis);\n    const state: AxisState = { file: axis.file, reqNames: new Set(), digests: new Set(), scenarios: [] };\n    const path = paths[axis.key];\n    if (existsSync(path)) {\n      const reqs = ctx.fleet === undefined\n        ? parseRequirements(await readFile(path, \"utf8\"))\n        : await ctx.fleet.readRequirements(path);\n      for (const r of reqs) {\n        if (r.kind === \"REMOVED\") continue;\n        state.reqNames.add(r.name);\n        for (const s of r.scenarios) {\n          const digest = scenarioDigest(ctx.service, s.lines, label);\n          state.digests.add(digest);\n          state.scenarios.push({ req: r.name, name: s.name, digest });\n        }\n      }\n    }\n    axes.set(label, state);\n  }\n\n  // The stamped side. Every stamped digest counts toward coverage — an\n  // in-flight file whose scenario matches the living words IS a test for them.\n  // `Set<string>`, not the ids' own brand: this set answers membership\n  // questions for tags read out of .feature files — document text.\n  const active = new Set<string>((await listFeatures(ctx.docsDir, {}, ctx.fleet)).map((f) => f.id));\n  const stampedDigests = { business: new Set<string>(), arch: new Set<string>() };\n  const parsed: Array<{ rel: string; axis: \"business\" | \"arch\"; file: StampedFeature }> = [];\n  let stampedScenarios = 0;\n  for (const abs of await featureFilesUnder(root)) {\n    const file = parseStampedFeature(await readFile(abs, \"utf8\"));\n    if (file === null) continue;\n    const axis = file.tags.includes(\"architecture\") ? \"arch\" : \"business\";\n    for (const s of file.scenarios) stampedDigests[axis].add(s.digest);\n    stampedScenarios += file.scenarios.length;\n    parsed.push({ rel: relative(ctx.repoDir, abs).split(sep).join(\"/\"), axis, file });\n  }\n\n  const findings: Finding[] = [];\n  const regen = `\\`loam gherkin --service ${ctx.service}\\``;\n  for (const [axis, state] of axes) {\n    for (const sc of state.scenarios) {\n      if (stampedDigests[axis].has(sc.digest)) continue;\n      findings.push({\n        severity: \"warn\",\n        code: \"gherkin.missing\",\n        subject: ctx.service,\n        message: `${ctx.service}: scenario '${sc.name}' of requirement '${sc.req}' (${state.file}) has no generated .feature scenario — the suite has no test for these words; ${regen} regenerates it`,\n      });\n    }\n  }\n  for (const { rel, axis, file } of parsed) {\n    if (file.tags.some((t) => active.has(t))) continue;\n    const state = axes.get(axis)!;\n    if (file.featureName === null || !state.reqNames.has(file.featureName)) {\n      findings.push({\n        severity: \"warn\",\n        code: \"gherkin.orphaned\",\n        subject: ctx.service,\n        message: `${ctx.service}: ${rel}: requirement '${file.featureName ?? \"(unnamed)\"}' no longer exists in the living ${state.file} — the whole file is orphaned; ${regen} removes it`,\n      });\n      continue;\n    }\n    for (const s of file.scenarios) {\n      if (state.digests.has(s.digest)) continue;\n      findings.push({\n        severity: \"warn\",\n        code: \"gherkin.stale\",\n        subject: ctx.service,\n        message: `${ctx.service}: ${rel}: scenario '${s.name}' matches no scenario in the living ${state.file} — the spec moved under the generated file; ${regen} regenerates it`,\n      });\n    }\n  }\n  if (findings.length === 0) {\n    findings.push({\n      severity: \"ok\",\n      code: \"gherkin.current\",\n      message: `${ctx.service}: generated gherkin current (${parsed.length} file(s), ${stampedScenarios} stamped scenario(s) agree with the living specs)`,\n    });\n  }\n  return findings;\n}\n\n/**\n * Every `.feature` file at or under `root`, sorted by repo-relative path —\n * enumeration is part of the output contract, so the order cannot depend on\n * the filesystem's. Dot-entries are skipped, like every other walk in loam.\n *\n * Symlinks are FOLLOWED — repo.ts's `entryIs` and brief/brief.ts's `hasMarkdown` are\n * the same rule for the same reason. A `Dirent` from `readdir(withFileTypes)`\n * never follows one, so `isFile()` and `isDirectory()` are both false for a\n * symlinked `.feature`: it was invisible to the orphan scan (`loam gherkin`\n * left it behind forever) and invisible to the staleness scan (it graded as no\n * coverage at all). Composing a suite out of links is legitimate, so they are\n * followed rather than refused, and a dangling one is skipped exactly as an\n * absent file is.\n */\nexport async function featureFilesUnder(root: string): Promise<string[]> {\n  const out: string[] = [];\n  // Following links means a cycle is now possible; every directory is entered\n  // once by its resolved path, so a loop terminates instead of hanging.\n  const entered = new Set<string>();\n  const walk = async (dir: string): Promise<void> => {\n    if (!existsSync(dir)) return;\n    let resolved: string;\n    try {\n      resolved = await realpath(dir);\n    } catch {\n      return;\n    }\n    if (entered.has(resolved)) return;\n    entered.add(resolved);\n    for (const entry of await readdir(dir, { withFileTypes: true })) {\n      if (entry.name.startsWith(\".\")) continue;\n      const abs = join(dir, entry.name);\n      const what = entryKind(abs, entry);\n      if (what === \"dir\") await walk(abs);\n      else if (what === \"file\" && entry.name.endsWith(\".feature\")) out.push(abs);\n    }\n  };\n  await walk(root);\n  return out.sort((a, b) => {\n    const ra = a.split(sep).join(\"/\");\n    const rb = b.split(sep).join(\"/\");\n    return ra < rb ? -1 : ra > rb ? 1 : 0;\n  });\n}\n\n/** What an entry IS, resolving a symlink to find out. Nothing when it dangles. */\nfunction entryKind(abs: string, e: Dirent): \"dir\" | \"file\" | null {\n  if (!e.isSymbolicLink()) return e.isDirectory() ? \"dir\" : e.isFile() ? \"file\" : null;\n  try {\n    const s = statSync(abs);\n    return s.isDirectory() ? \"dir\" : s.isFile() ? \"file\" : null;\n  } catch {\n    return null;\n  }\n}\n"]}
+{"version":3,"file":"stale.js","sourceRoot":"","sources":["../../../src/core/gherkin/stale.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What `loam validate` reports about a generated suite: which scenarios moved\n * out from under it, and which were never generated at all.\n *\n * Service-repo-scoped, and silent until a suite exists — a service that never\n * ran `loam gherkin` has not opted into the axis and is not failing it. The\n * whole comparison is by digest rather than by name, so a reworded scenario\n * reads as stale rather than as missing plus new.\n */\nimport { existsSync } from \"node:fs\";\nimport { readdir, readFile } from \"node:fs/promises\";\nimport { join, relative, sep } from \"node:path\";\nimport type { PathableService } from \"../kernel/ids/service.js\";\nimport { SPEC_AXES } from \"../repo/paths.js\";\nimport { locateServicePaths } from \"../repo/service-target.js\";\nimport { listFeatures } from \"../repo/repo.js\";\nimport { entryIs, markDescended } from \"../repo/tree/fs.js\";\nimport type { FleetContext } from \"../fleet-context.js\";\nimport type { Finding } from \"../vocabulary/report.js\";\nimport { UnsafePathError } from \"../kernel/path-safety.js\";\nimport { gherkinRoot, scenarioDigest } from \"./stamp.js\";\nimport { axisLabel } from \"./emit.js\";\nimport { parseStampedFeature, type StampedFeature } from \"./read.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\n\n/**\n * The gherkin freshness chain, service-repo-scoped like `sources.*`: it needs\n * the repo (the suite lives there), and it stays quiet until\n * `<gherkinDir>/loam/` exists — a service that never generated has not opted\n * in, and silence there is honest, not vacuous.\n *\n * The LIVING specs are the reference, with one carve-out. A stamped file\n * tagged with a feature still in flight answers to that feature's delta, not\n * to the living spec its requirements have not merged into yet — so it is\n * skipped here (its regeneration is `loam gherkin <FEAT>`), and the moment the\n * feature archives, its requirements ARE living requirements, digests\n * unchanged, and the same file grades current with no rewrite. A tag naming\n * no active feature (the feature was archived, or abandoned) gets no\n * exemption: the living spec is all there is to answer to.\n *\n * Three warnings, one per way the suite and the spec can disagree, judged\n * digest-first and by requirement name second:\n *\n * - `gherkin.missing` — a living scenario whose digest no stamped scenario of\n *   its axis carries: the suite has no test for these words.\n * - `gherkin.stale` — a stamped scenario whose digest matches no living\n *   scenario while its file's requirement still exists: the spec moved under\n *   the generated file. (A reworded scenario therefore reports both: the old\n *   words are stale, the new words are missing — one regeneration clears\n *   both.)\n * - `gherkin.orphaned` — a whole file whose requirement no longer exists in\n *   its axis's living spec; reported once per file, because every scenario in\n *   it is moot together.\n *\n * Digests are content identity within one service and one axis, deliberately:\n * two identically-worded scenarios of one service's one axis share one digest,\n * so one stamped copy covers both — while the axes stay separate namespaces\n * twice over (every comparison here is axis-scoped, and the recipe salts the\n * arch axis), and the services stay separate because the recipe salts the\n * service too. That last salt is why a stamped file copied out of another\n * service's repository grades `gherkin.orphaned`/`gherkin.stale` here instead\n * of quietly counting as this service's coverage.\n *\n * All warnings — `--strict` is the CI escalation — plus one `ok` confirmation\n * (`gherkin.current`, the `sources.current` pattern) when a generated suite\n * exists and nothing disagrees.\n */\nexport async function gherkinFindings(ctx: {\n  docsDir: DocsDir;\n  service: PathableService;\n  /** The service repo, when loam is standing in it. Undefined disables the chain, like sources.*. */\n  repoDir?: string;\n  gherkinDir?: string;\n  fleet: FleetContext;\n}): Promise<Finding[]> {\n  if (ctx.repoDir === undefined) return [];\n  let root: string;\n  try {\n    root = gherkinRoot(ctx.repoDir, ctx.gherkinDir);\n  } catch (err) {\n    if (!(err instanceof UnsafePathError)) throw err;\n    return [\n      {\n        severity: \"error\",\n        code: \"gherkin.path-outside\",\n        subject: ctx.service,\n        message: `The configured Gherkin output is unsafe: ${err.message}. It must stay inside the service repo.`,\n      },\n    ];\n  }\n  if (!existsSync(root)) return [];\n\n  // The living reference, per axis: requirement names, and scenario digests.\n  interface AxisState {\n    file: string;\n    reqNames: Set<string>;\n    digests: Set<string>;\n    scenarios: Array<{ req: string; name: string; digest: string }>;\n  }\n  const paths = await locateServicePaths(ctx.docsDir, ctx.service, ctx.fleet);\n  const axes = new Map<\"business\" | \"arch\", AxisState>();\n  for (const axis of SPEC_AXES) {\n    const label = axisLabel(axis);\n    const state: AxisState = { file: axis.file, reqNames: new Set(), digests: new Set(), scenarios: [] };\n    const path = paths[axis.key];\n    if (existsSync(path)) {\n      for (const r of await ctx.fleet.readRequirements(path)) {\n        if (r.kind === \"REMOVED\") continue;\n        state.reqNames.add(r.name);\n        for (const s of r.scenarios) {\n          const digest = scenarioDigest(ctx.service, s.lines, label);\n          state.digests.add(digest);\n          state.scenarios.push({ req: r.name, name: s.name, digest });\n        }\n      }\n    }\n    axes.set(label, state);\n  }\n\n  // The stamped side. Every stamped digest counts toward coverage — an\n  // in-flight file whose scenario matches the living words IS a test for them.\n  // `Set<string>`, not the ids' own brand: this set answers membership\n  // questions for tags read out of .feature files — document text.\n  const active = new Set<string>((await listFeatures(ctx.docsDir, {}, ctx.fleet)).map((f) => f.id));\n  const stampedDigests = { business: new Set<string>(), arch: new Set<string>() };\n  const parsed: Array<{ rel: string; axis: \"business\" | \"arch\"; file: StampedFeature }> = [];\n  let stampedScenarios = 0;\n  for (const abs of await featureFilesUnder(root)) {\n    const file = parseStampedFeature(await readFile(abs, \"utf8\"));\n    if (file === null) continue;\n    const axis = file.tags.includes(\"architecture\") ? \"arch\" : \"business\";\n    for (const s of file.scenarios) stampedDigests[axis].add(s.digest);\n    stampedScenarios += file.scenarios.length;\n    parsed.push({ rel: relative(ctx.repoDir, abs).split(sep).join(\"/\"), axis, file });\n  }\n\n  const findings: Finding[] = [];\n  const regen = `\\`loam gherkin --service ${ctx.service}\\``;\n  for (const [axis, state] of axes) {\n    for (const sc of state.scenarios) {\n      if (stampedDigests[axis].has(sc.digest)) continue;\n      findings.push({\n        severity: \"warn\",\n        code: \"gherkin.missing\",\n        subject: ctx.service,\n        message: `${ctx.service}: scenario '${sc.name}' of requirement '${sc.req}' (${state.file}) has no generated .feature scenario — the suite has no test for these words; ${regen} regenerates it`,\n      });\n    }\n  }\n  for (const { rel, axis, file } of parsed) {\n    if (file.tags.some((t) => active.has(t))) continue;\n    const state = axes.get(axis)!;\n    if (file.featureName === null || !state.reqNames.has(file.featureName)) {\n      findings.push({\n        severity: \"warn\",\n        code: \"gherkin.orphaned\",\n        subject: ctx.service,\n        message: `${ctx.service}: ${rel}: requirement '${file.featureName ?? \"(unnamed)\"}' no longer exists in the living ${state.file} — the whole file is orphaned; ${regen} removes it`,\n      });\n      continue;\n    }\n    for (const s of file.scenarios) {\n      if (state.digests.has(s.digest)) continue;\n      findings.push({\n        severity: \"warn\",\n        code: \"gherkin.stale\",\n        subject: ctx.service,\n        message: `${ctx.service}: ${rel}: scenario '${s.name}' matches no scenario in the living ${state.file} — the spec moved under the generated file; ${regen} regenerates it`,\n      });\n    }\n  }\n  if (findings.length === 0) {\n    findings.push({\n      severity: \"ok\",\n      code: \"gherkin.current\",\n      message: `${ctx.service}: generated gherkin current (${parsed.length} file(s), ${stampedScenarios} stamped scenario(s) agree with the living specs)`,\n    });\n  }\n  return findings;\n}\n\n/**\n * Every `.feature` file at or under `root`, sorted by repo-relative path —\n * enumeration is part of the output contract, so the order cannot depend on\n * the filesystem's. Dot-entries are skipped, like every other walk in loam.\n *\n * Symlinks are FOLLOWED, through `repo/tree/fs.ts`'s `entryIs` — the rule\n * every enumeration shares (brief/brief.ts's `hasEntry` too), for the same\n * reason. A `Dirent` from `readdir(withFileTypes)` never follows one, so\n * `isFile()` and `isDirectory()` are both false for a\n * symlinked `.feature`: it was invisible to the orphan scan (`loam gherkin`\n * left it behind forever) and invisible to the staleness scan (it graded as no\n * coverage at all). Composing a suite out of links is legitimate, so they are\n * followed rather than refused, and a dangling one is skipped exactly as an\n * absent file is.\n */\nexport async function featureFilesUnder(root: string): Promise<string[]> {\n  const out: string[] = [];\n  // Following links means a cycle is now possible; every directory is entered\n  // once by its resolved path (`markDescended`), so a loop terminates instead\n  // of hanging.\n  const entered = new Set<string>();\n  const walk = async (dir: string): Promise<void> => {\n    if (!markDescended(dir, entered)) return;\n    for (const entry of await readdir(dir, { withFileTypes: true })) {\n      if (entry.name.startsWith(\".\")) continue;\n      const abs = join(dir, entry.name);\n      if (entryIs(dir, entry, \"dir\")) await walk(abs);\n      else if (entry.name.endsWith(\".feature\") && entryIs(dir, entry, \"file\")) out.push(abs);\n    }\n  };\n  await walk(root);\n  return out.sort((a, b) => {\n    const ra = a.split(sep).join(\"/\");\n    const rb = b.split(sep).join(\"/\");\n    return ra < rb ? -1 : ra > rb ? 1 : 0;\n  });\n}\n"]}

package/dist/core/glossary/delta.js

@@ -49,13 +49,16 @@ export function featureGlossary(featureDir) {
  * Where each of this feature's terms WILL live once the archive merges — the
  * overlay a feature's own documents are allowed to cite.
  *
- * A feature that introduces a word cites it at its future living path
- * (`../../glossary/order.md`), because that is where the link has to point once
- * the feature ships; citing the delta path instead would resolve today and rot
- * on the day it lands. So while a feature is in flight, `link.unresolved` treats
- * these paths as resolved — the same overlay the capability axis needed for
- * `Realizes:`, and for the same reason: an index built from the LIVING tree
- * alone refuses the feature's own headline flow.
+ * A feature that introduces a word may cite it at its future living path
+ * (`../../glossary/order.md` from `intent.md`), because that is where the link
+ * points once the feature ships. So while a feature is in flight,
+ * `link.unresolved` treats these paths as resolved — the same overlay the
+ * capability axis needed for `Realizes:`, and for the same reason: an index
+ * built from the LIVING tree alone refuses the feature's own headline flow.
+ * Citing the term at its path INSIDE the feature is the other legal spelling,
+ * and it no longer rots on the day the feature lands: archive re-points every
+ * merged link into the feature at the file's new home
+ * (`commands/archive/plan/document/links.ts`).
  */
 export async function featureGlossaryOverlay(docsDir, featureDir) {
     const glossary = await featureGlossary(featureDir);

package/dist/core/glossary/delta.js.map

@@ -1 +1 @@
-{"version":3,"file":"delta.js","sourceRoot":"","sources":["../../../src/core/glossary/delta.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAC5E,OAAO,EAAc,MAAM,wBAAwB,CAAC;AAEpD,OAAO,EAAE,YAAY,EAAiB,MAAM,WAAW,CAAC;AAExD;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,UAAsB;IACpD,OAAO,YAAY,CAAC,kBAAkB,CAAC,UAAU,CAAC,CAAC,CAAC;AACtD,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,OAAgB,EAAE,UAAsB;IACnF,MAAM,QAAQ,GAAG,MAAM,eAAe,CAAC,UAAU,CAAC,CAAC;IACnD,OAAO,IAAI,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,cAAc,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;AACpF,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,OAAgB,EAAE,UAAsB;IAChF,MAAM,QAAQ,GAAG,MAAM,eAAe,CAAC,UAAU,CAAC,CAAC;IACnD,IAAI,CAAC,QAAQ,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC;IACjC,OAAO,QAAQ,CAAC,KAAK;SAClB,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,cAAc,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;SAC9D,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACd,QAAQ,EAAE,OAAgB;QAC1B,IAAI,EAAE,sBAA+B;QACrC,OAAO,EAAE,IAAI,CAAC,EAAE;QAChB,OAAO,EACL,YAAY,IAAI,CAAC,EAAE,wDAAwD,IAAI,CAAC,EAAE,8CAA8C;YAChI,gFAAgF;YAChF,mCAAmC,IAAI,CAAC,EAAE,yBAAyB,IAAI,CAAC,EAAE,oCAAoC;YAC9G,6EAA6E;KAChF,CAAC,CAAC,CAAC;AACR,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,cAAc,CAAC,OAAgB,EAAE,EAAU;IACzD,OAAO,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;AAChD,CAAC","sourcesContent":["/**\n * A feature's own glossary deltas: `features/<FEAT>/glossary/<term>.md`.\n *\n * A change that needs a new word brings the word with it. The archive copies the\n * definition into `glossary/`, `loam unarchive` takes it back out with\n * everything else the feature landed, and until then the term is visible in\n * review beside the requirements that use it — which is the whole reason this\n * route exists rather than \"remember to edit the glossary too\".\n *\n * CREATE-ONLY, and this is the axis's one real design decision rather than an\n * unfinished half. A feature-local capability document is a DELTA — `## ADDED\n * Requirements`, `Requirement-ID:` identity, `Based-On:` pins — because it\n * merges INTO a living document and two features editing one requirement would\n * otherwise silently overwrite each other. A term has none of that: the file is\n * one definition, the merge is a whole-file copy, and there is nothing to merge\n * partially. So rewriting a living definition through a feature would be a\n * silent whole-file replacement with no pin to collide on, where editing\n * `glossary/<term>.md` directly in the same pull request produces an ordinary\n * git conflict that a human resolves. `glossary.term-exists` refuses the first\n * and points at the second.\n *\n * TWO FEATURES INTRODUCING THE SAME WORD is the case that makes the refusal\n * load-bearing rather than pedantic: whichever archives first creates the living\n * definition, and the second is told — loudly, before it merges — that the word\n * now exists and its own file is the one to delete.\n *\n * ONE CALL for the walk, because it is already written: `readGlossary`\n * implements the file-is-a-term rule, the `README.md` exclusion, the nesting and\n * the symlink guard over any root. A second walk for the feature side would be\n * two implementations free to disagree about what a term is.\n */\nimport { existsSync } from \"node:fs\";\nimport { join, resolve } from \"node:path\";\nimport { featureGlossaryDir, glossaryDir } from \"../repo/authored/paths.js\";\nimport { type Issue } from \"../vocabulary/issue.js\";\nimport type { DocsDir, FeatureDir } from \"../kernel/ids/dirs.js\";\nimport { readGlossary, type Glossary } from \"./tree.js\";\n\n/**\n * The definitions one feature carries, ordered by id.\n *\n * `present: false` — and zero readdirs — when the feature has no `glossary/`\n * directory, which is every feature in a fleet that has not adopted the axis.\n * That short-circuit is `readGlossary`'s own `existsSync` and it is the whole\n * cost such a fleet pays.\n */\nexport function featureGlossary(featureDir: FeatureDir): Promise<Glossary> {\n  return readGlossary(featureGlossaryDir(featureDir));\n}\n\n/**\n * Where each of this feature's terms WILL live once the archive merges — the\n * overlay a feature's own documents are allowed to cite.\n *\n * A feature that introduces a word cites it at its future living path\n * (`../../glossary/order.md`), because that is where the link has to point once\n * the feature ships; citing the delta path instead would resolve today and rot\n * on the day it lands. So while a feature is in flight, `link.unresolved` treats\n * these paths as resolved — the same overlay the capability axis needed for\n * `Realizes:`, and for the same reason: an index built from the LIVING tree\n * alone refuses the feature's own headline flow.\n */\nexport async function featureGlossaryOverlay(docsDir: DocsDir, featureDir: FeatureDir): Promise<Set<string>> {\n  const glossary = await featureGlossary(featureDir);\n  return new Set(glossary.terms.map((t) => resolve(livingTermPath(docsDir, t.id))));\n}\n\n/**\n * `glossary.term-exists` — a term this feature introduces that the living\n * glossary already defines.\n *\n * An ERROR and never a warning-that-gates: unlike `capability.uncovered`, there\n * is no legal reading of it. The merge would replace an authored definition\n * with another one, and no `--approve` makes that a different act than it is.\n * The fix is in the message and is the one a reviewer would give anyway.\n */\nexport async function glossaryDeltaIssues(docsDir: DocsDir, featureDir: FeatureDir): Promise<Issue[]> {\n  const glossary = await featureGlossary(featureDir);\n  if (!glossary.present) return [];\n  return glossary.terms\n    .filter((term) => existsSync(livingTermPath(docsDir, term.id)))\n    .map((term) => ({\n      severity: \"error\" as const,\n      code: \"glossary.term-exists\" as const,\n      subject: term.id,\n      message:\n        `glossary/${term.id}.md already exists, so this feature's definition of '${term.id}' would replace an authored one wholesale — ` +\n        \"a feature-local glossary document INTRODUCES a term, it does not rewrite one. \" +\n        `Delete features/<FEAT>/glossary/${term.id}.md and edit glossary/${term.id}.md directly in this same change, ` +\n        \"where git produces an ordinary conflict if somebody else is editing it too.\",\n    }));\n}\n\n/**\n * The LIVING path a feature-local term id addresses. Spelled here because three\n * readers need it — the refusal above, the overlay, and the archive merge — and\n * a reader that resolved it differently would refuse a term the merge then\n * created anyway.\n *\n * The id is joined un-split, which `node:path` normalizes: `join(dir, \"a/b\")`\n * and `join(dir, \"a\", \"b\")` are the same string. What holds this join is\n * PROVENANCE, exactly as it holds `livingCapabilityPaths` — every id here came\n * out of a `readGlossary` walk, where each component is a `readdir` entry name\n * and therefore a directory or file that exists. No caller takes one from argv;\n * the day one does, it needs the treatment `core/kernel/ids/capability.ts` gave\n * the same hazard one axis over.\n */\nexport function livingTermPath(docsDir: DocsDir, id: string): string {\n  return join(glossaryDir(docsDir), `${id}.md`);\n}\n"]}
+{"version":3,"file":"delta.js","sourceRoot":"","sources":["../../../src/core/glossary/delta.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAC5E,OAAO,EAAc,MAAM,wBAAwB,CAAC;AAEpD,OAAO,EAAE,YAAY,EAAiB,MAAM,WAAW,CAAC;AAExD;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,UAAsB;IACpD,OAAO,YAAY,CAAC,kBAAkB,CAAC,UAAU,CAAC,CAAC,CAAC;AACtD,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,OAAgB,EAAE,UAAsB;IACnF,MAAM,QAAQ,GAAG,MAAM,eAAe,CAAC,UAAU,CAAC,CAAC;IACnD,OAAO,IAAI,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,cAAc,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;AACpF,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,OAAgB,EAAE,UAAsB;IAChF,MAAM,QAAQ,GAAG,MAAM,eAAe,CAAC,UAAU,CAAC,CAAC;IACnD,IAAI,CAAC,QAAQ,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC;IACjC,OAAO,QAAQ,CAAC,KAAK;SAClB,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,cAAc,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;SAC9D,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACd,QAAQ,EAAE,OAAgB;QAC1B,IAAI,EAAE,sBAA+B;QACrC,OAAO,EAAE,IAAI,CAAC,EAAE;QAChB,OAAO,EACL,YAAY,IAAI,CAAC,EAAE,wDAAwD,IAAI,CAAC,EAAE,8CAA8C;YAChI,gFAAgF;YAChF,mCAAmC,IAAI,CAAC,EAAE,yBAAyB,IAAI,CAAC,EAAE,oCAAoC;YAC9G,6EAA6E;KAChF,CAAC,CAAC,CAAC;AACR,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,cAAc,CAAC,OAAgB,EAAE,EAAU;IACzD,OAAO,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;AAChD,CAAC","sourcesContent":["/**\n * A feature's own glossary deltas: `features/<FEAT>/glossary/<term>.md`.\n *\n * A change that needs a new word brings the word with it. The archive copies the\n * definition into `glossary/`, `loam unarchive` takes it back out with\n * everything else the feature landed, and until then the term is visible in\n * review beside the requirements that use it — which is the whole reason this\n * route exists rather than \"remember to edit the glossary too\".\n *\n * CREATE-ONLY, and this is the axis's one real design decision rather than an\n * unfinished half. A feature-local capability document is a DELTA — `## ADDED\n * Requirements`, `Requirement-ID:` identity, `Based-On:` pins — because it\n * merges INTO a living document and two features editing one requirement would\n * otherwise silently overwrite each other. A term has none of that: the file is\n * one definition, the merge is a whole-file copy, and there is nothing to merge\n * partially. So rewriting a living definition through a feature would be a\n * silent whole-file replacement with no pin to collide on, where editing\n * `glossary/<term>.md` directly in the same pull request produces an ordinary\n * git conflict that a human resolves. `glossary.term-exists` refuses the first\n * and points at the second.\n *\n * TWO FEATURES INTRODUCING THE SAME WORD is the case that makes the refusal\n * load-bearing rather than pedantic: whichever archives first creates the living\n * definition, and the second is told — loudly, before it merges — that the word\n * now exists and its own file is the one to delete.\n *\n * ONE CALL for the walk, because it is already written: `readGlossary`\n * implements the file-is-a-term rule, the `README.md` exclusion, the nesting and\n * the symlink guard over any root. A second walk for the feature side would be\n * two implementations free to disagree about what a term is.\n */\nimport { existsSync } from \"node:fs\";\nimport { join, resolve } from \"node:path\";\nimport { featureGlossaryDir, glossaryDir } from \"../repo/authored/paths.js\";\nimport { type Issue } from \"../vocabulary/issue.js\";\nimport type { DocsDir, FeatureDir } from \"../kernel/ids/dirs.js\";\nimport { readGlossary, type Glossary } from \"./tree.js\";\n\n/**\n * The definitions one feature carries, ordered by id.\n *\n * `present: false` — and zero readdirs — when the feature has no `glossary/`\n * directory, which is every feature in a fleet that has not adopted the axis.\n * That short-circuit is `readGlossary`'s own `existsSync` and it is the whole\n * cost such a fleet pays.\n */\nexport function featureGlossary(featureDir: FeatureDir): Promise<Glossary> {\n  return readGlossary(featureGlossaryDir(featureDir));\n}\n\n/**\n * Where each of this feature's terms WILL live once the archive merges — the\n * overlay a feature's own documents are allowed to cite.\n *\n * A feature that introduces a word may cite it at its future living path\n * (`../../glossary/order.md` from `intent.md`), because that is where the link\n * points once the feature ships. So while a feature is in flight,\n * `link.unresolved` treats these paths as resolved — the same overlay the\n * capability axis needed for `Realizes:`, and for the same reason: an index\n * built from the LIVING tree alone refuses the feature's own headline flow.\n * Citing the term at its path INSIDE the feature is the other legal spelling,\n * and it no longer rots on the day the feature lands: archive re-points every\n * merged link into the feature at the file's new home\n * (`commands/archive/plan/document/links.ts`).\n */\nexport async function featureGlossaryOverlay(docsDir: DocsDir, featureDir: FeatureDir): Promise<Set<string>> {\n  const glossary = await featureGlossary(featureDir);\n  return new Set(glossary.terms.map((t) => resolve(livingTermPath(docsDir, t.id))));\n}\n\n/**\n * `glossary.term-exists` — a term this feature introduces that the living\n * glossary already defines.\n *\n * An ERROR and never a warning-that-gates: unlike `capability.uncovered`, there\n * is no legal reading of it. The merge would replace an authored definition\n * with another one, and no `--approve` makes that a different act than it is.\n * The fix is in the message and is the one a reviewer would give anyway.\n */\nexport async function glossaryDeltaIssues(docsDir: DocsDir, featureDir: FeatureDir): Promise<Issue[]> {\n  const glossary = await featureGlossary(featureDir);\n  if (!glossary.present) return [];\n  return glossary.terms\n    .filter((term) => existsSync(livingTermPath(docsDir, term.id)))\n    .map((term) => ({\n      severity: \"error\" as const,\n      code: \"glossary.term-exists\" as const,\n      subject: term.id,\n      message:\n        `glossary/${term.id}.md already exists, so this feature's definition of '${term.id}' would replace an authored one wholesale — ` +\n        \"a feature-local glossary document INTRODUCES a term, it does not rewrite one. \" +\n        `Delete features/<FEAT>/glossary/${term.id}.md and edit glossary/${term.id}.md directly in this same change, ` +\n        \"where git produces an ordinary conflict if somebody else is editing it too.\",\n    }));\n}\n\n/**\n * The LIVING path a feature-local term id addresses. Spelled here because three\n * readers need it — the refusal above, the overlay, and the archive merge — and\n * a reader that resolved it differently would refuse a term the merge then\n * created anyway.\n *\n * The id is joined un-split, which `node:path` normalizes: `join(dir, \"a/b\")`\n * and `join(dir, \"a\", \"b\")` are the same string. What holds this join is\n * PROVENANCE, exactly as it holds `livingCapabilityPaths` — every id here came\n * out of a `readGlossary` walk, where each component is a `readdir` entry name\n * and therefore a directory or file that exists. No caller takes one from argv;\n * the day one does, it needs the treatment `core/kernel/ids/capability.ts` gave\n * the same hazard one axis over.\n */\nexport function livingTermPath(docsDir: DocsDir, id: string): string {\n  return join(glossaryDir(docsDir), `${id}.md`);\n}\n"]}

package/dist/core/glossary/tree.js

@@ -24,11 +24,11 @@
  * document is prose for a human, and the one thing loam reads from it — the
  * links it writes — is read by `core/links/`, where every other document's are.
  */
-import { existsSync, realpathSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { readdir } from "node:fs/promises";
 import { join } from "node:path";
 import { compareIds } from "../repo/entries.js";
-import { entryIs } from "../repo/tree/fs.js";
+import { entryIs, markDescended } from "../repo/tree/fs.js";
 /** The one filename under `glossary/` that is not a term. */
 const INDEX_PAGE = "README.md";
 /**
@@ -37,8 +37,9 @@ const INDEX_PAGE = "README.md";
  * A fleet is expected to hold tens to low hundreds of these — a domain's
  * vocabulary, not its data — so the cost is one `readdir` per directory and the
  * walk's expense is a non-question. The symlink-cycle guard is the one
- * `core/repo/tree/walk.ts` and the capability walk both carry, and for the same
- * reason: `entryIs` follows symlinks on purpose, and a followed cycle without a
+ * `core/repo/tree/walk.ts` and the capability walk both carry
+ * (`core/repo/tree/fs.ts`'s `markDescended`), and for the same reason:
+ * `entryIs` follows symlinks on purpose, and a followed cycle without a
  * visited set recurses until the stack ends.
  */
 export async function readGlossary(root) {
@@ -51,7 +52,7 @@ export async function readGlossary(root) {
 }
 /** Collect the terms in one directory and walk what is beneath it. */
 async function visit(spot, state) {
-    if (!descended(spot.dir, state))
+    if (!markDescended(spot.dir, state.visited))
         return;
     const entries = (await readdir(spot.dir, { withFileTypes: true })).filter((e) => !e.name.startsWith("."));
     for (const entry of entries.filter((e) => e.name.endsWith(".md")).sort((a, b) => compareIds(a.name, b.name))) {
@@ -69,18 +70,4 @@ async function visit(spot, state) {
         await visit({ dir: join(spot.dir, child), chain: [...spot.chain, child] }, state);
     }
 }
-/** Mark a directory as descended-into; false when it (or another name for it) already was. */
-function descended(dir, state) {
-    let real;
-    try {
-        real = realpathSync(dir);
-    }
-    catch {
-        return false;
-    }
-    if (state.visited.has(real))
-        return false;
-    state.visited.add(real);
-    return true;
-}
 //# sourceMappingURL=tree.js.map

package/dist/core/glossary/tree.js.map

@@ -1 +1 @@
-{"version":3,"file":"tree.js","sourceRoot":"","sources":["../../../src/core/glossary/tree.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The glossary tree: `glossary/<term>.md`, and the rule that a markdown file\n * under it IS a declared term.\n *\n * WHY A TREE AND NOT A YAML VOCABULARY, at length in `repo/authored/paths.ts`'s\n * `glossaryDir`: a single vocabulary file at fleet scale is unworkable, and a\n * second list is the drift `loam init`'s removed service manifest was removed\n * for. A term is prose — that is what a definition is — so by this codebase's\n * own rule it gets a file.\n *\n * PRESENCE CLASSIFIES, one tree over from `capabilities/`: a `.md` file is a\n * term, a directory is a group the walk descends through. There is no\n * \"half-created term\" state to name, which is why this walk emits nothing like\n * `capability.doc-missing`: creating a term is writing one file, and an empty\n * grouping directory declares nothing and claims nothing.\n *\n * `README.md` IS NOT A TERM, and it is the one name excluded. A glossary big\n * enough to want an index page is normal, and reporting that page as a word\n * nobody uses would make the axis's only warning fire on the document that\n * explains the axis. Excluded by name rather than by a marker field: the\n * alternative is frontmatter nobody would remember to write.\n *\n * The walk reads directories only and never opens a file. What is IN a term\n * document is prose for a human, and the one thing loam reads from it — the\n * links it writes — is read by `core/links/`, where every other document's are.\n */\nimport { existsSync, realpathSync } from \"node:fs\";\nimport { readdir } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport { compareIds } from \"../repo/entries.js\";\nimport { entryIs } from \"../repo/tree/fs.js\";\n\n/** The one filename under `glossary/` that is not a term. */\nconst INDEX_PAGE = \"README.md\";\n\n/** One defined term: what it is called, and where its definition is. */\nexport interface GlossaryTerm {\n  /** The path from `glossary/` to the file, without `.md` — `order`, or `payments/order`. */\n  id: string;\n  /** Absolute path of the definition. */\n  path: string;\n}\n\nexport interface Glossary {\n  /**\n   * False when `glossary/` does not exist. The directory's existence is the\n   * axis's opt-in, so a fleet without one produces nothing here — not an empty\n   * glossary, which would read as \"the terms went missing\" to anything counting.\n   */\n  present: boolean;\n  /** Every term found, at any depth, ordered by id. */\n  terms: GlossaryTerm[];\n}\n\n/** One directory the walk is looking at: where it is, and how it was reached. */\ninterface Spot {\n  dir: string;\n  /** Directory names between `glossary/` and this one, outermost first. */\n  chain: string[];\n}\n\ninterface WalkState {\n  terms: GlossaryTerm[];\n  /** Realpaths already descended into — the symlink-cycle guard. */\n  visited: Set<string>;\n}\n\n/**\n * Read the tree under `root` (`glossaryDir(docsDir)`).\n *\n * A fleet is expected to hold tens to low hundreds of these — a domain's\n * vocabulary, not its data — so the cost is one `readdir` per directory and the\n * walk's expense is a non-question. The symlink-cycle guard is the one\n * `core/repo/tree/walk.ts` and the capability walk both carry, and for the same\n * reason: `entryIs` follows symlinks on purpose, and a followed cycle without a\n * visited set recurses until the stack ends.\n */\nexport async function readGlossary(root: string): Promise<Glossary> {\n  if (!existsSync(root)) return { present: false, terms: [] };\n  const state: WalkState = { terms: [], visited: new Set() };\n  await visit({ dir: root, chain: [] }, state);\n  state.terms.sort((a, b) => compareIds(a.id, b.id));\n  return { present: true, terms: state.terms };\n}\n\n/** Collect the terms in one directory and walk what is beneath it. */\nasync function visit(spot: Spot, state: WalkState): Promise<void> {\n  if (!descended(spot.dir, state)) return;\n  const entries = (await readdir(spot.dir, { withFileTypes: true })).filter((e) => !e.name.startsWith(\".\"));\n  for (const entry of entries.filter((e) => e.name.endsWith(\".md\")).sort((a, b) => compareIds(a.name, b.name))) {\n    if (entry.name === INDEX_PAGE || !entryIs(spot.dir, entry, \"file\")) continue;\n    state.terms.push({\n      id: [...spot.chain, entry.name.slice(0, -\".md\".length)].join(\"/\"),\n      path: join(spot.dir, entry.name),\n    });\n  }\n  // Sequential, not Promise.all: the visited set is shared mutable state and\n  // the walk's correctness under symlinks rests on a child being marked before\n  // its sibling asks. These trees are tens of directories at most.\n  for (const child of entries.filter((e) => entryIs(spot.dir, e, \"dir\")).map((e) => e.name).sort()) {\n    await visit({ dir: join(spot.dir, child), chain: [...spot.chain, child] }, state);\n  }\n}\n\n/** Mark a directory as descended-into; false when it (or another name for it) already was. */\nfunction descended(dir: string, state: WalkState): boolean {\n  let real: string;\n  try {\n    real = realpathSync(dir);\n  } catch {\n    return false;\n  }\n  if (state.visited.has(real)) return false;\n  state.visited.add(real);\n  return true;\n}\n"]}
+{"version":3,"file":"tree.js","sourceRoot":"","sources":["../../../src/core/glossary/tree.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The glossary tree: `glossary/<term>.md`, and the rule that a markdown file\n * under it IS a declared term.\n *\n * WHY A TREE AND NOT A YAML VOCABULARY, at length in `repo/authored/paths.ts`'s\n * `glossaryDir`: a single vocabulary file at fleet scale is unworkable, and a\n * second list is the drift `loam init`'s removed service manifest was removed\n * for. A term is prose — that is what a definition is — so by this codebase's\n * own rule it gets a file.\n *\n * PRESENCE CLASSIFIES, one tree over from `capabilities/`: a `.md` file is a\n * term, a directory is a group the walk descends through. There is no\n * \"half-created term\" state to name, which is why this walk emits nothing like\n * `capability.doc-missing`: creating a term is writing one file, and an empty\n * grouping directory declares nothing and claims nothing.\n *\n * `README.md` IS NOT A TERM, and it is the one name excluded. A glossary big\n * enough to want an index page is normal, and reporting that page as a word\n * nobody uses would make the axis's only warning fire on the document that\n * explains the axis. Excluded by name rather than by a marker field: the\n * alternative is frontmatter nobody would remember to write.\n *\n * The walk reads directories only and never opens a file. What is IN a term\n * document is prose for a human, and the one thing loam reads from it — the\n * links it writes — is read by `core/links/`, where every other document's are.\n */\nimport { existsSync } from \"node:fs\";\nimport { readdir } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport { compareIds } from \"../repo/entries.js\";\nimport { entryIs, markDescended } from \"../repo/tree/fs.js\";\n\n/** The one filename under `glossary/` that is not a term. */\nconst INDEX_PAGE = \"README.md\";\n\n/** One defined term: what it is called, and where its definition is. */\nexport interface GlossaryTerm {\n  /** The path from `glossary/` to the file, without `.md` — `order`, or `payments/order`. */\n  id: string;\n  /** Absolute path of the definition. */\n  path: string;\n}\n\nexport interface Glossary {\n  /**\n   * False when `glossary/` does not exist. The directory's existence is the\n   * axis's opt-in, so a fleet without one produces nothing here — not an empty\n   * glossary, which would read as \"the terms went missing\" to anything counting.\n   */\n  present: boolean;\n  /** Every term found, at any depth, ordered by id. */\n  terms: GlossaryTerm[];\n}\n\n/** One directory the walk is looking at: where it is, and how it was reached. */\ninterface Spot {\n  dir: string;\n  /** Directory names between `glossary/` and this one, outermost first. */\n  chain: string[];\n}\n\ninterface WalkState {\n  terms: GlossaryTerm[];\n  /** Realpaths already descended into — the symlink-cycle guard. */\n  visited: Set<string>;\n}\n\n/**\n * Read the tree under `root` (`glossaryDir(docsDir)`).\n *\n * A fleet is expected to hold tens to low hundreds of these — a domain's\n * vocabulary, not its data — so the cost is one `readdir` per directory and the\n * walk's expense is a non-question. The symlink-cycle guard is the one\n * `core/repo/tree/walk.ts` and the capability walk both carry\n * (`core/repo/tree/fs.ts`'s `markDescended`), and for the same reason:\n * `entryIs` follows symlinks on purpose, and a followed cycle without a\n * visited set recurses until the stack ends.\n */\nexport async function readGlossary(root: string): Promise<Glossary> {\n  if (!existsSync(root)) return { present: false, terms: [] };\n  const state: WalkState = { terms: [], visited: new Set() };\n  await visit({ dir: root, chain: [] }, state);\n  state.terms.sort((a, b) => compareIds(a.id, b.id));\n  return { present: true, terms: state.terms };\n}\n\n/** Collect the terms in one directory and walk what is beneath it. */\nasync function visit(spot: Spot, state: WalkState): Promise<void> {\n  if (!markDescended(spot.dir, state.visited)) return;\n  const entries = (await readdir(spot.dir, { withFileTypes: true })).filter((e) => !e.name.startsWith(\".\"));\n  for (const entry of entries.filter((e) => e.name.endsWith(\".md\")).sort((a, b) => compareIds(a.name, b.name))) {\n    if (entry.name === INDEX_PAGE || !entryIs(spot.dir, entry, \"file\")) continue;\n    state.terms.push({\n      id: [...spot.chain, entry.name.slice(0, -\".md\".length)].join(\"/\"),\n      path: join(spot.dir, entry.name),\n    });\n  }\n  // Sequential, not Promise.all: the visited set is shared mutable state and\n  // the walk's correctness under symlinks rests on a child being marked before\n  // its sibling asks. These trees are tens of directories at most.\n  for (const child of entries.filter((e) => entryIs(spot.dir, e, \"dir\")).map((e) => e.name).sort()) {\n    await visit({ dir: join(spot.dir, child), chain: [...spot.chain, child] }, state);\n  }\n}\n"]}

package/dist/core/kernel/concurrency.js

@@ -7,6 +7,16 @@
  * either opens all of them — on a big fleet that is not a faster run, it is a
  * bigger one. The cap and the ordering guarantee travel together because a
  * caller that wants the first cannot afford to lose the second.
+ *
+ * The third answer to "how much may happen at once" is `memo`: the same read
+ * asked for twice in one invocation happens once, both askers sharing the one
+ * in-flight promise. It lives here, in a leaf, because both read indexes —
+ * `core/fleet-context.ts` and the service-model memos it owns
+ * (`core/c4/prefetch/fleet.ts`) — spell every cache they keep with it, and
+ * neither should own the other's idiom. The read index could borrow it from
+ * the package it already imports, but then a rule about caching in general
+ * would live inside the LikeC4 adapter, and the next memo outside `c4/` would
+ * have to import that adapter to obey it.
  */
 import { cpus } from "node:os";
 /**
@@ -48,4 +58,13 @@ export async function inOrder(items, work) {
     }));
     return out;
 }
+/** One in-flight promise per key, created on first ask — the memo idiom, once. */
+export function memo(store, k, make) {
+    let pending = store.get(k);
+    if (pending === undefined) {
+        pending = make();
+        store.set(k, pending);
+    }
+    return pending;
+}
 //# sourceMappingURL=concurrency.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"concurrency.js","sourceRoot":"","sources":["../../../src/core/kernel/concurrency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAE/B;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;AAE1E;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,KAAmB,EACnB,IAA6B;IAE7B,MAAM,GAAG,GAAQ,EAAE,CAAC;IACpB,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,kBAAkB,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC3D,MAAM,OAAO,CAAC,GAAG,CACf,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,KAAK,IAAI,EAAE;QACzC,KAAK,IAAI,CAAC,GAAG,IAAI,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE;YAAE,GAAG,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,CAAC;IACpF,CAAC,CAAC,CACH,CAAC;IACF,OAAO,GAAG,CAAC;AACb,CAAC","sourcesContent":["/**\n * How much of loam may happen at once, and in what order the answers come back.\n *\n * One rule, because there is one resource being rationed: a LikeC4/Langium\n * workspace. `validate --all` opens one per service and per feature, the\n * dependency graph opens one per feature, and an unbounded `Promise.all` over\n * either opens all of them — on a big fleet that is not a faster run, it is a\n * bigger one. The cap and the ordering guarantee travel together because a\n * caller that wants the first cannot afford to lose the second.\n */\nimport { cpus } from \"node:os\";\n\n/**\n * How many units of work may be in flight at once.\n *\n * Capped as well as scaled: each in-flight unit holds a whole LikeC4/Langium\n * workspace, so a 64-core box would open sixty-four of them at once and buy\n * memory pressure rather than throughput (peak RSS on an 80-service fleet:\n * 385 MB serial, ~500 MB pooled). That measurement is the entire justification\n * for the cap, and it is why the cap lives with the work rather than inside one\n * command: `loam dependencies` and the fleet form of `loam status` fan out over\n * the same workspaces `validate --all` does, and used to do it uncapped.\n *\n * Do not quote a speedup for this. The measured cost is CPU inside the Langium\n * parse, which one thread cannot divide however the loop is shaped; what the\n * pool overlaps is the I/O half — the spec, contract and health reads around\n * each parse. On an 80-service fleet it measures as a wash (11–13 s either way,\n * on a box that was itself loaded). The number that moves these commands is\n * workspaces per run, not awaits per loop.\n */\nexport const TARGET_CONCURRENCY = Math.max(1, Math.min(cpus().length, 8));\n\n/**\n * Run `work` over `items` with a bounded number in flight, returning the\n * results in INPUT order.\n *\n * The order is the contract, not an accident: the text report and the `--json`\n * envelope are diffed between runs and between machines, so a concurrent run\n * has to be byte-identical to the serial one for the same input. That is why\n * results are written by index — nothing is appended as it finishes, and a slow\n * item cannot reorder the fleet around it.\n */\nexport async function inOrder<T, R>(\n  items: readonly T[],\n  work: (item: T) => Promise<R>,\n): Promise<R[]> {\n  const out: R[] = [];\n  let next = 0;\n  const workers = Math.min(TARGET_CONCURRENCY, items.length);\n  await Promise.all(\n    Array.from({ length: workers }, async () => {\n      for (let i = next++; i < items.length; i = next++) out[i] = await work(items[i]!);\n    }),\n  );\n  return out;\n}\n"]}
+{"version":3,"file":"concurrency.js","sourceRoot":"","sources":["../../../src/core/kernel/concurrency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAE/B;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;AAE1E;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,KAAmB,EACnB,IAA6B;IAE7B,MAAM,GAAG,GAAQ,EAAE,CAAC;IACpB,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,kBAAkB,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC3D,MAAM,OAAO,CAAC,GAAG,CACf,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,KAAK,IAAI,EAAE;QACzC,KAAK,IAAI,CAAC,GAAG,IAAI,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE;YAAE,GAAG,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,CAAC;IACpF,CAAC,CAAC,CACH,CAAC;IACF,OAAO,GAAG,CAAC;AACb,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,IAAI,CAAI,KAA8B,EAAE,CAAS,EAAE,IAAsB;IACvF,IAAI,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAC3B,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,OAAO,GAAG,IAAI,EAAE,CAAC;QACjB,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IACxB,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC","sourcesContent":["/**\n * How much of loam may happen at once, and in what order the answers come back.\n *\n * One rule, because there is one resource being rationed: a LikeC4/Langium\n * workspace. `validate --all` opens one per service and per feature, the\n * dependency graph opens one per feature, and an unbounded `Promise.all` over\n * either opens all of them — on a big fleet that is not a faster run, it is a\n * bigger one. The cap and the ordering guarantee travel together because a\n * caller that wants the first cannot afford to lose the second.\n *\n * The third answer to \"how much may happen at once\" is `memo`: the same read\n * asked for twice in one invocation happens once, both askers sharing the one\n * in-flight promise. It lives here, in a leaf, because both read indexes —\n * `core/fleet-context.ts` and the service-model memos it owns\n * (`core/c4/prefetch/fleet.ts`) — spell every cache they keep with it, and\n * neither should own the other's idiom. The read index could borrow it from\n * the package it already imports, but then a rule about caching in general\n * would live inside the LikeC4 adapter, and the next memo outside `c4/` would\n * have to import that adapter to obey it.\n */\nimport { cpus } from \"node:os\";\n\n/**\n * How many units of work may be in flight at once.\n *\n * Capped as well as scaled: each in-flight unit holds a whole LikeC4/Langium\n * workspace, so a 64-core box would open sixty-four of them at once and buy\n * memory pressure rather than throughput (peak RSS on an 80-service fleet:\n * 385 MB serial, ~500 MB pooled). That measurement is the entire justification\n * for the cap, and it is why the cap lives with the work rather than inside one\n * command: `loam dependencies` and the fleet form of `loam status` fan out over\n * the same workspaces `validate --all` does, and used to do it uncapped.\n *\n * Do not quote a speedup for this. The measured cost is CPU inside the Langium\n * parse, which one thread cannot divide however the loop is shaped; what the\n * pool overlaps is the I/O half — the spec, contract and health reads around\n * each parse. On an 80-service fleet it measures as a wash (11–13 s either way,\n * on a box that was itself loaded). The number that moves these commands is\n * workspaces per run, not awaits per loop.\n */\nexport const TARGET_CONCURRENCY = Math.max(1, Math.min(cpus().length, 8));\n\n/**\n * Run `work` over `items` with a bounded number in flight, returning the\n * results in INPUT order.\n *\n * The order is the contract, not an accident: the text report and the `--json`\n * envelope are diffed between runs and between machines, so a concurrent run\n * has to be byte-identical to the serial one for the same input. That is why\n * results are written by index — nothing is appended as it finishes, and a slow\n * item cannot reorder the fleet around it.\n */\nexport async function inOrder<T, R>(\n  items: readonly T[],\n  work: (item: T) => Promise<R>,\n): Promise<R[]> {\n  const out: R[] = [];\n  let next = 0;\n  const workers = Math.min(TARGET_CONCURRENCY, items.length);\n  await Promise.all(\n    Array.from({ length: workers }, async () => {\n      for (let i = next++; i < items.length; i = next++) out[i] = await work(items[i]!);\n    }),\n  );\n  return out;\n}\n\n/** One in-flight promise per key, created on first ask — the memo idiom, once. */\nexport function memo<T>(store: Map<string, Promise<T>>, k: string, make: () => Promise<T>): Promise<T> {\n  let pending = store.get(k);\n  if (pending === undefined) {\n    pending = make();\n    store.set(k, pending);\n  }\n  return pending;\n}\n"]}

package/dist/core/kernel/ids/fqn/ancestors.js

@@ -0,0 +1,65 @@
+/**
+ * The ancestor chain of a dotted element id — `a.b.c` yields `a.b`, then `a`.
+ *
+ * A leaf of its own because five modules were each walking it privately, in two
+ * spellings, and the walk is not incidental to any of them: it is the rule that
+ * a landscape does not have to draw a service as one opaque box. The moment
+ * somebody models its containers — `paymentService.api`, `paymentService.worker`
+ * — an edge drawn INTO a container is still an edge into the service, and every
+ * join that groups by service has to know that. Resolving only the exact id is
+ * what made those edges invisible: the spine check silently skipped them, and
+ * the no-openapi grace treated a service with a dozen inbound container calls as
+ * one nobody calls at all.
+ *
+ * The same walk answers a second question one altitude down, which is why a
+ * fifth copy appeared. A service model draws an edge at `kafka.orderEvents`
+ * while the fleet's health.yaml names the dependency `kafka`, so the slice of a
+ * per-service project has to carry the ANCESTOR of a partner endpoint as well as
+ * the endpoint (`core/c4/service-model/slice.ts`). Dropping it would turn a
+ * fleet's dependency declarations into `health.dependency-unmodelled` findings
+ * on the day it migrated its models, with nothing in the docs having changed.
+ *
+ * TWO SPELLINGS, both exported, because both are real and picking one would make
+ * every second caller write `[id, ...properAncestorIds(id)]` or `.slice(1)` — a
+ * per-call-site adjustment is exactly how a shared walk drifts back into five.
+ * A resolver that also looks the element itself up wants `ancestorIds`; a walk
+ * that has already handled the element wants `properAncestorIds`.
+ *
+ * No brand and no validation: this is string arithmetic over an id a DOCUMENT
+ * spells, and `core/kernel/ids/service.ts`'s provenance rules are about names
+ * that have to answer for a directory. An id with no dot in it has no ancestors
+ * and yields the empty list, which is the correct answer rather than an edge
+ * case — a top-level element belongs to nothing above it.
+ */
+/** Every dotted ancestor of an id, NEAREST FIRST and excluding the id itself. */
+export function properAncestorIds(id) {
+    const out = [];
+    // Walking right-to-left from the last dot rather than splitting and rejoining:
+    // the ids are already strings, the answer is a set of prefixes of one of them,
+    // and a split/join round trip would invent a rule about what a segment may
+    // contain that nothing else here has.
+    for (let dot = id.lastIndexOf("."); dot !== -1; dot = id.lastIndexOf(".", dot - 1)) {
+        out.push(id.slice(0, dot));
+    }
+    return out;
+}
+/** The id itself, then every dotted ancestor of it, nearest first. */
+export function ancestorIds(id) {
+    return [id, ...properAncestorIds(id)];
+}
+/**
+ * The id a declaration nests directly under — `""` for a top-level one, which
+ * nests under nothing.
+ *
+ * The nearest ancestor, named because that is the question the callers ask:
+ * `properAncestorIds(id)[0] ?? ""` is the same walk spelled as an array index,
+ * and every reader has to re-derive that the first entry is the parent. It is
+ * here rather than beside its callers for the reason the file exists at all —
+ * the archive's two merges had each grown a private copy, and a third was about
+ * to appear the moment the routing gained a module.
+ */
+export function parentIdOf(id) {
+    const dot = id.lastIndexOf(".");
+    return dot === -1 ? "" : id.slice(0, dot);
+}
+//# sourceMappingURL=ancestors.js.map

package/dist/core/kernel/ids/fqn/ancestors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ancestors.js","sourceRoot":"","sources":["../../../../../src/core/kernel/ids/fqn/ancestors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,iFAAiF;AACjF,MAAM,UAAU,iBAAiB,CAAC,EAAU;IAC1C,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,+EAA+E;IAC/E,+EAA+E;IAC/E,2EAA2E;IAC3E,sCAAsC;IACtC,KAAK,IAAI,GAAG,GAAG,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,GAAG,KAAK,CAAC,CAAC,EAAE,GAAG,GAAG,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,GAAG,CAAC,CAAC,EAAE,CAAC;QACnF,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;IAC7B,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,WAAW,CAAC,EAAU;IACpC,OAAO,CAAC,EAAE,EAAE,GAAG,iBAAiB,CAAC,EAAE,CAAC,CAAC,CAAC;AACxC,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,UAAU,CAAC,EAAU;IACnC,MAAM,GAAG,GAAG,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAChC,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AAC5C,CAAC","sourcesContent":["/**\n * The ancestor chain of a dotted element id — `a.b.c` yields `a.b`, then `a`.\n *\n * A leaf of its own because five modules were each walking it privately, in two\n * spellings, and the walk is not incidental to any of them: it is the rule that\n * a landscape does not have to draw a service as one opaque box. The moment\n * somebody models its containers — `paymentService.api`, `paymentService.worker`\n * — an edge drawn INTO a container is still an edge into the service, and every\n * join that groups by service has to know that. Resolving only the exact id is\n * what made those edges invisible: the spine check silently skipped them, and\n * the no-openapi grace treated a service with a dozen inbound container calls as\n * one nobody calls at all.\n *\n * The same walk answers a second question one altitude down, which is why a\n * fifth copy appeared. A service model draws an edge at `kafka.orderEvents`\n * while the fleet's health.yaml names the dependency `kafka`, so the slice of a\n * per-service project has to carry the ANCESTOR of a partner endpoint as well as\n * the endpoint (`core/c4/service-model/slice.ts`). Dropping it would turn a\n * fleet's dependency declarations into `health.dependency-unmodelled` findings\n * on the day it migrated its models, with nothing in the docs having changed.\n *\n * TWO SPELLINGS, both exported, because both are real and picking one would make\n * every second caller write `[id, ...properAncestorIds(id)]` or `.slice(1)` — a\n * per-call-site adjustment is exactly how a shared walk drifts back into five.\n * A resolver that also looks the element itself up wants `ancestorIds`; a walk\n * that has already handled the element wants `properAncestorIds`.\n *\n * No brand and no validation: this is string arithmetic over an id a DOCUMENT\n * spells, and `core/kernel/ids/service.ts`'s provenance rules are about names\n * that have to answer for a directory. An id with no dot in it has no ancestors\n * and yields the empty list, which is the correct answer rather than an edge\n * case — a top-level element belongs to nothing above it.\n */\n\n/** Every dotted ancestor of an id, NEAREST FIRST and excluding the id itself. */\nexport function properAncestorIds(id: string): string[] {\n  const out: string[] = [];\n  // Walking right-to-left from the last dot rather than splitting and rejoining:\n  // the ids are already strings, the answer is a set of prefixes of one of them,\n  // and a split/join round trip would invent a rule about what a segment may\n  // contain that nothing else here has.\n  for (let dot = id.lastIndexOf(\".\"); dot !== -1; dot = id.lastIndexOf(\".\", dot - 1)) {\n    out.push(id.slice(0, dot));\n  }\n  return out;\n}\n\n/** The id itself, then every dotted ancestor of it, nearest first. */\nexport function ancestorIds(id: string): string[] {\n  return [id, ...properAncestorIds(id)];\n}\n\n/**\n * The id a declaration nests directly under — `\"\"` for a top-level one, which\n * nests under nothing.\n *\n * The nearest ancestor, named because that is the question the callers ask:\n * `properAncestorIds(id)[0] ?? \"\"` is the same walk spelled as an array index,\n * and every reader has to re-derive that the first entry is the parent. It is\n * here rather than beside its callers for the reason the file exists at all —\n * the archive's two merges had each grown a private copy, and a third was about\n * to appear the moment the routing gained a module.\n */\nexport function parentIdOf(id: string): string {\n  const dot = id.lastIndexOf(\".\");\n  return dot === -1 ? \"\" : id.slice(0, dot);\n}\n"]}

package/dist/core/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

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

@@ -1 +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 * 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"]}
+{"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/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

@@ -1 +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;;;;;;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 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"]}
+{"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

@@ -20,11 +20,9 @@
  * file already earns `link.unreadable`; `loam list` has no such finding, so it
  * needs the list to say what it did not read.
  */
-import { readFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
 import { repoPath } from "../envelope/json.js";
-import { decodeDocument } from "../kernel/document-bytes.js";
 import { pathCaseIndex } from "./case.js";
 import { allAuthoredDocuments } from "./corpus.js";
 import { resolveLinks } from "./findings.js";
@@ -44,7 +42,7 @@ export async function backlinkIndex(docsDir, fleet) {
             continue;
         let text;
         try {
-            text = fleet === undefined ? decodeDocument(await readFile(path), path) : await fleet.readText(path);
+            text = await fleet.readText(path);
         }
         catch {
             unreadable.push(repoPath(docsDir, path));

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

@@ -1 +1 @@
-{"version":3,"file":"backlinks.js","sourceRoot":"","sources":["../../../src/core/links/backlinks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAE/C,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAE7D,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,KAAoB;IACxE,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,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,cAAc,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QACvG,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 { readFile } from \"node:fs/promises\";\nimport { existsSync } from \"node:fs\";\nimport { resolve } from \"node:path\";\nimport { repoPath } from \"../envelope/json.js\";\nimport type { FleetContext } from \"../fleet-context.js\";\nimport { decodeDocument } from \"../kernel/document-bytes.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 = fleet === undefined ? decodeDocument(await readFile(path), path) : 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"]}
+{"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"]}