Пакеты и их виды

Что такое пакет

03Пакет — это проект, который сделали устанавливаемым. У него та же раскладка, что у проекта: собственный vibe.toml и собственный vibevm/vibespecs/, и рядом может лежать код. Когда проект его ставит, опубликованное дерево пакета копируется в дерево зависимостей проекта дословно; ничего не извлекается, не переписывается и не сливается.

04 L4 — packages too. Every package root mirrors the same layout (vibevm/vibespecs inside the package instead of spec/); materialisation mirrors package layout into the slots, boot-snippet paths and INDEX targets follow.

05Пакет называется координатой: группа, косая черта и имя, как в org.vibevm.world/wal. Группа похожа на перевёрнутое доменное имя и говорит, кто публикует; имя уникально внутри группы. Версия дополняет адрес, когда она нужна: org.vibevm.world/wal@1.0.0. Вид в имя не входит. Его можно написать префиксом в командной строке, flow:org.vibevm.world/wal, и тогда vibe проверит, что пакет действительно этого вида.

06 Decision. Package identity becomes (group, name, version, content_hash). kind leaves the identity tuple.

07Группа — заявление, а не удостоверение: никто не проверяет, владеет ли издатель com.google/x этим доменом, и никогда не проверит, потому что у vibe нет центрального проверяющего, которого можно спросить. Имя уникально внутри своей группы, так что координата сама по себе и есть идентичность. В командной строке префикс вида и группа необязательны; в манифесте координата всегда пишется полностью. В реестре репозиторий называется группой и именем через точку, org.vibevm.world.wal, что само по себе корректное перевёрнутое доменное имя.

08 Decision (owner ruling, 2026-08-13). A group is a claim, not a credential. Nothing verifies that the author of com.google/x owns google.com — and nothing ever will: vibevm is decentralised and has no central verifier to delegate to (Maven's central domain verification is the model we deliberately do not inherit). The claim's grammar is domain-shaped (§2.1); its semantics carry no domain-ownership assertion.

09 name becomes unique within a group (was: within a kind, VIBEVM-SPEC.md §7.1). (group, name) is therefore unique on its own — kind is no longer needed to disambiguate.

10 Decision. The pkgref grammar gains an optional group segment and makes the kind prefix optional:

11 The short form is CLI-only sugar. It is never written to a manifest (§2.6).

12 Decision: [<kind>:]<group>/<name>@<version> — identity is qualified since M1.19 (PROP-008 §2.2); the unqualified <kind>:<name>@<version> of VIBEVM-SPEC.md §7.1 is CLI sugar that resolves once, at the human boundary.

13 naming = "fqdn" maps a pkgref to the repository name <group>.<name> (org.vibevm.world/wal → org.vibevm.world.wal) — the composite is itself a valid reversed FQDN, and that is the point of the ruling. Owner ruling 2026-08-13 («убери подчёркивания везде, чтобы получились настоящие FQDN с доменными правилами»), superseding the 2026-05 _-joiner decision recorded in this unit's earlier text. The split stays deterministic without a charset-excluded joiner: the name is a single dot-free LDH label (validate_package_name), so the last dot is always the boundary — parse back by taking the last label as name, the rest as group. The old rationale's premises are both gone: _ was then legal inside groups (no longer — §2.1 LDH), and the composite was not required to be a domain (now it is). Considered and rejected: keeping _ (the composite is not even formally a domain; and a _-joined name contradicts the LDH ruling the halves now obey). Migration: live _-joined repositories in vibespecs (M0/M1 scale) rename to the dot form as a follow-up of the 2026-08-13 landing — pre-public and cheap, and GitHub redirects renamed repositories; the §3 history below records the _-era as it happened and is not rewritten. Revisit: a hosting provider that forbids . in repository names appears in the registry set — then that provider's adapter gets its own naming value, never a silent re-join.

14Где бы пакет ни назывался в проекте, стоит полная координата: group/name в требовании, group.name как имя репозитория, group/name как первый сегмент адреса spec://. Короткие имена живут только там, где человек один раз набирает их в командной строке.

15 A package address MUST carry its full coordinate — group and name — in every occurrence across the project:

16 [<kind>:]<group>/<name>

17 <group>.<name> — / is illegal in a repo name; the name is the last label

18 <group>/<name> — the name is the first path segment

19 Short or bare names survive only as a one-time human CLI input, resolved to the qualified form at the boundary (PROP-008 §2.6).

Восемь видов

21Набор закрыт и растёт только поправкой к спецификации; манифест с неизвестным видом отвергается, а не угадывается.

22 kind ∈ {flow, feat, stack, tool, mcp, lang, doc, app} — eight kinds; mcp shipped with PROP-027; doc and app admitted by PROP-057 through the VIBEVM-SPEC.md §4.1 amendment of 2026-09-12 (pending the owner's ratification at the merge of the docs-2026-09 branch; the code learns the two kinds in that campaign's phase 2). (§Invariants INV-VOCABULARY in this file carries the same list.)

23Вид — метаданные пакета, а не часть его идентичности: он решает, куда кладётся содержимое, что показывает фильтр --kind у vibe list и vibe search и принимается ли имя с префиксом вида. Два пакета разных видов не могут делить координату, потому что координата сама по себе и есть идентичность.

24 Decision. kind (flow / feat / stack / tool) stays a mandatory [package] field but is now a pure attribute — it identifies nothing and names nothing.

25app отличается от tool механически: инструмент живёт в проекте и запускается через vibe bin exec по лок-файлу, а приложение не живёт ни в каком проекте-потребителе и собирается и выкладывается само по себе.

26 The boundary with tool is mechanical: a tool lives in a project and runs through vibe bin exec by the lock file; an app runs nowhere in a consumer project and is built and deployed on its own.

Семейства и компаньоны

27Некоторые возможности приходят несколькими пакетами с общей основой имени: языковой гайд, сервер, который отдаёт его инструменты, и маленький бандл, который закрепляет оба на одной версии. Это семейство. Потребовать бандл — значит поставить семейство, а изменение любого члена поднимает всех до одной общей версии, так что части никогда не разъедутся.

28 Within a family the members move in unison: a content change to any member bumps EVERY member of that family to one shared version, and the aggregator's version IS that family version.

29Сам бандл — самый маленький пакет из возможных: манифест и README, ни кода, ни стартового фрагмента. Его единственная работа — назвать членов семейства одной версии.

30 <family> — the aggregator. kind = "stack", content-minimal: a vibe.toml and a README.md, and nothing else — no code, no boot snippet, no specmap.toml / conform.toml. Its whole job is to name the family's members at one resolved version set through exact =X.Y.Z pins in [requires]. Requiring the aggregator installs the family.

31Документация — исключение. Руководство пакета — его компаньон с суффиксом -docs в той же группе, и оно держит собственную линию версий. Исправленная опечатка в руководстве не выпускает инструменты, а новая версия инструмента не требует нового руководства. Руководство говорит, какие версии своего предмета оно описывает, а сайт берёт самое новое руководство, которое подходит.

32 <family>-docs — the documentation companion (kind = "doc", PROP-057 §3): the official-by-default documentation of the family's subject, in the subject's group. Unlike the three code roles it is a companion, not a member: it is never pinned by the aggregator, it does not take part in the family's unison (§2.2), it keeps its own version line, and it states compatibility with its subject through the version constraint of its [[documents]] table. Its translations follow the same companion form, one package per language, named <family>-docs-<lang> with a lower-case BCP-47 tag (rust-ai-native-docs-ru). Amended 2026-09-11.

Как пакет ложится на диск

33[package].materialization говорит, как пакет попадает в дерево потребителя. copy — умолчание и всё, что нужно обычному пакету; hardlink — то же содержимое, делящее байты с хранилищем. Оба вендорятся: папка коммитится вместе с проектом и восстанавливается из него без сети. in-place держит живой git-чекаут с собственным .git, который git игнорирует и который свежий клон восстанавливает на закреплённом коммите, поэтому ему нужны сеть и git-источник. Всё разрушительное над таким слотом — удаление, принудительная переустановка, смена версии — сначала спрашивает, а когда ответить некому, требует --force.

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

35 copy 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.)

