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

package/dist/core/c4/splice/placement.js

@@ -0,0 +1,298 @@
+import {} from "../likec4.js";
+import { elementService, serviceOf } from "../resolve/service.js";
+import { relSortKey } from "./identity/edges.js";
+import { aboveComments, closeSpot, lineStartAt, spotAfter } from "./text/spot.js";
+/* ------------------------------------------------------------------ */
+/* Landscape placement — where a top-level addition lands               */
+/* ------------------------------------------------------------------ */
+/**
+ * The placement scheme, in full. It never moves an authored byte — placement
+ * only chooses where NEW spliced blocks go — and it is deterministic in a
+ * stronger sense: archiving feature A then feature B (touching different
+ * services) yields the SAME final bytes as B then A, which is what lets two
+ * concurrent archive PRs merge in git instead of colliding on one shared
+ * append point.
+ *
+ *  - An ELEMENT whose service already has top-level elements in the model
+ *    (the elementService join — binding first, title as the fallback) lands
+ *    immediately after the last of them: it joins its service's neighborhood.
+ *    Two features touching the SAME service therefore land adjacently, and
+ *    their concurrent PRs still conflict — expected, and documented
+ *    (SCHEMA.md sends that conflict to the PR flow).
+ *  - An element opening a NEW service lands in the trailing region before the
+ *    model's closing brace: skip the trailing relationship run, then walk left
+ *    per same-service RUN, past every run whose leading id is
+ *    lexicographically greater — an insertion sort of neighborhood heads
+ *    against whatever is already there, which is what makes the region's
+ *    final order independent of archive order (see the note on elementSpot:
+ *    per-statement comparison was order-dependent).
+ *  - A RELATIONSHIP lands after the last top-level relationship touching its
+ *    SOURCE's service (either endpoint counts), then past the anchor's own
+ *    CLUSTER members with a smaller sort key — two edges anchored to the same
+ *    statement must order by key, not by which archived first. With no such
+ *    neighborhood it falls to the trailing region, cluster-head-key-sorted
+ *    the same insertion-sort way, after the trailing elements.
+ *  - The relationship walk sorts only within the region's ASCENDING TAIL — the
+ *    run loam's own insertions keep sorted — and stops where the existing order
+ *    descends (`relSpot` has the case and the order-independence argument). A
+ *    hand-written region is sorted by nobody, so walking into it made the spot
+ *    depend on how unrelated edges happened to be drawn. The element walk is
+ *    left unbounded: the map's top-level elements are few, a new service among
+ *    them misfiles nothing, and its bytes are pinned as they always were.
+ *  - A walk that stops BEFORE a statement, or at the closing brace, lands above
+ *    the comment written directly over it (`aboveComments` in `./text/spot.ts`):
+ *    a comment is about what follows it, and an addition between the two
+ *    misfiles under it.
+ *
+ * A landscape may hold SEVERAL top-level `model { }` blocks, and LikeC4 reads
+ * them as one model. Placement keeps every rule above and adds one: an
+ * ANCHORED addition lands in its anchor's block (after the neighbor, clamped
+ * to that block's closing brace), and an UNANCHORED one — the trailing-region
+ * walks — lands in `HOME_BLOCK`, never crossing a block boundary. A same-service
+ * run and a relationship cluster are contiguous statements of ONE block: the
+ * views or the specification between two blocks are not a neighborhood.
+ *
+ * LikeC4 reference resolution is not order-dependent, so a relationship
+ * placed before an element it names still parses; the in-memory parse net in
+ * landscape-merge.ts's planLandscapeMerge stays as the backstop regardless.
+ */
+/**
+ * The block an addition with no anchor lands in: the document's FIRST
+ * `model { }` block.
+ *
+ * First, because it is the block every unanchored addition already landed in
+ * before the scan could see a second one — the scan stopped at the first
+ * match — so a single-block map places byte-identically, and a map that grew
+ * a second block keeps receiving new services where its older ones went. It
+ * is also invariant under every addition this merge can make (an archive never
+ * creates or reorders a block), which is what order-independence needs of it:
+ * a block chosen by size or content would move as the archives landed, and the
+ * same two features would compose to different bytes by archive order. The
+ * service-model splice (`./model/merge.ts`) uses the same block for the same
+ * reasons.
+ */
+export const HOME_BLOCK = 0;
+/** The statements of one block, in document order — what a trailing walk may step over. */
+function inBlock(stmts, block) {
+    return stmts.filter((s) => s.block === block);
+}
+/** The model's top-level statements in document order, joined to the parsed elements for services. */
+export function topStatements(scan, els) {
+    // An `extend <fqn>` frame is never a top-level declaration of THIS document —
+    // it reopens one another document owns — so it anchors nothing and displaces
+    // nothing. Undotted fqns are the reason the tag is checked rather than the
+    // dot: `extend paymentService { }` would otherwise read as a declaration of
+    // `paymentService` here.
+    const topEls = scan.elements.filter((e) => e.extend !== true && !e.id.includes("."));
+    const bound = new Map(els.map((e) => [e.id, elementService(e)]));
+    const stmts = topEls.map((e) => ({
+        kind: "element",
+        id: e.id,
+        key: "",
+        services: [bound.get(e.id) ?? e.id],
+        start: e.start,
+        end: e.end,
+        block: e.block,
+    }));
+    // Every top-level FRAME a statement can sit inside: the elements, and the
+    // `extend` frames, which hold edges as well as children.
+    const frames = scan.elements.filter((e) => e.extend === true || !e.id.includes("."));
+    for (const r of scan.rels) {
+        // A rel declared inside an element's body is not a top-level statement —
+        // anchoring after it would splice into the parent's block. Inside an
+        // `extend` frame it is worse than misplaced: the frame is a SCOPE, so an
+        // edge spliced in after it re-resolves there, and the delta's `zulu ->
+        // beta` landed inside `extend alpha { beta = … }` as an edge into
+        // `alpha.beta` — a merge that parses, written at exit 0 (probed
+        // 2026-10-20). Only the extend frames' edges are new to this filter.
+        if (frames.some((e) => r.start > e.start && r.start < e.end))
+            continue;
+        stmts.push({
+            kind: "rel",
+            id: "",
+            key: relSortKey(els, r),
+            // Deliberately no `known` fleet set here: this resolution only decides
+            // WHERE in the file a statement anchors, both sides of every comparison
+            // resolve through the same call, and the merged document is re-parsed
+            // before anything is written — a wrong grouping is cosmetic, never a
+            // wrong merge.
+            services: [serviceOf(els, r.source), serviceOf(els, r.target)],
+            start: r.start,
+            end: r.end,
+            block: r.block,
+        });
+    }
+    return stmts.sort((a, b) => a.start - b.start);
+}
+/**
+ * The trailing walks move in PLACEMENT UNITS, never single statements. A unit
+ * is a service neighborhood: a contiguous run of top-level elements resolving
+ * to one service, or a contiguous cluster of relationships grown around the
+ * statements touching one — keyed by its LEADING statement's id/key. Anchored
+ * inserts extend a neighborhood without changing its head, so the insertion
+ * sort the trailing region maintains is over neighborhood heads, which
+ * archive order cannot reshuffle. Comparing per statement instead let an
+ * anchored insert legally sit a LOWER id/key after a higher one (its anchor
+ * decides where it lives, not its own sort key), and a later trailing walk
+ * then stopped at different statements depending on which archive had run
+ * first — order-DEPENDENT bytes for features touching disjoint services, the
+ * exact regime the scheme guarantees.
+ */
+export function elementSpot(region, id, service) {
+    const { text, blocks } = region;
+    let anchor;
+    for (const s of region.stmts) {
+        if (s.kind === "element" && s.services.includes(service))
+            anchor = s;
+    }
+    if (anchor !== undefined)
+        return spotAfter(text, blocks[anchor.block].close, anchor.end);
+    const stmts = inBlock(region.stmts, HOME_BLOCK);
+    const close = blocks[HOME_BLOCK].close;
+    let i = stmts.length - 1;
+    let before;
+    while (i >= 0 && stmts[i].kind === "rel") {
+        before = stmts[i];
+        i -= 1;
+    }
+    while (i >= 0 && stmts[i].kind === "element") {
+        // The same-service run ending here is one unit: skip it whole or stop
+        // before it whole — an anchored member may carry any id, the run's
+        // LEADING id is its sort key.
+        let j = i;
+        while (j > 0 && stmts[j - 1].kind === "element" && stmts[j - 1].services[0] === stmts[i].services[0])
+            j -= 1;
+        if (!(stmts[j].id > id))
+            break;
+        before = stmts[j];
+        i = j - 1;
+    }
+    return before !== undefined ? beforeSpot(text, before) : closeSpot(text, close);
+}
+/**
+ * Each top-level statement's cluster, as the index of the cluster's leading
+ * statement. A relationship whose SOURCE's service some earlier relationship
+ * in the same contiguous stretch already touches is an anchored join — it
+ * belongs to that neighborhood wherever its own key would sort. One whose
+ * source's service nothing before it touches opens a new cluster; sharing
+ * only a TARGET does not join (every trailing edge into a busy hub would
+ * otherwise dissolve into one giant cluster, and the trailing sort with it).
+ * Recomputed from bytes alone, so the next archive sees the same units this
+ * one placed.
+ */
+function relClusterHeads(stmts) {
+    const heads = stmts.map((_, i) => i);
+    let head = -1;
+    let services = null;
+    for (let i = 0; i < stmts.length; i += 1) {
+        const s = stmts[i];
+        // A block boundary ends a cluster exactly as an element does: the first
+        // edge of the next block is not contiguous with the last of this one.
+        if (i > 0 && stmts[i - 1].block !== s.block) {
+            head = -1;
+            services = null;
+        }
+        if (s.kind !== "rel") {
+            head = -1;
+            services = null;
+            continue;
+        }
+        if (services !== null && services.has(s.services[0])) {
+            for (const svc of s.services)
+                services.add(svc);
+        }
+        else {
+            head = i;
+            services = new Set(s.services);
+        }
+        heads[i] = head;
+    }
+    return heads;
+}
+/**
+ * Where a relationship lands: after its source's neighborhood, or — with none —
+ * in the trailing region, insertion-sorted among the cluster heads.
+ *
+ * The trailing walk sorts only within the region's ASCENDING TAIL: it steps left
+ * past a cluster whose head sorts above the new key only while that head also
+ * sorts at or below the head of the cluster after it. The insertions loam makes
+ * keep that tail sorted, so on a region loam wrote the walk is the plain
+ * insertion sort it always was; a hand-written region is sorted by nobody, and
+ * walking into it made the landing spot a function of unrelated edges — an edge
+ * drawn `svc -> kafka` let a new edge walk past it, the same edge turned round
+ * (`kafka -[delivers]-> svc`, a head that sorts lower) stopped the walk, and the
+ * addition landed sixty lines away under a comment about something else
+ * (2026-10). Order-independence survives the bound: the statements before the
+ * tail never change, because an addition sorting below the tail's first head
+ * becomes its new first head, and that still sorts below the statement the tail
+ * broke from — so every archive inserts into the same sorted run, whatever
+ * order they land in.
+ */
+export function relSpot(region, sourceService, key) {
+    const anchored = anchoredRelSpot(region, sourceService, key);
+    if (anchored !== null)
+        return anchored;
+    const { text, blocks } = region;
+    const stmts = inBlock(region.stmts, HOME_BLOCK);
+    const close = blocks[HOME_BLOCK].close;
+    const heads = relClusterHeads(stmts);
+    let i = stmts.length - 1;
+    let before;
+    while (i >= 0 && stmts[i].kind === "rel") {
+        const j = heads[i];
+        if (!(stmts[j].key > key))
+            break;
+        if (before !== undefined && stmts[j].key > before.key)
+            break;
+        before = stmts[j];
+        i = j - 1;
+    }
+    return before !== undefined ? beforeSpot(text, before) : closeSpot(text, close);
+}
+/** After the last relationship touching the source's service, in that relationship's block — null when none does. */
+function anchoredRelSpot(region, sourceService, key) {
+    const { text, stmts, blocks } = region;
+    const heads = relClusterHeads(stmts);
+    let anchorAt = -1;
+    for (let i = 0; i < stmts.length; i += 1) {
+        const s = stmts[i];
+        if (s.kind === "rel" && s.services.includes(sourceService))
+            anchorAt = i;
+    }
+    if (anchorAt !== -1) {
+        // Past the anchor, order among the cluster's OWN members is by key — two
+        // edges anchored to the same statement must order by key, not by which
+        // archived first — but the walk never leaves the cluster: the next
+        // cluster is another neighborhood's, and stepping over it would depend
+        // on which archive put it there.
+        let last = stmts[anchorAt];
+        for (let j = anchorAt + 1; j < stmts.length; j += 1) {
+            const s = stmts[j];
+            if (s.kind !== "rel" || heads[j] !== heads[anchorAt] || s.key >= key)
+                break;
+            last = s;
+        }
+        return spotAfter(text, blocks[last.block].close, last.end);
+    }
+    return null;
+}
+/**
+ * Insertion before an existing statement: above the comment written directly
+ * over it when only whitespace precedes it on its line, at the statement itself
+ * — bare, displacing it onto a fresh line — when other text shares the line (a
+ * statement written on the `model {` line, say). The unguarded line start
+ * spliced the block BEFORE the model keyword, and the parse net refused a
+ * perfectly legal landscape.
+ *
+ * Above the comment, because a comment written over a statement is about that
+ * statement, or heads the section it opens: inserted at the statement's own
+ * line, an addition landed between a six-line explanation and the edge it
+ * explains (2026-10). `aboveComments` says which lines count.
+ */
+function beforeSpot(text, before) {
+    const ls = lineStartAt(text, before.start);
+    if (/^[ \t]*$/.test(text.slice(ls, before.start)))
+        return { at: aboveComments(text, ls), bare: false };
+    return { at: before.start, bare: true };
+}
+//# sourceMappingURL=placement.js.map

