PROP-030 — The embedded registry

1. Motivation

• 04vibevm ships its own packages in-tree, under packages/.
• When vibe is built and installed from that source tree (vibe self install / self update, recorded with origin = "external" and a source_path), those packages are sitting on disk right next to the binary — yet a consuming project still has to name them explicitly with --registry <path> on every command, or hand-write a [[registry]] block.
• With the packages not published to any network registry (the current state), that friction is the only way to use them at all.

05This PROP makes the in-tree packages/ of a source-installed vibe an ambient default registry — resolved automatically, with zero configuration in the consuming project.

2. The embedded registry

09An embedded registry is a local-directory registry (PROP-002, the M0 LocalRegistry shape — packages/<group>/<name>/<version>/) that vibe derives from its own active install, not from the consuming project:

1. 10vibe reads its active VVM install record (~/opt/vibevm/state.toml, the record whose slot holds current_exe).
2. If that record has origin = "external" and a source_path, and <source_path>/packages exists, that directory is the embedded registry.
3. It is injected into resolution for every project automatically. The project's vibe.toml is never read for it and never written — the default is ambient, carried by the vibe binary, not the project.

• 11Because it is derived from the active install, vibe self use <instance> re-points the embedded registry at that instance's source_path.
• Two source checkouts installed side by side each carry their own embedded registry; switching the active version switches the default.

• 12A managed-origin install (no source tree) has no embedded registry from a source path.
• A future distribution that bundles packages names its bundle location through the same seam (§3.2), at end-user precedence.

3. Precedence

13Resolution keeps PROP-002's explicit-source short-circuits above the embedded registry — an explicit per-dependency source or pin is always deliberate and always wins:

[[override]]  >  path-source  >  git-source  >  ⟨registry layer⟩

15The embedded registry enters the ⟨registry layer⟩, and its position there is the developer↔user inversion:

• 16origin = "external" (developer) — embedded FIRST: embedded > declared [[registry]] walk. On a coordinate clash, the embedded copy wins. This is the vibevm-on-vibevm case (§1.1).
• distribution / end-user — embedded LAST: declared [[registry]] walk > embedded. The bundle is a fall-through.

17If the project declares no [[registry]] at all and an embedded registry is available, resolution uses the embedded registry instead of failing — the build_install_resolver "no registry configured" bail (PROP-002) is lifted when an embedded registry is present.

4. The lock

28A package resolved from the embedded registry records source_kind = "embedded" in vibe.lock (a PROP-002 SourceKind variant beside registry / git / override / path). Its source_url is the file:// path into <source_path>/packages.

29A package resolved from project-local (§3.3) records source_kind = "local" (another SourceKind variant). Its source_url is the file:// path into <project_root>/packages.

• 30source_kind = "embedded" is the marker the reproducibility guard keys on (§5): it says "this entry resolved from a machine-local, source-install-derived directory," which a different machine — a teammate, CI — cannot reproduce.
• source_kind = "local" is portable (per-project, §3.3) and the guard does NOT key on it.

5. Reproducibility guard

• 31A file://<source_path>/packages/... entry (the vibe-embedded registry, §2) is machine-local: a checkout on another box, or CI, has no such path.
• Left unguarded, an embedded-resolved lock committed to a shared repo breaks for everyone else.

32The guard, at the warn + CI-off strength the owner chose:

• 33CI-off. In --frozen (and any non-interactive CI resolution), the vibe-embedded registry is disabled by default — CI must resolve from declared registries (and, since §3.3, project-local), so a machine-local lock cannot silently pass there. Project-local is NOT suppressed by this gate — it is per-project and portable.
• Warn. vibe check warns (does not fail) when the lock carries any source_kind = "embedded" entry: "this lockfile depends on the embedded registry of a source install and is not portable; publish or vendor these packages before sharing the lock." A source_kind = "local" entry is portable and does NOT warn.

• 34This keeps the embedded-registry convenience strictly a developer-machine affordance and stops a non-portable lock from leaking into a shared commit unnoticed.
• Project-local (§3.3) is the portable counterpart — it has the same convenience without the portability caveat.

6. Discoverability

35The embedded registry is ambient but never silent:

• 36vibe doctor reports it: embedded registry: <source_path>/packages (active install #<n>, origin external, precedence first) — or none for a distribution / managed install.
• Resolution output names the source when a package resolves from it ("resolved org.vibevm.world/wal from the embedded registry").

7. Implementation hooks

37Grounded in the current tree:

• 38Origin + source path: ~/opt/vibevm/state.toml already records each install's origin and source_path; the active record is store.active() (crates/vibe-cli/src/commands/vvm/mod.rs). Reuse that store to discover the embedded path.
• Injection point: build_install_resolver (crates/vibe-cli/src/commands/install/resolver.rs). After the explicit --registry branch, resolve the embedded registry (unless suppressed) and compose it with the declared MultiRegistryResolver at the origin-selected precedence; lift the empty-[[registry]] bail when embedded is present.
• Lock: add SourceKind::Embedded (crates/vibe-core/src/manifest/lockfile.rs); tag embedded-resolved entries.
• Guard: thread a frozen flag into resolver construction to drop the embedded registry in CI; add the vibe check warning on Embedded lock entries.
• The same composition serves vibe install, update, and outdated (they share MultiRegistryResolver::open).

8. Edge cases

• 39Source tree deleted / moved: <source_path>/packages missing → the embedded registry is skipped with a vibe doctor warning; resolution falls back to declared registries.
• Non-vibevm packages: the embedded registry only answers for coordinates it actually contains; anything else falls through to declared registries as usual, regardless of precedence.
• The host vibevm project itself: with an embedded registry active, the host can drop --registry packages/ from its own dev workflow — its own packages/ becomes the embedded default (full self-dogfood).

9. Decisions

• 40D1 — precedence is origin-selected, not fixed. Rejected: one global precedence. It cannot serve both the developer (embedded must win, to test local edits) and the end user (bundle must not shadow published packages). The install origin already encodes which case applies.
• D2 — embedded, not local, in name and source_kind. Rejected: --prefer-local / source_kind = "local". "Local" is reserved for a future user-owned-repository feature (§3.2); using it here would collide. D2 revised (§3.3 amendment): the reserved --prefer-local / source_kind = "local" name now lands for the narrower project-packages semantics — a project's own in-tree <project_root>/packages/. The narrower scope (a single well-known directory per project, portable across checkouts) is distinct from the original "arbitrary user-owned-repos" concern, which remains a future expansion under a different name. The reservation was the right call to avoid colliding the two; the §3.3 feature takes the name now that the narrow semantics is shipped and the broader one is still unscoped.
• D3 — explicit sources stay above embedded. Rejected: embedded above overrides / path / git. Those are deliberate per-dependency choices; an ambient default must not override a decision the author wrote down.
• D4 — warn + CI-off, not hard-error. Rejected: hard-error in CI on an embedded lock. The owner chose the lighter guard: CI simply does not use the embedded registry (so a machine-local lock fails to resolve there rather than being rejected), and vibe check warns the developer. Revisit if leaks recur.
• D5 — ambient but visible. Rejected: a purely silent default. vibe doctor and resolution output always surface the embedded registry, so the behaviour is discoverable, not magic.