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

package/dist/core/document/spec.js

@@ -0,0 +1,234 @@
+/**
+ * What a requirement IS, what makes one the same requirement twice, and the one
+ * canonical way it is written back out.
+ *
+ * Living specs use `## Requirements` with `### Requirement:` + `#### Scenario:`.
+ * Feature deltas group requirements under `## ADDED|MODIFIED|REMOVED
+ * Requirements`. Scenarios are the acceptance criteria (Given/When/Then) and
+ * the source for tests.
+ *
+ * Identity and serialization cannot be separated here: `requirementDigest` is
+ * defined AS the sha256 of the serialized requirement without its baseline, so
+ * a second module owning the writer would mean the digest and the bytes it
+ * claims to describe could disagree. `./parse.ts` turns markdown into these,
+ * `./apply.ts` folds a delta into a living set of them.
+ */
+import { createHash } from "node:crypto";
+export const KIND_RE = /^##\s+(ADDED|MODIFIED|REMOVED)\s+Requirements\s*$/i;
+export const REQUIREMENT_ID_LINE_RE = /^\s*Requirement-ID:\s*(.*?)\s*$/i;
+export const BASED_ON_LINE_RE = /^\s*Based-On:\s*(.*?)\s*$/i;
+/**
+ * The `Capability:` body line (also accepted: `Capabilities:`), exactly as the
+ * parser reads it — `./parse.ts` consumes the capture, migrate-openspec's
+ * materializer tests presence with it before appending its own line. One
+ * spelling on purpose: two copies of a grammar is how a "presence" test and
+ * the parse quietly stop agreeing about what counts as the line.
+ */
+export const CAPABILITY_LINE_RE = /^\s*Capabilit(?:y|ies):\s*(.+?)\s*$/i;
+/**
+ * The `Realizes:` body line. One spelling only — no `Realize:` singular
+ * alternative, unlike `Operations?:` and the rest — because the verb already
+ * reads correctly for one entry and for six, and the plural forms in the older
+ * lines exist to forgive a NOUN that changes shape. A grammar with an
+ * alternative nobody needs is one more thing two readers can disagree about.
+ */
+export const REALIZES_LINE_RE = /^\s*Realizes:\s*(.+?)\s*$/i;
+/**
+ * The separator between a `Realizes:` target and the digest of the capability
+ * requirement it was written against — `checkout#CHK-1@9f2c1a4b`.
+ *
+ * `@` and not a second `#`, because the two halves are read by different rules:
+ * `splitRealizesEntry` takes the LAST `#` to find the requirement half, so a
+ * second one would move that boundary and re-parse every existing entry. `@`
+ * is also excluded from `REQUIREMENT_ID_RE`, which is what makes the split
+ * unambiguous rather than a convention — an id can never contain one.
+ *
+ * NOBODY TYPES THIS. `loam rebase --living` writes it and rewrites it; a human
+ * writes `Realizes: checkout#CHK-1` and is never asked for more. An entry
+ * without a pin is not a defect and never becomes one — it is a claim that has
+ * not been pinned yet, and it grades exactly as it did before pins existed.
+ */
+export const REALIZES_PIN_SEPARATOR = "@";
+/**
+ * One `Realizes:` entry split into the target it names and the digest it was
+ * written against, or `pin: null` when it carries none.
+ *
+ * A suffix that is not a well-formed digest is NOT a pin and NOT a refusal:
+ * the whole entry stays the target, so `checkout#CHK-1@nonsense` resolves — or
+ * fails to resolve — exactly as it would have before, under
+ * `capability.realizes-unknown`, whose message names the entry the author
+ * actually typed. Inventing a second refusal for one mistake is the failure
+ * `splitRealizesEntry` already refuses two lines up.
+ */
+export function splitRealizesPin(entry) {
+    const at = entry.lastIndexOf(REALIZES_PIN_SEPARATOR);
+    if (at <= 0)
+        return { target: entry, pin: null };
+    const suffix = entry.slice(at + 1);
+    if (!REQUIREMENT_DIGEST_RE.test(suffix))
+        return { target: entry, pin: null };
+    return { target: entry.slice(0, at), pin: suffix };
+}
+/** Portable, review-friendly stable IDs. Case-sensitive by design. */
+export const REQUIREMENT_ID_RE = /^[A-Za-z][A-Za-z0-9._-]{0,127}$/;
+/**
+ * How much of the sha256 a `Based-On:` line carries — the length
+ * `sources_digest` already uses (core/provenance/stamp.ts), for one reason a reader
+ * can hold: every digest loam writes into a document reads the same.
+ */
+export const REQUIREMENT_DIGEST_LENGTH = 16;
+/** The value shape of a `Based-On:` line, exactly as `requirementDigest` writes it. */
+export const REQUIREMENT_DIGEST_RE = new RegExp(`^[0-9a-f]{${REQUIREMENT_DIGEST_LENGTH}}$`);
+/** Every authored Requirement-ID value in a requirement body, including blanks. */
+export function requirementIdDeclarations(requirement) {
+    return requirement.text.flatMap((line) => {
+        const match = REQUIREMENT_ID_LINE_RE.exec(line);
+        return match === null ? [] : [match[1].trim()];
+    });
+}
+/** Structural ID problems within one spec/delta document. */
+export function requirementIdProblems(reqs) {
+    const problems = [];
+    const owners = new Map();
+    for (const requirement of reqs) {
+        const declarations = requirementIdDeclarations(requirement);
+        const values = declarations.length > 0
+            ? declarations
+            : requirement.id === undefined
+                ? []
+                : [requirement.id];
+        if (declarations.length > 1) {
+            problems.push({ kind: "repeated", requirement: requirement.name, values: declarations });
+        }
+        for (const value of values) {
+            if (!REQUIREMENT_ID_RE.test(value)) {
+                problems.push({ kind: "invalid", requirement: requirement.name, value });
+            }
+        }
+        // A repeated declaration is already an error. Do not also pretend its
+        // keep-last parse result is an unambiguous document identity.
+        if (values.length !== 1 || !REQUIREMENT_ID_RE.test(values[0]))
+            continue;
+        const names = owners.get(values[0]) ?? [];
+        names.push(requirement.name);
+        owners.set(values[0], names);
+    }
+    for (const [id, requirements] of owners) {
+        if (requirements.length > 1)
+            problems.push({ kind: "duplicate", id, requirements });
+    }
+    return problems;
+}
+/** Every authored `Based-On:` value in a requirement body, including blanks. */
+export function basedOnDeclarations(requirement) {
+    return requirement.text.flatMap((line) => {
+        const match = BASED_ON_LINE_RE.exec(line);
+        return match === null ? [] : [match[1].trim()];
+    });
+}
+/**
+ * The requirement without its baseline marker — what a digest is taken over,
+ * and what archive merges into the living document.
+ *
+ * `Based-On:` is a statement ABOUT a delta ("this was written against that"),
+ * never part of the requirement it describes, and both consequences of
+ * forgetting that are bad. Left in the digest input, a requirement's digest
+ * would depend on the pin pointing at it, so no baseline could ever be
+ * self-consistent. Left in the merged text — `applyRequirementDelta` copies the
+ * delta's body into living wholesale — the living document would grow a pin to
+ * a version of itself, and the NEXT feature's baseline would be taken over a
+ * document containing the previous feature's bookkeeping.
+ */
+export function withoutBaseline(requirement) {
+    const { basedOn: _dropped, ...rest } = requirement;
+    return { ...rest, text: requirement.text.filter((line) => !BASED_ON_LINE_RE.test(line)) };
+}
+/**
+ * The requirement with every `Realizes:` pin stripped back to its bare target —
+ * the second thing a digest is taken over, for the same reason as the first.
+ *
+ * `withoutBaseline`'s argument, one axis over: a pin is a statement ABOUT a
+ * join ("this claim was written against that version of the promise"), never
+ * part of the requirement making the claim. Left in the digest input it would
+ * make re-pinning a content change, so every requirement realizing a capability
+ * would go stale against ITS OWN consumers the moment the capability moved —
+ * one edit cascading through the corpus, which is the failure the pin exists to
+ * report rather than to cause.
+ *
+ * The line is kept and only the suffix removed, unlike `withoutBaseline` which
+ * drops the whole line: the target ids ARE content, and a requirement that
+ * stops naming the promise it keeps is a different requirement.
+ */
+export function withoutRealizesPins(requirement) {
+    return {
+        ...requirement,
+        text: requirement.text.map((line) => {
+            const match = REALIZES_LINE_RE.exec(line);
+            if (match === null)
+                return line;
+            const bare = match[1]
+                .split(",")
+                .map((entry) => splitRealizesPin(entry.trim()).target)
+                .join(", ");
+            return line.replace(match[1], bare);
+        }),
+    };
+}
+/**
+ * The identity of a requirement's CONTENT: sha256 over its canonical
+ * serialization, truncated like every other digest loam stamps.
+ *
+ * Canonical, not raw bytes, and deliberately: archive writes every requirement
+ * a delta adds or replaces through `serializeRequirements`, so hashing bytes
+ * would make a baseline go stale over reflowed blank lines — a false alarm on
+ * the one check whose whole value is that it only fires when something moved.
+ * What the hash therefore covers is exactly what survives a round trip: the
+ * heading, the body (`Requirement-ID:` and `Operations:`/`Covers:` lines
+ * included), and every scenario with its Given/When/Then lines. `kind` and
+ * `section` are not serialized and so are not hashed — a requirement does not
+ * change because the document quoting it moved it under another heading.
+ *
+ * The two normalizations are the two kinds of bookkeeping a requirement can
+ * carry about its own joins — the baseline pointing AT it, and the `Realizes:`
+ * pins pointing OUT of it. Both are stripped for the same reason: a digest that
+ * moved when bookkeeping moved would make every pin self-invalidating.
+ */
+export function requirementDigest(requirement) {
+    return createHash("sha256")
+        .update(serializeRequirements([withoutRealizesPins(withoutBaseline(requirement))]), "utf8")
+        .digest("hex")
+        .slice(0, REQUIREMENT_DIGEST_LENGTH);
+}
+/** Serialize requirements back to OpenSpec markdown (`### Requirement:` + `#### Scenario:`). */
+export function serializeRequirements(reqs) {
+    // Framing (blank lines between sections) is normalized here; body content is
+    // only edge-trimmed, never collapsed — blank lines inside a scenario (e.g. in
+    // fenced code blocks) are verbatim content.
+    const chunks = [];
+    for (const r of reqs) {
+        const chunk = [`### Requirement: ${r.name}`];
+        const body = [...r.text];
+        // Parsed documents already carry the authored line in `text`. This branch
+        // also makes programmatically constructed Requirements serialize fully.
+        if (r.id !== undefined && !body.some((line) => REQUIREMENT_ID_LINE_RE.test(line))) {
+            body.unshift(`Requirement-ID: ${r.id}`);
+        }
+        // Directly under the identity it pins, which is where `loam rebase` writes
+        // it too — the two lines are read together, so they are never apart.
+        if (r.basedOn !== undefined && !body.some((line) => BASED_ON_LINE_RE.test(line))) {
+            body.splice(body.findIndex((line) => REQUIREMENT_ID_LINE_RE.test(line)) + 1, 0, `Based-On: ${r.basedOn}`);
+        }
+        const text = body.join("\n").trim();
+        if (text)
+            chunk.push("", text);
+        for (const s of r.scenarios) {
+            chunk.push("", `#### Scenario: ${s.name}`);
+            const body = s.lines.join("\n").trim();
+            if (body)
+                chunk.push(body);
+        }
+        chunks.push(chunk.join("\n"));
+    }
+    return chunks.join("\n\n").trim() + "\n";
+}
+//# sourceMappingURL=spec.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"spec.js","sourceRoot":"","sources":["../../../src/core/document/spec.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What a requirement IS, what makes one the same requirement twice, and the one\n * canonical way it is written back out.\n *\n * Living specs use `## Requirements` with `### Requirement:` + `#### Scenario:`.\n * Feature deltas group requirements under `## ADDED|MODIFIED|REMOVED\n * Requirements`. Scenarios are the acceptance criteria (Given/When/Then) and\n * the source for tests.\n *\n * Identity and serialization cannot be separated here: `requirementDigest` is\n * defined AS the sha256 of the serialized requirement without its baseline, so\n * a second module owning the writer would mean the digest and the bytes it\n * claims to describe could disagree. `./parse.ts` turns markdown into these,\n * `./apply.ts` folds a delta into a living set of them.\n */\nimport { createHash } from \"node:crypto\";\n\nexport type DeltaKind = \"ADDED\" | \"MODIFIED\" | \"REMOVED\" | \"BASE\";\n\nexport interface Scenario {\n  name: string;\n  lines: string[];\n  /**\n   * 1-based line of this scenario's `#### Scenario:` heading in its source document\n   * — `Requirement.line` one level down, so body line `lines[i]` sits at `line + 1 + i`.\n   *\n   * NOT part of identity, and that is load-bearing: `serializeRequirements` writes a\n   * scenario from `name` and `lines` alone and `requirementDigest` is the hash OF that\n   * serialization, so recording a position moves no digest and no living `Based-On:`\n   * pin goes stale because the parser learned to count lines.\n   */\n  line?: number;\n}\n\nexport interface Requirement {\n  /** BASE for a living spec; ADDED/MODIFIED/REMOVED inside a feature delta. */\n  kind: DeltaKind;\n  /**\n   * Stable identity from a `Requirement-ID:` body line. Optional so existing\n   * OpenSpec-compatible documents continue to use their heading as identity.\n   */\n  id?: string;\n  /**\n   * The living requirement this delta was WRITTEN AGAINST, from a `Based-On:`\n   * body line — `requirementDigest` of that requirement at authoring time.\n   *\n   * Delta-only, and meaningful on MODIFIED/REMOVED alone: those two address a\n   * requirement that already exists, and a MODIFIED carries its full new text,\n   * so archive does not merge the living wording — it REPLACES it. Two features\n   * rewriting one requirement therefore lose the loser's text outright, and the\n   * in-flight warning (`delta.modified-conflict`) cannot see the case that\n   * actually happens: once the first archives it leaves `changes/`, the second\n   * goes green again, and its stale text lands on top without a word. This is\n   * the pin that closes that window — the same trick as `sources_digest`\n   * (core/provenance/stamp.ts), one requirement wide.\n   *\n   * Absent on requirements adopted from OpenSpec, which never had the line;\n   * those keep the older, weaker protection and are told so once (warn).\n   */\n  basedOn?: string;\n  name: string;\n  text: string[];\n  /** OpenAPI operationIds this requirement governs, from an `Operations:` line. */\n  operations: string[];\n  /**\n   * What this requirement's scenarios exercise, from a `Covers:` line — the\n   * architecture analog of `Operations:`. Entries are C4 element ids, edges\n   * (`source -> target`), or health signals (`alert:<id>` / `sli:<id>`);\n   * core/c4/arch.ts owns the grammar and the resolution. Parsed everywhere for one\n   * grammar's sake, meaningful in arch.spec.md.\n   */\n  covers: string[];\n  /**\n   * Authorization this requirement is gated on, from a `Requires:` line —\n   * `<subject>/<permission>` entries declared in `architecture/permissions.yaml`.\n   *\n   * A third join beside `Operations:` and `Covers:`, and it exists because the\n   * other two cannot carry it. A permission is not an operation (one operation\n   * is gated by several, and the same permission gates several operations) and\n   * it is not a C4 element (it is a domain fact, not a structural one). The\n   * subject half is what the OpenAPI security model cannot express at all:\n   * `security` names what the CALLER must hold, while a permission is as often\n   * checked on an entity inside the request — the profile a message is sent\n   * from, the org a resource belongs to.\n   */\n  requires: string[];\n  /**\n   * Fleet capabilities this requirement realizes part of, from a `Capability:`\n   * (also accepted: `Capabilities:`) line — ids declared in\n   * `architecture/capabilities.yaml`.\n   *\n   * A fourth join beside `Operations:`, `Covers:` and `Requires:`, and a LIST\n   * because the relation is many-to-many in both directions: one requirement\n   * commonly closes part of two capabilities, and a capability is realized by\n   * many requirements across several services — a single-valued field would\n   * force authors to pick a lie. Neither existing line can carry it: a\n   * capability is not an operation (it is behaviour above any one endpoint)\n   * and not a C4 element (it is a business fact, not a structural one).\n   * The parse is additive exactly as `requires` is — the line rides in\n   * `req.text` and therefore inside `requirementDigest`, so no living\n   * document's digest moves merely because loam learned to read it.\n   */\n  capabilities: string[];\n  /**\n   * Capability REQUIREMENTS this requirement realizes part of, from a\n   * `Realizes:` line — entries spelled `<capability-id>#<Requirement-ID>`,\n   * resolving against `capabilities/<cap>/spec.md`.\n   *\n   * A fifth join, and the one that makes the business tree checkable rather\n   * than merely present. `Capability:` beside it answers a DIFFERENT question\n   * and neither replaces the other: `Capability: checkout` says this\n   * requirement is part of that capability, which is a claim about theme;\n   * `Realizes: checkout#CHECKOUT-CHARGE-ONCE` says it is part of what makes one\n   * named promise true, which is a claim loam can grade in both directions —\n   * an entry that resolves to nothing, and a capability requirement nothing\n   * realizes.\n   *\n   * WHY A COMPOSITE ENTRY RATHER THAN TWO LINES. A `Requirement-ID` is only\n   * unique inside its own document, so the capability half is not decoration —\n   * it is what makes the target addressable at all. Two lines would let a\n   * requirement name three capabilities and four ids with nothing saying which\n   * belongs to which.\n   *\n   * WHY THE SEPARATOR IS THE LAST `#` AND NOT THE FIRST. The requirement half\n   * has a strict grammar (`REQUIREMENT_ID_RE`) that excludes `#`, while the\n   * capability half is a YAML key and a directory name and is not constrained\n   * here at all. Splitting at the last `#` is therefore unambiguous for every\n   * capability id there is; splitting at the first would mis-parse any id that\n   * contained one, and would do it silently.\n   *\n   * Parsed additively exactly as `capabilities` is — the line rides in\n   * `req.text` and therefore inside `requirementDigest`, so no living\n   * document's digest moves merely because loam learned to read it.\n   */\n  realizes: string[];\n  /**\n   * AsyncAPI message names this requirement governs on the PRODUCING side, from\n   * a `Publishes:` line — the event-axis analog of `Operations:`.\n   *\n   * Two lines rather than one, because the async spine is directional in a way\n   * the HTTP one is not: `Publishes:` resolves against this service's OWN\n   * contract, while `Consumes:` names a message another service declares, and\n   * only a fleet-wide view can say whether anybody does. Grading them alike\n   * would either excuse a typo in a producer or point a consumer's error at the\n   * wrong repository.\n   */\n  publishes: string[];\n  /** AsyncAPI message names this requirement consumes, from a `Consumes:` line. See `publishes`. */\n  consumes: string[];\n  scenarios: Scenario[];\n  /**\n   * The H2 heading of its SOURCE DOCUMENT this requirement was parsed under,\n   * verbatim (`## Behavior`), or absent if it preceded every heading. Records where\n   * the text came from, so it stays true after a merge re-homes the requirement.\n   *\n   * `kind` alone cannot explain why a requirement is BASE, and the two BASE cases\n   * differ completely: under `## Requirements` a delta is legally quoting the\n   * living state, while under `## Behavior` the author wrote a change that archive\n   * will silently not merge. `delta.requirement-not-merged` tells them apart.\n   */\n  section?: string;\n  /**\n   * 1-based line of this requirement's `### Requirement:` heading in its source\n   * document. Body line `text[i]` is therefore at line `line + 1 + i` — the\n   * capture is contiguous from the heading to the first scenario — which is what\n   * lets `loam rebase` rewrite one `Based-On:` line by surgery instead of\n   * reserializing the document and flattening the author's sections and prose.\n   */\n  line?: number;\n}\n\nexport const KIND_RE = /^##\\s+(ADDED|MODIFIED|REMOVED)\\s+Requirements\\s*$/i;\nexport const REQUIREMENT_ID_LINE_RE = /^\\s*Requirement-ID:\\s*(.*?)\\s*$/i;\nexport const BASED_ON_LINE_RE = /^\\s*Based-On:\\s*(.*?)\\s*$/i;\n\n/**\n * The `Capability:` body line (also accepted: `Capabilities:`), exactly as the\n * parser reads it — `./parse.ts` consumes the capture, migrate-openspec's\n * materializer tests presence with it before appending its own line. One\n * spelling on purpose: two copies of a grammar is how a \"presence\" test and\n * the parse quietly stop agreeing about what counts as the line.\n */\nexport const CAPABILITY_LINE_RE = /^\\s*Capabilit(?:y|ies):\\s*(.+?)\\s*$/i;\n\n/**\n * The `Realizes:` body line. One spelling only — no `Realize:` singular\n * alternative, unlike `Operations?:` and the rest — because the verb already\n * reads correctly for one entry and for six, and the plural forms in the older\n * lines exist to forgive a NOUN that changes shape. A grammar with an\n * alternative nobody needs is one more thing two readers can disagree about.\n */\nexport const REALIZES_LINE_RE = /^\\s*Realizes:\\s*(.+?)\\s*$/i;\n\n/**\n * The separator between a `Realizes:` target and the digest of the capability\n * requirement it was written against — `checkout#CHK-1@9f2c1a4b`.\n *\n * `@` and not a second `#`, because the two halves are read by different rules:\n * `splitRealizesEntry` takes the LAST `#` to find the requirement half, so a\n * second one would move that boundary and re-parse every existing entry. `@`\n * is also excluded from `REQUIREMENT_ID_RE`, which is what makes the split\n * unambiguous rather than a convention — an id can never contain one.\n *\n * NOBODY TYPES THIS. `loam rebase --living` writes it and rewrites it; a human\n * writes `Realizes: checkout#CHK-1` and is never asked for more. An entry\n * without a pin is not a defect and never becomes one — it is a claim that has\n * not been pinned yet, and it grades exactly as it did before pins existed.\n */\nexport const REALIZES_PIN_SEPARATOR = \"@\";\n\n/**\n * One `Realizes:` entry split into the target it names and the digest it was\n * written against, or `pin: null` when it carries none.\n *\n * A suffix that is not a well-formed digest is NOT a pin and NOT a refusal:\n * the whole entry stays the target, so `checkout#CHK-1@nonsense` resolves — or\n * fails to resolve — exactly as it would have before, under\n * `capability.realizes-unknown`, whose message names the entry the author\n * actually typed. Inventing a second refusal for one mistake is the failure\n * `splitRealizesEntry` already refuses two lines up.\n */\nexport function splitRealizesPin(entry: string): { target: string; pin: string | null } {\n  const at = entry.lastIndexOf(REALIZES_PIN_SEPARATOR);\n  if (at <= 0) return { target: entry, pin: null };\n  const suffix = entry.slice(at + 1);\n  if (!REQUIREMENT_DIGEST_RE.test(suffix)) return { target: entry, pin: null };\n  return { target: entry.slice(0, at), pin: suffix };\n}\n\n/** Portable, review-friendly stable IDs. Case-sensitive by design. */\nexport const REQUIREMENT_ID_RE = /^[A-Za-z][A-Za-z0-9._-]{0,127}$/;\n\n/**\n * How much of the sha256 a `Based-On:` line carries — the length\n * `sources_digest` already uses (core/provenance/stamp.ts), for one reason a reader\n * can hold: every digest loam writes into a document reads the same.\n */\nexport const REQUIREMENT_DIGEST_LENGTH = 16;\n\n/** The value shape of a `Based-On:` line, exactly as `requirementDigest` writes it. */\nexport const REQUIREMENT_DIGEST_RE = new RegExp(`^[0-9a-f]{${REQUIREMENT_DIGEST_LENGTH}}$`);\n\nexport type RequirementIdProblem =\n  | { kind: \"invalid\"; requirement: string; value: string }\n  | { kind: \"repeated\"; requirement: string; values: string[] }\n  | { kind: \"duplicate\"; id: string; requirements: string[] };\n\n/** Every authored Requirement-ID value in a requirement body, including blanks. */\nexport function requirementIdDeclarations(requirement: Requirement): string[] {\n  return requirement.text.flatMap((line) => {\n    const match = REQUIREMENT_ID_LINE_RE.exec(line);\n    return match === null ? [] : [match[1]!.trim()];\n  });\n}\n\n/** Structural ID problems within one spec/delta document. */\nexport function requirementIdProblems(reqs: Requirement[]): RequirementIdProblem[] {\n  const problems: RequirementIdProblem[] = [];\n  const owners = new Map<string, string[]>();\n  for (const requirement of reqs) {\n    const declarations = requirementIdDeclarations(requirement);\n    const values = declarations.length > 0\n      ? declarations\n      : requirement.id === undefined\n        ? []\n        : [requirement.id];\n    if (declarations.length > 1) {\n      problems.push({ kind: \"repeated\", requirement: requirement.name, values: declarations });\n    }\n    for (const value of values) {\n      if (!REQUIREMENT_ID_RE.test(value)) {\n        problems.push({ kind: \"invalid\", requirement: requirement.name, value });\n      }\n    }\n    // A repeated declaration is already an error. Do not also pretend its\n    // keep-last parse result is an unambiguous document identity.\n    if (values.length !== 1 || !REQUIREMENT_ID_RE.test(values[0]!)) continue;\n    const names = owners.get(values[0]!) ?? [];\n    names.push(requirement.name);\n    owners.set(values[0]!, names);\n  }\n  for (const [id, requirements] of owners) {\n    if (requirements.length > 1) problems.push({ kind: \"duplicate\", id, requirements });\n  }\n  return problems;\n}\n\n/** Every authored `Based-On:` value in a requirement body, including blanks. */\nexport function basedOnDeclarations(requirement: Requirement): string[] {\n  return requirement.text.flatMap((line) => {\n    const match = BASED_ON_LINE_RE.exec(line);\n    return match === null ? [] : [match[1]!.trim()];\n  });\n}\n\n/**\n * The requirement without its baseline marker — what a digest is taken over,\n * and what archive merges into the living document.\n *\n * `Based-On:` is a statement ABOUT a delta (\"this was written against that\"),\n * never part of the requirement it describes, and both consequences of\n * forgetting that are bad. Left in the digest input, a requirement's digest\n * would depend on the pin pointing at it, so no baseline could ever be\n * self-consistent. Left in the merged text — `applyRequirementDelta` copies the\n * delta's body into living wholesale — the living document would grow a pin to\n * a version of itself, and the NEXT feature's baseline would be taken over a\n * document containing the previous feature's bookkeeping.\n */\nexport function withoutBaseline(requirement: Requirement): Requirement {\n  const { basedOn: _dropped, ...rest } = requirement;\n  return { ...rest, text: requirement.text.filter((line) => !BASED_ON_LINE_RE.test(line)) };\n}\n\n/**\n * The requirement with every `Realizes:` pin stripped back to its bare target —\n * the second thing a digest is taken over, for the same reason as the first.\n *\n * `withoutBaseline`'s argument, one axis over: a pin is a statement ABOUT a\n * join (\"this claim was written against that version of the promise\"), never\n * part of the requirement making the claim. Left in the digest input it would\n * make re-pinning a content change, so every requirement realizing a capability\n * would go stale against ITS OWN consumers the moment the capability moved —\n * one edit cascading through the corpus, which is the failure the pin exists to\n * report rather than to cause.\n *\n * The line is kept and only the suffix removed, unlike `withoutBaseline` which\n * drops the whole line: the target ids ARE content, and a requirement that\n * stops naming the promise it keeps is a different requirement.\n */\nexport function withoutRealizesPins(requirement: Requirement): Requirement {\n  return {\n    ...requirement,\n    text: requirement.text.map((line) => {\n      const match = REALIZES_LINE_RE.exec(line);\n      if (match === null) return line;\n      const bare = match[1]!\n        .split(\",\")\n        .map((entry) => splitRealizesPin(entry.trim()).target)\n        .join(\", \");\n      return line.replace(match[1]!, bare);\n    }),\n  };\n}\n\n/**\n * The identity of a requirement's CONTENT: sha256 over its canonical\n * serialization, truncated like every other digest loam stamps.\n *\n * Canonical, not raw bytes, and deliberately: archive writes every requirement\n * a delta adds or replaces through `serializeRequirements`, so hashing bytes\n * would make a baseline go stale over reflowed blank lines — a false alarm on\n * the one check whose whole value is that it only fires when something moved.\n * What the hash therefore covers is exactly what survives a round trip: the\n * heading, the body (`Requirement-ID:` and `Operations:`/`Covers:` lines\n * included), and every scenario with its Given/When/Then lines. `kind` and\n * `section` are not serialized and so are not hashed — a requirement does not\n * change because the document quoting it moved it under another heading.\n *\n * The two normalizations are the two kinds of bookkeeping a requirement can\n * carry about its own joins — the baseline pointing AT it, and the `Realizes:`\n * pins pointing OUT of it. Both are stripped for the same reason: a digest that\n * moved when bookkeeping moved would make every pin self-invalidating.\n */\nexport function requirementDigest(requirement: Requirement): string {\n  return createHash(\"sha256\")\n    .update(serializeRequirements([withoutRealizesPins(withoutBaseline(requirement))]), \"utf8\")\n    .digest(\"hex\")\n    .slice(0, REQUIREMENT_DIGEST_LENGTH);\n}\n\n/** Serialize requirements back to OpenSpec markdown (`### Requirement:` + `#### Scenario:`). */\nexport function serializeRequirements(reqs: Requirement[]): string {\n  // Framing (blank lines between sections) is normalized here; body content is\n  // only edge-trimmed, never collapsed — blank lines inside a scenario (e.g. in\n  // fenced code blocks) are verbatim content.\n  const chunks: string[] = [];\n  for (const r of reqs) {\n    const chunk: string[] = [`### Requirement: ${r.name}`];\n    const body = [...r.text];\n    // Parsed documents already carry the authored line in `text`. This branch\n    // also makes programmatically constructed Requirements serialize fully.\n    if (r.id !== undefined && !body.some((line) => REQUIREMENT_ID_LINE_RE.test(line))) {\n      body.unshift(`Requirement-ID: ${r.id}`);\n    }\n    // Directly under the identity it pins, which is where `loam rebase` writes\n    // it too — the two lines are read together, so they are never apart.\n    if (r.basedOn !== undefined && !body.some((line) => BASED_ON_LINE_RE.test(line))) {\n      body.splice(body.findIndex((line) => REQUIREMENT_ID_LINE_RE.test(line)) + 1, 0, `Based-On: ${r.basedOn}`);\n    }\n    const text = body.join(\"\\n\").trim();\n    if (text) chunk.push(\"\", text);\n    for (const s of r.scenarios) {\n      chunk.push(\"\", `#### Scenario: ${s.name}`);\n      const body = s.lines.join(\"\\n\").trim();\n      if (body) chunk.push(body);\n    }\n    chunks.push(chunk.join(\"\\n\"));\n  }\n  return chunks.join(\"\\n\\n\").trim() + \"\\n\";\n}\n"]}

