Output reference

Compass outputs range from the current compass-out/ directory to versioned CompassQL results and immutable history exports. This reference describes consumer responsibilities and authority.

Current output directory

Default:

compass-out/
├── .compass-active-generation
├── .compass-generations/<active>/
│   ├── graph.json
│   └── store.ref               # with the default SQLite query index
├── .compass-store/
│   └── compass-store.sqlite3   # with the default SQLite query index
├── program.json                 # only with --program or --program-artifact
├── GRAPH_REPORT.md
├── graph.html
├── manifest.json
├── cache/
└── optional sidecars and exports

--out DIR or compatible COMPASS_OUT use can select another root.

Authority table

Do not reconstruct graph truth from HTML when JSON is available.

.compass-store/compass-store.sqlite3 is the default local SQLite realization shared by retained graph generations. It is addressed through the compass-store namespace/partition/key contract and is not a public SQL schema. The file is not copied into a published generation; a new build writes immutable content, checkpoints it, and publishes a digest-bound generation reference. graph.json remains the complete portable graph engine. Pass --store json during a build to omit the sidecar; --engine json forces the portable reader, while the default query engine uses the sidecar when it is present and fails closed if its reference is corrupt.

The store snapshot accepts canonical graphs up to 2 GiB. This larger, still finite bound applies only to the indexed store path; in-memory JSON readers retain their independent 1 GiB cap and should be used only for bounded investigations or smaller outputs.

graph.json

Top-level node-link shape:

{
  "directed": true,
  "multigraph": true,
  "graph": {},
  "nodes": [],
  "links": []
}

Node

{
  "id": "opaque-stable-string",
  "label": "authorize_payment()",
  "file_type": "Function",
  "source_file": "src/payments.py",
  "source_location": "L12",
  "community": 4
}

Only id is structurally required by the typed node record. Attributes are extensible.

For a source-backed declaration with one containing owning scope, the node's source anchor spans the complete definition and is the authoritative range for editor navigation. Its AST provenance keeps the narrower exact declaration anchor, such as the identifier token. When a containing definition extent is missing or ambiguous, Compass publishes the exact declaration anchor instead of selecting an arbitrary scope.

Edge

{
  "source": "caller-id",
  "target": "callee-id",
  "relation": "calls",
  "confidence": "INFERRED",
  "context": "call"
}

Source/target IDs must be indexable. Attributes are extensible.

Compass sets multigraph from the emitted links. It is true when two links share an endpoint pair (ordered for directed graphs, unordered for undirected graphs), including repeated self-loops. Consumers do not need to request this promotion.

Consumer requirements

• preserve unknown attributes;
• treat IDs as opaque strings;
• preserve direction;
• preserve parallel edges when multigraph is true;
• do not make JSON member order meaningful;
• use canonical/semantic equivalence for graph comparisons;
• validate file size and JSON at your trust boundary.

Compass readers use a bounded 1 GiB default graph-size cap. This accommodates qualified enterprise artifacts while preventing unbounded input reads. Operators can set COMPASS_MAX_GRAPH_BYTES to an explicit byte count or <N>MB/<N>GB; raising it also raises the memory exposure of JSON decoding and indexing.

Partial publication diagnostics

A successful build can publish a strictly valid partial graph after quarantining invalid individual records. The durable warning codes are:

• publication_omitted_node
• publication_omitted_edge
• publication_identity_collision
• publication_omission_summary

The first three provide bounded examples. The summary contains exact omitted node, omitted edge, identity-collision, and capped-example counts. At most 100 examples of each record category are stored.

The private .compass_output_stats.json and sealed build state retain the same counts so no-op and watch results preserve the partial status. They are operational state, not an alternative graph schema. Consumers should use graph diagnostics or typed query incomplete_coverage diagnostics.

GRAPH_REPORT.md

The report can include:

• corpus and graph summary;
• freshness/build metadata;
• god nodes;
• communities;
• surprising connections;
• cycles/diagnostics;
• suggested questions.

It is intended for people and can evolve in prose/format. Do not parse it when structured data or command JSON exists.

graph.html

Optional interactive visualization. It may be absent when:

• --no-viz was used;
• graph size exceeds a rendering limit;
• a specific build/export omitted it.

It is not required for query commands.

The document is self-contained and uses the same versioned graph workbench as the VS Code extension. It performs no runtime network requests, follows the operating system's light or dark color scheme, and retains keyboard, reduced motion, narrow-screen, and high-contrast behavior from the shared viewer.

