valise-sh 0.2.0 → 0.3.0

package/docs/release-policy.md

@@ -2,9 +2,11 @@
 
 ## Current status
 
-`valise-sh` is at **0.2.0**. Before 1.0, the CLI, module ABI, and release
-format do not have a backward-compatibility guarantee. Consumers should pin
-updates, review release notes, and run their profile's tests before upgrading.
+`valise-sh` is at **0.3.0**. Before 1.0, the CLI, module ABI, and release
+format do not have a backward-compatibility guarantee. Pin the version you
+use, read the release notes, and run `valise lint` and `valise test` on your
+project before upgrading. A project can set `requires_valise=` in
+`valise.conf` so an older valise refuses to build it.
 
 ## Compatibility surface
 
@@ -23,107 +25,80 @@ minor releases, and release notes must state what consumers have to change.
 After 1.0, use semantic versioning: patch for compatible fixes,
 minor for backward-compatible features, and major for incompatible changes.
 
-## What changed in 0.2.0
-
-`0.1.0` had no external users, so `0.2.0` provides no migration path for its
-CLI or shell integration. The items below describe the 0.2.0 contract; each is
-also recorded in [CHANGELOG.md](../CHANGELOG.md).
-
-### The registry is a generated artifact
-
-`shell/release/module-registry.tsv` is generated from the project's metadata
-by `valise registry`, and `valise build` regenerates it while `valise registry
---check` validates it. A hand-written registry is no longer the source of truth, and a
-project needs no registry file at all to build: it keeps its `.meta` files,
-their bodies, the bundle roots, and the variants. A committed registry is
-accepted as input, but it is overwritten on the next build.
-
-The row order is fixed and does not depend on the caller's locale: the
-primary modules of `shell/module.d/` first, then the layer modules of each
-`shell/layers/<provider>/module.d/`, each group in C-locale name order.
-
-### The metadata ABI gained fields and classes
-
-- **Meta modules.** Metadata with `requires=` and no `load` is a
-  dependency-only aggregator. It loads successfully without a body. `load`
-  and `requires` may be combined.
-- **`side_effect=local-state`.** A source-safe class for modules that write
-  under the XDG state directory. It loads in the ordinary phase where
-  `generated-file` still fails.
-- **`shells=sh` covers every POSIX shell.** A module that declares `shells=sh`
-  loads under `sh`, `dash`, `bash`, `zsh`, and `ksh`, and is skipped under
-  Fish unless it is requested directly in strict mode.
-
-### Compiled plans follow the loader
-
-A compiled plan uses the loader's dependency rules. The required closure is
-the bundle's roots plus their transitive `requires`. A module whose required
-dependency is unavailable, failed, or skipped for the platform does not run.
-Strict mode stops at the first failure in that closure and returns nonzero;
-permissive mode reports each failure, continues with unrelated modules, and
-returns zero. An optional dependency loads first when it is available for the
-shell and variant; its absence never blocks the module that declared it. A
-cross-platform profile declares platform-specific modules with `optional=`.
-A meta module that declares exports is a compile error, and a module that
-fails has its declared exports removed from the function namespace.
-
-### Capabilities are available at runtime
-
-The `sp_cap_*` helpers remain sourced and callable after a compiled plan or a
-loader load finishes. A module may call `sp_cap_os` and the other helpers
-from its own functions. A plan that removed them at the end of the load left
-module functions unusable.
-
-### Startup integration is managed
-
-`valise install` writes a managed block into `~/.profile` and into each
-further startup file it manages: the existing `~/.bash_profile` or
-`~/.bash_login`, `~/.bashrc` and `~/.zshrc` when that shell is current or the
-file exists, and `~/.zprofile` when zsh is on `PATH` or the file exists. It
-does not create `~/.bash_profile` or `~/.bash_login`, because either would
-stop bash from reading `~/.profile`. A Fish `conf.d` hook is written when
-valise finds a Fish executable in a trusted location. `--no-integration`
-writes no startup file and no Fish hook. `valise apply` uses the same writer
-after building and installing.
-
-Each POSIX file receives the block between `# BEGIN valise managed block` and
-`# END valise managed block`. A repeat install replaces the block in place
-and preserves the rest of the file. An unpaired marker is refused and stops
-the install; a file already processed keeps its updated block. A symlinked
-startup file is reported and left untouched.
-
-### Commands
-
-The command surface has one command per job. `valise init` takes `posix` or
-`fish`; with no argument it prints the Fish hook when `$SHELL` names fish and
-the POSIX block otherwise. `valise new`, `valise module`, `valise build`,
-`valise apply`, `valise status`, and `valise registry` are new. `valise build`
-builds a release tree, and `valise apply` builds, installs, writes the shell
-integration, and verifies the result.
-
-Installed releases are managed by `valise release list|use|prune|verify`.
-`variant list`, `variant use`, and `verify-active` are gone; `variant` now
-refers only to a build variant. `valise doctor` gained `--pre-install` and
-`--no-integration`; it reads the startup files the running shell actually
-reads and exits nonzero when the active release is missing or fails
-verification, or when no startup file carries the block. `valise
-explain-bundles` and `valise layer-lint` no longer use Python.
+## What changed in 0.3.0
+
+0.3.0 changes the project layout, the metadata, the release format, and the
+startup block. A 0.2 project does not build until it is moved to the new
+layout, and a 0.2 release cannot be installed; rebuild it. Every change is
+also in [CHANGELOG.md](../CHANGELOG.md).
+
+### Moving a 0.2 project
+
+| 0.2 | 0.3 |
+|---|---|
+| `shell/module.d/`, `shell/modules/` | `module.d/`, `modules/` at the project root |
+| `shell/layers/<p>/` | `layers/<p>/` |
+| `shell/release/bundle-roots` | `bundles.tsv` (bundle, shell, roots) |
+| `shell/release/install-variants` | `variants.tsv` (variant, description, excluded) |
+| `shell/release/project.conf` | `valise.conf` (`bundle=`, `variant=`, `requires_valise=`, `lint_layer_forbid=`) |
+| `shell/release/module-registry.tsv` | nothing: the registry is internal; delete the file |
+| `valise registry --check` | nothing: `valise lint` checks the metadata |
+| `@shell/layers/<p>/module.d` in a qualified name | `@layers/<p>/module.d` |
+
+valise does not read the `shell/` layout: until `valise.conf` exists,
+project commands report that they are not inside a valise project.
+
+### Metadata
+
+- `shells=posix` means every POSIX shell. `shells=sh` now means only the
+  generic class (dash, BusyBox ash, and other plain `sh`), so a module that
+  used `shells=sh` for "all POSIX shells" must change to `shells=posix`.
+- `updates=` is rejected. Remove it.
+- A repeated field is rejected.
+- The engine modules moved into the reserved `valise_` namespace:
+  `contrib_path` is now `valise_path` (exports `valise_path_prepend` and
+  `valise_path_append`), `contrib_editor`, `contrib_history`,
+  `contrib_pager`, and `contrib_xdg` are `valise_editor`, `valise_history`,
+  `valise_pager`, and `valise_xdg`, and `platform_<os>` is
+  `valise_platform_<os>`. Update `requires=` and the calls to their
+  exports.
+- New fields: `commands=` publishes exports as commands on `PATH`,
+  `executables=` publishes scripts, and `tests=` names the scripts
+  `valise test` runs.
+
+### Releases and startup
+
+- A release has one shape: `plans/<shell>.sh`, `runtime/`, `bin/`,
+  `valise-release.conf` with `format=2`, and `manifest.tsv`. It contains
+  only the modules some plan loads. The `generated/`, `vendor/`,
+  `shell/install/`, and engine-release (`entrypoints/`) shapes are gone, and
+  install refuses a tree without `format=2`.
+- The POSIX block picks a plan for `ksh`, `zsh`, `bash`, or `sh` and has no
+  loader fallback. Run `valise apply` once to rewrite the block in each
+  startup file. Install warns about any line outside a managed block that
+  still loads a 0.2 release.
+- A bundle's `fish` rows build the native Fish runtime into the release.
+
+### New commands
+
+`valise lint`, `test`, `run`, `env`, `uninstall`, `release rollback`, and
+`apply --dry-run`. Install is transactional: a failure puts the previous
+active release back.
 
 ## Release checklist
 
 Before tagging or publishing a release:
 
