@opum-ai/lore 0.1.0 → 0.1.1

package/src/core/graph.ts

@@ -1,201 +0,0 @@
-/**
- * graph.ts — shape the bundle graph into an exportable model (and DOT text).
- *
- * `lore graph` surfaces the cross-link graph for orientation: concepts as nodes,
- * OKF cross-links and frontmatter refs as edges, each carrying a chars/4 token
- * estimate (cli-surface §graph). This module is the pure shaping layer between
- * the in-memory {@link BundleGraph} and what the command emits — it turns the
- * graph (optionally narrowed to a {@link subgraph} id-set) into the serializable
- * {@link GraphExport} the `--json` envelope carries, and renders that same model
- * as Graphviz {@link toDot} text. It reads the graph and returns data; the
- * command owns I/O and flag parsing (design §2.1).
- *
- * The token estimates are the bundle's own {@link BundleGraph.tokenEstimate}
- * (memoized, chars/4 over canonical serialized bytes — *not* a real tokenizer);
- * this layer only sums and presents them. The total is summed over the
- * **included** nodes, so a subgraph reports the budget of exactly what it shows.
- */
-
-import { type BundleGraph, type EdgeKind, frontmatterScalar } from "./bundle";
-import { compareCodeUnits } from "./order";
-import type { WorkspaceRecordProvenance, WorkspaceResultScope } from "./workspace-contract";
-import type { WorkspaceProjectedLink } from "./workspace-projection";
-
-/** One concept in the exported graph. */
-export interface GraphNode {
-  /** The concept id (bundle-root-relative, e.g. `adr/0010-x`). */
-  readonly id: string;
-  /** The concept's resolved `type` (mirrors `frontmatter.type`). */
-  readonly type: string;
-  /**
-   * The concept's optional `title` frontmatter, via {@link frontmatterScalar}: a
-   * finite number or boolean value is coerced to its string form, and the field
-   * is omitted only for a missing/empty/whitespace/non-scalar value.
-   */
-  readonly title?: string;
-  /** This concept's chars/4 token estimate over its canonical serialized bytes. */
-  readonly tokenEstimate: number;
-  /** Complete locator-free provenance in explicit workspace mode. */
-  readonly provenance?: WorkspaceRecordProvenance;
-}
-
-/** One directed reference in the exported graph (mirrors a {@link Edge}, with `dangling` made explicit). */
-export interface GraphEdge {
-  /** The source concept id. */
-  readonly from: string;
-  /** The resolved target concept id, or `null` when the reference dangles. */
-  readonly to: string | null;
-  /** Which kind of reference produced this edge (`link`/`specs`/`supersedes`/`superseded_by`). */
-  readonly kind: EdgeKind;
-  /** The reference as parsed (link destination / frontmatter value), for diagnostics. */
-  readonly target: string;
-  /** `true` when the reference resolves to no concept in the bundle (`to === null`). */
-  readonly dangling: boolean;
-}
-
-/** The `graph.export` payload: the nodes, the edges among them, and the token budget. */
-export interface GraphExport {
-  /** The root concept id when the export is a subgraph; omitted for a whole-bundle export. */
-  readonly root?: string;
-  /** The hop radius when the subgraph was bounded by `--depth`; omitted when unbounded or whole-bundle. */
-  readonly depth?: number;
-  /** Every included concept, in ascending id order. */
-  readonly nodes: readonly GraphNode[];
-  /** Every reference whose source is included and whose target is included or dangling, in graph order. */
-  readonly edges: readonly GraphEdge[];
-  /** The summed chars/4 token estimate over the included nodes (labeled a heuristic, not a tokenizer). */
-  readonly tokenEstimate: number;
-  /** Explicit selected workspace scope; absent for repository-local output. */
-  readonly workspace?: WorkspaceResultScope;
-  /** Exact manifest-authored cross-repository links in workspace mode. */
-  readonly workspaceLinks?: readonly WorkspaceProjectedLink[];
-}
-
-/** Options for {@link buildGraphExport}. */
-export interface GraphExportOptions {
-  /**
-   * The concept ids to include — typically a {@link subgraph} result. When omitted,
-   * the whole bundle is exported. Ids not present in the bundle are ignored.
-   */
-  readonly include?: ReadonlySet<string>;
-  /** The root concept id, recorded on the result when this is a subgraph export. */
-  readonly root?: string;
-  /** The hop radius, recorded on the result when the subgraph was bounded. */
-  readonly depth?: number;
-  readonly workspace?: WorkspaceResultScope;
-  readonly provenanceById?: ReadonlyMap<string, WorkspaceRecordProvenance>;
-  readonly workspaceLinks?: readonly WorkspaceProjectedLink[];
-}
-
-/**
- * Shape a {@link BundleGraph} into a {@link GraphExport}, optionally narrowed to
- * an `include` id-set (a {@link subgraph}).
- *
- * Nodes are the bundle's concepts (in their already-sorted id order) filtered to
- * the included set, each annotated with its `type`, optional `title`, and token
- * estimate. Edges are the **closure** of the included set: an edge is kept when
- * its `from` is included **and** its `to` is included *or* dangling — so a
- * subgraph keeps its internal links and its members' broken links, but drops
- * edges that lead to concepts outside the requested radius (a bounded `--depth`
- * is an explicit cut, not a leak). For a whole-bundle export every edge
- * qualifies. The token total is summed over exactly the included nodes, so it
- * equals the whole-bundle estimate for a full export and the subgraph's budget
- * otherwise.
- */
-export function buildGraphExport(graph: BundleGraph, options: GraphExportOptions = {}): GraphExport {
-  const { include, root, depth } = options;
-  // Drive node iteration by the *smaller* of the two: the whole concept map for a
-  // full export (already ascending-id order), or just the included ids — sorted to
-  // preserve that order — for a subgraph, so a bounded `--depth` query costs
-  // O(N_sub log N_sub), not O(N_total).
-  const ids = include === undefined ? graph.concepts.keys() : [...include].sort(compareCodeUnits);
-  const nodes: GraphNode[] = [];
-  let tokenEstimate = 0;
-  for (const id of ids) {
-    const concept = graph.concepts.get(id);
-    if (concept === undefined) {
-      continue; // an include id that names no concept — ignored, never an error
-    }
-    const tokens = graph.tokenEstimate(id);
-    tokenEstimate += tokens;
-    const title = frontmatterScalar(concept.frontmatter.title);
-    nodes.push({
-      id,
-      type: concept.type,
-      ...(title !== undefined ? { title } : {}),
-      tokenEstimate: tokens,
-      ...(options.provenanceById?.get(id) !== undefined ? { provenance: options.provenanceById.get(id) } : {}),
-    });
-  }
-
-  // Edge closure: for a full export every edge qualifies (per the Edge contract
-  // `from` is always a concept and `to` is null-or-concept), so no membership
-  // filtering is needed; for a subgraph, keep an edge whose `from` is included and
-  // whose `to` is included or dangling — the `include` set already equals the node
-  // id-set, so no second set is built.
-  const edges: GraphEdge[] = [];
-  for (const edge of graph.edges) {
-    if (include !== undefined && (!include.has(edge.from) || (edge.to !== null && !include.has(edge.to)))) {
-      continue; // leads outside the requested subgraph — an explicit radius cut
-    }
-    edges.push({ from: edge.from, to: edge.to, kind: edge.kind, target: edge.target, dangling: edge.to === null });
-  }
-
-  return {
-    ...(root !== undefined ? { root } : {}),
-    ...(depth !== undefined ? { depth } : {}),
-    nodes,
-    edges,
-    tokenEstimate,
-    ...(options.workspace !== undefined ? { workspace: options.workspace } : {}),
-    ...(options.workspaceLinks !== undefined ? { workspaceLinks: options.workspaceLinks } : {}),
-  };
-}
-
-/**
- * Render a {@link GraphExport} as Graphviz DOT — a `digraph` with one statement
- * per node (labeled with its title or id) and one per **resolved** edge (labeled
- * with its kind). Dangling edges are omitted: they have no target node to draw
- * to, and the `--json` model already carries them for tooling that needs the
- * broken-link signal (`lore check` is the dedicated reporter). Output is
- * deterministic — nodes in the export's id order, edges in graph order — so
- * `lore graph --dot | dot -Tpng` is stable across runs.
- */
-export function toDot(data: GraphExport): string {
-  const lines = ["digraph lore {"];
-  for (const node of data.nodes) {
-    lines.push(`  ${quote(node.id)} [label=${quote(node.title ?? node.id)}];`);
-  }
-  for (const edge of data.edges) {
-    if (edge.to === null) {
-      continue; // no target node to draw to
-    }
-    lines.push(`  ${quote(edge.from)} -> ${quote(edge.to)} [label=${quote(edge.kind)}];`);
-  }
-  lines.push("}");
-  return lines.join("\n");
-}
-
-/**
- * Quote a string as a DOT double-quoted ID (an escString, per the Graphviz
- * language spec). Graphviz's lexer (`lib/cgraph/scan.l`) recognizes exactly
- * two escapes inside a quoted string — `\"` for a literal quote and `\\` for
- * a literal backslash — and otherwise **drops** a backslash that precedes
- * any other character (so an *unescaped* `\` is not safe passthrough; it is
- * silently eaten, or worse, combines with the following character). A literal
- * backslash therefore must be doubled to `\\` so it survives the round trip,
- * and that doubling must happen **first**, before any escape sequence this
- * function injects (`\"`, `\n`) — otherwise the backslash the doubling itself
- * introduces would be doubled again. A raw line break cannot survive inside a
- * quoted ID without splitting `toDot()`'s one-statement-per-line output
- * across two physical lines, so an embedded newline (`value` is
- * bundle-controlled — a concept id or frontmatter scalar, either of which can
- * carry one) is rewritten to the two-character escape `\n` — the same escape
- * Graphviz itself uses to force a line break inside a label.
- */
-function quote(value: string): string {
-  return `"${value
-    .replace(/\\/g, "\\\\")
-    .replace(/\r\n|\r|\n/g, "\\n")
-    .replace(/"/g, '\\"')}"`;
-}

