PROP-008: Qualified package naming — groups, short aliases, collision detection

**Milestone:** `M1.18` + `M1.19` ([`ROADMAP.md`](../../../ROADMAP.md)) — **shipped**, implementation-locked. (The line read "design proposal … not implementation-locked" until 2026-07-25; it had never been reconciled with the IMPLEMENTED status one line below.)

**Status:** IMPLEMENTED — Phases 1–4 + 7 landed 2026-05-22 (M1.18, see §7); Phases 5–6 + 8 landed with M1.19 (index-backed short-name resolution at the CLI boundary — `vibe-cli::commands::short_name`; collision detection with exit code `7` — `InstallError::AmbiguousPackage`; the live-registry fqdn migration). Decision units typed at REQ grain 2026-06-12 (the depth program).

**Design rationale:** [`vibevm/vibespecs/design/workspace-and-qualified-naming.xml`](../../design/workspace-and-qualified-naming.xml) — the *why* and the lore behind this PROP: the owner's mental model, the fork-by-fork decision record, the Cargo-vs-Maven precedents. Non-normative; this PROP is the contract.

**Discipline:** the general namespace-scaling laws — why a flat namespace fails, the mandatory *group*, the identity tuple, why a rename is a new identity, why short names live only at the human boundary, and why a *collision* and a *conflict* are different failures — are the `qualified-naming` flow: `spec://org.vibevm.world/qualified-naming/flows/qualified-naming/QUALIFIED-NAMING-PROTOCOL#root`. This PROP is vibevm's IMPLEMENTED instance of them — the `org.vibevm.*` groups, the CLI short-name resolution (`vibe-cli::commands::short_name`), and collision detection (`InstallError::AmbiguousPackage`).

**Owner sanction:** the owner granted (2026-05-20) explicit sanction to edit any specification, including `VIBEVM-SPEC.md` §7.1. PROP-008 is the requirements record; the `VIBEVM-SPEC.md` edit lands at implementation time.

`req r1`

**Decision.** `[package]` gains a **mandatory** `group` field:

[package] kind = "flow" name = "wal" group = "org.vibevm" version = "0.3.0" Reverse-FQDN is the **recommended convention**; the core does **not** enforce it. Whether `group` looks like a reversed domain is a matter of style, left to humans and linters. (Maven likewise does not enforce groupId shape.) Grammar (owner ruling 2026-08-13 — «настоящие домены»): dot-separated segments, each an **LDH hostname label** — `[a-z0-9-]+`, ASCII lowercase, hyphen never at a label edge; `_` is forbidden (it is not legal in a domain). Interior doubled hyphens stay legal, as DNS itself allows (`xn--…` punycode). A group is therefore grammatically a valid reversed FQDN even though semantically it is a claim, not a credential (§2.10). Enforced by `Group::parse`. *Considered and rejected:* keeping `_` (groups would not even be formally domains, and the flat `<group>.<name>` carrier §2.5 would lose its unambiguous split); recording "FQDN-like, not FQDN-valid" as a deliberate looseness (the ruling chose real domain rules). *Revisit:* a real-world group needing `_` appears — it cannot, if groups track domains. The core grammar requires **≥ 1 segment** — `acme` parses. Requiring ≥ 2 segments, reverse-FQDN shape, or any other domain-likeness is **registry policy**, enforced at registration time by the registry's moderation or web surface (owner ruling 2026-08-13), never by the core. Short single-segment groups are the norm for local registries (§2.10). `group` is mandatory as of this PROP. The three then-current canonical packages migrated to `group = "org.vibevm"` (§3) — the owner's reverse-FQDN, recorded at the time as the one canonical group. Superseded on the group's NAME by PROP-029 (2026-07-12): first-party packages now live under `org.vibevm.world` and `org.vibevm.ai-native` (and `org.vibevm.fractality`); the mandatory-group law itself is unchanged and live in every manifest.

`req r1`

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