package/dist/core/c4/splice/placement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"placement.js","sourceRoot":"","sources":["../../../../src/core/c4/splice/placement.ts"],"names":[],"mappings":"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","sourcesContent":["import { type Elem } from \"../likec4.js\";\nimport { elementService, serviceOf } from \"../resolve/service.js\";\nimport type { ScannedBlock, ScannedModel } from \"../source-scan.js\";\nimport { relSortKey } from \"./identity/edges.js\";\nimport { aboveComments, closeSpot, lineStartAt, spotAfter, type Spot } from \"./text/spot.js\";\n\n/* ------------------------------------------------------------------ */\n/* Landscape placement — where a top-level addition lands               */\n/* ------------------------------------------------------------------ */\n\n/**\n * The placement scheme, in full. It never moves an authored byte — placement\n * only chooses where NEW spliced blocks go — and it is deterministic in a\n * stronger sense: archiving feature A then feature B (touching different\n * services) yields the SAME final bytes as B then A, which is what lets two\n * concurrent archive PRs merge in git instead of colliding on one shared\n * append point.\n *\n *  - An ELEMENT whose service already has top-level elements in the model\n *    (the elementService join — binding first, title as the fallback) lands\n *    immediately after the last of them: it joins its service's neighborhood.\n *    Two features touching the SAME service therefore land adjacently, and\n *    their concurrent PRs still conflict — expected, and documented\n *    (SCHEMA.md sends that conflict to the PR flow).\n *  - An element opening a NEW service lands in the trailing region before the\n *    model's closing brace: skip the trailing relationship run, then walk left\n *    per same-service RUN, past every run whose leading id is\n *    lexicographically greater — an insertion sort of neighborhood heads\n *    against whatever is already there, which is what makes the region's\n *    final order independent of archive order (see the note on elementSpot:\n *    per-statement comparison was order-dependent).\n *  - A RELATIONSHIP lands after the last top-level relationship touching its\n *    SOURCE's service (either endpoint counts), then past the anchor's own\n *    CLUSTER members with a smaller sort key — two edges anchored to the same\n *    statement must order by key, not by which archived first. With no such\n *    neighborhood it falls to the trailing region, cluster-head-key-sorted\n *    the same insertion-sort way, after the trailing elements.\n *  - The relationship walk sorts only within the region's ASCENDING TAIL — the\n *    run loam's own insertions keep sorted — and stops where the existing order\n *    descends (`relSpot` has the case and the order-independence argument). A\n *    hand-written region is sorted by nobody, so walking into it made the spot\n *    depend on how unrelated edges happened to be drawn. The element walk is\n *    left unbounded: the map's top-level elements are few, a new service among\n *    them misfiles nothing, and its bytes are pinned as they always were.\n *  - A walk that stops BEFORE a statement, or at the closing brace, lands above\n *    the comment written directly over it (`aboveComments` in `./text/spot.ts`):\n *    a comment is about what follows it, and an addition between the two\n *    misfiles under it.\n *\n * A landscape may hold SEVERAL top-level `model { }` blocks, and LikeC4 reads\n * them as one model. Placement keeps every rule above and adds one: an\n * ANCHORED addition lands in its anchor's block (after the neighbor, clamped\n * to that block's closing brace), and an UNANCHORED one — the trailing-region\n * walks — lands in `HOME_BLOCK`, never crossing a block boundary. A same-service\n * run and a relationship cluster are contiguous statements of ONE block: the\n * views or the specification between two blocks are not a neighborhood.\n *\n * LikeC4 reference resolution is not order-dependent, so a relationship\n * placed before an element it names still parses; the in-memory parse net in\n * landscape-merge.ts's planLandscapeMerge stays as the backstop regardless.\n */\n\n/**\n * The block an addition with no anchor lands in: the document's FIRST\n * `model { }` block.\n *\n * First, because it is the block every unanchored addition already landed in\n * before the scan could see a second one — the scan stopped at the first\n * match — so a single-block map places byte-identically, and a map that grew\n * a second block keeps receiving new services where its older ones went. It\n * is also invariant under every addition this merge can make (an archive never\n * creates or reorders a block), which is what order-independence needs of it:\n * a block chosen by size or content would move as the archives landed, and the\n * same two features would compose to different bytes by archive order. The\n * service-model splice (`./model/merge.ts`) uses the same block for the same\n * reasons.\n */\nexport const HOME_BLOCK = 0;\n\n/** A top-level statement of the living model, with everything placement asks of it. */\nexport interface TopStmt {\n  kind: \"element\" | \"rel\";\n  /** Element: its id. */\n  id: string;\n  /** Relationship: its placement sort key (relSortKey). */\n  key: string;\n  /** The service(s) this statement resolves to — one for an element, both endpoints for a rel. */\n  services: string[];\n  start: number;\n  end: number;\n  /** The `model { }` block it is written in, as `ScannedModel.blocks` indexes it. */\n  block: number;\n}\n\n/**\n * The living model as placement reads it: the text being spliced into, its\n * top-level statement layout, and the model blocks' braces. One value\n * because every spot is computed against all three at the same instant — a\n * layout paired with text a splice has since moved would place against a\n * document that no longer exists (see `modelRegion` in landscape-merge.ts's\n * planLandscapeMerge).\n */\nexport interface ModelRegion {\n  text: string;\n  stmts: TopStmt[];\n  /** Every top-level `model { }` block, by the index `TopStmt.block` names. */\n  blocks: readonly ScannedBlock[];\n}\n\n/** The statements of one block, in document order — what a trailing walk may step over. */\nfunction inBlock(stmts: TopStmt[], block: number): TopStmt[] {\n  return stmts.filter((s) => s.block === block);\n}\n\n/** The model's top-level statements in document order, joined to the parsed elements for services. */\nexport function topStatements(scan: ScannedModel, els: Elem[]): TopStmt[] {\n  // An `extend <fqn>` frame is never a top-level declaration of THIS document —\n  // it reopens one another document owns — so it anchors nothing and displaces\n  // nothing. Undotted fqns are the reason the tag is checked rather than the\n  // dot: `extend paymentService { }` would otherwise read as a declaration of\n  // `paymentService` here.\n  const topEls = scan.elements.filter((e) => e.extend !== true && !e.id.includes(\".\"));\n  const bound = new Map(els.map((e) => [e.id, elementService(e)]));\n  const stmts: TopStmt[] = topEls.map((e) => ({\n    kind: \"element\" as const,\n    id: e.id,\n    key: \"\",\n    services: [bound.get(e.id) ?? e.id],\n    start: e.start,\n    end: e.end,\n    block: e.block,\n  }));\n  // Every top-level FRAME a statement can sit inside: the elements, and the\n  // `extend` frames, which hold edges as well as children.\n  const frames = scan.elements.filter((e) => e.extend === true || !e.id.includes(\".\"));\n  for (const r of scan.rels) {\n    // A rel declared inside an element's body is not a top-level statement —\n    // anchoring after it would splice into the parent's block. Inside an\n    // `extend` frame it is worse than misplaced: the frame is a SCOPE, so an\n    // edge spliced in after it re-resolves there, and the delta's `zulu ->\n    // beta` landed inside `extend alpha { beta = … }` as an edge into\n    // `alpha.beta` — a merge that parses, written at exit 0 (probed\n    // 2026-10-20). Only the extend frames' edges are new to this filter.\n    if (frames.some((e) => r.start > e.start && r.start < e.end)) continue;\n    stmts.push({\n      kind: \"rel\",\n      id: \"\",\n      key: relSortKey(els, r),\n      // Deliberately no `known` fleet set here: this resolution only decides\n      // WHERE in the file a statement anchors, both sides of every comparison\n      // resolve through the same call, and the merged document is re-parsed\n      // before anything is written — a wrong grouping is cosmetic, never a\n      // wrong merge.\n      services: [serviceOf(els, r.source), serviceOf(els, r.target)],\n      start: r.start,\n      end: r.end,\n      block: r.block,\n    });\n  }\n  return stmts.sort((a, b) => a.start - b.start);\n}\n\n\n/**\n * The trailing walks move in PLACEMENT UNITS, never single statements. A unit\n * is a service neighborhood: a contiguous run of top-level elements resolving\n * to one service, or a contiguous cluster of relationships grown around the\n * statements touching one — keyed by its LEADING statement's id/key. Anchored\n * inserts extend a neighborhood without changing its head, so the insertion\n * sort the trailing region maintains is over neighborhood heads, which\n * archive order cannot reshuffle. Comparing per statement instead let an\n * anchored insert legally sit a LOWER id/key after a higher one (its anchor\n * decides where it lives, not its own sort key), and a later trailing walk\n * then stopped at different statements depending on which archive had run\n * first — order-DEPENDENT bytes for features touching disjoint services, the\n * exact regime the scheme guarantees.\n */\nexport function elementSpot(region: ModelRegion, id: string, service: string): Spot {\n  const { text, blocks } = region;\n  let anchor: TopStmt | undefined;\n  for (const s of region.stmts) {\n    if (s.kind === \"element\" && s.services.includes(service)) anchor = s;\n  }\n  if (anchor !== undefined) return spotAfter(text, blocks[anchor.block]!.close, anchor.end);\n  const stmts = inBlock(region.stmts, HOME_BLOCK);\n  const close = blocks[HOME_BLOCK]!.close;\n  let i = stmts.length - 1;\n  let before: TopStmt | undefined;\n  while (i >= 0 && stmts[i]!.kind === \"rel\") {\n    before = stmts[i];\n    i -= 1;\n  }\n  while (i >= 0 && stmts[i]!.kind === \"element\") {\n    // The same-service run ending here is one unit: skip it whole or stop\n    // before it whole — an anchored member may carry any id, the run's\n    // LEADING id is its sort key.\n    let j = i;\n    while (j > 0 && stmts[j - 1]!.kind === \"element\" && stmts[j - 1]!.services[0] === stmts[i]!.services[0]) j -= 1;\n    if (!(stmts[j]!.id > id)) break;\n    before = stmts[j];\n    i = j - 1;\n  }\n  return before !== undefined ? beforeSpot(text, before) : closeSpot(text, close);\n}\n\n/**\n * Each top-level statement's cluster, as the index of the cluster's leading\n * statement. A relationship whose SOURCE's service some earlier relationship\n * in the same contiguous stretch already touches is an anchored join — it\n * belongs to that neighborhood wherever its own key would sort. One whose\n * source's service nothing before it touches opens a new cluster; sharing\n * only a TARGET does not join (every trailing edge into a busy hub would\n * otherwise dissolve into one giant cluster, and the trailing sort with it).\n * Recomputed from bytes alone, so the next archive sees the same units this\n * one placed.\n */\nfunction relClusterHeads(stmts: TopStmt[]): number[] {\n  const heads = stmts.map((_, i) => i);\n  let head = -1;\n  let services: Set<string> | null = null;\n  for (let i = 0; i < stmts.length; i += 1) {\n    const s = stmts[i]!;\n    // A block boundary ends a cluster exactly as an element does: the first\n    // edge of the next block is not contiguous with the last of this one.\n    if (i > 0 && stmts[i - 1]!.block !== s.block) {\n      head = -1;\n      services = null;\n    }\n    if (s.kind !== \"rel\") {\n      head = -1;\n      services = null;\n      continue;\n    }\n    if (services !== null && services.has(s.services[0]!)) {\n      for (const svc of s.services) services.add(svc);\n    } else {\n      head = i;\n      services = new Set(s.services);\n    }\n    heads[i] = head;\n  }\n  return heads;\n}\n\n/**\n * Where a relationship lands: after its source's neighborhood, or — with none —\n * in the trailing region, insertion-sorted among the cluster heads.\n *\n * The trailing walk sorts only within the region's ASCENDING TAIL: it steps left\n * past a cluster whose head sorts above the new key only while that head also\n * sorts at or below the head of the cluster after it. The insertions loam makes\n * keep that tail sorted, so on a region loam wrote the walk is the plain\n * insertion sort it always was; a hand-written region is sorted by nobody, and\n * walking into it made the landing spot a function of unrelated edges — an edge\n * drawn `svc -> kafka` let a new edge walk past it, the same edge turned round\n * (`kafka -[delivers]-> svc`, a head that sorts lower) stopped the walk, and the\n * addition landed sixty lines away under a comment about something else\n * (2026-10). Order-independence survives the bound: the statements before the\n * tail never change, because an addition sorting below the tail's first head\n * becomes its new first head, and that still sorts below the statement the tail\n * broke from — so every archive inserts into the same sorted run, whatever\n * order they land in.\n */\nexport function relSpot(region: ModelRegion, sourceService: string, key: string): Spot {\n  const anchored = anchoredRelSpot(region, sourceService, key);\n  if (anchored !== null) return anchored;\n  const { text, blocks } = region;\n  const stmts = inBlock(region.stmts, HOME_BLOCK);\n  const close = blocks[HOME_BLOCK]!.close;\n  const heads = relClusterHeads(stmts);\n  let i = stmts.length - 1;\n  let before: TopStmt | undefined;\n  while (i >= 0 && stmts[i]!.kind === \"rel\") {\n    const j = heads[i]!;\n    if (!(stmts[j]!.key > key)) break;\n    if (before !== undefined && stmts[j]!.key > before.key) break;\n    before = stmts[j];\n    i = j - 1;\n  }\n  return before !== undefined ? beforeSpot(text, before) : closeSpot(text, close);\n}\n\n/** After the last relationship touching the source's service, in that relationship's block — null when none does. */\nfunction anchoredRelSpot(region: ModelRegion, sourceService: string, key: string): Spot | null {\n  const { text, stmts, blocks } = region;\n  const heads = relClusterHeads(stmts);\n  let anchorAt = -1;\n  for (let i = 0; i < stmts.length; i += 1) {\n    const s = stmts[i]!;\n    if (s.kind === \"rel\" && s.services.includes(sourceService)) anchorAt = i;\n  }\n  if (anchorAt !== -1) {\n    // Past the anchor, order among the cluster's OWN members is by key — two\n    // edges anchored to the same statement must order by key, not by which\n    // archived first — but the walk never leaves the cluster: the next\n    // cluster is another neighborhood's, and stepping over it would depend\n    // on which archive put it there.\n    let last = stmts[anchorAt]!;\n    for (let j = anchorAt + 1; j < stmts.length; j += 1) {\n      const s = stmts[j]!;\n      if (s.kind !== \"rel\" || heads[j] !== heads[anchorAt] || s.key >= key) break;\n      last = s;\n    }\n    return spotAfter(text, blocks[last.block]!.close, last.end);\n  }\n  return null;\n}\n\n/**\n * Insertion before an existing statement: above the comment written directly\n * over it when only whitespace precedes it on its line, at the statement itself\n * — bare, displacing it onto a fresh line — when other text shares the line (a\n * statement written on the `model {` line, say). The unguarded line start\n * spliced the block BEFORE the model keyword, and the parse net refused a\n * perfectly legal landscape.\n *\n * Above the comment, because a comment written over a statement is about that\n * statement, or heads the section it opens: inserted at the statement's own\n * line, an addition landed between a six-line explanation and the edge it\n * explains (2026-10). `aboveComments` says which lines count.\n */\nfunction beforeSpot(text: string, before: TopStmt): Spot {\n  const ls = lineStartAt(text, before.start);\n  if (/^[ \\t]*$/.test(text.slice(ls, before.start))) return { at: aboveComments(text, ls), bare: false };\n  return { at: before.start, bare: true };\n}\n"]}

