PROP-009: Loading model — computed boot composition and the effective spec

2.1 Two trees — authored spec and materialised dependencies

10Decision. A node's authored spec/ and its materialised dependencies live in physically separate trees. vibe install never writes into any node's authored spec/.

• 11Authored spec/ — written only by the node's author. Unchanged definition.
• Materialised dependencies — a vibedeps/ tree at the absolute workspace root (PROP-007 §2.3), written only by vibe. One slot per resolved package, vibedeps/<group>.<name>/<version>/ (identity-keyed, PROP-022 §2.1 — owner ruling 2026-08-13), holding the package's published tree verbatim (PROP-024 §2.2 re-scopes "published" to the shippable tree — source minus build output — for code-bearing packages). A package's prompt content lives under its own spec/, so a boot snippet materialises at vibedeps/<slot>/spec/boot/<file> (PROP-024 §2.1). Unified resolution (PROP-007 §2.4) guarantees one version per package, so one slot serves the whole workspace.
• vibedeps/ is committed to the repository. A fresh clone is immediately bootable with no vibe install; the dependency corpus is visible and diffable; this matches the spec-driven principle that the committed spec corpus is the product.

• 12Consequence — the mirror layout is retired. VIBEVM-SPEC.md §13.1's mirror layout (a package's [writes] entry is both source and target path) worked only because a dependency landed at one fixed path in every project.
• A materialised package is now its own verbatim subtree under vibedeps/<slot>/; a package's internal cross-references must become package-relative or spec:// URIs. [writes] is retired (§2.6): a materialised package is its own subtree, and a per-file write list has nothing left to declare.

2.2 The effective boot sequence

13Decision. Every node has an effective boot sequence, computed by vibe from the unified resolution:

inherited foundation (from ancestors) + the node's own authored boot
  + the boot of the node's transitive dependencies + user overrides

• 15Inherited foundation flows down: a member inherits the project-wide foundation boot of its ancestors up to the absolute root (conventions, the four rules, technology choices).
• Dependency boot flows up: a node's sequence includes the boot of everything it transitively requires.
• A node that is itself a workspace aggregates its members' sequences — the root's effective boot is the union of the whole tree; a leaf member's is its own subtree only. The hierarchy scopes cost: a session opened in a small member boots small.
• The sequence is computed per node directly from the resolution graph, never copied physically between levels (copying drifts; computation does not).

2.3 Generated boot artifacts

16Decision. For every entry-point node, vibe install generates two artifacts under the node's vibevm/vibespecs/boot/:

• 17STATIC.md — the anchor-qualified concatenation, in priority order, of every static-typed (§2.4) contribution in the node's effective boot: each contribution's content is carried whole, with its label definitions (heading anchors, fact ids) and intra-contribution label links rewritten to the origin-qualified form <origin-slug>--<original> (PROP-035 §8's qualify phase, B-011 — owner-approved 2026-08-04), so the compiled file's label namespace is collision-free by construction. Read first. Generated only when the node has static contributions.
• The lane emits each package's text once (B-006, owner-approved 2026-08-04). A static entry that would embed a compiled unit artifact (a dependency that statically links children, PROP-038 §2.1) is de-substituted when every boot-bearing member of its static zone (itself excluded) is already present as an individual static entry of the same lane: a package with its own boot snippet reverts to that snippet — its own text still enters, once; a snippetless aggregator leaves a generated provenance stub — one marker comment naming the origin and stating the zone is emitted member-by-member, never a #use directive (which would route a mandatory read back into the unit artifact carrying the very duplicate) and never a second copy of the text. An entry with any zone member not individually present keeps its unit-artifact substitution whole — the rule removes proven duplicates only and never drops coverage. The decision is a pure function of the lane's entry set and the unit zones — independent of how many consumers pull the package, through which mix of static / static-transitive / static-hard edges, and in what order: the closure walk already emits one entry per package identity, and the single-version invariant (PROP-038 §2.6) makes every copy of a member byte-identical, so covered-zone de-substitution can never lose text. The stated residual: under partial coverage a member both individually present and embedded in the kept unit artifact is carried twice — accepted deliberately, because the composition layer only chooses paths and never rewrites a unit artifact's content; deduplicating a widely-shared member inside unit artifacts is the hoisting plane's job (PROP-038 §2.4–2.5 — a hoisted member's text is replaced by a #use marker in every unit that shares it), and the undercounting hoist trigger is recorded at PROP-038's DRIFT-030 review stop, not here.
• STATIC.md opens with the resolution preamble and the tombstone table (PROP-035 §11, B-011): the label convention, alias semantics, the lookup rule, and every renamed short name with its qualified heirs — placed first because the first lines of the first file read are the one position an agent re-reads every session and after compaction (the owner's priority-placement addition, 2026-08-04).
• A generated STATIC.md is not a citation target — authored text never cites spec://…/boot/STATIC#…; the lane is compiler output, and source-of-truth is the package source under vibedeps/ (PROP-035 §11's lint, B-011 §6.1).
• INDEX.md — a generated TOML manifest of the rest of the sequence: a schema version, a static pointer (the path of STATIC.md, when one exists), and an ordered list of [[entry]] tables. Each entry carries path, kind ("static" — a resolved file the agent reads directly; "dynamic" — an INCLUDE the agent resolves at boot, §2.4), and, for dynamic entries, when (the activation condition, §2.4). The manifest is flat and machine-precise — vibe performed the graph walk once at generation time; the agent parses one TOML document and reads the listed files, with no recursion, discovery, or cycle-detection.

# vibevm/vibespecs/boot/INDEX.md — generated by vibe, do not edit.
schema = 1
static = "vibevm/vibespecs/boot/STATIC.xml"

[[entry]]
path = "vibevm/vibespecs/boot/00-core.xml"
kind = "static"

[[entry]]
path = "vibedeps/org.vibevm.windows/2.1.0/boot/windows.md"
kind = "dynamic"
when = "os:windows"

• 19Both artifacts are generated, git-tracked, and marked "generated — do not edit".
• A generated boot artifact carries no token budget (owner ruling, 2026-07-29). The size budgets of the addressable-specs flow govern authored documents, where a page over budget is a page nobody re-reads and the remedy is to split it. STATIC.md — the project-wide one and every per-node one — is compiler output: it is not read by a human, not edited, and not splittable, because its size is the sum of what the resolution graph says the session must have. Compiling a document into the lane is therefore a legitimate answer to a dangling pointer, and «the lane grew» is not an objection to it. What remains measurable, and is the honest cost, is the session's context, which the dynamic lane exists to keep off the critical path (§2.4).
• Authored boot files (the user-owned snippets, the node's own authored boot) continue to live alongside as ordinary files; INDEX.md references them in computed order.

• 20Session-start order: the CLAUDE.md / AGENTS.md / GEMINI.md redirect → vibevm/vibespecs/boot/STATIC.xml (if present) → vibevm/vibespecs/boot/INDEX.md and the entries it names, in order.
• Boot remains pure file-reading — the redirect never becomes "run vibe", preserving the zero-dependency cross-agent property of VIBEVM-SPEC.md §6.1.

21The redirect is a managed block (PROP-012). The CLAUDE.md / AGENTS.md / GEMINI.md redirect is not a whole generated file. PROP-012 refines it: vibevm owns only a delimited <vibevm> block inside each shared instruction file and preserves every byte outside it — the file is a co-tenant surface, not vibevm's property.

2.4 Inclusion types — static, dynamic

22Decision. Each dependency declares an inclusion type, set by the consumer in its vibe.toml on the [requires.packages] entry:

[requires.packages]
"flow:wal"        = { version = "^0.3", link = "dynamic" }   # default
"flow:discipline" = { version = "^1.0", link = "static" }    # emergency priority lane
"stack:rust"      = { version = "^2.0", link = "dynamic" }   # conditional / context-gated

• 24link = "dynamic" — the default. vibe resolves the contribution to a concrete path in INDEX.md; the agent reads it dynamically, on demand. An optional when condition gates the read: with a when it is a conditional INCLUDE (loaded only when the condition holds) — mechanically the subskill lazy-pull delivery mode; without one it is read unconditionally. The when draws on the subskill [activation] probe vocabulary (PROP-003 §2.5) — one probe grammar across both mechanisms. v1 implements the os: probe end-to-end — when = "os:windows" matches the session's operating system (windows / macos / linux); the remaining probes are reserved until PROP-003's activation engine is built.
• link = "static" — the contribution's boot text is compiled into STATIC.md ahead of time (whole, anchor-qualified — §2.3). Read first, one read, maximum attention weight. The emergency priority lane — for top-level skills and critical disciplines whose priority must be guaranteed by position, not by trusting agent-side resolution. Used sparingly; it duplicates the text on disk.

25The two types are the two ends of the static/dynamic-linking spectrum: static is compiled in ahead of time (the STATIC.md lane), dynamic is loaded by reference on demand (the INDEX.md lane), and the old third type is gone — a conditional load is just a dynamic entry carrying a when.

26A package MAY declare a suggested default inclusion type in its own [boot_snippet]; the consumer's declaration always wins. Absent both, the type is dynamic.

27A [boot_snippet] that declares a when condition (§2.6) stays a conditional dynamic entry, irrespective of link: a condition cannot be honoured by the ahead-of-time static lane, so a when forces the gated INDEX form. It is a correctness constraint, not a preference — OS-specific content must never reach a session on the wrong OS.

2.5 Ordering by category — the NN- prefix is retired

28Decision. vibe owns the order of entries in the generated artifacts. The author-chosen two-digit NN- prefix (VIBEVM-SPEC.md §6.2) is retired — it cannot survive a workspace's combined namespace, and §6.5 already admits it provisional.

• 29A package declares a category for its boot snippet, not a number. The categories preserve the intent of the old range bands: foundation, flow, stack, user-override.
• Within the computed sequence the order is: foundation → the node's own → dependency boot (topologically — a dependency before its dependents) → user-override. static contributions are concatenated into STATIC.md in the same relative order.
• Prefix collisions — the failure mode of VIBEVM-SPEC.md §6.3 — become impossible by construction; BootSnippetConflict / BootSnippetNumericConflict (vibe-install) are removed.
• The user-owned files keep their reserved names (00-core.xml, 90-user.xml) by convention; vibe places them at the foundation / override ends.

2.6 Manifest schema changes

30Decision.

• 31[requires.packages] inline-table entries accept an optional link field (§2.4): "static" | "dynamic", default dynamic. Valid on registry-, path-, and git-source dependencies.
• [boot_snippet] (package-role) drops the filename field (the NN- target name) and gains category (§2.5); source — the path to the boot file inside the package — is retained. It may carry an optional suggested link default, and an optional when activation condition — the declaration site for §2.3's dynamic-entry when, closing the gap Phase 4 flagged. For v1 the only when is an operating-system match, the wire string "os:<name>" with <name> one of windows / macos / linux; a snippet carrying a when is dynamic (§2.4). The package author owns this declaration: whether a boot snippet is OS-specific is the author's knowledge, not the consumer's.
• [writes] (package-role) is removed (§2.1, §2.7) — a package's materialised footprint is its verbatim tree under its vibedeps/ slot; a per-file write list has nothing left to declare.
• A minimal project-level [boot] table carries workspace-wide loading settings — for v1, only a default link override. Room to grow; nothing more is added now.
• A vibe.lock schema bump may be required to record materialisation slots and inclusion types — assessed in Phase 1.

2.7 Workspace-aware vibe install / vibe build

32Decision. vibe install and vibe build discover the workspace and operate on it as a whole — the piece PROP-007 §6 q3 deferred, now subsumed.

• 33Run anywhere inside a workspace, vibe install calls Workspace::discover, runs one unified resolution across every member's [requires], materialises each resolved package once into vibedeps/ (§2.1), and regenerates the boot artifacts (§2.3) for every entry-point node. One vibe.lock at the absolute root (PROP-007 §2.4).
• The plan / confirm / apply contract holds, but the plan's unit is the set of packages to materialise plus the boot artifacts to regenerate, not a per-file write list — [writes] is retired (§2.6).
• -p <member> scopes resolution reporting to one member; the materialisation and the single root lockfile are always workspace-wide — unified resolution admits no per-member subset.
• A standalone single-package project is a degenerate workspace and follows the identical path (§2.9).

2.8 The computed-view engine — boot and the effective spec

34Decision. The boot artifacts (§2.3) and the effective spec (VIBEVM-SPEC.md §4.6 — the merged corpus consumed by vibe build and vibe show effective) are two projections of one computed-view engine: workspace walk (Workspace::discover) + unified resolution + two-tree layering (§2.1, §2.2).

• 35The boot view projects the boot-category content into the ordered STATIC.md / INDEX.md (§2.3).
• The effective-spec view projects the full layered corpus — authored spec/ plus materialised vibedeps/ — into the effective spec.
• Both are deterministic and regenerated by vibe install.

36The effective-spec view's detailed shape is v1.5 scope (it feeds vibe build). PROP-009 fixes only that it shares the engine, so it is not built as a later retrofit.

2.9 Uniform model — every project is a workspace

37Decision. The loading model is uniform: a single-package project is a degenerate (zero-member) workspace. Workspace::discover already degenerates cleanly (PROP-007 §2.3).

38There is one loading model, one set of artifacts, one code path.

• 39Every existing project migrates (§4). vibevm is pre-release; M1.17's no-legacy hard break is the precedent.
• The vibevm repository, itself a vibevm project, migrates too — vibevm/vibespecs/boot/00-core.xml and 90-user.xml stay user-owned authored boot; the generated STATIC.md / INDEX.md join them.

2.10 Regeneration — vibe reinstall

40Decision. vibe reinstall [<path>] [--force] reinstalls and regenerates the materialised state.

• 41It targets any node in the workspace. Reinstalling a node regenerates that node and every ancestor up to the absolute root — the matryoshka (§2.2) means an ancestor's aggregated artifacts depend on the node's. vibe reinstall run at the root regenerates the whole tree.
• Without --force it recomputes the materialisation and the boot artifacts from the existing vibe.lock and the local cache — no fresh resolution.
• --force re-fetches the file content of the whole targeted subtree from the source repositories, overwriting the current vibedeps/ files and bypassing the cache. The escape hatch for a corrupted, hand-edited, or wrongly-generated subtree.

42It exists for when the materialised state is believed stale or a previous generation pass was wrong.

2.11 Published-copy regeneration

43Decision. vibe workspace publish (PROP-007 §2.7) regenerates the boot artifacts of each staged copy for the published shape — where dependencies are registry-resolved and version-pinned, not path-sourced.

44This consumes PROP-007 §2.5's dual-form { path, version }: the local vibedeps/ slots and path entries become registry references in the published copy's artifacts. Publishing the development tree's own path-resolved artifacts would dangle for an external consumer.