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

package/dist/core/c4/resolve/service.js

@@ -0,0 +1,113 @@
+/**
+ * Which `services/<id>/` directory a modelled element belongs to.
+ *
+ * A distinct subject from loading a document, and a distinct phase: the
+ * loader beside this package (`../likec4.ts`) turns LikeC4's parse output into
+ * loam's neutral `Elem`/`Rel` records, and everything here runs AFTER that, over
+ * those records, answering one question the model itself never states outright.
+ * It is the join every fleet-wide check rests on — the landscape↔services
+ * reconciliation, the spine's edge grouping, `Covers:` resolution, health.yaml's
+ * dependency matching — which is why `docs/DESIGN.md`'s Open-decisions table
+ * audits its call sites as a subject of their own rather than as a detail of the
+ * loader.
+ *
+ * The resolution order below is the whole of it, and its last rung is the one
+ * that lies: read that comment before adding a caller.
+ */
+import { declaredService } from "../../kernel/ids/service.js";
+import {} from "../likec4.js";
+/**
+ * The service directory an element stands for: an explicit
+ * `metadata { service '<id>' }` binding wins, the title is the fallback.
+ *
+ * The fallback is what every docs repo written before the binding existed relies
+ * on, and it is also the trap the binding exists to close: matching on the title
+ * means renaming a box in a diagram silently unlinks it from its service, and
+ * every check that joined the two just stops finding anything.
+ */
+export function elementService(e) {
+    return e.service ?? declaredService(e.title);
+}
+/**
+ * Every id an endpoint may be filed under, nearest first: `a.b.c`, `a.b`, `a`.
+ *
+ * A landscape does not have to draw a service as one opaque box. The moment
+ * somebody models its containers — `paymentService.api`, `paymentService.worker`
+ * — an edge drawn INTO a container is still an edge into the service, and every
+ * join that groups by service has to know that. Resolving only the exact id is
+ * what made those edges invisible: the spine check silently skipped them, and
+ * the no-openapi grace treated a service with a dozen inbound container calls as
+ * one nobody calls at all.
+ */
+function ancestorIds(id) {
+    const out = [id];
+    for (let dot = id.lastIndexOf("."); dot !== -1; dot = id.lastIndexOf(".", dot - 1)) {
+        out.push(id.slice(0, dot));
+    }
+    return out;
+}
+/**
+ * A memoized `id -> service` resolver over one document.
+ *
+ * Resolution order, and why it is this order:
+ *
+ *  1. the nearest ancestor (the id itself first) carrying an explicit
+ *     `metadata { service '<id>' }` — a binding is a claim somebody wrote down,
+ *     so it outranks every guess;
+ *  2. the nearest ancestor whose title names a REAL `services/<id>/` directory —
+ *     positive evidence from the filesystem, available only to callers that
+ *     hand in `known`;
+ *  3. the element's own title, and finally the raw id — today's fallback, kept
+ *     LAST because it is the one that lies: it happily resolves
+ *     `paymentService.api` to "api", a service that has never existed.
+ *
+ * Built once per document and shared, because it is called inside loops over
+ * every relationship and the walk up the ancestor chain is not free.
+ */
+export function serviceResolver(elements, known) {
+    const byId = new Map(elements.map((e) => [e.id, e]));
+    const memo = new Map();
+    return (id) => {
+        const hit = memo.get(id);
+        if (hit !== undefined)
+            return hit;
+        let answer;
+        for (const candidate of ancestorIds(id)) {
+            const e = byId.get(candidate);
+            if (e?.service !== undefined) {
+                answer = e.service;
+                break;
+            }
+        }
+        if (answer === undefined && known !== undefined) {
+            for (const candidate of ancestorIds(id)) {
+                const e = byId.get(candidate);
+                if (e !== undefined && known.has(e.title)) {
+                    answer = declaredService(e.title);
+                    break;
+                }
+            }
+        }
+        if (answer === undefined) {
+            const self = byId.get(id);
+            answer = self ? elementService(self) : declaredService(id);
+        }
+        memo.set(id, answer);
+        return answer;
+    };
+}
+/**
+ * The service a relationship endpoint belongs to. An id that names no element
+ * resolves to itself, so a partial document degrades to the id rather than
+ * throwing.
+ *
+ * `known` is the set of service directories that actually exist; pass it
+ * wherever the caller has enumerated `services/`, so an edge into a modelled
+ * container resolves to the service that owns it instead of to the container's
+ * own title. Callers with a single document and no repository in hand omit it
+ * and keep the pre-existing behaviour.
+ */
+export function serviceOf(elements, id, known) {
+    return serviceResolver(elements, known)(id);
+}
+//# sourceMappingURL=service.js.map

