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

2.1 The group field

11req r1

12Decision. [package] gains a mandatory group field:

[package]
kind    = "flow"
name    = "wal"
group   = "org.vibevm"
version = "0.3.0"

• 14Reverse-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.

2.2 Identity tuple — (group, name, version, content_hash)

15req r1

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

• 17name 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. 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.

2.3 kind becomes pure metadata

18req r1

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

20It is still needed for:

• 21content 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).

22The 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.

2.4 pkgref grammar

23req r1

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

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

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

• 28kind 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).

2.5 Repository naming — naming = "fqdn"

29req r1

30Decision. 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

• 32naming = "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.

2.6 Short-name resolution

33req r1

34Decision. 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.

• 35vibe 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 — 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.
• 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.

2.7 Collision vs conflict

36req r1

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

• 38Collision (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).

39Collision handling (new):

• 40The 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`.

42Conflict 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.

2.8 Index extension

43req r1

44Decision. PROP-005'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 [origin]).

• 45The 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.

2.9 Registry explorer

46design r1

47Decision (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):

• 48a 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).

• 49The 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.

2.10 Trust: the group is a claim, not a credential

50req r2

51Decision (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.

• 52Domain 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) 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).

53Package removal, name re-registration, and the visible-lineage obligation that trust depends on are registry semantics and live in PROP-002 §2.13; the two-tier publish flow that operationalises moderation is PROP-002 §2.10.