-1. Update `package.json` and `bin/valise` version together; add a dated entry
-   to [CHANGELOG.md](../CHANGELOG.md). The CLI's test suite asserts that the
+1. Update the `package.json` version and `VALISE_VERSION` in `bin/valise`
+   together; add a dated entry to [CHANGELOG.md](../CHANGELOG.md). The CLI's test suite asserts that the
    two versions match, so a bump that updates one and forgets the other
    fails the build.
 2. Run `make check-fast`, then run `make VALISE_REQUIRE_TOOLING=1 check`
    locally or use the GitHub Actions job. Keep the successful strict run as
    release evidence for every lane, including Fish, zsh, BusyBox, dash, and
    ksh.
-3. Run the README isolated quickstart from a clean checkout and verify that
-   install, `release verify`, and example module loading work in the temporary
-   home. Confirm cleanup removes the entire demo state.
+3. Run the README's scratch-home example from a clean checkout and check
+   that `greet` runs and the cleanup removes the scratch directory.
 4. Inspect the result of `npm pack --dry-run` and install/test the packed
    tarball. The CLI's tests currently cover pack contents, installation, and
    module loading. The probe in `tests/cli-posix.test.sh` builds a tree from

package/docs/shared-modules.md

@@ -7,18 +7,20 @@ removed.
 
 ## Namespace and ownership
 
