ADR: Global Installer Contract and Canonical Manifest (`installer.v1`)

Date: 2026-03-03
Status: Accepted
Scope: beadboard-05a.1.1 + beadboard-05a.1.2

Context

The beadboard-05a epic requires one installer contract shared by all platform wrappers and launcher behavior.
Without a canonical schema, wrappers can drift and the driver skill can emit inconsistent remediation guidance.

Constraints:

bd remains source of truth for work state.
Driver skill must remain detect/remediate only, with no install side effects.
Windows and POSIX wrappers must map to one shared semantic model.

Decision

Adopt installer.v1 as the canonical manifest contract and validate it centrally in code.

Contract requirements:

Versioned schema

version must be exactly installer.v1.

Distribution contract

distribution.packageName declares the global package identity.
distribution.shimNames declares required command shims (bb, beadboard).

Wrapper contract

wrappers.windows.script and wrappers.posix.script are required and explicit.

Runtime command contract

runtime.start, runtime.open, and runtime.status are required.

Driver boundary contract

driver.remediationMode must be detect_only.
driver.installSideEffects must be false.

Implementation

Added canonical validator and type contract:

src/lib/install-manifest.ts
tests/lib/install-manifest.test.ts

Exported artifacts:

INSTALLER_SCHEMA_VERSION = "installer.v1"
validateInstallerManifest(input)
canonicalInstallerManifest for shared reference in downstream wrapper and launcher tasks

Verification Evidence

TDD red:

node --import tsx --test tests/lib/install-manifest.test.ts
failed with Cannot find module '../../src/lib/install-manifest'

TDD green:

node --import tsx --test tests/lib/install-manifest.test.ts
passed (4/4)

Suite registration:

package.json test script now explicitly includes tests/lib/install-manifest.test.ts

Consequences

Positive:

Platform wrappers now have one schema target.
Launcher semantics are pre-declared before wrapper implementation.
Driver detection-only boundary is encoded in validator rules.

Tradeoff:

Wrapper and CI tasks (05a.2+) must now conform to installer.v1; they cannot introduce ad hoc fields.

Runtime Manager Alignment

This ADR is paired with docs/adr/2026-03-03-runtime-manager-global-install.md.

Canonical runtime home is ~/.beadboard/runtime/<version>.
Global install (npm i -g beadboard) is the primary operator path.
Wrappers remain supported as fallback bootstraps.
Legacy repo-bound shim migration is mandatory for backward compatibility.

2.7 KiB Raw Blame History

ADR: Global Installer Contract and Canonical Manifest (installer.v1)