When the node limit selects a community overview, each complete community detail is embedded as inert JSON and validated only when opened. Double-click a community node (or use Open community in the inspector) to enter its member graph; use Overview to return. Community details preserve internal edges, source anchors, and hyperedges, while cross-community edges remain represented only in the overview.

The HTML DOM and CSS classes are presentation details, not a compatibility contract. Automations should consume graph.json or compass export json instead of scraping the viewer.

manifest.json

The manifest supports incremental detection and cache compatibility. It represents the artifact set it was published with.

Do not:

• edit it manually;
• copy it between unrelated roots;
• pair it with another graph version;
• treat it as a durable historical graph.

A forced/cold build can regenerate current output.

program.json

program.json is the optional canonical, language-neutral Program IR produced by native init, update, extract, and watch builds when --program or --program-artifact is selected. Its public schema identifier is:

http://crab.build/compass/v1

The artifact records providers, evidence, modules, functions, operations, resolved and unresolved calls, capability coverage, and derived summaries. Coverage is explicitly complete, partial, indeterminate, or failed; consumers must preserve non-complete reasons and must not interpret unresolved calls as proof that no target exists.

Use compass program for read-only inspection and CompassQL projection. Reject unknown schema identifiers rather than guessing compatibility.

Query text

query, path, explain, affected, and some history commands emit human-readable text. It is stable enough for people, not the preferred machine contract.

Natural-language query output distinguishes declaration locations (src and loc) from unresolved-symbol occurrence sites (wiring) and relationship occurrences (at). explain similarly reports Source for declarations, Wiring for source-less placeholders, and source sites on connections.

When exact automation is required, use:

• CompassQL JSON/JSONL;
• history JSON;
• diff JSON;
• direct graph JSON.

CompassQL JSON

Schema:

compass.cql.result/1

Contains:

• explicit version tag;
• columns;
• typed rows;
• optional plan;
• optional profile.

Reject an unknown major version.

CompassQL JSONL

Schema:

compass.cql.jsonl/1

Order:

header
row object
row object
...
summary

Do not treat a truncated stream without a successful command/summary as a complete result.

Atomic query output

--output PATH writes a completed rendering atomically. On compile, graph-load, execution, limit, cancellation, or output failure, no successful partial result should appear at the final path.

Consumers should still check exit status before opening the file.

History JSON

History commands that accept --format json expose stable structured status, list, show, build, preference, or GC results. Exact fields are defined by the current history schema and tests.

Record:

• commit;
• realization ID;
• fingerprint;
• preferred/validation state;
• schema/version.

Diff JSON

compass diff OLD NEW --format json

Uses schema compass.semantic_diff.report/1. The report contains ranked semantic findings, affected callers/modules, source and graph evidence, verification state, completeness, and a collapsed-finding summary. Routine symbol churn is collapsed unless --all is supplied. Default text output shows 20 findings per section and reports every hidden count; --limit N changes that budget, while JSON and --all are exhaustive. Normal diff requires compatible build profiles.

verification.state is covered, gap, partial, or unknown for the static MVP (runtime adapters may also report stale, failing, or not_run). Compass reports a test gap only when the available evidence can establish one; missing or incomplete evidence is not presented as proof of a gap.

Diff HTML

compass diff OLD NEW --format html --output semantic-diff.html

Writes one self-contained HTML document with no runtime server or external assets. It includes the complete compass.semantic_diff.report/1 JSON payload, actionable metrics, feature groups, finding search and filters, expandable evidence, affected consumers, verification state, completeness, limitations, and collapsed routine-change groups. The Code section uses the pinned @pierre/diffs 1.2.12 renderer for line numbers, intraline emphasis, hunk metadata, line wrapping, and unified/split layouts. Compass embeds the library in the document, so the report has no CDN or runtime dependency, and retains the exact Git patch as a fallback if script execution is unavailable. The Graph section contains a compact changed-subgraph visualization plus exhaustive added, removed, and changed node/edge lists. Non-semantic graph metadata churn is summarized separately, including location/layout fields and edge-identity shifts that preserve multigraph multiplicity. HTML output always requires an explicit path; compass export html remains the full graph renderer and does not accept semantic-diff reports.

