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

package/dist/core/c4/likec4.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"likec4.js","sourceRoot":"","sources":["../../../src/core/c4/likec4.ts"],"names":[],"mappings":"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","sourcesContent":["import { readFile } from \"node:fs/promises\";\nimport { relative } from \"node:path\";\nimport { LikeC4 } from \"likec4\";\nimport { declaredService, type DeclaredService } from \"../kernel/ids/service.js\";\nimport { readDynamicViews, type ParsedView } from \"./parsed/dynamic-views.js\";\nimport { readGlobalStyleIds, readViewIds, type ViewIdClaim } from \"./parsed/view-ids.js\";\nimport { readSpecification, type DocSpecification } from \"./parsed/specification.js\";\nimport { readDeployment, type DeploymentModel } from \"./parsed/deployment.js\";\nimport { compareRels, descText, metaKey } from \"./parsed/values.js\";\n\n/** A parse/validation issue reported by LikeC4. */\nexport interface LikeC4Error {\n  message: string;\n  /** As LikeC4 hands it over: an LSP range line, which starts at 0. Print it through `errorText`. */\n  line?: number;\n  sourceFsPath?: string;\n}\n\n/**\n * The one spelling of a diagnostic loam prints — `L<n>: <message>`, with the\n * line 1-BASED: the number an editor's gutter shows, so an agent told to open\n * it opens the line the fault is on. LikeC4's `getErrors()` copies the LSP\n * range's start line, which counts from 0, and every message used to print that\n * raw number: the named line landed one above the fault every time\n * (verification 2026-09-04, W6).\n *\n * `likec4 validate` DOES NOT AGREE, and that is deliberate rather than\n * unnoticed. Measured at the 1.59.2 pin on a document whose fault is on file\n * line 10: the CLI prints `Line 9:` and loam prints `L10:` for the same\n * diagnostic — it renders the LSP index raw. Copying that would make loam's\n * output wrong in the way the fix above repaired, so the two spellings differ\n * by exactly one and a reader comparing them should expect it.\n *\n * Four modules used to hand-roll this ternary; they all read this one now, so\n * the base cannot drift between them again.\n *\n * The message itself is BOUNDED here too, and for the same reason it lives in\n * one place: every surface that prints a LikeC4 diagnostic — validate, context,\n * show, tasks, doctor, gate, archive — prints it through this function, so this\n * is the one spelling that can keep all of them small. See `boundedMessage`.\n */\nexport function errorText(e: LikeC4Error): string {\n  const message = boundedMessage(e.message);\n  return typeof e.line === \"number\" ? `L${e.line + 1}: ${message}` : message;\n}\n\n/**\n * The documents a project's diagnostics name, docs-relative POSIX, deduped and\n * sorted — the one spelling of \"which files broke\" behind `landscape.invalid`,\n * `spine.landscape-invalid`, the brief's unparseable arm, the work packet and\n * `loam explore`. Those surfaces are read one after another on the same tree,\n * and an agent has to be able to tell that they name the same file. Given ONE\n * error it spells that error's document: validate's detail-line prefix.\n */\nexport function brokenDocumentPaths(docsDir: string, errors: readonly LikeC4Error[]): string[] {\n  return [...new Set(errors.map((e) => e.sourceFsPath).filter((p): p is string => p !== undefined))]\n    .map((abs) => relative(docsDir, abs).split(/[\\\\/]/).join(\"/\"))\n    .sort();\n}\n\n/**\n * How many alternatives of a parser's \"one of these possible Token sequences\"\n * list a printed diagnostic keeps — the number `likec4 validate` itself prints\n * before its `...`.\n */\nconst TOKEN_ALTERNATIVES = 4;\n\n/** The heading line of Chevrotain's no-viable-alternative message, whose numbered list follows it. */\nconst TOKEN_SEQUENCES = /possible Token sequences:$/;\n\n/** One numbered alternative in that list: `  12. [IdTerminal, Dot]`. */\nconst ALTERNATIVE = /^\\s+\\d+\\. /;\n\n/**\n * A LikeC4 message, with Chevrotain's list of expected token sequences cut to\n * its first few alternatives and a count of the rest.\n *\n * When the parser meets a token no rule can take, Chevrotain lists EVERY token\n * sequence any rule could have accepted there — and inside a LikeC4 `model { }`\n * block that is the whole grammar. Measured at the 1.59.2 pin: deleting the\n * closing quote of one `technology '…'` makes three such messages of about\n * 6,160 lines each, and `loam validate --service` printed 18,503 lines\n * (434 KB; 458 KB as `--json`) for one keystroke. `capDetails` bounds how MANY\n * details a finding prints, never how big one is, and `loam context` has no cap\n * at all — so a broken feature delta turned a 24 KB briefing into 626 KB for\n * every agent working on any service the feature touches. An agent in the\n * check-fix loop gets nothing from alternative 4,000: what it acts on is the\n * line number and the `but found: '…'` line, which is kept.\n *\n * Upstream `likec4 validate` keeps the first five lines of any message and\n * prints `...`; this cuts the LIST only, so the `but found:` line after it\n * survives, and says how many alternatives were dropped so nothing reads as\n * complete when it is not (the convention `capDetails` uses). Any other\n * message is returned exactly as LikeC4 wrote it.\n */\nfunction boundedMessage(message: string): string {\n  const lines = message.split(\"\\n\");\n  if (!TOKEN_SEQUENCES.test(lines[0] ?? \"\")) return message;\n  const alternatives = lines.filter((line) => ALTERNATIVE.test(line)).length;\n  if (alternatives <= TOKEN_ALTERNATIVES) return message;\n  const kept: string[] = [];\n  let seen = 0;\n  for (const line of lines) {\n    if (!ALTERNATIVE.test(line)) kept.push(line);\n    else if (++seen <= TOKEN_ALTERNATIVES) kept.push(line);\n    else if (seen === TOKEN_ALTERNATIVES + 1) kept.push(`  … (+${alternatives - TOKEN_ALTERNATIVES} more)`);\n  }\n  return kept.join(\"\\n\");\n}\n\n/**\n * Diagnostics as loam keeps them: each one ONCE, in line order.\n *\n * LikeC4 can report one fault more than once: measured at the 1.59.2 pin, one\n * dropped quote in a service model came back as two byte-identical messages at\n * the same line — each of them the full token list `boundedMessage` cuts — and\n * every `details` list printed both. The same message at the same line of the\n * same file is one fault; the identity includes the file because LikeC4 blames\n * a duplicate declaration on BOTH documents of a project, and those are two\n * lines an author has to look at.\n *\n * In line order because LikeC4 hands its lexer's errors over before its\n * parser's: the first location printed for that dropped quote was an\n * \"unexpected character\" twelve lines BELOW it, where the runaway string ended,\n * while the parser's errors two lines below it came after. The sort is stable,\n * so diagnostics on one line keep LikeC4's order, and a list mixing documents\n * stays in line order within each of them — every loader groups by document\n * after this, which is why sorting by line alone is enough. A diagnostic with\n * no line is about the document as a whole and leads.\n *\n * Applied where `getErrors()` is read (`loadSource`, `./workspace.ts`,\n * `./project/load.ts`), so every loader hands every reader the same list and\n * test/likec4-batch-parity.test.ts can keep asserting the two modes equal.\n */\nexport function distinctErrors<E extends LikeC4Error>(errors: readonly E[]): E[] {\n  const seen = new Set<string>();\n  return errors\n    .filter((e) => {\n      const key = `${e.sourceFsPath ?? \"\"}\\0${e.line ?? \"\"}\\0${e.message}`;\n      if (seen.has(key)) return false;\n      seen.add(key);\n      return true;\n    })\n    .sort((a, b) => (a.line ?? -1) - (b.line ?? -1));\n}\n\n/** loam-neutral element view (flattened from the LikeC4 parsed model). */\nexport interface Elem {\n  id: string;\n  kind: string;\n  title: string;\n  description?: string;\n  /**\n   * The `services/<id>` directory this element stands for, from the element's\n   * `metadata { service '...' }`. Absent on the elements nobody has bound —\n   * see `elementService` for the fallback.\n   */\n  service?: DeclaredService;\n  tags: string[];\n}\n\n/** loam-neutral relationship view. */\nexport interface Rel {\n  source: string;\n  target: string;\n  title?: string;\n  /** OpenAPI operationId this call uses, from the relationship's `metadata { op '...' }`. */\n  op?: string;\n  /**\n   * AsyncAPI message this edge PRODUCES, from `metadata { publishes '...' }`.\n   * Resolved against the edge SOURCE's own contract: a service publishes what it\n   * declares an `action: send` for.\n   */\n  publishes?: string;\n  /**\n   * AsyncAPI message this edge CONSUMES, from `metadata { consumes '...' }`.\n   * Two keys rather than one directional `message`, because the async spine is\n   * not symmetric with the HTTP one: there the PROVIDER owns the contract and\n   * every consumer is checked against it, while here the PRODUCER owns the\n   * message and the consumer lives in another repository entirely. Which side of\n   * an edge owes the declaration is read from the key AND the arrow: `consumes`\n   * binds the TARGET, so a consume edge points away from the topic, at its\n   * consumer (`./direction/direction.ts`; reversed, `spine.message-unbound`).\n   */\n  consumes?: string;\n  tags: string[];\n}\n\nexport interface LoadedDoc {\n  errors: LikeC4Error[];\n  elements: Elem[];\n  relationships: Rel[];\n  /**\n   * The document's `specification { }` block — what its KINDS declare, as\n   * opposed to what its elements do. Optional because a document that did not\n   * parse has none, and because the several `LoadedDoc` literals standing in for\n   * an absent file (`show`'s missing model.likec4, `unreadableLandscape`) have\n   * nothing to put here: a reader must treat \"absent\" and \"declares nothing\" the\n   * same way. See `./parsed/specification.ts` for why loam reads it at all —\n   * short version: since LikeC4 1.59.0 a kind can carry tags, and only the\n   * specification can tell an inherited tag from an authored one.\n   */\n  specification?: DocSpecification;\n  /**\n   * The `dynamic view`s the document DECLARES — the ordered steps of a use\n   * case, never a rendering (docs/DESIGN.md rule 26). Optional for exactly the\n   * reason `specification` is: a document that did not parse has none, and the\n   * several `LoadedDoc` literals standing in for an absent file have nothing to\n   * put here. Absent and empty mean the same thing to every reader — no views\n   * were declared, or none could be read — and neither is a finding: a fleet\n   * that draws no diagrams owes loam no views block.\n   */\n  views?: ParsedView[];\n  /**\n   * The ids of every view the document AUTHORS, static ones included — a census,\n   * not a read of what any of them shows. Separate from `views` above because\n   * the two answer different questions off different filters (see\n   * `./parsed/view-ids.ts`), and because a static view contributes an id and\n   * nothing else loam may look at.\n   */\n  viewIds?: ViewIdClaim[];\n  /**\n   * The ids of every GLOBAL STYLE the document declares — `global { styleGroup\n   * <id> { … } }` and the single-rule `global { style <id> … }` alike, since\n   * LikeC4 files both under one id table (hence not `styleGroups`). A\n   * declaration census exactly as `viewIds` is: the ids, sorted, and never a\n   * rule inside one (docs/DESIGN.md rule 26 says why a style is a rendering\n   * instruction loam may not read). One consumer — the generated subsystem\n   * views, which reference the group named `subsystems` when it is declared\n   * and nothing otherwise, because a reference to an undeclared id is a parse\n   * error that blanks the whole `architecture/` project in the renderer.\n   * Optional for the reason `views` is: a document that did not parse has\n   * none, and the `LoadedDoc` literals standing in for an absent file have\n   * nothing to put here; absent and empty mean the same thing to every reader.\n   */\n  globalStyles?: string[];\n  /**\n   * The `deployment { }` model the document declares — nodes, instances and the\n   * edges between them (`./parsed/deployment.ts`). Optional for the reason\n   * `views` is, and read the same way by every consumer: absent and empty mean\n   * \"no topology\", and neither is a finding. A fleet that draws no deployment\n   * owes loam none, which is also the whole opt-in the axis has.\n   */\n  deployment?: DeploymentModel;\n}\n\n/**\n * The slice of a LikeC4 model loam reads: elements and relationships, and on\n * each of those only id/kind/title/description/tags/metadata.\n *\n * It is a type of its own, rather than an inline cast at the one call site,\n * because BOTH of LikeC4's model stages expose exactly this slice — which is\n * what makes the cheap stage a safe substitute for the expensive one. The\n * substitution is pinned in test/likec4-model-parity.test.ts, which flattens\n * both stages through `flattenModel` below and compares the results.\n *\n * Views are deliberately NOT in this interface, even though loam does read them.\n * What this interface pins is the two-stage PARITY that makes the cheap stage a\n * safe substitute for the expensive one — and the stages are not claimed to\n * agree about views, nor need to: the parsed stage is the only one rule 26\n * permits. That read has its own adapter, `./parsed/dynamic-views.ts`.\n */\nexport interface ReadableModel {\n  elements: () => Iterable<{\n    id: string;\n    kind: string;\n    title: string;\n    description?: unknown;\n    tags?: readonly string[];\n    metadata?: unknown;\n  }>;\n  relationships: () => Iterable<{\n    source: { id: string };\n    target: { id: string };\n    title?: string | null;\n    tags?: readonly string[];\n    metadata?: unknown;\n  }>;\n  /**\n   * The parsed `specification { }` block. Typed `unknown` and normalized by\n   * `readSpecification` rather than described here, because it is NOT part of\n   * the two-stage parity this interface pins: the shape is LikeC4's internal\n   * record (1.59.2 spells element-kind tags and relationship-kind tags\n   * differently), and writing it out here would be a structural claim about a\n   * dependency's internals that the compiler would then enforce against us.\n   */\n  specification?: unknown;\n}\n\n/** Flatten a LikeC4 model into loam's neutral `Elem`/`Rel` view. */\nexport function flattenModel(model: ReadableModel): { elements: Elem[]; relationships: Rel[] } {\n  const elements: Elem[] = [...model.elements()].map((e) => {\n    // The one crossing between LikeC4's parse output and loam's type system:\n    // a `metadata { service '...' }` binding is text somebody wrote, and this\n    // is where it acquires a type that says so.\n    const bound = metaKey(e.metadata, \"service\");\n    return {\n      id: e.id,\n      kind: e.kind,\n      title: e.title,\n      description: descText(e.description),\n      ...(bound === undefined ? {} : { service: declaredService(bound) }),\n      tags: [...(e.tags ?? [])],\n    };\n  });\n  const relationships: Rel[] = [...model.relationships()]\n    .map((r) => ({\n      source: r.source.id,\n      target: r.target.id,\n      // LikeC4 reports an untitled edge as title: null — normalize to the declared `title?: string`.\n      title: r.title ?? undefined,\n      op: metaKey(r.metadata, \"op\"),\n      publishes: metaKey(r.metadata, \"publishes\"),\n      consumes: metaKey(r.metadata, \"consumes\"),\n      tags: [...(r.tags ?? [])],\n    }))\n    // One order for every run and machine: `compareRels` (./parsed/values.ts) says why LikeC4 gives none.\n    .sort(compareRels);\n  return { elements, relationships };\n}\n\n/**\n * Load and validate a single self-contained `.likec4` document, in-process\n * (no external tool, no JVM). Returns validation errors and, if clean, the\n * flattened elements + relationships.\n */\nexport async function loadFile(path: string): Promise<LoadedDoc> {\n  return loadSource(await readFile(path, \"utf8\"));\n}\n\n/**\n * `loadFile` for text that is not (yet) on disk — what the archive merge uses\n * to prove a computed landscape parses BEFORE anything is written.\n */\nexport async function loadSource(src: string): Promise<LoadedDoc> {\n  // LikeC4 owns a Langium workspace and registers a process-exit listener for\n  // it. Validation creates many short-lived instances, so every acquired\n  // instance must be disposed even on an invalid document or a failed model\n  // computation. Its logger is disabled because diagnostics are returned in\n  // LoadedDoc instead of being written out-of-band to stderr.\n  const likec4 = await LikeC4.fromSource(src, { logger: false });\n  try {\n    // Assigned, not cast: LikeC4 declares `getErrors()` as a non-nullable array\n    // whose element type is structurally wider than ours, so the compiler can\n    // check the shape here. The cast was the only thing standing between a\n    // dependency renaming `message` and a build that still succeeded — and the\n    // `?? []` it carried could never fire. Through `distinctErrors`, as every\n    // loader's diagnostics are, so this one agrees with the batch loader.\n    const errors: LikeC4Error[] = distinctErrors(likec4.getErrors());\n    if (errors.length > 0) {\n      return { errors, elements: [], relationships: [] };\n    }\n\n    // `parsedModel`, not `computedModel`: the computed stage RESOLVES every\n    // view — expanding its predicates against the model and deriving the\n    // ancestor edges a diagram needs (and computing a default view when the\n    // document declares none). loam reads what a view DECLARES and never what a\n    // view SHOWS (docs/DESIGN.md rule 26), so none of that resolution is ever\n    // wanted; it renders nothing. That work is superlinear in the number of\n    // RELATIONSHIPS, so a landscape at fleet shape turned `loam list` from under\n    // a second into minutes. The elements and relationships below are identical\n    // either way. The `await` is load-bearing for anything reading `$data`: it is\n    // undefined on the unresolved promise.\n    return cleanDoc((await likec4.parsedModel()) as ReadableModel);\n  } finally {\n    await likec4.dispose();\n  }\n}\n\n/**\n * Everything loam reads out of one document that parsed clean, from LikeC4's\n * parsed stage. Shared with `./workspace.ts`'s batch loader, which used to\n * spell the same six reads out again: an adapter wired into one loader and not\n * the other reads as an absence rather than an error, the failure\n * test/likec4-batch-parity.test.ts exists to catch. `./project/load.ts`'s\n * `cleanProjectDoc` wraps the same reads in a project's record, whose error\n * shape differs and which requires the fields `LoadedDoc` leaves optional.\n */\nexport function cleanDoc(model: ReadableModel): LoadedDoc {\n  return { errors: [], ...readParsedModel(model) };\n}\n\n/**\n * The six reads themselves — one spelling under every loader (`cleanDoc`\n * above, `./project/load.ts`'s `cleanProjectDoc`), so the parity test guards\n * one function rather than a convention. The return type is inferred on\n * purpose: it is `LoadedDoc` minus `errors` with every read PRESENT, which is\n * what lets a project's record, whose fields are required, spread it.\n */\nexport function readParsedModel(model: ReadableModel) {\n  return {\n    specification: readSpecification(model.specification),\n    views: readDynamicViews(model),\n    viewIds: readViewIds(model),\n    globalStyles: readGlobalStyleIds(model),\n    deployment: readDeployment(model),\n    ...flattenModel(model),\n  };\n}\n"]}

