MIGRATION.md

Migrate from Graphify to Compass

Compass uses its own executable, output directory, environment variable, and sidecars. Its output root now preserves the familiar flat artifact shape so file-based workflows can transition while Compass's snapshot and store layout remains visible and clearly owned.

Rebuild artifacts produced before Compass 0.3.23

Current query loaders reject pre-0.3.23 Compass release artifacts before loading their node/edge records. The error reports the found and minimum versions and, when validated snapshot provenance exists, the exact recovery command:

compass update "<source-root>" --force

Use the actual project source directory, not compass-out. If source-root.txt is absent, invalid, or names a directory no longer present, explicitly supply the source project's current root. Forced update bypasses reuse of the prior graph and republishes from source using the configured storage mode. Do not edit builderVersion, copy indexes between generations, or migrate old artifacts in place. Immutable historical realizations are not rewritten by this recovery.

Enable embedded SurrealDB

To use a standalone server as well, install with --features surreal-surrealkv,surreal-remote. Configure a dedicated namespace and database through --surreal-config connection.yaml, environment settings, or flags, then run compass update . --store surreal --surreal-engine remote. The server is contacted over its API; never point --surreal-path at a running server's storage files. Existing embedded references need no migration. See the Surreal guide for exact YAML and environment names, precedence, credentials, and cross-engine portable restore.

SurrealDB remains an opt-in compile feature. Reinstall a SurrealKV-enabled CLI, then republish the active project:

cargo install --locked --path crates/compass-cli --bin compass \
  --features surreal-surrealkv --force
compass update . --force --store surreal --surreal-engine surrealkv
compass store validate compass-out --engine surreal --format json

Building a SurrealDB-enabled binary on Windows

Native Windows is supported without WSL, but building with any SurrealDB feature needs a C toolchain. surrealdb-core enables jsonwebtoken/aws-lc-rs unconditionally, so aws-lc-sys is compiled for every SurrealDB feature — including surreal-remote — and requires CMake and NASM on x86_64-pc-windows-msvc, plus the Visual Studio C++ build tools:

choco install cmake nasm --no-progress -y

This is a SurrealDB upstream requirement, not a Compass one. The default build has no such dependency: SurrealDB is absent from its dependency tree entirely, so a feature-free compass binary builds on Windows with only the Rust toolchain.

Ship surreal-surrealkv rather than surreal-rocksdb on Windows. SurrealKV is pure Rust, whereas RocksDB adds a C++ build through surrealdb-librocksdb-sys. RocksDB remains available from source.

Project configuration version 2 persists the storage selection. Version-1 configuration files still load with their previous behavior; run compass init --force --store surreal only when you intentionally want to rewrite the saved configuration. SQLite and JSON artifacts are not migrated in place. Compass stages a new immutable Surreal generation from the canonical graph and writes compass.surreal.ref/1 only after validation. Explicit Surreal queries fail closed until that reference is present and valid.

The fully wired projection is compass.graph.surreal/2. Existing library-only compass.graph.surreal/1 generations are not migrated in place; rerun the forced update above to create a new typed/indexed generation.

Graph rebuilds and query resolution

To enable full bounded document/prose recall, rebuild with compass extract <root> --force. Document/rationale resources now carry optional details.data.content (up to 4 KiB), and strict query consumers must admit optional conceptMatches and its closed match-method enum. AST cache v15 and JSON query-index format v2 invalidate older disposable entries automatically. Rebuild existing SQLite sidecars from the new graph to get prose postings; historical realizations retain their original content and indexes. Default concept recall needs no credentials; corpus-LSA search remains explicit opt-in.

Rebuild Python graphs with compass extract <root> --code-only --force to obtain receiver-chain resolution and source-call inventories. AST cache version 14 recomputes older entries automatically. Add --inference-level max to retain inferred deferred receiver edges; the source inventory remains available at low inference. Older/historical graphs remain readable but unresolved-call coverage is explicitly unavailable until a new graph is built. Strict machine consumers must admit optional details.callSites, callSummary, and impactSummary. Impact's broader default may return more dependents; use repeatable compass impact <symbol> --relation calls (or MCP relations) for a narrower policy. Counts distinguish incoming dependents from outgoing review context.