36 copy / 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.

37 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.

38 Requires a git source. Incremental update and git clean reset both need git; a non-git source has no in-place story (§4).

39 An 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.

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

40Смена группы или имени пакета создаёт новый пакет, а не переименовывает старый: версии не переносятся, а старые координаты никогда не используются повторно для другого содержимого.

41 Changing a package's group is a new package, not a rename — same discipline as changing name.

42Пакет документации нельзя установить в проект. vibe install отказывает и называет команду, которая вместо этого скачивает его для чтения.

43 vibe install MUST refuse a doc package with a hint naming the warm-up command; documentation is warmed into the machine store with vibe cache add (§11), and the local reader and vibe explain read the store.

44Короткое имя без группы, например wal, принимается в командной строке и разрешается через индекс реестра; это удобство, а манифест всегда записывает полную координату.

45 resolved via the index (§2.6)

46 vibe install wal resolves the collision once, at the top level, and writes org.vibevm.world/wal into [requires]. Manifests are therefore always qualified — exactly the cargo/npm pattern (cargo add serde on the CLI, serde = "1" in Cargo.toml).

47Разрешить короткое имя можно только через индекс, по одному запросу на реестр; реестр без индекса коротких имён не предлагает, и нужна полная координата. Если лок-файл уже закрепил пакет с таким именем, короткое имя означает закреплённый. Когда два реестра предлагают под одним именем разные пакеты, vibe останавливается с кодом выхода 7 и перечисляет кандидатов, а вы повторяете команду с группой. Префикс вида проверяет результат и никогда не снимает неоднозначность, потому что два пакета разных видов не могут делить координату.

48 Index dependency. Resolving a short name requires enumerating candidates (*, name) across registries. The host cannot list an org cheaply (PROP-005 §1 — GitVerse exposes no org listing, GitHub is rate-limited). Therefore short-name resolution requires PROP-005: one HTTP GET of by-name/<name>.json per registry yields the candidate set. Without an index, a registry's short names are unavailable and the qualified form is required.

49 Lockfile is authoritative. If vibe.lock already pins org.vibevm.world/wal, a later vibe install wal resolves to the locked entry — the short name prefers what is already locked.

50 One candidate → resolve. Multiple candidates with different identity → collision:

51 A new exit code 7 ("ambiguous package") is assigned, distinct from 3 ("package conflict", VIBEVM-SPEC.md §9.4).

52 kind validation. If the kind prefix is present, after resolution the resolver asserts resolved.kind == prefix; mismatch is a KindMismatch error. A kind prefix is validation + a UX signal — it does not disambiguate, because by §2.2 name is unique within a group, so flow:org.vibevm.world/wal and feat:org.vibevm.world/wal cannot co-exist. A short-name collision is always a group collision (§2.7), resolved by group-qualification, never by kind.