package/dist/core/c4/splice/text/spot.js

@@ -0,0 +1,131 @@
+/**
+ * Where a block enters a LikeC4 document, in byte offsets — the text half of
+ * the splice's placement. `../placement.ts` decides which statement an addition
+ * lands beside, by service and by sort key; everything here answers how that
+ * decision becomes an offset in the authored bytes without cutting into a
+ * comment, a body or the line another statement shares. The service-model
+ * splice (`../model/merge.ts`) asks the same questions of a document it does
+ * not group by service, and reads them from here for that reason.
+ */
+import { maskSource, pastComments, tokenEnd } from "../../source-mask.js";
+/**
+ * The line following the statement that ends at `end` — clamped to the closing
+ * brace's own spot. Exported for the service-model splice (`../model/merge.ts`),
+ * which asks the same two questions of a `model { }` block it does not group by
+ * service: after this statement, or last thing in the block.
+ *
+ * Unless code follows `end` on its line: then the spot is `end` itself, bare.
+ * The next line belongs to whatever is written there, and when that is a
+ * declaration whose body opens on the same line — `alpha = … { … }  beta = … {`
+ * — the line after is INSIDE beta: an addition anchored to alpha's service
+ * landed as `beta.kiwi`, in a merge that parsed and was written (exit 0,
+ * probed on main at 171555d). Right after the anchor is also what keeps two
+ * archives order-free when both anchor on that line: one anchored to alpha and
+ * one to beta used to share the next line's start, and whichever ran second
+ * landed above the other. A comment trailing the anchor is not code — the
+ * next line stays the spot, byte for byte as before — but a block comment
+ * it does not close is: its next line is inside the comment.
+ *
+ * A line comment ends where LikeC4's NL does, at `\r` as well as `\n` — the
+ * source mask agrees since the bare-CR fix — so `// note\r  beta = … {` is a
+ * comment and then code on the anchor's `\n`-line, and the spot after that
+ * line is inside beta: the same `beta.kiwi` merge, written at exit 0, which
+ * 171555d refused because it could not locate beta at all. A CRLF ending
+ * leaves nothing after the comment and keeps the next line, byte for byte.
+ */
+export function spotAfter(text, close, end) {
+    const nl = text.indexOf("\n", end);
+    const at = nl === -1 ? text.length : nl + 1;
+    let rest = pastComments(text.slice(end, Math.min(at, close)));
+    while (rest.startsWith("//")) {
+        const eol = rest.search(/[\r\n]/);
+        rest = eol === -1 ? "" : pastComments(rest.slice(eol));
+    }
+    if (rest !== "")
+        return { at: end, bare: true };
+    return at > close ? closeSpot(text, close) : { at, bare: false };
+}
+/**
+ * The last resort: directly before the model's closing brace — above a comment
+ * written directly over the brace, for the reason `aboveComments` gives.
+ */
+export function closeSpot(text, close) {
+    const ls = lineStartAt(text, close);
+    if (/^[ \t]*$/.test(text.slice(ls, close)))
+        return { at: aboveComments(text, ls), bare: false };
+    return { at: close, bare: true };
+}
+/**
+ * The start of the run of comment lines written directly above the line that
+ * starts at `at` — `at` itself when there is none. A blank line ends the run: a
+ * comment separated from what follows it by a blank line stands alone, and
+ * stays where it is. So does a line that is not comment from its first
+ * character to `at` — code, the `model {` line — and a line that starts INSIDE
+ * a block comment or a string opened above it, whatever it looks like: the last
+ * line of `/* retired … // old edge *\/` reads as a line comment on its own,
+ * and splicing at its start put the addition inside the block comment, where
+ * the map parsed clean and the edge was gone at exit 0 (review, 2026-10-22).
+ * Which lines are inside what is read off one pass over the whole text, never
+ * off the line.
+ *
+ * Every walk in `../placement.ts` that stops before a statement or at the
+ * closing brace lands here, and the rule has to be the same at both for
+ * placement to stay order-independent: each splits the lines between two
+ * statements at the same point, so an addition landing there first and one
+ * landing beside it second compose to the bytes the opposite order writes.
+ */
+export function aboveComments(text, at) {
+    const { comments, literals } = maskSource(text);
+    const inside = (p) => [...comments, ...literals].some((s) => s.start < p && p < s.end);
+    let top = at;
+    while (top > 0) {
+        const above = lineStartAt(text, top - 1);
+        if (text.slice(above, top).trim() === "" || inside(above) || !onlyComments(text.slice(above, at)))
+            break;
+        top = above;
+    }
+    return top;
+}
+/** Whether `text` holds nothing but whitespace and complete comments. */
+function onlyComments(text) {
+    let rest = pastComments(text);
+    while (rest.startsWith("//")) {
+        const eol = rest.search(/[\r\n]/);
+        rest = eol === -1 ? "" : pastComments(rest.slice(eol));
+    }
+    return rest === "";
+}
+export function lineStartAt(text, at) {
+    return text.lastIndexOf("\n", at - 1) + 1;
+}
+/**
+ * Where a child block enters an existing living parent: before the closing
+ * brace of the parent's body, on its own line at the parent's inner indent —
+ * and a parent that never had a body gains one around the child.
+ */
+export function nestedInsert(text, parent, block) {
+    if (parent.bodyOpen === -1) {
+        return { at: bodyAt(text, parent), insert: ` {\n${block}\n${parent.indent}}` };
+    }
+    const lineStart = text.lastIndexOf("\n", parent.bodyClose - 1) + 1;
+    if (/^[ \t]*$/.test(text.slice(lineStart, parent.bodyClose))) {
+        return { at: lineStart, insert: `${block}\n` };
+    }
+    // `{ ... }` on one line — break the brace onto its own line to make room.
+    return { at: parent.bodyClose, insert: `\n${block}\n${parent.indent}` };
+}
+/**
+ * Where a bodyless parent's new body opens: where its span ends, unless a line
+ * comment trails its last token there. The span carries that comment — it is
+ * the declaration's own authored text (`statementEnd`) — so the `{` landed
+ * INSIDE `// the api`, everything after it on the line was comment, and the
+ * parse net refused a valid map ("Expecting end of file"). It opens before the
+ * comment now, which then trails the new closing brace. A closed block comment
+ * is no such trap, and keeps the bytes it always had.
+ */
+function bodyAt(text, parent) {
+    const span = text.slice(parent.start, parent.end);
+    const last = parent.start + tokenEnd(maskSource(span), 0, span.length);
+    return pastComments(text.slice(last, parent.end)) === "" ? parent.end : last;
+}
+//# sourceMappingURL=spot.js.map

