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

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":"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","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/**\n * One `id -> service` resolver per document, not one per lookup.\n *\n * `serviceOf` builds a fresh id map on every call, and this axis calls it twice\n * for every relationship in scope — inside loops that already run over every\n * relationship a service can see. `serviceResolver`'s own doc says it is \"built\n * once per document and shared\"; this is where both axes that need it keep\n * that promise — `../arch.ts`'s `coversEdge` and `./steps.ts`'s `resolvedTier`,\n * each exported and each handed only the element array.\n *\n * A module-level cache is normally the wrong shape here, because a command runs\n * against whatever directory it was invoked in. This one is safe: the key is the\n * per-invocation `Elem[]` a parse produced, its value is a pure function of that\n * key alone, and nothing in it is derived from the working directory — so two\n * runs can never see each other's answer, and the entry dies with the document.\n * Nothing mutates an `Elem[]` after parse.\n *\n * Two tiers because the fleet set is part of the answer: the same document\n * resolves differently with and without `known`, so a cache keyed on the\n * elements alone handed a with-fleet caller the without-fleet resolver.\n * Callers build ONE set per run and pass the same instance through, which is\n * what lets the inner WeakMap key on the set's identity.\n */\nconst RESOLVERS = new WeakMap<Elem[], (id: string) => string>();\nconst FLEET_RESOLVERS = new WeakMap<Elem[], WeakMap<ReadonlySet<string>, (id: string) => string>>();\n\nexport function resolverFor(elements: Elem[], known?: ReadonlySet<string>): (id: string) => string {\n  if (known === undefined) {\n    const cached = RESOLVERS.get(elements);\n    if (cached !== undefined) return cached;\n    const resolver = serviceResolver(elements);\n    RESOLVERS.set(elements, resolver);\n    return resolver;\n  }\n  let perSet = FLEET_RESOLVERS.get(elements);\n  if (perSet === undefined) {\n    perSet = new WeakMap();\n    FLEET_RESOLVERS.set(elements, perSet);\n  }\n  const cached = perSet.get(known);\n  if (cached !== undefined) return cached;\n  const resolver = serviceResolver(elements, known);\n  perSet.set(known, resolver);\n  return resolver;\n}\n"]}

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