package/dist/core/c4/resolve/service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../../../../src/core/c4/resolve/service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,eAAe,EAAwB,MAAM,6BAA6B,CAAC;AACpF,OAAO,EAAa,MAAM,cAAc,CAAC;AAEzC;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,CAAO;IACpC,OAAO,CAAC,CAAC,OAAO,IAAI,eAAe,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAS,WAAW,CAAC,EAAU;IAC7B,MAAM,GAAG,GAAG,CAAC,EAAE,CAAC,CAAC;IACjB,KAAK,IAAI,GAAG,GAAG,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,GAAG,KAAK,CAAC,CAAC,EAAE,GAAG,GAAG,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,GAAG,CAAC,CAAC,EAAE,CAAC;QACnF,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;IAC7B,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,eAAe,CAC7B,QAAgB,EAChB,KAA2B;IAE3B,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IACrD,MAAM,IAAI,GAAG,IAAI,GAAG,EAA2B,CAAC;IAChD,OAAO,CAAC,EAAU,EAAmB,EAAE;QACrC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACzB,IAAI,GAAG,KAAK,SAAS;YAAE,OAAO,GAAG,CAAC;QAClC,IAAI,MAAmC,CAAC;QACxC,KAAK,MAAM,SAAS,IAAI,WAAW,CAAC,EAAE,CAAC,EAAE,CAAC;YACxC,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YAC9B,IAAI,CAAC,EAAE,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC7B,MAAM,GAAG,CAAC,CAAC,OAAO,CAAC;gBACnB,MAAM;YACR,CAAC;QACH,CAAC;QACD,IAAI,MAAM,KAAK,SAAS,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YAChD,KAAK,MAAM,SAAS,IAAI,WAAW,CAAC,EAAE,CAAC,EAAE,CAAC;gBACxC,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;gBAC9B,IAAI,CAAC,KAAK,SAAS,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC;oBAC1C,MAAM,GAAG,eAAe,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;oBAClC,MAAM;gBACR,CAAC;YACH,CAAC;QACH,CAAC;QACD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAC1B,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,EAAE,CAAC,CAAC;QAC7D,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;QACrB,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,SAAS,CAAC,QAAgB,EAAE,EAAU,EAAE,KAA2B;IACjF,OAAO,eAAe,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC;AAC9C,CAAC","sourcesContent":["/**\n * Which `services/<id>/` directory a modelled element belongs to.\n *\n * A distinct subject from loading a document, and a distinct phase: the\n * loader beside this package (`../likec4.ts`) turns LikeC4's parse output into\n * loam's neutral `Elem`/`Rel` records, and everything here runs AFTER that, over\n * those records, answering one question the model itself never states outright.\n * It is the join every fleet-wide check rests on — the landscape↔services\n * reconciliation, the spine's edge grouping, `Covers:` resolution, health.yaml's\n * dependency matching — which is why `docs/DESIGN.md`'s Open-decisions table\n * audits its call sites as a subject of their own rather than as a detail of the\n * loader.\n *\n * The resolution order below is the whole of it, and its last rung is the one\n * that lies: read that comment before adding a caller.\n */\nimport { declaredService, type DeclaredService } from \"../../kernel/ids/service.js\";\nimport { type Elem } from \"../likec4.js\";\n\n/**\n * The service directory an element stands for: an explicit\n * `metadata { service '<id>' }` binding wins, the title is the fallback.\n *\n * The fallback is what every docs repo written before the binding existed relies\n * on, and it is also the trap the binding exists to close: matching on the title\n * means renaming a box in a diagram silently unlinks it from its service, and\n * every check that joined the two just stops finding anything.\n */\nexport function elementService(e: Elem): DeclaredService {\n  return e.service ?? declaredService(e.title);\n}\n\n/**\n * Every id an endpoint may be filed under, nearest first: `a.b.c`, `a.b`, `a`.\n *\n * A landscape does not have to draw a service as one opaque box. The moment\n * somebody models its containers — `paymentService.api`, `paymentService.worker`\n * — an edge drawn INTO a container is still an edge into the service, and every\n * join that groups by service has to know that. Resolving only the exact id is\n * what made those edges invisible: the spine check silently skipped them, and\n * the no-openapi grace treated a service with a dozen inbound container calls as\n * one nobody calls at all.\n */\nfunction ancestorIds(id: string): string[] {\n  const out = [id];\n  for (let dot = id.lastIndexOf(\".\"); dot !== -1; dot = id.lastIndexOf(\".\", dot - 1)) {\n    out.push(id.slice(0, dot));\n  }\n  return out;\n}\n\n/**\n * A memoized `id -> service` resolver over one document.\n *\n * Resolution order, and why it is this order:\n *\n *  1. the nearest ancestor (the id itself first) carrying an explicit\n *     `metadata { service '<id>' }` — a binding is a claim somebody wrote down,\n *     so it outranks every guess;\n *  2. the nearest ancestor whose title names a REAL `services/<id>/` directory —\n *     positive evidence from the filesystem, available only to callers that\n *     hand in `known`;\n *  3. the element's own title, and finally the raw id — today's fallback, kept\n *     LAST because it is the one that lies: it happily resolves\n *     `paymentService.api` to \"api\", a service that has never existed.\n *\n * Built once per document and shared, because it is called inside loops over\n * every relationship and the walk up the ancestor chain is not free.\n */\nexport function serviceResolver(\n  elements: Elem[],\n  known?: ReadonlySet<string>,\n): (id: string) => DeclaredService {\n  const byId = new Map(elements.map((e) => [e.id, e]));\n  const memo = new Map<string, DeclaredService>();\n  return (id: string): DeclaredService => {\n    const hit = memo.get(id);\n    if (hit !== undefined) return hit;\n    let answer: DeclaredService | undefined;\n    for (const candidate of ancestorIds(id)) {\n      const e = byId.get(candidate);\n      if (e?.service !== undefined) {\n        answer = e.service;\n        break;\n      }\n    }\n    if (answer === undefined && known !== undefined) {\n      for (const candidate of ancestorIds(id)) {\n        const e = byId.get(candidate);\n        if (e !== undefined && known.has(e.title)) {\n          answer = declaredService(e.title);\n          break;\n        }\n      }\n    }\n    if (answer === undefined) {\n      const self = byId.get(id);\n      answer = self ? elementService(self) : declaredService(id);\n    }\n    memo.set(id, answer);\n    return answer;\n  };\n}\n\n/**\n * The service a relationship endpoint belongs to. An id that names no element\n * resolves to itself, so a partial document degrades to the id rather than\n * throwing.\n *\n * `known` is the set of service directories that actually exist; pass it\n * wherever the caller has enumerated `services/`, so an edge into a modelled\n * container resolves to the service that owns it instead of to the container's\n * own title. Callers with a single document and no repository in hand omit it\n * and keep the pre-existing behaviour.\n */\nexport function serviceOf(elements: Elem[], id: string, known?: ReadonlySet<string>): DeclaredService {\n  return serviceResolver(elements, known)(id);\n}\n\n"]}

package/dist/core/c4/seed/fleet-file.js

