Design rationale: Loading & boot composition model

1. What this document is

05PROP-007 shipped the workspace data model (M1.17) but deliberately left one question open — PROP-007 §6 question 3, the per-member materialisation target: when a dependency is resolved for member M, into which member's spec/ does its content land?

06This session answered it. The answer turned out to be far larger than picking a directory: it is a redesign of vibevm's entire loading model — how a dependency's content is materialised, how the boot sequence is composed across a workspace hierarchy, and how an AI agent consumes it at session start. This document records the why and the fork-by-fork reasoning; PROP-009 is the contract, and it shipped.

07It belongs to the workspace arc and continues workspace-and-qualified-naming.xml.

2. The problem the deferred question was hiding

08PROP-007 §6 q3 reads as a narrow placement question. It is not.

09vibevm's boot model (VIBEVM-SPEC.md §6) is a flat, single, shared, mutable namespace — spec/boot/NN-*.md, read in filename order, one sequence, one entry point. It is correct for exactly one project shape: one project → one boot sequence → one entry point.

10A workspace breaks every one of those assumptions at once:

• 11N nodes — the root plus every member.
• N entry points — a developer cds into any member and opens an agent there. This is PROP-007's load-bearing principle: "the user works in a sub-project and doesn't notice it is part of something bigger."
• N boot sequences — each entry point needs a sequence coherent for that node.
• One shared dependency set — unified resolution (PROP-007 §2.4) means one version of each external dependency across the whole workspace.

12The flat model cannot be stretched over this. It must be replaced.

13The owner's hard constraint, stated at the outset: installing a dependency must never modify anyone's authored spec. The owner's analogy is C++ — you do not rewrite your #include directives into the literal text of the dependency's headers. Merging a dependency's spec into the consuming spec is the broken option, and it is what a naïve "bubble everything into the root vibevm/vibespecs/boot/" would amount to.

3. The owner's mental model — boot as linking

14The owner framed the loading mechanism directly as static vs dynamic linking, and that framing became the spine of the design.

16The load-bearing consequence: at session start, the AI agent is the loader. Every reference the agent resolves itself costs tool calls, and tool calls are — the owner's words — безумно дорого. Static linking moves resolution to vibe install time (done once, by the machine); dynamic linking leaves it to the agent (every session, by the LLM). Exactly the C++ tradeoff: a statically-linked binary loads with no help; a dynamically-linked one needs the loader to find and map every .so.

4. The model — four principles

17P1 — Two trees. A node's authored spec/ (only the node's author writes it) and the materialised dependencies (a separate tree, only vibe writes it) are physically separate and never intermixed. Installing a dependency never touches authored spec/. This is "your code vs vendor/". Under unified resolution a dependency is materialised once for the whole workspace.

18P2 — The boot sequence is computed, not assembled by hand. Each node has an effective boot sequence = inherited foundation (from ancestors, flowing down) + the node's own authored boot + the boot of its transitive dependencies (flowing up) + user overrides. vibe computes it from the unified resolution. This is the owner's "matryoshka" — but computed directly per level from the resolution graph, not physically copied leaf-to-root (copying drifts; computation does not). Every level is self-contained: a session opened at any node gets a sequence coherent for that node's subtree. The root's sequence is the union of everything; a small member's is small — the hierarchy gives cost-scoping for free.

19P3 — One generated index per entry point; the agent never walks the graph. vibe install generates, for each entry-point node, the boot artifacts (§6). The agent reads them in a flat, predictable loop — reads parallelise, collapsing latency. No recursion, no discovery, no cycle-detection on the agent's side: vibe did that once. Boot stays pure file-reading — the CLAUDE.md / AGENTS.md / GEMINI.md redirect points at generated files; it does not become "run vibe". This preserves the zero-dependency cross-agent property that is the whole point of VIBEVM-SPEC §6.1.

20P4 — Three inclusion types: inline, static, dynamic. Declared per dependency in the consumer's vibe.toml; default static. They are the points on the linker spectrum (§6). (As shipped after the 2026-07-16 rename: two types, link = "static" | "dynamic", default dynamic, with the third case expressed as a dynamic entry carrying a when — see the rename note above.)

