PROP-011: Incremental install — skip resolution when fresh, materialise only the diff

2.1 Separate resolution from application

08Decision. vibe install is understood as two phases, optimised independently — the current code conflates them.

• 09Resolution — the depsolver: read every node's [requires], pick one version per package. It must stay unified (one vibe.lock, one version per package across the workspace — the diamond problem; PROP-007 §2.4). It cannot be computed per-subtree. But it can be skipped entirely when its inputs are unchanged (§2.2).
• Application — materialise the resolution into vibedeps/, then regenerate boot artifacts. This does not have to replace whole slots. It is an ownership diff: skip identity-current slots and reconcile only changed materialiser-owned files in slots that require refresh (§2.3); boot regeneration is cheap and stays whole-tree (§2.4).

10Resolution being unified does not force application to be whole-tree. PROP-011 keeps unified resolution and makes everything around it incremental.

2.2 Skip resolution when the lockfile is fresh

11Decision. Before running the depsolver, vibe install performs a freshness check: it compares the resolution inputs — the union of every workspace node's [requires] (registry, git, path, and resolved var packages) — against what the current vibe.lock was generated from.

• 12If they are unchanged, the depsolver is not run: the resolution is exactly what vibe.lock already records, and the run proceeds straight to application (§2.3) against the locked versions.
• This makes a vibe install where no dependency declaration changed cost only: discover the workspace, run the freshness check, apply. No network, no version re-selection — milliseconds even on a large workspace.

• 13It also fixes an observable wart. Today vibe install always re-resolves, so it silently bumps a package within its constraint on every run (a ^0.3 pin drifts to the newest 0.3.x available).
• With the freshness check, vibe install becomes lockfile-respecting: unchanged [requires] ⇒ the locked versions are honoured verbatim.
• vibe update remains the explicit "re-resolve and pick newer" command.
• This aligns vibe install with the cargo build / npm install contract — install respects the lock; update moves it — and makes a build reproducible.

• 14When [requires] has changed, resolution runs, but holds the lock for every dependency the change did not touch (§5.3): each registry-resolved root the lock still satisfies is pinned to its locked version, so the re-resolve never drifts an untouched dependency — only the changed one and its subtree move.
• A held pin that conflicts with the change is detected as a depsolver error and falls back to a full, free re-resolve.
• The freshness check itself adds no vibe.lock field: the lockfile is the baseline, and the check is a cargo-style satisfiability test of the locked versions against the current [requires] — see §5.1.

• 15vibe install <pkgref> builds the FULL resolution (bug ruling, 2026-08-24). An explicit-pkgref install solves over the union of every node's [requires] PLUS the named packages — the named ones re-resolved fresh, every untouched root held to its locked pin (§5.3) — never over the named packages alone. The apply phase treats any resolution as the whole world (its prune drops every slot outside it — correct for a full resolution, catastrophic for a partial one): vibe install X --offline used to erase every other slot and rewrite the lock to X's closure. A partial solve MUST never reach apply.
• Zero dependencies is a normal state (bug ruling, 2026-08-24). A bare vibe install over a project whose [requires] union is empty is NOT an error — it is a fresh project. The run regenerates the boot artifacts of the empty world (the authored snippets alone) and exits 0; the old NothingToInstall refusal made vibe init → vibe install fail out of the box.

2.3 Materialise only the diff

16Decision, revised by PROP-054 §9. An identity-current dependency slot is skipped. When a slot must be refreshed, its .vibe-slot.toml is the ownership boundary: materialisation reconciles the old recorded footprint with the incoming shippable tree instead of replacing the whole directory.

• 17Versions are immutable (PROP-002), so presence of the exact resolved version under its current representation may earn the immutable fast path. When refresh is required, whole-directory replacement is still unjustified: the record identifies exactly what the materialiser owns.
• A recorded refresh writes only new or changed owned files, removes only previously recorded files absent from the new footprint, and never removes an on-disk path outside the old record. Equal per-file hashes leave bytes, inode and mtime untouched. A legacy slot without a record pays one final full replacement and receives a record.
• For a vibe install that changed one subtree, this turns a re-copy of the dependency corpus into a per-file reconciliation of only the slots that actually moved.

• 18The skip trusts slot-presence-for-a-version as a proxy for correctness — by default it does not re-hash the slot.
• That is deliberate: hashing every immutable slot on every install would defeat the optimisation. The integrity escape hatch remains vibe reinstall --force (§2.5), which re-fetches and reconciles the materialiser-owned footprint without deleting unrecorded build output.
• Presence remains the default fast-path proof for an immutable, representation-current resolved version. When that proof does not hold, a valid slot record turns refresh into an owned footprint diff; a missing legacy record triggers one final full migration, and a malformed record is a hard error rather than authority to wipe unknown paths.
• Whether the fast path additionally verifies the slot record's source identity and owned-file hashes before trusting it is a configurable strategy — the slot_integrity setting, trust-presence by default (§5.2).

