Лок-файл и машинное хранилище

Идентичность — это содержимое, а не адрес

03Версию пакета определяют четыре вещи: его группа, имя, версия и отпечаток каждого файла внутри. Адрес, откуда её скачали, записан только для сведения. Поэтому зеркало, переехавший репозиторий или вендоренная копия никогда не меняют лок-файл: пока байты те же, пакет тот же.

04 Decision. A package's identity is the tuple (kind, name, version, content_hash). The content_hash is a digest over the deterministically-ordered concatenation of (rel_path_bytes || 0x00 || file_bytes || 0x00) for every file in the package directory, and the value names the recipe that produced it (PROP-044 §4.7): sha256-tree/1:<hex> is recipe 1, whose exclusion list, path normalisation and traversal order are carried as data in formats/hash_recipes/1.toml; the bare sha256:<hex> is recipe 0, the pre-recipe form, frozen verbatim in code — not configurable, because a frozen recipe that can be edited is not frozen — so that values written before recipes were named stay readable. Two hashes are comparable only at the same recipe; comparing across recipes answers a question nobody asked, and is never done silently. PROP-024 §2.2 re-scopes this to the package's shippable tree — its source, minus build output (.git/, .vibe/, target/, node_modules/, .vibeignore globs) — so a code-bearing package's identity is its source, not its build state; that exclusion lands with the code that implements it. The URL used to fetch the content is informational — recorded in the lockfile for debuggability, not for identity.

05Отпечаток — ещё и ворота целостности. Если источник отдаёт под известной версией другие байты, потому что тег перезаписали силой или зеркало подменили, vibe отказывает раньше, чем что-то запишет, и говорит, какой отпечаток ждал и какой увидел.

06 a force-pushed tag upstream is caught by the same machinery on the next install.

Лок-файл

07vibe.lock перечисляет каждый пакет разрешённого графа, прямой и транзитивный, с точной версией, отпечатком, реестром, откуда он пришёл, и способом, которым его разрешили. vibe пишет его при каждой установке и обновлении; вы его коммитите и никогда не правите. Свежий клон с лок-файлом ставит тот же самый граф, а пулл-реквест, который его меняет, показывает ровно то, что сдвинулось.

08Лок-файл сохраняется, даже когда выведенное состояние удалено: vibe clean стирает дерево зависимостей и сгенерированные стартовые файлы, но лок не трогает, потому что лок — это записанное решение, а дерево — только его следствие.

09 Never touched — vibe.lock. The lock is the recorded resolution, not derived state: keeping it is what makes vibe clean install --offline reproduce the exact world from the machine cache with zero network — the mvn analogy is target/ vs the dependency resolution, and the lock sits on the resolution side.

Машинное хранилище

10Каждый пакет, который vibe скачивает для любого проекта, попадает в одно хранилище в вашем домашнем каталоге, ~/.vibe/cache/, с ключом по идентичности пакета, а не по тому, откуда он пришёл. Версия, скачанная для одного проекта, доступна каждому другому проекту на машине, какие бы реестры они ни настроили, и хранилище никогда не очищается у вас за спиной: освободить место — это команда, которую запускаете вы.

11 Decision (override clause corrected 2026-08-20 to the later, more specific ruling). The package store is machine-global, not project-scoped — one store per machine at <settings-home>/cache, relocated only with the settings home ($VIBE_SETTINGS); no store-specific override exists — ##THE-STORE-IS-DOT-VIBE-CACHE is the governing ruling. (VIBE_REGISTRY_CACHE, which this decision originally named, governs the registry clone cache — a different layer that keeps its own job.)

12 Decision (owner, 2026-08-20): the store is ~/.vibe/cache/, beside ~/.vibe/registries/ (the registry git clones, which keep their own separate job) and under the one settings home.

13 Reclaiming space is an explicit operator action (§2.8), never a surprise.

14Хранилище можно прогреть намеренно. vibe cache add скачивает пакет и всё, от чего он зависит, не касаясь ни одного проекта; так готовятся к перелёту и так машина получает руководство пакета для чтения без сети. vibe cache list показывает, что лежит в хранилище; vibe cache check сверяет каждую запись с её отпечатком.

15 content_hash is the integrity gate: a cache entry is valid only if its content hashes to the recorded hash. Two sources claiming the same identity with divergent bytes are a collision, surfaced per PROP-008's collision rules, never silently merged.

16 vibe cache add <pkgref>… — deliberately pre-warm: fetch a package and its dependency closure into the cache while online, so a later --offline run finds it. The "I am about to go offline, pull down what I will need" workflow. It fetches from the project's [[registry]] when run inside a project, otherwise from the user-level registries (§2.4).

17 vibe cache list — the packages and versions present locally; the offline-resolvable inventory.

18 vibe cache check (owner, 2026-08-20) — the integrity sweep, and the only place the store is fully re-hashed. It walks every entry, recomputes the content hash, and reports each one that no longer matches what was recorded. It is the answer to «how do you forbid overwriting»: nothing forbids it, and this is what notices. («What was recorded» is an integrity sidecar v<version>.sha256 written once beside the entry at insert — beside, not inside, or the record would change the very tree it pins; an entry without one is the honest unrecorded class, not an error.)

19vibe cache clean освобождает место: всё целиком, по возрасту или по пакету, и только когда вы скажете, что именно.

20 vibe cache clean — reclaim space: all, by age, or by package.

Без сети

21С --offline или с VIBE_OFFLINE=1 в окружении vibe не касается сети вовсе. Подбор версий и скачивание обслуживаются из хранилища, локальных зеркал, собственного дерева зависимостей проекта и путевых источников. Всего, чего там нет, — жёсткая ошибка с именем недостающего пакета; vibe никогда молча не ставит частичный результат.

22 Decision. A global --offline flag forbids all network access for the invocation.

23 Anything not available locally is a hard error with an actionable message: it names the missing package and version and tells the operator how to recover (run once online, vibe cache add, or vibe registry vendor).

24Версией в хранилище можно пользоваться, даже если её больше не перечисляет ни один реестр. Хранилище держит байты, которые проверили, когда они пришли; замолчавший реестр не делает их хуже.

25 Decision (owner, 2026-08-19). A package version present in the cache is usable, and materialises, even when it exists in no registry at all — deleted upstream, the whole organisation gone, every mirror down. This is not the --offline policy: --offline forbids the network, while this governs a run where the network is allowed, was consulted, and answered "no such package". (Built 2026-08-20: the fallback fires strictly on the absence forms and rides the LOCKFILE pin — provenance comes from the existing lock entry, so a version in the store but in no lock and no registry is not rescued; minting a store-provenance wire form for that case is an owner act, held open.)

Особые случаи и правила

26Папка настроек, включая хранилище, — это ~/.vibe/ на любой платформе; переменная окружения VIBE_SETTINGS переносит всю папку, и так тесты и сборочные серверы держат приватную копию.

27 The settings home is ~/.vibe (owner, 2026-08-20). This document previously named ~/.config/vibe/config.toml; the code has treated ~/.vibe as canonical all along and the XDG path only as a legacy location an operator is invited to migrate out of. The correction is to this document, not to the tree.

28Хранилище и кэш клонов реестров — две разные папки: хранилище держит распакованные версии пакетов, кэш клонов под ~/.vibe/registries/ держит git-чекауты, которыми их скачивают. Очистка одной не очищает другую.

29 Decision (owner, 2026-08-19). The on-disk layout is per-identity extracted directories, one per (group, name, version). Git clones indexed by identity are rejected.