Disposable graph query/impact/traversal and typed content caches are rebuilt automatically when read by this version. No source graph rebuild or historical rewrite is needed for cache freshness. An in-flight MCP request retains its loaded graph snapshot; subsequent requests read the current content and reject missing or corrupt replacements.

Rebuild Java graphs to resolve imported nested nominal receiver names for field and enum references. The resolver now joins dotted source type names to canonical nested declarations, retaining duplicate-owner ambiguity. This correction reuses version-10 AST facts; it does not change schemas or rewrite historical graphs.

Rebuild Java graphs to receive source-proven field and enum-constant references, including supported enum switch labels and constant-specific body ownership. AST cache semantics version 10 automatically invalidates earlier extraction facts. Existing stored/historical graphs are not rewritten; unsupported receivers and inherited/anonymous/local-class cases remain gaps. These references do not classify read/write effects or establish class cohesion or god-object defects.

Rebuild Rust graphs to receive newly emitted field-access references. AST cache semantics version 8 invalidates earlier facts automatically; stored graphs and historical realizations are not rewritten. The added member-access references preserve source occurrences but do not classify reads/writes or prove cohesion.

MCP neighbor responses now include exact destination records in structuredContent.result with schema compass.query.neighbors/1. Consumers that need machine identities should read those records instead of parsing text labels. The text adds identity/source lines and orders groups deterministically. If a large neighbor request exceeds the new adjacency, record or 1 MiB semantic response limit, it fails explicitly; narrow relation_filter or use the bounded typed caller/callee queries. An empty successful result means no matching records. No graph rebuild is required for this output change.

Rebuild Java graphs to receive corrected varargs signatures, array argument types, and overload targets. Spread parameters now retain their declared array type; calls may gain targets or select a different, source-supported overload. Normal builds discard AST cache versions older than 6. Existing historical graphs and the graph schema remain unchanged.

Name-based queries can now resolve a coincident export binding to its proven declaration. Use the exact export node ID when you want the binding record. This query correction works on existing graphs. Older traversal caches rebuild automatically to retain mixed-confidence and deferred relationship evidence; graph re-extraction is not required for that cache correction.

Rebuild Java graphs to receive the constructor-receiver correction. Direct constructor method calls can gain source-proven targets; invented external targets and unrelated imported-class construction edges can disappear. Normal builds discard AST cache versions older than 5. This does not rewrite historical graphs or change the graph schema.

Rebuild graphs with programmatic framework routes to remove filesystem-derived containment between independent routers and unsupported file-route parents. Framework-pack semantics version 8 invalidates prior build profiles and build-state seals; disposable framework facts can be rebuilt from source. Hub rankings, navigation paths, and communities can change. Existing historical realizations remain unchanged.

Version 8 corrects the directory-order parent rule introduced before version 7. File-route siblings, standalone endpoints, and page files without a layout parent may lose containment edges. Source-proven nested layouts and flat-route parents can gain the correct edges. The graph schema is unchanged.

Rebuild existing Go graphs to receive the control-initializer and receiver shadowing corrections. Normal builds automatically discard AST cache versions older than 4. Source-proven calls can appear and incorrectly attributed calls can disappear; existing historical realizations are not rewritten.

For MCP shortest_path, replace partial keywords with exact IDs or complete symbol/qualified names. Handle ambiguity candidates before retrying. Use structuredContent.result (compass.mcp.path/1) for ordered identities and statuses. depth_limit and work-limit errors are incomplete searches, not proof of disconnection. max_hops is limited to 0–64. Equal-hop routes may change because structural relation cost now breaks ties; the operation remains undirected navigation.

MCP callers of get_neighbors must handle an Ambiguous candidate list and retry with a returned exact node ID. Earlier versions silently chose one match. Labeled community IDs are restored by automatic traversal-cache rebuilding; existing graph files can be queried directly.

