PROP-032 — The project model as a universal typed graph; the agent-first IDE substrate

2.1 The project model is a typed, directed graph over addressable nodes

• 08prop r1 — The canonical model of the project is a typed, directed property graph: nodes are anything with a stable address (spec units today; code items, packages, boot entries as the model grows); edges are typed and directed and may connect any node kind to any node kind.
• specmap's code→spec edges are one projection of this graph, not its definition.
• The graph is the single source of truth for navigation and refactoring; everything else (the index file, the queries, the operations, the surfaces) is a view or an action over it.

2.2 Every node carries a stable, minted, location-independent address

• 09req r1 — A node's address of record is minted and travels with the artifact; its location (line number, symbol-path, doc-path, file) is derived decoration, never the address.
• This is the property that lets the graph survive refactoring — the lesson PROP-014 §5.2 learned when it rejected line/range anchors as "maximally fragile," here promoted to a model-wide invariant:

• 10spec node → spec://<ns>/<doc-path>#<anchor>; the {#anchor} is minted and immutable, travels via edit-in-place.
• code node → code://<ns>/<id>; the <id> is minted and travels on an attribute on the item (§2.3).
• package node → the FQID (PROP-029).

• 11Because the address is minted, renaming or moving the artifact does not change its address — the address moves with it.
• Location-based addressing is inverted: the symbol-path and line are computed from the item at index time, for human navigation, and are free to churn.