-The loader enforces the layer namespace. This policy assigns ownership and
-review responsibility.
+`valise build`, `valise lint`, and `valise layer-lint` enforce the layer
+namespace. This policy assigns ownership and review responsibility.
 
-- Layer-only modules must use the `contrib_` prefix. The loader rejects
-  other layer-only names (see [module-abi.md](module-abi.md)).
+- Layer modules must use the `contrib_` prefix, and the `valise_` prefix
+  belongs to the engine (see [module-abi.md](module-abi.md#layers)).
 - Module names are owned by the tree that ships them. The engine
   repository owns every module under its `module.d/`. A provider
   repository owns every module in its layer tree.
-- A module with the same name in multiple roots must have matching metadata
-  and body bytes. Different bytes or different `version=` values make the
-  load fail with a diagnostic naming the providers. Identical copies resolve
-  by root priority; providers should still agree on which tree owns the name.
+- When two sources in a project define the same name, a bare bundle root
+  or exclusion naming it is ambiguous and the build fails until it is
+  qualified as `name@source`; a dependency resolves to its own source first. The Fish loader and the development loader accept several
+  providers of one name only when their metadata and bodies are
+  byte-identical. Either way, providers should agree on which tree owns a
+  name.
 - A provider repository that wants its modules consumed must document them
   in an index of its own, following this document's shape (name, version,
   exports, source, status). Consumers read the provider's index to
@@ -46,7 +48,7 @@ consistently across all of its modules, so a consumer can see at a glance
 which provider owns what.
 
 If you must ship a module whose name another provider might already use,
-prefix it with your owner segment anyway — a name collision between two
+prefix it with your owner segment anyway: a name collision between two
 vendored providers is otherwise unresolvable without renaming one of them.
 
 ## What belongs in a layer
@@ -64,19 +66,21 @@ A layer module must have:
   editor, no particular toolchain, model, or theme.
 - **No dependency outside the layer**, apart from the engine's own modules.
   A layer module may require an engine module, but it may not require a
-  module that lives in the consumer's primary root — that dependency cannot
+  module that lives in the consumer's primary root, because that dependency cannot
   be satisfied when someone else vendors the layer.
 
 Everything else stays in the primary root: environment setup, completions,
 tool wrappers, work-specific modules, and the aggregators.
 
-`valise layer-lint <layer-name>` enforces the mechanical half of this. It
+`valise layer-lint <layer-name>` and `valise lint` enforce the mechanical
+half of this. It
 checks that the layer has a `module.d/` directory, that every metadata file
 is a regular file with a safe mode, that every module name carries the
 `contrib_` prefix, that the metadata validates as data, that the version is
 present, that the load target exists as a regular file, and that every
-dependency resolves inside the layer or to an engine module. It needs no
-Python.
+dependency resolves inside the layer or to an engine module. Set
+`lint_layer_forbid` in `valise.conf` to make `valise lint` reject named
+identifiers, such as an employer's, anywhere under `layers/`.
 
 ### 1. Separate generic engines from opinionated presets
 
@@ -116,7 +120,7 @@ contrib_owner_cli_quote     # POSIX, no dependencies
 contrib_owner_cli_local     # needs a non-POSIX shell
 ```
 
-Now the first module keeps `shells=sh bash zsh ksh` and the second declares
+Now the first module keeps `shells=posix` and the second declares
 what it actually needs. The same rule applies to dependencies: a module that
 pulls in a heavy dependency should be separate from one that does not.
 
@@ -130,12 +134,7 @@ consistently.
 A layer module **may** call `sp_cap_*` helpers at run time. A compiled plan
 sources the capability prelude and leaves it in place, so a function the
 module defines can call `sp_cap_os`, `sp_cap_cpu_count`, or any other helper
-long after the profile finished loading. The loader behaves the same way.
-
-This is a change from earlier engine behavior, where the helpers were
-removed after loading and a module function that called one broke. If you
-have a layer that avoided the helpers to work around that, you can now use
-them directly.
+long after the profile finished loading.
 
 Prefer the `sp_cap_*` helpers over open-coding platform-specific commands.
 See [contrib-modules.md](contrib-modules.md) for the list.
@@ -144,11 +143,15 @@ See [contrib-modules.md](contrib-modules.md) for the list.
 
 | Module | Version | Exports | Source | Status |
 |---|---|---|---|---|
-| `contrib_path` | 1.0.0 | `contrib_path_prepend`, `contrib_path_append` | `modules/system/contrib_path.sh` | active |
-| `contrib_editor` | 1.0.0 | `contrib_editor_defaults` | `modules/system/contrib_editor.sh` | active |
-| `contrib_pager` | 1.0.0 | `contrib_pager_defaults` | `modules/system/contrib_pager.sh` | active |
-| `contrib_xdg` | 1.0.0 | `contrib_xdg_defaults` | `modules/system/contrib_xdg.sh` | active |
-| `contrib_history` | 1.0.0 | `contrib_history_defaults` | `modules/system/contrib_history.sh` | active |
+| `valise_path` | 1.0.0 | `valise_path_prepend`, `valise_path_append` | `modules/system/valise_path.sh` | active |
+| `valise_editor` | 1.0.0 | `valise_editor_defaults` | `modules/system/valise_editor.sh` | active |
+| `valise_pager` | 1.0.0 | `valise_pager_defaults` | `modules/system/valise_pager.sh` | active |
+| `valise_xdg` | 1.0.0 | `valise_xdg_defaults` | `modules/system/valise_xdg.sh` | active |
+| `valise_history` | 1.0.0 | `valise_history_defaults` | `modules/system/valise_history.sh` | active |
+| `valise_platform_posix` | — | `sp_platform_*` helpers | `modules/platform/posix.sh` | active |
+| `valise_platform_macos` | — | `sp_platform_macos_*` helpers | `modules/platform/macos/capabilities.sh` | active |
+| `valise_platform_linux` | — | `sp_platform_linux_*` helpers | `modules/platform/linux/capabilities.sh` | active |
+| `valise_platform_bsd` | — | `sp_platform_bsd_*` helpers | `modules/platform/bsd/capabilities.sh` | active |
 
 The example provider tree in this repository
 (`examples/shared/`) additionally ships:
@@ -158,9 +161,7 @@ The example provider tree in this repository
 | `contrib_shared_paths` | 1.0.0 | `contrib_shared_paths_setup` | `examples/shared/modules/shared/contrib_shared_paths.sh` | active |
 | `contrib_shared_umask` | 1.0.0 | `contrib_shared_umask_secure` | `examples/shared/modules/shared/contrib_shared_umask.sh` | active |
 
-These engine-shipped modules predate the owner-segment recommendation and
-keep their existing names; renaming them would break every consumer that
-already vendors them. New modules should use the owner-segment form.
+The example provider's owner segment is `shared`.
 
 Update the index in the same change that adds, renames, deprecates, or
 removes a shared module. Provider repositories should maintain a corresponding
@@ -181,27 +182,27 @@ Every change to a shared module passes the same floor:
    and quiet.
 3. For engine modules, review happens in this repository's normal commit
    review. For provider modules, review happens in the provider
-   repository; the consumer re-applies judgment at re-pin time by
-   reviewing the vendored diff (see the update policy in
-   [module-abi.md](module-abi.md)).
+   repository, and the consumer reviews the vendored diff again when
+   copying a new revision into `layers/<provider>/` (see
+   [module-abi.md](module-abi.md#layers)).
 
 Breaking changes to behavior require a `version=` bump so the skew rule
 can catch mixed-version compositions.
 
 ## Deprecation
 
-A deprecated module keeps shipping unchanged — its bytes stay available
-to every consumer that already pinned them — but is marked for eventual
+A deprecated module keeps shipping unchanged, so its bytes stay available
+to every consumer that already pinned them, but it is marked for eventual
 removal:
 
 1. Set the module's status to `deprecated` in this index.
 2. Freeze its `version=`: no feature work lands; fixes that cannot wait
-   follow the normal re-pin policy with the deprecation still visible.
+   follow the normal update policy with the deprecation still visible.
 3. State the replacement (another module, or none) in the index row.
 
 A module stays deprecated for at least one release before it may be
-removed, so consumers see the deprecation in a re-pin before the
-disappearance. The loader continues to load a deprecated module;
+removed, so consumers see the deprecation in an update before the
+disappearance. Builds continue to include a deprecated module;
 deprecation is a signal to consumers, not a gate.
 
 ## Removal
@@ -214,6 +215,6 @@ Removing a shared module is a release-visible change:
 3. Rebuild the manifest and install: the content-derived release ID
    changes, making the switch to a post-removal release an explicit,
    reviewed act.
-4. Consumers keep working on their already-installed sealed releases —
-   each verifies against its own manifest — and notice the removal at
-   their next re-pin, when the module is absent from the diff.
+4. Consumers keep working on their already-installed sealed releases,
+   each of which verifies against its own manifest, and notice the removal at
+   their next update, when the module is absent from the diff.

package/examples/README.md

@@ -2,12 +2,13 @@
 
 - `local/` is the smallest example: one metadata file and one POSIX shell
   module. It demonstrates sourcing a module without installing a release.
-- `profile-project/` is a complete consuming project: metadata-driven
-  modules, a provider layer, a bundle, a variant, and project defaults.
-  It is the shortest path from a clone to a loaded profile.
-- `e2e/` is a sample consumer profile. Its twelve modules cover dependency
-  resolution, platform and shell selection, exports, optional dependencies,
-  release installation, and shared-module composition.
+- `profile-project/` is a small complete project: two modules, a provider
+  layer, a bundle, and two variants. It is the shortest path from a clone to
+  a loaded profile.
+- `e2e/` is the project `tests/e2e.test.sh` builds. Its thirteen modules
+  cover dependency resolution, platform and shell selection, exports,
+  optional dependencies, a Fish module, and composition with a layer.
+- `shared/` is a sample provider whose modules a project vendors as a layer.
 
 ## Complete project
 
@@ -19,7 +20,8 @@ login shell.
 
 ## Minimal module
 
-From the repository root, load the example with:
+`local/` loads through the development loader, without a project or a
+release. From the repository root:
 
 ```sh
 VALISE_MODULE_ROOT="$PWD/examples/local" \
@@ -38,7 +40,6 @@ The metadata is in `examples/local/module.d/hello_valise.meta`; the body is
 
 ## Sample consumer profile
 
-`e2e/README.md` describes how to build its release manifest, install and
-verify the release, load its modules, and compose the `examples/shared/`
-provider. The example installer writes shell integration under `HOME`, so
-use a temporary home if you do not want to change your normal startup files.
+[e2e/README.md](e2e/README.md) builds, installs, and verifies that project
+in a temporary home, loads it in each shell, and composes the `shared/`
+provider as a layer.

package/examples/e2e/README.md

@@ -1,31 +1,40 @@
 # End-to-end example
 
-This directory is a sample consuming profile. It includes twelve modules
-that exercise dependencies, shell and platform selection, exports, optional
-dependencies, and composition with the shared provider in `examples/shared/`.
+This directory is a valise project used by `tests/e2e.test.sh`. Its modules
+exercise dependencies, shell and platform selection, exports, optional
+dependencies, a Fish module, and composition with the shared provider in
+`examples/shared/`.
 
 ## Modules
 
 | Module | Shells | Platforms | Depends on | Export |
 |---|---|---|---|---|
-| `e2e_env_setup` | sh bash zsh ksh | any | `platform_posix` | `e2e_env_ready` |
-| `e2e_aliases` | sh bash zsh ksh | any | `e2e_env_setup` | `e2e_show_aliases` |
+| `e2e_env_setup` | posix | any | `valise_platform_posix` | `e2e_env_ready` |
+| `e2e_aliases` | posix | any | `e2e_env_setup` | `e2e_show_aliases` |
 | `e2e_completions_bash` | bash | any | `e2e_aliases` | `e2e_bash_completions_loaded` |
 | `e2e_completions_zsh` | zsh | any | `e2e_aliases` | `e2e_zsh_completions_loaded` |
 | `e2e_ksh_features` | ksh | any | `e2e_env_setup` | `e2e_ksh_loaded` |
 | `e2e_fish_features` | fish | any | optional `e2e_env_setup` | `e2e_fish_loaded` |
-| `e2e_platform_tools_darwin` | sh bash zsh ksh | darwin | `platform_macos` | `e2e_darwin_tools_ready` |
-| `e2e_platform_tools_linux` | sh bash zsh ksh | linux | `platform_linux` | `e2e_linux_tools_ready` |
-| `e2e_platform_tools_bsd` | sh bash zsh ksh | bsd | `platform_bsd` | `e2e_bsd_tools_ready` |
-| `e2e_optional_network` | sh bash zsh ksh | any | optional `e2e_env_setup` | `e2e_net_available` |
-| `e2e_generated_config` | sh bash zsh ksh | any | `e2e_env_setup` | `e2e_config_loaded` |
-| `e2e_layer_probe` | sh bash zsh ksh | any | `e2e_env_setup`, optional `contrib_shared_paths` | `e2e_layer_probe_ok` |
-
-`e2e_layer_probe` depends on a primary-root module and optionally on a
-module in the shared layer. It tests dependency resolution in both directions
-across the two roots.
-
-## Build, install, and verify
+| `e2e_platform_tools` | posix | any | `e2e_env_setup`, optional the three below | none |
+| `e2e_platform_tools_darwin` | posix | darwin | `valise_platform_macos` | `e2e_darwin_tools_ready` |
+| `e2e_platform_tools_linux` | posix | linux | `valise_platform_linux` | `e2e_linux_tools_ready` |
+| `e2e_platform_tools_bsd` | posix | bsd | `valise_platform_bsd` | `e2e_bsd_tools_ready` |
+| `e2e_optional_network` | posix | any | optional `e2e_env_setup` | `e2e_net_available` |
+| `e2e_generated_config` | posix | any | `e2e_env_setup` | `e2e_config_loaded` |
+| `e2e_layer_probe` | posix | any | `e2e_env_setup`, optional `contrib_shared_paths` | `e2e_layer_probe_ok` |
+
+`bundles.tsv` gives each shell its roots. The POSIX rows name
+`e2e_platform_tools`, which lists the per-platform modules as optional
+dependencies: a platform module that does not match the running system is
+skipped quietly, while naming it as a root would be a strict-mode failure on
+every other platform. `variants.tsv` has `default` and `no-network`, which
+excludes `e2e_optional_network`.
+
+`e2e_layer_probe` optionally depends on `contrib_shared_paths` from the
+shared provider. Without the provider it reports a standalone load; with the
+provider vendored as a layer it reports that the layer resolved.
+
+## Build, install, and load
 
 Run these commands from the repository root. Installation writes shell
 integration under `HOME`; this example uses a temporary home so it does not
@@ -33,7 +42,7 @@ touch your normal startup files.
 
 ```sh
 export PATH="$PWD/bin:$PATH"
-sh examples/e2e/build-manifest.sh
+valise -C examples/e2e build
 
 _demo=$(mktemp -d)
 mkdir -p "$_demo/home"
@@ -46,35 +55,20 @@ export XDG_STATE_HOME="$_demo/state"
 valise release verify
 ```
 
-The build script copies the engine runtime and shared example into
-`examples/e2e/build/release`, then writes `shell/install/profile-release.manifest`
-with each file's size and SHA-256 digest using `valise make-manifest`. Generated
-release files are isolated in `build/` and can be rebuilt at any time.
+`valise build` writes the release to `examples/e2e/build/release`: one plan
+per POSIX shell class under `plans/`, the Fish runtime under `runtime/fish/`,
+and only the modules some shell loads. `valise install` seals it, makes it
+active, and writes the managed block to `~/.profile` (plus `~/.bashrc` or
+`~/.zshrc` for those shells) and the Fish hook.
 
-Load sample modules in a POSIX shell:
+Start a shell through the startup file valise wrote:
 
 ```sh
-_active=$(cd "$XDG_CONFIG_HOME/valise/active" && pwd -P)
-VALISE_MODULE_ROOT="$_active" \
-VALISE_MODULES='e2e_env_setup e2e_aliases e2e_generated_config e2e_optional_network' \
-VALISE_MODE=strict \
-. "$_active/entrypoints/profile.sh"
-
-e2e_env_ready
-e2e_show_aliases
-e2e_config_loaded
+bash -c '. "$HOME/.bashrc"; e2e_env_ready; e2e_show_aliases; e2e_config_loaded'
+fish -c 'functions -q e2e_fish_loaded; and valise release verify'
 ```
 
-Try the Fish module in a new Fish process. The installed `conf.d` hook loads
-the sealed release at startup, so set the module list in the child's
-environment before starting Fish:
-
-```sh
-VALISE_MODULES=e2e_fish_features VALISE_MODE=strict fish -c \
-  'functions -q e2e_fish_loaded; and valise release verify'
-```
-
-When finished, stop using the functions and remove the temporary installation:
+When finished, remove the temporary installation:
 
 ```sh
 chmod -R u+w "$_demo"
@@ -83,31 +77,30 @@ rm -rf "$_demo"
 
 ## Shared provider composition
 
-The build script vendors `examples/shared/` under `layer/shared/` and records
-its source revision in `layer/shared/layer-pin.txt`. The release manifest
-covers both the profile and provider files. After the build, installation,
-and verification above, load the cross-root probe and shared utilities:
+A project composes a provider by vendoring its tree as `layers/<provider>/`.
+To try it, copy this project, vendor `examples/shared/` as `layers/shared/`,
+and add the provider's modules to the POSIX roots:
 
 ```sh
-_active=$(cd "$XDG_CONFIG_HOME/valise/active" && pwd -P)
-VALISE_MODULE_ROOT="$_active" \
-VALISE_MODULE_PATH="$_active/layer/shared" \
-VALISE_MODULES='e2e_layer_probe contrib_shared_paths contrib_shared_umask' \
-VALISE_MODE=strict \
-. "$_active/entrypoints/profile.sh"
-
-e2e_layer_probe_ok
-contrib_shared_paths_setup
-contrib_shared_umask_secure  # explicitly changes umask to 077
+_proj=$(mktemp -d)
+cp -R examples/e2e/valise.conf examples/e2e/variants.tsv \
+  examples/e2e/module.d examples/e2e/modules "$_proj/"
+mkdir -p "$_proj/layers/shared"
+cp -R examples/shared/module.d examples/shared/modules "$_proj/layers/shared/"
+awk -F '\t' 'BEGIN { OFS = "\t" } NR > 1 && $2 != "fish" { $3 = $3 " contrib_shared_umask" } { print }' \
+  examples/e2e/bundles.tsv >"$_proj/bundles.tsv"
+valise -C "$_proj" build
 ```
 
-The provider modules are POSIX-only; Fish users can load the profile's Fish
-modules but not these utilities. To update the provider in a real consuming
-project, vendor a reviewed commit, inspect the diff, then rebuild and verify
-the release. See [the module ABI](../../docs/module-abi.md) for multi-root
-resolution and [the installation guide](../../docs/installation.md) for the
-integrity and provenance limits.
-
-`tests/e2e.test.sh` runs the install, verification, tamper, and composition
-scenarios in quarantined homes. It also runs available host-shell lanes;
-configured Lima Linux, BusyBox, and BSD lanes run when their VMs are present.
+The release then carries the provider's modules under `layers/shared/`, and
+`e2e_layer_probe_ok` reports that the shared layer resolved. The provider
+modules are POSIX-only, so the Fish closure is unchanged. To update a
+vendored provider in a real project, copy a reviewed commit, inspect the
+diff, then rebuild and verify. See [the module ABI](../../docs/module-abi.md)
+for dependency resolution and [the installation guide](../../docs/installation.md)
+for the integrity and provenance limits.
+
+`tests/e2e.test.sh` runs these scenarios in quarantined homes: every
+available host shell, a tamper lane, and the composition lane. Configured
+Lima Linux, BusyBox, and BSD guests run the same install and load checks
+when their VMs are present.

package/examples/e2e/bundles.tsv

@@ -0,0 +1,6 @@
+bundle	shell	roots
+default	sh	e2e_env_setup e2e_generated_config e2e_optional_network e2e_layer_probe e2e_platform_tools
+default	bash	e2e_env_setup e2e_generated_config e2e_optional_network e2e_layer_probe e2e_platform_tools e2e_aliases e2e_completions_bash
+default	zsh	e2e_env_setup e2e_generated_config e2e_optional_network e2e_layer_probe e2e_platform_tools e2e_aliases e2e_completions_zsh
+default	ksh	e2e_env_setup e2e_generated_config e2e_optional_network e2e_layer_probe e2e_platform_tools e2e_ksh_features
+default	fish	e2e_fish_features

package/examples/e2e/module.d/e2e_aliases.meta

@@ -1,9 +1,8 @@
 name=e2e_aliases
 requires=e2e_env_setup
 optional=
-shells=sh bash zsh ksh
+shells=posix bash zsh ksh
 platforms=any
 side_effect=read-only
 exports=e2e_show_aliases
-updates=
 load=modules/e2e/aliases.sh

package/examples/e2e/module.d/e2e_completions_bash.meta

@@ -5,5 +5,4 @@ shells=bash
 platforms=any
 side_effect=read-only
 exports=e2e_bash_completions_loaded
-updates=
 load=modules/e2e/completions_bash.sh

package/examples/e2e/module.d/e2e_completions_zsh.meta

@@ -5,5 +5,4 @@ shells=zsh
 platforms=any
 side_effect=read-only
 exports=e2e_zsh_completions_loaded
-updates=
 load=modules/e2e/completions_zsh.sh

package/examples/e2e/module.d/e2e_env_setup.meta

@@ -1,9 +1,8 @@
 name=e2e_env_setup
-requires=platform_posix
+requires=valise_platform_posix
 optional=
-shells=sh bash zsh ksh
+shells=posix bash zsh ksh
 platforms=any
 side_effect=read-only
 exports=e2e_env_ready
-updates=
 load=modules/e2e/env_setup.sh

package/examples/e2e/module.d/e2e_fish_features.meta

@@ -5,5 +5,4 @@ shells=fish
 platforms=any
 side_effect=read-only
 exports=e2e_fish_loaded
-updates=
 load=modules/e2e/fish_features.fish