package/src/core/indexes.ts

@@ -1,436 +0,0 @@
-/**
- * indexes.ts — the bundle's `index.md` files as **graph-derived**, byte-stable navigable hubs (LORE-29).
- *
- * Where [`log.ts`](./log.ts) derives `log.md` from git history, this module derives every
- * `index.md` from the bundle graph: the reserved root entry point plus one local hub per
- * sub-directory, each listing its immediate children (concepts + child indexes) as portable
- * markdown links (okf-conformance: "index bodies link children as a navigable hub").
- *
- * ### What it owns, and what it deliberately does not
- *
- * Index files are **hand-authored documents with one machine-owned region** — exactly the
- * managed-block discipline of lore-design §6.2, where everything outside the region is the
- * author's and is never touched. {@link generateIndexes} regenerates only the
- * `<!-- lore:index:begin -->…<!-- lore:index:end -->` listing block, by **string-splicing it
- * into the existing file's raw bytes**. It never round-trips the file through
- * {@link serializeConcept}: doing so would canonicalize frontmatter and, worse, drop the root
- * index's in-fence editor modeline (an accepted js-yaml round-trip limitation, ADR-0011 §2). So
- * the root index's `okf_version` frontmatter, its modeline, and all curated prose survive
- * byte-for-byte; only the listing block changes.
- *
- * Two responsibilities stay with their owners, not here:
- *
- * - **Root index *creation* and `okf_version`** belong to `scaffold.ts` / `lore init`
- *   (okf-conformance: the bundle-root `index.md` is the only file carrying `okf_version`; a
- *   sub-index carries none, AC#2). `generateIndexes` only *maintains the region* of a root index
- *   that already exists; it never invents the frontmatter. A **sub**-index that does not yet
- *   exist is synthesized frontmatter-free.
- * - **Writing files and reading their current bytes** is the command layer's (`lore sync`,
- *   LORE-26). The current on-disk index bytes enter through the injected {@link GenerateIndexesOptions.existing}
- *   seam — the same determinism boundary `log.ts` draws with its `GitAdapter`: core stays pure
- *   (no filesystem, no clock), and tests inject a fixed map rather than touching disk.
- *
- * ### Byte-stability (AC#1)
- *
- * The output is a pure function of `(g.concepts, existing)`: directory sets, child lists, and the
- * listing are all sorted with {@link compareCodeUnits}, so the same bundle always yields the same
- * bytes. Splicing is a **fixpoint** — re-running over already-generated bytes replaces the region
- * with an identical region, so a no-change `lore sync` is a byte-level no-op and `lore check`'s
- * regenerate-and-compare drift gate stays trustworthy (`index.md` is gated, unlike the
- * git-derived `log.md`; see [log.ts](./log.ts)).
- *
- * ### A note for the link gate (LORE-27)
- *
- * A generated hub links to child-directory indexes (`[adr](adr/index.md)`), but those sub-indexes
- * are frontmatter-free (AC#2) and so are **not** concepts in the {@link BundleGraph} — the root
- * index *is* a concept (it carries `okf_version`), so `bundle.ts` extracts those links as edges that
- * resolve to `null` (dangling). That is expected: when `lore check`'s broken-link reporting lands
- * (LORE-27), it must treat a reserved `index.md`/`log.md` link target as resolving to the file, not
- * flag a freshly-generated, correct hub as broken.
- *
- * Per the core contract (lore-design §2.1) this module is pure: no filesystem, no spawn, no clock.
- */
-
-import { posix } from "node:path";
-import { LoreError, singleLine } from "../errors";
-import { type BundleGraph, frontmatterScalar } from "./bundle";
-import type { Concept } from "./concept";
-import { encodePathSegments } from "./links";
-import { compareCodeUnits } from "./order";
-
-/** The reserved index file name — the per-directory navigable hub (one per dir, plus the bundle root). */
-const INDEX_FILE = "index.md";
-
-/** Reserved file names excluded from a directory's child listing (they are structure, not content). */
-const RESERVED_FILES: ReadonlySet<string> = new Set([INDEX_FILE, "log.md"]);
-
-/**
- * The HTML-comment markers bounding the machine-owned listing block. HTML comments are invisible
- * in every target renderer (GitHub, Obsidian, MkDocs, Docusaurus), and the exact `lore:index:*`
- * sentinels never occur in authored prose, so a literal find is safe (no AST needed here; the
- * remark/mdast unification of all managed regions is LORE-22's `managed-block.ts`). The `:begin`/
- * `:end` shape mirrors the `<!-- lore:tasks:begin -->…<!-- lore:tasks:end -->` task block
- * (lore-design §6.2). Exported so `lore sync`/`lore check` (LORE-26/27) match the same block.
- */
-export const INDEX_BLOCK_BEGIN = "<!-- lore:index:begin -->";
-export const INDEX_BLOCK_END = "<!-- lore:index:end -->";
-
-/** Options for {@link generateIndexes}. */
-export interface GenerateIndexesOptions {
-  /**
-   * The current raw bytes of each index file, keyed by bundle-relative path (e.g. `"index.md"`,
-   * `"adr/index.md"`) — the injected determinism seam (lore-design §8). The command layer reads
-   * these from disk; tests inject a fixed map. A present entry has its listing region spliced in
-   * place (or appended if it carries no markers yet), preserving every other byte — frontmatter,
-   * modeline, and prose. An absent entry means the index file does not exist, so a minimal
-   * frontmatter-free hub is synthesized. Default: empty (every index synthesized fresh).
-   */
-  readonly existing?: ReadonlyMap<string, string>;
-}
-
-/**
- * Regenerate every bundle `index.md` from the graph, returning a map of bundle-relative path →
- * new bytes (the same path space as {@link BundleGraph} concept ids/paths, e.g. `"adr/index.md"`).
- *
- * An index is produced for the bundle root and for every directory that (transitively) contains a
- * concept, so the hub is navigable from the root down. Each index lists, sorted by link target:
- * its immediate child concepts (excluding the reserved `index.md`/`log.md`) and a link into each
- * immediate child directory's index.
- *
- * Pure and total: identical `(g, options)` always yield identical output, and splicing is a
- * fixpoint (AC#1). Existing files keep all bytes outside the listing block (AC#2: a sub-index is
- * never given frontmatter); see the module header for the seam and ownership boundaries.
- */
-export function generateIndexes(g: BundleGraph, options: GenerateIndexesOptions = {}): Map<string, string> {
-  const existing = options.existing ?? new Map<string, string>();
-
-  // Group concepts by their directory, excluding reserved files (an index/log is bundle structure,
-  // not a listable child — and the root index is itself a concept we must not list under itself).
-  const conceptsByDir = new Map<string, Concept[]>();
-  for (const concept of g.concepts.values()) {
-    if (RESERVED_FILES.has(posix.basename(concept.path))) {
-      continue;
-    }
-    const dir = dirOf(concept.path);
-    const bucket = conceptsByDir.get(dir);
-    if (bucket === undefined) {
-      conceptsByDir.set(dir, [concept]);
-    } else {
-      bucket.push(concept);
-    }
-  }
-
-  // Every directory that needs an index: each dir holding a concept, plus all of its ancestors up
-  // to the root (so an intermediate dir with concepts only deeper still gets a hub that links down).
-  const indexDirs = liveIndexDirs(g);
-
-  // Immediate child directories of each index dir (only dirs that themselves get an index).
-  const childDirs = new Map<string, string[]>();
-  for (const dir of indexDirs) {
-    if (dir === "") {
-      continue;
-    }
-    const parent = parentDir(dir);
-    const bucket = childDirs.get(parent);
-    if (bucket === undefined) {
-      childDirs.set(parent, [dir]);
-    } else {
-      bucket.push(dir);
-    }
-  }
-
-  const result = new Map<string, string>();
-  for (const dir of indexDirs) {
-    const indexPath = dir === "" ? INDEX_FILE : `${dir}/${INDEX_FILE}`;
-    const listing = buildListing(conceptsByDir.get(dir) ?? [], childDirs.get(dir) ?? []);
-    const block = `${INDEX_BLOCK_BEGIN}\n${listing}\n${INDEX_BLOCK_END}`;
-    result.set(indexPath, render(existing.get(indexPath), block, dir));
-  }
-  return result;
-}
-
-/**
- * Every directory that needs a **live** index for `g`: the bundle root, every directory holding a
- * concept directly (excluding the reserved `index.md`/`log.md`), plus each such directory's
- * ancestors up to the root — so an intermediate directory with concepts only deeper still counts as
- * live (it gets a hub that links down to them). This is exactly {@link generateIndexes}'s own
- * `indexDirs` derivation, factored out so {@link orphanedIndexPaths} can compare against the same
- * live set without duplicating (and risking drift from) the ancestor-walk logic.
- */
-function liveIndexDirs(g: BundleGraph): Set<string> {
-  const dirs = new Set<string>([""]);
-  for (const concept of g.concepts.values()) {
-    if (RESERVED_FILES.has(posix.basename(concept.path))) {
-      continue;
-    }
-    for (const ancestor of ancestorsInclusive(dirOf(concept.path))) {
-      dirs.add(ancestor);
-    }
-  }
-  return dirs;
-}
-
-/**
- * The bundle-relative paths of every `index.md` present in `existing` whose directory {@link
- * generateIndexes} did **not** regenerate for `g` — a directory holding no concept, directly or via
- * any descendant (LORE-150). This is the stale-index detection `generateIndexes` itself never
- * performed: it derives `indexDirs` solely from the live graph and simply never emits an entry for a
- * directory outside that set, so a caller iterating only its *returned* map has no way to tell "this
- * on-disk index was never regenerated because its directory is orphaned" apart from "this on-disk
- * index was never regenerated because nothing has changed" — both look identical from that map
- * alone. Diffing `existing`'s keys against the live set here makes that distinction explicit and
- * queryable, so `lore sync` (the one caller with a `existing` map sourced from disk) can report an
- * orphan instead of silently leaving it untouched and unmentioned.
- *
- * `generateIndexes`'s own signature and behavior are deliberately unchanged (its returned map is
- * still keyed only by live directories, exactly as before) — this is a separate, additive query so
- * every existing caller (`lore rename`'s `mergeIndexWrites`, which has its own established
- * empty-listing strategy for a directory a rename itself empties) keeps compiling and behaving
- * identically; only `lore sync` needs to ask this new question.
- *
- * Pure and total, sorted with {@link compareCodeUnits} (matching {@link generateIndexes}'s own
- * ordering) so a caller's report is byte-stable regardless of `existing`'s iteration order.
- */
-export function orphanedIndexPaths(g: BundleGraph, existing: ReadonlyMap<string, string>): string[] {
-  const live = liveIndexDirs(g);
-  const livePaths = new Set<string>();
-  for (const dir of live) {
-    livePaths.add(dir === "" ? INDEX_FILE : `${dir}/${INDEX_FILE}`);
-  }
-  return [...existing.keys()].filter((path) => !livePaths.has(path)).sort(compareCodeUnits);
-}
-
-/**
- * The sorted listing lines for one directory: its immediate child concepts and child-directory
- * indexes, each `- [title](link)`, ordered by link target with {@link compareCodeUnits} so the
- * block is byte-stable regardless of map iteration order. An empty directory (no listable children)
- * yields an empty string, so the block is still well-formed (just the two markers around nothing).
- */
-function buildListing(concepts: readonly Concept[], childDirSet: readonly string[]): string {
-  const entries: Array<{ link: string; title: string }> = [];
-
-  for (const concept of concepts) {
-    const target = posix.basename(concept.path);
-    entries.push({ link: encodePathSegments(target), title: conceptTitle(concept) });
-  }
-  for (const childDir of childDirSet) {
-    const name = posix.basename(childDir);
-    entries.push({ link: `${encodePathSegments(name)}/${INDEX_FILE}`, title: name });
-  }
-
-  return entries
-    .sort((a, b) => compareCodeUnits(a.link, b.link))
-    .map((e) => `- [${linkText(e.title)}](${e.link})`)
-    .join("\n");
-}
-
-/**
- * Sanitize an untrusted title (a concept's frontmatter `title` or a file/dir base name) into safe
- * markdown **link text**. Three defenses, all of which keep the rendered text readable:
- *
- * - **Single-line** ({@link singleLine}, as `log.ts` does for commit subjects) — a title carrying a
- *   newline (a YAML block scalar) would otherwise split the entry out of the list.
- * - **Escape `\`** — done *first*, before the `[`/`]` escape below. A pre-existing literal backslash
- *   immediately before a bracket (e.g. a title `Plan \]B\[`) would otherwise combine with the
- *   bracket-escape's inserted backslash into CommonMark's `\\` (an escaped backslash) followed by a
- *   live, link-syntax bracket — shifting text into a real `[text](link)` boundary (same class of bug
- *   as {@link cell}, LORE-154). Doubling backslashes first means the later step's own backslashes are
- *   never mistaken for source content and never re-escaped.
- * - **Escape `[` / `]`** — an unbalanced bracket would truncate or break the `[text](link)` syntax,
- *   leaving the entry as literal text that links nowhere.
- * - **Neutralize HTML-comment sentinels** (`<!--` / `-->` → entities) — a title literally containing
- *   the managed-block end marker would otherwise be written *inside* the generated block and, on the
- *   next run, be mistaken for the region boundary — corrupting the file and breaking the AC#1
- *   fixpoint. The entities render identically (and, as a bonus, a stray `<!--` no longer starts a
- *   real HTML comment that hides text).
- */
-function linkText(title: string): string {
-  return singleLine(title)
-    .replace(/\\/g, "\\\\")
-    .replace(/[[\]]/g, (c) => `\\${c}`)
-    .replace(/<!--/g, "&lt;!--")
-    .replace(/-->/g, "--&gt;");
-}
-
-/**
- * A concept's display title: its frontmatter `title` via the shared {@link frontmatterScalar}
- * (a non-empty string verbatim, or a finite number/boolean coerced to its string form) when that
- * yields a value, else the file's base name (the id's last segment). Falling back to the file
- * name keeps the listing total for a title-less or unknown-type concept (OKF tolerance) without
- * inventing prose. Sharing `frontmatterScalar` keeps this in lockstep with `graph.ts`/`query.ts`/
- * `context.ts`, so the same concept never shows one title in the generated index and another
- * everywhere else (LORE-244).
- */
-function conceptTitle(concept: Concept): string {
-  return frontmatterScalar(concept.frontmatter.title) ?? posix.basename(concept.path, ".md");
-}
-
-/**
- * Produce the final index bytes for one directory, given the directory's current raw bytes (or
- * `undefined` if absent) and the freshly built listing `block`.
- *
- * - **Existing file with the markers** → the block (begin…end inclusive) is replaced in place; all
- *   other bytes are preserved verbatim (frontmatter, modeline, prose), so only the listing changes.
- * - **Existing file without markers** → the block is appended after the body, separated by one
- *   blank line, with a single trailing newline; nothing the author wrote is altered.
- * - **Absent or blank file** → a minimal, frontmatter-free hub is synthesized (`# <title>` + the
- *   block). An existing-but-empty/whitespace-only file is treated like an absent one so a
- *   `touch`-ed or blanked index still gets a heading rather than a heading-less, blank-line-led stub.
- *   The root index is never synthesized with `okf_version` here (that is `lore init`'s job); a
- *   synthesized root simply carries the block under a heading.
- *
- * Every branch ends in exactly one trailing newline, and re-rendering the output is a **fixpoint**
- * (AC#1): the replace branch absorbs a block left at end-of-file by re-adding the newline only when
- * nothing follows the block.
- */
-function render(current: string | undefined, block: string, dir: string): string {
-  if (current === undefined || current.trim() === "") {
-    return `# ${headingFor(dir)}\n\n${block}\n`;
-  }
-  const bounds = blockBounds(current);
-  if (bounds !== null) {
-    const tail = current.slice(bounds.end);
-    const spliced = current.slice(0, bounds.start) + block + tail;
-    // A block sitting at end-of-file (a normal append, or a truncated region replaced to EOF) leaves
-    // no trailing newline; add exactly one. When prose follows the block, `tail` already carries it
-    // (newline included), so this is a no-op and the result stays a fixpoint.
-    return tail === "" ? `${spliced}\n` : spliced;
-  }
-  // No managed region yet: append it, normalizing to exactly one blank-line separator and one
-  // trailing newline so a second run (which now finds the markers) is a byte-level fixpoint.
-  return `${current.replace(/\n+$/, "")}\n\n${block}\n`;
-}
-
-/**
- * Locate the managed block in `content` as a `[start, end)` byte range, or `null` when no begin
- * marker is present (an unmanaged file the caller appends to). See {@link locateManagedBlock} for
- * the full contract, including the malformed-layout cases that are a fail-loud `validation` error
- * (LORE-86).
- */
-function blockBounds(content: string): { start: number; end: number } | null {
-  return locateManagedBlock(content, INDEX_BLOCK_BEGIN, INDEX_BLOCK_END);
-}
-
-/**
- * The generic managed-block locator behind {@link blockBounds}, exported as the **one** rule for
- * where a lore-managed region lives in raw text — `[start, end)` spanning the `begin` marker to the
- * `end` marker (markers included), or `null` when no `begin` is present (an unmanaged file the
- * caller appends to).
- *
- * A well-formed file carries exactly one `begin` and one `end`, with the `end` at or after the
- * `begin`. Anything else is a **malformed layout** — a duplicated pair (both markers appear more
- * than once, e.g. a 3-way-merge artifact) or an unmatched `begin` (no `end` after it, e.g. an
- * interrupted write, or an `end` marker that precedes it) — and is a fail-loud `validation`
- * {@link LoreError} (exit 6) rather than a guessed range. This module previously collapsed a
- * duplicated pair to its first-begin→last-end span and extended an unmatched begin to end-of-file,
- * both to keep regeneration converging to a byte-level fixpoint even from a corrupted file — but a
- * duplicated pair's collapse silently deleted any hand-authored prose sitting between the two
- * blocks (LORE-86), and a guessed range is exactly the ambiguity {@link findMarkers} in
- * `managed-block.ts` already refuses for the sibling `lore:tasks` block. This function now matches
- * that same fail-loud contract instead of guessing.
- *
- * Exported so every consumer that must agree on a managed region's extent (and its validation) uses
- * the *same* rule: index regeneration ({@link generateIndexes}) splices it, and `lore replace`
- * (LORE-35) protects it. Sharing this is what keeps `replace` from editing a span that `lore sync`
- * would later regenerate.
- *
- * The unavoidable cost of literal markers (no AST): a begin/end the *author* wrote in prose — e.g. a
- * doc demonstrating this very format — is treated as a real marker occurrence, contributing to the
- * duplicate count above. That ambiguity is what LORE-22's mdast-based `managed-block.ts` resolves
- * structurally; here it remains a documented limitation of the string splice.
- */
-export function locateManagedBlock(content: string, begin: string, end: string): { start: number; end: number } | null {
-  const begins = allIndicesOf(content, begin);
-  if (begins.length === 0) {
-    return null; // no managed block yet — the caller appends one
-  }
-  const ends = allIndicesOf(content, end);
-  if (begins.length > 1 || ends.length > 1) {
-    throw managedBlockError(
-      begin,
-      end,
-      `the managed block is duplicated (found ${begins.length} begin and ${ends.length} end markers; expected exactly one of each)`,
-      { begins: begins.length, ends: ends.length },
-    );
-  }
-  const start = begins[0] as number;
-  if (ends.length === 0) {
-    throw managedBlockError(begin, end, "the begin marker has no matching end marker after it", {
-      begins: begins.length,
-      ends: ends.length,
-    });
-  }
-  const endStart = ends[0] as number;
-  if (endStart < start + begin.length) {
-    throw managedBlockError(begin, end, "the markers are crossed (the end marker precedes the begin marker)", {
-      begin: start,
-      end: endStart,
-    });
-  }
-  return { start, end: endStart + end.length };
-}
-
-/** Every (non-overlapping) occurrence of `marker` in `content`, in ascending order. */
-function allIndicesOf(content: string, marker: string): number[] {
-  const indices: number[] = [];
-  let from = 0;
-  for (;;) {
-    const at = content.indexOf(marker, from);
-    if (at === -1) {
-      return indices;
-    }
-    indices.push(at);
-    from = at + marker.length;
-  }
-}
-
-/**
- * Build the fail-loud "malformed managed-block markers" error {@link locateManagedBlock} throws
- * (`validation`, exit 6) — the same category and shape `managed-block.ts`'s marker validation uses
- * for the sibling `lore:tasks` block, so both engines refuse to guess in the same voice.
- */
-function managedBlockError(begin: string, end: string, reason: string, input: Record<string, unknown>): LoreError {
-  return new LoreError(
-    "validation",
-    `cannot locate the managed block bounded by \`${begin}\` / \`${end}\`: ${reason}`,
-    `place exactly one \`${begin}\` and one \`${end}\` on their own lines, in that order`,
-    input,
-  );
-}
-
-/** The synthesized heading for a brand-new index: the directory's base name, or `index` for the root. */
-function headingFor(dir: string): string {
-  return dir === "" ? "index" : posix.basename(dir);
-}
-
-/**
- * The directory of a bundle-relative concept path, normalized to `""` for the bundle root.
- * `posix.dirname("x.md")` is `"."`; we use `""` for the root so the root index path is `index.md`
- * (not `./index.md`) and ancestor walking terminates cleanly.
- */
-function dirOf(path: string): string {
-  const dir = posix.dirname(path);
-  return dir === "." ? "" : dir;
-}
-
-/** The parent of a non-root bundle directory (`"a/b/c"` → `"a/b"`, `"a"` → `""`). */
-function parentDir(dir: string): string {
-  const slash = dir.lastIndexOf("/");
-  return slash === -1 ? "" : dir.slice(0, slash);
-}
-
-/**
- * Every directory from `dir` up to (and including) the root `""`, e.g. `"a/b"` → `["a/b", "a", ""]`.
- * Used to ensure an intermediate directory that holds no concept directly — only in a descendant —
- * still gets an index that links down toward it.
- */
-function ancestorsInclusive(dir: string): string[] {
-  const chain: string[] = [];
-  let current = dir;
-  while (current !== "") {
-    chain.push(current);
-    current = parentDir(current);
-  }
-  chain.push("");
-  return chain;
-}