@@ -0,0 +1,201 @@
+/**
+ * fleet.yaml — the tiny human-authored file `loam seed` templates the fleet
+ * map from. A human states the facts (which services exist, who calls whom);
+ * loam does mechanical templating and guesses nothing, which is what keeps
+ * seed on the same side of the no-extractor line as `loam new`.
+ *
+ * Parsed with the AST (`parseDocument` + `LineCounter`) rather than `parse`,
+ * deliberately: every refusal names `file:line`, because the file is edited by
+ * hand and "something in it is wrong" is not a fix. Fail-closed throughout —
+ * an unknown key, a non-string entry, a malformed call all refuse before the
+ * caller writes a single byte; a partially-understood fleet file must never
+ * become a partially-right landscape. The node-level readers live in
+ * `./items.ts`; this module owns what their answers must amount to.
+ *
+ * The grammars are the shared ones and never a private copy: service ids
+ * through `parseServiceId`, subsystem names through `parseSubsystemName`,
+ * externals through the same `dirNameHazard` those two are built on (an
+ * external never becomes a directory, but calls name services and externals
+ * out of ONE namespace, and a name legal as one and illegal as the other
+ * would make the duplicate refusal incoherent — `kernel/ids/service.ts`'s own
+ * argument, one level up).
+ */
+import { isMap, isScalar, LineCounter, parseDocument } from "yaml";
+import { dirNameHazard, parseServiceId } from "../../kernel/ids/service.js";
+import { parseSubsystemName } from "../../kernel/ids/subsystem.js";
+import { at, hint, listOf, serviceEntry, stringOf } from "./items.js";
+const TOP_KEYS = ["services", "subsystems", "externals", "calls"];
+function invalid(message) {
+    return { ok: false, problem: { kind: "invalid", message } };
+}
+/** Parse and validate the fleet file's text. Never throws for an expected outcome. */
+export function readFleetFile(text, file) {
+    const lines = new LineCounter();
+    const doc = parseDocument(text, { lineCounter: lines });
+    const ctx = { file, lines };
+    const parseError = doc.errors[0];
+    if (parseError !== undefined) {
+        const line = parseError.linePos?.[0]?.line;
+        return invalid(`${file}${line === undefined ? "" : `:${line}`} cannot be read as YAML — ` +
+            `${parseError.message.split("\n")[0]}`);
+    }
+    if (!isMap(doc.contents)) {
+        return invalid(`${file} must be a YAML mapping with a \`services:\` list (and optional ` +
+            `\`subsystems:\`, \`externals:\`, \`calls:\`) — the whole document is ` +
+            `${doc.contents === null ? "empty" : "not a mapping"}.`);
+    }
+    // The top level, fail-closed: a mistyped key is a whole section silently
+    // dropped, which is exactly the partial scaffold this reader must refuse.
+    const sections = new Map();
+    for (const pair of doc.contents.items) {
+        const key = isScalar(pair.key) && typeof pair.key.value === "string" ? pair.key.value : null;
+        if (key === null || !TOP_KEYS.includes(key)) {
+            const spelled = key ?? String(pair.key);
+            return invalid(`${at(ctx, pair.key)} — unknown key '${spelled}': the fleet file's keys are ` +
+                `services, subsystems, externals and calls.${hint(spelled, TOP_KEYS)}`);
+        }
+        sections.set(key, pair.value);
+    }
+    // One flat namespace over everything a name can be declared as, because a
+    // call endpoint must name exactly one thing — the same rule the tree walk
+    // enforces over `services/` (`subsystem.name-collision`).
+    const declared = new Map();
+    const claim = (name, where, role) => {
+        const held = declared.get(name);
+        if (held !== undefined) {
+            return {
+                kind: "duplicate",
+                message: `${where} declares '${name}' as ${role}, but ${held.where} already declares it as ` +
+                    `${held.role} — service ids, subsystem names and externals share one flat namespace ` +
+                    `(a call endpoint must name exactly one thing). Rename or remove one, then re-run.`,
+            };
+        }
+        declared.set(name, { where, role });
+        return null;
+    };
+    const subsystems = [];
+    for (const item of listOf(sections.get("subsystems"))) {
+        const raw = stringOf(item);
+        if (raw === null)
+            return invalid(`${at(ctx, item)} — a subsystems entry must be a string (quote it if YAML reads it as something else).`);
+        const parsed = parseSubsystemName(raw, "subsystems entry");
+        if (!parsed.ok)
+            return invalid(`${at(ctx, item)} — ${parsed.problem}`);
+        const dup = claim(raw, at(ctx, item), "a subsystem");
+        if (dup !== null)
+            return { ok: false, problem: dup };
+        subsystems.push(parsed.name);
+    }
+    const services = [];
+    /** Deferred so `subsystem: X` can reference a subsystem declared lower in the file. */
+    const subsystemRefs = [];
+    for (const item of listOf(sections.get("services"))) {
+        const entry = serviceEntry(ctx, item);
+        if ("invalid" in entry)
+            return invalid(entry.invalid);
+        const parsed = parseServiceId(entry.id, "services entry");
+        if (!parsed.ok)
+            return invalid(`${entry.where} — ${parsed.problem}`);
+        const dup = claim(entry.id, entry.where, "a service");
+        if (dup !== null)
+            return { ok: false, problem: dup };
+        if (entry.subsystem !== null)
+            subsystemRefs.push({ id: parsed.id, sub: entry.subsystem, where: entry.where });
+        services.push({ id: parsed.id, subsystem: null });
+    }
+    if (services.length === 0) {
+        return invalid(`${file} declares no services — \`services:\` is the one required key: list every ` +
+            `service id the fleet has (a bare string, or \`{ id, subsystem }\` to file one under a group).`);
+    }
+    const externals = [];
+    for (const item of listOf(sections.get("externals"))) {
+        const raw = stringOf(item);
+        if (raw === null)
+            return invalid(`${at(ctx, item)} — an externals entry must be a string (quote it if YAML reads it as something else).`);
+        if (dirNameHazard(raw) !== null) {
+            return invalid(`${at(ctx, item)} — '${raw}' cannot be an external's name: externals share the service-id ` +
+                `grammar (start with a letter or digit; letters, digits, '.', '_', '-'; no Windows-reserved ` +
+                `names), because calls name services and externals out of one namespace.`);
+        }
+        const dup = claim(raw, at(ctx, item), "an external");
+        if (dup !== null)
+            return { ok: false, problem: dup };
+        externals.push(raw);
+    }
+    // Subsystem references, now that every declaration is in: a `subsystem:`
+    // naming nothing is the second-likeliest typo in the file, and the hint
+    // offers only names the file really declares.
+    const subNames = new Set(subsystems);
+    for (const ref of subsystemRefs) {
+        if (!subNames.has(ref.sub)) {
+            return {
+                ok: false,
+                problem: {
+                    kind: "unknown-subsystem",
+                    message: `${ref.where} files service '${ref.id}' under '${ref.sub}', but \`subsystems:\` ` +
+                        `declares no '${ref.sub}'.${hint(ref.sub, subsystems)} Add it to subsystems:, ` +
+                        `or fix the spelling, then re-run.`,
+                },
+            };
+        }
+    }
+    // The branded name comes from the DECLARATION list, never from a second
+    // parse of the reference: `subsystems:` is where the grammar ran, and the
+    // membership check above proved every reference resolves into it.
+    const bySubName = new Map(subsystems.map((s) => [s, s]));
+    const filed = new Map(subsystemRefs.map((r) => [r.id, bySubName.get(r.sub) ?? null]));
+    const seededServices = services.map((s) => ({
+        id: s.id,
+        subsystem: filed.get(s.id) ?? null,
+    }));
+    const endpointProblem = (raw, name, where) => {
+        if (subNames.has(name)) {
+            return {
+                kind: "unknown-endpoint",
+                message: `${where} — call '${raw}' names the subsystem '${name}': a subsystem is a place ` +
+                    `services live, never a call endpoint. Name one of its services instead.`,
+            };
+        }
+        return {
+            kind: "unknown-endpoint",
+            message: `${where} — call '${raw}' names '${name}', which no services: or externals: entry ` +
+                `declares.${hint(name, [...services.map((s) => s.id), ...externals])} Declare it, ` +
+                `or fix the spelling, then re-run.`,
+        };
+    };
+    const callable = new Set([...services.map((s) => s.id), ...externals]);
+    const calls = [];
+    const seenCalls = new Set();
+    for (const item of listOf(sections.get("calls"))) {
+        const raw = stringOf(item);
+        if (raw === null)
+            return invalid(`${at(ctx, item)} — a calls entry must be a string of the form 'caller -> callee'.`);
+        const m = /^(\S+)\s*->\s*(\S+)$/.exec(raw.trim());
+        if (m === null) {
+            return invalid(`${at(ctx, item)} — a call is written 'caller -> callee' (got '${raw}').`);
+        }
+        const [from, to] = [m[1], m[2]];
+        for (const end of [from, to]) {
+            if (!callable.has(end))
+                return { ok: false, problem: endpointProblem(raw, end, at(ctx, item)) };
+        }
+        // LikeC4 has no self-edge: it reads `a -> a` as a parent-child
+        // relationship and refuses the whole file. Caught HERE, with the line,
+        // because the alternative is the self-check refusing `internal` over a
+        // fleet file whose fault it is not — and a copy-paste inside `calls:` is
+        // exactly how this line gets written.
+        if (from === to) {
+            return invalid(`${at(ctx, item)} — call '${raw}' names '${from}' at both ends, and LikeC4 has no ` +
+                `self-edge (it reads 'a -> a' as a parent-child relationship). Name the other ` +
+                `endpoint, or drop the line.`);
+        }
+        const key = `${from} ${to}`;
+        // A repeated line is the same fact stated twice, not a second edge.
+        if (seenCalls.has(key))
+            continue;
+        seenCalls.add(key);
+        calls.push({ from, to });
+    }
+    return { ok: true, seed: { services: seededServices, subsystems, externals, calls } };
+}
+//# sourceMappingURL=fleet-file.js.map