`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. `content_hash` is unchanged — computed over package file bytes per [PROP-002 §2.1](PROP-002-decentralized-registry.xml#identity). `group` lives in `vibe.toml`, so it influences the hash only as ordinary file content; the tuple lists it explicitly so that changing `group` yields a different package. Changing a package's `group` is a new package, not a rename — same discipline as changing `name`.

`req r1`

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

It is still needed for:

content placement — `spec/flows/` vs `spec/feats/` vs `spec/stacks/`; the `--kind` filter on `vibe list` / `vibe search`; the UX signal in a kind-prefixed pkgref (§2.4).

The kind taxonomy (`VIBEVM-SPEC.md` §4.1 — four kinds when this PROP was written; six today, `mcp` and `lang` joined by PROP-025/027 and the 2026-08-06 ruling) is unchanged in importance — it simply stops being part of identity and repository naming, whatever its member count.

`req r1`

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

pkgref := [ <kind> ":" ] [ <group> "/" ] <name> [ "@" <version> ]

The `group`↔`name` separator is `/` (`:` is taken by `kind`, `@` by version).

Form	Context	Behaviour
`org.vibevm.world/wal`	qualified — the form written into manifests (see §2.6, [PROP-002](PROP-002-decentralized-registry.xml))	resolved exactly
`flow:org.vibevm.world/wal`	qualified + kind	resolved exactly; kind validated against the manifest
`wal`	short — CLI sugar	resolved via the index (§2.6)
`flow:wal`	short + kind	resolved via the index; kind validated

**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. **The short form is CLI-only sugar.** It is never written to a manifest (§2.6).

`req r1`

**Decision.** `kind` leaves the repository name. A new `[[registry]]` naming convention value:

[[registry]] name = "vibespecs" url = "https://github.com/vibespecs" naming = "fqdn" # repo name = "<group>.<name>" → org.vibevm.world.wal `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. Because `(group, name)` is unique (§2.2), `<group>.<name>` is a collision-free repo name without needing `kind`. The existing `kind-name` / `name` / `kind/name` conventions (PROP-002 §2.2) remain for registries that have not adopted `group`. This realises the owner's "short name in the CLI, fat name in the repository" goal: the repository is the pure reverse-FQDN; the CLI keeps the short alias.

`req r1`

**Decision.** A short name (`wal`, `flow:wal`) is resolved **only at the CLI input boundary** — through the index, or from `vibe.lock` alone where the verb acts on installed state (`##INSTALLED-STATE-RESOLVES-LOCALLY`). Manifests always store the qualified form.

`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`). **Consequence — no transitive collisions.** Every package's `[requires]` is qualified (its author published through the same flow). The dependency graph is built from qualified names; short-name resolution never recurses into the graph. It happens once, for a human-typed CLI argument. **Index dependency.** Resolving a short name requires enumerating candidates `(*, name)` across registries. The host cannot list an org cheaply ([PROP-005 §1](../vibe-index/PROP-005-package-index.xml) — GitVerse exposes no org listing, GitHub is rate-limited). Therefore short-name resolution **requires [PROP-005](../vibe-index/PROP-005-package-index.xml)**: 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. **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. **A verb that acts on an already-installed package resolves a short name from `vibe.lock` alone — no index, no network.** `vibe uninstall wal` and `vibe update wal` operate over installed state, and the lockfile *is* that state's record, so the answer sits in the file beside them and `##INDEX-DEPENDENCY` does not bind: a name the lockfile does not carry is **not installed** — a local failure with a local remedy, never a lookup that could not be performed. Requiring the qualified form there would be a restriction with no cause behind it. The counter-case is the registry-side redirect verbs (`vibe registry redirect`, `redirect-sync`, `redirect-update`), which create and maintain a stub for a package that need **not** be installed at all: there is no lockfile to answer from, so `##INDEX-DEPENDENCY` binds as written and the qualified form stays required — an honest requirement rather than an unfinished one.

`req r1`

**Decision.** Two distinct failure classes, with distinct handling. This terminology is fixed by this PROP.

**Collision (a naming ambiguity).** Two *different* packages match one short name (`wal`) with different `group`. Detected during short-name resolution (§2.6). **Conflict (a dependency conflict).** The depsolver cannot satisfy version constraints — incompatible constraints, declared `[conflicts]`, an unsatisfiable diamond. Already handled (PROP-002 §2.9 — resolvo/libsolv conflict-explanation chain).

Collision handling (new):

