tomoaki/hakorune
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
aabb67cdc22915c0c10023b0bf7acd66a1b2d50c
hakorune/docs/architecture/RINGS.md

2.3 KiB
Raw Blame History

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).