@@ -0,0 +1,144 @@
+/**
+ * Which declared relationship backs one hop of a use case, and what it says the
+ * operation is.
+ *
+ * A `dynamic view`'s hop says "web talks to orders". Answering it is the same
+ * shape of join `Covers:` performs for an edge entry one module over — same two
+ * tiers, same cached `serviceResolver` (`./service.ts`'s `resolverFor`, which
+ * both axes share), same "an endpoint names an element or the service it stands
+ * for" rule.
+ *
+ * It lived in `../arch.ts` while that file was the only home the join had, and
+ * moved here when the Covers grammar grew a fourth entry form and the file
+ * reached its line limit. The move changed nothing: the seam was already named
+ * in that file's own header, and this is the package the resolution it depends
+ * on lives in.
+ *
+ * It does NOT live beside the view reader in `../parsed/dynamic-views.ts`, and
+ * that is a rule rather than a preference: a second copy of this join is the
+ * copy that drifts, and that module may read `$data` and nothing else
+ * (docs/DESIGN.md rule 26) — it has no business holding the model join.
+ */
+import {} from "../likec4.js";
+import { resolverFor } from "./service.js";
+/**
+ * The pair a step's backing relationship is looked up under. This is the half
+ * that mis-grades the whole fleet if it is wrong, because a reply arrow is the
+ * commonest step in any sequence diagram.
+ *
+ * MEASURED at the `likec4@1.59.2` pin, and `test/likec4-view-shape.test.ts` holds
+ * the raw form: a reply written `a <- b 'reply'` parses as
+ * `{source: "b", target: "a", isBackward: true}` — LikeC4 has ALREADY reversed
+ * the endpoints and set the flag — while the forward `b -> a` yields that same
+ * pair with no `isBackward` key at all (ABSENT, not false). So the endpoints as
+ * parsed describe the direction the MESSAGE travels, and the flag records which
+ * arrow the author typed.
+ *
+ * loam attributes a reply to the CALL it answers, so the reversal is undone
+ * here. A landscape declares `web -> orders` because that edge is the
+ * dependency; a mirror `orders -> web` for each response is not something a
+ * fleet writes down. Reading a reply hop under the message's own direction would
+ * report every return hop against such a landscape as `unbacked`, and where a
+ * fleet does draw the mirror edge it would file the two halves of one call under
+ * two operations — the call under `op 'createOrder'`, its reply under none.
+ *
+ * That is deliberately NOT what LikeC4's own computed stage does, and the
+ * difference is measured rather than assumed: that stage resolves a backward
+ * step's `relations` from the UNFLIPPED pair, so at this pin a `web <- orders`
+ * step computes to `relations: []` when only `web -> orders` exists, and to the
+ * mirror edge when only `orders -> web` does. It is answering which arrow to
+ * draw; loam is answering which operation the hop exercises, and reads what a
+ * view DECLARES rather than what it shows — which is why loam never reaches that
+ * stage at all (docs/DESIGN.md rule 26, enforced by `scripts/arch-check.mjs`).
+ * The consequence to know before changing this: where
+ * a fleet declares BOTH directions, the mirror edge is not what backs the reply
+ * here — the call is, and the mirror edge backs only a hop drawn forward along
+ * it.
+ */
+function callPair(step) {
+    return step.isBackward ? { from: step.target, to: step.source } : { from: step.source, to: step.target };
+}
+/**
+ * The distinct `op` values across candidates, first-seen order preserved.
+ *
+ * Absent is a VALUE here, not a gap to skip: a relationship carrying no `op` and
+ * one carrying `createOrder` disagree about the operation just as surely as two
+ * different ops do, and skipping the absent one would silently promote that
+ * disagreement to a confident answer. `includes` rather than a `Set` because a
+ * candidate list is the handful of relationships between one pair of endpoints,
+ * and it keeps `undefined` comparing the way the rest of this file expects.
+ */
+function distinctOps(rels) {
+    const out = [];
+    for (const r of rels)
+        if (!out.includes(r.op))
+            out.push(r.op);
+    return out;
+}
+/**
+ * The verdict one tier's candidates imply, or `undefined` when that tier found
+ * nothing and is therefore not the tier that answers.
+ *
+ * The count that decides is the DISTINCT-OP count, never the candidate count.
+ * That distinction is what makes the service tier safe: once a service is drawn
+ * as containers, `a.api -> b` and `a.worker -> b` both carrying
+ * `op 'createOrder'` are two relationships and one operation, and a verdict read
+ * off `rels.length` would convict a perfectly consistent model of contesting
+ * itself.
+ */
+function verdictOn(pair, tier, rels) {
+    if (rels.length === 0)
+        return undefined;
+    const ops = distinctOps(rels);
+    if (ops.length > 1)
+        return { ...pair, verdict: "contested", tier, rels, ops };
+    // Length is exactly one here, so the single distinct value is the answer —
+    // and `undefined` is a legitimate answer: every candidate agreed that this
+    // hop names no operation.
+    const [only] = ops;
+    return { ...pair, verdict: "attributed", tier, rels, ...(only === undefined ? {} : { op: only }) };
+}
+/**
+ * Relationships whose ENDPOINTS resolve to the same two services as the pair —
+ * the fallback tier, and the reason a step drawn between two services matches an
+ * edge drawn between two containers.
+ *
+ * Through the module's cached `resolverFor`, not a fresh `serviceResolver`: this
+ * runs once per step of every use case in the fleet, and building the id map per
+ * step is the cost that comment above `RESOLVERS` exists to prevent.
+ */
+function resolvedTier(pair, scope) {
+    const resolve = resolverFor(scope.elements, scope.known);
+    const from = resolve(pair.from);
+    const to = resolve(pair.to);
+    return scope.relationships.filter((r) => resolve(r.source) === from && resolve(r.target) === to);
+}
+/**
+ * Which relationship in the model backs one hop of a use case, and what it says
+ * the operation is.
+ *
+ * Two tiers, and the second runs ONLY when the first is empty. That ordering is
+ * load-bearing rather than an optimisation: the service tier necessarily
+ * re-finds every exact match — an endpoint that matches literally resolves to
+ * the same service trivially — so running it unconditionally would let a
+ * container-level edge with a different `op` contest a step the model already
+ * answers exactly, turning an `attributed` verdict into a `contested` one on a
+ * document nobody changed.
+ *
+ * Relationship `kind` is deliberately not part of the match, and that is
+ * measured too: at this pin `a -[http]-> b` without a `relationship http` in the
+ * `specification` block is "Could not resolve reference to RelationshipKind
+ * named 'http'" — a parse error, which under loam's standing rule means no model
+ * at all — and `test/helpers/harness.ts`'s own `LANDSCAPE` declares no
+ * relationship kinds. So narrowing by kind would mean a fix message asking an
+ * author to write a line their document does not parse.
+ */
+export function attributeStep(step, scope) {
+    const pair = callPair(step);
+    const exact = scope.relationships.filter((r) => r.source === pair.from && r.target === pair.to);
+    const declared = verdictOn(pair, 1, exact);
+    if (declared !== undefined)
+        return declared;
+    return verdictOn(pair, 2, resolvedTier(pair, scope)) ?? { ...pair, verdict: "unbacked" };
+}
+//# sourceMappingURL=steps.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"steps.js","sourceRoot":"","sources":["../../../../src/core/c4/resolve/steps.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Which declared relationship backs one hop of a use case, and what it says the\n * operation is.\n *\n * A `dynamic view`'s hop says \"web talks to orders\". Answering it is the same\n * shape of join `Covers:` performs for an edge entry one module over — same two\n * tiers, same cached `serviceResolver` (`./service.ts`'s `resolverFor`, which\n * both axes share), same \"an endpoint names an element or the service it stands\n * for\" rule.\n *\n * It lived in `../arch.ts` while that file was the only home the join had, and\n * moved here when the Covers grammar grew a fourth entry form and the file\n * reached its line limit. The move changed nothing: the seam was already named\n * in that file's own header, and this is the package the resolution it depends\n * on lives in.\n *\n * It does NOT live beside the view reader in `../parsed/dynamic-views.ts`, and\n * that is a rule rather than a preference: a second copy of this join is the\n * copy that drifts, and that module may read `$data` and nothing else\n * (docs/DESIGN.md rule 26) — it has no business holding the model join.\n */\nimport { type Elem, type Rel } from \"../likec4.js\";\nimport { resolverFor } from \"./service.js\";\nimport type { ParsedStep } from \"../parsed/dynamic-views.js\";\n\n/**\n * The three fields an attribution reads off a step, and no more.\n *\n * Narrower than `ParsedStep` on purpose. Attribution must not depend on the\n * ordinal, the title or the notes — a hop is graded by where it points, never by\n * what the author called it — and a signature that says so is also a signature a\n * test can satisfy with a literal instead of a parsed document. Derived from\n * `ParsedStep` rather than restated, so a rename upstream is a compile error\n * here instead of a second definition that quietly disagrees.\n */\nexport type StepEndpoints = Pick<ParsedStep, \"source\" | \"target\" | \"isBackward\">;\n\n/**\n * What a step is attributed against: the model in view, plus the enumerated\n * fleet where the caller has it.\n *\n * A deliberate subset of `CoverageScope` rather than a reuse of it — an\n * attribution never reads `health`, and demanding one would make every caller\n * fabricate an empty `HealthIds` to ask a question that has nothing to do with\n * alerts. A `CoverageScope` is still structurally assignable here, so a caller\n * already holding the fuller scope passes it through unchanged.\n */\nexport interface StepScope {\n  elements: Elem[];\n  relationships: Rel[];\n  /** As `CoverageScope.known`, for the same reason: one set per run, shared. */\n  known?: ReadonlySet<string>;\n}\n\n/** The oriented pair a verdict is about — see `callPair` for which way round. */\ninterface CallPair {\n  from: string;\n  to: string;\n}\n\n/**\n * What the model says about one hop of a use case.\n *\n * Three variants rather than one record with optional fields, because the fields\n * are not independent: `op` is meaningful only when exactly one operation was\n * implied, `ops` only when more than one was, and an unbacked step has neither\n * and no tier either. Tagged, those states stop being constructible.\n *\n *  - `attributed` — the candidates on the matched tier agree, so the hop\n *    exercises exactly one operation. `op` is absent when that one agreed\n *    operation is *no* operation: the relationships back the hop but none of\n *    them carries `metadata { op '…' }`.\n *  - `contested` — the candidates disagree, so loam cannot say which operation\n *    the hop exercises. `ops` lists the distinct values in candidate order,\n *    `undefined` standing for the candidate that declared none.\n *  - `unbacked` — nothing in the model backs the hop on either tier. The pair is\n *    still carried, because a message about it has to be able to name the edge\n *    the author would have to draw.\n *\n * `rels` carries every candidate on the matched tier, not just the first: an\n * `attributed` verdict over two relationships is the normal shape once a service\n * is drawn as containers, and a caller pinning evidence needs all of them.\n */\nexport type StepAttribution =\n  | (CallPair & { verdict: \"attributed\"; tier: 1 | 2; rels: readonly Rel[]; op?: string })\n  | (CallPair & { verdict: \"contested\"; tier: 1 | 2; rels: readonly Rel[]; ops: readonly (string | undefined)[] })\n  | (CallPair & { verdict: \"unbacked\" });\n\n/**\n * The pair a step's backing relationship is looked up under. This is the half\n * that mis-grades the whole fleet if it is wrong, because a reply arrow is the\n * commonest step in any sequence diagram.\n *\n * MEASURED at the `likec4@1.59.2` pin, and `test/likec4-view-shape.test.ts` holds\n * the raw form: a reply written `a <- b 'reply'` parses as\n * `{source: \"b\", target: \"a\", isBackward: true}` — LikeC4 has ALREADY reversed\n * the endpoints and set the flag — while the forward `b -> a` yields that same\n * pair with no `isBackward` key at all (ABSENT, not false). So the endpoints as\n * parsed describe the direction the MESSAGE travels, and the flag records which\n * arrow the author typed.\n *\n * loam attributes a reply to the CALL it answers, so the reversal is undone\n * here. A landscape declares `web -> orders` because that edge is the\n * dependency; a mirror `orders -> web` for each response is not something a\n * fleet writes down. Reading a reply hop under the message's own direction would\n * report every return hop against such a landscape as `unbacked`, and where a\n * fleet does draw the mirror edge it would file the two halves of one call under\n * two operations — the call under `op 'createOrder'`, its reply under none.\n *\n * That is deliberately NOT what LikeC4's own computed stage does, and the\n * difference is measured rather than assumed: that stage resolves a backward\n * step's `relations` from the UNFLIPPED pair, so at this pin a `web <- orders`\n * step computes to `relations: []` when only `web -> orders` exists, and to the\n * mirror edge when only `orders -> web` does. It is answering which arrow to\n * draw; loam is answering which operation the hop exercises, and reads what a\n * view DECLARES rather than what it shows — which is why loam never reaches that\n * stage at all (docs/DESIGN.md rule 26, enforced by `scripts/arch-check.mjs`).\n * The consequence to know before changing this: where\n * a fleet declares BOTH directions, the mirror edge is not what backs the reply\n * here — the call is, and the mirror edge backs only a hop drawn forward along\n * it.\n */\nfunction callPair(step: StepEndpoints): CallPair {\n  return step.isBackward ? { from: step.target, to: step.source } : { from: step.source, to: step.target };\n}\n\n/**\n * The distinct `op` values across candidates, first-seen order preserved.\n *\n * Absent is a VALUE here, not a gap to skip: a relationship carrying no `op` and\n * one carrying `createOrder` disagree about the operation just as surely as two\n * different ops do, and skipping the absent one would silently promote that\n * disagreement to a confident answer. `includes` rather than a `Set` because a\n * candidate list is the handful of relationships between one pair of endpoints,\n * and it keeps `undefined` comparing the way the rest of this file expects.\n */\nfunction distinctOps(rels: readonly Rel[]): (string | undefined)[] {\n  const out: (string | undefined)[] = [];\n  for (const r of rels) if (!out.includes(r.op)) out.push(r.op);\n  return out;\n}\n\n/**\n * The verdict one tier's candidates imply, or `undefined` when that tier found\n * nothing and is therefore not the tier that answers.\n *\n * The count that decides is the DISTINCT-OP count, never the candidate count.\n * That distinction is what makes the service tier safe: once a service is drawn\n * as containers, `a.api -> b` and `a.worker -> b` both carrying\n * `op 'createOrder'` are two relationships and one operation, and a verdict read\n * off `rels.length` would convict a perfectly consistent model of contesting\n * itself.\n */\nfunction verdictOn(pair: CallPair, tier: 1 | 2, rels: readonly Rel[]): StepAttribution | undefined {\n  if (rels.length === 0) return undefined;\n  const ops = distinctOps(rels);\n  if (ops.length > 1) return { ...pair, verdict: \"contested\", tier, rels, ops };\n  // Length is exactly one here, so the single distinct value is the answer —\n  // and `undefined` is a legitimate answer: every candidate agreed that this\n  // hop names no operation.\n  const [only] = ops;\n  return { ...pair, verdict: \"attributed\", tier, rels, ...(only === undefined ? {} : { op: only }) };\n}\n\n/**\n * Relationships whose ENDPOINTS resolve to the same two services as the pair —\n * the fallback tier, and the reason a step drawn between two services matches an\n * edge drawn between two containers.\n *\n * Through the module's cached `resolverFor`, not a fresh `serviceResolver`: this\n * runs once per step of every use case in the fleet, and building the id map per\n * step is the cost that comment above `RESOLVERS` exists to prevent.\n */\nfunction resolvedTier(pair: CallPair, scope: StepScope): Rel[] {\n  const resolve = resolverFor(scope.elements, scope.known);\n  const from = resolve(pair.from);\n  const to = resolve(pair.to);\n  return scope.relationships.filter((r) => resolve(r.source) === from && resolve(r.target) === to);\n}\n\n/**\n * Which relationship in the model backs one hop of a use case, and what it says\n * the operation is.\n *\n * Two tiers, and the second runs ONLY when the first is empty. That ordering is\n * load-bearing rather than an optimisation: the service tier necessarily\n * re-finds every exact match — an endpoint that matches literally resolves to\n * the same service trivially — so running it unconditionally would let a\n * container-level edge with a different `op` contest a step the model already\n * answers exactly, turning an `attributed` verdict into a `contested` one on a\n * document nobody changed.\n *\n * Relationship `kind` is deliberately not part of the match, and that is\n * measured too: at this pin `a -[http]-> b` without a `relationship http` in the\n * `specification` block is \"Could not resolve reference to RelationshipKind\n * named 'http'\" — a parse error, which under loam's standing rule means no model\n * at all — and `test/helpers/harness.ts`'s own `LANDSCAPE` declares no\n * relationship kinds. So narrowing by kind would mean a fix message asking an\n * author to write a line their document does not parse.\n */\nexport function attributeStep(step: StepEndpoints, scope: StepScope): StepAttribution {\n  const pair = callPair(step);\n  const exact = scope.relationships.filter((r) => r.source === pair.from && r.target === pair.to);\n  const declared = verdictOn(pair, 1, exact);\n  if (declared !== undefined) return declared;\n  return verdictOn(pair, 2, resolvedTier(pair, scope)) ?? { ...pair, verdict: \"unbacked\" };\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":"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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"]}