ask agent output now records parsed operands in request.operands and the original question in request.question. Consumers needing the question should read that dedicated field. If an existing text cursor fails its prefix check after the corrected subject ordering, reissue the question to start a new page.

Plain compass query output is now concise by default and its page budget is 8,000 approximate tokens. Scripts or review workflows that need the previous expanded provenance should pass --evidence. Existing compass.query.discovery-text-page/1 cursors cannot be resumed; start the query again to receive a /2 cursor, and keep the concise/evidence tier unchanged while paging. Discovery JSON remains compass.query.discovery/1.

Natural structural queries now mark every fuzzy execution or suggestion with NO EXACT MATCH/the typed no_match diagnostic. Handle that signal and retry with a suggested exact ID when exact identity is required. compass path no longer promotes a fuzzy symbol candidate into an endpoint; it is weighted toward structural relations, defaults to an eight-hop bound, and reports NO PATH FOUND separately when both endpoints exist but are unreachable within the requested hop bound. Consumers that parsed the prior human path prose should migrate to these explicit signals; machine-query schema versions are unchanged.

path now fails with a nonzero work-limit error if either its weighted or alternative search exceeds 1,000,000 adjacency entries or 16 MiB of cumulative path-key bytes. Treat this as an incomplete search, not proof of disconnection; reduce --max-depth or query a smaller graph before retrying.

Typed relationship commands now share source-backed import/reference resolution. callers, impact, and typed affected may therefore return additional importer evidence and can emit a relationship_inconsistency diagnostic when their bounded traversal disagrees with the importer probe. Treat that diagnostic as incomplete coverage rather than an empty answer. The default typed search candidate limit is now 64; count-shaped automation should inspect the structured truncated flag and diagnostics.

ask, search, query, callers, callees, impact, path, and explain accept the shared --format text|json|agent-json contract where applicable. Use compass architecture --format agent-json for a bounded repository overview with omission counts and witness IDs.

Rebuild cached AST facts after receiver corrections

AST cache semantics version 3 invalidates older cached extractions, including Rust calls incorrectly attributed to an outer variable shadowed by a local binding. The next extraction rebuilds these facts automatically and can take longer. Re-extract existing graphs to receive the correction; historical realizations remain immutable. No source or configuration migration is needed.

Rebuild SQLite adjacency sidecars

Store snapshots now declare edge-ID-ordered directional adjacency so bounded JSON and SQLite queries retain the same canonical edge prefix. Existing graph.json artifacts remain compatible. A SQLite sidecar created before this capability can still be validated, backed up, and used to recover canonical JSON, but directional store queries reject it with edge_id_ordered_adjacency_unavailable.

Preserve graph.json, then rebuild the disposable sidecar with:

compass update --force --store sqlite
compass store validate compass-out --format json

Use --engine json until the rebuild completes. Do not edit or copy SQLite tables to add the capability marker; the directional index key order must be rebuilt from the validated graph.

Rebuild communities for the Leiden profile

Typed clustered graphs now use seeded-leiden-modularity/v1 over typed-evidence-undirected/v1 with the fixed-resolution selector. Run a normal forced build after upgrading:

compass update --force

Community membership, numeric IDs, labels, architecture groupings, and derived reports may change. Do not copy old community attributes or label signatures into the new graph. Base Graph node and relationship identity, direction, multiplicity, anchors, and provenance are unchanged by clustering.

Omitting --resolution uses fixed resolution 1; an explicit --resolution N uses exactly one positive finite value. Automatic multi-resolution selection is not a production default. Clustered typed builds add community-quality.json, bound to the exact graph.json. Upgrade strict artifact readers to accept compass.community-quality/1 and reject unknown majors, unknown fields, digest mismatch, or profile mismatch. Missing evidence on an older or legacy graph means unavailable, not zero quality.

Published historical realizations remain immutable. New materializations use the complete Leiden profile fingerprint; Compass does not rewrite or silently reinterpret older memberships.