package/dist/core/c4/splice/text/spot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spot.js","sourceRoot":"","sources":["../../../../../src/core/c4/splice/text/spot.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAW1E;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,KAAa,EAAE,GAAW;IAChE,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACnC,MAAM,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC5C,IAAI,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IAC9D,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7B,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAClC,IAAI,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;IACzD,CAAC;IACD,IAAI,IAAI,KAAK,EAAE;QAAE,OAAO,EAAE,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAChD,OAAO,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AACnE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,KAAa;IACnD,MAAM,EAAE,GAAG,WAAW,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACpC,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,aAAa,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;IAChG,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AACnC,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY,EAAE,EAAU;IACpD,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;IAChD,MAAM,MAAM,GAAG,CAAC,CAAS,EAAW,EAAE,CAAC,CAAC,GAAG,QAAQ,EAAE,GAAG,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;IACxG,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,OAAO,GAAG,GAAG,CAAC,EAAE,CAAC;QACf,MAAM,KAAK,GAAG,WAAW,CAAC,IAAI,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC;QACzC,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YAAE,MAAM;QACzG,GAAG,GAAG,KAAK,CAAC;IACd,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,yEAAyE;AACzE,SAAS,YAAY,CAAC,IAAY;IAChC,IAAI,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAC9B,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7B,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAClC,IAAI,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;IACzD,CAAC;IACD,OAAO,IAAI,KAAK,EAAE,CAAC;AACrB,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,EAAU;IAClD,OAAO,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;AAC5C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,MAAsB,EAAE,KAAa;IAC9E,IAAI,MAAM,CAAC,QAAQ,KAAK,CAAC,CAAC,EAAE,CAAC;QAC3B,OAAO,EAAE,EAAE,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,OAAO,KAAK,KAAK,MAAM,CAAC,MAAM,GAAG,EAAE,CAAC;IACjF,CAAC;IACD,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,SAAS,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;IACnE,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC;QAC7D,OAAO,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,KAAK,IAAI,EAAE,CAAC;IACjD,CAAC;IACD,0EAA0E;IAC1E,OAAO,EAAE,EAAE,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,KAAK,KAAK,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC;AAC1E,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,MAAM,CAAC,IAAY,EAAE,MAAsB;IAClD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IAClD,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,GAAG,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IACvE,OAAO,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;AAC/E,CAAC","sourcesContent":["/**\n * Where a block enters a LikeC4 document, in byte offsets — the text half of\n * the splice's placement. `../placement.ts` decides which statement an addition\n * lands beside, by service and by sort key; everything here answers how that\n * decision becomes an offset in the authored bytes without cutting into a\n * comment, a body or the line another statement shares. The service-model\n * splice (`../model/merge.ts`) asks the same questions of a document it does\n * not group by service, and reads them from here for that reason.\n */\nimport { maskSource, pastComments, tokenEnd } from \"../../source-mask.js\";\nimport type { ScannedElement } from \"../../source-scan.js\";\n\n/** A splice point the placement rules chose. */\nexport interface Spot {\n  /** Offset into the living text: a line start, or a point inside a shared line. */\n  at: number;\n  /** True when `at` shares its line with other text (the closing brace, or a displaced statement) — the block must bring its own newlines. */\n  bare: boolean;\n}\n\n/**\n * The line following the statement that ends at `end` — clamped to the closing\n * brace's own spot. Exported for the service-model splice (`../model/merge.ts`),\n * which asks the same two questions of a `model { }` block it does not group by\n * service: after this statement, or last thing in the block.\n *\n * Unless code follows `end` on its line: then the spot is `end` itself, bare.\n * The next line belongs to whatever is written there, and when that is a\n * declaration whose body opens on the same line — `alpha = … { … }  beta = … {`\n * — the line after is INSIDE beta: an addition anchored to alpha's service\n * landed as `beta.kiwi`, in a merge that parsed and was written (exit 0,\n * probed on main at 171555d). Right after the anchor is also what keeps two\n * archives order-free when both anchor on that line: one anchored to alpha and\n * one to beta used to share the next line's start, and whichever ran second\n * landed above the other. A comment trailing the anchor is not code — the\n * next line stays the spot, byte for byte as before — but a block comment\n * it does not close is: its next line is inside the comment.\n *\n * A line comment ends where LikeC4's NL does, at `\\r` as well as `\\n` — the\n * source mask agrees since the bare-CR fix — so `// note\\r  beta = … {` is a\n * comment and then code on the anchor's `\\n`-line, and the spot after that\n * line is inside beta: the same `beta.kiwi` merge, written at exit 0, which\n * 171555d refused because it could not locate beta at all. A CRLF ending\n * leaves nothing after the comment and keeps the next line, byte for byte.\n */\nexport function spotAfter(text: string, close: number, end: number): Spot {\n  const nl = text.indexOf(\"\\n\", end);\n  const at = nl === -1 ? text.length : nl + 1;\n  let rest = pastComments(text.slice(end, Math.min(at, close)));\n  while (rest.startsWith(\"//\")) {\n    const eol = rest.search(/[\\r\\n]/);\n    rest = eol === -1 ? \"\" : pastComments(rest.slice(eol));\n  }\n  if (rest !== \"\") return { at: end, bare: true };\n  return at > close ? closeSpot(text, close) : { at, bare: false };\n}\n\n/**\n * The last resort: directly before the model's closing brace — above a comment\n * written directly over the brace, for the reason `aboveComments` gives.\n */\nexport function closeSpot(text: string, close: number): Spot {\n  const ls = lineStartAt(text, close);\n  if (/^[ \\t]*$/.test(text.slice(ls, close))) return { at: aboveComments(text, ls), bare: false };\n  return { at: close, bare: true };\n}\n\n/**\n * The start of the run of comment lines written directly above the line that\n * starts at `at` — `at` itself when there is none. A blank line ends the run: a\n * comment separated from what follows it by a blank line stands alone, and\n * stays where it is. So does a line that is not comment from its first\n * character to `at` — code, the `model {` line — and a line that starts INSIDE\n * a block comment or a string opened above it, whatever it looks like: the last\n * line of `/* retired … // old edge *\\/` reads as a line comment on its own,\n * and splicing at its start put the addition inside the block comment, where\n * the map parsed clean and the edge was gone at exit 0 (review, 2026-10-22).\n * Which lines are inside what is read off one pass over the whole text, never\n * off the line.\n *\n * Every walk in `../placement.ts` that stops before a statement or at the\n * closing brace lands here, and the rule has to be the same at both for\n * placement to stay order-independent: each splits the lines between two\n * statements at the same point, so an addition landing there first and one\n * landing beside it second compose to the bytes the opposite order writes.\n */\nexport function aboveComments(text: string, at: number): number {\n  const { comments, literals } = maskSource(text);\n  const inside = (p: number): boolean => [...comments, ...literals].some((s) => s.start < p && p < s.end);\n  let top = at;\n  while (top > 0) {\n    const above = lineStartAt(text, top - 1);\n    if (text.slice(above, top).trim() === \"\" || inside(above) || !onlyComments(text.slice(above, at))) break;\n    top = above;\n  }\n  return top;\n}\n\n/** Whether `text` holds nothing but whitespace and complete comments. */\nfunction onlyComments(text: string): boolean {\n  let rest = pastComments(text);\n  while (rest.startsWith(\"//\")) {\n    const eol = rest.search(/[\\r\\n]/);\n    rest = eol === -1 ? \"\" : pastComments(rest.slice(eol));\n  }\n  return rest === \"\";\n}\n\nexport function lineStartAt(text: string, at: number): number {\n  return text.lastIndexOf(\"\\n\", at - 1) + 1;\n}\n\n/**\n * Where a child block enters an existing living parent: before the closing\n * brace of the parent's body, on its own line at the parent's inner indent —\n * and a parent that never had a body gains one around the child.\n */\nexport function nestedInsert(text: string, parent: ScannedElement, block: string): { at: number; insert: string } {\n  if (parent.bodyOpen === -1) {\n    return { at: bodyAt(text, parent), insert: ` {\\n${block}\\n${parent.indent}}` };\n  }\n  const lineStart = text.lastIndexOf(\"\\n\", parent.bodyClose - 1) + 1;\n  if (/^[ \\t]*$/.test(text.slice(lineStart, parent.bodyClose))) {\n    return { at: lineStart, insert: `${block}\\n` };\n  }\n  // `{ ... }` on one line — break the brace onto its own line to make room.\n  return { at: parent.bodyClose, insert: `\\n${block}\\n${parent.indent}` };\n}\n\n/**\n * Where a bodyless parent's new body opens: where its span ends, unless a line\n * comment trails its last token there. The span carries that comment — it is\n * the declaration's own authored text (`statementEnd`) — so the `{` landed\n * INSIDE `// the api`, everything after it on the line was comment, and the\n * parse net refused a valid map (\"Expecting end of file\"). It opens before the\n * comment now, which then trails the new closing brace. A closed block comment\n * is no such trap, and keeps the bytes it always had.\n */\nfunction bodyAt(text: string, parent: ScannedElement): number {\n  const span = text.slice(parent.start, parent.end);\n  const last = parent.start + tokenEnd(maskSource(span), 0, span.length);\n  return pastComments(text.slice(last, parent.end)) === \"\" ? parent.end : last;\n}\n"]}