package/dist/core/c4/locate/unlocated.js

@@ -0,0 +1,150 @@
+/**
+ * What the parsed model declares and the splice map cannot locate — named the
+ * way an author can act on it.
+ *
+ * The archive splices the landscape by its text scan (`../source-scan.ts`) and
+ * refuses rather than splice around a declaration the scan cannot see. That
+ * refusal used to guess its cause: "most often two declarations sharing one
+ * line", whatever the map held. A fleet on 0.2.0-alpha.7 read it over a
+ * standalone declaration on a line of its own — the scan was blind to a second
+ * `model { }` block — and was asked to rewrite a valid map to satisfy a message
+ * that described something else. So the cause is no longer guessed where it can
+ * be read: LikeC4's own locator says on which line the declaration is, the
+ * line itself says whether anything but the declaration's own lead (`Lead`)
+ * precedes it there, and the scan says what it read in that place instead.
+ *
+ * A second parse of the landscape, and it is paid only on the refusal path —
+ * the merge decides THAT something is unlocated from the parse it already has,
+ * and asks this module only for the words.
+ */
+import { LikeC4 } from "likec4";
+import { maskSource } from "../source-mask.js";
+/**
+ * The first declaration of `text` that `scan` does not locate — elements in
+ * the parser's order, then relationships in document order; null when every
+ * one is located.
+ *
+ * An element is located when the scan holds its id. A relationship has no id
+ * the text can carry, so it is located by POSITION: LikeC4 places each edge at
+ * its arrow, and each scanned statement may stand for one edge — the second
+ * arrow inside one scanned span is the edge the scan swallowed.
+ */
+export async function firstUnlocated(text, scan) {
+    const likec4 = await LikeC4.fromSource(text, { logger: false });
+    try {
+        const model = await likec4.parsedModel();
+        const where = placer(text, scan);
+        const scanned = new Set(scan.elements.map((e) => e.id));
+        for (const e of model.elements()) {
+            if (scanned.has(e.id))
+                continue;
+            return { kind: "element", name: e.id, ...where.place(likec4.languageServices.locate({ element: e.id })?.range.start, { kind: e.kind }) };
+        }
+        const edges = [...model.relationships()].map((r) => {
+            const start = likec4.languageServices.locate({ relation: r.id })?.range.start;
+            return { name: `${r.source.id} -> ${r.target.id}`, start, offset: start === undefined ? -1 : where.offset(start) };
+        });
+        const claimed = new Set();
+        for (const edge of edges.sort((a, b) => a.offset - b.offset)) {
+            if (edge.offset === -1)
+                continue;
+            const span = scan.rels.findIndex((s) => edge.offset >= s.start && edge.offset < s.end);
+            if (span !== -1 && !claimed.has(span)) {
+                claimed.add(span);
+                continue;
+            }
+            return { kind: "relationship", name: edge.name, ...where.place(edge.start, "edge") };
+        }
+        // Every located edge has a statement of its own: an unlocated one, if the
+        // count says there is one, is among those the locator could not place.
+        const lost = edges.find((edge) => edge.offset === -1);
+        return lost === undefined ? null : { kind: "relationship", name: lost.name };
+    }
+    finally {
+        await likec4.dispose();
+    }
+}
+/** A whole token — not the tail of a longer id — directly before the anchor, the kind written there. */
+const ELEMENT_LEAD = /(?<![\w.-])([A-Za-z_][\w-]*)\s*$/;
+/** An optional source reference and an optional `-[`, directly before the anchor; always matches, possibly empty. */
+const EDGE_LEAD = /(?<![\w.-])(?:[A-Za-z_][\w.-]*\s*)?(?:-\[\s*)?$/;
+/**
+ * Where the declaration anchored at `at` starts, in the masked `code` of the
+ * line starting at `from`: before its lead when the code there ends in one,
+ * else `at`. Masked, a literal or a URI is blank, so the word before one reads
+ * as an edge's source here exactly as `relationHead` reads it in the scan
+ * (`link https://… -> zulu` is `link -> zulu` to both). Such a line is a
+ * scanned edge of its own, so its edge is unlocated only when an earlier
+ * statement's span ran on over it — and then the line-break explanation is
+ * the one to give, which is what dropping that word leads to.
+ */
+function leadStart(code, span, lead) {
+    const before = code.slice(span.from, span.at);
+    const m = lead === "edge" ? EDGE_LEAD.exec(before) : ELEMENT_LEAD.exec(before);
+    return m === null || (lead !== "edge" && m[1] !== lead.kind) ? span.at : span.from + m.index;
+}
+/**
+ * Reads a position against the text and the scan. Lines are split the way LSP
+ * counts them — `\r\n`, `\r` or `\n` — because that is the count LikeC4's
+ * positions are in. A bare carriage return used to be the one break the scan
+ * did not make, and so the cause the "read it as part of" words were written
+ * for; `statementHead` breaks there too now, and the words stay for whatever
+ * run-on the scan has next.
+ */
+function placer(text, scan) {
+    const starts = [0];
+    for (const m of text.matchAll(/\r\n|\r|\n/g))
+        starts.push(m.index + m[0].length);
+    const lineOf = (offset) => starts.findLastIndex((s) => s <= offset) + 1;
+    const { code } = maskSource(text);
+    const offset = (start) => (starts[start.line] ?? text.length) + start.character;
+    const heads = [
+        ...scan.elements
+            .filter((e) => e.extend !== true)
+            .map((e) => ({ name: `'${e.id}'`, start: e.start, end: e.bodyOpen === -1 ? e.end : e.bodyOpen })),
+        ...scan.rels.map((r) => ({ name: `the edge '${r.source} -> ${r.target}'`, start: r.start, end: r.end })),
+    ];
+    const place = (start, lead) => {
+        if (start === undefined)
+            return {};
+        const at = offset(start);
+        const from = starts[start.line] ?? at;
+        // Measured from where the declaration starts, not from the anchor: its own
+        // kind keyword or source is no other statement (`Lead`).
+        const before = code.slice(from, leadStart(code, { from, at }, lead));
+        // Innermost first: a nested declaration's span lies inside its parent's.
+        const cover = heads.filter((h) => at >= h.start && at < h.end).sort((a, b) => b.start - a.start)[0];
+        return {
+            line: start.line + 1,
+            ...(/\S/.test(before) ? { sharesLine: true } : {}),
+            ...(cover === undefined ? {} : { readAs: { name: cover.name, line: lineOf(cover.start) } }),
+        };
+    };
+    return { place, offset };
+}
+/**
+ * The refusal's words for one unlocated declaration of `file`. A shared line
+ * is named only when the line shows one, and the statement the scan read
+ * instead only when it read one: a guess at the cause is the message this
+ * replaced.
+ */
+export function unlocatedReason(file, gap) {
+    const remedy = "nothing was written; rewrite it on a line of its own as `name = kind 'title' {` (an edge as `a -> b 'title'`) and re-run — " +
+        "and report the original shape: LikeC4 parses it, so it is a form the splice map should read";
+    if (gap === null)
+        return `${file} declares more than placement can locate, and LikeC4's locator could not say where — ${remedy}`;
+    const what = `${file} declares ${gap.kind === "element" ? `'${gap.name}'` : `the relationship '${gap.name}'`}`;
+    const where = gap.line === undefined ? "" : ` at line ${gap.line}`;
+    const read = gap.readAs;
+    if (gap.sharesLine === true) {
+        const other = read === undefined ? "the statement before it" : read.name;
+        return (`${what}${where} in a form placement cannot locate: it shares that line with ${other}, and the splice map reads ` +
+            `one statement per line where LikeC4 accepts two — give each its own line, then re-run`);
+    }
+    if (read !== undefined) {
+        return (`${what}${where} in a form placement cannot locate: the splice map read it as part of ${read.name}, which starts at ` +
+            `line ${read.line} — it ran that statement on past a line break LikeC4 makes — ${remedy}`);
+    }
+    return `${what}${where} in a form placement cannot locate, and the splice map read no statement there — ${remedy}`;
+}
+//# sourceMappingURL=unlocated.js.map

package/dist/core/c4/locate/unlocated.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unlocated.js","sourceRoot":"","sources":["../../../../src/core/c4/locate/unlocated.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What the parsed model declares and the splice map cannot locate — named the\n * way an author can act on it.\n *\n * The archive splices the landscape by its text scan (`../source-scan.ts`) and\n * refuses rather than splice around a declaration the scan cannot see. That\n * refusal used to guess its cause: \"most often two declarations sharing one\n * line\", whatever the map held. A fleet on 0.2.0-alpha.7 read it over a\n * standalone declaration on a line of its own — the scan was blind to a second\n * `model { }` block — and was asked to rewrite a valid map to satisfy a message\n * that described something else. So the cause is no longer guessed where it can\n * be read: LikeC4's own locator says on which line the declaration is, the\n * line itself says whether anything but the declaration's own lead (`Lead`)\n * precedes it there, and the scan says what it read in that place instead.\n *\n * A second parse of the landscape, and it is paid only on the refusal path —\n * the merge decides THAT something is unlocated from the parse it already has,\n * and asks this module only for the words.\n */\nimport { LikeC4 } from \"likec4\";\nimport { maskSource } from \"../source-mask.js\";\nimport type { ScannedModel } from \"../source-scan.js\";\n\n/** One declaration the parser has and the scan cannot place. */\nexport interface Unlocated {\n  kind: \"element\" | \"relationship\";\n  /** The element's id, or the relationship as `source -> target`, as the parser resolved them. */\n  name: string;\n  /** 1-based line LikeC4's locator puts the declaration on; absent when it has no answer. */\n  line?: number;\n  /**\n   * Code other than the declaration's own lead precedes it on its own line —\n   * the shared line is then a FACT, not a guess.\n   */\n  sharesLine?: true;\n  /** The scanned statement that covers where the declaration sits, and the line that statement starts on. */\n  readAs?: { name: string; line: number };\n}\n\n/**\n * The first declaration of `text` that `scan` does not locate — elements in\n * the parser's order, then relationships in document order; null when every\n * one is located.\n *\n * An element is located when the scan holds its id. A relationship has no id\n * the text can carry, so it is located by POSITION: LikeC4 places each edge at\n * its arrow, and each scanned statement may stand for one edge — the second\n * arrow inside one scanned span is the edge the scan swallowed.\n */\nexport async function firstUnlocated(text: string, scan: ScannedModel): Promise<Unlocated | null> {\n  const likec4 = await LikeC4.fromSource(text, { logger: false });\n  try {\n    const model = await likec4.parsedModel();\n    const where = placer(text, scan);\n    const scanned = new Set(scan.elements.map((e) => e.id));\n    for (const e of model.elements()) {\n      if (scanned.has(e.id)) continue;\n      return { kind: \"element\", name: e.id, ...where.place(likec4.languageServices.locate({ element: e.id })?.range.start, { kind: e.kind }) };\n    }\n    const edges = [...model.relationships()].map((r) => {\n      const start = likec4.languageServices.locate({ relation: r.id })?.range.start;\n      return { name: `${r.source.id} -> ${r.target.id}`, start, offset: start === undefined ? -1 : where.offset(start) };\n    });\n    const claimed = new Set<number>();\n    for (const edge of edges.sort((a, b) => a.offset - b.offset)) {\n      if (edge.offset === -1) continue;\n      const span = scan.rels.findIndex((s) => edge.offset >= s.start && edge.offset < s.end);\n      if (span !== -1 && !claimed.has(span)) {\n        claimed.add(span);\n        continue;\n      }\n      return { kind: \"relationship\", name: edge.name, ...where.place(edge.start, \"edge\") };\n    }\n    // Every located edge has a statement of its own: an unlocated one, if the\n    // count says there is one, is among those the locator could not place.\n    const lost = edges.find((edge) => edge.offset === -1);\n    return lost === undefined ? null : { kind: \"relationship\", name: lost.name };\n  } finally {\n    await likec4.dispose();\n  }\n}\n\n/** An LSP position: a 0-based line and a character within it. */\ninterface Position {\n  line: number;\n  character: number;\n}\n\n/**\n * The part of a declaration LikeC4's locator leaves BEFORE its anchor. It\n * points an element at its NAME and a relationship at its ARROW — inside\n * `-[…]->`, at the kind — so `container api 'API'` has its kind keyword in\n * front of the anchor and `zulu -> apple` its source. Read as \"code before\n * it\", every unlocated edge and every `kind name` element shared its line with\n * itself, and the line-break explanation `unlocatedReason` holds below the\n * shared-line one was never reached. An element's lead is a token equal to\n * its parsed kind; an edge's is its source reference (`it`, a dotted path or\n * none) and the `-[` opening a bracketed kind.\n */\ntype Lead = { kind: string } | \"edge\";\n\n/** A whole token — not the tail of a longer id — directly before the anchor, the kind written there. */\nconst ELEMENT_LEAD = /(?<![\\w.-])([A-Za-z_][\\w-]*)\\s*$/;\n/** An optional source reference and an optional `-[`, directly before the anchor; always matches, possibly empty. */\nconst EDGE_LEAD = /(?<![\\w.-])(?:[A-Za-z_][\\w.-]*\\s*)?(?:-\\[\\s*)?$/;\n\n/**\n * Where the declaration anchored at `at` starts, in the masked `code` of the\n * line starting at `from`: before its lead when the code there ends in one,\n * else `at`. Masked, a literal or a URI is blank, so the word before one reads\n * as an edge's source here exactly as `relationHead` reads it in the scan\n * (`link https://… -> zulu` is `link -> zulu` to both). Such a line is a\n * scanned edge of its own, so its edge is unlocated only when an earlier\n * statement's span ran on over it — and then the line-break explanation is\n * the one to give, which is what dropping that word leads to.\n */\nfunction leadStart(code: string, span: { from: number; at: number }, lead: Lead): number {\n  const before = code.slice(span.from, span.at);\n  const m = lead === \"edge\" ? EDGE_LEAD.exec(before) : ELEMENT_LEAD.exec(before);\n  return m === null || (lead !== \"edge\" && m[1] !== lead.kind) ? span.at : span.from + m.index;\n}\n\n/** Everything a position tells about a declaration, and the offset arithmetic that is built on. */\ninterface Placer {\n  place: (start: Position | undefined, lead: Lead) => Pick<Unlocated, \"line\" | \"sharesLine\" | \"readAs\">;\n  offset: (start: Position) => number;\n}\n\n/**\n * Reads a position against the text and the scan. Lines are split the way LSP\n * counts them — `\\r\\n`, `\\r` or `\\n` — because that is the count LikeC4's\n * positions are in. A bare carriage return used to be the one break the scan\n * did not make, and so the cause the \"read it as part of\" words were written\n * for; `statementHead` breaks there too now, and the words stay for whatever\n * run-on the scan has next.\n */\nfunction placer(text: string, scan: ScannedModel): Placer {\n  const starts = [0];\n  for (const m of text.matchAll(/\\r\\n|\\r|\\n/g)) starts.push(m.index + m[0].length);\n  const lineOf = (offset: number): number => starts.findLastIndex((s) => s <= offset) + 1;\n  const { code } = maskSource(text);\n  const offset = (start: Position): number => (starts[start.line] ?? text.length) + start.character;\n  const heads = [\n    ...scan.elements\n      .filter((e) => e.extend !== true)\n      .map((e) => ({ name: `'${e.id}'`, start: e.start, end: e.bodyOpen === -1 ? e.end : e.bodyOpen })),\n    ...scan.rels.map((r) => ({ name: `the edge '${r.source} -> ${r.target}'`, start: r.start, end: r.end })),\n  ];\n  const place = (start: Position | undefined, lead: Lead): Pick<Unlocated, \"line\" | \"sharesLine\" | \"readAs\"> => {\n    if (start === undefined) return {};\n    const at = offset(start);\n    const from = starts[start.line] ?? at;\n    // Measured from where the declaration starts, not from the anchor: its own\n    // kind keyword or source is no other statement (`Lead`).\n    const before = code.slice(from, leadStart(code, { from, at }, lead));\n    // Innermost first: a nested declaration's span lies inside its parent's.\n    const cover = heads.filter((h) => at >= h.start && at < h.end).sort((a, b) => b.start - a.start)[0];\n    return {\n      line: start.line + 1,\n      ...(/\\S/.test(before) ? { sharesLine: true as const } : {}),\n      ...(cover === undefined ? {} : { readAs: { name: cover.name, line: lineOf(cover.start) } }),\n    };\n  };\n  return { place, offset };\n}\n\n/**\n * The refusal's words for one unlocated declaration of `file`. A shared line\n * is named only when the line shows one, and the statement the scan read\n * instead only when it read one: a guess at the cause is the message this\n * replaced.\n */\nexport function unlocatedReason(file: string, gap: Unlocated | null): string {\n  const remedy =\n    \"nothing was written; rewrite it on a line of its own as `name = kind 'title' {` (an edge as `a -> b 'title'`) and re-run — \" +\n    \"and report the original shape: LikeC4 parses it, so it is a form the splice map should read\";\n  if (gap === null) return `${file} declares more than placement can locate, and LikeC4's locator could not say where — ${remedy}`;\n  const what = `${file} declares ${gap.kind === \"element\" ? `'${gap.name}'` : `the relationship '${gap.name}'`}`;\n  const where = gap.line === undefined ? \"\" : ` at line ${gap.line}`;\n  const read = gap.readAs;\n  if (gap.sharesLine === true) {\n    const other = read === undefined ? \"the statement before it\" : read.name;\n    return (\n      `${what}${where} in a form placement cannot locate: it shares that line with ${other}, and the splice map reads ` +\n      `one statement per line where LikeC4 accepts two — give each its own line, then re-run`\n    );\n  }\n  if (read !== undefined) {\n    return (\n      `${what}${where} in a form placement cannot locate: the splice map read it as part of ${read.name}, which starts at ` +\n      `line ${read.line} — it ran that statement on past a line break LikeC4 makes — ${remedy}`\n    );\n  }\n  return `${what}${where} in a form placement cannot locate, and the splice map read no statement there — ${remedy}`;\n}\n"]}

