PROP-007: Workspace — multi-package projects, recursive nesting, selective publish

2.1 The [workspace] section

12req r1

13Decision. A vibe.toml may carry a [workspace] table declaring member packages:

[workspace]
members = [
  "packages/flow-wal",
  "packages/feat-auth",
  "packages/stack-*",          # glob permitted
]

• 15members — paths relative to the manifest. Glob patterns are permitted (packages/*).
• Each member is a directory carrying its own vibe.toml (§2.2).
• Membership is explicit — there is no auto-discovery of directories that happen to carry a vibe.toml. The structure is declared, per the owner's "the whole structure is in the project description" requirement.

2.2 Unified manifest — one vibe.toml

16req r1

17Decision. vibe-package.toml is retired as a distinct filename. Every node — project root, workspace member, published package — carries a single vibe.toml; the role is expressed by which sections are present. This is the cargo model: one Cargo.toml carries [package] and/or [workspace].

18Section roles:

• 20[package] and [project] are mutually exclusive in one file — a node is either a publishable package or a plain project, not both. (Decision 7-α from the design session: keep the two sections distinct rather than folding [project] into a [package] with optional kind. Explicitness wins; kind stays strictly mandatory wherever [package] appears.)
• [workspace] composes with [package], with [project], or with neither (a virtual workspace root — just a coordinator).

• 21Why one file. A workspace member is simultaneously a locally-developed node and a publishable artifact. Two files would give every member both, each carrying its own [requires] — duplication that drifts. One vibe.toml with a variable section set is the only coherent shape.
• The owner's secondary reason, recorded verbatim: reading one file is easier for a human — and for a small/weak LLM agent — than chasing many.

22Consequence. Registry repositories migrate vibe-package.toml → vibe.toml (a published package is a vibe.toml with [package], no [workspace]). The redirect-stub marker vibe-redirect.toml (PROP-002 §2.4.2) is a separate concern and is unaffected. Migration detail: PROP-008 §3.

2.3 Recursive nesting

23req r1

24Decision. Nested workspaces are permitted to arbitrary depth — a member may itself carry a [workspace] section.

25The load-bearing principle that keeps this from becoming chaos:

26Nesting is hierarchical grouping, not independent resolution domains. The lockfile and unified resolution always live at the absolute root of the workspace tree. A nested [workspace] provides (a) the [workspace.versions] matryoshka (§2.6) and (b) logical grouping of members — never its own lockfile, never its own resolution pass.

• 27Root discovery. A command run inside a node walks up the directory tree, collects every vibe.toml carrying [workspace], and selects the topmost one that transitively includes the current node. The lockfile lives there.
• Standalone node. If no enclosing [workspace] exists above a node (it was cloned on its own — e.g. it is just a published package), the node is its own absolute root. This is the same rule as §2.4's command-bubbling and matches cargo's behaviour for a crate cloned outside any workspace.
• Explicit nesting. A parent [workspace].members lists the nested sub-workspace among its members. No nesting is inferred from the directory tree alone.

28Cost. Cargo forbids nested workspaces precisely to avoid "which workspace is mine" ambiguity. vibevm permits them because the "lock always at the absolute root" rule resolves that ambiguity deterministically. The price is recursion in three places — parent-chain discovery, transitive member aggregation, and placeholder resolution (§2.6) — which the implementation estimate for M1.17 must absorb.

2.4 Single lockfile at the absolute root

29req r1

30Decision. One vibe.lock, at the absolute root of the workspace tree (§2.3). No per-member lockfiles.

• 31Unified resolution. All members resolve together: one version of each external dependency across the whole workspace. A "diamond" inside a workspace is impossible by construction. This is the cargo model; Maven's nearest equivalent is <dependencyManagement> in the parent POM (Maven has no lockfile at all — a known reproducibility gap vibevm does not inherit, since the lockfile is already load-bearing for content-hash integrity per PROP-002 §2.1).
• Command bubbling. A command (vibe install, vibe build) run inside a member's directory walks up to the absolute root, finds vibe.lock, and operates against it. The member "does not notice" it is part of something larger — this realises the owner's requirement that a developer can work inside a sub-project unaware of the surrounding workspace.

2.5 Cross-member dependencies — the path source

32req r1

33Decision. A third dependency source-kind joins registry-resolved (PROP-002 §2.2) and git-source (PROP-002 §2.4.1): path-source.

[requires.packages]
"org.vibevm.world/wal" = { path = "../flow-wal" }
# dual-form (recommended for any member that is itself published):
"org.vibevm.world/wal" = { path = "../flow-wal", version = "^0.1" }

• 35Dual-form. path is used during local development inside the workspace; version takes effect when the consuming node is itself published — the published copy references org.vibevm.world/wal@^0.1 from a registry, not ../flow-wal (which an external consumer does not have). This is cargo's { path = ..., version = ... } shape. Dual-form is required for any path-dep whose consumer is publishable.
• Resolution priority. [[override]] > path > git-source > registry-walk. Path sits below override (override is a deliberate patch) and above git-source (path is the most local, most authoritative declaration).
• Lockfile. New source_kind = "path". For a workspace-member path-dep the lockfile records a reference to the member by id within the workspace, not an external source_url — so the lockfile stays portable across machines (an absolute path would not).
• path outside the workspace. A path pointing at a directory that is not a member of this workspace is permitted, but a node depending on it via path-only (no version) is not publishable — the published copy would dangle.

2.6 Version placeholders — [workspace.versions]

36req r1

37Decision. Named version placeholders, the equivalent of Maven <properties>:

# in a [workspace] manifest:
[workspace.versions]
core = "0.0.1"
ui   = "^0.3"

# in a member:
[requires.packages]
"org.vibevm/auth" = { version.var = "core" }

• 40Recursive resolution (matryoshka). A version.var = "core" reference is resolved bottom-up: search [workspace.versions] of the node's nearest enclosing workspace, then its parent, then upward to the absolute root. First hit wins — a nearer level overrides a farther one. This is the arbitrary-depth nesting the owner asked for; it depends on §2.3 permitting nested workspaces.
• Version inheritance. A member may write version = { workspace = true } in [package] to inherit its own version from the nearest [workspace] — cargo's version.workspace = true. Independent per-member versions remain the default; inheritance is opt-in.
• A companion mechanism, [workspace.dependencies] (cargo-style centralised per-pkgref defaults, ≈ Maven <dependencyManagement>), is noted as a possible addition but not the primary surface — named placeholders were the owner's explicit request and cover the stated use case ("write 0.0.1 once, reference it by name everywhere").

2.7 Selective publish

41req r1

42Decision. Each publishable node declares its publish posture in [package]:

[package]
publish = false                 # never published — workspace-internal
# or
publish = true                  # default
# or
publish = ["vibespecs"]         # only into these named registries

• 44vibe workspace publish [--member <m>] walks members in topological order (dependency-first) and skips publish = false.
• Publish is not atomic: on the first failure the command stops and reports what was already published and what remains. (Distributed publishing across N independent host repos has no transaction; a rollback would be a worse lie than a clear partial-progress report.)
• Extremes: every member publish = false → the project is entirely invisible, nothing leaves the machine. Every member publish = true → the whole project, root included (§2.9), is published.

2.8 Published package repositories

45req r1

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

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

PUBLISH (`vibe workspace 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. It stays a monorepo.

48A 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.

49Terminology. The published copy is a published package repository; the source of truth is the workspace (the development monorepo). This is not a [[mirror]] (PROP-002 §2.3 — that term means an availability copy of a registry).

50Origin marker. The published copy carries a machine-readable marker in its vibe.toml:

[origin]
upstream     = "https://github.com/you/my-project"   # the monorepo
path         = "packages/flow-wal"                   # path within it
generated_by = "vibe 0.x"
generated_at = "2026-…"

52"Do not contribute here" signalling. A published copy whose source of truth is a monorepo should tell humans not to send pull requests. GitHub offers no "disable PRs only" switch, so the signal is layered. vibe workspace publish default applies layers 1–4; --archive adds layer 5:

54A [workspace]-level setting published_repos = "read-only" | "open" (default "read-only" for workspace members) lets an operator opt into the inverse model where the split repo is the canonical contribution target.

• 55Layout recommendation. Keep members as siblings (flat under packages/), not physically nested. Logical hierarchy ("X is built from Y") is expressed by a path-dependency (§2.5), not by nesting directories.
• If a member is physically inside another's directory, publishing the outer package must excise the inner sub-package's subtree from the outer's content (cargo does this with nested crates) — supported, but discouraged for the "holes in the tree" complexity it adds.

2.9 Root as a publishable package

56req r1

57Decision. The root vibe.toml may itself carry [package] alongside [workspace] — cargo-style. The workspace coordinator can also be a publishable artifact in its own right. (Maven's parent POM cannot; cargo's root crate can. vibevm follows cargo.)

9.1 What each phase delivered

74Phase 1 — the unified manifest (vibe-core; commits b794e7a, 9a190ff). The two manifest types — ProjectManifest (read from vibe.toml) and PackageManifest (read from vibe-package.toml) — collapse into one Manifest type for a single vibe.toml per node. Sections are optional; the role is the set of sections present. Manifest::validate enforces: [project] ⊕ [package] (never both); at least one of [project] / [package] / [workspace]; package-role sections ([writes], [provides], [boot_snippet], [[requires_any]], [obsoletes], [conflicts], [compatibility], [features], [target.*]) require [package]. The new [workspace], [origin] and [package].publish are parsed here and consumed by later phases. New module manifest/document.rs. The ~190 downstream call-sites across vibe-registry, vibe-resolver, vibe-install, vibe-publish, vibe-check, vibe-cli, vibe-mcp and the vibe-index service were migrated; CachedPackage.manifest is a Manifest with a package_meta() accessor; eight registry / manual-test fixtures were renamed vibe-package.toml → vibe.toml.

75Phase 2 — workspace discovery (new vibe-workspace crate; commit ece30a6). Workspace::discover(start) walks up from any directory to the topmost [workspace] transitively enclosing the start node — the absolute root. Workspace::load(root) reads the root manifest and expands members recursively: members patterns are glob-expanded against the filesystem; an explicit (non-glob) member that does not resolve is an error, a glob that sweeps a non-package directory skips it; a workspace that transitively lists itself is a NestingCycle. A node with no enclosing [workspace] is a standalone workspace with zero members — so discover is the universal entry point and degenerates cleanly for every existing single-package project. Members carry a portable rel_path (forward-slashed, relative to the root); absolute paths exist only in memory during the walk.

76Phase 3 — path-source dependencies + lockfile v4 (vibe-core, vibe-registry, vibe-install; commits ff21de3, e9a15d2). A [requires.packages] entry { path = "../sibling", version = "^0.1" } is a third source-kind. vibe-core gains PathPackageDep and the Requires.path_packages bucket. The resolver dispatches [[override]] > path-source > git-source > registry-walk; resolve_path_source reads the package off the local directory, fetch_path_source copies it into the cache (no clone). vibe.lock bumps to schema v4: a new source_kind = "path", whose source_url carries the member's path relative to the workspace root. All legacy lockfile readers — the source field alias, the v1 heuristic, the schema-version default — were deleted; Lockfile::read rejects any schema_version other than 4.

77Phase 4 — [workspace.versions] placeholders (vibe-core, vibe-workspace; commit 98795e8). A [workspace] may carry a [workspace.versions] table of named version constraints. A member references one as { version.var = "core" }, parsed into Requires.var_packages. The vibe-workspace loader, after discovering all members, resolves each placeholder bottom-up — the node's own [workspace.versions] if it is itself a workspace, then its declaring workspace, up to the absolute root; first hit wins — folding each into a concrete PackageRef. WorkspaceMember gained a parent link to make the enclosing-workspace walk possible.

78Phase 5 — selective publish (vibe-cli, vibe-workspace; commit b673d2b). vibe workspace publish selects the self-publishing nodes (those carrying [package] whose PublishPosture admits the primary registry), orders them dependency-first over the inter-member path-deps, and publishes each from a staged copy — the developer's tree is never modified. Each staged copy carries the [origin] provenance marker, a "generated copy — contribute upstream" README banner, a PULL_REQUEST_TEMPLATE.md STOP notice, and a generated-copy description. Publishing is non-atomic: on the first failure the command stops and reports what published and what remains.

79Phase 6 — documentation (commits 047f92d, 10406a1, 3cb2a03). VIBEVM-SPEC.md §4.2 / §7.6, this §9 and the §6 / §8 updates, ROADMAP.md, CHANGELOG.md, the docs/ and manual-tests/ sweep, the new docs/commands/workspace-publish.md, and the WAL checkpoint.

9.2 Decisions pinned during implementation

• 80Hard compatibility break — no legacy, no migration. vibevm is pre-release; rather than carry compatibility shims, every legacy form was deleted: the vibe-package.toml filename, the [dependencies] section, the array-form packages = ["…"], the singleton [registry] table, and the vibe.lock v1/v2/v3 readers. A manifest or lockfile using a removed form is a hard error. This is the owner's directive for the milestone, recorded here.
• §6 question 2 — the lockfile path-member shape. Resolved: source_kind = "path" with source_url holding the member's workspace-root-relative path. No separate workspace_member field — a relative path is portable and one field suffices.
• §6 question 1 — the [origin] field set. Resolved: upstream, path, commit (optional — present when the monorepo is a git repo), generated_by, generated_at.
• version.var scope. Supported on registry-resolved dependencies only; a git-source or path-source version must be a concrete constraint. The placeholder mechanism serves the many registry deps that share a version — the owner's stated use case.

9.3 Deferred work

• 81Workspace-aware vibe install / vibe build — RESOLVED, no longer deferred. This was PROP-007's one remaining piece: §2.4 / §3 described command-bubbling and unified multi-member resolution, but the concrete behaviour turned on a per-member materialisation target (when a dependency is resolved for member M, into which member's spec/ does its content land?) — a genuine design fork left to an explicit owner decision (§6 question 3). PROP-009 §2.7 answered it and M1.18 Phase 5 shipped it: Workspace::discover runs in the install plan and apply paths (vibe-install/plan.rs, apply.rs), gathering every member's [requires] into one resolve. Standalone single-package projects were unaffected throughout.
• version = { workspace = true } (§2.6) — member-version inheritance. Deferred because §2.6 names no source table for the inherited version (cargo reads [workspace.package].version; PROP-007 defines no such table). Shipping it means extending the spec — a decision to take explicitly. [workspace.versions] already covers the "write the version once" use case (§6 question 4).
• Publish-signalling polish (§2.8) — --archive (the GitHub archived = true lockdown and its unarchive→push→archive re-publish cycle), has_issues = false at repo creation, the published_repos = "read-only" | "open" toggle, and multi-registry fan-out. The [origin] marker + README banner + PR template + description already make a published copy unmistakably a generated read-only copy; these remaining layers are incremental host-API hardening.

9.4 Crate and module map

• 82vibe-core — manifest/document.rs (Manifest, WorkspaceSection, OriginSection, validate); manifest/package.rs (PackageMeta + PublishPosture, Requires + PathPackageDep + VarRegistryDep, the wire forms); manifest/lockfile.rs (schema v4, SourceKind::Path).
• vibe-workspace — new crate. lib.rs (Workspace, WorkspaceMember, discover / load, the [workspace.versions] finalize pass); publish.rs (publishable-node selection, topological order, node staging).
• vibe-registry — multi_registry_resolver.rs (ResolvedPathDep, with_path_packages, resolve_path_source / fetch_path_source, the priority dispatch).
• vibe-cli — commands/workspace.rs (the vibe workspace publish command).
• vibe-install — the is_path_source → SourceKind::Path lockfile mapping.

9.5 Quality gates

83Every phase landed with cargo clippy --workspace --all-targets -- -D warnings clean and its full test suite green — 703 hermetic tests across the workspace at the close of M1.17, plus vibe check reporting 0/0/0. vibe-install's tests pass — 18 of them — but only when the test binary is run under a name without the substring install: os error 740 on the normally-named vibe_install-<hash>.exe is Windows UAC installer detection (a heuristic that treats an unsigned, unmanifested *install*.exe as a legacy installer requiring elevation), not Windows Defender, and not a code defect.