The resolver collects *all* candidates of a short name — it does **not** stop at the first registry. (PROP-002 §2.2's first-match-wins remains correct for the *same* package mirrored across registries — identical identity. It is wrong for *different* packages sharing a short name; the two are distinguishable only once `group` exists.) One candidate → resolve. Multiple candidates with different identity → **collision**: interactive TTY — print the alternatives and fail with a hint pointing at the qualified form (no interactive pick: the choice must be recorded deliberately, not clicked); `--unattended` / full-auto — fail-fast; the resolver never guesses. A new exit code **`7`** ("ambiguous package") is assigned, distinct from `3` ("package conflict", `VIBEVM-SPEC.md` §9.4). flow:wal is ambiguous — 2 packages match: 1. org.vibevm.world/wal (registry vibespecs) 2. com.acme/wal (registry acme-internal) Re-run with the qualified form, e.g. `vibe install org.vibevm.world/wal`.

Conflict handling is unchanged: the install pipeline is already atomic (resolve → plan → confirm → apply); a failed resolve never reaches apply — "fail without applying the plan", as the owner specified.

`req r1`

**Decision.** [PROP-005](../vibe-index/PROP-005-package-index.xml)'s entry schema (§2.6) gains two fields: `group` (mandatory, §2.1) and `workspace_origin` (optional — set when the package was published from a workspace, [PROP-007 §2.8](../vibe-workspace/PROP-007-workspace.xml) `[origin]`).

The `by-name/` layer indexes by `name` and returns the candidate set with each candidate's `group`, so §2.6 short-name resolution is one GET per registry. PROP-005 was a draft when these edits were written; it has since shipped (implemented, folded into the workspace 2026-05-22), and the §2.8 edits below live in that implemented contract.

`design r1`

**Decision (forward-looking, out of implementation scope).** The index makes a Maven-Central-style browsable visualisation possible — and richer. A **vibevm registry explorer** is recorded here as a long-term direction (a `ROADMAP.md` M3+ entry):

a reverse-FQDN group tree with drill-down (`org` → `org.vibevm` → packages → versions), as Maven Central does; beyond Maven Central: filter by `kind`; a capability graph (`[provides]`/`[requires]`); `describes`/PURL links to upstream libraries; redirect-stub delegation; the full dependency DAG; and **workspace provenance** ("Y is a sub-package of X", from `workspace_origin`). The explorer is a separate, optional layer over the index — not part of PROP-008's implementation. PROP-005 §2.10 already reserves the hook (`vibe-index serve`, CORS-open read endpoints). The only obligation on this refactor is that the index carry `group` and `workspace_origin` (§2.8) so the explorer is not a retrofit later.

`req r2`

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

**Domain existence is never checked, in any layer, ever.** No resolver, registry client, publisher, or linter of the core performs a DNS lookup or any other existence/ownership test on a group. A future contributor "improving" this would be reverting an owner ruling. **Within one registry, the organisation vouches for the group.** Legitimacy of a name is established at registration time by the registry's own admission mechanism — for the default registries, a moderator admitting the package (the OpenVSX model): creating the package repository is the act of vouching. Naming policy (≥ 2 segments, reverse-FQDN shape, squatting rules) is that registry's business, enforced by its moderation or registration surface — never by the core (§2.1). **Across registries, truth is held by the content hash, not the name.** Two registries may serve different packages under one `(group, name)` — a local registry shadowing a well-known package with a patched build is a *legal, normal* configuration (the Maven-local-override pattern), not an attack by definition. The consumer's protections are structural: the priority-ordered `[[registry]]` list ([PROP-002 §2.2](PROP-002-decentralized-registry.xml#registry-model)) says who is asked first, and the lockfile's `content_hash` pin says what may be reproduced. **The default trust set is exactly two roots** — `https://github.com/vibespecs` and `https://gitverse.ru/vibespecs` — trusted by default as the registries `vibe init` writes. Every other registry is trusted **only** by the user's own act of adding it to their configuration (owner ruling, 2026-08-13). **No blessed convention for authors without domains.** A group like `oleg.examples` — a domain that exists nowhere — is fully legal at the core and normal in a local registry. Whether a public registry admits it (or requires an `io.github.<user>`-class convention) is that registry's naming policy. The core blesses nothing (owner ruling, 2026-08-13, superseding the earlier recommendation to bless one convention).

Package **removal, name re-registration, and the visible-lineage obligation** that trust depends on are registry semantics and live in [PROP-002 §2.13](PROP-002-decentralized-registry.xml#lifecycle); the two-tier publish flow that operationalises moderation is [PROP-002 §2.10](PROP-002-decentralized-registry.xml#publish).