feature - RFC 106 compiler-backed agent context graph

[dannymeijer]

Status

RFC 106 is a full v0.6 implementation commitment. The prior v0.4 baseline export remains accepted evidence, but it is not the release scope.

Problem statement

Agents and maintainers need one compiler-backed account of checked and tolerant source facts, generated behavior, Rust/Incan build boundaries, diagnostics, context relevance, architecture evidence, and process-risk evidence. No CLI, LSP, Architect, MCP tool, external importer, or generated artifact may create a competing semantic graph.

Scope

• Complete the versioned graph document, required node and edge kinds, provenance tiers, stable identities, checked/tolerant behavior, source anchors, diagnostics, generated behavior, and backend/Rust artifact relationships required by RFC 106.
• Deliver shared live and persisted fact projections for CLI, LSP, Architect, MCP task context, and inspection.
• Deliver task-ranked deterministic context packing, read-only MCP orientation and graph tools, and explicit staleness/snapshot behavior.
• Deliver evidence-backed architecture findings and the complete deterministic process-risk signal family with raw measures and controls.
• Exercise external ingestion/comparison without importing external semantic authority, generic indexing, hosted storage, or mandatory embeddings.
• Deliver the full RFC 106 conformance and evaluation contract in chore - RFC 106 full graph/context conformance and evaluation #1019.

Delivery

• feature - RFC 106 share complete codegraph projection with LSP #772 — shared LSP projection
• feature - RFC 106 graph-backed architect findings #773 — graph-backed Architect findings
• feature - RFC 106 MCP tools and complete task context packing #774 — MCP task context packing
• feature - RFC 106 process-risk signals and evaluation harness #775 — process-risk signals and evaluation
• feature - RFC 106 Rust/Incan build and interop graph for Oven #777 — Rust/Incan build and interop graph
• chore - RFC 106 full graph/context conformance and evaluation #1019 — end-to-end conformance and evaluation

Done when

• All RFC 106 consumers use one fact model with consistent identities, provenance, ranges, and stale-state semantics.
• The complete graph, context, Architect, risk, and inspection matrix passes its recorded evaluation.
• External tools consume Incan facts without becoming a semantic authority.

[dannymeijer]

Design note from the Zero/Zig/AILANG comparison: this feature should be framed as the agent-readable complement to human-readable Incan source, not a replacement for source readability.

The thesis stays: readable .incn should be understandable by humans and agents. The codegraph export gives agents and external tooling the stable anchors they need at repo scale: module/import/declaration/member nodes, source spans, checked API links, and deterministic graph edges so they do not have to repeatedly infer structure from text searches. That framing also helps keep the compiler boundary clean: Incan exports authoritative facts; downstream CodeGraph-style tooling stores, indexes, embeds, or serves them.

[dannymeijer]

Stage 3 / PR #764 intentionally creates the first stable diagnostics plane, but there are a few diagnostic-fact improvements that should live here rather than being treated as CLI-only follow-up work.

Concrete follow-up scope for RFC 106 / codegraph inspection:

• More granular diagnostic codes should evolve with compiler-backed semantic facts, not by adding ad-hoc strings at the CLI edge. The initial INCAN-P0001, INCAN-T0001, INCAN-I0001, and INCAN-C0001 phase-level codes are deliberately broad; feature - RFC 106 compiler-backed agent context graph #573 should be where narrower parser/typechecker/import/tooling codes are tied to stable diagnostic constructors and graph fact categories.
• related_spans should become populated from real compiler facts. Examples include duplicate declarations pointing at the previous declaration, call-site errors pointing at the callee signature, import errors pointing at the export/provider declaration when one exists, and type errors pointing at both the use site and the source of the expected type.
• Diagnostic phase/source ownership should move deeper than the current CLI bridge. PR feature - add stable diagnostic commands #764 classifies import diagnostics partly by checking whether the diagnostic span overlaps an import declaration. That is acceptable for the first JSON surface, but the long-term codegraph/inspection model should carry diagnostic origin metadata from the parser/import resolver/typechecker/Rust bridge into CLI, LSP, and codegraph records through one shared path.
• Structured expected/actual facts should be added where diagnostics have them. Type mismatches, call arity errors, missing fields, unresolved exports, and overload failures should expose machine-readable facts rather than requiring agents/tools to parse prose messages.

The invariant I would attach to this issue: if a diagnostic is visible through incan check --format json, LSP, or incan inspect codegraph, those surfaces should be projections of the same compiler-owned diagnostic fact, not separate classifiers with their own truth surfaces. This keeps #573 aligned with the 0.4 boundary-identity lesson from v0.3 and avoids diagnostics becoming another split-brain subsystem.