40 lines
2.3 KiB
Markdown
40 lines
2.3 KiB
Markdown
|
# Runtime Rings Architecture (ring0 / ring1 / ring2)
|
||
|
|
|
||
|
|
Purpose: clarify responsibilities and naming for core runtime layers, and make provider selection and diagnostics consistent without large code moves.
|
||
|
|
|
||
|
|
Overview
|
||
|
|
- ring0 (Kernel): Core executor/runner/host-bridge. Responsible for fail-fast and process orchestration. No direct business logic of boxes.
|
||
|
|
- ring1 (Core Providers): Minimal, trusted, always-available providers (static). Example: FileBox Core-RO (open/read/close). Small, reproducible, and safe to enable under fail-fast.
|
||
|
|
- ring2 (Plugins): Dynamic, featureful providers. Swappable and extensible. Example: Array/Map plugins, full-feature FileBox plugin.
|
||
|
|
|
||
|
|
Mapping (current repo)
|
||
|
|
- ring0: src/ring0/ (facade + guard; re-exports are deferred). Existing core remains under src/*; ring0 is a conceptual anchor.
|
||
|
|
- ring1: src/providers/ring1/ (facade + guard). Concrete code still lives where it is; ring1 hosts documentation and future home for static providers.
|
||
|
|
- ring2: plugins/ (dynamic shared libraries, as before).
|
||
|
|
|
||
|
|
Selection Policy (Auto mode)
|
||
|
|
- Global: `HAKO_PROVIDER_POLICY=strict-plugin-first|safe-core-first|static-preferred`
|
||
|
|
- strict-plugin-first (default): prefer dynamic/plugin; fallback to ring1 when allowed.
|
||
|
|
- safe-core-first/static-preferred: prefer ring1 (static) when available; fallback to plugin.
|
||
|
|
- Per box (example: FileBox)
|
||
|
|
- `NYASH_FILEBOX_MODE=auto|ring1|plugin-only`
|
||
|
|
- `NYASH_FILEBOX_ALLOW_FALLBACK=0|1` (narrow dev override)
|
||
|
|
|
||
|
|
Diagnostics (stderr, quiet when JSON_ONLY=1)
|
||
|
|
- Selection: `[provider/select:<Box> ring=<0|1|plugin> src=<static|dynamic>]`
|
||
|
|
- Fail-Fast block: `[failfast/provider/<box>:<reason>]`
|
||
|
|
|
||
|
|
Design Invariants
|
||
|
|
- ring0 must not depend on ring2. ring1 contains only minimal stable capabilities.
|
||
|
|
- Fallback is disallowed by default (Fail-Fast). Allow only via per-box override or JSON_ONLY quiet pipe.
|
||
|
|
|
||
|
|
Migration Plan (small steps)
|
||
|
|
1) Add facades and guards (this change).
|
||
|
|
2) Keep existing code paths; introduce provider policy (done for FileBox).
|
||
|
|
3) Gradually move minimal static providers under `src/providers/ring1/` (no behavior change).
|
||
|
|
4) Add canaries to assert selection tags under different policies.
|
||
|
|
|
||
|
|
Notes on Naming
|
||
|
|
- Historical names like "builtin" referred to in-tree providers. To avoid confusion, use ring terms: ring0 (kernel), ring1 (core providers), ring2 (plugins).
|
||
|
|
|