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

python_delphi_lsp-3.6.0.dist-info/METADATA

@@ -0,0 +1,766 @@
+Metadata-Version: 2.4
+Name: python-delphi-lsp
+Version: 3.6.0
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Compilers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: lark>=1.1.9
+Requires-Dist: pygls>=1.3.0,<2.0
+Requires-Dist: lsprotocol>=2023.0.1
+Requires-Dist: tomli>=2.0.1 ; python_full_version < '3.11'
+Requires-Dist: watchfiles>=1.2,<2.0
+Requires-Dist: build>=1.2.0 ; extra == 'dev'
+Requires-Dist: maturin>=1.5,<2.0 ; extra == 'dev'
+Requires-Dist: twine>=5.0.0 ; extra == 'dev'
+Requires-Dist: pygls>=1.3.0,<2.0 ; extra == 'dev'
+Requires-Dist: lsprotocol>=2023.0.1 ; extra == 'dev'
+Requires-Dist: pytest>=8.0.0 ; extra == 'dev'
+Requires-Dist: pytest-timeout>=2.3.0 ; extra == 'dev'
+Requires-Dist: pygls>=1.3.0,<2.0 ; extra == 'lsp'
+Requires-Dist: lsprotocol>=2023.0.1 ; extra == 'lsp'
+Requires-Dist: pytest>=8.0.0 ; extra == 'test'
+Requires-Dist: pytest-timeout>=2.3.0 ; extra == 'test'
+Provides-Extra: dev
+Provides-Extra: lsp
+Provides-Extra: test
+License-File: LICENSE
+Summary: Python Delphi/Object Pascal parser, semantic indexer, and language server.
+Keywords: delphi,object-pascal,pascal,lsp,language-server,parser
+Author: Dark Light
+License-Expression: MPL-2.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+
+# Python Delphi LSP
+
+`python-delphi-lsp` parses Delphi/Object Pascal, builds semantic and project
+indexes, serves LSP, and provides bounded codebase navigation for agents.
+Version 3.5.0 is authored by Dark Light and supports Windows, macOS, and Linux.
+
+## Install and quick start
+
+Install into the Python environment that will run the command:
+
+```bash
+python -m pip install python-delphi-lsp
+```
+
+On Windows, use `py -m pip install python-delphi-lsp` if that is your system
+convention. On macOS and Linux, use `python3 -m pip install python-delphi-lsp`
+when `python` is unavailable. Normal installed use needs neither a checkout
+nor `PYTHONPATH`.
+
+```python
+from delphi_lsp import parse
+
+result = parse("unit Unit1; interface implementation end.", "Unit1.pas")
+print(result.root)
+```
+
+For semantic work across units, `build_workspace_semantics` returns per-file
+models and a shared symbol index. `ProjectIndexer` follows a project entry
+with explicit search paths, include paths, and defines.
+
+```python
+from delphi_lsp import ProjectIndexer, build_workspace_semantics
+
+workspace = build_workspace_semantics({
+    "Unit1.pas": "unit Unit1; interface uses Unit2; implementation end.",
+    "Unit2.pas": "unit Unit2; interface implementation end.",
+})
+print(workspace.index.lookup("Unit2"))
+
+project = ProjectIndexer(
+    search_paths=["src"], include_paths=["include"], defines=["DEBUG"]
+).index("Main.dpr")
+print(project.parsed_units)
+```
+
+Long-running discovery and indexing accept a keyword-only `on_progress`
+callback. It receives an immutable `ProgressEvent` with package-controlled
+phase, path, and monotonic counters; callback exceptions are not suppressed.
+
+```python
+from delphi_lsp import ProjectIndexer, ProgressEvent
+
+def report(event: ProgressEvent) -> None:
+    print(event.phase, event.files_completed, event.path)
+
+ProjectIndexer(on_progress=report).index("Main.dpr")
+```
+## Integrated Rust parser
+
+On Windows x64, the distribution includes the Rust-native parser in the same
+wheel:
+
+```bash
+pip install python-delphi-lsp
+DELPHI_LSP_PARSER=python …              # force the Python parser
+```
+
+The extension is an `abi3` module built with maturin and lives inside the
+`delphi_lsp` package. There is no separate native distribution or `rust` extra.
+Other operating systems and Windows on ARM receive the universal Python wheel;
+the native backend is hard-disabled there and the Python parser is used.
+Set `DELPHI_LSP_PARSER=python` to force the Python parser. Set
+`DELPHI_LSP_PARSER=rust` to force Rust and fail immediately if the compiled
+module is unavailable. The default `auto` selects Rust when the module loads,
+otherwise falls back to Python.
+
+Parity between the two parsers is tracked via
+`scripts/parser_differential.py --stage 1..5` (see
+[docs/rust-backend.md](docs/rust-backend.md) for details).
+
+## Architecture metrics
+
+The public metrics API analyzes a single unit or aggregates a complete project:
+
+```python
+from delphi_lsp import analyze_project, analyze_unit
+
+unit = analyze_unit(
+    "unit Alpha; interface implementation procedure Run; begin end; end.",
+    "Alpha.pas",
+)
+print(unit.lines.total_lines, unit.cyclomatic.maximum)
+
+project = analyze_project({
+    "Main.dpr": "program Main; uses Alpha; begin end.",
+    "Alpha.pas": "unit Alpha; interface implementation end.",
+})
+print(project.total_loc)
+```
+
+Line results distinguish total, source, blank, comment-only, mixed-comment, and
+compiler-directive lines. Project `total_loc` counts each `.dpr`, `.dpk`, and
+`.pas` source once; `include_loc` counts unique `.inc` inputs separately, and
+`total_loc_with_includes` combines both totals.
+
+Cyclomatic complexity is reported per routine and as unit/project aggregates.
+The result also includes complete Halstead counts and derived values, a
+normalized 0–100 maintainability index, symbol counts, dependency edges,
+afferent coupling (fan-in), efferent coupling (fan-out), instability,
+abstractness, and distance from the main sequence. Coupling detail separates
+internal from external dependencies. Empty or partial inputs produce finite
+JSON values; unreadable agent-workspace inputs are reported as metric problems.
+
+Run the stdio language server with `delphi-lsp`, or equivalently:
+
+```bash
+python -m delphi_lsp.lsp_server
+```
+
+## OpenCode LSP configuration
+
+The root `opencode.json` starts the installed package portably:
+
+```json
+{
+  "lsp": {
+    "delphi": {
+      "command": ["delphi-lsp"],
+      "extensions": [".pas", ".dpr", ".dpk", ".inc"],
+      "initialization": {
+        "autoDiscoverPaths": true,
+        "semanticCacheSize": 512
+      }
+    }
+  }
+}
+```
+
+`autoDiscoverPaths` is the default. It discovers compiler context without an
+environment section; LSP remains available for normal editor and OpenCode use,
+including large sources.
+
+`semanticCacheSize` limits retained per-file outline models while keeping
+source text available. Its default is 512; set it to zero to disable retained
+snapshot models. The value is preserved when workspace folders change.
+
+The LSP builds its structural index through the same optimized outline path for
+every source, with no file-size threshold. Definition, hover, references,
+rename, completion, document symbols, workspace symbols, and diagnostics remain
+registered for every file size; source-aware fallbacks keep body-level queries
+available without returning the complete file as agent context.
+
+### Automatic discovery
+
+Auto-discovery reads `.dpr`, `.dpk`, `.dproj`, `.cfg`, and `.dof` files.
+Its resolution order is:
+
+1. An explicit `.dproj`, `.dpr`, or `.dpk` selection takes precedence. An
+   explicit `.dproj` resolves its `MainSource`.
+2. Otherwise, `.dpr` and `.dpk` candidates are considered.
+3. `MainSource` in a `.dproj` contributes its entry project.
+4. A selected entry associates same-stem `.dproj`, `.cfg`, and `.dof`.
+5. Unit search paths, include paths, and defines are accumulated from explicit
+   settings, project metadata, and the associated settings files.
+6. Direct `Unit in 'path/Unit.pas'` references contribute their parent
+   directory to unit search paths.
+
+A single discovered project is selected automatically. With multiple project
+entries, a synthetic repository workspace containing every supported source is
+selected automatically while the concrete projects remain available. With no
+project entry, the same workspace model is used. Scans skip build and cache
+directories such as `build`, `dist`, environments, VCS folders, `node_modules`,
+and tool caches. Missing paths and invalid metadata become problems; paths are
+not guessed.
+
+## Agent CLI and Interface/Protocol v3
+
+`delphi-lsp-agent` has these subcommands and options:
+
+```text
+delphi-lsp-agent cache start --root PATH [--project-file FILE] [--max-memory 512M]
+                                  [--max-disk-cache 512M]
+                                  [--workers auto|N] [--startup-timeout 120]
+                                  [--idle-timeout 1800]
+delphi-lsp-agent cache status --root PATH [--format text|json]
+delphi-lsp-agent cache stop --root PATH
+delphi-lsp-agent cache clear --root PATH
+delphi-lsp-agent view --root PATH [--project-file FILE] --layer LAYER
+                      [--query TEXT] [--format markdown|json] [--deep-projects]
+                      [--workers auto|N]
+delphi-lsp-agent index --root PATH [--project-file FILE] [--out FILE]
+                       [--workers auto|N] [--deep-projects]
+delphi-lsp-agent wiki export --root PATH [--project-file FILE] [--out DIRECTORY]
+                             [--workers auto|N] [--force] [--quiet]
+delphi-lsp-agent query --root PATH ACTION [VALUE]
+                      [--project-id ID] [--detail summary|declaration|members|context|body|implementations]
+                      [--relation references|callers|callees|uses|used_by|inherits|implements]
+                      [--graph ast|cfg|dfg|call|full] [--direction out|in|both]
+                      [--depth 1..16]
+                      [--cursor TEXT] [--max-items INT] [--max-chars INT]
+delphi-lsp-agent skill install [--target PATH] [--force]
+delphi-lsp-agent opencode install [--target PATH] [--python PYTHON]
+                                  [--force] [--write-agent|--write-config]
+delphi-lsp-agent worker --root PATH [--project-file FILE] [--workers auto|N]
+```
+
+`--deep-projects` opts into per-project dependency parsing for the `projects`
+and `problems` layers. It is off by default because it dominates run time on
+real repositories:
+on a 60-project corpus it cost 36.9 s against 1.0 s for the same index, and it
+adds nothing to the unit model set. Without it the `projects` and `problems`
+layers report `deep_indexed: false`, and `index` records `deep_projects` at the
+top level of its JSON, so a shallow index is never mistaken for a complete one.
+
+The `cache` commands manage one daemon per canonical root. Use these:
+
+```bash
+delphi-lsp-agent cache start --root PATH
+delphi-lsp-agent cache status --root PATH
+delphi-lsp-agent cache stop --root PATH
+delphi-lsp-agent cache clear --root PATH
+```
+
+`cache start` outputs cache lifecycle JSON; runtime warnings are still on stderr.
+`cache status --format json` outputs status JSON to stdout and the same warning stream on stderr.
+`cache stop` outputs stop status JSON and may include warnings on stderr.
+`cache clear` stops the daemon and removes persistent navigation shards.
+`query` outputs Protocol v3 JSON responses and writes warnings to stderr.
+For `index`, a relative `--out` is resolved below `--root`; the default is
+`.delphi-lsp/agent-index/index.json`.
+
+### Open Knowledge Format wiki export
+
+Export the complete unique knowledge represented by the layered codebase views
+as a portable Markdown wiki:
+
+```bash
+delphi-lsp-agent wiki export --root PATH --out codebase-wiki
+```
+
+When `--out` is relative, it is resolved below `--root`; the default is
+`.delphi-lsp/wiki`. The command builds the semantic index once, deep-indexes
+main projects, calculates workspace and unit metrics, and writes:
+
+- an OKF 0.2 root `index.md`;
+- linked project, unit, and symbol concepts;
+- declaration and implementation source fragments;
+- resolved and unresolved semantic references;
+- discovery/project problems and complete metric records;
+- Protocol v3, relation, CPG, cache, and layer-mapping reference concepts.
+
+Without `--project-file`, the exporter selects repository main projects:
+non-example project entries in the repository root, or, when none exist, the
+shallowest configured `.dproj` entries. Recursively discovered example,
+sample, test, benchmark, and vendor projects are not promoted to project
+pages. A repository `.delphi-lsp.toml` can replace this heuristic with the
+explicit monorepo selection described below. With `--project-file`, only that
+explicit entry is selected. Project
+dependency traversal and include loading are confined to the repository root,
+so Delphi SDK and other external standard units are recorded as unresolved
+dependencies instead of being parsed. If no main project can be identified,
+the exporter falls back to the repository source inventory without inventing
+project pages.
+
+Every non-index concept is UTF-8 Markdown with YAML frontmatter and a non-empty
+`type`. Readable filenames include a stable digest, so overloads and equal names
+from different units remain distinct even on case-insensitive filesystems.
+Output order and content are deterministic. The finished bundle replaces the
+destination only after generation succeeds; an existing non-empty destination
+requires `--force`, and unsafe root/ancestor/symlink targets are rejected.
+
+Pages are streamed to disk, decoded source retention is bounded, and metrics
+process source paths without materializing the entire source corpus. Lazy CPG
+subgraphs are documented rather than eagerly multiplied across all possible
+targets; a focused live `cpg` query remains the bounded way to obtain one graph.
+The bundle structure follows the
+[Open Knowledge Format 0.2 specification](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md).
+
+Progress is shown on `stderr` while the final machine-readable JSON summary
+remains the only record on `stdout`. Redirected progress is throttled to
+milestones; pass `--quiet` to suppress it completely.
+
+```bash
+delphi-lsp-agent query --root PATH find TCustomer
+delphi-lsp-agent query --root PATH focus TARGET_ID
+delphi-lsp-agent query --root PATH inspect
+delphi-lsp-agent query --root PATH trace TARGET_ID --relation callers
+delphi-lsp-agent query --root PATH cpg TARGET_ID --graph full --direction out --depth 4
+delphi-lsp-agent query --root PATH metrics
+delphi-lsp-agent query --root PATH metrics UNIT_QUERY
+delphi-lsp-agent query --root PATH metrics --target-id UNIT_TARGET_ID
+delphi-lsp-agent cache status --root PATH --format json
+```
+
+A `target_v2_...` positional value for `metrics` is also recognized as a unit
+target ID; other positional values remain case-insensitive unit-name or path
+queries.
+
+The repository root is sufficient even when it contains many projects:
+
+```bash
+delphi-lsp-agent cache start --root PATH
+delphi-lsp-agent query --root PATH find TCustomer
+```
+
+This prewarms one bounded repository navigation index and requires no project
+selection. A `.dproj` is optional. For repeatable monorepo selection, add a
+`.delphi-lsp.toml` file as described below. Pass one project explicitly when
+its project-specific compiler
+settings and `MainSource` should define the index:
+
+```bash
+delphi-lsp-agent cache start --root PATH --project-file relative/path/Main.dproj
+```
+
+An explicit `.dpr` or `.dpk` remains supported. To switch an already running
+repository cache to one of its concrete project views, list the projects and
+focus one by its returned `project_id`:
+
+```bash
+delphi-lsp-agent query --root PATH open
+delphi-lsp-agent query --root PATH focus --project-id PROJECT_ID
+```
+
+Selecting a project this way also prewarms its navigation cache.
+
+### TOML project selection for monorepos
+
+Place `.delphi-lsp.toml` in the repository root to define which `.dpr`,
+`.dpk`, or companion `.dproj` projects belong to the codebase:
+
+```toml
+[projects]
+include = [
+  "apps/**",
+  "services/Api/ApiServer.dproj",
+  "packages/*/Runtime.dpk",
+]
+exclude = [
+  "**/examples/**",
+  "**/tests/**",
+]
+
+[workspace]
+exclude = [
+  "vendor",
+  "generated/**",
+  "thirdparty/legacy",
+]
+```
+
+Paths are relative to the repository root, case-insensitive, and use `/` on
+every operating system. An exact directory name covers all descendants. `*`
+matches within one path segment, while `**` crosses directory boundaries.
+Absolute paths and `..` traversal are rejected.
+
+When `include` is non-empty, only matching project entries remain. Matching a
+`.dproj` selects the `.dpr` or `.dpk` from its `MainSource`. The `exclude`
+list is applied afterward, so `exclude` always wins. With active TOML filters,
+all remaining matches are main projects even when they occur at different
+directory depths; the built-in shallow-project and example-name heuristic is
+not applied.
+
+Use `projects.exclude` when a directory may still contain shared units but its
+project entries must not become selectable projects. Use `workspace.exclude`
+for a hard boundary. Matching directories are never traversed or parsed, and
+neither is any file below them. They cannot be reintroduced by
+`projects.include` or an explicit `--project-file`. Unit dependencies and
+include directives resolving into those directories are reported as
+unavailable without reading the files.
+For complete directory pruning, an exact entry such as `"vendor"` is enough;
+`"generated/**"` also excludes the `generated` directory itself.
+
+The same selection is used by `cache`, `worker`, `query`, `view`, `index`,
+wiki export, and language-server discovery. An explicit `--project-file`
+bypasses `projects.include` and `projects.exclude` for that invocation, but
+never bypasses `workspace.exclude`. If no project remains, the command reports
+that the configured filters matched no Delphi projects and stops instead of
+silently parsing every source file in the repository. Restart an already
+running cache daemon after changing the path configuration.
+
+`inspect` uses the currently focused target, so call `focus TARGET_ID` before
+`inspect` unless a previous request already selected it.
+
+The cache daemon prewarms the navigation cache at startup so first `find` requests are
+fast. The cache retained-cache budget is `512 MiB` by default and tracks retained
+cache usage only, not a hard RSS/parse peak. Warnings are emitted on stderr at or
+above 80 percent.
+
+Cold builds parse independent source units in short-lived processes created with
+the cross-platform `spawn` method. `--workers auto|N` defaults to `auto`.
+Automatic selection uses at most eight worker processes, leaves one detected CPU
+free, never exceeds the source task count, and—for the cache daemon—allows one
+worker per `64 MiB` of retained-cache budget. `view` and `index` use the same
+task, CPU, and eight-worker caps without the cache-budget term. An explicit value
+from 1 through 32 overrides the automatic CPU and memory caps but is still
+limited by the number of tasks.
+
+Standalone `view` and `index` commands cache their exact completed response
+bytes under `.delphi-lsp/response-cache`. A strong content revision covers the
+selected source, include, project, and configuration files, so any relevant
+content change produces a miss. Records are content-addressed, owner-only,
+atomically replaced, size-bounded, and never use pickle. Batch commands bypass
+the older per-unit artifact shards; an unchanged request can therefore return
+the validated response without rebuilding semantic models. To reproduce the
+large-corpus cold/warm gate, run:
+
+```bash
+python scripts/benchmark_response_cache.py \
+  --fpc-root /path/to/fpc-corpus \
+  --delphi-root /path/to/delphi-corpus
+```
+
+Worker processes build compact, detached navigation shards and exit before
+retained-cache accounting. Full semantic object graphs and source text are not
+retained in the parent. Tokenized source documents are loaded only for source
+evidence requests such as `inspect`, and a byte-bounded LRU evicts older
+documents. The transient worker memory remains separate from retained navigation
+structures and the existing 80-percent warning. Retained bytes are maintained
+incrementally; requests never traverse the complete cache object graph merely
+to measure it. If an automatic pool fails before accepting a result, one
+automatic serial fallback is attempted; explicit worker counts fail instead of
+silently changing the requested configuration.
+
+Detached navigation shards are also stored as versioned, content-addressed JSON
+under `.delphi-lsp/agent-cache/navigation-v1`. A restarted CLI or OpenCode cache
+daemon reuses unchanged units without parsing them again. Source content,
+conditional defines, or a shard-schema change produces a cache miss; malformed
+or incompatible JSON is ignored and rebuilt. The disk cache contains no pickle
+payloads and does not count against the retained-RAM budget. Each completed
+navigation build removes superseded shards and enforces the
+`--max-disk-cache` byte budget, which defaults to 512 MiB.
+
+Cache prewarming builds the navigation registry directly without constructing
+an empty-query result, symbol cards, pagination, or JSON payloads. Up to sixteen
+recent ranked queries are retained in a small LRU so alternating CLI and
+OpenCode searches remain warm.
+
+`cache start` waits up to `--startup-timeout 120` seconds for the child process
+to bind and publish readiness metadata, not for the large workspace to finish
+prewarming. Workspace discovery and prewarming continue in the daemon while
+status reports `warming`. If bootstrap fails, the CLI reports whether it timed
+out or exited, the exit code, Python executable, workspace, and a sanitized
+tail of child stderr. Starting a live root with a different worker
+configuration reports a configuration conflict.
+
+Eviction is ordered: auxiliary caches are evicted first, navigation caches second.
+If compaction removes navigable data, the daemon rebuilds the navigation state on demand
+while preserving focus state for the next request.
+
+The daemon tracks a 30-minute idle timeout; idle state shows in JSON status (`cache status`).
+`source revision` changes on source edits and invalidate reused request caches.
+Workspace state appears in status as `requests`, `warm_hits`, `rebuilds`, `invalidations`,
+`evictions`, and `cache_state`. Parallel prewarm status adds
+`workers_configured`, `workers_effective`, `parallel_files_completed`,
+`prewarm_seconds`, `parallel_seconds`, `parallel_fallbacks`,
+`navigation_disk_hits`, and `navigation_disk_misses`.
+
+Metadata is stored in `.delphi-lsp/agent-cache/daemon.json` with owner-only token and
+permissions (`daemon.json` mode 600 and parent 700). Do not copy or share this token
+outside the root workspace.
+
+`view --layer` accepts `overview`, `projects`, `units`, `unit`,
+`symbols`, `symbol`, `implementation`, `references`, `problems`, and
+`metrics`. For example, `delphi-lsp-agent view --layer metrics --format json`
+returns a project summary and detailed unit metric objects; `--query` filters
+units by name or path.
+`index` materializes overview, projects, and problems JSON. `wiki export`
+materializes the same navigational knowledge as a linked OKF Markdown bundle. `skill install`
+writes the skill; `opencode install` writes the package-named skill, Markdown
+agent, and plugin. The two deprecated write flags are harmless aliases and do
+not change user configuration.
+`worker` serves NDJSON over standard input/output.
+
+Protocol v3 actions are `open`, `find`, `inspect`, `trace`, `focus`,
+`problems`, `metrics`, and `cpg`. A `metrics` request without a query returns the
+project summary followed by unit cards. A query filters units, while a unit
+`target_id` from `open` selects one unit; `detail: "members"` adds routine,
+Halstead, dependency, and symbol-count detail without returning source text.
+Detail values are `summary`, `declaration`, `members`,
+`context`, `body`, and `implementations`. Relations are `references`,
+`callers`, `callees`, `uses`, `used_by`, `inherits`, and
+`implements`.
+
+A request requires `action` and can include `query`, `target_id`,
+`project_id`, `detail`, `relation`, `graph`, `direction`, `depth`, `cursor`,
+`max_items`, and `max_chars`. Defaults are empty text fields,
+`detail: "summary"`, no relation, `graph: "full"`, `direction: "out"`,
+`depth: 4`, `max_items: 12`, and `max_chars: 12000`. Depth is 1–16;
+response ranges are 1–50 items and 256–40000 characters. A successful envelope
+has `schema: 3`,
+`workspace_revision`, `focus` (project, unit, and target IDs), `result`,
+`page`, and `context`; errors have `schema: 3` and a code/message. Existing
+target IDs remain unchanged across the protocol upgrade.
+
+Focus preserves the selected project, unit, or target. Cursors bind a workspace
+revision and request fingerprint, so source changes and cross-target or
+cross-detail reuse invalidate them. `max_items` and `max_chars` bound each
+response. A `sound_partial` relation is sound but incomplete: unresolved and
+ambiguous relations are never fabricated. Unsupported relations are rejected.
+
+### Lazy code property graph
+
+The `cpg` action translates one selected unit, type, or routine into a bounded
+code property graph. Graph selectors are `ast`, `cfg`, `dfg`, `call`, and `full`;
+`direction` accepts `out`, `in`, or `both`, and `depth` limits traversal
+from the selected target. Together, `graph`, `direction`, and `depth` select
+the returned subgraph. Results contain stable CPG node and edge IDs,
+location and symbol properties, graph metadata, and explicit problems.
+
+AST edges preserve syntax containment. CFG edges include routine entry/exit,
+sequence, conditional branches, loop back-edges, and conservative structured
+control flow. Local DFG edges distinguish definitions, uses, and reaching
+definitions. CALL edges are emitted only for a uniquely resolved explicit
+callee. Ambiguous or unsupported semantics increase the unresolved count and
+are reported as `sound_partial`; the navigator does not fabricate certainty.
+
+CPG construction is lazy: navigation prewarming creates no graph. The first
+request parses only the selected source, and identical requests reuse an
+in-memory LRU keyed by workspace revision, target, `graph`, `direction`, and
+`depth`. The CPG LRU receives 20 percent of the configured retained-cache
+budget, capped at 128 MiB. Source text and full parser trees are not retained
+inside graph records, and normal navigation keeps its existing cache path.
+
+The release gate used the pinned 8,549-file FPC corpus with 4,021,192 physical
+lines on an Apple-silicon Mac with Python 3.14 and eight workers. Navigation
+prewarming took 22.62 seconds. The first focused CPG query took 0.0166 seconds;
+the cached query took 0.000069 seconds and retained 4,007 bytes. Exactly one
+source was parsed for CPG. Legacy navigation retained 98.43 percent of its
+in-run control throughput, above the 95-percent release floor. Reproduce it
+with `python scripts/benchmark_cpg.py --root CORPUS --query Run --workers 8`.
+
+Separate reproducible performance profiles cover the coherent FPC compiler
+tree and a project-file-dense Delphi corpus. The Delphi profile can add a
+deterministic `__history`/recovery/build/search-path overlay without changing
+the pinned base corpus. See [the FPC benchmark](docs/performance-fpc.md) and
+[the Delphi discovery benchmark](docs/performance-delphi.md).
+
+For every source size the navigator builds an outline first, loads source detail
+lazily for a selected target, and returns only selected fragments. Typed source
+chunks are at most 6000 characters and also respect the response budget. This
+optimization does not remove LSP functionality.
+
+## OpenCode semantic navigator
+
+Install the generated integration in a worktree:
+
+```bash
+delphi-lsp-agent opencode install --target .
+```
+
+It writes:
+
+```text
+.agents/skills/python-delphi-lsp/SKILL.md
+.opencode/plugins/delphi_codebase.ts
+.opencode/agents/python-delphi-lsp.md
+```
+
+The package-named Markdown agent enables only the
+`python-delphi-lsp` skill and `delphi_codebase`. It denies
+`bash`, `read`, `glob`, `grep`, and `lsp`, along with edit/write and
+other raw source tools. The skill is enabled. The installer does not use the
+retired `.opencode/tools` path and never reads or changes `opencode.json`; that
+file remains entirely user-owned. The deprecated `--write-config` and
+`--write-agent` options are accepted harmlessly for compatibility.
+
+The plugin maintains one worker per session/root, reusing focus, indexes, and
+lazy CPG subgraphs.
+During compaction it restores the focus and summary into the new context.
+Transport failure, session deletion, and plugin disposal clean up the worker.
+
+OpenCode history: 1.1.0 and 1.1.1 used a spawned view per call model.
+Persistent session/root worker support first shipped in 2.0.0.
+This is the same persistent session/root worker boundary.
+The OpenCode worker stays separate from CLI daemon. Protocol v3 adds CPG
+arguments without changing the persistent session/root boundary.
+
+A generated OpenCode agent starts with this Markdown frontmatter:
+
+```markdown
+---
+description: Inspect Delphi and Object Pascal codebases through python-delphi-lsp.
+mode: all
+temperature: 0
+permission:
+  delphi_codebase: allow
+  skill:
+    "*": deny
+    python-delphi-lsp: allow
+  lsp: deny
+  bash: deny
+  read: deny
+  glob: deny
+  grep: deny
+  list: deny
+  edit: deny
+  write: deny
+  patch: deny
+  task: deny
+  webfetch: deny
+  websearch: deny
+  question: deny
+  todowrite: deny
+  todoread: deny
+  codebase_map: deny
+  code_guidelines: deny
+---
+```
+
+Select `python-delphi-lsp`, ask it to load the `python-delphi-lsp` skill, then
+use `delphi_codebase` actions such as
+`open`, `find`, `focus`, `inspect`, and `cpg`. Use semantic tool calls, not raw
+source tools.
+
+For architecture questions, call `metrics` without a query to compare unit
+cards and read project LOC. Then select a returned unit ID with another
+`metrics` call and `detail: "members"` to inspect its routines and coupling.
+
+For the root LSP configuration, a local model can be used as follows:
+
+```bash
+opencode run --dir . --model ollama/ornith-lspctx --agent vllm-lsp \
+  "Find the declaration of a Delphi symbol through LSP."
+```
+
+Use `--agent vllm-lsp-edit` only for the separate, focused LSP/edit
+verification workflow; the semantic navigator agent above remains restricted
+to its named skill and tool.
+
+That separate verification uses `vllm/ornith-lspctx` and accepts the focused
+LSP result `edit:Edit applied successfully`; it is not the semantic navigator
+workflow and does not grant the navigator any raw source tools.
+
+## Reproducible large-project vLLM proof
+
+The proof generates a 117,511-line project. The verifier requires `skill`, `open` (`Main.dpr` evidence), `find`, `focus`, and `inspect`,
+checks `MegaProc02500` and `Value := Value + 40`, and forbids raw `bash`,
+`read`, `glob`, and `grep`. It then waits for the final answer and requires the
+exact body range `src/Mega100kUnit.pas:117464-117509` and the inspected
+statement in that answer. The prompt requires returned range metadata instead
+of a model-calculated line inside the source fragment.
+The proof uses the local Ornith vLLM OpenAI-compatible
+endpoint at `http://127.0.0.1:8001/v1`.
+
+Default scripts are offline and must not redownload the model. First check the
+cache:
+
+```bash
+python scripts/check_ornith_cache.py --require-complete
+```
+
+With an already-running endpoint on any supported platform, run:
+
+```bash
+python scripts/bootstrap_vllm_codebase_skill_test.py --use-running-server
+```
+
+On macOS, the offline cached auto-start path is:
+
+```bash
+python scripts/bootstrap_vllm_codebase_skill_test.py --start-vllm
+```
+
+Automatic local vLLM startup is macOS-only. The package and OpenCode plugin are
+supported on Windows. On Windows, start an OpenAI-compatible vLLM endpoint, then
+run the Python bootstrap from PowerShell:
+
+```powershell
+python .\scripts\bootstrap_vllm_codebase_skill_test.py --use-running-server
+```
+
+For an endpoint at another URL, add `--base-url`:
+
+```powershell
+python .\scripts\bootstrap_vllm_codebase_skill_test.py --use-running-server --base-url http://127.0.0.1:9000/v1
+```
+
+`--skip-install` is an optional acceleration for an already prepared `.venv`;
+omit it on a clean checkout so the bootstrap installs `.[dev]`.
+The final-answer verifier defaults to a 420-second probe timeout. On a slower
+local model server, increase it explicitly with `--probe-timeout SECONDS`.
+
+The bundled automatic helper is not a cross-platform startup mechanism.
+
+The architecture-metrics proof uses a separate deterministic 34-LOC project.
+It requires the restricted model to load the skill, call `metrics` for the
+project and most-complex unit, and report exact LOC, cyclomatic maximum, and
+instability values. Raw source, search, shell, and write tools remain forbidden:
+
+```bash
+python scripts/bootstrap_vllm_codebase_skill_test.py --probe metrics --use-running-server
+```
+
+Use `--probe metrics --start-vllm --max-model-len 24576` for the cached macOS
+auto-start path when no endpoint is already running.
+
+## Migration to 2.0
+
+`delphi_lsp` is the only supported import namespace. Update imports directly;
+there is no compatibility import alias.
+
+## Verification and limitations
+
+For a checkout:
+
+```bash
+python -m pip install -e ".[dev]"
+python -m pytest
+python -m build
+python -m twine check dist/*
+```
+
+CI tests Ubuntu, macOS, and Windows on Python 3.10 and 3.14, then builds and
+smoke-installs the wheel on Ubuntu/Python 3.14. Results depend on available
+project files, defines, includes, and paths; unsupported compiler behavior and
+unresolvable references are reported as problems. The vLLM proof additionally
+requires OpenCode, a local endpoint, and a complete local cache.
+
+## License
+
+Mozilla Public License 2.0. See [LICENSE](LICENSE).
+