package/dist/core/c4/seed/fleet-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fleet-file.js","sourceRoot":"","sources":["../../../../src/core/c4/seed/fleet-file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,aAAa,EAAa,MAAM,MAAM,CAAC;AAC9E,OAAO,EAAE,aAAa,EAAE,cAAc,EAAkB,MAAM,6BAA6B,CAAC;AAC5F,OAAO,EAAE,kBAAkB,EAAsB,MAAM,+BAA+B,CAAC;AACvF,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAgB,MAAM,YAAY,CAAC;AAwCpF,MAAM,QAAQ,GAAG,CAAC,UAAU,EAAE,YAAY,EAAE,WAAW,EAAE,OAAO,CAAU,CAAC;AAE3E,SAAS,OAAO,CAAC,OAAe;IAC9B,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,EAAE,CAAC;AAC9D,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,aAAa,CAAC,IAAY,EAAE,IAAY;IACtD,MAAM,KAAK,GAAG,IAAI,WAAW,EAAE,CAAC;IAChC,MAAM,GAAG,GAAG,aAAa,CAAC,IAAI,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,CAAC;IACxD,MAAM,GAAG,GAAY,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;IACrC,MAAM,UAAU,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IACjC,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,MAAM,IAAI,GAAG,UAAU,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC;QAC3C,OAAO,OAAO,CACZ,GAAG,IAAI,GAAG,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,4BAA4B;YACxE,GAAG,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAE,EAAE,CAC1C,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;QACzB,OAAO,OAAO,CACZ,GAAG,IAAI,kEAAkE;YACvE,uEAAuE;YACvE,GAAG,GAAG,CAAC,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,GAAG,CAC1D,CAAC;IACJ,CAAC;IAED,yEAAyE;IACzE,0EAA0E;IAC1E,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAmB,CAAC;IAC5C,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,QAAQ,CAAC,KAAe,EAAE,CAAC;QAChD,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,OAAO,IAAI,CAAC,GAAG,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;QAC7F,IAAI,GAAG,KAAK,IAAI,IAAI,CAAE,QAA8B,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YACnE,MAAM,OAAO,GAAG,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACxC,OAAO,OAAO,CACZ,GAAG,EAAE,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,mBAAmB,OAAO,+BAA+B;gBAC3E,6CAA6C,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,CACzE,CAAC;QACJ,CAAC;QACD,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;IAChC,CAAC;IAED,0EAA0E;IAC1E,0EAA0E;IAC1E,0DAA0D;IAC1D,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA2C,CAAC;IACpE,MAAM,KAAK,GAAG,CAAC,IAAY,EAAE,KAAa,EAAE,IAAY,EAA0B,EAAE;QAClF,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAChC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,OAAO;gBACL,IAAI,EAAE,WAAW;gBACjB,OAAO,EACL,GAAG,KAAK,cAAc,IAAI,QAAQ,IAAI,SAAS,IAAI,CAAC,KAAK,0BAA0B;oBACnF,GAAG,IAAI,CAAC,IAAI,yEAAyE;oBACrF,mFAAmF;aACtF,CAAC;QACJ,CAAC;QACD,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACpC,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;IAEF,MAAM,UAAU,GAAoB,EAAE,CAAC;IACvC,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC;QACtD,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC3B,IAAI,GAAG,KAAK,IAAI;YAAE,OAAO,OAAO,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,IAAI,CAAC,uFAAuF,CAAC,CAAC;QAC1I,MAAM,MAAM,GAAG,kBAAkB,CAAC,GAAG,EAAE,kBAAkB,CAAC,CAAC;QAC3D,IAAI,CAAC,MAAM,CAAC,EAAE;YAAE,OAAO,OAAO,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;QACvE,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,aAAa,CAAC,CAAC;QACrD,IAAI,GAAG,KAAK,IAAI;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC;QACrD,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;IAED,MAAM,QAAQ,GAAkB,EAAE,CAAC;IACnC,uFAAuF;IACvF,MAAM,aAAa,GAAoD,EAAE,CAAC;IAC1E,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC;QACpD,MAAM,KAAK,GAAG,YAAY,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACtC,IAAI,SAAS,IAAI,KAAK;YAAE,OAAO,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACtD,MAAM,MAAM,GAAG,cAAc,CAAC,KAAK,CAAC,EAAE,EAAE,gBAAgB,CAAC,CAAC;QAC1D,IAAI,CAAC,MAAM,CAAC,EAAE;YAAE,OAAO,OAAO,CAAC,GAAG,KAAK,CAAC,KAAK,MAAM,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;QACrE,MAAM,GAAG,GAAG,KAAK,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;QACtD,IAAI,GAAG,KAAK,IAAI;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC;QACrD,IAAI,KAAK,CAAC,SAAS,KAAK,IAAI;YAAE,aAAa,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE,GAAG,EAAE,KAAK,CAAC,SAAS,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC;QAC9G,QAAQ,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACpD,CAAC;IACD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,OAAO,CACZ,GAAG,IAAI,4EAA4E;YACjF,+FAA+F,CAClG,CAAC;IACJ,CAAC;IAED,MAAM,SAAS,GAAa,EAAE,CAAC;IAC/B,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,EAAE,CAAC;QACrD,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC3B,IAAI,GAAG,KAAK,IAAI;YAAE,OAAO,OAAO,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,IAAI,CAAC,uFAAuF,CAAC,CAAC;QAC1I,IAAI,aAAa,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC;YAChC,OAAO,OAAO,CACZ,GAAG,EAAE,CAAC,GAAG,EAAE,IAAI,CAAC,OAAO,GAAG,iEAAiE;gBACzF,6FAA6F;gBAC7F,yEAAyE,CAC5E,CAAC;QACJ,CAAC;QACD,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,aAAa,CAAC,CAAC;QACrD,IAAI,GAAG,KAAK,IAAI;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC;QACrD,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACtB,CAAC;IAED,yEAAyE;IACzE,wEAAwE;IACxE,8CAA8C;IAC9C,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAS,UAAU,CAAC,CAAC;IAC7C,KAAK,MAAM,GAAG,IAAI,aAAa,EAAE,CAAC;QAChC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAC3B,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,OAAO,EAAE;oBACP,IAAI,EAAE,mBAAmB;oBACzB,OAAO,EACL,GAAG,GAAG,CAAC,KAAK,mBAAmB,GAAG,CAAC,EAAE,YAAY,GAAG,CAAC,GAAG,yBAAyB;wBACjF,gBAAgB,GAAG,CAAC,GAAG,KAAK,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,UAAU,CAAC,0BAA0B;wBAC/E,mCAAmC;iBACtC;aACF,CAAC;QACJ,CAAC;IACH,CAAC;IACD,wEAAwE;IACxE,0EAA0E;IAC1E,kEAAkE;IAClE,MAAM,SAAS,GAAG,IAAI,GAAG,CAAwB,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAW,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1F,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAY,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC;IAChG,MAAM,cAAc,GAAkB,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACzD,EAAE,EAAE,CAAC,CAAC,EAAE;QACR,SAAS,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,IAAI;KACnC,CAAC,CAAC,CAAC;IAEJ,MAAM,eAAe,GAAG,CAAC,GAAW,EAAE,IAAY,EAAE,KAAa,EAAmB,EAAE;QACpF,IAAI,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACvB,OAAO;gBACL,IAAI,EAAE,kBAAkB;gBACxB,OAAO,EACL,GAAG,KAAK,YAAY,GAAG,0BAA0B,IAAI,4BAA4B;oBACjF,yEAAyE;aAC5E,CAAC;QACJ,CAAC;QACD,OAAO;YACL,IAAI,EAAE,kBAAkB;YACxB,OAAO,EACL,GAAG,KAAK,YAAY,GAAG,YAAY,IAAI,4CAA4C;gBACnF,YAAY,IAAI,CAAC,IAAI,EAAE,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,SAAS,CAAC,CAAC,eAAe;gBACnF,mCAAmC;SACtC,CAAC;IACJ,CAAC,CAAC;IACF,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAS,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,SAAS,CAAC,CAAC,CAAC;IAC/E,MAAM,KAAK,GAAe,EAAE,CAAC;IAC7B,MAAM,SAAS,GAAG,IAAI,GAAG,EAAU,CAAC;IACpC,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC;QACjD,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC3B,IAAI,GAAG,KAAK,IAAI;YAAE,OAAO,OAAO,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,IAAI,CAAC,mEAAmE,CAAC,CAAC;QACtH,MAAM,CAAC,GAAG,sBAAsB,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;QAClD,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;YACf,OAAO,OAAO,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,IAAI,CAAC,iDAAiD,GAAG,KAAK,CAAC,CAAC;QAC5F,CAAC;QACD,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAE,EAAE,CAAC,CAAC,CAAC,CAAE,CAAC,CAAC;QAClC,KAAK,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC;YAC7B,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC;gBAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,EAAE,CAAC;QAClG,CAAC;QACD,+DAA+D;QAC/D,uEAAuE;QACvE,uEAAuE;QACvE,yEAAyE;QACzE,sCAAsC;QACtC,IAAI,IAAI,KAAK,EAAE,EAAE,CAAC;YAChB,OAAO,OAAO,CACZ,GAAG,EAAE,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,GAAG,YAAY,IAAI,oCAAoC;gBACjF,+EAA+E;gBAC/E,6BAA6B,CAChC,CAAC;QACJ,CAAC;QACD,MAAM,GAAG,GAAG,GAAG,IAAI,IAAI,EAAE,EAAE,CAAC;QAC5B,oEAAoE;QACpE,IAAI,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,SAAS;QACjC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACnB,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;IAC3B,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,cAAc,EAAE,UAAU,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,CAAC;AACxF,CAAC","sourcesContent":["/**\n * fleet.yaml — the tiny human-authored file `loam seed` templates the fleet\n * map from. A human states the facts (which services exist, who calls whom);\n * loam does mechanical templating and guesses nothing, which is what keeps\n * seed on the same side of the no-extractor line as `loam new`.\n *\n * Parsed with the AST (`parseDocument` + `LineCounter`) rather than `parse`,\n * deliberately: every refusal names `file:line`, because the file is edited by\n * hand and \"something in it is wrong\" is not a fix. Fail-closed throughout —\n * an unknown key, a non-string entry, a malformed call all refuse before the\n * caller writes a single byte; a partially-understood fleet file must never\n * become a partially-right landscape. The node-level readers live in\n * `./items.ts`; this module owns what their answers must amount to.\n *\n * The grammars are the shared ones and never a private copy: service ids\n * through `parseServiceId`, subsystem names through `parseSubsystemName`,\n * externals through the same `dirNameHazard` those two are built on (an\n * external never becomes a directory, but calls name services and externals\n * out of ONE namespace, and a name legal as one and illegal as the other\n * would make the duplicate refusal incoherent — `kernel/ids/service.ts`'s own\n * argument, one level up).\n */\nimport { isMap, isScalar, LineCounter, parseDocument, type Pair } from \"yaml\";\nimport { dirNameHazard, parseServiceId, type ServiceId } from \"../../kernel/ids/service.js\";\nimport { parseSubsystemName, type SubsystemName } from \"../../kernel/ids/subsystem.js\";\nimport { at, hint, listOf, serviceEntry, stringOf, type SeedCtx } from \"./items.js\";\n\nexport interface SeedService {\n  readonly id: ServiceId;\n  /** The subsystem this service is filed under, or null for unfiled. */\n  readonly subsystem: SubsystemName | null;\n}\n\n/** One `a -> b` line. Endpoints are declared names (service ids or externals), not element ids. */\nexport interface SeedCall {\n  readonly from: string;\n  readonly to: string;\n}\n\n/** The whole fleet file, validated: what the templater renders from. */\nexport interface FleetSeed {\n  readonly services: readonly SeedService[];\n  readonly subsystems: readonly SubsystemName[];\n  readonly externals: readonly string[];\n  readonly calls: readonly SeedCall[];\n}\n\n/**\n * Why the file was refused, discriminated by the ACTION the caller takes —\n * each kind maps to one stable error code at the command layer (`invalid` →\n * `seed-file-invalid`, `duplicate` → `seed-duplicate-service`,\n * `unknown-subsystem` → `seed-unknown-subsystem`, `unknown-endpoint` → the\n * existing `unknown-service`, because the fix is the same as for every other\n * unknown service: correct the name and re-run).\n */\nexport type SeedFileProblem =\n  | { readonly kind: \"invalid\"; readonly message: string }\n  | { readonly kind: \"duplicate\"; readonly message: string }\n  | { readonly kind: \"unknown-subsystem\"; readonly message: string }\n  | { readonly kind: \"unknown-endpoint\"; readonly message: string };\n\nexport type FleetFileRead =\n  | { readonly ok: true; readonly seed: FleetSeed }\n  | { readonly ok: false; readonly problem: SeedFileProblem };\n\nconst TOP_KEYS = [\"services\", \"subsystems\", \"externals\", \"calls\"] as const;\n\nfunction invalid(message: string): FleetFileRead {\n  return { ok: false, problem: { kind: \"invalid\", message } };\n}\n\n/** Parse and validate the fleet file's text. Never throws for an expected outcome. */\nexport function readFleetFile(text: string, file: string): FleetFileRead {\n  const lines = new LineCounter();\n  const doc = parseDocument(text, { lineCounter: lines });\n  const ctx: SeedCtx = { file, lines };\n  const parseError = doc.errors[0];\n  if (parseError !== undefined) {\n    const line = parseError.linePos?.[0]?.line;\n    return invalid(\n      `${file}${line === undefined ? \"\" : `:${line}`} cannot be read as YAML — ` +\n        `${parseError.message.split(\"\\n\")[0]!}`,\n    );\n  }\n  if (!isMap(doc.contents)) {\n    return invalid(\n      `${file} must be a YAML mapping with a \\`services:\\` list (and optional ` +\n        `\\`subsystems:\\`, \\`externals:\\`, \\`calls:\\`) — the whole document is ` +\n        `${doc.contents === null ? \"empty\" : \"not a mapping\"}.`,\n    );\n  }\n\n  // The top level, fail-closed: a mistyped key is a whole section silently\n  // dropped, which is exactly the partial scaffold this reader must refuse.\n  const sections = new Map<string, unknown>();\n  for (const pair of doc.contents.items as Pair[]) {\n    const key = isScalar(pair.key) && typeof pair.key.value === \"string\" ? pair.key.value : null;\n    if (key === null || !(TOP_KEYS as readonly string[]).includes(key)) {\n      const spelled = key ?? String(pair.key);\n      return invalid(\n        `${at(ctx, pair.key)} — unknown key '${spelled}': the fleet file's keys are ` +\n          `services, subsystems, externals and calls.${hint(spelled, TOP_KEYS)}`,\n      );\n    }\n    sections.set(key, pair.value);\n  }\n\n  // One flat namespace over everything a name can be declared as, because a\n  // call endpoint must name exactly one thing — the same rule the tree walk\n  // enforces over `services/` (`subsystem.name-collision`).\n  const declared = new Map<string, { where: string; role: string }>();\n  const claim = (name: string, where: string, role: string): SeedFileProblem | null => {\n    const held = declared.get(name);\n    if (held !== undefined) {\n      return {\n        kind: \"duplicate\",\n        message:\n          `${where} declares '${name}' as ${role}, but ${held.where} already declares it as ` +\n          `${held.role} — service ids, subsystem names and externals share one flat namespace ` +\n          `(a call endpoint must name exactly one thing). Rename or remove one, then re-run.`,\n      };\n    }\n    declared.set(name, { where, role });\n    return null;\n  };\n\n  const subsystems: SubsystemName[] = [];\n  for (const item of listOf(sections.get(\"subsystems\"))) {\n    const raw = stringOf(item);\n    if (raw === null) return invalid(`${at(ctx, item)} — a subsystems entry must be a string (quote it if YAML reads it as something else).`);\n    const parsed = parseSubsystemName(raw, \"subsystems entry\");\n    if (!parsed.ok) return invalid(`${at(ctx, item)} — ${parsed.problem}`);\n    const dup = claim(raw, at(ctx, item), \"a subsystem\");\n    if (dup !== null) return { ok: false, problem: dup };\n    subsystems.push(parsed.name);\n  }\n\n  const services: SeedService[] = [];\n  /** Deferred so `subsystem: X` can reference a subsystem declared lower in the file. */\n  const subsystemRefs: { id: ServiceId; sub: string; where: string }[] = [];\n  for (const item of listOf(sections.get(\"services\"))) {\n    const entry = serviceEntry(ctx, item);\n    if (\"invalid\" in entry) return invalid(entry.invalid);\n    const parsed = parseServiceId(entry.id, \"services entry\");\n    if (!parsed.ok) return invalid(`${entry.where} — ${parsed.problem}`);\n    const dup = claim(entry.id, entry.where, \"a service\");\n    if (dup !== null) return { ok: false, problem: dup };\n    if (entry.subsystem !== null) subsystemRefs.push({ id: parsed.id, sub: entry.subsystem, where: entry.where });\n    services.push({ id: parsed.id, subsystem: null });\n  }\n  if (services.length === 0) {\n    return invalid(\n      `${file} declares no services — \\`services:\\` is the one required key: list every ` +\n        `service id the fleet has (a bare string, or \\`{ id, subsystem }\\` to file one under a group).`,\n    );\n  }\n\n  const externals: string[] = [];\n  for (const item of listOf(sections.get(\"externals\"))) {\n    const raw = stringOf(item);\n    if (raw === null) return invalid(`${at(ctx, item)} — an externals entry must be a string (quote it if YAML reads it as something else).`);\n    if (dirNameHazard(raw) !== null) {\n      return invalid(\n        `${at(ctx, item)} — '${raw}' cannot be an external's name: externals share the service-id ` +\n          `grammar (start with a letter or digit; letters, digits, '.', '_', '-'; no Windows-reserved ` +\n          `names), because calls name services and externals out of one namespace.`,\n      );\n    }\n    const dup = claim(raw, at(ctx, item), \"an external\");\n    if (dup !== null) return { ok: false, problem: dup };\n    externals.push(raw);\n  }\n\n  // Subsystem references, now that every declaration is in: a `subsystem:`\n  // naming nothing is the second-likeliest typo in the file, and the hint\n  // offers only names the file really declares.\n  const subNames = new Set<string>(subsystems);\n  for (const ref of subsystemRefs) {\n    if (!subNames.has(ref.sub)) {\n      return {\n        ok: false,\n        problem: {\n          kind: \"unknown-subsystem\",\n          message:\n            `${ref.where} files service '${ref.id}' under '${ref.sub}', but \\`subsystems:\\` ` +\n            `declares no '${ref.sub}'.${hint(ref.sub, subsystems)} Add it to subsystems:, ` +\n            `or fix the spelling, then re-run.`,\n        },\n      };\n    }\n  }\n  // The branded name comes from the DECLARATION list, never from a second\n  // parse of the reference: `subsystems:` is where the grammar ran, and the\n  // membership check above proved every reference resolves into it.\n  const bySubName = new Map<string, SubsystemName>(subsystems.map((s) => [s as string, s]));\n  const filed = new Map(subsystemRefs.map((r) => [r.id as string, bySubName.get(r.sub) ?? null]));\n  const seededServices: SeedService[] = services.map((s) => ({\n    id: s.id,\n    subsystem: filed.get(s.id) ?? null,\n  }));\n\n  const endpointProblem = (raw: string, name: string, where: string): SeedFileProblem => {\n    if (subNames.has(name)) {\n      return {\n        kind: \"unknown-endpoint\",\n        message:\n          `${where} — call '${raw}' names the subsystem '${name}': a subsystem is a place ` +\n          `services live, never a call endpoint. Name one of its services instead.`,\n      };\n    }\n    return {\n      kind: \"unknown-endpoint\",\n      message:\n        `${where} — call '${raw}' names '${name}', which no services: or externals: entry ` +\n        `declares.${hint(name, [...services.map((s) => s.id), ...externals])} Declare it, ` +\n        `or fix the spelling, then re-run.`,\n    };\n  };\n  const callable = new Set<string>([...services.map((s) => s.id), ...externals]);\n  const calls: SeedCall[] = [];\n  const seenCalls = new Set<string>();\n  for (const item of listOf(sections.get(\"calls\"))) {\n    const raw = stringOf(item);\n    if (raw === null) return invalid(`${at(ctx, item)} — a calls entry must be a string of the form 'caller -> callee'.`);\n    const m = /^(\\S+)\\s*->\\s*(\\S+)$/.exec(raw.trim());\n    if (m === null) {\n      return invalid(`${at(ctx, item)} — a call is written 'caller -> callee' (got '${raw}').`);\n    }\n    const [from, to] = [m[1]!, m[2]!];\n    for (const end of [from, to]) {\n      if (!callable.has(end)) return { ok: false, problem: endpointProblem(raw, end, at(ctx, item)) };\n    }\n    // LikeC4 has no self-edge: it reads `a -> a` as a parent-child\n    // relationship and refuses the whole file. Caught HERE, with the line,\n    // because the alternative is the self-check refusing `internal` over a\n    // fleet file whose fault it is not — and a copy-paste inside `calls:` is\n    // exactly how this line gets written.\n    if (from === to) {\n      return invalid(\n        `${at(ctx, item)} — call '${raw}' names '${from}' at both ends, and LikeC4 has no ` +\n          `self-edge (it reads 'a -> a' as a parent-child relationship). Name the other ` +\n          `endpoint, or drop the line.`,\n      );\n    }\n    const key = `${from} ${to}`;\n    // A repeated line is the same fact stated twice, not a second edge.\n    if (seenCalls.has(key)) continue;\n    seenCalls.add(key);\n    calls.push({ from, to });\n  }\n\n  return { ok: true, seed: { services: seededServices, subsystems, externals, calls } };\n}\n"]}