The graph visualization is a bounded interactive sample backed by those exhaustive lists and the embedded JSON. Select a node to focus its direct changed-edge neighborhood and open a persistent inspector with its retained kind, source path, changed-field names, incoming and outgoing relationships, and related semantic findings. Inspector links open an exact source patch or finding only when the report contains a matching target. Context-only endpoints show their identifier and known relationships without implying unavailable metadata. If JavaScript is disabled, the exhaustive lists remain the authoritative fallback.

Finding prose resolves retained entity identities to human-readable symbol names. This applies to subjects, dependency endpoints, affected consumers, witness-path hops, evidence record keys, and semantic before/after values. Raw stable IDs remain unchanged in JSON, alongside entity_display_names, so automation and exact traceability are preserved.

After writing any HTML page, an interactive Compass CLI asks before opening it in the default browser; Enter or n leaves the page closed. Scripts, pipes, redirected commands, and CI never prompt or launch a browser.

History export

graph-json

compass history export REV \
  --format graph-json \
  --output graph.json

Reconstructs canonical graph JSON from a validated realization.

compass-out

compass history export REV \
  --format compass-out \
  --output directory

Restores:

• authoritative non-derivable sidecars verbatim;
• graph artifacts;
• derived reports/HTML only using recorded compatible renderer versions.

Equivalence

Semantic/canonical equivalence includes:

• same nodes and stable identities;
• same relationships and direction;
• same relevant attributes;
• same multiplicity;
• same duplicate id-less hyperedges;
• same authoritative bytes.

It does not require:

• same insignificant JSON object member order;
• same platform filesystem timestamp;
• same operational timing/token data;
• same derived byte order where the renderer contract allows semantic comparison.

Binary caches

Query caches live under the graph output cache directory with versioned magic and graph file signature. They are:

• acceleration only;
• bounded relative to source graph size;
• invalidated when signature/format changes;
• safely rebuildable.

Do not archive them as the only graph copy.

Versioned history uses a repository-private cache/v1 directory below the Git common directory. It contains verified-content extraction entries plus canonical semantic-diff and viewer projections. This is a hard-cutover cache: older layouts are ignored, not migrated. Everything below cache/v1 is reproducible from Git commits and immutable realizations.

Other exports

compass export can produce:

• HTML and call-flow HTML;
• SVG;
• GraphML;
• Cypher;
• Obsidian/wiki/canvas-style documents;
• Neo4j/FalkorDB operations.

Each format has separate escaping, direction, multiplicity, and size concerns. Use its command help and retain the source graph.

First-party editor and offline-viewer contracts are versioned independently:

• compass.viewer.graph/1 — shared interactive graph model; located edges may include an optional relationshipSite source anchor;
• compass.graph-overview/2 — rebuildable prepared graph projection used by editor integrations;
• compass.program.call_graph/1 — bounded symbol-centered caller/callee graph;
• compass.viewer.callflow/1 — broader subsystem architecture flow;
• compass.history.timeline/1 — commit and materialization states;
• compass.history.change_counts/1 — lazy structural counts between existing realizations;
• compass.history.viewer_graph/1 — exact historical graph envelope;
• compass.semantic_diff.report/1 — exhaustive semantic findings, source changes, and exact added, removed, and changed node/edge records consumed by the CLI HTML report and editor comparison views;
• compass.ide.progress/1 — newline-delimited guided-operation events.

Graph quality diagnostics

Use compass diagnose quality --graph <path> --json to inspect the typed graph before giving it to an agent or downstream exporter. The report includes evidence confidence, source-anchor coverage, external placeholders, dangling relationships, publication omissions, identity collisions, and consistency with the publisher statistics and overview sidecars.

For graphs larger than the default bounded in-memory reader cap, the command returns quality_scope: "publisher-stats-only": counts and omission metadata come from .compass_output_stats.json, while record-level ratios are reported as unavailable. This is an explicit safety boundary; use a prepared store or a bounded investigation with COMPASS_MAX_GRAPH_BYTES rather than silently allocating an unbounded JSON graph.

Filesystem and concurrency

• Wait for the producing command to succeed.
• Avoid multiple writers to one output directory.
• Use distinct output paths for comparisons.
• Keep old output until new output validates when building critical integrations.
• Treat disk-full and permission errors as failed publication.
• Do not copy live history SQLite without its WAL state.

Related pages

• Graph model
• Integrating Compass
• Versioned history
• Command reference

Next step: identify the most structured available output for your consumer and validate its major version/direction/multiplicity before reading values.