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

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

@@ -0,0 +1 @@
+{"version":3,"file":"catalogue.js","sourceRoot":"","sources":["../../../../src/core/gherkin/steps/catalogue.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The step catalogue: which phrases somebody has DECIDED the suite defines.\n *\n * ## The decision this file records, because it was the open question\n *\n * `./inventory.ts` answers how many definitions a suite needs. It stops there on\n * purpose — no file, no finding, no stable code — and the gap it leaves is the\n * next ARTIFACT, not the next warning: a team reads the report, writes the glue\n * by hand, and nothing anywhere records which phrases now have definitions, so\n * the report is recomputed from scratch every time instead of diffed against a\n * decision somebody made.\n *\n * The catalogue is **AUTHORED**, not emitted, and it lives in the DOCS repo at\n * `services/<svc>/steps.yaml`. Four things decided it:\n *\n *  - It is a DECISION, not an observation. loam does not read code and must\n *    never present a derived thing as truth (the non-goal is written down); what\n *    a team can say is \"these are the phrases we have agreed to define\", and\n *    that sentence is an authored document by construction. An emitted\n *    catalogue would have to be derived from a step registry loam cannot read.\n *  - `loam steps` NEEDS NO SERVICE REPO to stand in — that is its own stated\n *    design, and it reads the living specs rather than the emitted `.feature`\n *    files precisely so it answers the same way in a repo that has never run\n *    `loam gherkin`. A catalogue in the service repo would make the comparison\n *    require one, which is a different command.\n *  - The shape rule the glossary and capability trees already settled: an entry\n *    with prose gets a file, an entry WITHOUT prose stays a line in YAML. A\n *    catalogue entry is a phrase and nothing else, so it is a line in YAML — the\n *    same side of that rule `architecture/capabilities.yaml` and\n *    `permissions.yaml` sit on.\n *  - Nothing generated may land inside `<gherkinDir>/loam/`, which `loam\n *    gherkin` owns and overwrites wholesale. Living in the docs repo satisfies\n *    that by construction rather than by a rule somebody has to remember.\n *\n * SERVICE-SCOPED, beside `health.yaml`, because a step registry belongs to one\n * suite and a suite belongs to one service. A fleet-level catalogue would claim\n * one registry across services that do not share a test runner.\n *\n * ## What it does NOT do, and this is the other half of the decision\n *\n * **It gains no stable code, and `loam validate` never reads it.** A phrase\n * written but not catalogued is a work-list row, not a breach: writing a spec\n * ahead of the glue is the normal order, and a check that fires on it is the\n * kind a fleet turns off — at which point the real findings beside it are turned\n * off too. The near-duplicate groups stay a report for the same reason. So this\n * axis costs one document kind and zero codes, and everything it produces is\n * columns in `loam steps`.\n *\n * **It claims nothing about whether the glue exists.** A catalogued phrase is a\n * phrase somebody said they would define; loam cannot see a step registry and\n * does not pretend to. The two columns are named for what they actually mean —\n * written-not-catalogued and catalogued-not-written — and neither says \"missing\n * definition\".\n *\n * ## The grammar\n *\n * ```yaml\n * steps:\n *   - a payment of 100.00\n *   - Given it is split 60/40\n * ```\n *\n * A list of step TEXTS, not of keys. The key is loam's own spelling — `{n}`,\n * `{s}`, `{p}` collapse, keyword stripped (`./phrase.ts`) — and asking an author\n * to write it would make an internal normalisation a hand-typed contract, where\n * one wrong brace silently catalogues nothing. So an entry is written the way a\n * step is written, with or without its keyword, and loam keys it the same way it\n * keys the written steps it is being compared against. Two entries that collapse\n * onto one key are reported as such rather than merged: that is the author\n * cataloguing one definition twice, which is exactly what the near-duplicate\n * report exists to surface.\n */\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { parse as parseYaml } from \"yaml\";\nimport { isRecord } from \"../../kernel/records.js\";\nimport { compareIds } from \"../../repo/entries.js\";\nimport { phraseOf } from \"./phrase.js\";\nimport { type StepInventory } from \"./inventory.js\";\n\n/** One catalogued phrase: what the author wrote, and the key loam derived from it. */\nexport interface CatalogueEntry {\n  /** The entry exactly as `steps.yaml` spells it. */\n  text: string;\n  /** The normalized phrase — the same key `./inventory.ts` gives a written step. */\n  key: string;\n}\n\n/** What `services/<svc>/steps.yaml` says, or the honest refusal to say. */\nexport interface StepCatalogue {\n  /** False when the service has no `steps.yaml` — which is every service until one opts in. */\n  present: boolean;\n  /**\n   * Why the file could not be read, when it exists and does not parse as the\n   * grammar above. A REASON rather than a boolean, because the report prints it:\n   * \"could not look\" is only useful if it says what stopped it.\n   */\n  unreadable?: string;\n  /** The catalogued entries, in the order the file lists them. */\n  entries: CatalogueEntry[];\n}\n\nconst ABSENT: StepCatalogue = { present: false, entries: [] };\n\n/**\n * Read one service's catalogue.\n *\n * A missing file is silence, not an error: the axis's opt-in is the file's\n * existence, exactly as `capabilities/`'s is a directory's. Anything present and\n * unparseable is `unreadable` with the reason — never an empty catalogue, which\n * would report every written phrase as uncatalogued and read as a work-list\n * somebody has to do.\n */\nexport async function readStepCatalogue(path: string): Promise<StepCatalogue> {\n  if (!existsSync(path)) return ABSENT;\n  let doc: unknown;\n  try {\n    doc = parseYaml(await readFile(path, \"utf8\"));\n  } catch (e) {\n    return { present: true, entries: [], unreadable: e instanceof Error ? e.message : String(e) };\n  }\n  if (doc === null || doc === undefined) return { present: true, entries: [] };\n  if (!isRecord(doc)) return { present: true, entries: [], unreadable: \"the document is not a mapping\" };\n  const block = doc[\"steps\"];\n  if (block === undefined) return { present: true, entries: [] };\n  if (!Array.isArray(block)) {\n    return { present: true, entries: [], unreadable: \"`steps` is not a list of step texts\" };\n  }\n  const entries: CatalogueEntry[] = [];\n  for (const item of block) {\n    // A non-string entry refuses the whole file rather than being skipped. A\n    // skipped entry is a phrase silently absent from the catalogue, which prints\n    // as \"written but not catalogued\" — a work-list row invented by a shape\n    // error, which is the wrong answer this fails closed to avoid.\n    if (typeof item !== \"string\") {\n      return { present: true, entries: [], unreadable: \"every `steps` entry must be a step text (a string)\" };\n    }\n    entries.push({ text: item, key: phraseOf(item).key });\n  }\n  return { present: true, entries };\n}\n\n/** The two lists a report needs, plus the entries an author catalogued twice. */\nexport interface CatalogueComparison {\n  /** Written phrase keys the catalogue does not list, most-used first — the work-list. */\n  uncatalogued: string[];\n  /** Catalogued keys nothing in the living specs writes — a definition with nothing to match. */\n  unwritten: string[];\n  /** Keys two or more catalogue entries collapse onto, with every spelling. */\n  duplicated: Array<{ key: string; texts: string[] }>;\n}\n\n/**\n * Written phrases against catalogued ones.\n *\n * ORDER IS THE INVENTORY'S for `uncatalogued` — `inv.phrases` is already sorted\n * count-descending then key-ascending, so the work-list comes out with the\n * phrase that pays back most first, and stays diffable. `unwritten` and\n * `duplicated` have no count to sort on and are sorted by key.\n *\n * The catalogue's own `present`/`unreadable` state is NOT consulted here: this\n * is the comparison, and whether it was worth making is the caller's question.\n * Handing it an unreadable catalogue would produce a full `uncatalogued` list\n * that reads exactly like a real work-list, which is why the caller checks first.\n */\nexport function compareToCatalogue(inv: StepInventory, catalogue: StepCatalogue): CatalogueComparison {\n  const catalogued = new Set(catalogue.entries.map((e) => e.key));\n  const written = new Set(inv.phrases.map((p) => p.key));\n  const bySpelling = new Map<string, string[]>();\n  for (const entry of catalogue.entries) {\n    const texts = bySpelling.get(entry.key) ?? [];\n    texts.push(entry.text);\n    bySpelling.set(entry.key, texts);\n  }\n  return {\n    uncatalogued: inv.phrases.filter((p) => !catalogued.has(p.key)).map((p) => p.key),\n    unwritten: [...catalogued].filter((key) => !written.has(key)).sort(compareIds),\n    duplicated: [...bySpelling]\n      .filter(([, texts]) => texts.length > 1)\n      .map(([key, texts]) => ({ key, texts }))\n      .sort((a, b) => compareIds(a.key, b.key)),\n  };\n}\n"]}

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

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

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,109 @@
+/**
+ * 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 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);
+    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;;;;;;;;;;;;;;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

@@ -0,0 +1,73 @@
+/**
+ * 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 } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { compareIds } from "../repo/entries.js";
+import { entryIs, markDescended } 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
+ * (`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) {
+    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 (!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))) {
+        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);
+    }
+}
+//# 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 } 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/{concurrency.js → 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

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