beadboard/docs/adr/2026-03-03-runtime-manager-global-install.md

# ADR: Runtime Manager for Global Install

- Date: 2026-03-03
- Status: Accepted
- Scope: Global installer runtime execution model

## Context

The installer currently supports wrappers and launcher behavior, but runtime location and shim targets must be stable across updates and usable from any working directory.

## Decision

Adopt a runtime-manager layout rooted at `~/.beadboard/runtime/<version>` with stable command shims in `~/.beadboard/bin`.

Primary install flow is npm global:

- `npm i -g beadboard`

Fallback install flow remains script bootstrap wrappers when npm-global is unavailable.

All shims resolve a runtime target from runtime metadata first, then execute launcher logic from the selected runtime root.

## Runtime Layout

- Runtime root: `~/.beadboard/runtime/<version>`
- Stable metadata: `~/.beadboard/runtime/current.json`
- Stable shim directory: `~/.beadboard/bin`
- Required shims: `bb`, `beadboard`

## Update / Uninstall Model

- Update writes a new versioned runtime directory and atomically switches `current.json`.
- Uninstall removes runtime directories and shims after explicit confirmation.
- Failed updates do not replace active metadata; previous runtime remains executable.

## Compatibility and Migration

Legacy repo-bound shim migration is required:

- Detect legacy shims that hardcode repository-relative launcher paths.
- Rewrite shims to runtime-managed targets atomically.
- Preserve user-facing command names and shell compatibility.

## Supported Platforms

- Linux: npm-global primary, POSIX wrapper fallback.
- macOS: npm-global primary, POSIX wrapper fallback.
- Windows: npm-global primary, PowerShell wrapper fallback.

## Failure Modes and Rollback

- Missing runtime metadata: launcher reports actionable remediation and install mode.
- Corrupt runtime target: launcher falls back to previous known-good metadata when present.
- Partial install: installer leaves active runtime unchanged and exits non-zero.