# Naming and contract migrations

This page tracks **non-breaking** renames and compatibility paths. Handbook, user manual, and reference docs should stay aligned when entries here change.

## Boot hook API (ctx)

| Canonical (preferred) | Legacy alias | Notes |
| --- | --- | --- |
| `bareOsRegisterBootStepHook(step, fn)` | `bareOsRegisterBootPhaseHook(phase, fn)` | Same matching rules; `step` and `phase` are the same string keyspace. |
| `bareOsInvokeBootStepHooks(ev)` | `bareOsInvokeBootPhaseHooks(ev)` | Event objects may include `phase`, `step`, and `when`; hooks match on `phase` / `when:phase` as before. |
| `bareOsEmitBareBootStepHint(payload)` | `bareOsEmitBareBootPhaseHint(payload)` | Accepts `step` or `phase` in payload; host event name unchanged for listeners. |

Deprecation: legacy names remain supported; no removal date is set until downstream consumers migrate.

## Boot policy JSON

| Canonical key(s) | Legacy alias(es) |
| --- | --- |
| `skipBootStages`, `denyBootStages` | `skipPhases`, `denyBootPhases` |
| `bootStagesRequireProcIndexMinSchema` | `bootPhasesRequireProcIndexMinSchema` |
| `bootStagesRequireLifecycleMinSchema` | `bootPhasesRequireLifecycleMinSchema` |

Merge logic accepts **both** names; first-party docs should cite canonical keys only.

## Boot ready / journal payloads

- `bareOsPublishBootReady` may expose both `stages` / `phases` and `bootStages` / `bootPhases` mirrors for consumers. Prefer **`stages`** / **`bootStages`** in new code.

## Boot trace JSON (`BARE_OS_BOOT_TRACE=json`)

- Schema **`bootTraceSchemaVersion`**: **2** adds canonical **`step`** alongside **`stage`** and legacy **`phase`** (mirror). Parsers should prefer **`step`**.

## CI gates

- `npm run pretest` runs `bundle:kernel`, `verify-banned-terminology`, `verify-naming-alias-matrix`, `verify-feature-roadmap-canonical`, `verify-no-new-giant-phase-identifiers`, compatibility matrix checks, and contract verifiers. Changing `bareOsCtxApiVersion` or capability bits requires updating the linked scripts and docs listed in the root `package.json` `pretest` chain.