package/dist/core/c4/seed/items.js

@@ -0,0 +1,91 @@
+/**
+ * One fleet.yaml item, read off the AST: the section-item and scalar readers,
+ * the `file:line` addressing every refusal opens with, and the one composite
+ * entry shape (`services:`'s string-or-mapping item). Split from
+ * `./fleet-file.ts` on the phase seam — this module answers "what does this
+ * NODE say, and where is it", while fleet-file owns what the answers must
+ * amount to (grammar, the flat namespace, reference resolution).
+ *
+ * `serviceEntry` reports its refusals as a plain `invalid` sentence rather
+ * than the reader's discriminated problem union, deliberately: every shape
+ * failure at item level maps to `seed-file-invalid`, and returning the
+ * sentence keeps this module free of the domain union — the import points
+ * fleet-file → items only, never back.
+ */
+import { isMap, isScalar, isSeq } from "yaml";
+import { closeIds } from "../arch.js";
+/** `file:line` for a node, or just the file when the node carries no range. */
+export function at(ctx, node) {
+    const range = node.range;
+    if (range === undefined || range === null)
+        return ctx.file;
+    return `${ctx.file}:${ctx.lines.linePos(range[0]).line}`;
+}
+/** A did-you-mean clause over real names, or the empty string. */
+export function hint(name, pool) {
+    const close = closeIds(name, [...pool]);
+    return close.length === 0 ? "" : ` Did you mean ${close.map((c) => `'${c}'`).join(" or ")}?`;
+}
+/**
+ * A section's items. An absent key and a key with nothing under it are both
+ * the empty list — clearing out the last entry must not require deleting the
+ * heading too. A non-sequence value comes back as ONE item, which reads
+ * `services: checkout` as the one-entry list it plainly means and hands
+ * everything else — a number, a mapping under `calls:` — to the caller's
+ * per-item type check, which refuses it with the node's own line.
+ */
+export function listOf(node) {
+    if (node === undefined || node === null)
+        return [];
+    // `parseDocument` gives a heading with nothing under it a Scalar HOLDING
+    // null, never a bare null, so the emptied-out section only looks like the
+    // absent one above. Without this arm, deleting the last entry under
+    // `externals:` refuses with "an externals entry must be a string (quote it
+    // if YAML reads it as something else)" — advice about a value that is not
+    // there — and an emptied `services:` shadows the friendly "declares no
+    // services" sentence that exists for exactly that case.
+    if (isScalar(node) && node.value === null)
+        return [];
+    if (isSeq(node))
+        return node.items;
+    return [node];
+}
+/** A scalar's string value, or null when the entry is not a string. */
+export function stringOf(item) {
+    if (!isScalar(item) || typeof item.value !== "string")
+        return null;
+    return item.value;
+}
+/** One services entry: a bare string id, or `{ id, subsystem? }` — nothing else. */
+export function serviceEntry(ctx, item) {
+    const where = at(ctx, item);
+    const bare = stringOf(item);
+    if (bare !== null)
+        return { id: bare, subsystem: null, where };
+    if (!isMap(item)) {
+        return { invalid: `${where} — a services entry is a string id, or a mapping with \`id\` and optional \`subsystem\`.` };
+    }
+    let id = null;
+    let subsystem = null;
+    for (const pair of item.items) {
+        const key = isScalar(pair.key) && typeof pair.key.value === "string" ? pair.key.value : null;
+        const value = stringOf(pair.value);
+        if (key === "id" && value !== null)
+            id = value;
+        else if (key === "subsystem" && value !== null)
+            subsystem = value;
+        else {
+            const spelled = key ?? String(pair.key);
+            return {
+                invalid: `${at(ctx, pair.key)} — a services entry takes \`id\` and optional \`subsystem\` ` +
+                    `(both strings); '${spelled}' is ${key === "id" || key === "subsystem" ? "not a string here" : "not one of them"}.` +
+                    `${hint(spelled, ["id", "subsystem"])}`,
+            };
+        }
+    }
+    if (id === null) {
+        return { invalid: `${where} — a services mapping entry must carry \`id\`.` };
+    }
+    return { id, subsystem, where };
+}
+//# sourceMappingURL=items.js.map