package/dist/core/{config.js → envelope/config.js}

@@ -1,8 +1,9 @@
 import { readFile, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { dirname, join, parse as parsePath, resolve } from "node:path";
-import { resolveInside } from "./path-safety.js";
-import { serviceIdProblem } from "./ids.js";
+import { resolveInside } from "../kernel/path-safety.js";
+import { docsDirOf } from "../kernel/ids/dirs.js";
+import { parseServiceId } from "../kernel/ids/service.js";
 /** Local config, committed at the root of a service repo (or the docs repo itself). */
 export const CONFIG_FILENAME = "loam.json";
 /**
@@ -45,6 +46,16 @@ function searchDirs(start) {
         current = parent;
     }
 }
+/**
+ * The files loam wrote into the repository this config governs and owns there,
+ * relative to its root: loam.json itself and every agent file `agentFiles`
+ * records. `sources.unwalked` leaves them out of its denominator — a check
+ * that counted loam's own bookkeeping as a part of the service nobody read
+ * fired in every service repo the moment `loam init` had run.
+ */
+export function loamOwnedFiles(config) {
+    return [CONFIG_FILENAME, ...Object.keys(config.agentFiles ?? {})];
+}
 /** Where a config written HERE goes — never a discovered one. `init` and `saveConfig` use this. */
 export function localConfigPath(cwd = process.cwd()) {
     return resolve(cwd, CONFIG_FILENAME);
@@ -103,15 +114,26 @@ export function parseConfig(raw, configDir) {
     // Same discipline as docsDir: a malformed fact refuses the whole config
     // rather than being silently defaulted over — `5` or `""` here is a typo,
     // and defaulting would send generated files somewhere nobody chose.
+    // `parseServiceId` rather than a bare check: the same call both refuses the
+    // malformed value and produces the branded one below, so there is no window
+    // in which a checked name is still typed as an unchecked string. It takes a
+    // `string`, hence the shape guard first — the id grammar's own message is
+    // about spelling, and `5` is not a spelling.
+    let service;
     if (record.service !== undefined) {
-        const problem = serviceIdProblem(record.service, '"service"');
-        if (problem !== null)
-            throw new ConfigError("service", `${file}: ${problem}`);
+        if (typeof record.service !== "string") {
+            throw new ConfigError("service", `${file}: "service" must be a string.`);
+        }
+        const parsed = parseServiceId(record.service, '"service"');
+        if (!parsed.ok)
+            throw new ConfigError("service", `${file}: ${parsed.problem}`);
+        service = parsed.id;
     }
     if (record.gherkinDir !== undefined
         && (typeof record.gherkinDir !== "string" || record.gherkinDir === "")) {
         throw new ConfigError("gherkinDir", `${file}: "gherkinDir" must be a non-empty string when present.`);
     }
+    const contracts = readContracts(record.contracts, file);
     // Shape only. Which ids are legal is the registry's question, and asking it
     // here would make a config written by a newer binary — one that knows a tool
     // this one does not — unloadable for every command, not just for `init`.
@@ -120,6 +142,21 @@ export function parseConfig(raw, configDir) {
             || record.agentTools.some((t) => typeof t !== "string" || t === ""))) {
         throw new ConfigError("agentTools", `${file}: "agentTools" must be an array of non-empty strings when present.`);
     }
+    if (record.agentFiles !== undefined) {
+        if (record.agentFiles === null || typeof record.agentFiles !== "object" || Array.isArray(record.agentFiles)) {
+            throw new ConfigError("agentFiles", `${file}: "agentFiles" must be a path-to-digest mapping when present.`);
+        }
+        const entries = Object.entries(record.agentFiles);
+        if (entries.some(([path, digest]) => path === "" || typeof digest !== "string" || !/^[a-f0-9]{64}$/.test(digest))) {
+            throw new ConfigError("agentFiles", `${file}: "agentFiles" must map non-empty paths to lowercase sha256 digests.`);
+        }
+    }
+    if (record.agentProfile !== undefined
+        && record.agentProfile !== "full"
+        && record.agentProfile !== "service"
+        && record.agentProfile !== "docs") {
+        throw new ConfigError("agentProfile", `${file}: "agentProfile" must be one of: full, service, docs.`);
+    }
     if (typeof record.gherkinDir === "string") {
         // Validate the owned output directory, not merely its spelling. This also
         // catches an otherwise-contained path whose existing parent is a symlink
@@ -133,11 +170,19 @@ export function parseConfig(raw, configDir) {
     }
     return {
         // Resolved here, against the file's own directory, so the doc comment on
-        // `docsDir` is true no matter where a caller later resolves the path from.
-        docsDir: resolve(configDir, record.docsDir),
-        ...(record.service === undefined ? {} : { service: record.service }),
+        // `docsDir` is true no matter where a caller later resolves the path from —
+        // which is exactly the provenance `docsDirOf` demands.
+        docsDir: docsDirOf(resolve(configDir, record.docsDir)),
+        ...(service === undefined ? {} : { service }),
         ...(record.gherkinDir === undefined ? {} : { gherkinDir: record.gherkinDir }),
+        ...(contracts === undefined ? {} : { contracts }),
         ...(record.agentTools === undefined ? {} : { agentTools: record.agentTools }),
+        ...(record.agentFiles === undefined
+            ? {}
+            : { agentFiles: record.agentFiles }),
+        ...(record.agentProfile === undefined
+            ? {}
+            : { agentProfile: record.agentProfile }),
         root: resolve(configDir),
         docsDirAsWritten: record.docsDir,
     };
@@ -145,7 +190,7 @@ export function parseConfig(raw, configDir) {
 export async function loadConfig(cwd = process.cwd()) {
     const p = findConfigPath(cwd);
     if (p === null)
-        return null;
+        return { kind: "absent" };
     try {
         // The read belongs INSIDE the try: `existsSync` only says the name is
         // taken, not that it names a file this process can read. A loam.json that
@@ -153,17 +198,11 @@ export async function loadConfig(cwd = process.cwd()) {
         // deleted between the search and the read (ENOENT) all fail here rather
         // than in `parseConfig` — and read outside, each of them escaped every
         // command as an `internal` crash carrying a bare errno. Caught here they
-        // join the same "exists but cannot be believed" arm the parse failures
-        // already take, so `reportNoConfig` re-checks the path and answers the
-        // designed `config-invalid` (or `no-config` if the file really has gone).
-        return parseConfig(await readFile(p, "utf8"), dirname(p));
+        // join the same "exists but cannot be believed" arm the parse failures take.
+        return { kind: "loaded", config: parseConfig(await readFile(p, "utf8"), dirname(p)) };
     }
     catch (err) {
-        // An unreadable config must not crash the CLI with a stack trace: report it and
-        // treat it as absent — commands fail with their normal hint, and `loam init`
-        // (which spreads the old config) can rewrite a corrupt file instead of dying on it.
-        console.error(`Invalid ${CONFIG_FILENAME}: ${err instanceof Error ? err.message : String(err)}`);
-        return null;
+        return { kind: "invalid", path: p, problem: err instanceof Error ? err.message : String(err) };
     }
 }
 /**
@@ -177,4 +216,36 @@ export async function saveConfig(config, cwd = process.cwd()) {
     await writeFile(p, JSON.stringify(stored, null, 2) + "\n", "utf8");
     return p;
 }
+/**
+ * The optional `contracts` block, validated to shape only.
+ *
+ * SHAPE ONLY, exactly as `agentTools` is, and for a sharper version of the same
+ * reason: containment is not checked here because a build output legitimately
+ * sits outside the repo root's own subtree in some layouts, and the reader that
+ * resolves it is where an escaping path must be refused — with the service in
+ * hand, so the refusal can name it. A config that throws takes down every
+ * command, including the ones with nothing to do with contracts.
+ */
+function readContracts(value, file) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new ConfigError("contracts", `${file}: "contracts" must be a mapping with an optional "openapi" path.`);
+    }
+    const record = value;
+    // Only `openapi` today. The event axis gets a key when it gets a check —
+    // a config key nothing reads is worse than a missing one, because a fleet
+    // sets it and believes something is being graded.
+    const out = {};
+    for (const key of ["openapi"]) {
+        const spelled = record[key];
+        if (spelled === undefined)
+            continue;
+        if (typeof spelled !== "string" || spelled === "") {
+            throw new ConfigError("contracts", `${file}: "contracts.${key}" must be a non-empty string when present.`);
+        }
+        out[key] = spelled;
+    }
+    return out.openapi === undefined ? undefined : out;
+}
 //# sourceMappingURL=config.js.map

package/dist/core/envelope/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../src/core/envelope/config.ts"],"names":[],"mappings":"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","sourcesContent":["import { readFile, writeFile } from \"node:fs/promises\";\nimport { existsSync } from \"node:fs\";\nimport { dirname, join, parse as parsePath, resolve } from \"node:path\";\nimport { resolveInside } from \"../kernel/path-safety.js\";\nimport { docsDirOf, type DocsDir } from \"../kernel/ids/dirs.js\";\nimport { parseServiceId, type ServiceId } from \"../kernel/ids/service.js\";\n\n/** Local config, committed at the root of a service repo (or the docs repo itself). */\nexport const CONFIG_FILENAME = \"loam.json\";\n\nexport interface LoamConfig {\n  /**\n   * Path to the single shared docs repo (the source of truth). A LOADED config\n   * carries it resolved — `parseConfig` resolves the file's spelling against\n   * the config file's own directory, which is what earns the brand. The\n   * spelling itself is `docsDirAsWritten`, and the shape `saveConfig` persists\n   * (`StoredConfig`) keeps it a plain `string`: the stored form is deliberately\n   * unresolved (see `storedDocsDir` in commands/init/options.ts), and branding\n   * it would state a resolution that never happened.\n   */\n  docsDir: DocsDir;\n  /**\n   * Canonical id of the service in the current repo, if this is a service repo.\n   *\n   * Branded because `parseConfig` below is the one place that checks it, so\n   * every command reading `config.service` is reading a name that has already\n   * passed the grammar — which is why the config arm of\n   * `opts.service ?? config.service` needs no second parse.\n   */\n  service?: ServiceId;\n  /**\n   * Where Gherkin lives in this service repo, relative to the repo root\n   * (default \"features\" — the cucumber convention). `loam gherkin` writes only\n   * inside `<gherkinDir>/loam/`; the rest of the directory stays the team's.\n   * Left unresolved on purpose: commands resolve it against the repo they run\n   * in, which is where the config file lives.\n   */\n  gherkinDir?: string;\n  /**\n   * Where this repo's BUILD writes its contract documents, relative to the\n   * repo root — the springdoc/FastAPI/NestJS output, not a second copy anybody\n   * maintains.\n   *\n   * loam reads these and compares a digest; it never writes them, never copies\n   * them into the docs repo, and never derives meaning from them. That is what\n   * keeps the field on the right side of the no-extractor line: it parses a\n   * standard document somebody else generated, at a path a human named, in\n   * exactly the way `verify --results` already ingests a cucumber report.\n   *\n   * The committed `services/<id>/openapi.yaml` stays the contract, and the copy\n   * stays a human `cp` reviewed in a pull request. Automating the copy would\n   * make the docs-repo document a cache of the build; leaving it manual and\n   * merely REPORTING the divergence keeps it a document somebody agreed to.\n   */\n  contracts?: { openapi?: string };\n  /**\n   * The agent tools `loam init` has written command and skill files for in this\n   * repo, by AGENT_TOOLS id.\n   *\n   * Recorded because the two ways a generated file can be absent look identical\n   * on disk: the binary grew a command nobody has re-run `init` for, or nobody\n   * ever selected that tool here. Only this list tells them apart, and `loam\n   * doctor` needs the difference to know which absence is worth reporting.\n   *\n   * ACCUMULATED, never replaced — a later `init --tools cursor` does not\n   * un-write the claude files an earlier run left on disk, so the record of\n   * what this repo holds has to keep them too.\n   *\n   * Optional, and unvalidated against the registry on purpose: a config written\n   * by an older binary has no list at all, and one written by a NEWER binary\n   * may name a tool this one has never heard of. Neither may refuse to load.\n   */\n  agentTools?: string[];\n  /**\n   * Digests of generated agent files loam may safely refresh. Keys are\n   * repo-relative portable paths; a file whose bytes differ from its recorded\n   * digest is human-owned and is never overwritten.\n   */\n  agentFiles?: Record<string, string>;\n  /** Which workflow subset `loam init` manages; absent means the compatible full set. */\n  agentProfile?: \"full\" | \"service\" | \"docs\";\n  /**\n   * The directory the config was actually FOUND in — the repo root, which is\n   * not necessarily the cwd now that discovery walks upward. Everything a\n   * command resolves against \"this repo\" (gherkinDir, relative `sources:`)\n   * belongs here, not against process.cwd(): running `loam gherkin` from\n   * `src/deep/` must write the same files as running it from the root.\n   *\n   * Derived, never stored: `saveConfig` strips it, so it can never be spelled\n   * in loam.json and drift from where the file really is.\n   */\n  root?: string;\n  /**\n   * `docsDir` exactly as the file spells it, before resolution. Kept because\n   * \"relative\" and \"absolute\" are not recoverable from the resolved path, and\n   * the difference is the whole point: an absolute docsDir in a COMMITTED\n   * config is a path that only exists on the machine that ran `loam init`.\n   *\n   * Derived, never stored — same contract as `root`.\n   */\n  docsDirAsWritten?: string;\n}\n\n/**\n * A loam.json that exists but cannot be believed. Carries the field at fault\n * (null when the whole document is), because \"which field\" is the difference\n * between a fix and a guess — and because both `loadConfig` and `loam doctor`\n * report the same sentence from it.\n */\nexport class ConfigError extends Error {\n  constructor(\n    readonly field: string | null,\n    message: string,\n  ) {\n    super(message);\n    this.name = \"ConfigError\";\n  }\n}\n\n/**\n * The directories a config search may look in: `start`, then each ancestor, up\n * to AND INCLUDING the git root — or the filesystem root when there is no git\n * repo above.\n *\n * The git root is the stop because it is the boundary the user already thinks\n * in: a loam.json outside it belongs to some other checkout (or, worse, to a\n * home directory), and silently adopting it would point a service repo's\n * commands at a docs repo nobody in this repo ever chose.\n */\nfunction searchDirs(start: string): string[] {\n  const out: string[] = [];\n  let current = resolve(start);\n  const root = parsePath(current).root;\n  for (;;) {\n    out.push(current);\n    // `.git` is a directory in a normal clone and a FILE in a worktree or\n    // submodule — existsSync answers both without caring which.\n    if (existsSync(join(current, \".git\"))) return out;\n    const parent = dirname(current);\n    if (parent === current || current === root) return out;\n    current = parent;\n  }\n}\n\n/**\n * The files loam wrote into the repository this config governs and owns there,\n * relative to its root: loam.json itself and every agent file `agentFiles`\n * records. `sources.unwalked` leaves them out of its denominator — a check\n * that counted loam's own bookkeeping as a part of the service nobody read\n * fired in every service repo the moment `loam init` had run.\n */\nexport function loamOwnedFiles(config: LoamConfig): string[] {\n  return [CONFIG_FILENAME, ...Object.keys(config.agentFiles ?? {})];\n}\n\n/** Where a config written HERE goes — never a discovered one. `init` and `saveConfig` use this. */\nexport function localConfigPath(cwd: string = process.cwd()): string {\n  return resolve(cwd, CONFIG_FILENAME);\n}\n\n/**\n * The nearest loam.json at or above `cwd`, or null. Exported because `init` has\n * to be able to ask a different question from \"is there one here\": a config in\n * an ancestor already governs this directory, and a second one written below it\n * would quietly shadow the first for every command run from the subtree.\n */\nexport function findConfigPath(cwd: string = process.cwd()): string | null {\n  for (const dir of searchDirs(cwd)) {\n    const candidate = join(dir, CONFIG_FILENAME);\n    if (existsSync(candidate)) return candidate;\n  }\n  return null;\n}\n\n/**\n * The config that governs `cwd`: the discovered one, or — when there is none —\n * where it would have to be written. The fallback keeps this total, which is\n * what lets a caller distinguish \"absent\" from \"present but unloadable\" with a\n * single existsSync (see `reportNoConfig`).\n */\nexport function configPath(cwd: string = process.cwd()): string {\n  return findConfigPath(cwd) ?? localConfigPath(cwd);\n}\n\n/**\n * THE config validator. One implementation, because two of them are two\n * opinions: `loam doctor` used to carry its own copy, and a config doctor\n * called healthy could still be one every other command refused to load.\n *\n * `configDir` is the directory the file lives in — every relative path in the\n * document is resolved against it, so the doc comments above stay true no\n * matter where the caller happens to be standing.\n */\nexport function parseConfig(raw: string, configDir: string): LoamConfig {\n  const file = join(configDir, CONFIG_FILENAME);\n  let value: unknown;\n  try {\n    value = JSON.parse(raw);\n  } catch (err) {\n    throw new ConfigError(null, `${file} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);\n  }\n  // Checked before any field access: `JSON.parse(\"null\")` and `JSON.parse(\"5\")`\n  // are valid JSON, and reaching for `.docsDir` on them is how a config typo\n  // used to surface as a raw Node TypeError instead of a named field.\n  if (value === null || typeof value !== \"object\" || Array.isArray(value)) {\n    throw new ConfigError(null, `${file} must contain a JSON object.`);\n  }\n  const record = value as Record<string, unknown>;\n\n  if (typeof record.docsDir !== \"string\" || record.docsDir === \"\") {\n    throw new ConfigError(\"docsDir\", `${file}: \"docsDir\" must be a non-empty string.`);\n  }\n  // Same discipline as docsDir: a malformed fact refuses the whole config\n  // rather than being silently defaulted over — `5` or `\"\"` here is a typo,\n  // and defaulting would send generated files somewhere nobody chose.\n  // `parseServiceId` rather than a bare check: the same call both refuses the\n  // malformed value and produces the branded one below, so there is no window\n  // in which a checked name is still typed as an unchecked string. It takes a\n  // `string`, hence the shape guard first — the id grammar's own message is\n  // about spelling, and `5` is not a spelling.\n  let service: ServiceId | undefined;\n  if (record.service !== undefined) {\n    if (typeof record.service !== \"string\") {\n      throw new ConfigError(\"service\", `${file}: \"service\" must be a string.`);\n    }\n    const parsed = parseServiceId(record.service, '\"service\"');\n    if (!parsed.ok) throw new ConfigError(\"service\", `${file}: ${parsed.problem}`);\n    service = parsed.id;\n  }\n  if (record.gherkinDir !== undefined\n    && (typeof record.gherkinDir !== \"string\" || record.gherkinDir === \"\")) {\n    throw new ConfigError(\"gherkinDir\", `${file}: \"gherkinDir\" must be a non-empty string when present.`);\n  }\n  const contracts = readContracts(record.contracts, file);\n  // Shape only. Which ids are legal is the registry's question, and asking it\n  // here would make a config written by a newer binary — one that knows a tool\n  // this one does not — unloadable for every command, not just for `init`.\n  if (record.agentTools !== undefined\n    && (!Array.isArray(record.agentTools)\n      || record.agentTools.some((t) => typeof t !== \"string\" || t === \"\"))) {\n    throw new ConfigError(\n      \"agentTools\",\n      `${file}: \"agentTools\" must be an array of non-empty strings when present.`,\n    );\n  }\n  if (record.agentFiles !== undefined) {\n    if (record.agentFiles === null || typeof record.agentFiles !== \"object\" || Array.isArray(record.agentFiles)) {\n      throw new ConfigError(\"agentFiles\", `${file}: \"agentFiles\" must be a path-to-digest mapping when present.`);\n    }\n    const entries = Object.entries(record.agentFiles as Record<string, unknown>);\n    if (entries.some(([path, digest]) => path === \"\" || typeof digest !== \"string\" || !/^[a-f0-9]{64}$/.test(digest))) {\n      throw new ConfigError(\n        \"agentFiles\",\n        `${file}: \"agentFiles\" must map non-empty paths to lowercase sha256 digests.`,\n      );\n    }\n  }\n  if (record.agentProfile !== undefined\n    && record.agentProfile !== \"full\"\n    && record.agentProfile !== \"service\"\n    && record.agentProfile !== \"docs\") {\n    throw new ConfigError(\n      \"agentProfile\",\n      `${file}: \"agentProfile\" must be one of: full, service, docs.`,\n    );\n  }\n  if (typeof record.gherkinDir === \"string\") {\n    // Validate the owned output directory, not merely its spelling. This also\n    // catches an otherwise-contained path whose existing parent is a symlink\n    // out of the service repo.\n    try {\n      resolveInside(configDir, join(record.gherkinDir, \"loam\"), `\"gherkinDir\"`);\n    } catch (err) {\n      throw new ConfigError(\"gherkinDir\", `${file}: ${err instanceof Error ? err.message : String(err)}`);\n    }\n  }\n\n  return {\n    // Resolved here, against the file's own directory, so the doc comment on\n    // `docsDir` is true no matter where a caller later resolves the path from —\n    // which is exactly the provenance `docsDirOf` demands.\n    docsDir: docsDirOf(resolve(configDir, record.docsDir)),\n    ...(service === undefined ? {} : { service }),\n    ...(record.gherkinDir === undefined ? {} : { gherkinDir: record.gherkinDir as string }),\n    ...(contracts === undefined ? {} : { contracts }),\n    ...(record.agentTools === undefined ? {} : { agentTools: record.agentTools as string[] }),\n    ...(record.agentFiles === undefined\n      ? {}\n      : { agentFiles: record.agentFiles as Record<string, string> }),\n    ...(record.agentProfile === undefined\n      ? {}\n      : { agentProfile: record.agentProfile as \"full\" | \"service\" | \"docs\" }),\n    root: resolve(configDir),\n    docsDirAsWritten: record.docsDir,\n  };\n}\n\n/**\n * Every way asking for the config can come out, as data. It used to be\n * `LoamConfig | null` with a `console.error` on the invalid arm — core's one\n * print outside the envelope adapter, and a null that collapsed \"no config\"\n * and \"a config nobody can read\" into one answer `reportNoConfig` then had to\n * re-derive from the filesystem (a TOCTOU: the file could change between the\n * load and the re-check). The union says which case it is, carries the parse\n * problem for the command layer to render, and prints nothing.\n */\nexport type ConfigLoad =\n  | { kind: \"loaded\"; config: LoamConfig }\n  | { kind: \"absent\" }\n  | { kind: \"invalid\"; path: string; problem: string };\n\nexport async function loadConfig(cwd: string = process.cwd()): Promise<ConfigLoad> {\n  const p = findConfigPath(cwd);\n  if (p === null) return { kind: \"absent\" };\n  try {\n    // The read belongs INSIDE the try: `existsSync` only says the name is\n    // taken, not that it names a file this process can read. A loam.json that\n    // is a directory (EISDIR), one whose permissions refuse us (EACCES), or one\n    // deleted between the search and the read (ENOENT) all fail here rather\n    // than in `parseConfig` — and read outside, each of them escaped every\n    // command as an `internal` crash carrying a bare errno. Caught here they\n    // join the same \"exists but cannot be believed\" arm the parse failures take.\n    return { kind: \"loaded\", config: parseConfig(await readFile(p, \"utf8\"), dirname(p)) };\n  } catch (err) {\n    return { kind: \"invalid\", path: p, problem: err instanceof Error ? err.message : String(err) };\n  }\n}\n\n/**\n * What `saveConfig` persists: `LoamConfig` with `docsDir` back to a plain\n * `string`, because the stored form is the SPELLING (deliberately relative —\n * `storedDocsDir`), not the resolved `DocsDir` a loaded config carries. The\n * two derived fields ride along as optional so a caller may spread a loaded\n * config forward — `saveConfig` strips them on the way out either way.\n */\nexport type StoredConfig = Omit<LoamConfig, \"docsDir\"> & { docsDir: string };\n\n/**\n * Write the config for the repo rooted at `cwd`. The derived fields are dropped\n * on the way out: they are facts about where the file was found and how it was\n * spelled, and a stored copy could only ever disagree with the file itself.\n */\nexport async function saveConfig(config: StoredConfig, cwd: string = process.cwd()): Promise<string> {\n  const p = localConfigPath(cwd);\n  const { root: _root, docsDirAsWritten: _asWritten, ...stored } = config;\n  await writeFile(p, JSON.stringify(stored, null, 2) + \"\\n\", \"utf8\");\n  return p;\n}\n\n/**\n * The optional `contracts` block, validated to shape only.\n *\n * SHAPE ONLY, exactly as `agentTools` is, and for a sharper version of the same\n * reason: containment is not checked here because a build output legitimately\n * sits outside the repo root's own subtree in some layouts, and the reader that\n * resolves it is where an escaping path must be refused — with the service in\n * hand, so the refusal can name it. A config that throws takes down every\n * command, including the ones with nothing to do with contracts.\n */\nfunction readContracts(value: unknown, file: string): { openapi?: string } | undefined {\n  if (value === undefined) return undefined;\n  if (typeof value !== \"object\" || value === null || Array.isArray(value)) {\n    throw new ConfigError(\"contracts\", `${file}: \"contracts\" must be a mapping with an optional \"openapi\" path.`);\n  }\n  const record = value as Record<string, unknown>;\n  // Only `openapi` today. The event axis gets a key when it gets a check —\n  // a config key nothing reads is worse than a missing one, because a fleet\n  // sets it and believes something is being graded.\n  const out: { openapi?: string } = {};\n  for (const key of [\"openapi\"] as const) {\n    const spelled = record[key];\n    if (spelled === undefined) continue;\n    if (typeof spelled !== \"string\" || spelled === \"\") {\n      throw new ConfigError(\"contracts\", `${file}: \"contracts.${key}\" must be a non-empty string when present.`);\n    }\n    out[key] = spelled;\n  }\n  return out.openapi === undefined ? undefined : out;\n}\n"]}