36 lines
2.0 KiB
Markdown
36 lines
2.0 KiB
Markdown
# 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.
|