Frontend graph vocabulary

Recent pre-release builds can add React-oriented renders edges and UI/server roles to compass.graph/1. Consumers with strict enum validation must upgrade their graph reader before opening a graph produced by a frontend-enabled build; the old reader must reject the new values rather than treating them as unknown calls or silently omitting them. Rebuild cached graph and query artifacts after upgrading so the frontend extraction semantics and framework pack digest are applied consistently. The matching compass.query/1 manifest and fingerprint must be deployed with the reader as well.

Framework task context

Frontend-enabled builds emit compass.task-context/2 (the previous compass.task-context/1 packet is intentionally rejected). Upgrade CLI, MCP, and agent readers together, then rebuild cached context artifacts. The new typed framework section carries pack/version and qualification state, route stages, render direction, runtime boundaries, configuration dependencies, and explicit ambiguity or truncation; unknown pack IDs and qualification states must fail closed.

Route-stage readers must also add the dependency and security variants to their closed enum. Update the compass.query/1 manifest fingerprint and viewer assets with the reader. Do not map these stages to middleware: middlewareCount continues to count HTTP middleware only. An older strict reader should reject a packet containing either new value, then be upgraded; cached graph, query, or task-context packets may be rebuilt after deployment.

Python framework readers must replace the combined python-web pack ID with django-python, django-rest-framework-python, fastapi-python, flask-python, pydantic-python, sqlalchemy-python, celery-python, and starlette-python. django-python, fastapi-python, and flask-python are now semantics version 2, and the framework-pack cache identity is compass.framework-packs/6, so run a fresh or forced build after upgrading. A Flask @app.route without a methods argument now records the declared GET operation instead of ANY. Exact Django URL calls and Python receiver mount identities can also remove older name-shaped false positives; unresolved ambiguous or dynamic registrations are intentionally not restored through a legacy fallback.

Python SQLAlchemy and Celery facts no longer come from enterprise-domain-facts. Exact SQLAlchemy 2 declarations, mapped fields, relationships, and literal table mappings are owned by sqlalchemy-python; exact Celery task decorators, task invocations, canvas signatures, literal queues, retries, and beat schedules are owned by celery-python. Dynamic or ambiguous forms now remain unresolved instead of retaining regex-derived facts. Non-Python enterprise-domain-facts behavior is unchanged.

FastAPI Depends values previously exposed as legacy middleware references now use the additive dependency route stage; Security uses the distinct security stage. Consumers must retain these values rather than coercing them to HTTP middleware. Pydantic schema dependencies reuse depends_on and existing class/field nodes, so no new public node or edge kind is introduced. DRF router routes likewise reuse routes_to; serializer, security, model, field-relationship, manager, and signal-sender wiring use the existing depends_on and subscribes relationships. Strict framework-context readers must accept django-rest-framework-python. No settings, middleware, or admin registration edge is synthesized: the current descriptor vocabulary cannot advertise those registrations without incorrectly claiming bean-container semantics.

Rust receiver and macro evidence rebuild

Rust universal evidence now uses producer version 2. The first graph build after upgrading re-extracts cached Rust files automatically. No graph schema migration or manual artifact editing is required. The new producer follows source-proven Arc, Rc, and Box field chains and recovers calls from a bounded local macro_rules! shape only when the captured expression or statement is proven to be evaluated; ambiguous cases remain unresolved.

Ruby universal evidence rebuild

The current release publishes Ruby through the version-1 universal evidence pipeline (compass.ruby) and the evidence-backed rails-ruby framework pack. Ruby graph output is therefore regenerated on the first build after upgrading; do not reuse a Ruby cache produced by an older Compass publisher. Ruby is Qualified for the bounded producer capabilities recorded in the release decision; retain review of ambiguous/dynamic Ruby relationships and do not treat unresolved dynamic dispatch as a missing deterministic fact.

All 14 registered universal evidence pipelines are now marked Qualified. The release decision at tests/qualification/universal-evidence-promotion.json binds each producer ID, language, version, and dialect alias to that state. Changing a producer version or advertised capability requires a new decision; existing cached evidence is regenerated when its pipeline identity changes.

