PROP-022 — Materialization modes

1.1 The problem — one materialisation policy does not fit every package

• 03Today every package is materialised the same way: clone into the live-git cache, strip .git into a content tree, then full recursive copy of that tree into the vibedeps/<group>.<name>/<version>/ slot (identity-keyed — owner ruling 2026-08-13; the slot carried <kind>-<name> before that ruling, which collided same-named packages of different groups and moved a package on a kind change).
• This is right for ordinary packages and gives the lockfile a stable content_hash and a committable, offline-reproducible vendored slot.

04It fails at two different scales of "big":

1. 05Big in bytes — a package with a few large binary assets pays a full byte copy per install/update of data that did not change.
2. Big in file count — a package with millions of small files (think the Chromium source tree) is killed not by bytes but by per-file syscalls: copying — or even hardlinking — five million files takes hours, barely faster than re-fetching over the network. The full-tree walk (content_hash reads every file too) is itself the cost.

06The fix is to make materialisation a declared mode on the package, and to borrow the two cost-avoidance primitives VVM already proved (PROP-019 §2.15/§2.16).

2.1 Three modes, declared in the descriptor

07req r1

08[package].materialization selects how the package lands on disk:

[package]
materialization = "copy"       # default | "hardlink" | "in-place"

• 10copy is the default and the only mode an ordinary package needs. (It was named snapshot until the owner's 2026-08-13 terminology ruling reserved that word for the unfrozen version — PROP-044 §2b; the legacy spelling is refused with the rename recipe, never aliased.)
• The mode is published in the descriptor so a consumer sees, before installing, how a package will be placed.

2.2 copy — the vendored full copy (default)

11req r1

• 12Initial placement is live-git cache → .git-stripped shippable tree → full recursive copy into the slot. Refresh is record-aware: the incoming tree is reconciled against .vibe-slot.toml rather than replacing the directory.
• PROP-024 §2.2 extends the .git strip to build output (.vibe/, target/, node_modules/, .vibeignore globs) for code-bearing packages, so such a package vendors its source, never its build artifacts.
• The slot is a self-contained tree, identified by content_hash (§2.5), vendored into the project's git (§2.7).
• Submodule content is embedded into the copied tree (PROP-021 §2.3).
• For copy and hardlink slots, update/reinstall restores the materialiser-owned payload by diffing the incoming shippable tree against .vibe-slot.toml: changed owned files are replaced, stale owned files are removed, equal files stay untouched, and unrecorded build output is preserved. Hooks rerun exactly when that materialisation diff is nonempty, per PROP-020 §2.1.

2.3 hardlink — per-file hardlink, copy on change

13req r1

• 14For packages big in bytes but modest in file count. Initial placement may hardlink source/cache files into the slot, falling back to copy when linking is unavailable. Refresh uses the common .vibe-slot.toml path→SHA-256 footprint: equal files are left in place and a changed destination is unlinked before its replacement is staged, so writing a slot can never mutate the source/cache inode through a hardlink.
• A hardlink that fails (cross-volume / unsupported filesystem) falls back to copy.
• The slot still presents a full shippable tree and its source identity remains content_hash. The slot record is reconciliation and integrity metadata, not a second source identity; unrecorded paths such as target/ remain outside the materialiser-owned footprint.
• This mode does not help the file-count case — the per-file syscall remains — so it is not the giant-repo answer (§2.4 is).

2.4 in-place — git-native, project-local, no copy

15req r1

16For packages big in file count (and incidentally bytes), where even one full tree walk is unacceptable. vibevm never walks the tree:

• 17git clone --recurse-submodules lands directly in the slot, bypassing both the cache clone and the snapshot copy — one physical copy on the machine, not three (decisive when disk cannot hold several copies of a giant).
• git manages it in place: update is git fetch + checkout (incremental, touches only changed objects/files); a hook's edits are reset with git clean -dfx in the slot.
• Project-local, never shared. Each project gets its own clone in its own vibedeps/; there is deliberately no cross-project sharing, which removes the concurrent-mutation problem a shared global clone would create.
• The slot path is not version-qualified. An in-place slot is vibedeps/<group>.<name>/ (no /<version>/): one working clone whose version is the current git ref. Versioning the path would mean two on-disk copies of the giant — the opposite of the goal.
• Requires a git source. Incremental update and git clean reset both need git; a non-git source has no in-place story (§4).

2.5 Identity follows the mode

18req r1

• 19copy / hardlink — source identity remains content_hash; .vibe-slot.toml independently records the owned destination footprint and exact per-file SHA-256 values used for reconciliation and verification.
• in-place — resolved_commit, not content_hash. The slot is a mutable git working tree (hooks edit it), so a content hash is neither stable nor affordable to compute; the git commit is the identity, known in O(1). The lockfile already records resolved_commit, so no new field is needed.

2.6 Destructive operations on an in-place slot need confirmation

20req r1

• 21An in-place slot may be a multi-hour download. Any destructive operation on it — uninstall, reinstall --force, a version switch that requires a re-clone, or slot removal — must be confirmed: interactively a y/n, and in a non-interactive run it requires an explicit flag (--force) or it aborts rather than silently deleting an expensive resource.
• Hooks and their reset (git clean -dfx) are exempt — they are routine and trusted (the hook author is assumed competent, PROP-020).
• The guard protects against accidental loss, not against the package's own lifecycle.

2.7 Vendoring differs by mode

22req r1

• 23copy / hardlink are vendored — the slot is committed into the project's git and is offline-reproducible from it (a hardlink slot's bytes are materialised into git on git add like any file); a copy slot trivially so.
• in-place is not vendored — the slot (a nested .git plus possibly millions of files) is .gitignored in the project; restoration is a re-clone at the lockfile's resolved_commit. The honest trade: in-place packages need the network to restore, where snapshot packages do not.