python-delphi-lsp 3.6.0__cp310-abi3-win_amd64.whl

delphi_lsp/agent_wiki.py

@@ -0,0 +1,2853 @@
+from __future__ import annotations
+
+import gc
+import hashlib
+import json
+import os
+import re
+import shutil
+import sqlite3
+import sys
+import tempfile
+import unicodedata
+from collections import OrderedDict
+from collections.abc import Callable, Iterable, Iterator, Mapping
+from contextlib import contextmanager
+from dataclasses import asdict, dataclass
+from functools import lru_cache
+from itertools import chain
+from pathlib import Path, PurePosixPath
+from typing import Any
+
+from ._version import __version__
+from .agent_layers import (
+    CodebaseIndex,
+    _all_symbols,
+    _source_fragment,
+    build_codebase_index,
+    layer_payload,
+)
+from .agent_metrics import build_path_metrics
+from .agent_protocol import (
+    SCHEMA_VERSION,
+    SUPPORTED_ACTIONS,
+    SUPPORTED_DETAILS,
+    SUPPORTED_DIRECTIONS,
+    SUPPORTED_GRAPHS,
+    SUPPORTED_RELATIONS,
+)
+from .parallel_outline import OutlineResult, ParallelBuildStats
+from .parse_artifacts import semantic_model_from_mapping, semantic_model_to_mapping
+from .parser import DelphiParser
+from .parser_backend import ParserMode
+from .project_config import workspace_include_loader
+from .project_discovery import DelphiProjectDiscovery
+from .project_indexer import ProjectIndexResult
+from .semantic import Scope, Symbol, SymbolIndex, SymbolReference, normalize_name
+from .semantic_builder import SemanticModel
+from .source_reader import read_source_text
+from .wiki_external_sort import sort_jsonl_records
+from .wiki_memory import (
+    MemoryStage,
+    MemoryTransition,
+    WikiMemoryGuard,
+    WikiMemoryLimitExceeded,
+    resolve_memory_limit_bytes,
+)
+
+OKF_VERSION = "0.2"
+_WIKI_ARTIFACT_RECURSION_LIMIT = 50_000
+_STREAMING_UNIT_GC_INTERVAL = 16
+
+
+@contextmanager
+def _expanded_recursion_limit() -> Iterator[None]:
+    previous = sys.getrecursionlimit()
+    if previous < _WIKI_ARTIFACT_RECURSION_LIMIT:
+        sys.setrecursionlimit(_WIKI_ARTIFACT_RECURSION_LIMIT)
+    try:
+        yield
+    finally:
+        if previous < _WIKI_ARTIFACT_RECURSION_LIMIT:
+            sys.setrecursionlimit(previous)
+
+
+class WikiExportError(RuntimeError):
+    """Raised when an OKF bundle cannot be created safely."""
+
+
+@dataclass(frozen=True)
+class WikiExportResult:
+    output: str
+    documents: int
+    projects: int
+    units: int
+    symbols: int
+    peak_process_tree_rss_bytes: int
+    phase_peak_process_tree_rss_bytes: dict[str, int]
+
+    def to_mapping(self) -> dict[str, Any]:
+        return {
+            "format": "okf",
+            "okf_version": OKF_VERSION,
+            **asdict(self),
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class WikiProgressEvent:
+    phase: str
+    completed: int
+    total: int | None
+    path: str
+    detail: str
+
+
+WikiProgressCallback = Callable[[WikiProgressEvent], None]
+
+
+@dataclass(frozen=True, slots=True)
+class _UnitRecord:
+    source_path: str
+    name: str
+    page: PurePosixPath
+
+
+def _iter_symbols(
+    scope: Scope,
+    *,
+    include_unit: bool = True,
+    seen: set[int] | None = None,
+) -> Iterator[Symbol]:
+    """Depth-first symbol traversal without Python call-stack growth."""
+    visited = set() if seen is None else seen
+    pending: list[Iterator[Symbol]] = []
+
+    def enter(candidate: Scope) -> bool:
+        scope_id = id(candidate)
+        if scope_id in visited:
+            return False
+        visited.add(scope_id)
+        pending.append(
+            iter(
+                symbol
+                for symbols in candidate.symbols.values()
+                for symbol in symbols
+            )
+        )
+        return True
+
+    enter(scope)
+    while pending:
+        try:
+            symbol = next(pending[-1])
+        except StopIteration:
+            pending.pop()
+            continue
+        if include_unit or symbol.kind.value != "unit":
+            yield symbol
+        if symbol.member_scope is not None:
+            enter(symbol.member_scope)
+
+
+@dataclass(frozen=True, slots=True)
+class _StoredModelRecord:
+    source_path: str
+    name: str
+    artifact_path: Path
+    symbol_count: int
+
+
+@dataclass(slots=True)
+class _WikiExecutionStrategy:
+    workers: int
+    outline_worker_limit: int = 2
+    sort_records_per_run: int = 50_000
+    sort_bytes_per_run: int = 8 * 1024 * 1024
+
+    def reduce_workers(self) -> None:
+        effective = self.workers if self.workers > 0 else min(8, os.cpu_count() or 1)
+        self.workers = max(1, effective // 2)
+        self.outline_worker_limit = max(1, self.outline_worker_limit // 2)
+
+    def sequentialize(self) -> None:
+        self.workers = 1
+        self.outline_worker_limit = 1
+        self.sort_records_per_run = min(self.sort_records_per_run, 5_000)
+        self.sort_bytes_per_run = min(self.sort_bytes_per_run, 8 * 1024 * 1024)
+
+
+class _StoredWikiModels(Mapping[str, SemanticModel]):
+    """Disk-backed outline models with a small, explicitly clearable LRU."""
+
+    def __init__(
+        self,
+        workspace: Path,
+        *,
+        max_cached_models: int = 128,
+        max_cached_model_bytes: int = 0,
+    ) -> None:
+        if max_cached_models < 0:
+            raise ValueError("max_cached_models must not be negative")
+        if max_cached_model_bytes < 0:
+            raise ValueError("max_cached_model_bytes must not be negative")
+        self.workspace = workspace
+        self.model_directory = workspace / "models"
+        self.model_directory.mkdir(parents=True, exist_ok=True)
+        self.catalog_path = workspace / "symbols-raw.jsonl"
+        self._records: dict[str, _StoredModelRecord] = {}
+        self._ordered_sources: list[str] = []
+        self._source_by_unit: dict[str, str] = {}
+        self._max_cached_models = max_cached_models
+        self._max_cached_model_bytes = max_cached_model_bytes
+        self._cache: OrderedDict[str, SemanticModel] = OrderedDict()
+        self._cache_weights: dict[str, int] = {}
+        self._cached_model_bytes = 0
+
+    def store(self, result: OutlineResult) -> None:
+        if result.read_error or result.model is None:
+            return
+        digest = hashlib.sha256(result.source_path.encode("utf-8")).hexdigest()
+        artifact_path = self.model_directory / f"{digest}.json"
+        with (
+            _expanded_recursion_limit(),
+            artifact_path.open("w", encoding="utf-8", newline="\n") as stream,
+        ):
+            json.dump(
+                semantic_model_to_mapping(result.model),
+                stream,
+                ensure_ascii=False,
+                separators=(",", ":"),
+            )
+            stream.write("\n")
+        symbol_count = 0
+        with self.catalog_path.open("a", encoding="utf-8", newline="\n") as catalog:
+            for symbol in _iter_symbols(result.model.unit_scope, include_unit=False):
+                symbol_count += 1
+                identity = _symbol_identity(symbol)
+                catalog.write(
+                    json.dumps(
+                        {
+                            "identity": identity,
+                            "kind": symbol.kind.value,
+                            "model_source": result.source_path,
+                            "name": symbol.name,
+                            "name_key": symbol.name.casefold(),
+                            "page": _symbol_page(symbol).as_posix(),
+                            "source_key": _normalized_source(symbol.decl_range.file_name),
+                            "start_col": symbol.decl_range.start_col,
+                            "start_line": symbol.decl_range.start_line,
+                        },
+                        ensure_ascii=False,
+                        separators=(",", ":"),
+                    )
+                )
+                catalog.write("\n")
+        self._records[result.source_path] = _StoredModelRecord(
+            result.source_path,
+            result.model.unit_scope.name,
+            artifact_path,
+            symbol_count,
+        )
+
+    def finalize(self, source_order: Iterable[str]) -> None:
+        self._ordered_sources = [source for source in source_order if source in self._records]
+        self._source_by_unit = {}
+        for source in self._ordered_sources:
+            self._source_by_unit[self._records[source].name.casefold()] = source
+        self.catalog_path.touch(exist_ok=True)
+
+    def source_for_unit(self, name: str) -> str | None:
+        return self._source_by_unit.get(name.casefold())
+
+    def unit_records(self) -> list[_UnitRecord]:
+        records = [
+            _UnitRecord(
+                source,
+                self._records[source].name,
+                PurePosixPath("units")
+                / _document_name(
+                    self._records[source].name,
+                    _normalized_source(source),
+                ),
+            )
+            for source in self._ordered_sources
+        ]
+        return sorted(
+            records,
+            key=lambda record: (record.name.casefold(), record.source_path.casefold()),
+        )
+
+    def __getitem__(self, source_path: str) -> SemanticModel:
+        cached = self._cache.get(source_path)
+        if cached is not None:
+            self._cache.move_to_end(source_path)
+            cached.index = SymbolIndex()
+            return cached
+        record = self._records[source_path]
+        with _expanded_recursion_limit():
+            with record.artifact_path.open("r", encoding="utf-8") as stream:
+                payload = json.load(stream)
+            if not isinstance(payload, dict):
+                raise WikiExportError(f"Invalid stored outline model: {source_path}")
+            model = semantic_model_from_mapping(payload)
+        model.index = SymbolIndex()
+        weight = record.artifact_path.stat().st_size
+        if (
+            self._max_cached_models
+            and weight <= self._max_cached_model_bytes
+        ):
+            self._cache[source_path] = model
+            self._cache_weights[source_path] = weight
+            self._cached_model_bytes += weight
+            self._cache.move_to_end(source_path)
+            while (
+                len(self._cache) > self._max_cached_models
+                or self._cached_model_bytes > self._max_cached_model_bytes
+            ):
+                expired, _model = self._cache.popitem(last=False)
+                self._cached_model_bytes -= self._cache_weights.pop(expired)
+        return model
+
+    def clear_cache(self) -> None:
+        self._cache.clear()
+        self._cache_weights.clear()
+        self._cached_model_bytes = 0
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._ordered_sources)
+
+    def __len__(self) -> int:
+        return len(self._ordered_sources)
+
+
+class _LazyWikiSymbolIndex(SymbolIndex):
+    """Load only units actually imported by the unit currently being parsed."""
+
+    def __init__(self, models: _StoredWikiModels) -> None:
+        super().__init__()
+        self.models = models
+
+    def register_unit(
+        self,
+        unit_name: str,
+        unit_scope: Scope,
+        *,
+        index_symbols: bool = True,
+    ) -> None:
+        del index_symbols
+        super().register_unit(unit_name, unit_scope, index_symbols=False)
+
+    def lookup_unit(self, unit_name: str):  # type: ignore[no-untyped-def]
+        normalized = normalize_name(unit_name)
+        existing = self.units.get(normalized)
+        if existing is not None:
+            return existing
+        source = self.models.source_for_unit(unit_name)
+        if source is None:
+            return None
+        model = self.models[source]
+        self.register_unit(model.unit_scope.name, model.unit_scope)
+        return self.units.get(normalized)
+
+
+class _WikiProjectStore:
+    def __init__(self, path: Path) -> None:
+        self.path = path
+        self.count = 0
+
+    def append(self, project: str, result: ProjectIndexResult) -> None:
+        item = _project_item(project, result)
+        with self.path.open("a", encoding="utf-8", newline="\n") as stream:
+            stream.write(json.dumps(item, ensure_ascii=False, separators=(",", ":")))
+            stream.write("\n")
+        self.count += 1
+
+    def items(self) -> Iterator[dict[str, Any]]:
+        if not self.path.is_file():
+            return
+        with self.path.open("r", encoding="utf-8") as stream:
+            for line in stream:
+                item = json.loads(line)
+                if isinstance(item, dict):
+                    yield item
+
+
+class _ProjectMembershipStore:
+    def __init__(self, path: Path) -> None:
+        self.connection = sqlite3.connect(path)
+        self.connection.execute(
+            "CREATE TABLE membership (source TEXT, ordinal INTEGER, title TEXT, page TEXT, "
+            "PRIMARY KEY (source, title, page))"
+        )
+
+    def add(
+        self,
+        source: str,
+        ordinal: int,
+        title: str,
+        page: PurePosixPath,
+    ) -> None:
+        self.connection.execute(
+            "INSERT OR IGNORE INTO membership VALUES (?, ?, ?, ?)",
+            (_normalized_source(source), ordinal, title, page.as_posix()),
+        )
+
+    def for_source(self, source: str) -> list[tuple[str, PurePosixPath]]:
+        rows = self.connection.execute(
+            "SELECT title, page FROM membership WHERE source = ? ORDER BY ordinal",
+            (_normalized_source(source),),
+        )
+        return [(str(title), PurePosixPath(str(page))) for title, page in rows]
+
+    def commit(self) -> None:
+        self.connection.commit()
+
+    def close(self) -> None:
+        self.connection.close()
+
+
+class _BoundedSourceCache(OrderedDict[str, list[str]]):
+    """Keep only a few decoded source files resident during page generation."""
+
+    def __init__(self, max_entries: int = 4) -> None:
+        super().__init__()
+        self.max_entries = max_entries
+
+    def get(self, key: str, default: list[str] | None = None) -> list[str] | None:
+        value = super().get(key, default)
+        if key in self:
+            self.move_to_end(key)
+        return value
+
+    def __setitem__(self, key: str, value: list[str]) -> None:
+        super().__setitem__(key, value)
+        self.move_to_end(key)
+        while len(self) > self.max_entries:
+            self.popitem(last=False)
+
+
+def export_okf_wiki(
+    root: str | Path,
+    output: str | Path,
+    *,
+    project_file: str | Path | None = None,
+    workers: int = 0,
+    max_memory_bytes: int | None = None,
+    force: bool = False,
+    on_progress: WikiProgressCallback | None = None,
+) -> WikiExportResult:
+    """Export all unique layered codebase knowledge as an OKF 0.2 bundle."""
+
+    root_path = Path(root).expanduser().resolve()
+    requested_output, output_path = _resolve_output_destination(output)
+    _validate_paths(root_path, output_path, force=force)
+
+    def forward_index_progress(event: Any) -> None:
+        if event.phase in {"inventory", "detail"} or event.detail in {
+            "project index started",
+            "project index complete",
+        }:
+            guard.check(phase="project indexing")
+        if event.phase in {"inventory", "detail"}:
+            return
+        if event.detail in {"project index started", "project index complete"}:
+            return
+        phase = {
+            "outline": "index",
+            "relations": "relations",
+            "projects": "projects",
+            "complete": "index",
+        }.get(event.phase, "discovery")
+        _emit_wiki_progress(
+            on_progress,
+            phase,
+            event.files_completed,
+            event.files_total,
+            event.path,
+            event.detail,
+        )
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = Path(
+        tempfile.mkdtemp(prefix=f".{output_path.name}.tmp-", dir=output_path.parent)
+    )
+    workspace = Path(
+        tempfile.mkdtemp(prefix=f".{output_path.name}.work-", dir=output_path.parent)
+    )
+    strategy = _WikiExecutionStrategy(workers)
+
+    def memory_transition(transition: MemoryTransition) -> None:
+        _emit_wiki_progress(
+            on_progress,
+            "memory",
+            (MemoryStage.COMPACT, MemoryStage.REDUCE_WORKERS, MemoryStage.SEQUENTIAL).index(
+                transition.stage
+            )
+            + 1,
+            3,
+            transition.phase,
+            (
+                f"memory guard {transition.stage.value}: "
+                f"{transition.used_bytes} of {transition.limit_bytes} bytes"
+            ),
+        )
+
+    models = _StoredWikiModels(workspace)
+    writer: _StreamingWikiWriter | None = None
+
+    def compact_memory() -> None:
+        models.clear_cache()
+        if writer is not None:
+            writer.clear_caches()
+        gc.collect()
+
+    try:
+        memory_limit = resolve_memory_limit_bytes(max_memory_bytes)
+    except ValueError as error:
+        shutil.rmtree(temporary, ignore_errors=True)
+        shutil.rmtree(workspace, ignore_errors=True)
+        raise WikiExportError(str(error)) from error
+    guard = WikiMemoryGuard(
+        limit_bytes=memory_limit,
+        compact=compact_memory,
+        reduce_workers=strategy.reduce_workers,
+        sequentialize=strategy.sequentialize,
+        on_transition=memory_transition,
+    )
+    projects = _WikiProjectStore(workspace / "projects.jsonl")
+
+    def store_outline(result: OutlineResult) -> None:
+        models.store(result)
+        guard.check(phase="unit outlines")
+
+    def store_project(project: str, result: ProjectIndexResult) -> None:
+        projects.append(project, result)
+        guard.check(phase="project indexing")
+
+    try:
+        _emit_wiki_progress(
+            on_progress,
+            "discovery",
+            0,
+            None,
+            str(root_path),
+            "discovering repository sources",
+        )
+        index = _build_wiki_index(
+            root_path,
+            project_file=project_file,
+            workers=strategy.workers,
+            memory_limit_bytes=memory_limit,
+            on_project_result=store_project,
+            on_outline_result=store_outline,
+            outline_heartbeat=lambda: guard.check(
+                phase="unit outlines",
+            ),
+            outline_force_heartbeat=lambda: guard.check(
+                phase="unit outlines",
+                force_process_tree=True,
+            ),
+            outline_active_worker_limit=lambda: strategy.outline_worker_limit,
+            on_progress=forward_index_progress,
+        )
+        guard.check(phase="project indexing", force_process_tree=True)
+        models.finalize(index.discovery.source_files)
+        guard.check(phase="unit outlines", force_process_tree=True)
+        index.models = models
+        unique_catalog, name_catalog, symbol_count = _prepare_symbol_catalog(
+            models,
+            workspace,
+            strategy,
+            guard,
+        )
+        guard.check(phase="external symbol sort", force_process_tree=True)
+        writer = _StreamingWikiWriter(
+            index,
+            temporary,
+            models=models,
+            projects=projects,
+            unique_catalog=unique_catalog,
+            name_catalog=name_catalog,
+            symbol_count=symbol_count,
+            workspace=workspace,
+            guard=guard,
+            strategy=strategy,
+            on_progress=on_progress,
+        )
+        writer.write()
+        documents = writer.documents
+        symbol_count = writer.symbol_count
+        guard.check(phase="finalization", force_process_tree=True)
+        guard.check(phase="finalization", force_process_tree=True)
+        _emit_wiki_progress(
+            on_progress,
+            "install",
+            0,
+            1,
+            str(output_path),
+            "installing completed bundle",
+        )
+        _install_completed_bundle(
+            temporary,
+            output_path,
+            requested_output=requested_output,
+            force=force,
+        )
+    except WikiMemoryLimitExceeded as error:
+        if temporary.exists():
+            shutil.rmtree(temporary, ignore_errors=True)
+        raise WikiExportError(
+            f"{error} Retry with a larger --max-memory value or fewer workers."
+        ) from error
+    except BaseException:
+        if temporary.exists():
+            shutil.rmtree(temporary, ignore_errors=True)
+        raise
+    finally:
+        if writer is not None:
+            writer.close()
+        shutil.rmtree(workspace, ignore_errors=True)
+
+    result = WikiExportResult(
+        output=str(output_path),
+        documents=documents,
+        projects=len(index.discovery.project_files),
+        units=len(index.models),
+        symbols=symbol_count,
+        peak_process_tree_rss_bytes=guard.peak_bytes,
+        phase_peak_process_tree_rss_bytes=dict(sorted(guard.phase_peaks.items())),
+    )
+    _emit_wiki_progress(
+        on_progress,
+        "complete",
+        1,
+        1,
+        str(output_path),
+        "wiki export complete",
+    )
+    return result
+
+
+def _build_wiki_index(
+    root: Path,
+    *,
+    project_file: str | Path | None,
+    workers: int,
+    memory_limit_bytes: int,
+    on_project_result: Callable[[str, ProjectIndexResult], None],
+    on_outline_result: Callable[[OutlineResult], None],
+    outline_heartbeat: Callable[[], object],
+    outline_force_heartbeat: Callable[[], object],
+    outline_active_worker_limit: Callable[[], int],
+    on_progress: Callable[[Any], None],
+) -> CodebaseIndex:
+    requested_outline_workers = (
+        workers
+        if workers > 0
+        else max(1, min(2, (os.cpu_count() or 1) - 1))
+    )
+    outline_workers = max(1, min(2, requested_outline_workers))
+    source_roots = (
+        _manifest_source_roots(root)
+        if project_file is None
+        else (root,)
+    )
+    merge_workspace_sources = len(source_roots) > 1
+    indexes = [
+        build_codebase_index(
+            source_root,
+            project_file=project_file if source_root == root else None,
+            index_projects=True,
+            main_projects_only=True,
+            scan_workspace_sources=(
+                True
+                if merge_workspace_sources
+                else None
+            ),
+            retain_project_syntax=False,
+            retain_project_results=False,
+            retain_outline_models=False,
+            project_source_roots=(source_root,),
+            on_progress=on_progress,
+            on_project_result=on_project_result,
+            on_outline_result=on_outline_result,
+            outline_heartbeat=outline_heartbeat,
+            outline_force_heartbeat=outline_force_heartbeat,
+            outline_active_worker_limit=outline_active_worker_limit,
+            # Keep the Windows spawn multiplier bounded while recovering
+            # enough parse throughput for multi-million-line corpora.
+            workers=outline_workers,
+            project_workers=1,
+            outline_memory_budget_bytes=memory_limit_bytes * 8 // 10,
+            use_artifact_cache=False,
+        )
+        for source_root in source_roots
+    ]
+    if len(indexes) == 1:
+        return indexes[0]
+    return _merge_wiki_indexes(root, indexes)
+
+
+def _prepare_symbol_catalog(
+    models: _StoredWikiModels,
+    workspace: Path,
+    strategy: _WikiExecutionStrategy,
+    guard: WikiMemoryGuard,
+) -> tuple[Path, Path, int]:
+    source_order = {source: ordinal for ordinal, source in enumerate(models)}
+    sorted_catalog = workspace / "symbols-by-identity.jsonl"
+    unique_catalog = workspace / "symbols-unique.jsonl"
+    name_catalog = workspace / "symbols-by-name.jsonl"
+    sort_jsonl_records(
+        models.catalog_path,
+        sorted_catalog,
+        key=lambda item: (
+            str(item["identity"]),
+            f"{source_order.get(str(item['model_source']), len(source_order)):012d}",
+        ),
+        max_records_per_run=strategy.sort_records_per_run,
+        max_bytes_per_run=strategy.sort_bytes_per_run,
+        temp_dir=workspace,
+        heartbeat=lambda: guard.check(
+            phase="external symbol sort",
+        ),
+        force_heartbeat=lambda: guard.check(
+            phase="external symbol sort",
+            force_process_tree=True,
+        ),
+    )
+    symbol_count = 0
+    previous_identity: str | None = None
+    with (
+        sorted_catalog.open("r", encoding="utf-8") as source,
+        unique_catalog.open("w", encoding="utf-8", newline="\n") as target,
+    ):
+        for line in source:
+            item = json.loads(line)
+            identity = str(item["identity"])
+            if identity == previous_identity:
+                continue
+            previous_identity = identity
+            target.write(line)
+            symbol_count += 1
+    sort_jsonl_records(
+        unique_catalog,
+        name_catalog,
+        key=lambda item: (
+            str(item["name_key"]),
+            str(item["source_key"]),
+            f"{int(item['start_line']):012d}",
+            f"{int(item['start_col']):012d}",
+            str(item["kind"]),
+        ),
+        max_records_per_run=strategy.sort_records_per_run,
+        max_bytes_per_run=strategy.sort_bytes_per_run,
+        temp_dir=workspace,
+        heartbeat=lambda: guard.check(
+            phase="external symbol sort",
+        ),
+        force_heartbeat=lambda: guard.check(
+            phase="external symbol sort",
+            force_process_tree=True,
+        ),
+    )
+    return unique_catalog, name_catalog, symbol_count
+
+
+def _manifest_source_roots(root: Path) -> tuple[Path, ...]:
+    manifest = root / "corpus-manifest.json"
+    try:
+        payload = json.loads(manifest.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, ValueError):
+        return (root,)
+    corpora = payload.get("corpora") if isinstance(payload, dict) else None
+    if not isinstance(corpora, list):
+        return (root,)
+    roots: dict[str, Path] = {}
+    for corpus in corpora:
+        name = corpus.get("name") if isinstance(corpus, dict) else None
+        if not isinstance(name, str) or not name.strip():
+            return (root,)
+        candidate = (root / name).resolve()
+        if not candidate.is_relative_to(root) or not candidate.is_dir():
+            return (root,)
+        roots.setdefault(str(candidate).casefold(), candidate)
+    if len(roots) < 2:
+        return (root,)
+    return tuple(sorted(roots.values(), key=lambda path: str(path).casefold()))
+
+
+def _merge_wiki_indexes(
+    root: Path,
+    indexes: list[CodebaseIndex],
+) -> CodebaseIndex:
+    discovery = DelphiProjectDiscovery(root=str(root))
+
+    def merge_values(target: list[str], values: Iterable[str]) -> None:
+        existing = {value.casefold() for value in target}
+        for value in values:
+            if value.casefold() not in existing:
+                target.append(value)
+                existing.add(value.casefold())
+
+    models: dict[str, SemanticModel] = {}
+    project_results: dict[str, ProjectIndexResult] = {}
+    configured_workers = 0
+    effective_workers = 0
+    files_completed = 0
+    elapsed_seconds = 0.0
+    fallbacks = 0
+    for index in indexes:
+        current = index.discovery
+        merge_values(discovery.project_files, current.project_files)
+        merge_values(discovery.config_files, current.config_files)
+        merge_values(discovery.search_paths, current.search_paths)
+        merge_values(discovery.include_paths, current.include_paths)
+        merge_values(discovery.defines, current.defines)
+        merge_values(discovery.source_files, current.source_files)
+        discovery.problems.extend(current.problems)
+        for target, source_origins in (
+            (discovery.search_path_origins, current.search_path_origins),
+            (discovery.include_path_origins, current.include_path_origins),
+            (discovery.define_origins, current.define_origins),
+        ):
+            for key, values in source_origins.items():
+                merge_values(target.setdefault(key, []), values)
+        models.update(index.models)
+        project_results.update(index.project_results)
+        configured_workers = max(
+            configured_workers,
+            index.parallel_stats.configured_workers,
+        )
+        effective_workers = max(
+            effective_workers,
+            index.parallel_stats.effective_workers,
+        )
+        files_completed += index.parallel_stats.files_completed
+        elapsed_seconds += index.parallel_stats.elapsed_seconds
+        fallbacks += index.parallel_stats.fallbacks
+
+    discovery.project_files.sort(key=str.casefold)
+    discovery.config_files.sort(key=str.casefold)
+    discovery.search_paths.sort(key=str.casefold)
+    discovery.include_paths.sort(key=str.casefold)
+    discovery.defines.sort(key=str.casefold)
+    discovery.source_files.sort(key=str.casefold)
+    for source in discovery.source_files:
+        discovery.unit_paths.setdefault(
+            Path(source).stem.casefold(),
+            [],
+        ).append(source)
+
+    symbol_index = SymbolIndex()
+    for model in models.values():
+        symbol_index.register_unit(model.unit_scope.name, model.unit_scope)
+    for model in models.values():
+        model.index = symbol_index
+
+    return CodebaseIndex(
+        root=str(root),
+        discovery=discovery,
+        models=models,
+        symbol_index=symbol_index,
+        project_results=project_results,
+        parallel_stats=ParallelBuildStats(
+            configured_workers,
+            effective_workers,
+            files_completed,
+            elapsed_seconds,
+            fallbacks,
+        ),
+    )
+
+
+def _populate_wiki_references(index: CodebaseIndex) -> None:
+    reference_index = SymbolIndex()
+    outline_by_exact: dict[tuple[str, str, str, int, int], Symbol] = {}
+    outline_by_source: dict[tuple[str, str, str], Symbol] = {}
+    outline_ids: set[int] = set()
+    for model in index.models.values():
+        reference_index.register_unit(model.unit_scope.name, model.unit_scope)
+        for symbol in _iter_symbols(model.unit_scope):
+            outline_ids.add(id(symbol))
+            source_key = (
+                symbol.name.casefold(),
+                symbol.kind.value,
+                symbol.decl_range.file_name.casefold(),
+            )
+            outline_by_source.setdefault(source_key, symbol)
+            outline_by_exact[
+                (
+                    *source_key,
+                    symbol.name_range.start_line,
+                    symbol.name_range.start_col,
+                )
+            ] = symbol
+    outline_units = dict(reference_index.units)
+    outline_name_counts = {
+        name: len(symbols)
+        for name, symbols in reference_index.name_index.items()
+    }
+
+    parser = DelphiParser(
+        include_paths=index.discovery.include_paths,
+        defines=index.discovery.defines,
+        include_loader=workspace_include_loader(
+            index.discovery.project_config,
+            index.discovery.include_paths,
+        ),
+        mode=ParserMode.TOLERANT,
+    )
+    for source_path, outline_model in index.models.items():
+        try:
+            source = read_source_text(Path(source_path))
+            parsed = parser.parse(
+                source,
+                source_path,
+                build_semantic=True,
+                index=reference_index,
+            )
+        except (OSError, UnicodeError):
+            continue
+        if parsed.semantic is None:
+            continue
+        parsed_unit_key = normalize_name(parsed.semantic.unit_scope.name)
+        registered_names = {
+            normalize_name(symbol.name)
+            for symbol in _iter_symbols(parsed.semantic.unit_scope)
+        }
+        try:
+            references: list[SymbolReference] = []
+            for reference in parsed.semantic.references:
+                resolved = reference.resolved
+                mapped = (
+                    resolved
+                    if resolved is not None and id(resolved) in outline_ids
+                    else None
+                )
+                if resolved is not None and mapped is None:
+                    source_key = (
+                        resolved.name.casefold(),
+                        resolved.kind.value,
+                        resolved.decl_range.file_name.casefold(),
+                    )
+                    mapped = outline_by_exact.get(
+                        (
+                            *source_key,
+                            resolved.name_range.start_line,
+                            resolved.name_range.start_col,
+                        )
+                    ) or outline_by_source.get(source_key)
+                references.append(
+                    SymbolReference(
+                        name=reference.name,
+                        kind=reference.kind,
+                        ref_range=reference.ref_range,
+                        scope=outline_model.unit_scope,
+                        resolved=mapped,
+                    )
+                )
+            outline_model.references = references
+        finally:
+            outline_unit = outline_units.get(parsed_unit_key)
+            if outline_unit is None:
+                reference_index.units.pop(parsed_unit_key, None)
+            else:
+                reference_index.units[parsed_unit_key] = outline_unit
+            for name in registered_names:
+                count = outline_name_counts.get(name)
+                if count is None:
+                    reference_index.name_index.pop(name, None)
+                else:
+                    del reference_index.name_index[name][count:]
+
+
+def _emit_wiki_progress(
+    callback: WikiProgressCallback | None,
+    phase: str,
+    completed: int,
+    total: int | None,
+    path: str,
+    detail: str,
+) -> None:
+    if callback is not None:
+        callback(WikiProgressEvent(phase, completed, total, path, detail))
+
+
+def _resolve_output_destination(output: str | Path) -> tuple[Path, Path]:
+    requested = Path(os.path.abspath(Path(output).expanduser()))
+    if requested.is_symlink():
+        raise WikiExportError(f"Wiki destination must not be a symlink: {requested}")
+    canonical = requested.parent.resolve() / requested.name
+    return requested, canonical
+
+
+def _validate_paths(root: Path, output: Path, *, force: bool) -> None:
+    if not root.is_dir():
+        raise WikiExportError(f"Repository root is not a directory: {root}")
+    if output == root:
+        raise WikiExportError("Wiki destination must not be the repository root.")
+    if root.is_relative_to(output):
+        raise WikiExportError("Wiki destination must not contain the repository root.")
+    if output.is_symlink():
+        raise WikiExportError(f"Wiki destination must not be a symlink: {output}")
+    if output.exists() and not output.is_dir():
+        raise WikiExportError(f"Wiki destination already exists and is not a directory: {output}")
+    if output.exists() and not force and _directory_has_entries(output):
+        raise WikiExportError(
+            f"Wiki destination already exists: {output}. Pass --force to replace it."
+        )
+
+
+def _directory_has_entries(path: Path) -> bool:
+    try:
+        next(path.iterdir())
+    except StopIteration:
+        return False
+    return True
+
+
+def _install_completed_bundle(
+    temporary: Path,
+    output: Path,
+    *,
+    requested_output: Path,
+    force: bool,
+) -> None:
+    _revalidate_output_destination(requested_output, output)
+    if not output.exists():
+        os.replace(temporary, output)
+        return
+    if not force and _directory_has_entries(output):
+        raise WikiExportError(f"Wiki destination already exists: {output}")
+
+    backup = output.parent / f".{output.name}.backup-{os.getpid()}"
+    suffix = 0
+    while backup.exists():
+        suffix += 1
+        backup = output.parent / f".{output.name}.backup-{os.getpid()}-{suffix}"
+    os.replace(output, backup)
+    try:
+        os.replace(temporary, output)
+    except Exception:
+        os.replace(backup, output)
+        raise
+    shutil.rmtree(backup)
+
+
+def _revalidate_output_destination(requested: Path, canonical: Path) -> None:
+    if requested.is_symlink():
+        raise WikiExportError(f"Wiki destination became a symlink: {requested}")
+    current = requested.parent.resolve() / requested.name
+    if current != canonical:
+        raise WikiExportError(
+            "Wiki destination parent changed while the bundle was generated."
+        )
+    if canonical.is_symlink():
+        raise WikiExportError(f"Wiki destination must not be a symlink: {canonical}")
+
+
+class _WikiWriter:
+    def __init__(
+        self,
+        index: CodebaseIndex,
+        destination: Path,
+        *,
+        workers: int = 0,
+        on_progress: WikiProgressCallback | None = None,
+    ) -> None:
+        self.index = index
+        self.destination = destination
+        self.workers = workers
+        self._on_progress = on_progress
+        self.documents = 0
+        self._source_cache: dict[str, list[str]] = _BoundedSourceCache()
+        self._display_path_cache: dict[str, str] = {}
+        self._symbol_count = sum(1 for _symbol in self._iter_unique_symbols())
+        self.units = self._unit_records()
+        self._unit_by_source = {
+            _normalized_source(record.source_path): record for record in self.units
+        }
+        self._unit_by_name = {record.name.casefold(): record for record in self.units}
+        self._references_by_target: dict[int, list[SymbolReference]] = {}
+        self._projects_by_source: dict[str, list[tuple[str, PurePosixPath]]] = {}
+        self._metric_page_by_source: dict[str, PurePosixPath] = {}
+        self._collect_references()
+
+    @property
+    def symbol_count(self) -> int:
+        return self._symbol_count
+
+    def write(self) -> None:
+        self._write_root_index()
+        self._write_overview()
+        self._write_manifest()
+        self._write_projects()
+        self._write_metrics()
+        self._write_units()
+        self._write_symbols()
+        self._write_references()
+        self._write_problems()
+        self._write_reference_docs()
+
+    def _iter_unique_symbols(self) -> Iterator[Symbol]:
+        seen: set[bytes] = set()
+        for symbol in _all_symbols(self.index):
+            if symbol.kind.value == "unit":
+                continue
+            digest = hashlib.sha256(
+                _symbol_identity(symbol).encode("utf-8")
+            ).digest()
+            if digest in seen:
+                continue
+            seen.add(digest)
+            yield symbol
+
+    def _unit_records(self) -> list[_UnitRecord]:
+        records = [
+            _UnitRecord(
+                source,
+                model.unit_scope.name,
+                PurePosixPath("units")
+                / _document_name(model.unit_scope.name, _normalized_source(source)),
+            )
+            for source, model in self.index.models.items()
+        ]
+        return sorted(records, key=lambda record: (record.name.casefold(), record.source_path.casefold()))
+
+    def _collect_references(self) -> None:
+        for model in self.index.models.values():
+            for reference in model.references:
+                if reference.resolved is None:
+                    continue
+                key = id(reference.resolved)
+                self._references_by_target.setdefault(key, []).append(reference)
+        for references in self._references_by_target.values():
+            references.sort(key=_reference_sort_key)
+
+    def _iter_unresolved_references(self) -> Iterator[SymbolReference]:
+        seen: set[tuple[str, str, int, int, str]] = set()
+        for _source, model in sorted(
+            self.index.models.items(),
+            key=lambda item: item[0].casefold(),
+        ):
+            for reference in sorted(model.references, key=_reference_sort_key):
+                if reference.resolved is not None:
+                    continue
+                key = (
+                    reference.name.casefold(),
+                    reference.ref_range.file_name,
+                    reference.ref_range.start_line,
+                    reference.ref_range.start_col,
+                    reference.kind.value,
+                )
+                if key in seen:
+                    continue
+                seen.add(key)
+                yield reference
+
+    def _progress(
+        self,
+        phase: str,
+        completed: int,
+        total: int | None,
+        path: str,
+        detail: str,
+    ) -> None:
+        _emit_wiki_progress(
+            self._on_progress,
+            phase,
+            completed,
+            total,
+            path,
+            detail,
+        )
+
+    def _write_root_index(self) -> None:
+        body = [
+            "---",
+            f'okf_version: "{OKF_VERSION}"',
+            "---",
+            "# Delphi Codebase Wiki",
+            "",
+            "Portable knowledge export generated by "
+            f"`python-delphi-lsp {__version__}`.",
+            "",
+            "## Start here",
+            "",
+            f"- {_link('Overview', PurePosixPath('overview.md'))}",
+            f"- {_link('Projects', PurePosixPath('projects/index.md'))}",
+            f"- {_link('Units', PurePosixPath('units/index.md'))}",
+            f"- {_link('Symbols', PurePosixPath('symbols/index.md'))}",
+            f"- {_link('References', PurePosixPath('references/index.md'))}",
+            f"- {_link('Problems', PurePosixPath('problems/index.md'))}",
+            f"- {_link('Metrics', PurePosixPath('metrics/index.md'))}",
+            f"- {_link('Query and graph reference', PurePosixPath('reference/index.md'))}",
+            f"- {_link('Export manifest', PurePosixPath('manifest.md'))}",
+        ]
+        self._write(PurePosixPath("index.md"), "\n".join(body) + "\n")
+
+    def _write_overview(self) -> None:
+        overview = layer_payload(self.index, "overview")
+        body = [
+            f"# {_escape( Path(self.index.root).name or 'Delphi workspace')}",
+            "",
+            f"- Repository root: `{_escape_code(self.index.root)}`",
+            f"- Projects: {overview['project_count']}",
+            f"- Sources: {overview['source_count']}",
+            f"- Units: {overview['unit_count']}",
+            f"- Symbols: {self.symbol_count}",
+            "",
+            "## Defines",
+            "",
+            *_bullet_code_values(overview["defines"]),
+            "",
+            "## Search paths",
+            "",
+            *_bullet_code_values(overview["search_paths"]),
+            "",
+            "## Include paths",
+            "",
+            *_bullet_code_values(overview["include_paths"]),
+            "",
+            "## Related knowledge",
+            "",
+            f"- {_link('Projects', PurePosixPath('projects/index.md'))}",
+            f"- {_link('Problems', PurePosixPath('problems/index.md'))}",
+            f"- {_link('Workspace metrics', PurePosixPath('metrics/workspace.md'))}",
+        ]
+        self._concept(
+            PurePosixPath("overview.md"),
+            concept_type="Delphi Codebase",
+            title="Delphi codebase overview",
+            description="Discovered projects, sources, units, paths, defines, and diagnostics.",
+            tags=("delphi", "codebase", "overview"),
+            body=body,
+        )
+
+    def _write_manifest(self) -> None:
+        body = [
+            "# Export manifest",
+            "",
+            f"- Generator: `python-delphi-lsp/{__version__}`",
+            f"- Open Knowledge Format: `{OKF_VERSION}`",
+            f"- Projects: {len(self.index.discovery.project_files)}",
+            f"- Units: {len(self.units)}",
+            f"- Symbols: {self.symbol_count}",
+            "",
+            "## Coverage",
+            "",
+            "- Layered views: overview, projects, units, unit, symbols, symbol, "
+            "implementation, references, problems, and metrics.",
+            "- Semantic references are attached to their resolved symbol pages; "
+            "unresolved references are retained separately.",
+            "- Protocol v3 query, relation, CPG, pagination, and cache semantics "
+            "are documented under the reference section.",
+            "- Lazy CPG results are intentionally not expanded for every symbol, "
+            "which avoids redundant parsing and unbounded bundle growth.",
+        ]
+        self._concept(
+            PurePosixPath("manifest.md"),
+            concept_type="Knowledge Bundle Manifest",
+            title="Export manifest",
+            description="Generator, format, counts, and coverage of this knowledge bundle.",
+            tags=("manifest", "okf", "delphi"),
+            body=body,
+        )
+
+    def _write_projects(self) -> None:
+        pages: list[tuple[str, PurePosixPath]] = []
+        total = len(self.index.discovery.project_files)
+        for ordinal, item in enumerate(self._project_items(), start=1):
+            project_path = str(item["path"])
+            title = Path(project_path).name
+            page = PurePosixPath("projects") / _document_name(title, _normalized_source(project_path))
+            pages.append((title, page))
+            project_membership = (
+                project_path,
+                *(str(unit["path"]) for unit in item["parsed_units"]),
+            )
+            for source_path in project_membership:
+                self._record_project_membership(source_path, ordinal, title, page)
+            body = [
+                f"# {_escape(title)}",
+                "",
+                f"- Path: `{_escape_code(self._display_path(project_path))}`",
+                f"- Parsed units: {len(item['parsed_units'])}",
+                f"- Include files: {len(item['include_files'])}",
+                f"- Missing units: {len(item['not_found_units'])}",
+                f"- Problems: {len(item['problems'])}",
+                "",
+                "## Parsed units",
+                "",
+            ]
+            if item["parsed_units"]:
+                for unit in item["parsed_units"]:
+                    unit_record = self._find_unit(str(unit["path"]), str(unit["name"]))
+                    label = f"{unit['name']} — {self._display_path(str(unit['path']))}"
+                    body.append(
+                        f"- {_link(label, unit_record.page) if unit_record else _escape(label)}"
+                        f"{' (parse error)' if unit['has_error'] else ''}"
+                    )
+            else:
+                body.append("- None")
+            body.extend(["", "## Include files", ""])
+            body.extend(
+                f"- `{_escape_code(self._display_path(str(value['path'])))}`"
+                for value in item["include_files"]
+            )
+            if not item["include_files"]:
+                body.append("- None")
+            body.extend(["", "## Missing units", ""])
+            body.extend(f"- `{_escape_code(str(value))}`" for value in item["not_found_units"])
+            if not item["not_found_units"]:
+                body.append("- None")
+            body.extend(["", "## Project-index problems", ""])
+            body.extend(
+                f"- **{_escape(str(problem['kind']))}:** "
+                f"{_escape(str(problem['message']))} "
+                f"(`{_escape_code(self._display_path(str(problem['file'])))}`)"
+                for problem in item["problems"]
+            )
+            if not item["problems"]:
+                body.append("- None")
+            body.extend(["", "## Complete indexed data", "", _json_block(item)])
+            self._concept(
+                page,
+                concept_type="Delphi Project",
+                title=title,
+                description=f"Project index for {title}.",
+                tags=("delphi", "project"),
+                body=body,
+            )
+            self._progress(
+                "projects",
+                ordinal,
+                total,
+                project_path,
+                "project page written",
+            )
+        self._directory_index(
+            PurePosixPath("projects/index.md"),
+            "Projects",
+            pages,
+            empty="No Delphi project entry files were discovered.",
+        )
+
+    def _project_items(self) -> Iterable[dict[str, Any]]:
+        return layer_payload(self.index, "projects")["items"]
+
+    def _record_project_membership(
+        self,
+        source_path: str,
+        ordinal: int,
+        title: str,
+        page: PurePosixPath,
+    ) -> None:
+        del ordinal
+        memberships = self._projects_by_source.setdefault(
+            _normalized_source(source_path), []
+        )
+        membership = (title, page)
+        if membership not in memberships:
+            memberships.append(membership)
+
+    def _project_memberships_for(
+        self,
+        source_path: str,
+    ) -> list[tuple[str, PurePosixPath]]:
+        return self._projects_by_source.get(_normalized_source(source_path), [])
+
+    def _write_units(self) -> None:
+        pages: list[tuple[str, PurePosixPath]] = []
+        total = len(self.units)
+        for ordinal, unit in enumerate(self.units, start=1):
+            pages.append((unit.name, unit.page))
+            model = self.index.models[unit.source_path]
+            symbols = sorted(
+                _iter_symbols(model.unit_scope, include_unit=False),
+                key=lambda symbol: (
+                    symbol.decl_range.start_line,
+                    symbol.decl_range.start_col,
+                    symbol.name.casefold(),
+                    symbol.kind.value,
+                ),
+            )
+            references = sorted(model.references, key=_reference_sort_key)
+            projects = self._project_memberships_for(unit.source_path)
+            body = [
+                f"# {_escape(unit.name)}",
+                "",
+                f"- Source: `{_escape_code(self._display_path(unit.source_path))}`",
+                f"- Symbols: {len(symbols)}",
+                f"- Semantic references: {len(references)}",
+                "",
+                "## Projects",
+                "",
+            ]
+            body.extend(f"- {_link(title, page)}" for title, page in projects)
+            if not projects:
+                body.append("- No concrete project membership was resolved")
+            body.extend(
+                [
+                    "",
+                    "## Symbols",
+                    "",
+                ]
+            )
+            body.extend(
+                f"- {_link(symbol.name, _symbol_page(symbol))} "
+                f"— `{symbol.kind.value}` at line {symbol.decl_range.start_line}"
+                for symbol in symbols
+            )
+            if not symbols:
+                body.append("- None")
+            body.extend(["", "## References found in this unit", ""])
+            body.extend(self._reference_lines(references))
+            if not references:
+                body.append("- None")
+            metrics_page = self._metric_page_by_source.get(
+                _normalized_source(unit.source_path)
+            )
+            if metrics_page is not None:
+                body.extend(
+                    [
+                        "",
+                        "## Related knowledge",
+                        "",
+                        f"- {_link('Unit metrics', metrics_page)}",
+                    ]
+                )
+            self._concept(
+                unit.page,
+                concept_type="Delphi Unit",
+                title=unit.name,
+                description=f"Symbols and references in {unit.name}.",
+                tags=("delphi", "unit"),
+                body=body,
+            )
+            self._progress(
+                "units",
+                ordinal,
+                total,
+                unit.source_path,
+                "unit page written",
+            )
+        pages.sort(key=lambda item: (item[0].casefold(), item[1].as_posix()))
+        self._directory_index(
+            PurePosixPath("units/index.md"),
+            "Units",
+            pages,
+            empty="No Delphi units were indexed.",
+        )
+
+    def _write_symbols(self) -> None:
+        source_ordered_symbols = sorted(
+            self._iter_unique_symbols(),
+            key=lambda symbol: (
+                _normalized_source(symbol.decl_range.file_name),
+                symbol.decl_range.start_line,
+                symbol.decl_range.start_col,
+                symbol.name.casefold(),
+                symbol.kind.value,
+            ),
+        )
+        total = len(source_ordered_symbols)
+        for ordinal, symbol in enumerate(source_ordered_symbols, start=1):
+            references = self._references_by_target.get(id(symbol), [])
+            page, source, body = self._symbol_body_prefix(symbol)
+            body.extend(["", "## Semantic references", ""])
+            body.extend(self._reference_lines(references))
+            if not references:
+                body.append("- None")
+            self._concept(
+                page,
+                concept_type=f"Delphi {symbol.kind.value.replace('_', ' ').title()} Symbol",
+                title=symbol.name,
+                description=(
+                    f"{symbol.kind.value} {symbol.name} in {source} at "
+                    f"line {symbol.decl_range.start_line}."
+                ),
+                tags=("delphi", "symbol", symbol.kind.value),
+                body=body,
+            )
+            self._progress(
+                "symbols",
+                ordinal,
+                total,
+                symbol.decl_range.file_name,
+                f"symbol page written: {symbol.name}",
+            )
+
+        name_ordered_symbols = sorted(
+            self._iter_unique_symbols(),
+            key=lambda symbol: (
+                symbol.name.casefold(),
+                _normalized_source(symbol.decl_range.file_name),
+                symbol.decl_range.start_line,
+                symbol.decl_range.start_col,
+                symbol.kind.value,
+            ),
+        )
+        self._directory_index_iter(
+            PurePosixPath("symbols/index.md"),
+            "Symbols",
+            (
+                (f"{symbol.name} ({symbol.kind.value})", _symbol_page(symbol))
+                for symbol in name_ordered_symbols
+            ),
+            empty="No non-unit symbols were indexed.",
+        )
+
+    def _symbol_body_prefix(
+        self,
+        symbol: Symbol,
+    ) -> tuple[PurePosixPath, str, list[str]]:
+        page = _symbol_page(symbol)
+        source = self._display_path(symbol.decl_range.file_name)
+        unit = self._unit_by_source.get(_normalized_source(symbol.decl_range.file_name))
+        owner = _symbol_owner(symbol)
+        owner_symbol = symbol.scope.owner
+        owner_page = (
+            _symbol_page(owner_symbol)
+            if owner_symbol is not None
+            and owner_symbol.kind.value != "unit"
+            and owner_symbol is not symbol
+            else None
+        )
+        children = self._direct_symbol_children(symbol)
+        fragment = _source_fragment(symbol.decl_range, "declaration", self._source_cache)
+        modifiers = sorted(value.value for value in symbol.modifiers)
+        body = [
+            f"# {_escape(symbol.name)}",
+            "",
+            f"- Kind: `{symbol.kind.value}`",
+            f"- Type: `{_escape_code(symbol.type_ref.display_name())}`",
+            f"- Visibility: `{symbol.visibility.value}`",
+            (
+                f"- Owner: "
+                f"{_link(owner, owner_page) if owner_page else f'`{_escape_code(owner)}`'}"
+            ),
+            f"- Unit: {_link(unit.name, unit.page) if unit else '`unknown`'}",
+            (
+                f"- Location: `{_escape_code(source)}:{symbol.decl_range.start_line}:"
+                f"{symbol.decl_range.start_col}`"
+            ),
+            (
+                f"- Range: `{symbol.decl_range.start_line}:{symbol.decl_range.start_col}-"
+                f"{symbol.decl_range.end_line}:{symbol.decl_range.end_col}`"
+            ),
+            f"- Modifiers: {', '.join(f'`{value}`' for value in modifiers) or 'None'}",
+            (
+                f"- Base types: "
+                f"{', '.join(f'`{_escape_code(value.display_name())}`' for value in symbol.base_types) or 'None'}"
+            ),
+        ]
+        if symbol.doc:
+            body.extend(["", "## Documentation", "", symbol.doc])
+        if symbol.attributes:
+            body.extend(["", "## Attributes", "", _json_block(symbol.attributes)])
+        body.extend(["", "## Declaration or implementation", ""])
+        if fragment is None:
+            body.append("Source fragment unavailable.")
+        else:
+            body.extend(
+                [
+                    (
+                        f"`{_escape_code(self._display_path(str(fragment['range']['path'])))}:"
+                        f"{fragment['range']['start_line']}`"
+                    ),
+                    "",
+                    _code_block(str(fragment["text"]), "pascal"),
+                ]
+            )
+        body.extend(["", "## Members", ""])
+        body.extend(
+            f"- {_link(child.name, _symbol_page(child))} — `{child.kind.value}`"
+            for child in children
+        )
+        if not children:
+            body.append("- None")
+        return page, source, body
+
+    @staticmethod
+    def _direct_symbol_children(symbol: Symbol) -> list[Symbol]:
+        if symbol.member_scope is None:
+            return []
+        children = [
+            child
+            for symbols in symbol.member_scope.symbols.values()
+            for child in symbols
+            if child is not symbol and child.kind.value != "unit"
+        ]
+        return sorted(
+            children,
+            key=lambda child: (
+                child.name.casefold(),
+                child.kind.value,
+                child.decl_range.start_line,
+                child.decl_range.start_col,
+            ),
+        )
+
+    def _write_references(self) -> None:
+        resolved_symbols = sorted(
+            (
+                symbol
+                for symbol in self._iter_unique_symbols()
+                if id(symbol) in self._references_by_target
+            ),
+            key=lambda symbol: (
+                symbol.name.casefold(),
+                _normalized_source(symbol.decl_range.file_name),
+                symbol.decl_range.start_line,
+                symbol.decl_range.start_col,
+            ),
+        )
+        unresolved_page = PurePosixPath("references/unresolved.md")
+        unresolved_count = sum(1 for _ in self._iter_unresolved_references())
+
+        def unresolved_body() -> Iterator[str]:
+            yield "# Unresolved semantic references"
+            yield ""
+            yield (
+                "These names were observed by the tolerant semantic index but "
+                "could not be resolved soundly in the current workspace."
+            )
+            yield ""
+            if unresolved_count:
+                yield from self._iter_reference_lines(
+                    self._iter_unresolved_references()
+                )
+            else:
+                yield "- None"
+
+        self._concept_iter(
+            unresolved_page,
+            concept_type="Delphi Unresolved References",
+            title="Unresolved semantic references",
+            description="References that remain unresolved in the tolerant semantic index.",
+            tags=("delphi", "references", "diagnostics"),
+            body=unresolved_body(),
+        )
+
+        def reference_index_lines() -> Iterator[str]:
+            yield "# References"
+            yield ""
+            yield "Resolved references are embedded on their target symbol pages."
+            yield ""
+            if resolved_symbols:
+                for symbol in resolved_symbols:
+                    count = len(self._references_by_target[id(symbol)])
+                    yield f"- {_link(f'{symbol.name} ({count})', _symbol_page(symbol))}"
+            else:
+                yield "- No resolved references"
+            yield ""
+            yield f"- {_link('Unresolved references', unresolved_page)}"
+
+        self._write_lines(
+            PurePosixPath("references/index.md"),
+            reference_index_lines(),
+        )
+        self._progress(
+            "references",
+            1,
+            1,
+            str(unresolved_page),
+            (
+                f"reference pages written ({len(resolved_symbols)} resolved "
+                f"targets, {unresolved_count} unresolved)"
+            ),
+        )
+
+    def _write_problems(self) -> None:
+        payload = layer_payload(self.index, "problems")
+        page = PurePosixPath("problems/workspace.md")
+        body = ["# Workspace problems", "", f"Problems: {len(payload['items'])}", ""]
+        body.extend(
+            f"- **{_escape(str(item['kind']))}:** {_escape(str(item['message']))} "
+            f"(`{_escape_code(self._display_path(str(item.get('origin', ''))))}`)"
+            for item in payload["items"]
+        )
+        if not payload["items"]:
+            body.append("- None")
+        body.extend(["", "## Complete problem data", "", _json_block(payload["items"])])
+        self._concept(
+            page,
+            concept_type="Delphi Workspace Problems",
+            title="Workspace problems",
+            description="Discovery and deep-project indexing problems.",
+            tags=("delphi", "problems", "diagnostics"),
+            body=body,
+        )
+        self._directory_index(
+            PurePosixPath("problems/index.md"),
+            "Problems",
+            [("Workspace problems", page)],
+            empty="No problem report was generated.",
+        )
+
+    def _write_metrics(self) -> None:
+        project_name = "Workspace"
+        if len(self.index.discovery.project_files) == 1:
+            project_name = Path(self.index.discovery.project_files[0]).stem
+        metric_source_total = len(self.index.discovery.source_files)
+        self._progress(
+            "metrics",
+            0,
+            metric_source_total or 1,
+            self.index.root,
+            "calculating source metrics",
+        )
+        metrics = build_path_metrics(
+            self.index.root,
+            self.index.discovery.source_files,
+            defines=self.index.discovery.defines,
+            include_paths=self.index.discovery.include_paths,
+            project_config=self.index.discovery.project_config,
+            project_name=project_name,
+            workers=self.workers,
+            on_progress=lambda completed, total, path: self._progress(
+                "metrics",
+                completed,
+                total,
+                path,
+                "source metrics calculated",
+            ),
+        )
+        payload = {
+            "project": metrics.to_mapping(),
+            "items": [unit.to_mapping(detail=True) for unit in metrics.file_metrics],
+        }
+        workspace_page = PurePosixPath("metrics/workspace.md")
+        project = payload["project"]
+        workspace_body = [
+            "# Workspace metrics",
+            "",
+            f"- Total LOC: {project['total_loc']}",
+            f"- Total LOC with includes: {project['total_loc_with_includes']}",
+            f"- Units: {project['unit_count']}",
+            f"- Maintainability index: {project['maintainability_index']:.2f}",
+            "",
+            "## Complete metric data",
+            "",
+            _json_block(project),
+        ]
+        self._concept(
+            workspace_page,
+            concept_type="Delphi Project Metrics",
+            title="Workspace metrics",
+            description="Aggregate architecture and maintainability metrics.",
+            tags=("delphi", "metrics", "architecture"),
+            body=workspace_body,
+        )
+
+        unit_pages: list[tuple[str, PurePosixPath]] = []
+        metric_item_total = len(payload["items"])
+        for ordinal, item in enumerate(payload["items"], start=1):
+            unit = self._find_unit(str(item["path"]), str(item["name"]))
+            metric_identity = (
+                _normalized_source(unit.source_path)
+                if unit is not None
+                else _normalized_source(str(item["path"]))
+            )
+            page = PurePosixPath("metrics/units") / _document_name(
+                str(item["name"]), metric_identity
+            )
+            if unit is not None:
+                self._metric_page_by_source[
+                    _normalized_source(unit.source_path)
+                ] = page
+            unit_pages.append((str(item["name"]), page))
+            body = [
+                f"# {_escape(str(item['name']))} metrics",
+                "",
+                f"- Unit: {_link(str(item['name']), unit.page) if unit else _escape(str(item['name']))}",
+                f"- Source: `{_escape_code(self._display_path(str(item['path'])))}`",
+                f"- LOC: {item['lines']['total_lines']}",
+                f"- Cyclomatic maximum: {item['cyclomatic']['maximum']}",
+                f"- Maintainability index: {item['maintainability_index']:.2f}",
+                f"- Instability: {item['instability']:.3f}",
+                f"- Abstractness: {item['abstractness']:.3f}",
+                f"- Distance: {item['distance']:.3f}",
+                "",
+                "## Complete metric data",
+                "",
+                _json_block(item),
+            ]
+            self._concept(
+                page,
+                concept_type="Delphi Unit Metrics",
+                title=f"{item['name']} metrics",
+                description=f"Architecture and maintainability metrics for {item['name']}.",
+                tags=("delphi", "metrics", "unit"),
+                body=body,
+            )
+            self._progress(
+                "metric-pages",
+                ordinal,
+                metric_item_total,
+                str(item["path"]),
+                "unit metric page written",
+            )
+        self._directory_index(
+            PurePosixPath("metrics/units/index.md"),
+            "Unit metrics",
+            unit_pages,
+            empty="No per-unit metrics were calculated.",
+        )
+        self._directory_index(
+            PurePosixPath("metrics/index.md"),
+            "Metrics",
+            [("Workspace metrics", workspace_page), ("Unit metrics", PurePosixPath("metrics/units/index.md"))],
+            empty="No metrics were calculated.",
+        )
+
+    def _write_reference_docs(self) -> None:
+        protocol_page = PurePosixPath("reference/protocol.md")
+        protocol_body = [
+            "# Agent Protocol v3",
+            "",
+            f"- Schema version: `{SCHEMA_VERSION}`",
+            f"- Actions: {_inline_code(SUPPORTED_ACTIONS)}",
+            f"- Detail modes: {_inline_code(SUPPORTED_DETAILS)}",
+            f"- Relations: {_inline_code(SUPPORTED_RELATIONS)}",
+            f"- Graphs: {_inline_code(SUPPORTED_GRAPHS)}",
+            f"- Directions: {_inline_code(SUPPORTED_DIRECTIONS)}",
+            "",
+            "Query pages are revision-bound and may use cursors. Live requests "
+            "bound result size with `max_items` and `max_chars`; this static "
+            "bundle instead stores each unique exported fact once.",
+        ]
+        self._concept(
+            protocol_page,
+            concept_type="Delphi Agent Protocol Reference",
+            title="Agent Protocol v3",
+            description="Supported query actions, detail modes, relations, and pagination.",
+            tags=("delphi", "protocol", "query"),
+            body=protocol_body,
+        )
+
+        cpg_page = PurePosixPath("reference/cpg.md")
+        cpg_body = [
+            "# Code Property Graph",
+            "",
+            f"Available graph projections: {_inline_code(SUPPORTED_GRAPHS)}.",
+            f"Traversal directions: {_inline_code(SUPPORTED_DIRECTIONS)}.",
+            "",
+            "CPG queries lazily combine AST, control-flow, data-flow, and call "
+            "edges for a focused target. They remain live queries because "
+            "eagerly materializing every overlapping target would repeat source "
+            "parsing and make a multi-million-line export unbounded.",
+            "",
+            "The exporter retains symbol locations, implementations, semantic "
+            "references, metrics, and the supported graph contract needed to "
+            "select a target for a subsequent live CPG query.",
+        ]
+        self._concept(
+            cpg_page,
+            concept_type="Delphi Code Property Graph Reference",
+            title="Code Property Graph",
+            description="Available CPG projections, traversal controls, and export boundaries.",
+            tags=("delphi", "cpg", "graph"),
+            body=cpg_body,
+        )
+
+        cache_page = PurePosixPath("reference/cache.md")
+        cache_body = [
+            "# Cache behavior",
+            "",
+            "The shared cache daemon prewarms a repository navigation context, "
+            "reuses it across CLI queries, invalidates it when the workspace "
+            "revision changes, and keeps memory bounded by its configured limit.",
+            "",
+            "The wiki export is independent of daemon lifetime. It performs one "
+            "parallel index build and writes a portable on-disk snapshot.",
+        ]
+        self._concept(
+            cache_page,
+            concept_type="Delphi Cache Reference",
+            title="Cache behavior",
+            description="Relationship between the live bounded cache and static wiki exports.",
+            tags=("delphi", "cache", "performance"),
+            body=cache_body,
+        )
+
+        layers_page = PurePosixPath("reference/layers.md")
+        layers_body = [
+            "# Layer mapping",
+            "",
+            "- `overview` → `overview.md`",
+            "- `projects` → `projects/`",
+            "- `units` and `unit` → `units/`",
+            "- `symbols`, `symbol`, and `implementation` → `symbols/`",
+            "- `references` → symbol pages and `references/`",
+            "- `problems` → `problems/`",
+            "- `metrics` → `metrics/`",
+        ]
+        self._concept(
+            layers_page,
+            concept_type="Delphi Layer Export Reference",
+            title="Layer mapping",
+            description="Mapping from live layered views to static wiki concepts.",
+            tags=("delphi", "layers", "export"),
+            body=layers_body,
+        )
+        self._directory_index(
+            PurePosixPath("reference/index.md"),
+            "Query and graph reference",
+            [
+                ("Agent Protocol v3", protocol_page),
+                ("Layer mapping", layers_page),
+                ("Code Property Graph", cpg_page),
+                ("Cache behavior", cache_page),
+            ],
+            empty="No reference documents were generated.",
+        )
+
+    def _reference_lines(self, references: Iterable[SymbolReference]) -> list[str]:
+        return list(self._iter_reference_lines(references))
+
+    def _iter_reference_lines(
+        self,
+        references: Iterable[SymbolReference],
+    ) -> Iterator[str]:
+        for reference in references:
+            yield self._reference_line(
+                reference,
+                target_key=_reference_target_key(reference),
+            )
+
+    def _reference_line(
+        self,
+        reference: SymbolReference,
+        *,
+        target_key: str | None,
+    ) -> str:
+        location = (
+            f"{self._display_path(reference.ref_range.file_name)}:"
+            f"{reference.ref_range.start_line}:{reference.ref_range.start_col}"
+        )
+        target = reference.resolved
+        target_text = (
+            f" → {_link(target.name, PurePosixPath('symbols') / _document_name(target.name, target_key))}"
+            if target is not None and target_key is not None
+            else ""
+        )
+        return (
+            f"- `{reference.kind.value}` `{_escape_code(reference.name)}` at "
+            f"`{_escape_code(location)}`{target_text}"
+        )
+
+    def _find_unit(self, source: str, name: str) -> _UnitRecord | None:
+        source_path = Path(source).expanduser()
+        if not source_path.is_absolute():
+            source_path = Path(self.index.root) / source_path
+        return self._unit_by_source.get(
+            _normalized_source(str(source_path))
+        ) or self._unit_by_name.get(name.casefold())
+
+    def _display_path(self, value: str) -> str:
+        if not value:
+            return ""
+        cached = self._display_path_cache.get(value)
+        if cached is not None:
+            return cached
+        path = Path(value)
+        try:
+            displayed = path.resolve().relative_to(Path(self.index.root)).as_posix()
+        except (OSError, ValueError):
+            displayed = path.as_posix()
+        self._display_path_cache[value] = displayed
+        return displayed
+
+    def _concept(
+        self,
+        page: PurePosixPath,
+        *,
+        concept_type: str,
+        title: str,
+        description: str,
+        tags: tuple[str, ...],
+        body: list[str],
+    ) -> None:
+        frontmatter = [
+            "---",
+            f"type: {json.dumps(concept_type, ensure_ascii=False)}",
+            f"title: {json.dumps(title, ensure_ascii=False)}",
+            f"description: {json.dumps(description, ensure_ascii=False)}",
+            f"tags: {json.dumps(list(tags), ensure_ascii=False)}",
+            'status: "stable"',
+            "---",
+        ]
+        self._write(page, "\n".join([*frontmatter, *body]).rstrip() + "\n")
+
+    def _concept_iter(
+        self,
+        page: PurePosixPath,
+        *,
+        concept_type: str,
+        title: str,
+        description: str,
+        tags: tuple[str, ...],
+        body: Iterable[str],
+    ) -> None:
+        frontmatter = (
+            "---",
+            f"type: {json.dumps(concept_type, ensure_ascii=False)}",
+            f"title: {json.dumps(title, ensure_ascii=False)}",
+            f"description: {json.dumps(description, ensure_ascii=False)}",
+            f"tags: {json.dumps(list(tags), ensure_ascii=False)}",
+            'status: "stable"',
+            "---",
+        )
+        self._write_lines(page, chain(frontmatter, body))
+
+    def _directory_index(
+        self,
+        page: PurePosixPath,
+        title: str,
+        items: list[tuple[str, PurePosixPath]],
+        *,
+        empty: str,
+    ) -> None:
+        body = [f"# {_escape(title)}", ""]
+        body.extend(f"- {_link(label, target)}" for label, target in items)
+        if not items:
+            body.append(empty)
+        self._write(page, "\n".join(body).rstrip() + "\n")
+
+    def _directory_index_iter(
+        self,
+        page: PurePosixPath,
+        title: str,
+        items: Iterable[tuple[str, PurePosixPath]],
+        *,
+        empty: str,
+    ) -> None:
+        iterator = iter(items)
+        first = next(iterator, None)
+
+        def lines() -> Iterator[str]:
+            yield f"# {_escape(title)}"
+            yield ""
+            if first is None:
+                yield empty
+                return
+            yield f"- {_link(first[0], first[1])}"
+            for label, target in iterator:
+                yield f"- {_link(label, target)}"
+
+        self._write_lines(page, lines())
+
+    def _write(self, relative_path: PurePosixPath, text: str) -> None:
+        target = self.destination.joinpath(*relative_path.parts)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(text, encoding="utf-8", newline="\n")
+        self.documents += 1
+
+    def _write_lines(
+        self,
+        relative_path: PurePosixPath,
+        lines: Iterable[str],
+    ) -> None:
+        target = self.destination.joinpath(*relative_path.parts)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        with target.open("w", encoding="utf-8", newline="\n") as stream:
+            for line in lines:
+                stream.write(line)
+                stream.write("\n")
+        self.documents += 1
+
+
+class _StreamingWikiWriter(_WikiWriter):
+    """Write a wiki while retaining at most the current unit and reference group."""
+
+    def __init__(
+        self,
+        index: CodebaseIndex,
+        destination: Path,
+        *,
+        models: _StoredWikiModels,
+        projects: _WikiProjectStore,
+        unique_catalog: Path,
+        name_catalog: Path,
+        symbol_count: int,
+        workspace: Path,
+        guard: WikiMemoryGuard,
+        strategy: _WikiExecutionStrategy,
+        on_progress: WikiProgressCallback | None,
+    ) -> None:
+        self.index = index
+        self.destination = destination
+        self.workers = strategy.workers
+        self._on_progress = on_progress
+        self.documents = 0
+        self._source_cache: dict[str, list[str]] = _BoundedSourceCache()
+        self._display_path_cache: dict[str, str] = {}
+        self._symbol_count = symbol_count
+        self.units = models.unit_records()
+        self._unit_by_source = {
+            _normalized_source(record.source_path): record for record in self.units
+        }
+        self._unit_by_name = {record.name.casefold(): record for record in self.units}
+        self._references_by_target: dict[int, list[SymbolReference]] = {}
+        self._projects_by_source: dict[str, list[tuple[str, PurePosixPath]]] = {}
+        self._metric_page_by_source: dict[str, PurePosixPath] = {}
+        self.models = models
+        self.projects = projects
+        self.unique_catalog = unique_catalog
+        self.name_catalog = name_catalog
+        self.workspace = workspace
+        self.guard = guard
+        self.strategy = strategy
+        self.memberships = _ProjectMembershipStore(workspace / "membership.sqlite3")
+        self.raw_references = workspace / "references-raw.jsonl"
+        self.raw_unresolved = workspace / "unresolved-raw.jsonl"
+
+    def close(self) -> None:
+        self.memberships.close()
+
+    def clear_caches(self) -> None:
+        self.models.clear_cache()
+        self._source_cache.clear()
+        self._display_path_cache.clear()
+
+    def write(self) -> None:
+        self._write_root_index()
+        self._write_overview()
+        self._write_manifest()
+        self._write_projects()
+        self.memberships.commit()
+        self._write_metrics()
+        self.guard.check(phase="metrics")
+        self._write_streaming_units_and_symbol_bases()
+        sorted_references = self._sort_references()
+        self._finish_symbol_pages_and_references(sorted_references)
+        self._write_streaming_problems()
+        self._write_reference_docs()
+
+    def _project_items(self) -> Iterable[dict[str, Any]]:
+        return self.projects.items()
+
+    def _record_project_membership(
+        self,
+        source_path: str,
+        ordinal: int,
+        title: str,
+        page: PurePosixPath,
+    ) -> None:
+        self.memberships.add(source_path, ordinal, title, page)
+
+    def _project_memberships_for(
+        self,
+        source_path: str,
+    ) -> list[tuple[str, PurePosixPath]]:
+        return self.memberships.for_source(source_path)
+
+    def _write_streaming_units_and_symbol_bases(self) -> None:
+        parser = DelphiParser(
+            include_paths=self.index.discovery.include_paths,
+            defines=self.index.discovery.defines,
+            include_loader=workspace_include_loader(
+                self.index.discovery.project_config,
+                self.index.discovery.include_paths,
+            ),
+            mode=ParserMode.TOLERANT,
+        )
+        unit_pages: list[tuple[str, PurePosixPath]] = []
+        self.raw_references.touch()
+        self.raw_unresolved.touch()
+        total = len(self.units)
+        source_ordinal = {source: ordinal for ordinal, source in enumerate(self.models)}
+        with (
+            self.raw_references.open("a", encoding="utf-8", newline="\n") as resolved_stream,
+            self.raw_unresolved.open("a", encoding="utf-8", newline="\n") as unresolved_stream,
+        ):
+            for ordinal, unit in enumerate(self.units, start=1):
+                outline_model = self.models[unit.source_path]
+                references = self._parse_unit_references(
+                    unit,
+                    outline_model,
+                    parser,
+                )
+                indexed_references = list(enumerate(references))
+                indexed_references.sort(key=lambda item: _reference_sort_key(item[1]))
+                prepared_references = [
+                    (
+                        reference_ordinal,
+                        reference,
+                        _reference_target_key(reference),
+                    )
+                    for reference_ordinal, reference in indexed_references
+                ]
+                reference_lines = [
+                    self._reference_line(reference, target_key=target_key)
+                    for _reference_ordinal, reference, target_key in prepared_references
+                ]
+                self._write_streaming_unit_page(
+                    unit,
+                    outline_model,
+                    reference_lines,
+                )
+                unit_pages.append((unit.name, unit.page))
+                self._write_symbol_bases(outline_model)
+                model_ordinal = source_ordinal[unit.source_path]
+                for (reference_ordinal, reference, target_key), line in zip(
+                    prepared_references,
+                    reference_lines,
+                    strict=True,
+                ):
+                    record = self._reference_record(
+                        reference,
+                        line=line,
+                        model_ordinal=model_ordinal,
+                        reference_ordinal=reference_ordinal,
+                        target_key=target_key,
+                    )
+                    if record["resolved"] and record.get("target_key") is None:
+                        continue
+                    stream = resolved_stream if record["resolved"] else unresolved_stream
+                    stream.write(
+                        json.dumps(record, ensure_ascii=False, separators=(",", ":"))
+                    )
+                    stream.write("\n")
+                del indexed_references
+                del prepared_references
+                del references
+                del outline_model
+                if ordinal % _STREAMING_UNIT_GC_INTERVAL == 0:
+                    gc.collect()
+                self._progress(
+                    "units",
+                    ordinal,
+                    total,
+                    unit.source_path,
+                    "unit and symbol pages streamed",
+                )
+                self.guard.check(phase="unit export")
+        gc.collect()
+        self.guard.check(phase="unit export", force_process_tree=True)
+        unit_pages.sort(key=lambda item: (item[0].casefold(), item[1].as_posix()))
+        self._directory_index(
+            PurePosixPath("units/index.md"),
+            "Units",
+            unit_pages,
+            empty="No Delphi units were indexed.",
+        )
+
+    def _parse_unit_references(
+        self,
+        unit: _UnitRecord,
+        outline_model: SemanticModel,
+        parser: DelphiParser,
+    ) -> list[SymbolReference]:
+        lazy_index = _LazyWikiSymbolIndex(self.models)
+        outline_by_exact: dict[tuple[str, str, str, int, int], Symbol] = {}
+        outline_by_source: dict[tuple[str, str, str], Symbol] = {}
+        for symbol in _iter_symbols(outline_model.unit_scope):
+            source_key = (
+                symbol.name.casefold(),
+                symbol.kind.value,
+                symbol.decl_range.file_name.casefold(),
+            )
+            outline_by_source.setdefault(source_key, symbol)
+            outline_by_exact[
+                (
+                    *source_key,
+                    symbol.name_range.start_line,
+                    symbol.name_range.start_col,
+                )
+            ] = symbol
+        try:
+            source = read_source_text(Path(unit.source_path))
+            parsed = parser.parse(
+                source,
+                unit.source_path,
+                build_semantic=True,
+                index=lazy_index,
+            )
+        except (OSError, UnicodeError):
+            return []
+        if parsed.semantic is None:
+            return []
+        mapped_references: list[SymbolReference] = []
+        for reference in parsed.semantic.references:
+            resolved = reference.resolved
+            mapped = (
+                resolved
+                if resolved is not None
+                and _scope_root(resolved.scope) is not parsed.semantic.unit_scope
+                else None
+            )
+            if resolved is not None and mapped is None:
+                source_key = (
+                    resolved.name.casefold(),
+                    resolved.kind.value,
+                    resolved.decl_range.file_name.casefold(),
+                )
+                mapped = outline_by_exact.get(
+                    (
+                        *source_key,
+                        resolved.name_range.start_line,
+                        resolved.name_range.start_col,
+                    )
+                ) or outline_by_source.get(source_key)
+            mapped_references.append(
+                SymbolReference(
+                    name=reference.name,
+                    kind=reference.kind,
+                    ref_range=reference.ref_range,
+                    scope=outline_model.unit_scope,
+                    resolved=mapped,
+                )
+            )
+        return mapped_references
+
+    def _write_streaming_unit_page(
+        self,
+        unit: _UnitRecord,
+        model: SemanticModel,
+        reference_lines: list[str],
+    ) -> None:
+        symbols = sorted(
+            _iter_symbols(model.unit_scope, include_unit=False),
+            key=lambda symbol: (
+                symbol.decl_range.start_line,
+                symbol.decl_range.start_col,
+                symbol.name.casefold(),
+                symbol.kind.value,
+            ),
+        )
+        projects = self._project_memberships_for(unit.source_path)
+        body = [
+            f"# {_escape(unit.name)}",
+            "",
+            f"- Source: `{_escape_code(self._display_path(unit.source_path))}`",
+            f"- Symbols: {len(symbols)}",
+            f"- Semantic references: {len(reference_lines)}",
+            "",
+            "## Projects",
+            "",
+        ]
+        body.extend(f"- {_link(title, page)}" for title, page in projects)
+        if not projects:
+            body.append("- No concrete project membership was resolved")
+        body.extend(["", "## Symbols", ""])
+        body.extend(
+            f"- {_link(symbol.name, _symbol_page(symbol))} "
+            f"— `{symbol.kind.value}` at line {symbol.decl_range.start_line}"
+            for symbol in symbols
+        )
+        if not symbols:
+            body.append("- None")
+        body.extend(["", "## References found in this unit", ""])
+        body.extend(reference_lines or ["- None"])
+        metrics_page = self._metric_page_by_source.get(
+            _normalized_source(unit.source_path)
+        )
+        if metrics_page is not None:
+            body.extend(
+                ["", "## Related knowledge", "", f"- {_link('Unit metrics', metrics_page)}"]
+            )
+        self._concept(
+            unit.page,
+            concept_type="Delphi Unit",
+            title=unit.name,
+            description=f"Symbols and references in {unit.name}.",
+            tags=("delphi", "unit"),
+            body=body,
+        )
+
+    def _write_symbol_bases(self, model: SemanticModel) -> None:
+        for symbol in _iter_symbols(model.unit_scope, include_unit=False):
+            page = _symbol_page(symbol)
+            target = self.destination.joinpath(*page.parts)
+            if target.exists():
+                continue
+            page, source, body = self._symbol_body_prefix(symbol)
+            body.extend(["", "## Semantic references", ""])
+            self._concept(
+                page,
+                concept_type=f"Delphi {symbol.kind.value.replace('_', ' ').title()} Symbol",
+                title=symbol.name,
+                description=(
+                    f"{symbol.kind.value} {symbol.name} in {source} at "
+                    f"line {symbol.decl_range.start_line}."
+                ),
+                tags=("delphi", "symbol", symbol.kind.value),
+                body=body,
+            )
+
+    def _reference_record(
+        self,
+        reference: SymbolReference,
+        *,
+        line: str,
+        model_ordinal: int,
+        reference_ordinal: int,
+        target_key: str | None,
+    ) -> dict[str, Any]:
+        target = reference.resolved
+        source_symbol = (
+            reference.scope.owner.name
+            if reference.scope.owner is not None
+            else reference.scope.name
+        )
+        reference_key = (
+            _normalized_source(reference.ref_range.file_name),
+            reference.ref_range.start_line,
+            reference.ref_range.start_col,
+            reference.kind.value,
+            reference.name.casefold(),
+        )
+        dedupe_key = "|".join(
+            (
+                reference.name.casefold(),
+                reference.ref_range.file_name,
+                str(reference.ref_range.start_line),
+                str(reference.ref_range.start_col),
+                reference.kind.value,
+            )
+        )
+        order_key = "|".join(
+            (
+                f"{model_ordinal:012d}",
+                reference_key[0],
+                f"{reference_key[1]:012d}",
+                f"{reference_key[2]:012d}",
+                reference_key[3],
+                reference_key[4],
+                f"{reference_ordinal:012d}",
+            )
+        )
+        return {
+            "column": reference.ref_range.start_col,
+            "dedupe_key": dedupe_key,
+            "file": reference.ref_range.file_name,
+            "file_key": reference_key[0],
+            "kind": reference.kind.value,
+            "line": line,
+            "line_number": reference.ref_range.start_line,
+            "model_ordinal": f"{model_ordinal:012d}",
+            "name": reference.name,
+            "name_key": reference.name.casefold(),
+            "order_key": order_key,
+            "reference_ordinal": f"{reference_ordinal:012d}",
+            "resolved": target is not None,
+            "source_symbol": source_symbol,
+            "target_key": target_key,
+        }
+
+    def _sort_references(self) -> Path:
+        sorted_references = self.workspace / "references-sorted.jsonl"
+        sort_jsonl_records(
+            self.raw_references,
+            sorted_references,
+            key=lambda item: (
+                str(item["target_key"]),
+                str(item["file_key"]),
+                f"{int(item['line_number']):012d}",
+                f"{int(item['column']):012d}",
+                str(item["kind"]),
+                str(item["name_key"]),
+                str(item["model_ordinal"]),
+                str(item["reference_ordinal"]),
+            ),
+            max_records_per_run=self.strategy.sort_records_per_run,
+            max_bytes_per_run=self.strategy.sort_bytes_per_run,
+            temp_dir=self.workspace,
+            heartbeat=lambda: self.guard.check(
+                phase="external reference sort",
+            ),
+            force_heartbeat=lambda: self.guard.check(
+                phase="external reference sort",
+                force_process_tree=True,
+            ),
+        )
+        self.guard.check(phase="external reference sort", force_process_tree=True)
+        return sorted_references
+
+    def _finish_symbol_pages_and_references(self, sorted_references: Path) -> None:
+        resolved_index = self.workspace / "resolved-index-raw.jsonl"
+        resolved_index.touch()
+        references = _iter_json_objects(sorted_references)
+        current_reference = next(references, None)
+        symbol_total = self.symbol_count
+        with resolved_index.open("a", encoding="utf-8", newline="\n") as resolved_stream:
+            for ordinal, symbol_item in enumerate(
+                _iter_json_objects(self.unique_catalog),
+                start=1,
+            ):
+                identity = str(symbol_item["identity"])
+                page = PurePosixPath(str(symbol_item["page"]))
+                page_path = self.destination.joinpath(*page.parts)
+                count = 0
+                with page_path.open("a", encoding="utf-8", newline="\n") as page_stream:
+                    page_stream.write("\n")
+                    while (
+                        current_reference is not None
+                        and str(current_reference["target_key"]) < identity
+                    ):
+                        current_reference = next(references, None)
+                    while (
+                        current_reference is not None
+                        and str(current_reference["target_key"]) == identity
+                    ):
+                        page_stream.write(str(current_reference["line"]))
+                        page_stream.write("\n")
+                        count += 1
+                        current_reference = next(references, None)
+                    if count == 0:
+                        page_stream.write("- None\n")
+                if count:
+                    resolved_item = {
+                        "count": count,
+                        "kind": symbol_item["kind"],
+                        "name": symbol_item["name"],
+                        "name_key": symbol_item["name_key"],
+                        "page": symbol_item["page"],
+                        "source_key": symbol_item["source_key"],
+                        "start_col": symbol_item["start_col"],
+                        "start_line": symbol_item["start_line"],
+                    }
+                    resolved_stream.write(
+                        json.dumps(
+                            resolved_item,
+                            ensure_ascii=False,
+                            separators=(",", ":"),
+                        )
+                    )
+                    resolved_stream.write("\n")
+                self._progress(
+                    "symbols",
+                    ordinal,
+                    symbol_total,
+                    str(symbol_item["source_key"]),
+                    f"symbol page finalized: {symbol_item['name']}",
+                )
+                if ordinal % 1_000 == 0:
+                    self.guard.check(phase="reverse references")
+        self.guard.check(phase="reverse references", force_process_tree=True)
+        self._write_symbol_index()
+        unresolved_count = self._write_unresolved_page()
+        resolved_count = self._write_reference_index(resolved_index)
+        self._progress(
+            "references",
+            1,
+            1,
+            "references/unresolved.md",
+            (
+                f"reference pages written ({resolved_count} resolved "
+                f"targets, {unresolved_count} unresolved)"
+            ),
+        )
+
+    def _write_symbol_index(self) -> None:
+        self._directory_index_iter(
+            PurePosixPath("symbols/index.md"),
+            "Symbols",
+            (
+                (
+                    f"{item['name']} ({item['kind']})",
+                    PurePosixPath(str(item["page"])),
+                )
+                for item in _iter_json_objects(self.name_catalog)
+            ),
+            empty="No non-unit symbols were indexed.",
+        )
+
+    def _write_unresolved_page(self) -> int:
+        by_key = self.workspace / "unresolved-by-key.jsonl"
+        unique = self.workspace / "unresolved-unique.jsonl"
+        ordered = self.workspace / "unresolved-ordered.jsonl"
+        sort_jsonl_records(
+            self.raw_unresolved,
+            by_key,
+            key=lambda item: (str(item["dedupe_key"]), str(item["order_key"])),
+            max_records_per_run=self.strategy.sort_records_per_run,
+            max_bytes_per_run=self.strategy.sort_bytes_per_run,
+            temp_dir=self.workspace,
+            heartbeat=lambda: self.guard.check(
+                phase="unresolved reference sort",
+            ),
+            force_heartbeat=lambda: self.guard.check(
+                phase="unresolved reference sort",
+                force_process_tree=True,
+            ),
+        )
+        previous_key: str | None = None
+        unresolved_count = 0
+        with unique.open("w", encoding="utf-8", newline="\n") as target:
+            for item in _iter_json_objects(by_key):
+                dedupe_key = str(item["dedupe_key"])
+                if dedupe_key == previous_key:
+                    continue
+                previous_key = dedupe_key
+                target.write(json.dumps(item, ensure_ascii=False, separators=(",", ":")))
+                target.write("\n")
+                unresolved_count += 1
+        sort_jsonl_records(
+            unique,
+            ordered,
+            fields=("order_key",),
+            max_records_per_run=self.strategy.sort_records_per_run,
+            max_bytes_per_run=self.strategy.sort_bytes_per_run,
+            temp_dir=self.workspace,
+            heartbeat=lambda: self.guard.check(
+                phase="unresolved reference sort",
+            ),
+            force_heartbeat=lambda: self.guard.check(
+                phase="unresolved reference sort",
+                force_process_tree=True,
+            ),
+        )
+
+        def body() -> Iterator[str]:
+            yield "# Unresolved semantic references"
+            yield ""
+            yield (
+                "These names were observed by the tolerant semantic index but "
+                "could not be resolved soundly in the current workspace."
+            )
+            yield ""
+            if unresolved_count:
+                for item in _iter_json_objects(ordered):
+                    yield str(item["line"])
+            else:
+                yield "- None"
+
+        self._concept_iter(
+            PurePosixPath("references/unresolved.md"),
+            concept_type="Delphi Unresolved References",
+            title="Unresolved semantic references",
+            description="References that remain unresolved in the tolerant semantic index.",
+            tags=("delphi", "references", "diagnostics"),
+            body=body(),
+        )
+        return unresolved_count
+
+    def _write_reference_index(self, raw_index: Path) -> int:
+        ordered_index = self.workspace / "resolved-index.jsonl"
+        sort_jsonl_records(
+            raw_index,
+            ordered_index,
+            key=lambda item: (
+                str(item["name_key"]),
+                str(item["source_key"]),
+                f"{int(item['start_line']):012d}",
+                f"{int(item['start_col']):012d}",
+            ),
+            max_records_per_run=self.strategy.sort_records_per_run,
+            max_bytes_per_run=self.strategy.sort_bytes_per_run,
+            temp_dir=self.workspace,
+            heartbeat=lambda: self.guard.check(
+                phase="reference index sort",
+            ),
+            force_heartbeat=lambda: self.guard.check(
+                phase="reference index sort",
+                force_process_tree=True,
+            ),
+        )
+        resolved_count = sum(1 for _item in _iter_json_objects(ordered_index))
+
+        def lines() -> Iterator[str]:
+            yield "# References"
+            yield ""
+            yield "Resolved references are embedded on their target symbol pages."
+            yield ""
+            if resolved_count:
+                for item in _iter_json_objects(ordered_index):
+                    label = f"{item['name']} ({item['count']})"
+                    yield f"- {_link(label, PurePosixPath(str(item['page'])))}"
+            else:
+                yield "- No resolved references"
+            yield ""
+            yield f"- {_link('Unresolved references', PurePosixPath('references/unresolved.md'))}"
+
+        self._write_lines(PurePosixPath("references/index.md"), lines())
+        return resolved_count
+
+    def _write_streaming_problems(self) -> None:
+        payload = layer_payload(self.index, "problems")
+        items = list(payload["items"])
+        for project in self.projects.items():
+            for problem in project["problems"]:
+                items.append(
+                    {
+                        "kind": problem["kind"],
+                        "origin": project["path"],
+                        "message": problem["message"],
+                        "file": problem["file"],
+                    }
+                )
+        page = PurePosixPath("problems/workspace.md")
+        body = ["# Workspace problems", "", f"Problems: {len(items)}", ""]
+        body.extend(
+            f"- **{_escape(str(item['kind']))}:** {_escape(str(item['message']))} "
+            f"(`{_escape_code(self._display_path(str(item.get('origin', ''))))}`)"
+            for item in items
+        )
+        if not items:
+            body.append("- None")
+        body.extend(["", "## Complete problem data", "", _json_block(items)])
+        self._concept(
+            page,
+            concept_type="Delphi Workspace Problems",
+            title="Workspace problems",
+            description="Discovery and deep-project indexing problems.",
+            tags=("delphi", "problems", "diagnostics"),
+            body=body,
+        )
+        self._directory_index(
+            PurePosixPath("problems/index.md"),
+            "Problems",
+            [("Workspace problems", page)],
+            empty="No problem report was generated.",
+        )
+
+
+def _iter_json_objects(path: Path) -> Iterator[dict[str, Any]]:
+    with path.open("r", encoding="utf-8") as stream:
+        for line_number, line in enumerate(stream, start=1):
+            if not line.strip():
+                continue
+            item = json.loads(line)
+            if not isinstance(item, dict):
+                raise WikiExportError(
+                    f"Invalid wiki work record in {path} at line {line_number}"
+                )
+            yield item
+
+
+def _scope_root(scope: Scope) -> Scope:
+    current = scope
+    while current.parent is not None:
+        current = current.parent
+    return current
+
+
+def _project_item(project: str, result: ProjectIndexResult) -> dict[str, Any]:
+    return {
+        "path": project,
+        "parsed_units": [
+            {"name": unit.name, "path": unit.path, "has_error": unit.has_error}
+            for unit in result.parsed_units
+        ],
+        "include_files": [
+            {"name": item.name, "path": item.path} for item in result.include_files
+        ],
+        "not_found_units": result.not_found_units,
+        "problems": [
+            {
+                "kind": problem.problem_type.value,
+                "file": problem.file_name,
+                "message": problem.description,
+            }
+            for problem in result.problems
+        ],
+    }
+
+
+def _symbol_identity(symbol: Symbol) -> str:
+    source_range = symbol.decl_range
+    return "|".join(
+        (
+            _normalized_source(source_range.file_name),
+            symbol.name.casefold(),
+            symbol.kind.value,
+            str(source_range.start_line),
+            str(source_range.start_col),
+            str(source_range.end_line),
+            str(source_range.end_col),
+        )
+    )
+
+
+def _symbol_page(symbol: Symbol) -> PurePosixPath:
+    return PurePosixPath("symbols") / _document_name(
+        symbol.name,
+        _symbol_identity(symbol),
+    )
+
+
+def _symbol_owner(symbol: Symbol) -> str:
+    return symbol.scope.owner.name if symbol.scope.owner is not None else symbol.scope.name
+
+
+def _normalized_source(value: str) -> str:
+    absolute = value if os.path.isabs(value) else os.path.abspath(value)
+    return _normalized_absolute_source(absolute)
+
+
+@lru_cache(maxsize=2_048)
+def _normalized_absolute_source(value: str) -> str:
+    return os.path.normcase(os.path.normpath(value)).replace("\\", "/")
+
+
+def _reference_target_key(reference: SymbolReference) -> str | None:
+    target = reference.resolved
+    if target is None or target.kind.value == "unit":
+        return None
+    return _symbol_identity(target)
+
+
+def _reference_sort_key(reference: SymbolReference) -> tuple[str, int, int, str, str]:
+    return (
+        _normalized_source(reference.ref_range.file_name),
+        reference.ref_range.start_line,
+        reference.ref_range.start_col,
+        reference.kind.value,
+        reference.name.casefold(),
+    )
+
+
+@lru_cache(maxsize=2_048)
+def _document_name(label: str, identity: str) -> str:
+    normalized = unicodedata.normalize("NFKD", label)
+    ascii_label = normalized.encode("ascii", "ignore").decode("ascii").casefold()
+    slug = re.sub(r"[^a-z0-9]+", "-", ascii_label).strip("-")[:64] or "concept"
+    digest = hashlib.sha256(identity.encode("utf-8")).hexdigest()[:16]
+    return f"{slug}-{digest}.md"
+
+
+def _link(label: str, target: PurePosixPath) -> str:
+    return f"[{_escape(label)}](/{target.as_posix()})"
+
+
+def _escape(value: str) -> str:
+    return re.sub(r"([\\`*_[\]<>])", r"\\\1", value)
+
+
+def _escape_code(value: str) -> str:
+    return value.replace("`", "\\`")
+
+
+def _bullet_code_values(values: Iterable[Any]) -> list[str]:
+    rendered = [f"- `{_escape_code(str(value))}`" for value in values]
+    return rendered or ["- None"]
+
+
+def _inline_code(values: Iterable[str]) -> str:
+    return ", ".join(f"`{_escape_code(value)}`" for value in values)
+
+
+def _json_block(value: Any) -> str:
+    return _code_block(json.dumps(value, indent=2, ensure_ascii=False, sort_keys=True), "json")
+
+
+def _code_block(value: str, language: str) -> str:
+    longest = max((len(match.group(0)) for match in re.finditer(r"`+", value)), default=0)
+    fence = "`" * max(3, longest + 1)
+    return f"{fence}{language}\n{value}\n{fence}"
+
+
+__all__ = [
+    "OKF_VERSION",
+    "WikiExportError",
+    "WikiExportResult",
+    "WikiProgressCallback",
+    "WikiProgressEvent",
+    "export_okf_wiki",
+]