package/dist/core/c4/seed/items.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"items.js","sourceRoot":"","sources":["../../../../src/core/c4/seed/items.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * One fleet.yaml item, read off the AST: the section-item and scalar readers,\n * the `file:line` addressing every refusal opens with, and the one composite\n * entry shape (`services:`'s string-or-mapping item). Split from\n * `./fleet-file.ts` on the phase seam — this module answers \"what does this\n * NODE say, and where is it\", while fleet-file owns what the answers must\n * amount to (grammar, the flat namespace, reference resolution).\n *\n * `serviceEntry` reports its refusals as a plain `invalid` sentence rather\n * than the reader's discriminated problem union, deliberately: every shape\n * failure at item level maps to `seed-file-invalid`, and returning the\n * sentence keeps this module free of the domain union — the import points\n * fleet-file → items only, never back.\n */\nimport { isMap, isScalar, isSeq, type LineCounter, type Pair } from \"yaml\";\nimport { closeIds } from \"../arch.js\";\n\n/** What the readers walk with: the display path and the offset→line map. */\nexport interface SeedCtx {\n  readonly file: string;\n  readonly lines: LineCounter;\n}\n\n/** `file:line` for a node, or just the file when the node carries no range. */\nexport function at(ctx: SeedCtx, node: unknown): string {\n  const range = (node as { range?: readonly [number, number, number] | null }).range;\n  if (range === undefined || range === null) return ctx.file;\n  return `${ctx.file}:${ctx.lines.linePos(range[0]).line}`;\n}\n\n/** A did-you-mean clause over real names, or the empty string. */\nexport function hint(name: string, pool: readonly string[]): string {\n  const close = closeIds(name, [...pool]);\n  return close.length === 0 ? \"\" : ` Did you mean ${close.map((c) => `'${c}'`).join(\" or \")}?`;\n}\n\n/**\n * A section's items. An absent key and a key with nothing under it are both\n * the empty list — clearing out the last entry must not require deleting the\n * heading too. A non-sequence value comes back as ONE item, which reads\n * `services: checkout` as the one-entry list it plainly means and hands\n * everything else — a number, a mapping under `calls:` — to the caller's\n * per-item type check, which refuses it with the node's own line.\n */\nexport function listOf(node: unknown): unknown[] {\n  if (node === undefined || node === null) return [];\n  // `parseDocument` gives a heading with nothing under it a Scalar HOLDING\n  // null, never a bare null, so the emptied-out section only looks like the\n  // absent one above. Without this arm, deleting the last entry under\n  // `externals:` refuses with \"an externals entry must be a string (quote it\n  // if YAML reads it as something else)\" — advice about a value that is not\n  // there — and an emptied `services:` shadows the friendly \"declares no\n  // services\" sentence that exists for exactly that case.\n  if (isScalar(node) && node.value === null) return [];\n  if (isSeq(node)) return node.items;\n  return [node];\n}\n\n/** A scalar's string value, or null when the entry is not a string. */\nexport function stringOf(item: unknown): string | null {\n  if (!isScalar(item) || typeof item.value !== \"string\") return null;\n  return item.value;\n}\n\nexport type ServiceEntryRead =\n  | { id: string; subsystem: string | null; where: string }\n  | { invalid: string };\n\n/** One services entry: a bare string id, or `{ id, subsystem? }` — nothing else. */\nexport function serviceEntry(ctx: SeedCtx, item: unknown): ServiceEntryRead {\n  const where = at(ctx, item);\n  const bare = stringOf(item);\n  if (bare !== null) return { id: bare, subsystem: null, where };\n  if (!isMap(item)) {\n    return { invalid: `${where} — a services entry is a string id, or a mapping with \\`id\\` and optional \\`subsystem\\`.` };\n  }\n  let id: string | null = null;\n  let subsystem: string | null = null;\n  for (const pair of item.items as Pair[]) {\n    const key = isScalar(pair.key) && typeof pair.key.value === \"string\" ? pair.key.value : null;\n    const value = stringOf(pair.value);\n    if (key === \"id\" && value !== null) id = value;\n    else if (key === \"subsystem\" && value !== null) subsystem = value;\n    else {\n      const spelled = key ?? String(pair.key);\n      return {\n        invalid:\n          `${at(ctx, pair.key)} — a services entry takes \\`id\\` and optional \\`subsystem\\` ` +\n          `(both strings); '${spelled}' is ${key === \"id\" || key === \"subsystem\" ? \"not a string here\" : \"not one of them\"}.` +\n          `${hint(spelled, [\"id\", \"subsystem\"])}`,\n      };\n    }\n  }\n  if (id === null) {\n    return { invalid: `${where} — a services mapping entry must carry \\`id\\`.` };\n  }\n  return { id, subsystem, where };\n}\n"]}