2.4 Boot regeneration stays whole-tree — and why that is fine

19Decision. Boot-artifact regeneration (regenerate_boot over every node) is kept whole-tree. It is not the expensive part, and scoping it is low-value:

• 20It is cheap: per node, an in-memory topological sort plus writing INDEX.md (a small TOML), the redirects (~1 KB each), and STATIC.md only when the node has static dependencies. The cost is O(nodes) small operations, not the corpus-sized I/O of materialisation.
• It does not churn git: git tracks content, so regenerating a byte-identical INDEX.md produces no diff.
• Whole-tree regeneration is self-healing: a boot artifact left stale by an earlier bug is silently corrected on the next install. A scoped regeneration would preserve such staleness.

• 21Scoping boot regeneration to the affected set — a changed node plus its ancestors, the shape PROP-009 §2.10 already specifies for vibe reinstall — is possible but out of scope by owner decision: it is the cheap phase, and effort belongs on §2.2 and §2.3.
• It is recorded here only so the option is not lost: should a workspace ever grow large enough that O(nodes) small writes genuinely matter, §2.10's node-plus-ancestors shape is the ready answer. It is not a deliverable of this PROP.

2.5 Bypasses — no new flag

22Decision. PROP-011 adds no force flag to vibe install. The two skips (§2.2, §2.3) each already have an explicit, named bypass:

• 23to re-resolve even though [requires] is unchanged — vibe update (re-resolves and may pick newer versions; PROP-009 §2.7 / FU3);
• to re-materialise even though the slots are present — vibe reinstall --force (re-fetches from source and reconciles each materialiser-owned footprint; PROP-009 §2.10).

• 24The skips are safe precisely because these bypasses exist.
• Keeping them as the bypass — rather than adding vibe install --force — avoids a redundant flag and keeps each command's job distinct.

2.6 In-workspace file:// sources are mutable

25Decision. §2.2 and §2.3 both rest on version immutability — a locked version is correct content, so its resolution can be skipped (§2.2) and its present slot trusted (§2.3).

• 26That premise holds for a published registry version (PROP-002) and for a content-addressed git ref.
• It is false for a package resolved from a file:// source *inside the workspace — the in-repo self-hosting registry (packages/, --registry packages) the author edits in place while authoring* a package: the source is a working tree whose content changes with no version or [requires] edit, exactly like a path- or git-source dependency (which §2.2 already excludes from the fast path).
• An external local registry or mirror — a file:// path outside the workspace — is a static dependency source, not an edited working tree, so it stays immutable and keeps the fast path.

27So an in-workspace file://-sourced registry dependency is treated as mutable:

• 28Freshness (§2.2): it can never be proven fresh cheaply, so the freshness check reports Stale for it and the depsolver re-runs — re-reading the source and re-hashing it. This mirrors the existing path/git handling: the check is "conservative by construction", so a mutable source yields Stale and vibe install falls back to a full resolution (always correct, and for a local source merely a no-network walk).
• Materialisation (§2.3), revised by PROP-054 §9.3. An in-workspace file:// slot is never trusted by version-presence alone. Resolution re-fetches the mutable source and supplies its current shippable-tree content_hash; a valid slot record carrying the same source_hash earns the materialisation skip. A missing legacy record takes the one-time migration path, a mismatched record flows to record-aware reconciliation, and a malformed record refuses rather than authorising a wipe. Under slot_integrity = "verify", equality of source identity does not hide payload drift: recorded files are still verified and any divergence is repaired through reconciliation. External immutable registries retain the ordinary presence fast path; in-place packages retain their dedicated git-native update path.

• 29Scope — in-workspace file:// only, and not the giants. Confined to file:// sources under the workspace root (the self-hosting registry), which are non-reproducible by nature (a working directory, like a path dependency) and are actively edited — so honouring the edit concedes no reproducibility the source did not already concede.
• The discriminator is is_in_workspace_file_source: the lockfile's source_url has a file:// prefix and its decoded path lies under the (canonicalised, \\?\-free) workspace root (the path test is component-wise and case-insensitive on Windows; a git+file:// local git repo is content-addressed and does not match the file:// prefix).
• It explicitly excludes in-place (PROP-022) packages (materialization.is_in_place()): re-hashing or re-copying a giant working tree on every install is precisely the cost in-place materialisation exists to avoid, so an in-place package keeps the §2.2/§2.3 fast path and is refreshed only through its dedicated incremental path (vibe update <pkg>, the git fetch of PROP-022).
• The choice is source-and-path-based, not mtime-based (§6 rejects mtime — file mtimes do not survive git clone).

30No new flag (consistent with §2.5). This is automatic and source-aware — the author edits the in-repo source and runs vibe install; nothing to remember, and neither vibe update nor reinstall --force is needed for the local-authoring loop, while those bypasses remain for the immutable case.