Universal evidence schema reset

The universal evidence envelope is now compass.languages.evidence/2 and the extraction semantics identity is compass.languages.extraction/4. The envelope field is pipeline (with qualification and emitter metadata), replacing the provisional adapter/profile/producer shape. Compass intentionally does not translate or reuse pre-refactor universal evidence; run a forced update to regenerate one coherent artifact set. Qualification manifests, candidate exports, and TypeScript scorecards likewise require their /2 schemas and use producer for the language evidence identity; regenerate those audit inputs rather than trying to load the old field names.

Version 4 also invalidates pre-enhancement Markdown caches so nested frontmatter can be republished as exact graph-v1 config nodes. Normal builds re-extract affected files automatically; no graph schema migration or manual artifact editing is required.

Python project identity and stubs

Python now publishes version-1 compass.python evidence. Static pyproject.toml import roots can remove repository-layout prefixes such as src. from qualified names, and top-level Python graph IDs are derived from the proven module identity instead of the checkout path. .pyi files now use the Python pipeline: a matching .py file remains the declaration owner, stub-only declarations carry source_kind: "stub", and mismatches publish a python_stub_source_conflict diagnostic without merging guessed facts. The current producer also fills existing universal parameter, call-shape, type_of, returns, and call-result fields for the bounded static subset. Dynamic, starred, shadowed, Any, and conflicting-return cases remain unresolved.

Run a fresh or forced build after upgrading. Project evidence schema compass.framework-project-evidence/4 and Python producer version 1 invalidate the affected cache entries automatically. Published historical realizations remain immutable; rebuild a historical revision explicitly if it must use the new identities.

Architecture viewer contract

compass export callflow-json now emits compass.viewer.architecture/1, replacing compass.viewer.callflow/1. Update direct consumers as follows:

• negotiate contracts.architecture_viewer instead of callflow_viewer;
• read relationships and relationClass instead of treating every edge as a call;
• select projections[].scope (production or all_code) and join memberships, groups, and routes rather than reading flat sections;
• resolve each membership's nodeIndex against top-level nodes and groupIndex against that projection's groups array;
• use overviewGroupIds, overviewRouteIds, and omissions instead of an Other overflow section; and
• surface quality independently from extraction status.

Production excludes Documentation as well as Test, Generated, Vendor, and Unknown. Select All-code when documentation architecture is intentionally in scope.

The old major is rejected rather than silently translated. The CLI command names remain compatible. Rename project section files to a versioned compass.architecture-overlay/1 JSON/TOML overlay and pass --architecture-overlay PATH; --sections is temporarily retained as a deprecated adapter.

Install Compass

Install the latest macOS release:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/crabbuild/compass/releases/latest/download/install.sh | sh

The release contains only the compass executable. It doesn't install graphify or graphify-mcp compatibility entry points.

Rebuild project output

Compass doesn't read graphify-out/ or GRAPHIFY_OUT. Keep the old directory for rollback and run a new build to create compass-out/:

cd your_project_directory
compass update .

Set COMPASS_OUT before running Compass when you need a custom output directory.

Standalone compass.graph/1 files used by MCP clients must carry non-empty graph.build.sourceTreeDigest and graph.build.generationId values. Regenerate older or hand-authored files with compass update instead of substituting placeholder-empty identities.

Regenerate portable agent bundles

Portable bundles exported before the native distribution inventory do not carry the recorded harness version or the complete harness-native manifests. They also used legacy mcp/ configuration paths. The current validator rejects those bundles instead of guessing their platform contract. Regenerate them with the current binary:

compass agent export --platform codex --out ./compass-codex
compass agent export --platform claude --out ./compass-claude
compass agent export --platform opencode --out ./compass-opencode

The regenerated layouts use .mcp.json for Codex and Claude Code, opencode.json for OpenCode, and .agents/mcp.json for the generic Agent Skills package. Replace old generated bundles as whole directories; do not mix files from the old and new layouts.

