brick/docs/architecture/graph-model.md

Graph model

Brick separates analysis from presentation:

analyzers                  canonical model                consumers
grammar / lexical -\
YAMS graph ----------> nodes + typed edges ----------> JSON
Fold source/binary --/    evidence + metrics --------> Cytoscape
future traces ---------------------------------------> Fold/MCP

Compatibility

Schema version 4 makes evidence multiplicity, the selected P4 frontend in scan scope, and the nested P4 metric contract reader-visible. Readers must reject unsupported schema versions instead of guessing. Two models are structurally comparable only when they have the same schema version, canonical scan root, repository identity, and scan scope. The top-level root is absolute execution provenance; comparing artifacts from different clones or worktrees can opt into --allow-root-relocation for structural diffs. This caller assertion relaxes only root equality and is recorded in diff schema 2 alongside both original roots. It does not verify Git identity; the repository node ID is graph-local, not a repository-origin fingerprint. See structural diff.

scope.path is normalized and repository-relative. Each scope.excluded_directories value is one non-empty path component; the array is sorted and deduplicated before serialization. Readers reject absolute, drive-qualified, traversing, unsorted, duplicate, or empty scope values. scope.p4_frontend is lexical or the explicit tree-sitter-p4-pilot; models from those frontends are not comparable because their graph coverage differs. Future scope fields must become part of the compatibility check when they can change graph coverage. The top-level root must be a normalized portable absolute path (/repo, C:/repo, or a normalized UNC root); empty, relative, drive-relative, backslash, trailing separator, traversal, and unnormalized Windows verbatim forms are rejected. The scanner converts \\?\C:\repo to C:/repo and \\?\UNC\server\share to //server/share before serialization.

Compatible buildings can be compared through the separate versioned structural diff contract. It preserves complete added/removed facts and before/after records for shared IDs whose content or evidence changed. See docs/architecture/structural-diff.md. Versioned declarative boundary policy is a separate consumer of canonical dependency edges and never changes their kind or evidence; see docs/architecture/policy.md. The read-only MCP server is another consumer: it validates schema-v4 JSON once, then exposes versioned impact, cycle, bridge, and evidence queries without scanning or renderer coupling; see docs/architecture/mcp.md.

Nodes and identity

Exactly one Repository node is required; missing or ambiguous repository identity fails schema validation. Duplicate node/edge IDs, cross-kind ID collisions, dangling edge endpoints, and edges without evidence also fail schema validation. Repository and directory nodes provide compound layout. File, class, and function nodes represent source structure. External nodes make unresolved dependencies visible instead of dropping them. Finding nodes attach analyzer evidence without changing structural identities.

IDs derive from kind plus repository-relative semantic identity. The repository node uses . as its identity rather than the checkout directory name. Source line is provenance, not identity. Extracted symbols use:

path + semantic owner ID + coarse kind + name + same-name ordinal

The ordinal distinguishes overload-like declarations within one owner. This keeps IDs stable under unrelated line insertions, though inserting a same-name declaration before another remains an explicit lexical limitation.

The default C++/JS/TS/Dart/Rust grammar extractor preserves this identity format for unchanged declarations. Namespace/module scopes additionally contribute to identity and appear in attributes["source.scope"]; ordinals are local to that scope. Rust impl methods use their resolvable type as parent. Fixing a previously incorrect owner intentionally changes the affected method ID. Unresolved targets in these languages include source, language, and scope in identity so unrelated unknowns cannot merge. Legacy Python/Swift/P4 identities remain unchanged.

source.exports records syntax-level export names; it does not assert that a module is reachable under a particular build configuration. Parameter-bound calls retain source.unresolved-reason instead of resolving to a same-named function. Grammar version and extraction revision live in evidence backend strings. Schema 4 remains sufficient: consumers use the same node/edge kinds and evidence contract, with optional opaque attributes. Rebuild baselines when adopting the new extractor so corrected coverage is not mistaken for a source-code change.

P4 support initially retains the coarse display kind only when the exact domain kind is also present in node attributes:

domain = "p4"
p4.kind = "header" | "header-union" | "struct" | "parser" |
          "control" | "table" | "action" | "state" | "extern" |
          "terminal-state" | "unresolved"
p4.dialect = "p4-16"

An architecture attribute is added only when an explicit source or imported contract supplies it; the lexical scanner does not infer v1model from familiar shapes. Parser states and other nested entities use their semantic owner as parent. A consumer must not infer P4 semantics from class or function alone.