5. The fork-by-fork record

21Four forks were put to the owner. The options, the resolution, the reasoning.

6. The three inclusion types — the refined Fork-1 answer in detail

27Each dependency in a consumer's vibe.toml carries an inclusion type (working syntax of this session: link = "inline" | "static" | "dynamic"); the default was static. At vibe install time, for each entry-point node vibe generates:

• 28STATIC.md — the verbatim concatenation of every static-typed contribution in the node's effective boot, in priority order. Read first; one read; maximum attention weight. The emergency lane — used sparingly, for top-level skills and critical disciplines. Generated only when the node has inline contributions (shipped name: static contributions, carried by the vibe:static markers inside STATIC.md).
• INDEX.md — the ordered, resolved manifest of the rest of the boot sequence. static entries appear as resolved file paths the agent reads directly (a flat, parallelisable loop). dynamic entries appear as INCLUDE pointers the agent resolves at boot.
• Session-start order: CLAUDE.md → STATIC.md → INDEX.md and the files it names.

29Cost profile:

31dynamic is, mechanically, the subskill lazy-pull delivery mode (PROP-003 §2.5) — the loading model generalises subskill delivery rather than inventing a parallel axis.

7. Consequences and findings

• 32Numbering. The NN- prefix namespace (10–89, author-chosen) cannot survive a workspace and is already admitted provisional (§6.5). In the computed model vibe owns the order in the generated artifacts; a package author declares only a category (the existing range bands — foundation / flow / stack / user-override — become categories) and optionally a coarse early/late hint. Prefix collisions become impossible by construction.
• Mirror-layout breakage. VIBEVM-SPEC §13.1's mirror layout — source path = target path — works today only because a dependency always lands at the same path in every project. Moving dependency content into a separate tree breaks that; a package's internal cross-references (a boot snippet pointing at its own protocol document) must become package-relative or spec:// URIs, rewritten by vibe at materialisation.
• Published-copy regeneration. A package published by vibe workspace publish is consumed standalone — its boot index must be regenerated for the published shape, where dependencies are registry-resolved and version-pinned rather than path-sourced. This is exactly PROP-007 §2.5's dual-form { path, version }; publish staging gains an index-regeneration step.
• vibevm dogfoods itself. The vibevm repository is itself a vibevm project; PROP-009 changes how this repository boots. vibevm/vibespecs/boot/00-core.xml and vibevm/vibespecs/boot/90-user.xml stay user-owned authored boot; the generated STATIC.md / INDEX.md join them. The migration is part of the milestone.

8. What this supersedes and parks

• 33Workspace-aware vibe install / vibe build (PROP-007 §9.3, §6 q3) is no longer a separate deferred item — it is subsumed: it becomes the install/build half of PROP-009.
• version = { workspace = true } (PROP-007 §6 q4) and the publish-signalling polish (--archive etc., PROP-007 §9.3) are parked behind PROP-009 — recorded, not dropped.
• PROP-008 (qualified naming) is unaffected; it still follows PROP-005 (index).

9. Session log

• 342026-05-21. Session restored from CONTINUE.md + vibevm/vibespecs/WAL.xml. The owner reopened PROP-007 §6 q3 (the materialisation target). The discussion established that the question is a loading-model redesign, not a directory choice; produced the linker-model spine (§3), the four principles (§4), and the four-fork resolution recorded in §5. PROP-009 and its implementation milestone (M1.18) deferred to the contract-writing step. Out of band, a standing test-environment misdiagnosis was corrected — os error 740 on cargo test -p vibe-install is Windows UAC installer detection (the test binary's name contains "install"), not Windows Defender; see the WAL.

10. Pointers

• 35PROP-009 — the contract; shipped M1.18.
• PROP-007 — the workspace data model; §6 q3 is the question this answers.
• workspace-and-qualified-naming.xml — the preceding design session.
• VIBEVM-SPEC.md — §6 (boot directory model), §4.2 (layout), §4.6 (effective spec), §13.1 (mirror layout).
• PROP-003 §2.5 — subskills and delivery modes.