The new directory exposes the main artifacts directly:

compass-out/
├── graph.json
├── graph.html        # unless --no-viz or the render limit omits it
├── GRAPH_REPORT.md
├── orientation.json  # versioned agent context bound to this exact graph.json
├── manifest.json
└── cache/

Scripts that open, copy, serve, mount, or archive these conventional filenames only need the executable and output-directory rename. The JSON schema and cache payloads remain Compass contracts: do not copy graphify-out/cache/ or graphify-out/manifest.json into compass-out/. Compass rebuilds them from source while retaining its own internal snapshot and store protocols.

Rebuild provisional Compass artifacts after the v1 identity reset

Compass currently makes no backward-compatibility promise for pre-release internal artifacts. Extraction, cache, publication, store-index, query-index and ranker, overview, qualification, and semantic-diff identities have been reset to v1. Artifacts carrying provisional higher version numbers are not migrated. Run a forced update with the current binary to publish one coherent v1 artifact set:

compass update . --force

Disposable query indexes rebuild automatically on their next use.

Update natural-query automation

Plain compass query "<question>" now returns structured discovery text by default on a typed graph. Replace discovery text paging based on --budget and numeric --page with --text-budget and the opaque next=<cursor> token. Keep the question, discovery options, and graph unchanged while following a cursor. Use explicit --traverse when an existing workflow intentionally needs the former relevance traversal; its --budget/--page behavior remains. CompassQL and explicit ask, search, callers, callees, and other typed commands are unchanged.

Natural discovery now defaults to a focused 64-node, 128-edge neighborhood. Automation that depended on the former 500-node, 1,000-edge default should pass --max-nodes 500 --max-edges 1000 explicitly. Those values remain supported hard ceilings; the discovery JSON schema and deterministic result ordering are unchanged.

MCP clients must read structured results from the result field of the compass.mcp.tool-result/1 envelope and inspect transportTruncation separately from the domain result's own truncated field.

Run compass update . once after upgrading to publish orientation.json with the exact graph.json digest. Agent-facing orientation/report exports fail explicitly for older, missing, detached, or stale sidecars instead of pairing evidence by filename alone.

The orientation contract is now compass.orientation/2. Consumers that parse orientation.json must accept the new schema and may read its optional typed blindSpots projection; older orientation files should be regenerated with compass update . rather than edited in place.

Select inference breadth explicitly when upgrading

Structural init, update, extract, and watch builds now default to --inference-level low, which publishes exact relationships only. This is a hard cutover from the former max default. If an automation or downstream consumer requires deferred-receiver and all other retained inferred relationships, add the former behavior explicitly:

compass update . --inference-level max
compass extract . --code-only --inference-level max

medium adds source-backed inferred relationships and high additionally adds explicitly qualified external relationships. Existing schema-1 build state that omitted the inference field is still interpreted as historical max. Because new low profiles record the level explicitly, the first command run without an override rebuilds and republishes the graph coherently instead of reusing the wider graph.

Opt into Program IR generation

Structural graph builds now omit the optional program.json artifact by default. Add --program to init, update, extract, or watch when program inspection or Program-backed enrichment is part of the workflow. Supplying --program-artifact also enables Program IR on update, extract, and watch. Existing scripts may keep using --no-program; it remains accepted as an explicit structural-only spelling.

Rename repository and user configuration before the first build:

.graphifyignore                  -> .compassignore
~/.graphify/providers.json       -> ~/.compass/providers.json
GRAPHIFY_*                       -> COMPASS_*
merge.graphify.*                 -> merge.compass.*
graphify://... MCP resources     -> compass://...

Compass does not fall back to the old names.

Hard cut to visible Compass output state

Current output no longer hides Compass-owned files. The layout now uses snapshots/, current-snapshot, store/, and visible snapshot-local names such as build-state.json and analysis.json.

Compass contains no compatibility reader, detector, or in-place migrator for the former hidden layout. Archive or remove the entire old output directory before running this version, then build it again:

mv compass-out compass-out-hidden-layout-backup
compass update .

The history realization schema and SQLite store format remain at v1. Compass does not rewrite immutable realizations or map former hidden artifact paths. Use compass history rebuild to recreate any revision that must materialize with the current visible artifact layout; archive the existing history database first only when it is needed for audit or rollback.

Compass Store sidecar upgrades

The 0.3.x line supports the logical majors compass.store/1, compass.store.graph-snapshot/1, and compass.store.ref/1. A patch release can reopen and validate a same-major SQLite sidecar. Unknown majors, a missing or corrupt store.ref, and redb or prototype files are rebuildable hard cuts; they are not migrated in place.

The optimized immutable graph-index layout is also a hard cut from store files created by the pre-release per-snapshot/chunked-payload implementation. New SQLite state lives at compass-out/store/store.sqlite3; current snapshots contain only canonical graph.json and store.ref. Do not move an older database into that location or copy a newer database into a snapshot directory. Preserve graph.json and rebuild from source:

compass update . --out compass-out --force --store sqlite
compass store validate compass-out --format json

The disposable JSON query index advances to compass-code-index/2 so its FTS underscore tokenization matches store term postings. It is rebuilt automatically on the first JSON query; no graph or store migration is needed.

Check an output before upgrading or collecting support evidence:

compass store status compass-out --format json
compass store validate compass-out --format json

Create and verify a rollback bundle before a planned upgrade:

compass store backup compass-out --output /safe/compass-store-backup
compass store restore --from /safe/compass-store-backup --into /safe/compass-out-check
compass store validate /safe/compass-out-check --format json

If validation fails after an upgrade, retain graph.json and rebuild the sidecar from source:

scripts/rebuild_compass_store.sh . --out compass-out --compass compass

The script preserves existing sidecars in a timestamped rollback directory, restores them if compass update --force fails, and never replaces the JSON artifact. A normal compass update --force --store sqlite is also sufficient when the old sidecar has already been removed. Builds without --store sqlite now publish JSON only and remove store files from the new snapshot. Typed queries use JSON by default; use --engine store to select a retained sidecar.

Downgrades must validate the output with the target binary. Do not reuse a newer physical SQLite/redb file merely because its filename matches. Rebuild when the target binary reports an unsupported major or storage provider.

Update node-trail direction handling

Typed node-trail queries now interpret operands as source then target and only follow edges in their published direction. A route requiring reverse traversal no longer appears as if it were a valid forward dependency; the response contains the typed direction_mismatch diagnostic instead.

If a workflow intentionally needs the reverse route, swap its operands:

compass path "former-target" "former-source"
compass ask "path from former-target to former-source"

Consumers that exhaustively decode compass.query/1 diagnostic codes must add direction_mismatch before upgrading.

Regenerate HTML graph exports

Normal builds now write the self-contained page directly to compass-out/graph.html; compass export html repairs or regenerates the same root path. Current Compass releases use the shared graph workbench and do not preserve the previous export's DOM, CSS selectors, or remote vis-network script boundary. Regenerate saved HTML exports with the current compass export html command. Any private CSS overrides or browser automation that targeted the old document structure must be updated to use visible roles and labels in the new workbench.

The matching VS Code extension requires a CLI that advertises both graph and community_detail. Upgrade Compass and the extension together; the extension does not fall back to the older non-drill-down graph workflow.

Current VSIX builds require Compass CLI 0.3.0 or newer. If Select Compass CLI labels an installation unsupported, upgrade that CLI or select another detected installation. Releases below 0.3.0 and 0.3.0 prereleases cannot be activated, even if they advertise some current capabilities.

Optional document OCR

No migration is required for existing projects because OCR defaults to off. PDF and Office files now produce native structural blocks, so run compass update --force once if an existing output predates compass.document/1. To opt into local OCR, install one profile explicitly and rebuild under its new fingerprint:

compass models install pp-ocrv6-small
compass extract . --ocr auto --force