package/dist/core/c4/seed/stamp.js

@@ -0,0 +1,48 @@
+/**
+ * The generated-by stamp on a seeded landscape: line 1, self-verifying, no
+ * state anywhere else. `loam seed` may regenerate the fleet map wholesale
+ * exactly when it can PROVE no human work would be lost, and the only proof
+ * that needs no side channel is the file testifying about itself — a digest of
+ * every byte after the stamp line, written into the stamp line. A database of
+ * "files loam wrote" would be a second source of truth that drifts the first
+ * time somebody copies a docs repo; the digest travels with the bytes it
+ * covers.
+ *
+ * The stamp is recognised by its PREFIX and digest alone — the prose after the
+ * digest is free to be reworded (it is advice to a reader, not part of the
+ * proof), so a future loam rewording the sentence still recognises every file
+ * an older loam sealed. The digest covers everything after the first newline,
+ * with line endings normalised out: `core.autocrlf` is Git for Windows'
+ * installer default and the docs repo ships no `.gitattributes`, so an
+ * ordinary Windows clone of a seeded landscape rewrites every line of it and
+ * changes not one fact. Calling that "hand-edited" would stand `loam seed`
+ * against `loam status`, which reads the same file through
+ * `isLandscapeStub`'s CRLF-normalised compare and tells the reader to run
+ * seed. What the digest proves is that the CONTENT is still a pure function of
+ * fleet.yaml — which is what "no human work here" means.
+ */
+import { createHash } from "node:crypto";
+const STAMP_PREFIX = "// loam-seed sha256:";
+/** Line 1 must OPEN with the prefix and a full digest; the prose after is free. */
+const STAMP_LINE = /^\/\/ loam-seed sha256:([0-9a-f]{64})(?:\s|$)/;
+/** The digest the stamp carries: content, with line endings normalised out. See the header. */
+function digestOf(body) {
+    return createHash("sha256").update(body.replace(/\r\n/g, "\n"), "utf8").digest("hex");
+}
+/** Prepend the self-verifying stamp line to a rendered landscape body. */
+export function sealLandscape(body) {
+    return (`${STAMP_PREFIX}${digestOf(body)} — generated from fleet.yaml by \`loam seed\`. ` +
+        "Hand edits make this file yours: seed will then refuse to regenerate it.\n" +
+        body);
+}
+/** Classify a landscape's text by its own testimony. See {@link LandscapeProvenance}. */
+export function landscapeProvenance(text) {
+    const newline = text.indexOf("\n");
+    const first = newline === -1 ? text : text.slice(0, newline);
+    const m = STAMP_LINE.exec(first);
+    if (m === null)
+        return "foreign";
+    const body = newline === -1 ? "" : text.slice(newline + 1);
+    return digestOf(body) === m[1] ? "seed-stamped" : "seed-edited";
+}
+//# sourceMappingURL=stamp.js.map