Edges and evidence

Contains and defines describe hierarchy. Calls, imports, and inherits describe dependencies and participate in the current SCC/coupling metrics. Flags attaches analysis evidence and does not affect the structural score.

An edge has a stable relationship identity, optional attributes, and an ordered evidence array. The relationship is deduplicated by (source, target, kind); independent call sites and backends add evidence records rather than replacing one another. Evidence ordering is deterministic by lane, backend, provenance, and confidence.

P4 relationships retain their exact domain meaning in edge attributes even when a coarse edge kind is used:

domain = "p4"
p4.relation = "direct-transition" | "select-transition" |
              "select-default" | "apply" | "action-call" |
              "table-action" | "include" | "compiler-diagnostic"

Every evidence record has:

• lane: syntactic, symbolic, imported, or heuristic;
• backend: producer and mode;
• confidence: a producer-local numeric score, categorical label, or null when the producer did not supply one;
• provenance: source location or report artifact.

Confidence labels from different producers are not calibrated probabilities. Missing or unknown imported values remain unknown or produce diagnostics; they must not be mapped to a convenient backend, lane, or scalar.

Lane classification

Fact	Lane
Filesystem containment or declaration syntax	Syntactic
Lexical/tree-sitter target resolution without compiler proof	Heuristic
External analyzer diagnostic	Imported
Result proved within a named bounded model	Symbolic

A syntactic call expression, heuristic target resolution, imported diagnostic, and bounded symbolic fact may all support the same relationship. Name resolution never upgrades existing evidence confidence or lane.

Health indicator

The v0.1 score remains deliberately transparent:

Component	Weight	Meaning
Acyclicity	35%	Fraction of symbols outside cyclic SCCs
Resolution	25%	Dependency edges not ending at external nodes
Connectedness	25%	Symbols participating in dependencies
Concentration	15%	Penalty for one target dominating fan-in

The score is experimental. It is a navigation aid, not an architectural quality oracle. Future weights require labeled multi-project evidence and an ablation; they must not be tuned against one repository.

The top-level score remains the original coarse, language-agnostic indicator; its SCC inputs still include calls/imports/inherits, including coarse P4 edges. Consumers that need P4 meaning must use metrics.p4, whose fields are:

Field	Canonical observation
parser_state_count / terminal_state_count	P4 state and implicit terminal-state nodes
parser_transition_count	Transition edges sourced at a parser state
parser_cycle_count / cyclic_parser_state_count	SCCs over same-parser direct-transition, select-transition, and select-default edges
unreachable_state_count	Non-terminal states not reachable from a recognized start state within the same parser
control_apply_node_count	P4 control, table, and action nodes
control_apply_relationship_count	apply and action-call edges sourced at those nodes
control_apply_cycle_count / cyclic_control_apply_node_count	SCCs over resolved control/table/action apply and action-call edges
unresolved_dependency_count	P4 include, transition, apply, action-call, or table-action edges targeting an External node

A repeated apply or action call merges call-site evidence on one directed relationship and is not a cycle without a return path. Accept/reject terminals have no outgoing transition by construction. Unreachable-state diagnostics are prefixed P4 structural observation (not verifier proof) and are recomputed idempotently. Compiler/verifier Flags edges never enter these structural metrics.

P4 compiler evidence

The qualified p4c adapter accepts only Brick envelope schema 1 for p4c v1.2.5.16 p4test-regression diagnostics. It creates Finding nodes and Flags edges with Imported evidence, never Symbolic evidence. Tool version, command mode, result category/code, exit status, raw result identity, artifact identity/provenance, explicit model bounds/confidence category, and source position remain inspectable attributes or provenance.

The adapter first resolves the exact path/kind/name/owner/line P4 entity and falls back to the matching file with a diagnostic. Unknown categories, escaping paths, unsupported tool versions/modes, non-null symbolic bounds, and unqualified symbolic tools fail closed. The complete envelope and real-fixture contract is in docs/architecture/p4-evidence.md.

Fold integration

The current adapter imports SARIF and native findings JSON. A deeper adapter should map Fold function/block/operation/value fact IDs directly to Brick identities and retain source/binary lanes. Source proved, latent, heuristic, and concrete-witness confidence must remain distinguishable. Binary evidence must not be promoted to symbolic evidence without corroboration.

A Fold finding with no backend is diagnosed and not imported. Missing confidence is preserved as unknown with a diagnostic. Duplicate finding IDs merge report provenance into the existing Flags relationship.