Do not copy or rename old flattened document caches; incompatible schema, normalizer, renderer, OCR, and model identities are intentionally not migrated.

Replace commands

Replace Python and legacy executable invocations with compass:

graphify <command>       -> compass <command>
python -m graphify ...  -> compass ...

Compass exposes its Model Context Protocol server through compass serve. Reinstall assistant integrations so generated hooks and instructions invoke compass:

compass install --platform codex --project

Migrate MCP clients to MCP 2026-07-28

Compass stdio and HTTP now reject protocol revisions older than 2026-07-28. Upgrade clients to begin with server/discover and send the protocol's per-request _meta fields. HTTP no longer creates MCP sessions and additionally requires Mcp-Protocol-Version: 2026-07-28, the matching Mcp-Method, and any applicable parameter headers. Authentication, endpoint paths, size limits, and project_path selection are unchanged.

There is no legacy MCP-2025 HTTP mode or compatibility flag. --stateless may remain in existing scripts but is now redundant. Remove --session-timeout from scripts: Compass 0.4.x accepts and ignores it with a warning, and Compass 0.5.0 removes it. An obsolete Mcp-Session-Id header is ignored on an otherwise valid current request and never creates or restores state; clients should stop sending it. Stdio clients that previously negotiated a 2025 revision must upgrade; there is no legacy stdio compatibility flag.

Read core navigation results through the MCP envelope

Breaking in this release. The structured content returned by search_symbols, get_callers, get_callees, get_impact, explore_code, and get_node is now compass.mcp.tool-result/1. It previously used this fork's compass.code_context.v1, which has been withdrawn in favor of the upstream contract.

Move each read one field:

Was (compass.code_context.v1)	Now (compass.mcp.tool-result/1)
structuredContent.data	structuredContent.result
structuredContent.repository	structuredContent.agentView.identity.graphIdentity
structuredContent.generation	structuredContent.agentView.identity.buildGenerationIdentity
structuredContent.freshness	structuredContent.agentView.status
structuredContent.truncation	structuredContent.transportTruncation

The nested query record is unchanged: structuredContent.result is still compass.query/1 with the same fields and ordering. A client that only read data needs a one-word rename.

These tools no longer advertise a raw output schema in discovery, matching upstream. outputSchemaSha256 is now null for every tool. A client that required a declared output schema must validate structuredContent.schema itself.

New alongside the result: agentView (compass.query.agent-view/1) carries the bounded answer-first projection, and semanticResultDigest pins the result identity. Reject unknown agentView major versions explicitly rather than guessing.

Use structuredContent.schema to select the Compass decoder. Do not treat MCP resultType as that schema: for these synchronous MCP 2026 results it is the separate protocol value complete.

max_response_bytes still bounds what you receive. It is measured after the agent view and transport fields are attached, so a request whose query result fits but whose envelope does not fails with query_response_too_large rather than returning an oversized payload. Lower the requested bounds instead of retrying the same call.

Legacy text results remain callable, but discovery marks get_neighbors, get_community, god_nodes, graph_stats, shortest_path, list_prs, get_pr_impact, triage_prs, and explicit query_graph traversal text mode deprecated from 0.4.0. Migrate automation to typed navigation tools where an equivalent exists. Compass has not scheduled removal before typed replacements are available and separately reviewed.

Keep the old Graphify installation and graphify-out/ directory until the new compass-out/ graph has passed your project checks. The two tools don't share runtime output paths.

Natural-language candidate selection

compass query and compass ask now continue with a ranked symbol when a natural-language operand has multiple matches. Review the auto-picked or approximate label and the alternatives before attributing the result to the original question. Use an exact node ID to override the choice. Explicit structured commands retain their strict matching behavior. No graph rebuild is needed for this query change; cursors created for a different semantic answer fail explicitly and must be restarted.

Discovery text cursors now use version 3 because compact pages show relationships before declarations. Restart a query if a saved version 2 cursor is rejected. Natural discovery pages default to 800 tokens. Increase --text-budget or follow the printed --cursor to retrieve more of the same bounded answer.