2.3 Code is a first-class node (code://), not only a source

• 12req r1 — The concrete extension this PROP exists to fix.
• A code item becomes an addressable node under code://<namespace>/<id>, where <id> is a minted, immutable, kebab-case identifier carried by a per-language marker on the item — the specmark projection pattern PROP-014 §2.9 already uses (a Rust attribute #[addr("resolver-fixpoint")] or a field on #[spec]; JSDoc/decorator for the other stacks).
• The item's symbol-path, file, and line are derived decoration, exactly as a spec unit's line is.

13Two rules keep it honest:

• 14Mint sparingly. A code:// address is minted only where the code is meant to be pointed at — a canonical algorithm, a wire schema, a reference example — not on every function. Most code stays addressed only derivedly (by symbol-path in the index, which is enough for find-references). Ceremony is proportional to authority.
• The id is the address, the name is not. Because the id lives on the attribute, rename-symbol / move-item (PROP-031) do not break code:// links — the same robustness that makes #[spec] survive refactors. This is the whole reason to mint rather than address by symbol-path.

• 15Where the marker lives — on the item, never external. The address is carried by whatever metadata construct is idiomatic and scannable in each language, attached to the item itself, because an address that does not travel with the artifact reintroduces exactly the fragility PROP-014 §5.1 rejected (a sidecar map rots on every refactor).
• The neutral grammar is the address; the carrier is per-language (PROP-014 §2.9): a structured attribute where the language has one (Rust #[spec(addr = "…")], Java/Kotlin annotation, Python decorator), a structured doc-comment tag where it does not (TypeScript/JS /** @addr code://… */, matching the @spec JSDoc choice), and a comment-directive for languages with neither (Go //spec:addr …, cf. //go:generate).
• Three constraints bind every carrier:
• on the item — travels on refactor;
• scannable without execution — read as AST/text, as #[spec] is today;
• structured, not free prose — a defined grammar the scanner parses, never a human sentence.
• Recommendation: make addr a facet of the existing specmark marker, not a new construct — one code-marker family then carries both a node's identity (addr) and its outgoing edges (the verbs), the whole code-side of the graph in one place.

16This single change removes the asymmetry of §1: code can now be a target, so spec→code, doc→code, and code→code edges become expressible — and the graph is symmetric.

2.4 Edges are typed by authority direction

17prop r1 — An edge's verb carries which end is the source of truth, which is what makes the graph queryable and honest. Generalising PROP-014 §2.4 from five code→spec verbs to a directional set:

• 19canonical / defined-by is a marked, deliberate, rare inversion — the peer of deviates. It says "this concept's normative content genuinely is the code; do not restate it in prose."
• It is not a licence for shadow-code: PROP-014 §3.1.6 ("spec states what and why, never how; a spec that mirrors code is drift fuel") still governs the default.
• The inversion is the exception you mark, exactly as a deviation is.

2.5 Three operations over one model: query, mutate, render

20prop r1 — The substrate exposes exactly three operation families over the graph, and "the IDE" is nothing more than these three:

• 21Query — navigation. Go-to-definition = follow an edge to its target; find-references = the reverse edges into a node; impact = the transitive closure. specmap already ships these as explain / coverage / impact (PROP-014 §2.6); symmetry (§2.3) is what makes them work in both directions.
• Mutate — refactoring. The typed, atomic, gated operations of PROP-031 (rename-address, move-unit, rename-symbol, …), now spanning spec:// and code:// addresses.
• Render — explanation. The deterministic subgraph plus its optional prose rendering (PROP-014 §2.6); the data layer is always available without an LLM.

2.6 Agent-first: the primary client emits typed commands; surfaces are progressive

• 22req r1 — The primary consumer of the substrate is an agent, not a human at a keyboard.
• An agent drives navigation and refactoring by emitting typed query/mutation commands — the LLM boundary of PROP-031 §2.2 and PROP-014 §2.7: the model proposes a typed command; the deterministic engine executes and gates it.
• The transport is MCP (PROP-014 §2.8, already shipping specmap_query / specmap_explain).

• 23The consequence reorders the usual notion of "IDE": the IDE is a headless model-plus-operations server; the GUI is the last, optional client, not the IDE itself.
• Surfaces are progressive projections of the same command set:

library API  →  command line  →  MCP / agent  →  (last, optional) graphical view
   (exists)       (exists)        (embryo §2.8)        (future, human-facing)

• 25Building GUI-first would invert the dependency — a graphical shell over an incomplete, asymmetric model.
• The model and the operations are the product; every surface is a client.

2.7 Integrity and refactoring fall out of the model, not bespoke code

26req r1 — Because everything is one graph with minted addresses, the hard properties are free:

• 27a link to an address that resolves to no node is a dangling edge (the existing gate);
• a duplicate minted id is a duplicate-address warning (the existing duplicate-anchor machinery);
• a rename is a rename-address operation (PROP-031);
• a stale pin is a suspect (PROP-014 §2.2).

28This is the reason symmetry is cheap once the node model generalises: no new subsystem, only more node kinds and edge directions in the graph that already computes all of this.

2.8 The substrate is a discipline-neutral, independently-installable tier

29req r1 — The substrate (specmark + specmap-core + the refactoring operations and their registry, PROP-033) is packaged independently of the ai-native discipline and delivered as its own installable tier, so vibevm serves a spectrum of users through a three-tier product model:

1. 30Base vibevm — the package manager itself (resolve / install / lockfile / boot; working with vibe.toml projects; loading spec collections). No traceability, no refactoring, no discipline. The "just load a collection of specs" user lives here.
2. + the SDD substrate (a package under org.vibevm.world, not ai-native) — installs specmark + specmap + the refactoring registry: the spec:// / code:// model, integrity checking, navigation, and the algorithmic refactoring core. Proper spec-driven development, without the strict discipline.
3. + the ai-native discipline (rust-ai-native, …) — the strict opt-in: conform, cards, cells, the nine scaffolds. It depends on tier 2, contributing its own refactorings to the registry; it never owns the substrate.

• 31The dependency runs ai-native → SDD substrate → base vibevm — a dependency inversion from today, where rust-ai-native owns specmap.
• A legacy tree that cannot adopt the discipline still gets tiers 1–2.
• This re-opens what the Traceability-Relocation plan §1 deferred, for the stronger reason of product surface (not cross-language DRY).
• The center of each tier is its Rust library + its spec, so agents work with it directly (§2.6); the CLI (vibe refactor …) and MCP are thin surfaces, never the center.