PROP-038: Hybrid boot linking — per-package compilation units with soft/hard static edges

2.1 Every materialised package is a compilation unit

10Decision. Every package materialised under vibedeps/ carries its own boot artifacts — vibedeps/<slot>/spec/boot/STATIC.xml (what is compiled into this unit, verbatim) and .../INDEX.md (this unit's external dynamic references, resolved when the unit loads) — not only entry-point workspace nodes.

11This changes PROP-009 §2.3's "for every entry-point node" to "for every compilation unit (entry-point node or materialised package)".

12A unit's STATIC.md is self-contained and reversible (open/close markers, PROP-035 §11): reading it, an agent gets this package and everything statically linked into it, in dependency order, once each — the PROP-034 dedup + topological-order + cycle-rejection invariants, applied within the unit.

13The unit artifact serves dynamic consumers (an INDEX.md reference loads the whole zone through it) and standalone unit reads; a static consumer whose lane already compiles the unit's zone member-by-member elides the aggregate entry to a provenance stub instead of embedding the artifact — the once-each rule of PROP-009 §2.3 ##STATIC-EMITS-ONCE-EACH (B-006, owner-approved 2026-08-04), applied at compose time and distinct from §2.4's hoisting, which shares one copy across consumers rather than deduplicating within one lane.

2.2 The edge is the linker instruction; compilation is recursive and dynamic-bounded

14Decision. link is a property of the edge (consumer-side, declared in the parent's manifest), never baked into the pulled package (as PROP-034 §2.1 already states). A unit P is compiled by walking its own direct edges P→X:

• 15static — X's STATIC.md is compiled into P's STATIC.md. Compilation recurses down X's own static edges; a nested dynamic edge inside X breaks the recursion (that target stays an INDEX.md reference). static therefore respects the modes below it.
• dynamic — X is not compiled; it becomes an [[entry]] in P's INDEX.md. The static zone breaks at this edge.
• static-transitive — X and its entire subtree are forced static, ignoring any dynamic edges inside — "rewrite the whole tree under X". This is the one mode that overrides nested breaks.

16The difference between static and static-transitive is exactly this treatment of nested dynamic edges: static honours them (breaks), static-transitive overrides them (forces).

17Worked example — root → A(dynamic) → B(static) → C(dynamic) → D(static-transitive):

2.3 Two static modes — static-soft (default) and static-hard

19Decision. The static side has two modes, differing in where duplication is deduplicated:

• 20static-soft — the default, the meaning of a bare link = "static". Hoisting dedup at compile time: a package statically linked by more than one consumer is hoisted to a shared location (§2.4) and linked once; each consumer references it. Deterministic; does not depend on read-time behaviour.
• static-hard — explicit opt-in (link = "static-hard"). Pure local compilation: every consumer compiles the package into its own STATIC.md independently, with no hoisting. Duplication is deduplicated at read time by the read-set (§2.9).

21Why soft is the default (owner decision, 2026-07-15). A forgotten qualifier must fail toward correctness, not toward implicit duplication.

• 22When the same package is compiled into several units unhoisted, the model sees the same prompt several times and can be confused about which copy is authoritative — a correctness hazard the owner weighs above the "explicit-over-implicit" cost of a smart default.
• static-hard remains for the deliberate case where a package must load only with its consumer (lazy locality preferred over dedup) even at the price of on-disk duplication.

2.4 Soft hoisting targets the LCA of the static-zone, not always the global root

23Decision. A hoisted package rises to the least common ancestor within a continuous static zone of its consumers, not unconditionally to the global root:

• 24Within one static zone (consumers share a static ancestor Z reached by an unbroken chain of static edges) → hoist into Z's STATIC.md. Dedup achieved and the package still loads only when Z loads: laziness is preserved. Within-zone hoisting is free and always done.
• Across dynamic zones (the consumers' common static ancestor does not exist because a dynamic edge separates them) → the only shared always-loaded location is the global root STATIC.md, and hoisting there makes the package eager (loaded even when its dynamic consumers are not). This is the one real cost of soft, paid only for cross-zone sharing.

25Consequences, all deliberate:

• 26Hoisting needs a global pass counting the static-consumers of each package (partially re-introducing global analysis the per-edge model otherwise avoids) — the price of compile-time dedup. Recorded as a change-detection cost in §2.7.
• Hoist transitivity. Hoisting L hoists L's own static sub-zone with it (else the hoisted L references code not present at the hoist point).
• A static-declared package can be hoisted past an edge that named it static only within its static zone; a dynamic edge is always a hoist barrier (crossing it is the eager cross-zone case above).

2.5 Hoist markers — the two ends of a lifted edge

27Decision. When soft hoists L out of a unit P's local STATIC.md, two markers preserve correctness — the reversible two-ended shape PROP-035 §7/§11 already defines:

• 28In P's STATIC.md, where L's text used to be: a #use spec://…/L directive (PROP-035 §7.2). It preserves the P→L graph edge locally and tells the agent "L is part of me; its text is lifted and already read above — do not duplicate." The read-set (§2.9) gates the re-read, so no duplication reaches context.
• In the hoist target (Z's or the root's STATIC.md), at the lifted block: a shared-by hint comment naming the consumers (shared by P, Q, R). It explains to the model why L is here and not local, and asserts this is one shared version — not a duplicate to reconcile.

29Both markers are generated, are part of the reversible marker set, and must be regenerated on recompilation.

2.6 The single-version invariant this rests on

30Decision (recording a closed question). Soft dedup is correct because the resolver guarantees one version per (kind, name) across the workspace — resolvo enforces single-version-per-name automatically (PROP-017 §3), and genuinely incompatible constraints fail as Unsatisfiable (PROP-017 §2.4) rather than coexisting. Therefore:

• 31A hoisted package is one shared version; there is never "two versions of B side by side" in a STATIC.md.
• The proposed "group different versions together + a divergence hint" feature is not needed — the situation it guards against cannot occur (confirmed 2026-07-15). Should the resolver model ever change to permit coexisting majors (a large, separate decision), this section is the trigger to revisit the hint mechanism.

32Conflict resolution (how an author forces the single chosen version) is out of scope here and documented in docs/faq/version-conflicts.md ([[override]], git-source, version.var).

2.7 Change-detection — a Merkle fingerprint over the boot graph

33Decision. Each unit's STATIC.md carries a fingerprint of the inputs it was compiled from — a Merkle hash over the unit's compilation zone:

fp(P) = hash(
    content_hash(own_boot(P)),                       // P's own boot text
    [ link_type(P→X) for each edge ],                // dynamic↔static switches
    [ fp(X) for each static / static-transitive edge P→X ],   // recurse into the zone
    [ identity(Y) = (group,name,version) for each dynamic edge P→Y ],  // dyn edge: identity only
    soft_hoist_inputs(P)                             // §2.4 global static-use counts touching P
)

35Properties:

• 36A dynamic edge breaks fingerprint propagation — exactly as it breaks compilation. A change behind a dynamic edge changes fp(Y) but not fp(P) (only Y's identity enters fp(P)); Y's unit recompiles independently.
• Any change inside a static zone — content, version, edge set, or a link-type switch (which resolution does not see, §2.8) — flips fp up the continuous static chain to the first dynamic break.
• The soft-hoist term makes a single→multi static-use transition (a new consumer statically links L, so L must now hoist) flip fp for the affected units — the nonlocal invalidation soft costs, made explicit so tests target it (§3).

37Fingerprint storage location and granularity were open here; §5 resolved both on 2026-07-15 — header storage (RES-FP-STORAGE) and per-package granularity (RES-GRANULARITY).

2.8 Incremental regeneration — the dirty subgraph

38Decision. Boot regeneration recompiles only the units whose fp changed (the dirty subgraph), replacing PROP-009's / PROP-011's whole-tree regeneration.

• 39PROP-011 §2.4 kept boot regeneration whole-tree because it was cheap (a small INDEX.md per node); with verbatim per-package compilation (§2.1) that rationale no longer holds — a STATIC.md is now real concatenated text — so the incremental path becomes load-bearing.
• The fast path: an unchanged root fp ⇒ zero recompilation, zero git churn (idempotency).

40This is the standard build-system shape — a cargo-fingerprint / Bazel-action-graph dirty-subgraph. The materialisation step is already incremental (PROP-011 §2.3); this brings boot regeneration to parity.

2.9 Read-set — the read-time dedup

41Decision. The @spec/#use read-set (PROP-035 §7.4 — a persistent { specpath, content_hash } record, "read once") is the dedup mechanism for (a) static-hard duplication across units, and (b) the #use markers soft leaves in local units (§2.5).

• 42It is a load-bearing prerequisite, not optional: without it, static-hard duplicates and lifted #use targets would re-enter context.
• Its known weakness across context compaction (PROP-035 open question #2) applies; soft's compile-time dedup is the mitigation for the common case.