Design rationale: Workspace & qualified naming

1. What this document is

04PROP-007 and PROP-008 say what the workspace + qualified-naming refactor does. This document says why — and keeps the lore: the owner's mental model, the four-axis decomposition, every fork weighed during the session, the Cargo-vs-Maven precedents studied, the publication model that needed careful explaining, and the ideas that surfaced but were parked.

05It exists because the design session that produced PROP-007/008 spent a large amount of reasoning that does not belong inside a contract-shaped PROP, yet would be expensive to lose at the next session boundary. See vibevm/vibespecs/design/README.md for the genre.

2. The owner's request and mental model

06The owner asked for a structure "most like Maven submodules and cargo": a project that decomposes naturally into modules; modules that publish to a repository individually — or are deliberately not shared; and the whole structure declared right in the project description.

07Two extremes were named as must-work cases, and they anchor the whole design:

• 08Entirely invisible — a fully structured project that lives nowhere in any external repository.
• Entirely published — the whole project, every sub-package individually, published.

09The "everything in between" (some modules public, some private, some workspace-internal) must also be first-class.

10A load-bearing phrase from the session, recorded verbatim because it shaped several decisions: "the user works in a sub-project and doesn't even notice that it is actually a small piece of something bigger." This is why commands bubble up to the workspace root (PROP-007 §2.4) and why there is one unified manifest rather than many files (§2.2) — "reading a million different files is hard for a human, and for a small dumb LLM agent too."

11The spirit throughout: flexibility and convention-over-configuration. The owner repeatedly chose "support both, default sensibly" over "pick one." That preference resolved R3 (version inheritance: both modes) and W8 (member versioning: both).

3. The four axes

12The request decomposes into four orthogonal axes. Keeping them separate was the single most clarifying move of the session — they have different cost, different dependencies, and ship as different milestones.

14Axis A alone closes roughly 80% of the request — multi-package projects, local cross-deps, selective publish, both extremes — and it depends on nothing. That was the good news delivered early: the heavy part (naming, discovery) is separable and can come later.

4. The dependency graph between axes

Axis A (workspace)          — independent ───────────────► do first
Axis B (selective publish)  — depends on A
Axis C (qualified naming)   — depends on PROP-005 (index)
Axis D (conflict-aware)     — depends on C; the conflict half partly exists already

16The chain D → C → PROP-005 index is the key finding. Reasoning:

• 17C needs the index. A short name wal must be resolved to a qualified org.vibevm.world/wal. That requires enumerating candidates (*, wal) 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 implemented.
• D needs C. A collision is two different packages sharing a short name. You can only tell a collision apart from a harmless mirror (the same package served by two registries) once group exists to distinguish them. Without group, first-match-wins is the only sane policy.
• The conflict half of D already exists. The depsolver (resolvo/libsolv per PROP-003), [conflicts], and the conflict-explanation chain are in place; the install pipeline is already atomic (resolve → plan → confirm → apply), so a failed resolve never reaches apply. "Fail without applying the plan" is already true. Only collision detection is new.

18This is why the recommended sequencing is A → PROP-005 implementation → C → D.

5. The fork-by-fork decision record

19Every fork weighed in the session, the options, the choice, and the reasoning. This is the most valuable part to preserve — settled questions that would otherwise be re-litigated.

6. Cargo vs Maven — the precedent lore

24Both were studied point by point. The findings, kept here so a future session need not re-derive them.

26The decisions vibevm drew from this:

• 27Lockfile: Cargo model. vibevm already mandates a lockfile (content-hash integrity, PROP-002 §2.1). Maven's lockless model would mean discarding working machinery. One vibe.lock at the absolute root.
• Nested workspaces: vibevm permits them, unlike Cargo. Cargo forbids them to dodge ambiguity. vibevm can afford them because it fixes "lock always at the absolute root" — that rule resolves the ambiguity deterministically. Maven shows arbitrary nesting works when version coordination aggregates upward.
• Version placeholders: Maven <properties> shape, because that is literally what the owner described ("write 0.0.1 once, reference it by name"). [workspace.dependencies] (Cargo's centralised per-pkgref defaults) is noted as a possible companion mechanism, not the primary one.
• groupId: adopted as group — but as a package attribute, not a registry attribute, which is why it does not reopen PROP-002 §3.4's rejection of per-registry identity.

7. The physical publication model

28This needed careful explanation — the owner flagged it as confusing and asked directly.

29The model: the development tree is one source tree (one git repo, or not in git at all if private). Workspace members are subdirectories; the split into packages is logical, at the resolver level. Publishing is a separate operation that copies a package directory's content into a new, separate repository in the registry org and tags it — exactly what vibe registry publish does today for one package, repeated per member by vibe workspace publish.

30A nested package does not "surface" by moving files. Only a copy of its content is published, into its own repository, at publish time. The source tree stays unified — a monorepo for development; the registry holds split copies.

DEVELOPMENT — one tree, one git repo (or no git):
  my-project/
  ├── vibe.toml          [workspace] members = ["packages/X", "packages/Y"]
  └── packages/{X,Y}/    each: vibe.toml with [package]

PUBLISH — splits into separate repos:
  packages/X/  --content copy-->  <registry-org>/org.vibevm.X   tag v…
  packages/Y/  --content copy-->  <registry-org>/org.vibevm.Y   tag v…
  The development tree is NOT modified.

32Recommendation: keep members as flat siblings, not physically nested. Logical hierarchy ("X is built from Y") is a path-dependency, not a nested directory. Physical nesting is supported (with subtree excision when publishing the outer package, cargo-style) but discouraged for the "holes in the tree" complexity.

8. "Do not contribute here" — the signalling lore

33The owner asked: when a sub-package's published copy is cloned, how do we make it super-obvious that pull requests there are pointless and contribution belongs to the main project?

34Prior art studied: AOSP / Chromium / Bazel keep read-only mirrors on GitHub with explicit "this is a mirror, do not send PRs, contribute upstream" banners. GitHub offers no "disable PRs only" switch — only full archival blocks PRs.

35The layered answer (detail in PROP-007 §2.8): README banner as the first block; repo description; Issues disabled; a PULL_REQUEST_TEMPLATE.md STOP notice; and archived = true as the nuclear --archive option (full read-only — vibevm drives the unarchive→push→archive cycle on re-publish). Plus a machine-readable [origin] marker in the published copy, and a published_repos = "read-only" | "open" setting for operators who want the inverse model.

36Terminology fixed: the published copy is a published package repository; the source of truth is the workspace. It is not a [[mirror]] (that term is taken — an availability copy of a registry).

9. Ideas parked for the future

• 37vibevm registry explorer. The owner asked whether a Maven-Central-style browsable visualisation is possible — and wanted it richer. Yes: the per-org index (PROP-005) carries the data. Beyond Maven Central: a reverse-FQDN group tree with drill-down, plus kind filtering, a capability graph, describes/PURL links to upstream libraries, redirect-stub delegation, the full dependency DAG, and workspace provenance ("sub-package of X" from the [origin] marker). Recorded as a ROADMAP.md M3+ entry and in PROP-008 §2.9. The only obligation on the refactor: the index must carry group and workspace_origin so the explorer is not a retrofit.
• [workspace.dependencies] — Cargo-style centralised per-pkgref version defaults, alongside the named placeholders. Deferred until a concrete need surfaces.
• Inverse contribution model — published_repos = "open" for projects where the split repo, not the monorepo, is the canonical contribution target.

10. Session log

• 382026-05-20. Session restored from CONTINUE.md + vibevm/vibespecs/WAL.xml. First closed the vibe registry redirect-update tech-debt item (M1.16 deferred-list — 4 commits, f8af587..b44729d). Then the owner opened the question of structuring a project with packages without necessarily publishing to a repository. The discussion grew into the workspace + qualified-naming refactor: the four-axis decomposition, the fork-by-fork resolution recorded in §5, two DRAFT PROPs (PROP-007 + PROP-008, commit ff23a0f), and finally the decision to create the vibevm/vibespecs/design/ genre so this lore is not lost when the implementation moves to a fresh session. Implementation deferred to a new session; this document plus PROP-007/008 are the handoff.
• 2026-05-21. PROP-007 implemented — M1.17 Phases 1–5 (the workspace data model, discovery, path-source + vibe.lock v4, [workspace.versions], vibe workspace publish) shipped on branch m1.17-workspace; Phase 6 documented it. The detailed implementation record is PROP-007 §9. Workspace-aware vibe install remains, gated on the materialisation-target decision (PROP-007 §6 q3). PROP-008 (qualified naming) is still unimplemented — its turn comes after PROP-005 (index).

11. Pointers

• 39PROP-007 — workspace (the contract).
• PROP-008 — qualified naming (the contract).
• PROP-002 — identity, registry, the per-registry-identity rejection (§3.4).
• PROP-005 — the index; a prerequisite for short-name resolution.
• ROADMAP.md — milestones M1.17 (workspace), M1.19 (qualified naming — the number shifted after this session was captured; M1.18 went to the loading model), and the M3+ registry-explorer entry.