package/dist/core/c4/seed/stamp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stamp.js","sourceRoot":"","sources":["../../../../src/core/c4/seed/stamp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAezC,MAAM,YAAY,GAAG,sBAAsB,CAAC;AAE5C,mFAAmF;AACnF,MAAM,UAAU,GAAG,+CAA+C,CAAC;AAEnE,+FAA+F;AAC/F,SAAS,QAAQ,CAAC,IAAY;IAC5B,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACxF,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,OAAO,CACL,GAAG,YAAY,GAAG,QAAQ,CAAC,IAAI,CAAC,iDAAiD;QACjF,4EAA4E;QAC5E,IAAI,CACL,CAAC;AACJ,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,KAAK,GAAG,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IAC7D,MAAM,CAAC,GAAG,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACjC,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IACjC,MAAM,IAAI,GAAG,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC;IAC3D,OAAO,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,aAAa,CAAC;AAClE,CAAC","sourcesContent":["/**\n * The generated-by stamp on a seeded landscape: line 1, self-verifying, no\n * state anywhere else. `loam seed` may regenerate the fleet map wholesale\n * exactly when it can PROVE no human work would be lost, and the only proof\n * that needs no side channel is the file testifying about itself — a digest of\n * every byte after the stamp line, written into the stamp line. A database of\n * \"files loam wrote\" would be a second source of truth that drifts the first\n * time somebody copies a docs repo; the digest travels with the bytes it\n * covers.\n *\n * The stamp is recognised by its PREFIX and digest alone — the prose after the\n * digest is free to be reworded (it is advice to a reader, not part of the\n * proof), so a future loam rewording the sentence still recognises every file\n * an older loam sealed. The digest covers everything after the first newline,\n * with line endings normalised out: `core.autocrlf` is Git for Windows'\n * installer default and the docs repo ships no `.gitattributes`, so an\n * ordinary Windows clone of a seeded landscape rewrites every line of it and\n * changes not one fact. Calling that \"hand-edited\" would stand `loam seed`\n * against `loam status`, which reads the same file through\n * `isLandscapeStub`'s CRLF-normalised compare and tells the reader to run\n * seed. What the digest proves is that the CONTENT is still a pure function of\n * fleet.yaml — which is what \"no human work here\" means.\n */\nimport { createHash } from \"node:crypto\";\n\n/**\n * What the landscape's bytes say about who wrote them:\n *\n * - `seed-stamped` — the stamp is present and its digest matches: every byte\n *   is a pure function of fleet.yaml, so regenerating loses nothing.\n * - `seed-edited` — the stamp is present but the digest does not match: a\n *   human edited a seeded file, and those edits are theirs to keep.\n * - `foreign` — no stamp: the file was authored some other way (by hand, or by\n *   the scaffold; the caller recognises the scaffold's stub separately, through\n *   `isLandscapeStub`, because the stub predates the stamp).\n */\nexport type LandscapeProvenance = \"seed-stamped\" | \"seed-edited\" | \"foreign\";\n\nconst STAMP_PREFIX = \"// loam-seed sha256:\";\n\n/** Line 1 must OPEN with the prefix and a full digest; the prose after is free. */\nconst STAMP_LINE = /^\\/\\/ loam-seed sha256:([0-9a-f]{64})(?:\\s|$)/;\n\n/** The digest the stamp carries: content, with line endings normalised out. See the header. */\nfunction digestOf(body: string): string {\n  return createHash(\"sha256\").update(body.replace(/\\r\\n/g, \"\\n\"), \"utf8\").digest(\"hex\");\n}\n\n/** Prepend the self-verifying stamp line to a rendered landscape body. */\nexport function sealLandscape(body: string): string {\n  return (\n    `${STAMP_PREFIX}${digestOf(body)} — generated from fleet.yaml by \\`loam seed\\`. ` +\n    \"Hand edits make this file yours: seed will then refuse to regenerate it.\\n\" +\n    body\n  );\n}\n\n/** Classify a landscape's text by its own testimony. See {@link LandscapeProvenance}. */\nexport function landscapeProvenance(text: string): LandscapeProvenance {\n  const newline = text.indexOf(\"\\n\");\n  const first = newline === -1 ? text : text.slice(0, newline);\n  const m = STAMP_LINE.exec(first);\n  if (m === null) return \"foreign\";\n  const body = newline === -1 ? \"\" : text.slice(newline + 1);\n  return digestOf(body) === m[1] ? \"seed-stamped\" : \"seed-edited\";\n}\n"]}