@opum-ai/lore 0.1.0

package/src/core/graph.ts

@@ -0,0 +1,201 @@
+/**
+ * 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

@@ -0,0 +1,436 @@
+/**
+ * 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;
+}