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

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":"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","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"]}

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

@@ -0,0 +1,173 @@
+/**
+ * A LikeC4 identifier for a declared name, mechanically: `.` and `-` become
+ * `_`, and the result takes its kind's prefix — `svc_` for a service, `ext_`
+ * for an external.
+ *
+ * The prefix is not decoration, and not only about the digit-initial case
+ * (LikeC4 identifiers are letter/underscore-initial). LikeC4's KEYWORDS are
+ * bare lowercase words — `notes`, `tag`, `view`, `metadata`, `style`, `link`,
+ * `import`, `description`, `size`, `line`, `this` and some thirty more — and a
+ * service legally named `notes` emitted as a bare `notes = softwareSystem`
+ * does not parse. The self-check would catch that, but only to refuse a fleet
+ * whose fault it is not, under `internal`, with no fix to offer. No keyword
+ * contains `_`, so a prefixed identifier is PROVABLY not one — at this LikeC4
+ * version and at every later one. A reserved-word list here would be the same
+ * bug again, rotting the first time the language grew a word.
+ *
+ * The fold is not injective — `a-b` and `a.b` both give `a_b` — so residual
+ * collisions take a deterministic numeric suffix in sorted processing order.
+ * Aesthetics do not matter here: the binding metadata, not the element id, is
+ * the element's identity to loam.
+ */
+function foldName(name, kind) {
+    return `${kind}_${name.replace(/[.-]/g, "_")}`;
+}
+/**
+ * The element id loam SUGGESTS for a service no map draws yet — this seed's
+ * own convention, exported so it is the only one. The adopt brief and the
+ * `loam new` delta used to camel-case the directory name instead, so a seeded
+ * fleet received three spellings of one box (`svc_payment_service` on the
+ * map, `paymentService` in every brief and scaffold), and a delta that reused
+ * the scaffold's guess never lined up with the map it was told to match. The
+ * id stays cosmetic — `metadata { service '<id>' }` is the join — but a
+ * suggestion gets pasted, so it has to be one spelling, and the keyword-proof
+ * one above is the one already on disk in every seeded repo.
+ */
+export function serviceElementId(service) {
+    return foldName(service, "svc");
+}
+/** Element ids for every declared name (services ∪ externals), collision-suffixed deterministically. */
+function elementIds(seed) {
+    const ids = new Map();
+    const used = new Set();
+    const named = [
+        ...[...seed.services]
+            .map((s) => s.id)
+            .sort()
+            .map((n) => [n, "svc"]),
+        ...[...seed.externals].sort().map((n) => [n, "ext"]),
+    ];
+    for (const [name, kind] of named) {
+        let candidate = foldName(name, kind);
+        for (let n = 2; used.has(candidate); n += 1)
+            candidate = `${foldName(name, kind)}_${n}`;
+        used.add(candidate);
+        ids.set(name, candidate);
+    }
+    return ids;
+}
+/** Render the landscape body (unstamped — `sealLandscape` adds line 1). */
+export function renderLandscape(seed) {
+    const ids = elementIds(seed);
+    // Every name reaching `el` was declared (calls are validated against
+    // services ∪ externals before rendering), so the fallback is unreachable —
+    // it exists so a future caller cannot get a silent `undefined` into the DSL.
+    const el = (name) => ids.get(name) ?? foldName(name, "svc");
+    const lines = [
+        "// Generated from fleet.yaml by `loam seed` — edit fleet.yaml and re-run to",
+        "// regenerate. Hand edits make this file yours: the stamp on line 1 is how",
+        "// seed tells, and it will then refuse to touch the file again.",
+        "//",
+        "// As contracts arrive, give each call the operationId it uses, so",
+        "// requirements, C4 and OpenAPI can be cross-checked:",
+        "//",
+        "//   svc_checkout -> svc_payment_service 'Calls authorizePayment' {",
+        "//     metadata { op 'authorizePayment' }",
+        "//   }",
+        "",
+        "specification {",
+        "  element person",
+        "  element softwareSystem",
+        "  element container",
+        "  element database",
+        "",
+        "  // #platform keeps ubiquitous infrastructure out of the fleet view;",
+        "  // #external marks somebody else's system, so validate does not ask for a",
+        "  // services/ directory nobody owes. A tag must be declared before it is",
+        "  // used, so both are declared here whether or not this fleet uses them.",
+        "  tag platform",
+        "  tag external",
+        // The relationship kinds are DUPLICATED from core/scaffold/landscape.ts's
+        // LANDSCAPE_STUB for the views block's reason below, and test/seed.test.ts
+        // compares the two byte for byte the same way. Declared, never used: the
+        // calls below stay plain edges, because fleet.yaml says who calls whom and
+        // has no spelling for what an edge carries — choosing a kind here would be
+        // the guess this templater exists not to make. Declaring them is what lets
+        // the adoptions and feature deltas that follow draw kinded edges into this
+        // map, and lets an archive that copies one in still parse.
+        "",
+        "  // One kind per kind of traffic, each with one direction. The style is the",
+        "  // picture: amber for messages, green for data at rest, gray and dashed for",
+        "  // a connection nobody has given a direction yet. Never tag a kind: LikeC4",
+        "  // copies a kind's tags onto every edge of it.",
+        "  relationship publishes {",
+        "    color amber",
+        "    line solid",
+        "    head normal",
+        "  }",
+        "  relationship delivers {",
+        "    color amber",
+        "    line solid",
+        "    head normal",
+        "  }",
+        "  relationship reads {",
+        "    color green",
+        "    head none",
+        "    tail normal",
+        "  }",
+        "  relationship writes {",
+        "    color green",
+        "    head normal",
+        "  }",
+        "  relationship readsWrites {",
+        "    color green",
+        "    head normal",
+        "    tail normal",
+        "  }",
+        "  relationship calls {",
+        "    color secondary",
+        "    line solid",
+        "    head normal",
+        "  }",
+        "  relationship connects {",
+        "    color gray",
+        "    line dashed",
+        "    head none",
+        "    // A marker at the source: an edge with no arrowhead at either end is laid",
+        "    // out unconstrained, and enough of them flatten a view into one band.",
+        "    tail odot",
+        "  }",
+        "}",
+        "",
+        "model {",
+    ];
+    const services = [...seed.services].sort((a, b) => (a.id < b.id ? -1 : 1));
+    for (const s of services) {
+        lines.push(`  ${el(s.id)} = softwareSystem '${s.id}' {`);
+        lines.push(`    metadata { service '${s.id}' }`);
+        lines.push("  }");
+    }
+    const externals = [...seed.externals].sort();
+    for (const x of externals) {
+        lines.push(`  ${el(x)} = softwareSystem '${x}' {`);
+        lines.push("    #external");
+        lines.push("  }");
+    }
+    const calls = [...seed.calls].sort((a, b) => a.from === b.from ? (a.to < b.to ? -1 : 1) : a.from < b.from ? -1 : 1);
+    if (calls.length > 0)
+        lines.push("");
+    for (const c of calls)
+        lines.push(`  ${el(c.from)} -> ${el(c.to)}`);
+    lines.push("}");
+    // The views block below is DUPLICATED from core/docs.ts's LANDSCAPE_STUB
+    // (two copies — extract on a third, per the house rule). The tripwire in
+    // test/seed.test.ts compares the two blocks BYTE FOR BYTE, comments and
+    // wrapping included, so whichever copy drifts fails the suite — a
+    // view-names-only compare let a corrected predicate land in one copy and
+    // leave every seeded fleet map rendering the old one.
+    // The emitted comment speaks to the docs repo's reader, not to loam's:
+    // internal paths mean nothing where this file lands.
+    lines.push("", "// The views are for LikeC4's own tooling — loam reads the model and never", "// a view. Render with `npx likec4 start` from the docs repo root. Tag", "// ubiquitous infrastructure #platform to keep the fleet view readable.", "views {", "  view fleet {", "    include *", "    exclude element.tag = #platform", "  }", "  // The obvious spelling — `include element.tag = #platform` — draws the", "  // platform boxes with NO edges and no consumers. The predicate that works is", "  // the relationship form below.", "  view platform {", "    include * -> element.tag = #platform", "  }", "}");
+    return lines.join("\n") + "\n";
+}
+//# sourceMappingURL=template.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"template.js","sourceRoot":"","sources":["../../../../src/core/c4/seed/template.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * FleetSeed → landscape DSL body: a pure, deterministic function — identical\n * fleet.yaml, identical bytes, on any machine — because the stamp\n * (`./stamp.ts`) digests the output and a nondeterministic templater would\n * read as hand-edited on the next run.\n *\n * The DSL shape is deliberately minimal: one bound `softwareSystem` per\n * service (the `metadata { service '<id>' }` binding is what every loam join\n * reads — element ids are cosmetic), `#external` systems for the externals,\n * and PLAIN edges. No operationIds: those arrive with contracts, and a\n * templated guess would be the extractor this command exists not to be. No\n * relationship kinds on the edges either, for the same reason — but the kinds\n * themselves are DECLARED, as the scaffold's stub declares them, so whatever\n * draws the next edge can name one.\n */\nimport type { FleetSeed } from \"./fleet-file.js\";\n\n/** Which kind of declared name an element id is being built for. */\ntype ElementKind = \"svc\" | \"ext\";\n\n/**\n * A LikeC4 identifier for a declared name, mechanically: `.` and `-` become\n * `_`, and the result takes its kind's prefix — `svc_` for a service, `ext_`\n * for an external.\n *\n * The prefix is not decoration, and not only about the digit-initial case\n * (LikeC4 identifiers are letter/underscore-initial). LikeC4's KEYWORDS are\n * bare lowercase words — `notes`, `tag`, `view`, `metadata`, `style`, `link`,\n * `import`, `description`, `size`, `line`, `this` and some thirty more — and a\n * service legally named `notes` emitted as a bare `notes = softwareSystem`\n * does not parse. The self-check would catch that, but only to refuse a fleet\n * whose fault it is not, under `internal`, with no fix to offer. No keyword\n * contains `_`, so a prefixed identifier is PROVABLY not one — at this LikeC4\n * version and at every later one. A reserved-word list here would be the same\n * bug again, rotting the first time the language grew a word.\n *\n * The fold is not injective — `a-b` and `a.b` both give `a_b` — so residual\n * collisions take a deterministic numeric suffix in sorted processing order.\n * Aesthetics do not matter here: the binding metadata, not the element id, is\n * the element's identity to loam.\n */\nfunction foldName(name: string, kind: ElementKind): string {\n  return `${kind}_${name.replace(/[.-]/g, \"_\")}`;\n}\n\n/**\n * The element id loam SUGGESTS for a service no map draws yet — this seed's\n * own convention, exported so it is the only one. The adopt brief and the\n * `loam new` delta used to camel-case the directory name instead, so a seeded\n * fleet received three spellings of one box (`svc_payment_service` on the\n * map, `paymentService` in every brief and scaffold), and a delta that reused\n * the scaffold's guess never lined up with the map it was told to match. The\n * id stays cosmetic — `metadata { service '<id>' }` is the join — but a\n * suggestion gets pasted, so it has to be one spelling, and the keyword-proof\n * one above is the one already on disk in every seeded repo.\n */\nexport function serviceElementId(service: string): string {\n  return foldName(service, \"svc\");\n}\n\n/** Element ids for every declared name (services ∪ externals), collision-suffixed deterministically. */\nfunction elementIds(seed: FleetSeed): Map<string, string> {\n  const ids = new Map<string, string>();\n  const used = new Set<string>();\n  const named: Array<readonly [string, ElementKind]> = [\n    ...[...seed.services]\n      .map((s) => s.id as string)\n      .sort()\n      .map((n) => [n, \"svc\"] as const),\n    ...[...seed.externals].sort().map((n) => [n, \"ext\"] as const),\n  ];\n  for (const [name, kind] of named) {\n    let candidate = foldName(name, kind);\n    for (let n = 2; used.has(candidate); n += 1) candidate = `${foldName(name, kind)}_${n}`;\n    used.add(candidate);\n    ids.set(name, candidate);\n  }\n  return ids;\n}\n\n/** Render the landscape body (unstamped — `sealLandscape` adds line 1). */\nexport function renderLandscape(seed: FleetSeed): string {\n  const ids = elementIds(seed);\n  // Every name reaching `el` was declared (calls are validated against\n  // services ∪ externals before rendering), so the fallback is unreachable —\n  // it exists so a future caller cannot get a silent `undefined` into the DSL.\n  const el = (name: string): string => ids.get(name) ?? foldName(name, \"svc\");\n\n  const lines: string[] = [\n    \"// Generated from fleet.yaml by `loam seed` — edit fleet.yaml and re-run to\",\n    \"// regenerate. Hand edits make this file yours: the stamp on line 1 is how\",\n    \"// seed tells, and it will then refuse to touch the file again.\",\n    \"//\",\n    \"// As contracts arrive, give each call the operationId it uses, so\",\n    \"// requirements, C4 and OpenAPI can be cross-checked:\",\n    \"//\",\n    \"//   svc_checkout -> svc_payment_service 'Calls authorizePayment' {\",\n    \"//     metadata { op 'authorizePayment' }\",\n    \"//   }\",\n    \"\",\n    \"specification {\",\n    \"  element person\",\n    \"  element softwareSystem\",\n    \"  element container\",\n    \"  element database\",\n    \"\",\n    \"  // #platform keeps ubiquitous infrastructure out of the fleet view;\",\n    \"  // #external marks somebody else's system, so validate does not ask for a\",\n    \"  // services/ directory nobody owes. A tag must be declared before it is\",\n    \"  // used, so both are declared here whether or not this fleet uses them.\",\n    \"  tag platform\",\n    \"  tag external\",\n    // The relationship kinds are DUPLICATED from core/scaffold/landscape.ts's\n    // LANDSCAPE_STUB for the views block's reason below, and test/seed.test.ts\n    // compares the two byte for byte the same way. Declared, never used: the\n    // calls below stay plain edges, because fleet.yaml says who calls whom and\n    // has no spelling for what an edge carries — choosing a kind here would be\n    // the guess this templater exists not to make. Declaring them is what lets\n    // the adoptions and feature deltas that follow draw kinded edges into this\n    // map, and lets an archive that copies one in still parse.\n    \"\",\n    \"  // One kind per kind of traffic, each with one direction. The style is the\",\n    \"  // picture: amber for messages, green for data at rest, gray and dashed for\",\n    \"  // a connection nobody has given a direction yet. Never tag a kind: LikeC4\",\n    \"  // copies a kind's tags onto every edge of it.\",\n    \"  relationship publishes {\",\n    \"    color amber\",\n    \"    line solid\",\n    \"    head normal\",\n    \"  }\",\n    \"  relationship delivers {\",\n    \"    color amber\",\n    \"    line solid\",\n    \"    head normal\",\n    \"  }\",\n    \"  relationship reads {\",\n    \"    color green\",\n    \"    head none\",\n    \"    tail normal\",\n    \"  }\",\n    \"  relationship writes {\",\n    \"    color green\",\n    \"    head normal\",\n    \"  }\",\n    \"  relationship readsWrites {\",\n    \"    color green\",\n    \"    head normal\",\n    \"    tail normal\",\n    \"  }\",\n    \"  relationship calls {\",\n    \"    color secondary\",\n    \"    line solid\",\n    \"    head normal\",\n    \"  }\",\n    \"  relationship connects {\",\n    \"    color gray\",\n    \"    line dashed\",\n    \"    head none\",\n    \"    // A marker at the source: an edge with no arrowhead at either end is laid\",\n    \"    // out unconstrained, and enough of them flatten a view into one band.\",\n    \"    tail odot\",\n    \"  }\",\n    \"}\",\n    \"\",\n    \"model {\",\n  ];\n\n  const services = [...seed.services].sort((a, b) => (a.id < b.id ? -1 : 1));\n  for (const s of services) {\n    lines.push(`  ${el(s.id)} = softwareSystem '${s.id}' {`);\n    lines.push(`    metadata { service '${s.id}' }`);\n    lines.push(\"  }\");\n  }\n  const externals = [...seed.externals].sort();\n  for (const x of externals) {\n    lines.push(`  ${el(x)} = softwareSystem '${x}' {`);\n    lines.push(\"    #external\");\n    lines.push(\"  }\");\n  }\n  const calls = [...seed.calls].sort((a, b) =>\n    a.from === b.from ? (a.to < b.to ? -1 : 1) : a.from < b.from ? -1 : 1,\n  );\n  if (calls.length > 0) lines.push(\"\");\n  for (const c of calls) lines.push(`  ${el(c.from)} -> ${el(c.to)}`);\n  lines.push(\"}\");\n\n  // The views block below is DUPLICATED from core/docs.ts's LANDSCAPE_STUB\n  // (two copies — extract on a third, per the house rule). The tripwire in\n  // test/seed.test.ts compares the two blocks BYTE FOR BYTE, comments and\n  // wrapping included, so whichever copy drifts fails the suite — a\n  // view-names-only compare let a corrected predicate land in one copy and\n  // leave every seeded fleet map rendering the old one.\n  // The emitted comment speaks to the docs repo's reader, not to loam's:\n  // internal paths mean nothing where this file lands.\n  lines.push(\n    \"\",\n    \"// The views are for LikeC4's own tooling — loam reads the model and never\",\n    \"// a view. Render with `npx likec4 start` from the docs repo root. Tag\",\n    \"// ubiquitous infrastructure #platform to keep the fleet view readable.\",\n    \"views {\",\n    \"  view fleet {\",\n    \"    include *\",\n    \"    exclude element.tag = #platform\",\n    \"  }\",\n    \"  // The obvious spelling — `include element.tag = #platform` — draws the\",\n    \"  // platform boxes with NO edges and no consumers. The predicate that works is\",\n    \"  // the relationship form below.\",\n    \"  view platform {\",\n    \"    include * -> element.tag = #platform\",\n    \"  }\",\n    \"}\",\n  );\n  return lines.join(\"\\n\") + \"\\n\";\n}\n"]}