feat(installer): prefer npm next lane (#688)

--next now prefers a fast npm @next install (CLI + gateway from the Gitea registry) and falls back to source build at next if the dist-tag is unavailable. Registry lane gated to non-dev, non-explicit-ref next installs; CLI/gateway prerelease versions must share a pipeline suffix. Adds tools/install-next-lane.test.sh (wired into CI). PR-event CI 1635 fully green + review-of-record APPROVE (functional install test, head 2fd7cfc3).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/design/prerelease-next-dist-tag-pipeline.md

@@ -1,40 +1,63 @@
-# Planned Design — npm `@next` prerelease lane
+# npm `@next` prerelease lane
 
-Status: **PLANNED / not yet built**
+Status: **IMPLEMENTED**
 
-## Current state
+## Current behavior
 
-`tools/install.sh --next` provides a prerelease integration lane by building the Mosaic CLI and gateway from source at the permanent `next` branch. This is correct for validating integration-branch source, but it is slower than the stable npm lane because it downloads the archive, installs workspace dependencies, builds packages, packs local tarballs, and installs those tarballs globally.
+`tools/install.sh --next` provides the prerelease integration lane for the permanent `next` branch.
 
-## Medium-term target
+The lane is fast-by-default:
 
-Publish every accepted `next` integration build to the npm registry under the `@next` dist-tag, for example:
+1. Install framework files from the `next` source archive.
+2. Resolve the Gitea npm registry `next` dist-tag for the globally installed packages:
+
+   ```bash
+   npm view @mosaicstack/gateway@next version
+   npm view @mosaicstack/mosaic@next version
+   ```
+
+3. Require both resolved versions to share the same `next.<pipeline>` suffix, then install the exact resolved versions.
+4. If either `@next` package is missing, unreachable, mismatched, or fails to install, fall back to the source-build path at `next`.
+
+`--next` never hard-fails solely because the prerelease npm dist-tag is unavailable.
+
+## Published packages
+
+The `next` publish pipeline publishes non-private `@mosaicstack/*` packages to the Mosaic Gitea npm registry:
 
 ```text
-@mosaicstack/mosaic@0.0.49-next.1
-@mosaicstack/mosaic@0.0.49-next.2
+https://git.mosaicstack.dev/api/packages/mosaicstack/npm/
 ```
 
-Then move `tools/install.sh --next` from source-build behavior to a fast npm install:
+Observed `next` dist-tags after enabling the pipeline:
 
-```bash
-npm install -g @mosaicstack/mosaic@next
+```text
+@mosaicstack/mosaic@next  -> 0.0.49-next.1633
+@mosaicstack/gateway@next -> 0.0.7-next.1633
 ```
 
-The framework archive should still resolve from the matching `next` source/ref until framework packaging has a registry-backed equivalent.
+The gateway also publishes a Docker image as `gateway:sha-<short>` on `next` merges. The installer fast path uses the npm gateway package when available; the Docker image is for deployed gateway/runtime harness flows.
+
+## Explicit source lanes
+
+Source builds remain available and are still the authority for explicit ref validation:
+
+- `--dev` always builds from source.
+- `--ref <ref>` / `MOSAIC_REF=<ref>` wins over `--next` and uses the source path for that exact ref.
 
 ## Pipeline shape
 
-1. Trigger on successful CI for `next`.
-2. Compute the next prerelease version from the upcoming stable version plus a monotonic prerelease counter (`0.0.49-next.N`).
-3. Build and pack publishable packages in CI.
+1. Trigger on `next` merges.
+2. Compute the next prerelease version from the upcoming stable version plus the Woodpecker pipeline number (`<target-stable>-next.<CI_PIPELINE_NUMBER>`).
+3. Build and publish non-private packages in CI.
 4. Publish to the Mosaic Gitea npm registry with dist-tag `next`.
 5. Keep `latest` untouched; only main/release promotion can update `latest`.
-6. Teach the installer to prefer `@next` for the CLI/gateway prerelease lane once the registry tag is reliable.
+6. Publish gateway Docker images from `next` as `gateway:sha-<short>` only.
 
 ## Guardrails
 
 - `@next` is mutable prerelease convenience, not a deployment pin.
 - Stable installs continue to use `@latest`.
 - Contributor validation remains available through `--dev --ref <branch>`.
-- Pipeline must be reproducible and trace every prerelease package back to the source commit on `next`.
+- Pipeline output traces every prerelease package back to the source commit on `next`.
+- The installer falls back to source rather than hard-failing on prerelease registry issues.