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

package/dist/core/gherkin/steps/inventory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inventory.js","sourceRoot":"","sources":["../../../../src/core/gherkin/steps/inventory.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The step-phrase inventory: how many DEFINITIONS a service's suite actually\n * needs, and which written steps collapse onto each one.\n *\n * ## What this is for\n *\n * Generated `.feature` files are only a suite if somebody writes the glue, and\n * the glue is where a generated suite dies: the step text is free prose from a\n * spec bullet, so the same precondition gets three spellings across three\n * requirements and the registry grows without bound until people quietly go\n * back to hand-written tests. Nothing in loam could previously say how bad that\n * was, which meant nobody could tell a suite that needs forty definitions from\n * one that needs four hundred.\n *\n * Measured on a real twelve-scenario component-test file, 324 written steps\n * collapse to 97 phrases, and 34 of those cover 82% of every step — so the\n * report is not an audit, it is the work-list a team writes glue from, and the\n * draft of any step catalogue that comes later.\n *\n * ## What it deliberately is NOT\n *\n * It emits no finding and no stable code. A near-duplicate is a judgement about\n * writing, and a phrase-similarity WARNING is the kind of check a fleet turns\n * off — at which point the real findings beside it are turned off too. It reads\n * the LIVING specs rather than the emitted files, so it answers the same way in\n * a repo that has never run `loam gherkin` and needs no service repo to stand\n * in.\n */\nimport { scenarioGherkin } from \"../../vocabulary/steps.js\";\nimport { type Requirement } from \"../../document/spec.js\";\nimport { keywordOf, phraseOf } from \"./phrase.js\";\n\n/** Where one written step lives, for the reader who wants to go and look. */\nexport interface PhraseUse {\n  requirement: string;\n  scenario: string;\n  /** \"business\" or \"arch\" — the two spec files are two namespaces everywhere else too. */\n  axis: string;\n  /** The step exactly as the spec writes it, keyword included. */\n  text: string;\n}\n\nexport interface PhraseRow {\n  /** The normalized phrase — one step definition serves every use under it. */\n  key: string;\n  /** How many written steps collapse onto this key. */\n  count: number;\n  /** The Gherkin keywords this phrase appears under, sorted — a runner resolves them as one. */\n  keywords: string[];\n  uses: PhraseUse[];\n}\n\n/** Phrases that share a family and not a key: two definitions where one was probably meant. */\nexport interface NearDuplicates {\n  family: string;\n  keys: string[];\n}\n\nexport interface StepInventory {\n  /** Total written steps across every scenario of both axes. */\n  steps: number;\n  /** Distinct phrases, most-used first, then alphabetically so the report is stable. */\n  phrases: PhraseRow[];\n  nearDuplicates: NearDuplicates[];\n}\n\n/** One spec file's requirements, with the axis label the whole product speaks. */\nexport interface InventoryAxis {\n  axis: string;\n  reqs: Requirement[];\n}\n\n/**\n * Count the phrases across both axes of one service.\n *\n * REMOVED requirements are skipped, exactly as every other scenario check skips\n * them: a step nobody will run is not glue anybody owes.\n *\n * Ordering is count-descending then key-ascending, and that second key is what\n * makes the report diffable — two phrases used once each must not swap places\n * between runs because a Map happened to iterate differently.\n */\nexport function stepInventory(axes: readonly InventoryAxis[]): StepInventory {\n  const byKey = new Map<string, PhraseRow>();\n  const families = new Map<string, Set<string>>();\n  let steps = 0;\n  for (const { axis, reqs } of axes) {\n    for (const r of reqs) {\n      if (r.kind === \"REMOVED\") continue;\n      for (const s of r.scenarios) {\n        for (const st of scenarioGherkin(s.lines).steps) {\n          steps += 1;\n          const { key, family } = phraseOf(st.text);\n          const row = byKey.get(key) ?? { key, count: 0, keywords: [], uses: [] };\n          row.count += 1;\n          const kw = keywordOf(st.text);\n          if (kw.length > 0 && !row.keywords.includes(kw)) row.keywords.push(kw);\n          row.uses.push({ requirement: r.name, scenario: s.name, axis, text: st.text });\n          byKey.set(key, row);\n          const seen = families.get(family) ?? new Set<string>();\n          seen.add(key);\n          families.set(family, seen);\n        }\n      }\n    }\n  }\n  const phrases = [...byKey.values()]\n    .map((row) => ({ ...row, keywords: [...row.keywords].sort() }))\n    .sort((a, b) => b.count - a.count || (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));\n  const nearDuplicates = [...families.entries()]\n    .filter(([, keys]) => keys.size > 1)\n    .map(([family, keys]) => ({ family, keys: [...keys].sort() }))\n    .sort((a, b) => (a.family < b.family ? -1 : a.family > b.family ? 1 : 0));\n  return { steps, phrases, nearDuplicates };\n}\n\n/**\n * How many phrases cover `share` of every written step — the one number that\n * says whether the glue is a morning's work or a quarter's.\n *\n * Returns zero for an empty suite rather than dividing by it, because \"0 of 0\n * steps\" is the honest reading of a service that has written no scenarios yet.\n */\nexport function coveringPhrases(inv: StepInventory, share = 0.8): number {\n  if (inv.steps === 0) return 0;\n  const target = inv.steps * share;\n  let running = 0;\n  let n = 0;\n  for (const row of inv.phrases) {\n    if (running >= target) break;\n    running += row.count;\n    n += 1;\n  }\n  return n;\n}\n"]}

package/dist/core/gherkin/steps/phrase.js

@@ -0,0 +1,72 @@
+/**
+ * The PHRASE KEY: what makes two written steps the same step definition.
+ *
+ * `loam steps` counts by this key, so the moment it ships the recipe is a
+ * contract — a team writes glue against the groups it reports, and a key that
+ * drifts re-partitions their whole registry. `test/steps-inventory.test.ts`
+ * pins it case by case for that reason.
+ *
+ * ## Why the keyword is dropped
+ *
+ * Every mainstream runner resolves Given/When/Then/And/But against ONE registry
+ * of patterns, so `Given the ledger is open` and `And the ledger is open` are
+ * one definition and must count as one row. Keeping the keyword would split
+ * every continued step from the step it continues, and the number the whole
+ * report exists to give — how many definitions does this suite need — would be
+ * wrong in the direction that flatters it.
+ *
+ * ## Why literals collapse and prose does not
+ *
+ * A quoted string, an angle-bracket placeholder and a bare number are what a
+ * step definition captures as an ARGUMENT; everything else is what it matches
+ * on. Collapsing exactly those three is therefore not a heuristic about
+ * similarity — it is the same partition the runner will make when the patterns
+ * are written. Nothing here measures edit distance: `core/repo/entries.ts`
+ * already records that verdict for close-id suggestions, and a third private
+ * copy of that function would be the drift it warns about.
+ */
+const KEYWORD_RE = /^(given|when|then|and|but)\s+/i;
+/**
+ * A subordinate clause that explains WHY, which a step definition never
+ * matches on separately: `validation branch "x" passes because the window is
+ * open` is the same definition as `validation branch "x" passes`, with the
+ * reason baked into the pattern. Reported as a near-duplicate rather than
+ * merged, because the fix — move the reason into the scenario description — is
+ * the author's to make.
+ */
+const RATIONALE_RE = /\s+(because|while|since|unless|so that)\s+.*$/i;
+const LEADING_ARTICLE_RE = /^(the|a|an)\s+/i;
+/** `Given a payment of 100.00 for "<tier>"` -> key `a payment of {n} for {s}`. */
+export function phraseOf(stepText) {
+    const key = stepText
+        .replace(KEYWORD_RE, "")
+        // A QUOTED placeholder is still a placeholder — `"<tier>"` is the outline's
+        // parameter, and letting the string rule reach it first would collapse the
+        // whole token to {s} and hide that the step is parameterized at all.
+        .replace(/(["'`])<[^<>\s]+>\1/g, "{p}")
+        .replace(/<[^<>\s]+>/g, "{p}")
+        .replace(/"[^"]*"/g, "{s}")
+        .replace(/'[^']*'/g, "{s}")
+        .replace(/`[^`]*`/g, "{s}")
+        // A number only when it stands alone: `v1` and `oauth2` are part of a name,
+        // and collapsing them would merge two steps that match different patterns.
+        .replace(/(?<![\w.])\d+(?:\.\d+)?(?![\w.])/g, "{n}")
+        .replace(/\s+/g, " ")
+        .trim();
+    const family = key
+        .replace(RATIONALE_RE, "")
+        .replace(LEADING_ARTICLE_RE, "")
+        .replace(/[.,;:]+$/, "")
+        .replace(/\s+/g, " ")
+        .trim();
+    return { key, family };
+}
+/** The canonical keyword of a written step line, for reporting which ones a phrase appears under. */
+export function keywordOf(stepText) {
+    const m = KEYWORD_RE.exec(stepText);
+    if (!m)
+        return "";
+    const w = m[1].toLowerCase();
+    return w[0].toUpperCase() + w.slice(1);
+}
+//# sourceMappingURL=phrase.js.map

package/dist/core/gherkin/steps/phrase.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"phrase.js","sourceRoot":"","sources":["../../../../src/core/gherkin/steps/phrase.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,MAAM,UAAU,GAAG,gCAAgC,CAAC;AAEpD;;;;;;;GAOG;AACH,MAAM,YAAY,GAAG,gDAAgD,CAAC;AAEtE,MAAM,kBAAkB,GAAG,iBAAiB,CAAC;AAa7C,kFAAkF;AAClF,MAAM,UAAU,QAAQ,CAAC,QAAgB;IACvC,MAAM,GAAG,GAAG,QAAQ;SACjB,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC;QACxB,4EAA4E;QAC5E,2EAA2E;QAC3E,qEAAqE;SACpE,OAAO,CAAC,sBAAsB,EAAE,KAAK,CAAC;SACtC,OAAO,CAAC,aAAa,EAAE,KAAK,CAAC;SAC7B,OAAO,CAAC,UAAU,EAAE,KAAK,CAAC;SAC1B,OAAO,CAAC,UAAU,EAAE,KAAK,CAAC;SAC1B,OAAO,CAAC,UAAU,EAAE,KAAK,CAAC;QAC3B,4EAA4E;QAC5E,2EAA2E;SAC1E,OAAO,CAAC,mCAAmC,EAAE,KAAK,CAAC;SACnD,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC;SACpB,IAAI,EAAE,CAAC;IACV,MAAM,MAAM,GAAG,GAAG;SACf,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC;SACzB,OAAO,CAAC,kBAAkB,EAAE,EAAE,CAAC;SAC/B,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC;SACvB,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC;SACpB,IAAI,EAAE,CAAC;IACV,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC;AACzB,CAAC;AAED,qGAAqG;AACrG,MAAM,UAAU,SAAS,CAAC,QAAgB;IACxC,MAAM,CAAC,GAAG,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACpC,IAAI,CAAC,CAAC;QAAE,OAAO,EAAE,CAAC;IAClB,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC,WAAW,EAAE,CAAC;IAC9B,OAAO,CAAC,CAAC,CAAC,CAAE,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAC1C,CAAC","sourcesContent":["/**\n * The PHRASE KEY: what makes two written steps the same step definition.\n *\n * `loam steps` counts by this key, so the moment it ships the recipe is a\n * contract — a team writes glue against the groups it reports, and a key that\n * drifts re-partitions their whole registry. `test/steps-inventory.test.ts`\n * pins it case by case for that reason.\n *\n * ## Why the keyword is dropped\n *\n * Every mainstream runner resolves Given/When/Then/And/But against ONE registry\n * of patterns, so `Given the ledger is open` and `And the ledger is open` are\n * one definition and must count as one row. Keeping the keyword would split\n * every continued step from the step it continues, and the number the whole\n * report exists to give — how many definitions does this suite need — would be\n * wrong in the direction that flatters it.\n *\n * ## Why literals collapse and prose does not\n *\n * A quoted string, an angle-bracket placeholder and a bare number are what a\n * step definition captures as an ARGUMENT; everything else is what it matches\n * on. Collapsing exactly those three is therefore not a heuristic about\n * similarity — it is the same partition the runner will make when the patterns\n * are written. Nothing here measures edit distance: `core/repo/entries.ts`\n * already records that verdict for close-id suggestions, and a third private\n * copy of that function would be the drift it warns about.\n */\n\nconst KEYWORD_RE = /^(given|when|then|and|but)\\s+/i;\n\n/**\n * A subordinate clause that explains WHY, which a step definition never\n * matches on separately: `validation branch \"x\" passes because the window is\n * open` is the same definition as `validation branch \"x\" passes`, with the\n * reason baked into the pattern. Reported as a near-duplicate rather than\n * merged, because the fix — move the reason into the scenario description — is\n * the author's to make.\n */\nconst RATIONALE_RE = /\\s+(because|while|since|unless|so that)\\s+.*$/i;\n\nconst LEADING_ARTICLE_RE = /^(the|a|an)\\s+/i;\n\nexport interface Phrase {\n  /** Two steps sharing this need ONE step definition. */\n  key: string;\n  /**\n   * The looser key that gathers near-duplicates: the same phrase with a leading\n   * article or a trailing rationale clause. Steps sharing a family but not a key\n   * are two definitions where the author probably meant one.\n   */\n  family: string;\n}\n\n/** `Given a payment of 100.00 for \"<tier>\"` -> key `a payment of {n} for {s}`. */\nexport function phraseOf(stepText: string): Phrase {\n  const key = stepText\n    .replace(KEYWORD_RE, \"\")\n    // A QUOTED placeholder is still a placeholder — `\"<tier>\"` is the outline's\n    // parameter, and letting the string rule reach it first would collapse the\n    // whole token to {s} and hide that the step is parameterized at all.\n    .replace(/([\"'`])<[^<>\\s]+>\\1/g, \"{p}\")\n    .replace(/<[^<>\\s]+>/g, \"{p}\")\n    .replace(/\"[^\"]*\"/g, \"{s}\")\n    .replace(/'[^']*'/g, \"{s}\")\n    .replace(/`[^`]*`/g, \"{s}\")\n    // A number only when it stands alone: `v1` and `oauth2` are part of a name,\n    // and collapsing them would merge two steps that match different patterns.\n    .replace(/(?<![\\w.])\\d+(?:\\.\\d+)?(?![\\w.])/g, \"{n}\")\n    .replace(/\\s+/g, \" \")\n    .trim();\n  const family = key\n    .replace(RATIONALE_RE, \"\")\n    .replace(LEADING_ARTICLE_RE, \"\")\n    .replace(/[.,;:]+$/, \"\")\n    .replace(/\\s+/g, \" \")\n    .trim();\n  return { key, family };\n}\n\n/** The canonical keyword of a written step line, for reporting which ones a phrase appears under. */\nexport function keywordOf(stepText: string): string {\n  const m = KEYWORD_RE.exec(stepText);\n  if (!m) return \"\";\n  const w = m[1]!.toLowerCase();\n  return w[0]!.toUpperCase() + w.slice(1);\n}\n"]}

package/dist/core/glossary/delta.js

@@ -0,0 +1,106 @@
+/**
+ * A feature's own glossary deltas: `features/<FEAT>/glossary/<term>.md`.
+ *
+ * A change that needs a new word brings the word with it. The archive copies the
+ * definition into `glossary/`, `loam unarchive` takes it back out with
+ * everything else the feature landed, and until then the term is visible in
+ * review beside the requirements that use it — which is the whole reason this
+ * route exists rather than "remember to edit the glossary too".
+ *
+ * CREATE-ONLY, and this is the axis's one real design decision rather than an
+ * unfinished half. A feature-local capability document is a DELTA — `## ADDED
+ * Requirements`, `Requirement-ID:` identity, `Based-On:` pins — because it
+ * merges INTO a living document and two features editing one requirement would
+ * otherwise silently overwrite each other. A term has none of that: the file is
+ * one definition, the merge is a whole-file copy, and there is nothing to merge
+ * partially. So rewriting a living definition through a feature would be a
+ * silent whole-file replacement with no pin to collide on, where editing
+ * `glossary/<term>.md` directly in the same pull request produces an ordinary
+ * git conflict that a human resolves. `glossary.term-exists` refuses the first
+ * and points at the second.
+ *
+ * TWO FEATURES INTRODUCING THE SAME WORD is the case that makes the refusal
+ * load-bearing rather than pedantic: whichever archives first creates the living
+ * definition, and the second is told — loudly, before it merges — that the word
+ * now exists and its own file is the one to delete.
+ *
+ * ONE CALL for the walk, because it is already written: `readGlossary`
+ * implements the file-is-a-term rule, the `README.md` exclusion, the nesting and
+ * the symlink guard over any root. A second walk for the feature side would be
+ * two implementations free to disagree about what a term is.
+ */
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { featureGlossaryDir, glossaryDir } from "../repo/authored/paths.js";
+import {} from "../vocabulary/issue.js";
+import { readGlossary } from "./tree.js";
+/**
+ * The definitions one feature carries, ordered by id.
+ *
+ * `present: false` — and zero readdirs — when the feature has no `glossary/`
+ * directory, which is every feature in a fleet that has not adopted the axis.
+ * That short-circuit is `readGlossary`'s own `existsSync` and it is the whole
+ * cost such a fleet pays.
+ */
+export function featureGlossary(featureDir) {
+    return readGlossary(featureGlossaryDir(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.
+ */
+export async function featureGlossaryOverlay(docsDir, featureDir) {
+    const glossary = await featureGlossary(featureDir);
+    return new Set(glossary.terms.map((t) => resolve(livingTermPath(docsDir, t.id))));
+}
+/**
+ * `glossary.term-exists` — a term this feature introduces that the living
+ * glossary already defines.
+ *
+ * An ERROR and never a warning-that-gates: unlike `capability.uncovered`, there
+ * is no legal reading of it. The merge would replace an authored definition
+ * with another one, and no `--approve` makes that a different act than it is.
+ * The fix is in the message and is the one a reviewer would give anyway.
+ */
+export async function glossaryDeltaIssues(docsDir, featureDir) {
+    const glossary = await featureGlossary(featureDir);
+    if (!glossary.present)
+        return [];
+    return glossary.terms
+        .filter((term) => existsSync(livingTermPath(docsDir, term.id)))
+        .map((term) => ({
+        severity: "error",
+        code: "glossary.term-exists",
+        subject: term.id,
+        message: `glossary/${term.id}.md already exists, so this feature's definition of '${term.id}' would replace an authored one wholesale — ` +
+            "a feature-local glossary document INTRODUCES a term, it does not rewrite one. " +
+            `Delete features/<FEAT>/glossary/${term.id}.md and edit glossary/${term.id}.md directly in this same change, ` +
+            "where git produces an ordinary conflict if somebody else is editing it too.",
+    }));
+}
+/**
+ * The LIVING path a feature-local term id addresses. Spelled here because three
+ * readers need it — the refusal above, the overlay, and the archive merge — and
+ * a reader that resolved it differently would refuse a term the merge then
+ * created anyway.
+ *
+ * The id is joined un-split, which `node:path` normalizes: `join(dir, "a/b")`
+ * and `join(dir, "a", "b")` are the same string. What holds this join is
+ * PROVENANCE, exactly as it holds `livingCapabilityPaths` — every id here came
+ * out of a `readGlossary` walk, where each component is a `readdir` entry name
+ * and therefore a directory or file that exists. No caller takes one from argv;
+ * the day one does, it needs the treatment `core/kernel/ids/capability.ts` gave
+ * the same hazard one axis over.
+ */
+export function livingTermPath(docsDir, id) {
+    return join(glossaryDir(docsDir), `${id}.md`);
+}
+//# sourceMappingURL=delta.js.map

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

@@ -0,0 +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"]}

package/dist/core/glossary/tree.js

@@ -0,0 +1,86 @@
+/**
+ * The glossary tree: `glossary/<term>.md`, and the rule that a markdown file
+ * under it IS a declared term.
+ *
+ * WHY A TREE AND NOT A YAML VOCABULARY, at length in `repo/authored/paths.ts`'s
+ * `glossaryDir`: a single vocabulary file at fleet scale is unworkable, and a
+ * second list is the drift `loam init`'s removed service manifest was removed
+ * for. A term is prose — that is what a definition is — so by this codebase's
+ * own rule it gets a file.
+ *
+ * PRESENCE CLASSIFIES, one tree over from `capabilities/`: a `.md` file is a
+ * term, a directory is a group the walk descends through. There is no
+ * "half-created term" state to name, which is why this walk emits nothing like
+ * `capability.doc-missing`: creating a term is writing one file, and an empty
+ * grouping directory declares nothing and claims nothing.
+ *
+ * `README.md` IS NOT A TERM, and it is the one name excluded. A glossary big
+ * enough to want an index page is normal, and reporting that page as a word
+ * nobody uses would make the axis's only warning fire on the document that
+ * explains the axis. Excluded by name rather than by a marker field: the
+ * alternative is frontmatter nobody would remember to write.
+ *
+ * The walk reads directories only and never opens a file. What is IN a term
+ * 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 { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { compareIds } from "../repo/entries.js";
+import { entryIs } from "../repo/tree/fs.js";
+/** The one filename under `glossary/` that is not a term. */
+const INDEX_PAGE = "README.md";
+/**
+ * Read the tree under `root` (`glossaryDir(docsDir)`).
+ *
+ * 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
+ * visited set recurses until the stack ends.
+ */
+export async function readGlossary(root) {
+    if (!existsSync(root))
+        return { present: false, terms: [] };
+    const state = { terms: [], visited: new Set() };
+    await visit({ dir: root, chain: [] }, state);
+    state.terms.sort((a, b) => compareIds(a.id, b.id));
+    return { present: true, terms: state.terms };
+}
+/** Collect the terms in one directory and walk what is beneath it. */
+async function visit(spot, state) {
+    if (!descended(spot.dir, state))
+        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))) {
+        if (entry.name === INDEX_PAGE || !entryIs(spot.dir, entry, "file"))
+            continue;
+        state.terms.push({
+            id: [...spot.chain, entry.name.slice(0, -".md".length)].join("/"),
+            path: join(spot.dir, entry.name),
+        });
+    }
+    // Sequential, not Promise.all: the visited set is shared mutable state and
+    // the walk's correctness under symlinks rests on a child being marked before
+    // its sibling asks. These trees are tens of directories at most.
+    for (const child of entries.filter((e) => entryIs(spot.dir, e, "dir")).map((e) => e.name).sort()) {
+        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

@@ -0,0 +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"]}

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

@@ -0,0 +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"]}

package/dist/core/{document-bytes.js → kernel/document-bytes.js}

@@ -5,7 +5,7 @@
  * the frontmatter reader, the requirement parser, the fleet-wide read index and
  * three commands that read a single file directly. It lived beside the read
  * index, so each of those imported the whole index (and through it repo.ts,
- * openapi.ts and spec.ts) to reach a dozen lines of decoding, and several of
+ * openapi/doc.ts and document/spec.ts) to reach a dozen lines of decoding, and several of
  * them closed an import cycle doing it. A leaf whose only dependency is
  * `node:buffer` costs nothing to import and can be reached from anywhere.
  */

package/dist/core/kernel/document-bytes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-bytes.js","sourceRoot":"","sources":["../../../src/core/kernel/document-bytes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAIlC,IAAI;IAHG,IAAI,GAAG,sBAAsB,CAAC;IAEhD,YACW,IAAY,EACrB,MAAc;QAEd,KAAK,CACH,GAAG,IAAI,mCAAmC,MAAM,6DAA6D;YAC3G,+GAA+G;YAC/G,8GAA8G;YAC9G,2DAA2D,CAC9D,CAAC;oBARO,IAAI;IASf,CAAC;CACF;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc,CAAC,KAAa,EAAE,IAAY;IACxD,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,oBAAoB,CAAC,IAAI,EAAE,0CAA0C,CAAC,CAAC;IACrG,MAAM,IAAI,GAAG,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACpC,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,oBAAoB,CAC5B,IAAI,EACJ,iHAAiH,CAClH,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC","sourcesContent":["/**\n * Decode the bytes of a document loam is about to parse, or refuse naming it.\n *\n * The rule belongs to every module that turns a markdown artifact into text —\n * the frontmatter reader, the requirement parser, the fleet-wide read index and\n * three commands that read a single file directly. It lived beside the read\n * index, so each of those imported the whole index (and through it repo.ts,\n * openapi/doc.ts and document/spec.ts) to reach a dozen lines of decoding, and several of\n * them closed an import cycle doing it. A leaf whose only dependency is\n * `node:buffer` costs nothing to import and can be reached from anywhere.\n */\nimport { isUtf8 } from \"node:buffer\";\n\n/**\n * A document loam was about to parse that is not UTF-8 text.\n *\n * Thrown rather than returned, and named as the file rather than as an empty\n * document, because every parser in the codebase reads \"no requirements, no\n * frontmatter\" as a legitimate state — a fresh baseline looks exactly like it.\n * A `spec.md` saved as UTF-16 (PowerShell's `>` writes UTF-16LE by default)\n * therefore validated green, with every requirement in it invisible.\n *\n * `path` is spelled the way Node spells it on an ErrnoException so that\n * validate's per-target guard names the file without knowing this type; the\n * write path makes the same two tests for the same reasons (staging.ts's\n * `decodeUtf8`), and its messages differ only in saying what a rewrite would\n * additionally destroy, which is not what a reader needs to hear.\n */\nexport class NotUtf8DocumentError extends Error {\n  override readonly name = \"NotUtf8DocumentError\";\n\n  constructor(\n    readonly path: string,\n    reason: string,\n  ) {\n    super(\n      `${path} is not a UTF-8 text document — ${reason}. Read as UTF-8 its requirements, frontmatter and headings ` +\n        `all come out absent rather than wrong, so the file grades as an empty baseline instead of an unreadable one. ` +\n        `Nothing here was checked. Re-save it as UTF-8 (PowerShell's \\`>\\` and \\`Out-File\\` write UTF-16 unless told ` +\n        `otherwise: use \\`Out-File -Encoding utf8\\`), then re-run.`,\n    );\n  }\n}\n\n/**\n * Decode a document loam is about to parse, or refuse naming it.\n *\n * Two tests, because one is not enough. `isUtf8` catches the byte sequences\n * that cannot be UTF-8 at all — which is what a byte-order mark makes UTF-16\n * into, and PowerShell writes one. Without a BOM, UTF-16LE of ASCII is a\n * sequence of valid UTF-8 bytes: every other byte is NUL, which decodes to\n * U+0000 and nothing complains. That file parsed as zero requirements and no\n * frontmatter, and validated green. A NUL in a markdown document loam owns has\n * no legitimate spelling, so it is the second test.\n */\nexport function decodeDocument(bytes: Buffer, path: string): string {\n  if (!isUtf8(bytes)) throw new NotUtf8DocumentError(path, \"its bytes are not a valid UTF-8 sequence\");\n  const text = bytes.toString(\"utf8\");\n  if (text.includes(\"\\u0000\")) {\n    throw new NotUtf8DocumentError(\n      path,\n      \"it holds NUL characters, which no markdown document does — almost always UTF-16 saved without a byte-order mark\",\n    );\n  }\n  return text;\n}\n"]}

package/dist/core/kernel/fences.js

@@ -0,0 +1,42 @@
+/**
+ * Track ``` / ~~~ fences line by line — the one rule every markdown walk in the
+ * product has to agree on about what is structure and what is quoted text.
+ *
+ * It lived in `core/document/parse.ts` while that file was its only writer and
+ * `core/provenance/sample/sections.ts` its only borrower. It moved here when the
+ * fourth reader arrived and could not reach it: `core/vocabulary/steps.ts` needs
+ * the same rule to stop a pipe table inside a fenced payload from being hoisted
+ * out as a scenario's `Examples`, and `core/document/` already imports
+ * `core/vocabulary/` (through `document/scenarios.ts`), so an import the other
+ * way would close a package cycle the graph check forbids. AGENTS.md names this
+ * move explicitly: when a helper you need lives in a module heavier than the
+ * helper, move the helper out rather than importing the weight.
+ *
+ * `core/kernel/` is where it lands because it is the one package below every
+ * other — it imports nothing from `core/` at all, so nobody can create a cycle
+ * by depending on it.
+ *
+ * Returns true while the line is fenced content — INCLUDING the fence marker
+ * itself. Callers that need the markers back (an emitter reading a docstring out
+ * of a body, rather than a heading walk skipping over one) must track the
+ * transition themselves; this predicate deliberately answers one question.
+ *
+ * A closing marker must match the opener's character, so a ``` block quoting a
+ * ~~~ line stays open, which is what the markdown spec says and what stops a
+ * payload containing fence characters from ending its own block early.
+ */
+export function fenceTracker() {
+    let fence = null;
+    return (line) => {
+        const m = /^\s*(```|~~~)/.exec(line);
+        if (m) {
+            if (fence === null)
+                fence = m[1];
+            else if (fence === m[1])
+                fence = null;
+            return true;
+        }
+        return fence !== null;
+    };
+}
+//# sourceMappingURL=fences.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fences.js","sourceRoot":"","sources":["../../../src/core/kernel/fences.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,YAAY;IAC1B,IAAI,KAAK,GAAkB,IAAI,CAAC;IAChC,OAAO,CAAC,IAAI,EAAE,EAAE;QACd,MAAM,CAAC,GAAG,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACrC,IAAI,CAAC,EAAE,CAAC;YACN,IAAI,KAAK,KAAK,IAAI;gBAAE,KAAK,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC;iBAC7B,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,CAAE;gBAAE,KAAK,GAAG,IAAI,CAAC;YACvC,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,KAAK,KAAK,IAAI,CAAC;IACxB,CAAC,CAAC;AACJ,CAAC","sourcesContent":["/**\n * Track ``` / ~~~ fences line by line — the one rule every markdown walk in the\n * product has to agree on about what is structure and what is quoted text.\n *\n * It lived in `core/document/parse.ts` while that file was its only writer and\n * `core/provenance/sample/sections.ts` its only borrower. It moved here when the\n * fourth reader arrived and could not reach it: `core/vocabulary/steps.ts` needs\n * the same rule to stop a pipe table inside a fenced payload from being hoisted\n * out as a scenario's `Examples`, and `core/document/` already imports\n * `core/vocabulary/` (through `document/scenarios.ts`), so an import the other\n * way would close a package cycle the graph check forbids. AGENTS.md names this\n * move explicitly: when a helper you need lives in a module heavier than the\n * helper, move the helper out rather than importing the weight.\n *\n * `core/kernel/` is where it lands because it is the one package below every\n * other — it imports nothing from `core/` at all, so nobody can create a cycle\n * by depending on it.\n *\n * Returns true while the line is fenced content — INCLUDING the fence marker\n * itself. Callers that need the markers back (an emitter reading a docstring out\n * of a body, rather than a heading walk skipping over one) must track the\n * transition themselves; this predicate deliberately answers one question.\n *\n * A closing marker must match the opener's character, so a ``` block quoting a\n * ~~~ line stays open, which is what the markdown spec says and what stops a\n * payload containing fence characters from ending its own block early.\n */\nexport function fenceTracker(): (line: string) => boolean {\n  let fence: string | null = null;\n  return (line) => {\n    const m = /^\\s*(```|~~~)/.exec(line);\n    if (m) {\n      if (fence === null) fence = m[1]!;\n      else if (fence === m[1]!) fence = null;\n      return true;\n    }\n    return fence !== null;\n  };\n}\n"]}

package/dist/core/kernel/ids/capability.js

@@ -0,0 +1,72 @@
+/**
+ * The spelling rule for a capability id that ARRIVED FROM ARGV — the one
+ * provenance `repo/authored/paths.ts` says must never reach a path join unchecked.
+ *
+ * `livingCapabilityPaths` takes a plain `string`, and its comment states why: a
+ * capability id has no grammar of its own — it is a YAML key and a chain of
+ * directory names — so what holds that join is PROVENANCE. Every id it sees
+ * today came out of a `readCapabilityTree` walk, where each component is a
+ * `readdir` entry name and therefore demonstrably a directory that exists.
+ * (`featureCapabilityDeltasDir` beside it takes a branded `FeatureDir` and no
+ * capability id at all; the feature-side join is spelled by `loam new` itself.)
+ *
+ * `loam new --capability <id>` is the first caller with no such provenance. The
+ * string is whatever a person typed, and it is joined as
+ * `features/<dirName>/capabilities/<id>/spec.md` — so `--capability ../../evil`
+ * resolves to `features/evil/spec.md`, a directory `listFeatures` then
+ * enumerates as a feature, and one `..` further reaches the docs-repo root.
+ * `resolveInside` cannot refuse either: both are still inside the repo. That is
+ * the failure this module closes, and it is the same one
+ * `core/kernel/ids/service.ts` opens with one file over.
+ *
+ * IT IS THE DIRECTORY-NAME RULE, NOT A NEW ONE. Nesting is spelled by the tree
+ * (`payments/refunds` is two directories), so an id is legal exactly when every
+ * one of its `/`-separated segments is a legal directory name in the docs repo
+ * — `dirNameHazard`, the same check a service id and a subsystem name are held
+ * to, Windows device names and trailing dots included. A capability tree that
+ * only clones onto some of the machines that read it is the same defect there
+ * as it is under `services/`.
+ *
+ * NO BRAND, deliberately, and the reason is the provenance rule above rather
+ * than an omission: a brand is worth its annotations when a path builder can
+ * DEMAND it, and neither builder can — both are called with walk-derived ids
+ * that were never parsed here and must keep working. What this module gives is
+ * the check the argv path owes; the rule that walk-derived ids are safe stays
+ * where `repo/paths.ts` already writes it down.
+ */
+import { dirNameHazard } from "./service.js";
+/** Prose form of the rule, shown verbatim in the refusal so the fix is obvious. */
+const CAPABILITY_ID_RULE = "a capability id is one or more '/'-separated segments, each starting with a letter or digit and " +
+    "containing only letters, digits, '.', '_' or '-' (no '..', no spaces, no leading or trailing '/') — " +
+    "it becomes the capabilities/<id>/ directory chain, one directory per segment";
+/**
+ * Why `id` cannot be a capability id, or null when it can.
+ *
+ * A sentence rather than a boolean, matching `serviceIdProblem`: a caller that
+ * is collecting findings prints exactly what a refusal would.
+ */
+export function capabilityIdProblem(id, label = "--capability") {
+    if (typeof id !== "string" || id === "") {
+        return `${label} must name a capability: ${CAPABILITY_ID_RULE}.`;
+    }
+    for (const segment of id.split("/")) {
+        const hazard = dirNameHazard(segment);
+        if (hazard === null)
+            continue;
+        switch (hazard.kind) {
+            case "grammar":
+                return `Invalid ${label} '${id}': ${CAPABILITY_ID_RULE}.`;
+            // Both Windows refusals keep their own sentence for `serviceIdProblem`'s
+            // reason: "does not match the grammar" is true and useless, because the
+            // id LOOKS fine and the problem is what the filesystem does with it.
+            case "windows-device":
+                return (`Invalid ${label} '${id}': '${hazard.stem}' is a reserved device name on Windows — ` +
+                    `the capabilities/${id}/ directory cannot be created there at all, so the docs repo would only work on some of the machines that clone it.`);
+            case "windows-trailing":
+                return (`Invalid ${label} '${id}': no segment of a capability id may end with '.' or a space — ` +
+                    "Windows strips both when creating a directory, so the id would silently name one directory there and another everywhere else.");
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=capability.js.map

package/dist/core/kernel/ids/capability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.js","sourceRoot":"","sources":["../../../../src/core/kernel/ids/capability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,mFAAmF;AACnF,MAAM,kBAAkB,GACtB,kGAAkG;IAClG,sGAAsG;IACtG,8EAA8E,CAAC;AAEjF;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,EAAW,EAAE,KAAK,GAAG,cAAc;IACrE,IAAI,OAAO,EAAE,KAAK,QAAQ,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACxC,OAAO,GAAG,KAAK,4BAA4B,kBAAkB,GAAG,CAAC;IACnE,CAAC;IACD,KAAK,MAAM,OAAO,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACpC,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;QACtC,IAAI,MAAM,KAAK,IAAI;YAAE,SAAS;QAC9B,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;YACpB,KAAK,SAAS;gBACZ,OAAO,WAAW,KAAK,KAAK,EAAE,MAAM,kBAAkB,GAAG,CAAC;YAC5D,yEAAyE;YACzE,wEAAwE;YACxE,qEAAqE;YACrE,KAAK,gBAAgB;gBACnB,OAAO,CACL,WAAW,KAAK,KAAK,EAAE,OAAO,MAAM,CAAC,IAAI,2CAA2C;oBACpF,oBAAoB,EAAE,qHAAqH,CAC5I,CAAC;YACJ,KAAK,kBAAkB;gBACrB,OAAO,CACL,WAAW,KAAK,KAAK,EAAE,iEAAiE;oBACxF,+HAA+H,CAChI,CAAC;QACN,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC","sourcesContent":["/**\n * The spelling rule for a capability id that ARRIVED FROM ARGV — the one\n * provenance `repo/authored/paths.ts` says must never reach a path join unchecked.\n *\n * `livingCapabilityPaths` takes a plain `string`, and its comment states why: a\n * capability id has no grammar of its own — it is a YAML key and a chain of\n * directory names — so what holds that join is PROVENANCE. Every id it sees\n * today came out of a `readCapabilityTree` walk, where each component is a\n * `readdir` entry name and therefore demonstrably a directory that exists.\n * (`featureCapabilityDeltasDir` beside it takes a branded `FeatureDir` and no\n * capability id at all; the feature-side join is spelled by `loam new` itself.)\n *\n * `loam new --capability <id>` is the first caller with no such provenance. The\n * string is whatever a person typed, and it is joined as\n * `features/<dirName>/capabilities/<id>/spec.md` — so `--capability ../../evil`\n * resolves to `features/evil/spec.md`, a directory `listFeatures` then\n * enumerates as a feature, and one `..` further reaches the docs-repo root.\n * `resolveInside` cannot refuse either: both are still inside the repo. That is\n * the failure this module closes, and it is the same one\n * `core/kernel/ids/service.ts` opens with one file over.\n *\n * IT IS THE DIRECTORY-NAME RULE, NOT A NEW ONE. Nesting is spelled by the tree\n * (`payments/refunds` is two directories), so an id is legal exactly when every\n * one of its `/`-separated segments is a legal directory name in the docs repo\n * — `dirNameHazard`, the same check a service id and a subsystem name are held\n * to, Windows device names and trailing dots included. A capability tree that\n * only clones onto some of the machines that read it is the same defect there\n * as it is under `services/`.\n *\n * NO BRAND, deliberately, and the reason is the provenance rule above rather\n * than an omission: a brand is worth its annotations when a path builder can\n * DEMAND it, and neither builder can — both are called with walk-derived ids\n * that were never parsed here and must keep working. What this module gives is\n * the check the argv path owes; the rule that walk-derived ids are safe stays\n * where `repo/paths.ts` already writes it down.\n */\nimport { dirNameHazard } from \"./service.js\";\n\n/** Prose form of the rule, shown verbatim in the refusal so the fix is obvious. */\nconst CAPABILITY_ID_RULE =\n  \"a capability id is one or more '/'-separated segments, each starting with a letter or digit and \" +\n  \"containing only letters, digits, '.', '_' or '-' (no '..', no spaces, no leading or trailing '/') — \" +\n  \"it becomes the capabilities/<id>/ directory chain, one directory per segment\";\n\n/**\n * Why `id` cannot be a capability id, or null when it can.\n *\n * A sentence rather than a boolean, matching `serviceIdProblem`: a caller that\n * is collecting findings prints exactly what a refusal would.\n */\nexport function capabilityIdProblem(id: unknown, label = \"--capability\"): string | null {\n  if (typeof id !== \"string\" || id === \"\") {\n    return `${label} must name a capability: ${CAPABILITY_ID_RULE}.`;\n  }\n  for (const segment of id.split(\"/\")) {\n    const hazard = dirNameHazard(segment);\n    if (hazard === null) continue;\n    switch (hazard.kind) {\n      case \"grammar\":\n        return `Invalid ${label} '${id}': ${CAPABILITY_ID_RULE}.`;\n      // Both Windows refusals keep their own sentence for `serviceIdProblem`'s\n      // reason: \"does not match the grammar\" is true and useless, because the\n      // id LOOKS fine and the problem is what the filesystem does with it.\n      case \"windows-device\":\n        return (\n          `Invalid ${label} '${id}': '${hazard.stem}' is a reserved device name on Windows — ` +\n          `the capabilities/${id}/ directory cannot be created there at all, so the docs repo would only work on some of the machines that clone it.`\n        );\n      case \"windows-trailing\":\n        return (\n          `Invalid ${label} '${id}': no segment of a capability id may end with '.' or a space — ` +\n          \"Windows strips both when creating a directory, so the id would silently name one directory there and another everywhere else.\"\n        );\n    }\n  }\n  return null;\n}\n"]}

package/dist/core/kernel/ids/dirs.js

@@ -0,0 +1,33 @@
+/** The only constructor. `resolved` must carry `DocsDir`'s provenance, above. */
+export function docsDirOf(resolved) {
+    return resolved;
+}
+/** The only constructor. `abs` must carry `FeatureDir`'s provenance, above. */
+export function featureDirOf(abs) {
+    return abs;
+}
+/** The only constructor. `abs` must carry one of `ServiceDir`'s two provenances, above. */
+export function serviceDirOf(abs) {
+    return abs;
+}
+/**
+ * Where a service sits under `services/`, repo-relative and spelled from its
+ * own placement chain — `services/<subsystem>/…/<id>/` for a filed service,
+ * `services/<id>/` for an unfiled one.
+ *
+ * The join it replaces is `services/${id}`, which is right for an unfiled
+ * service and WRONG for every filed one, and the failure is the kind a reader
+ * cannot diagnose: the message names a directory that does not exist, so the
+ * fix goes to the wrong place, or a `cd` simply fails. Three findings already
+ * spelled it correctly by hand and `loam status` spelled it by id; this exists
+ * so the rule has one implementation rather than a convention.
+ *
+ * DISPLAY only, and not a `ServiceDir`: it is repo-relative text for a human
+ * to read, while `ServiceDir` is the absolute path artifacts resolve from. And
+ * `subsystem` is placement carrying no identity, so nothing here may be joined
+ * on — the id is the identity, at whatever depth it lives.
+ */
+export function serviceTreePath(s) {
+    return ["services", ...s.subsystem, s.id].join("/");
+}
+//# sourceMappingURL=dirs.js.map

package/dist/core/kernel/ids/dirs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dirs.js","sourceRoot":"","sources":["../../../../src/core/kernel/ids/dirs.ts"],"names":[],"mappings":"AAwDA,iFAAiF;AACjF,MAAM,UAAU,SAAS,CAAC,QAAgB;IACxC,OAAO,QAAmB,CAAC;AAC7B,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,OAAO,GAAiB,CAAC;AAC3B,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,OAAO,GAAiB,CAAC;AAC3B,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,eAAe,CAAC,CAAsC;IACpE,OAAO,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACtD,CAAC","sourcesContent":["/**\n * The two directory roots loam's path builders spell paths under, branded by\n * PROVENANCE — where the string came from — exactly as the id brands beside\n * this file are.\n *\n * `repo/paths.ts` interpolates caller-controlled ids into these roots, and its\n * guarantee is only as good as the root it starts from: an\n * `unfiledServicePaths(dir, id)` whose `dir` is whatever string happened to\n * be in scope spells paths\n * into whatever tree that string names. Honestly stated: these constructors\n * VALIDATE nothing — they RECORD a provenance the caller must already have\n * established, and what the gate contributes is that the cast appears in\n * exactly one place per brand (a cast anywhere else in `src/` is a finding,\n * not a shortcut). `init` brands its `--docs` resolution before its guards\n * run and refuses before any path is built — the provenance comment is the\n * contract those call sites are held to by review, not by the compiler.\n *\n * The two brands are deliberately disjoint: a docs repo root and a feature\n * directory are different trees, and `featurePaths(docsDir)` is precisely the\n * confusion the compiler should refuse.\n */\ndeclare const provenance: unique symbol;\n\n/**\n * The resolved absolute root of the shared docs repo. Provenance: resolved\n * through a loaded config (`parseConfig` resolves the stored spelling against\n * the config file's own directory) or an explicit `--docs` a command\n * validated. NOT the stored spelling — loam.json deliberately keeps the\n * relative form (`storedDocsDir`), and that spelling stays a plain `string`.\n */\nexport type DocsDir = string & { readonly [provenance]: \"docs-dir\" };\n\n/**\n * The absolute path of one feature's directory. Provenance: an enumeration\n * read this directory — `listFeatures` joined a name `readdir` returned onto\n * the features root it walked, so the directory demonstrably exists (or did,\n * one readdir ago).\n */\nexport type FeatureDir = string & { readonly [provenance]: \"feature-dir\" };\n\n/**\n * The absolute path of one service's directory — the value the artifact paths\n * in `repo/paths.ts` are spelled under. Two provenances, both stated because\n * both are load-bearing: the tree walk read it (`core/repo/tree/walk.ts`\n * joined a name `readdir` returned onto the directory it was listed under, at\n * whatever depth the service actually lives), or it is the canonical UNFILED\n * spelling `<docsDir>/services/<id>/` that `unfiledServicePaths` builds from a\n * validated id and a `DocsDir` — the one place creation lands, and the honest\n * fallback for a service the enumeration does not answer. A path from a\n * readdir is NARROWER than one built from a validated string: the directory\n * demonstrably exists where the path says. Nothing else may construct this —\n * in particular not a bare `join(docsDir, \"services\", name)` at a call site,\n * which is exactly the root-level assumption the subsystem tree retired.\n */\nexport type ServiceDir = string & { readonly [provenance]: \"service-dir\" };\n\n/** The only constructor. `resolved` must carry `DocsDir`'s provenance, above. */\nexport function docsDirOf(resolved: string): DocsDir {\n  return resolved as DocsDir;\n}\n\n/** The only constructor. `abs` must carry `FeatureDir`'s provenance, above. */\nexport function featureDirOf(abs: string): FeatureDir {\n  return abs as FeatureDir;\n}\n\n/** The only constructor. `abs` must carry one of `ServiceDir`'s two provenances, above. */\nexport function serviceDirOf(abs: string): ServiceDir {\n  return abs as ServiceDir;\n}\n\n/**\n * Where a service sits under `services/`, repo-relative and spelled from its\n * own placement chain — `services/<subsystem>/…/<id>/` for a filed service,\n * `services/<id>/` for an unfiled one.\n *\n * The join it replaces is `services/${id}`, which is right for an unfiled\n * service and WRONG for every filed one, and the failure is the kind a reader\n * cannot diagnose: the message names a directory that does not exist, so the\n * fix goes to the wrong place, or a `cd` simply fails. Three findings already\n * spelled it correctly by hand and `loam status` spelled it by id; this exists\n * so the rule has one implementation rather than a convention.\n *\n * DISPLAY only, and not a `ServiceDir`: it is repo-relative text for a human\n * to read, while `ServiceDir` is the absolute path artifacts resolve from. And\n * `subsystem` is placement carrying no identity, so nothing here may be joined\n * on — the id is the identity, at whatever depth it lives.\n */\nexport function serviceTreePath(s: { id: string; subsystem: string[] }): string {\n  return [\"services\", ...s.subsystem, s.id].join(\"/\");\n}\n"]}