package/dist/core/c4/parsed/deployment.js

@@ -0,0 +1,160 @@
+/**
+ * The DEPLOYMENT model a document declares — which physical nodes exist, which
+ * containers are instanced where, and what talks to what across them.
+ *
+ * A `deployment { }` block has been legal in a docs repo since LikeC4 could
+ * parse one, and until this reader existed loam saw none of it. The parser
+ * resolved every `instanceOf` — so a container renamed out from under a
+ * deployment node already failed the gate — and after that no requirement could
+ * name a node, no `#obl-` tag on a datacenter was graded, and the context pack
+ * an agent implements from did not mention topology at all. Integrity held at
+ * the level of syntax and was absent at the level of requirements. ROADMAP's
+ * deployment axis and `meta/docs/features/FEAT-1-the-deployment-axis/` are the
+ * item and the specification; this module is its first half.
+ *
+ * ## Why this is a `parsed/` reader and not a package of its own
+ *
+ * It is the same job the three modules beside it do: take one corner of
+ * LikeC4's parse output and hand back a loam-neutral record, defensively, with
+ * its shape assumptions owned outright. `readSpecification`, `readDynamicViews`
+ * and `readViewIds` are all called on the line above `flattenModel(model)` in
+ * each of loam's three loaders, and so is this. FEAT-1's delta said
+ * `src/core/c4/deploy/`; a package holding this alone would be a directory
+ * pretending to be a subject (docs/DESIGN.md), and the delta was corrected
+ * rather than the code bent to it — which is what an unarchived feature is for.
+ *
+ * **`parsed/` is still AT its five-file limit.** The global style-id census
+ * rode into `view-ids.ts` because it IS that module's subject — one more
+ * table asked the same question — and the next reader that is not a census
+ * still needs the split first. The seam to split on is the one this file does
+ * not share: `dynamic-views.ts` and `view-ids.ts` read `$data`, this one and
+ * `specification.ts` read the model surface.
+ *
+ * ## What is read, and what is deliberately left
+ *
+ * Nodes, instances and relationships, with the ids, titles and tags each
+ * carries. MEASURED at the 1.59.2 pin, and every line of it needed measuring
+ * rather than assuming:
+ *
+ *  - `nodes()` returns deployment NODES only — an `instanceOf` is not among
+ *    them, which is why instances are a second list rather than a filter.
+ *  - an instance carries the LOGICAL element it deploys as `element.id`, and
+ *    that is the whole join back to the C4 model: `eu.a.dbA -> orders.db`.
+ *  - both nodes and instances carry `tags`, so `#obl-geo` on a datacenter is
+ *    readable — the fail-open case that made this an item.
+ *  - a relationship carries `tags` and `metadata` DIRECTLY (`r.metadata`, no
+ *    `$relationship` indirection), and both model stages return byte-identical
+ *    results, which is what lets `test/likec4-model-parity.test.ts` cover this
+ *    read with the substitution it already pins.
+ *  - a document with NO `deployment { }` block still returns a deployment
+ *    object whose three iterators are empty. Absent and empty are therefore the
+ *    same answer here, deliberately: no reader may distinguish "declares none"
+ *    from "could not be read", because the second is what the defensive returns
+ *    below produce and a fleet that draws no topology owes loam nothing.
+ *
+ * `metadata` is NOT carried on the records below, and neither is an instance's
+ * `kind`. Both are readable; no check reads them yet, and a field carried
+ * before a caller needs it is a field nobody notices going wrong. Add one with
+ * the check that consumes it.
+ */
+/** No topology — what an absent block and an unreadable one both come back as. */
+export const NO_DEPLOYMENT = { nodes: [], instances: [], relationships: [] };
+/** Is there anything here? The opt-in every deployment check is gated on. */
+export function hasDeployment(d) {
+    return d.nodes.length > 0 || d.instances.length > 0 || d.relationships.length > 0;
+}
+/** A record, or nothing — the parse surface hands back `unknown`. */
+function record(v) {
+    return v && typeof v === "object" && !Array.isArray(v) ? v : undefined;
+}
+/** An iterable produced by `name()`, or an empty one when the surface is not what we measured. */
+function iterate(source, name) {
+    const fn = source[name];
+    if (typeof fn !== "function")
+        return [];
+    try {
+        const out = fn.call(source);
+        // A generator satisfies this; so does an array. Anything else is a shape
+        // change upstream, and the honest answer to one is "no topology read".
+        return out !== null && typeof out === "object" && Symbol.iterator in out
+            ? [...out]
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** A string field, or the empty string — never `undefined` leaking into a record. */
+function str(o, key) {
+    const v = o[key];
+    return typeof v === "string" ? v : "";
+}
+/** Tags as loam models them: a plain array of strings, always present. */
+function tags(o) {
+    const v = o["tags"];
+    return Array.isArray(v) ? v.filter((t) => typeof t === "string") : [];
+}
+/**
+ * Read the deployment model off an awaited `parsedModel()`.
+ *
+ * Defensive throughout, in the shape `readViewIds` established: an entry
+ * missing the one field that identifies it is DROPPED rather than reported with
+ * a hole, and a surface that is not what was measured yields an empty model
+ * instead of throwing. A check that cannot see the topology must say
+ * could-not-look through its own silence, never fail the fleet's parse.
+ */
+export function readDeployment(model) {
+    const root = record(model);
+    if (root === undefined)
+        return NO_DEPLOYMENT;
+    const deployment = record(root["deployment"]);
+    if (deployment === undefined)
+        return NO_DEPLOYMENT;
+    const nodes = [];
+    for (const raw of iterate(deployment, "nodes")) {
+        const n = record(raw);
+        if (n === undefined)
+            continue;
+        const id = str(n, "id");
+        if (id === "")
+            continue;
+        nodes.push({ id, kind: str(n, "kind"), title: str(n, "title"), tags: tags(n) });
+    }
+    const instances = [];
+    for (const raw of iterate(deployment, "instances")) {
+        const i = record(raw);
+        if (i === undefined)
+            continue;
+        const id = str(i, "id");
+        // The logical element is the whole point of the record. An instance whose
+        // element cannot be read joins to nothing, so reporting it would put a
+        // deployed thing on the map that no requirement could ever cover.
+        const element = record(i["element"]);
+        if (id === "" || element === undefined)
+            continue;
+        const elementId = str(element, "id");
+        if (elementId === "")
+            continue;
+        instances.push({ id, element: elementId, title: str(i, "title"), tags: tags(i) });
+    }
+    const relationships = [];
+    for (const raw of iterate(deployment, "relationships")) {
+        const r = record(raw);
+        if (r === undefined)
+            continue;
+        const source = record(r["source"]);
+        const target = record(r["target"]);
+        if (source === undefined || target === undefined)
+            continue;
+        const from = str(source, "id");
+        const to = str(target, "id");
+        if (from === "" || to === "")
+            continue;
+        // LikeC4 reports an untitled edge as `title: null` — normalized to the
+        // declared optional exactly as `flattenModel` does for the logical model.
+        const title = typeof r["title"] === "string" ? r["title"] : undefined;
+        relationships.push({ source: from, target: to, ...(title === undefined ? {} : { title }), tags: tags(r) });
+    }
+    return { nodes, instances, relationships };
+}
+//# sourceMappingURL=deployment.js.map

package/dist/core/c4/parsed/deployment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deployment.js","sourceRoot":"","sources":["../../../../src/core/c4/parsed/deployment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AAuCH,kFAAkF;AAClF,MAAM,CAAC,MAAM,aAAa,GAAoB,EAAE,KAAK,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE,aAAa,EAAE,EAAE,EAAE,CAAC;AAE9F,6EAA6E;AAC7E,MAAM,UAAU,aAAa,CAAC,CAAkB;IAC9C,OAAO,CAAC,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC,CAAC;AACpF,CAAC;AAED,qEAAqE;AACrE,SAAS,MAAM,CAAC,CAAU;IACxB,OAAO,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAE,CAA6B,CAAC,CAAC,CAAC,SAAS,CAAC;AACtG,CAAC;AAED,kGAAkG;AAClG,SAAS,OAAO,CAAC,MAA+B,EAAE,IAAY;IAC5D,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IACxB,IAAI,OAAO,EAAE,KAAK,UAAU;QAAE,OAAO,EAAE,CAAC;IACxC,IAAI,CAAC;QACH,MAAM,GAAG,GAAa,EAAoB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACxD,yEAAyE;QACzE,uEAAuE;QACvE,OAAO,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,IAAK,GAAc;YAClF,CAAC,CAAC,CAAC,GAAI,GAAyB,CAAC;YACjC,CAAC,CAAC,EAAE,CAAC;IACT,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,qFAAqF;AACrF,SAAS,GAAG,CAAC,CAA0B,EAAE,GAAW;IAClD,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;IACjB,OAAO,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACxC,CAAC;AAED,0EAA0E;AAC1E,SAAS,IAAI,CAAC,CAA0B;IACtC,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC;IACpB,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACrF,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAC3B,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,aAAa,CAAC;IAC7C,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC;IAC9C,IAAI,UAAU,KAAK,SAAS;QAAE,OAAO,aAAa,CAAC;IAEnD,MAAM,KAAK,GAAiB,EAAE,CAAC;IAC/B,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC,EAAE,CAAC;QAC/C,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QACtB,IAAI,CAAC,KAAK,SAAS;YAAE,SAAS;QAC9B,MAAM,EAAE,GAAG,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;QACxB,IAAI,EAAE,KAAK,EAAE;YAAE,SAAS;QACxB,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAClF,CAAC;IAED,MAAM,SAAS,GAAqB,EAAE,CAAC;IACvC,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,UAAU,EAAE,WAAW,CAAC,EAAE,CAAC;QACnD,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QACtB,IAAI,CAAC,KAAK,SAAS;YAAE,SAAS;QAC9B,MAAM,EAAE,GAAG,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;QACxB,0EAA0E;QAC1E,uEAAuE;QACvE,kEAAkE;QAClE,MAAM,OAAO,GAAG,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;QACrC,IAAI,EAAE,KAAK,EAAE,IAAI,OAAO,KAAK,SAAS;YAAE,SAAS;QACjD,MAAM,SAAS,GAAG,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QACrC,IAAI,SAAS,KAAK,EAAE;YAAE,SAAS;QAC/B,SAAS,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACpF,CAAC;IAED,MAAM,aAAa,GAAgB,EAAE,CAAC;IACtC,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,UAAU,EAAE,eAAe,CAAC,EAAE,CAAC;QACvD,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QACtB,IAAI,CAAC,KAAK,SAAS;YAAE,SAAS;QAC9B,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;QACnC,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;QACnC,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,SAAS;YAAE,SAAS;QAC3D,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAC/B,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAC7B,IAAI,IAAI,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE;YAAE,SAAS;QACvC,uEAAuE;QACvE,0EAA0E;QAC1E,MAAM,KAAK,GAAG,OAAO,CAAC,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QACtE,aAAa,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAC7G,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,CAAC;AAC7C,CAAC","sourcesContent":["/**\n * The DEPLOYMENT model a document declares — which physical nodes exist, which\n * containers are instanced where, and what talks to what across them.\n *\n * A `deployment { }` block has been legal in a docs repo since LikeC4 could\n * parse one, and until this reader existed loam saw none of it. The parser\n * resolved every `instanceOf` — so a container renamed out from under a\n * deployment node already failed the gate — and after that no requirement could\n * name a node, no `#obl-` tag on a datacenter was graded, and the context pack\n * an agent implements from did not mention topology at all. Integrity held at\n * the level of syntax and was absent at the level of requirements. ROADMAP's\n * deployment axis and `meta/docs/features/FEAT-1-the-deployment-axis/` are the\n * item and the specification; this module is its first half.\n *\n * ## Why this is a `parsed/` reader and not a package of its own\n *\n * It is the same job the three modules beside it do: take one corner of\n * LikeC4's parse output and hand back a loam-neutral record, defensively, with\n * its shape assumptions owned outright. `readSpecification`, `readDynamicViews`\n * and `readViewIds` are all called on the line above `flattenModel(model)` in\n * each of loam's three loaders, and so is this. FEAT-1's delta said\n * `src/core/c4/deploy/`; a package holding this alone would be a directory\n * pretending to be a subject (docs/DESIGN.md), and the delta was corrected\n * rather than the code bent to it — which is what an unarchived feature is for.\n *\n * **`parsed/` is still AT its five-file limit.** The global style-id census\n * rode into `view-ids.ts` because it IS that module's subject — one more\n * table asked the same question — and the next reader that is not a census\n * still needs the split first. The seam to split on is the one this file does\n * not share: `dynamic-views.ts` and `view-ids.ts` read `$data`, this one and\n * `specification.ts` read the model surface.\n *\n * ## What is read, and what is deliberately left\n *\n * Nodes, instances and relationships, with the ids, titles and tags each\n * carries. MEASURED at the 1.59.2 pin, and every line of it needed measuring\n * rather than assuming:\n *\n *  - `nodes()` returns deployment NODES only — an `instanceOf` is not among\n *    them, which is why instances are a second list rather than a filter.\n *  - an instance carries the LOGICAL element it deploys as `element.id`, and\n *    that is the whole join back to the C4 model: `eu.a.dbA -> orders.db`.\n *  - both nodes and instances carry `tags`, so `#obl-geo` on a datacenter is\n *    readable — the fail-open case that made this an item.\n *  - a relationship carries `tags` and `metadata` DIRECTLY (`r.metadata`, no\n *    `$relationship` indirection), and both model stages return byte-identical\n *    results, which is what lets `test/likec4-model-parity.test.ts` cover this\n *    read with the substitution it already pins.\n *  - a document with NO `deployment { }` block still returns a deployment\n *    object whose three iterators are empty. Absent and empty are therefore the\n *    same answer here, deliberately: no reader may distinguish \"declares none\"\n *    from \"could not be read\", because the second is what the defensive returns\n *    below produce and a fleet that draws no topology owes loam nothing.\n *\n * `metadata` is NOT carried on the records below, and neither is an instance's\n * `kind`. Both are readable; no check reads them yet, and a field carried\n * before a caller needs it is a field nobody notices going wrong. Add one with\n * the check that consumes it.\n */\n\n/** One deployment node — a region, a datacenter, a cluster; the kinds are the fleet's own. */\nexport interface DeployNode {\n  /** The dotted path LikeC4 gives it: `eu.dcA.k8sA`. */\n  id: string;\n  /** The `deploymentNode` kind the specification declares. */\n  kind: string;\n  title: string;\n  tags: string[];\n}\n\n/** One deployed instance of a logical element. */\nexport interface DeployInstance {\n  id: string;\n  /**\n   * The id of the C4 element this instance deploys — the join back to the\n   * logical model, and the only reason an instance is worth reading at all.\n   */\n  element: string;\n  title: string;\n  tags: string[];\n}\n\n/** One edge between deployment objects — replication, failover, a network hop. */\nexport interface DeployRel {\n  source: string;\n  target: string;\n  title?: string;\n  tags: string[];\n}\n\n/** A document's whole deployment model, flattened. */\nexport interface DeploymentModel {\n  nodes: DeployNode[];\n  instances: DeployInstance[];\n  relationships: DeployRel[];\n}\n\n/** No topology — what an absent block and an unreadable one both come back as. */\nexport const NO_DEPLOYMENT: DeploymentModel = { nodes: [], instances: [], relationships: [] };\n\n/** Is there anything here? The opt-in every deployment check is gated on. */\nexport function hasDeployment(d: DeploymentModel): boolean {\n  return d.nodes.length > 0 || d.instances.length > 0 || d.relationships.length > 0;\n}\n\n/** A record, or nothing — the parse surface hands back `unknown`. */\nfunction record(v: unknown): Record<string, unknown> | undefined {\n  return v && typeof v === \"object\" && !Array.isArray(v) ? (v as Record<string, unknown>) : undefined;\n}\n\n/** An iterable produced by `name()`, or an empty one when the surface is not what we measured. */\nfunction iterate(source: Record<string, unknown>, name: string): unknown[] {\n  const fn = source[name];\n  if (typeof fn !== \"function\") return [];\n  try {\n    const out: unknown = (fn as () => unknown).call(source);\n    // A generator satisfies this; so does an array. Anything else is a shape\n    // change upstream, and the honest answer to one is \"no topology read\".\n    return out !== null && typeof out === \"object\" && Symbol.iterator in (out as object)\n      ? [...(out as Iterable<unknown>)]\n      : [];\n  } catch {\n    return [];\n  }\n}\n\n/** A string field, or the empty string — never `undefined` leaking into a record. */\nfunction str(o: Record<string, unknown>, key: string): string {\n  const v = o[key];\n  return typeof v === \"string\" ? v : \"\";\n}\n\n/** Tags as loam models them: a plain array of strings, always present. */\nfunction tags(o: Record<string, unknown>): string[] {\n  const v = o[\"tags\"];\n  return Array.isArray(v) ? v.filter((t): t is string => typeof t === \"string\") : [];\n}\n\n/**\n * Read the deployment model off an awaited `parsedModel()`.\n *\n * Defensive throughout, in the shape `readViewIds` established: an entry\n * missing the one field that identifies it is DROPPED rather than reported with\n * a hole, and a surface that is not what was measured yields an empty model\n * instead of throwing. A check that cannot see the topology must say\n * could-not-look through its own silence, never fail the fleet's parse.\n */\nexport function readDeployment(model: unknown): DeploymentModel {\n  const root = record(model);\n  if (root === undefined) return NO_DEPLOYMENT;\n  const deployment = record(root[\"deployment\"]);\n  if (deployment === undefined) return NO_DEPLOYMENT;\n\n  const nodes: DeployNode[] = [];\n  for (const raw of iterate(deployment, \"nodes\")) {\n    const n = record(raw);\n    if (n === undefined) continue;\n    const id = str(n, \"id\");\n    if (id === \"\") continue;\n    nodes.push({ id, kind: str(n, \"kind\"), title: str(n, \"title\"), tags: tags(n) });\n  }\n\n  const instances: DeployInstance[] = [];\n  for (const raw of iterate(deployment, \"instances\")) {\n    const i = record(raw);\n    if (i === undefined) continue;\n    const id = str(i, \"id\");\n    // The logical element is the whole point of the record. An instance whose\n    // element cannot be read joins to nothing, so reporting it would put a\n    // deployed thing on the map that no requirement could ever cover.\n    const element = record(i[\"element\"]);\n    if (id === \"\" || element === undefined) continue;\n    const elementId = str(element, \"id\");\n    if (elementId === \"\") continue;\n    instances.push({ id, element: elementId, title: str(i, \"title\"), tags: tags(i) });\n  }\n\n  const relationships: DeployRel[] = [];\n  for (const raw of iterate(deployment, \"relationships\")) {\n    const r = record(raw);\n    if (r === undefined) continue;\n    const source = record(r[\"source\"]);\n    const target = record(r[\"target\"]);\n    if (source === undefined || target === undefined) continue;\n    const from = str(source, \"id\");\n    const to = str(target, \"id\");\n    if (from === \"\" || to === \"\") continue;\n    // LikeC4 reports an untitled edge as `title: null` — normalized to the\n    // declared optional exactly as `flattenModel` does for the logical model.\n    const title = typeof r[\"title\"] === \"string\" ? r[\"title\"] : undefined;\n    relationships.push({ source: from, target: to, ...(title === undefined ? {} : { title }), tags: tags(r) });\n  }\n\n  return { nodes, instances, relationships };\n}\n"]}

package/dist/core/c4/parsed/dynamic-views.js

@@ -0,0 +1,132 @@
+/**
+ * The `dynamic view`s a document DECLARES, read off LikeC4's parsed model.
+ *
+ * This is the only module in loam permitted to touch `$data`, and
+ * `scripts/arch-check.mjs` enforces that rather than trusting it (docs/DESIGN.md
+ * rule 26). The confinement is the point: `$data` is public and typed but thinly
+ * documented for this use, so an upstream shape change has a blast radius of one
+ * file, and `test/likec4-view-shape.test.ts` is the tripwire that fires before
+ * the change reaches a check.
+ *
+ * It takes the WHOLE model as `unknown` rather than a `$data` slice handed in by
+ * its caller, and that is not squeamishness — naming `$data` in `../likec4.ts`
+ * would violate the containment scan this module exists behind. Callers pass the
+ * model; every assumption about LikeC4's record shape lives here.
+ *
+ * Everything is defensive, in the same posture as `./specification.ts`: a shape
+ * this reader cannot make sense of degrades to ZERO views, never to a wrong one
+ * and never to a throw inside a validate run. That asymmetry is deliberate and
+ * is loam's standing rule for a suspended axis — a check with no views to grade
+ * reports could-not-look, while a check fed a half-read view would report
+ * nothing-wrong about a flow it never saw.
+ */
+import { descText } from "./values.js";
+/** A record, or nothing — `v` is `unknown` off an untyped parse. */
+function record(v) {
+    return v && typeof v === "object" && !Array.isArray(v) ? v : undefined;
+}
+/** The value at `key`, when it is a non-empty string. */
+function str(rec, key) {
+    const v = rec[key];
+    return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+/**
+ * Every leaf step under `entries`, depth-first in author order.
+ *
+ * Steps NEST: a `loop 'until accepted' { ... }` arrives as an entry with
+ * `_type: "loop"`, a title, its own `steps[]`, and NO endpoints and NO `astPath`
+ * of its own (measured). A walk that treated every entry as a hop would read the
+ * bracket as a step and then fail to find a relationship backing it — inventing
+ * a finding out of a grouping the author drew for legibility.
+ *
+ * The test is structural rather than a list of group keywords (`loop`, `par`,
+ * ...): an entry with a nested `steps` array is a group whatever LikeC4 calls
+ * it, and an entry with two string endpoints is a hop. A future group kind
+ * therefore flattens correctly on the day it ships instead of on the day
+ * somebody notices.
+ */
+function leaves(entries, out) {
+    if (!Array.isArray(entries))
+        return;
+    for (const entry of entries) {
+        const rec = record(entry);
+        if (!rec)
+            continue;
+        if (Array.isArray(rec["steps"])) {
+            leaves(rec["steps"], out);
+            continue;
+        }
+        if (typeof rec["source"] === "string" && typeof rec["target"] === "string")
+            out.push(rec);
+    }
+}
+/** One leaf entry as a `ParsedStep`. Every leaf yields one; nothing is dropped. */
+function step(rec, ordinal) {
+    const astPath = str(rec, "astPath");
+    const title = str(rec, "title");
+    const notes = descText(rec["notes"]);
+    return {
+        ordinal,
+        source: rec["source"],
+        target: rec["target"],
+        ...(title === undefined ? {} : { title }),
+        ...(notes === undefined ? {} : { notes }),
+        // Present-and-true is the only truthy form LikeC4 emits; absent means
+        // forward. Read as a boolean rather than carried as `true | undefined` so a
+        // caller cannot accidentally test `=== false` against a key that is never
+        // written.
+        isBackward: rec["isBackward"] === true,
+        ...(astPath === undefined ? {} : { astPath }),
+    };
+}
+/**
+ * The dynamic views one parsed document declares, in the record's own order.
+ *
+ * `model` is the awaited `parsedModel()` result. The `await` matters and is the
+ * mistake every draft of this made: `$data` is `undefined` on the unresolved
+ * promise, so a reader handed the promise reports a document with views as
+ * having none — a silent zero, which is the one wrong answer this module is
+ * written to avoid.
+ *
+ * Two entries are dropped on the way out, for different reasons:
+ *
+ *  - Anything whose `_type` is not `"dynamic"`. LikeC4 synthesises an `index`
+ *    view into EVERY document, including one with no `views` block at all
+ *    (measured), so reporting element views would be reporting a fiction the
+ *    author never wrote. A census that must see authored element views wants the
+ *    other filter rule 26 states — `sourcePath !== undefined` — and must not
+ *    reuse this function to get it.
+ *  - Anything with no `id`. There is nothing to name in a finding, and a view
+ *    loam cannot name is a view it cannot ask anybody to fix.
+ */
+export function readDynamicViews(model) {
+    const data = record(record(model)?.["$data"]);
+    const views = record(data?.["views"]);
+    if (!views)
+        return [];
+    const out = [];
+    for (const raw of Object.values(views)) {
+        const rec = record(raw);
+        if (!rec || rec["_type"] !== "dynamic")
+            continue;
+        const id = str(rec, "id");
+        if (id === undefined)
+            continue;
+        const found = [];
+        leaves(rec["steps"], found);
+        const steps = found.map((leaf, i) => step(leaf, i + 1));
+        const title = str(rec, "title");
+        const description = descText(rec["description"]);
+        const sourcePath = str(rec, "sourcePath");
+        out.push({
+            id,
+            ...(sourcePath === undefined ? {} : { sourcePath }),
+            tags: Array.isArray(rec["tags"]) ? rec["tags"].filter((t) => typeof t === "string") : [],
+            ...(title === undefined ? {} : { title }),
+            ...(description === undefined ? {} : { description }),
+            steps,
+        });
+    }
+    return out;
+}
+//# sourceMappingURL=dynamic-views.js.map

package/dist/core/c4/parsed/dynamic-views.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dynamic-views.js","sourceRoot":"","sources":["../../../../src/core/c4/parsed/dynamic-views.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The `dynamic view`s a document DECLARES, read off LikeC4's parsed model.\n *\n * This is the only module in loam permitted to touch `$data`, and\n * `scripts/arch-check.mjs` enforces that rather than trusting it (docs/DESIGN.md\n * rule 26). The confinement is the point: `$data` is public and typed but thinly\n * documented for this use, so an upstream shape change has a blast radius of one\n * file, and `test/likec4-view-shape.test.ts` is the tripwire that fires before\n * the change reaches a check.\n *\n * It takes the WHOLE model as `unknown` rather than a `$data` slice handed in by\n * its caller, and that is not squeamishness — naming `$data` in `../likec4.ts`\n * would violate the containment scan this module exists behind. Callers pass the\n * model; every assumption about LikeC4's record shape lives here.\n *\n * Everything is defensive, in the same posture as `./specification.ts`: a shape\n * this reader cannot make sense of degrades to ZERO views, never to a wrong one\n * and never to a throw inside a validate run. That asymmetry is deliberate and\n * is loam's standing rule for a suspended axis — a check with no views to grade\n * reports could-not-look, while a check fed a half-read view would report\n * nothing-wrong about a flow it never saw.\n */\nimport { descText } from \"./values.js\";\n\n/** One hop of a declared use case: an ordered edge between two elements. */\nexport interface ParsedStep {\n  /**\n   * 1-based pre-order position among the view's LEAF steps — what lets a finding\n   * say \"step 4 of Checkout\". Group wrappers do not consume an ordinal: a\n   * `loop` is a bracket around hops, not a hop, and counting it would shift\n   * every number after it away from what the author sees on the diagram.\n   */\n  ordinal: number;\n  /**\n   * The step's endpoints, ALREADY ORIENTED — see `isBackward`. Dotted FQN\n   * strings naming elements, never relationship ids: a step says who talks to\n   * whom, and which relationship backs that is a join loam performs later.\n   */\n  source: string;\n  target: string;\n  /**\n   * The step's label, absent when the author wrote none. Carried verbatim,\n   * because one join reads its opening characters: a title that opens with a\n   * candidate relationship's operation id or message name, set off by\n   * punctuation, picks that relationship where the map joins the pair by\n   * several (`pickedByTitle` in `../resolve/steps.ts`).\n   */\n  title?: string;\n  /** A `notes '...'` block on the step, decoded from LikeC4's rich-text shape. */\n  notes?: string;\n  /**\n   * True when the author wrote the hop as a reply — `a <- b` rather than\n   * `b -> a`. LOAD-BEARING, and measured: LikeC4 records `a <- b 'reply'` as\n   * `{source: b, target: a, isBackward: true}` — already reversed AND flagged —\n   * while a forward step carries no such key at all. `source`/`target` above are\n   * therefore correct as they stand and need no flipping; the flag is carried so\n   * a check can tell a return hop from a call, and so a message naming the\n   * failing step can suggest the `<-` spelling to an author who wrote the arrow\n   * the long way round.\n   */\n  isBackward: boolean;\n  /**\n   * LikeC4's own path to the step inside the view (`/steps@1/steps@0`), carried\n   * verbatim. It is the only stable handle on a nested step — two hops between\n   * the same pair inside different `loop` blocks are otherwise indistinguishable\n   * — and it is message text, never identity: nothing joins on it.\n   *\n   * OPTIONAL, and that is a deliberate refusal to make it load-bearing. Every\n   * leaf carries one at the 1.59.2 pin, so requiring it would look free — and\n   * would mean that an upstream release which stopped emitting it turned every\n   * use case in the fleet into a view with zero steps. That is the silent wrong\n   * answer this module exists to avoid: a hop loam cannot cite is still a hop it\n   * must grade.\n   */\n  astPath?: string;\n}\n\n/** One declared `dynamic view`, flattened to what rule 26 permits reading. */\nexport interface ParsedView {\n  id: string;\n  /**\n   * The name LikeC4 knows the document by, and it is only a PATH under\n   * `loadProject`: there it is relative to the project root, so\n   * `usecases/checkout.likec4` inside `architecture/`. Under the per-file\n   * loaders it is whatever that loader called the document — `source.c4` for\n   * `loadSource`, the basename for `loadBatch` — because there is no project\n   * for it to be relative to.\n   *\n   * So: name a file with it only when the views came from `loadProject`. That\n   * is the only reader that has one, which is also the only reader that needs\n   * one — a use case lives in a file of its own now, and a finding that cannot\n   * name that file sends its reader to the landscape to look for something\n   * that is not there.\n   *\n   * Absent for anything LikeC4 synthesized rather than read off a file, which\n   * is how the census reader tells the two apart.\n   */\n  sourcePath?: string;\n  /**\n   * The view's declared tags, `[]` when it declares none. Normalized here\n   * because LikeC4 reads an untagged view's tags as `null`, and a caller\n   * testing `.length` on that would throw inside a validate run.\n   *\n   * Tags live on the VIEW and nowhere else: a step cannot carry tags, and\n   * `metadata` on a step is a hard parse error. That is measured, and it is why\n   * a use case is opted in as a whole rather than hop by hop.\n   */\n  tags: string[];\n  title?: string;\n  description?: string;\n  /** The declared hops, in author order, groups flattened away. */\n  steps: ParsedStep[];\n}\n\n/** A record, or nothing — `v` is `unknown` off an untyped parse. */\nfunction record(v: unknown): Record<string, unknown> | undefined {\n  return v && typeof v === \"object\" && !Array.isArray(v) ? (v as Record<string, unknown>) : undefined;\n}\n\n/** The value at `key`, when it is a non-empty string. */\nfunction str(rec: Record<string, unknown>, key: string): string | undefined {\n  const v = rec[key];\n  return typeof v === \"string\" && v.length > 0 ? v : undefined;\n}\n\n/**\n * Every leaf step under `entries`, depth-first in author order.\n *\n * Steps NEST: a `loop 'until accepted' { ... }` arrives as an entry with\n * `_type: \"loop\"`, a title, its own `steps[]`, and NO endpoints and NO `astPath`\n * of its own (measured). A walk that treated every entry as a hop would read the\n * bracket as a step and then fail to find a relationship backing it — inventing\n * a finding out of a grouping the author drew for legibility.\n *\n * The test is structural rather than a list of group keywords (`loop`, `par`,\n * ...): an entry with a nested `steps` array is a group whatever LikeC4 calls\n * it, and an entry with two string endpoints is a hop. A future group kind\n * therefore flattens correctly on the day it ships instead of on the day\n * somebody notices.\n */\nfunction leaves(entries: unknown, out: Record<string, unknown>[]): void {\n  if (!Array.isArray(entries)) return;\n  for (const entry of entries) {\n    const rec = record(entry);\n    if (!rec) continue;\n    if (Array.isArray(rec[\"steps\"])) {\n      leaves(rec[\"steps\"], out);\n      continue;\n    }\n    if (typeof rec[\"source\"] === \"string\" && typeof rec[\"target\"] === \"string\") out.push(rec);\n  }\n}\n\n/** One leaf entry as a `ParsedStep`. Every leaf yields one; nothing is dropped. */\nfunction step(rec: Record<string, unknown>, ordinal: number): ParsedStep {\n  const astPath = str(rec, \"astPath\");\n  const title = str(rec, \"title\");\n  const notes = descText(rec[\"notes\"]);\n  return {\n    ordinal,\n    source: rec[\"source\"] as string,\n    target: rec[\"target\"] as string,\n    ...(title === undefined ? {} : { title }),\n    ...(notes === undefined ? {} : { notes }),\n    // Present-and-true is the only truthy form LikeC4 emits; absent means\n    // forward. Read as a boolean rather than carried as `true | undefined` so a\n    // caller cannot accidentally test `=== false` against a key that is never\n    // written.\n    isBackward: rec[\"isBackward\"] === true,\n    ...(astPath === undefined ? {} : { astPath }),\n  };\n}\n\n/**\n * The dynamic views one parsed document declares, in the record's own order.\n *\n * `model` is the awaited `parsedModel()` result. The `await` matters and is the\n * mistake every draft of this made: `$data` is `undefined` on the unresolved\n * promise, so a reader handed the promise reports a document with views as\n * having none — a silent zero, which is the one wrong answer this module is\n * written to avoid.\n *\n * Two entries are dropped on the way out, for different reasons:\n *\n *  - Anything whose `_type` is not `\"dynamic\"`. LikeC4 synthesises an `index`\n *    view into EVERY document, including one with no `views` block at all\n *    (measured), so reporting element views would be reporting a fiction the\n *    author never wrote. A census that must see authored element views wants the\n *    other filter rule 26 states — `sourcePath !== undefined` — and must not\n *    reuse this function to get it.\n *  - Anything with no `id`. There is nothing to name in a finding, and a view\n *    loam cannot name is a view it cannot ask anybody to fix.\n */\nexport function readDynamicViews(model: unknown): ParsedView[] {\n  const data = record(record(model)?.[\"$data\"]);\n  const views = record(data?.[\"views\"]);\n  if (!views) return [];\n\n  const out: ParsedView[] = [];\n  for (const raw of Object.values(views)) {\n    const rec = record(raw);\n    if (!rec || rec[\"_type\"] !== \"dynamic\") continue;\n    const id = str(rec, \"id\");\n    if (id === undefined) continue;\n\n    const found: Record<string, unknown>[] = [];\n    leaves(rec[\"steps\"], found);\n    const steps = found.map((leaf, i) => step(leaf, i + 1));\n\n    const title = str(rec, \"title\");\n    const description = descText(rec[\"description\"]);\n    const sourcePath = str(rec, \"sourcePath\");\n    out.push({\n      id,\n      ...(sourcePath === undefined ? {} : { sourcePath }),\n      tags: Array.isArray(rec[\"tags\"]) ? rec[\"tags\"].filter((t): t is string => typeof t === \"string\") : [],\n      ...(title === undefined ? {} : { title }),\n      ...(description === undefined ? {} : { description }),\n      steps,\n    });\n  }\n  return out;\n}\n"]}