diff --git a/runtime/isolation-resource-rfc.md b/runtime/isolation-resource-rfc.md index b3b0c95..397f8bf 100644 --- a/runtime/isolation-resource-rfc.md +++ b/runtime/isolation-resource-rfc.md @@ -52,13 +52,20 @@ sidebar_order: 17 > `Draft -> experimental review evidence -> Accepted (2026-08-28) -> normative`; all RC > budgets now enforced measured and accepted 2026-08-28 (frontmatter `accepted`, closed OQ-014). -A candidate successor direction for the plugin VM is recorded in the -[Phodopus Plugin Runtime (Candidate)](phodopus-runtime-candidate.md): it maps -this RFC's RC-1, RC-2, and RC-11 ceilings and the FS-1..FS-9 failure semantics -onto a sandbox-quota runtime builder at the design level only. The accepted -isolation domains, resource ceilings, failure semantics, and adversarial test -specification above are unchanged, and that candidate promotes no status or -compatibility promise. +Successor direction (2026-09-20): the plugin-VM enforcement engine moves from +`piccolo` toward **Phodopus**, the sandbox-first successor fork, per +[ADR 0012](https://github.com/bitty-terminal/bitty-docs/blob/main/docs/decisions/adrs/ADR-0012-phodopus-runtime.md), +which refines the `piccolo` retention in +[ADR 0005](https://github.com/bitty-terminal/bitty-docs/blob/main/docs/decisions/adrs/ADR-0005-lua-pins-and-stdlib.md). +The accepted RC-1/RC-2/RC-11 ceilings and the dated measurement evidence above +are unchanged; the current `bitty-lua` `piccolo` 0.3.3 `Fuel`/wall enforcement +stays accurate until a migration task lands. The plugin-side consequences are +recorded in the [Phodopus Plugin Runtime (Candidate)](phodopus-runtime-candidate.md), +which maps this RFC's RC-1, RC-2, and RC-11 ceilings and the FS-1..FS-9 failure +semantics onto a sandbox-quota runtime builder at the design level only. The +accepted isolation domains, resource ceilings, failure semantics, and +adversarial test specification above are unchanged, and that candidate +promotes no status or compatibility promise. ## Purpose and scope @@ -86,7 +93,9 @@ Out of scope: capability identifiers and manifest schema (OQ-012, accepted in accepted), event interception phases (OQ-013, accepted), image protocol limits (OQ-008, which owns decompression budgets), IPC protocol wire format (OQ-018), and Lua runtime selection mechanics (OQ-009, accepted in [Lua Runtime RFC](lua-runtime-rfc.md); ADR 0004 records that `piccolo` -adoption timing is decided with this RFC and OQ-030..032 remain Open). +adoption timing is decided with this RFC, OQ-030..032 remain Open, and +[ADR 0012](https://github.com/bitty-terminal/bitty-docs/blob/main/docs/decisions/adrs/ADR-0012-phodopus-runtime.md) +records Phodopus as the plugin-VM successor direction). ## Normative precedence @@ -232,7 +241,7 @@ Proposed mechanisms: ## Proposed resource ceilings -Status: **accepted** on 2026-08-28; initial values with measurement evidence for queue budgets and VM budgets (2026-08-27) now accepted. Per-subscription 64, per-plugin 1024 events / 256 KiB (enforced at `EventPipeline::publish` via `DropOldest`), `BoundedText` 8 KiB, `drain_batch` strict, Global 8192 events / 2 MiB hard-gated at Host admission, RC-1 10^7 VM instructions / 50 ms wall / 8 ms warning hard-gated via `piccolo` Fuel + wall deadline, and RC-2 32 MiB via `Lua::total_memory()` are now measured via `bitty/crates/bitty-plugin-host/tests/measurement.rs` (21 headless tests, Global hard-gated) and `bitty/crates/bitty-lua/tests/measurement_lua.rs` (15 headless tests, RC-1/RC-2; instrumentation `event.rs`/`host.rs`: `budget_snapshot`, `invariant_*`, `publish_count`; `bitty-lua`: `VmBudgetSnapshot`, `would_exceed_lua_limits`, `piccolo` 0.3.3 Fuel/wall) as experimental review evidence per bitty CTX-0037 PR #68 / CTX-0040 `d67a65b` (docs CTX-0049 / CTX-0050); Global is now enforced hard-gated (fail-closed) via `would_exceed_global_limits` + `evict_oldest_globally` with shared `DropPolicy`, RC-1/RC-2 hard-gated fail-closed suspend, accepted 2026-08-28. All values follow the [Performance Budget RFC](https://github.com/bitty-terminal/bitty-terminal-docs/blob/main/specifications/performance-budget-rfc.md) convention that numbers are target contracts; tests must parameterize on the declared values; changing a value requires an RFC revision, never silent drift. Lifecycle is `Draft -> experimental review evidence -> Accepted (2026-08-28) -> normative`. +Status: **accepted** on 2026-08-28; initial values with measurement evidence for queue budgets and VM budgets (2026-08-27) now accepted. Per-subscription 64, per-plugin 1024 events / 256 KiB (enforced at `EventPipeline::publish` via `DropOldest`), `BoundedText` 8 KiB, `drain_batch` strict, Global 8192 events / 2 MiB hard-gated at Host admission, RC-1 10^7 VM instructions / 50 ms wall / 8 ms warning hard-gated via `piccolo` Fuel + wall deadline, and RC-2 32 MiB via `Lua::total_memory()` are now measured via `bitty/crates/bitty-plugin-host/tests/measurement.rs` (21 headless tests, Global hard-gated) and `bitty/crates/bitty-lua/tests/measurement_lua.rs` (15 headless tests, RC-1/RC-2; instrumentation `event.rs`/`host.rs`: `budget_snapshot`, `invariant_*`, `publish_count`; `bitty-lua`: `VmBudgetSnapshot`, `would_exceed_lua_limits`, `piccolo` 0.3.3 Fuel/wall) as experimental review evidence per bitty CTX-0037 PR #68 / CTX-0040 `d67a65b` (docs CTX-0049 / CTX-0050); Global is now enforced hard-gated (fail-closed) via `would_exceed_global_limits` + `evict_oldest_globally` with shared `DropPolicy`, RC-1/RC-2 hard-gated fail-closed suspend, accepted 2026-08-28. All values follow the [Performance Budget RFC](https://github.com/bitty-terminal/bitty-terminal-docs/blob/main/specifications/performance-budget-rfc.md) convention that numbers are target contracts; tests must parameterize on the declared values; changing a value requires an RFC revision, never silent drift. Lifecycle is `Draft -> experimental review evidence -> Accepted (2026-08-28) -> normative`. Successor direction (2026-09-20): the plugin-VM enforcement engine moves from `piccolo` toward Phodopus per [ADR 0012](https://github.com/bitty-terminal/bitty-docs/blob/main/docs/decisions/adrs/ADR-0012-phodopus-runtime.md); the ceilings and the dated measurement evidence above are unchanged, and the current `bitty-lua` `piccolo` 0.3.3 `Fuel`/wall enforcement stays accurate until a migration task lands. Two rules hold regardless of final values: @@ -246,7 +255,7 @@ Two rules hold regardless of final values: | ID | Dimension | Applies to | Proposed default | Floor and maximum policy | | ----- | --------------------------------------- | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| RC-1 | Callback CPU/instruction budget | each plugin callback | 10^7 VM instructions or 50 ms wall clock, whichever first; 8 ms warning (hard-gated measured via `bitty-lua` `piccolo` 0.3.3 Fuel + wall deadline, fail-closed suspend, measured 2026-08-27 via `crates/bitty-lua/tests/measurement_lua.rs` 15 headless tests @ `d67a65b`, worktree `ctx-0040/feat-lua-vm-budgets`) | Enforced measured via `bitty-lua` `piccolo` Fuel + wall deadline (10^7 / 50 ms / 8 ms warning, fail-closed suspend) @ `d67a65b` `measurement_lua.rs` 15 tests; constants `RC1_*` parameterized in harness; accepted 2026-08-28 | +| RC-1 | Callback CPU/instruction budget | each plugin callback | 10^7 VM instructions or 50 ms wall clock, whichever first; 8 ms warning (hard-gated measured via `bitty-lua` `piccolo` 0.3.3 Fuel + wall deadline, fail-closed suspend, measured 2026-08-27 via `crates/bitty-lua/tests/measurement_lua.rs` 15 headless tests @ `d67a65b`, worktree `ctx-0040/feat-lua-vm-budgets`) | Enforced measured via `bitty-lua` `piccolo` Fuel + wall deadline (10^7 / 50 ms / 8 ms warning, fail-closed suspend) @ `d67a65b` `measurement_lua.rs` 15 tests; constants `RC1_*` parameterized in harness; accepted 2026-08-28; successor enforcement engine direction is Phodopus per [ADR 0012](https://github.com/bitty-terminal/bitty-docs/blob/main/docs/decisions/adrs/ADR-0012-phodopus-runtime.md) (2026-09-20), current `piccolo` enforcement accurate until migration | | RC-2 | Memory per plugin VM | each plugin | 32 MiB accounted allocations (hard-gated measured via `Lua::total_memory()` 32 MiB suspend, measured 2026-08-27 via `crates/bitty-lua/tests/measurement_lua.rs` 15 headless tests @ `d67a65b`) | Enforced measured via `Lua::total_memory()` hard-gated suspend @ `d67a65b` `measurement_lua.rs` 15 tests; floor 8 MiB; policy maximum 256 MiB; accepted 2026-08-28 | | RC-3 | Aggregate plugin memory | all plugins | 512 MiB reserved shares, lazy plugins included | scales with PB-2/PB-3 headroom | | RC-4 | Live tasks and timers | each plugin | 64 tasks, 32 timers | refusal above cap; no burst queueing | diff --git a/runtime/lua-runtime-rfc.md b/runtime/lua-runtime-rfc.md index 71e81a3..8e99c91 100644 --- a/runtime/lua-runtime-rfc.md +++ b/runtime/lua-runtime-rfc.md @@ -27,19 +27,23 @@ beyond the accepted contract. [ADR 0004](https://github.com/bitty-terminal/bitty-docs/blob/main/docs/decisions/adrs/ADR-0004-upstream-dependencies.md) has selected `mlua` with Lua 5.4 as the P0 baseline (`vendored` Lua 5.4 sources built with -the core crate; `piccolo` remains a watch-list candidate per the ADR). This RFC +the core crate; `piccolo` was the watch-list candidate per the ADR). This RFC does not re-decide the runtime choice; it specifies the sandbox, standard library subset, module resolution, diagnostics, limits, and lifecycle contract built on that baseline. That authority remains unchanged per the Wave-C closure review on 2026-08-27 (CTX-0047) and independent security-auditor review. -A candidate successor direction for the plugin VM is recorded in the -[Phodopus Plugin Runtime (Candidate)](phodopus-runtime-candidate.md): it +The plugin-VM successor direction is now Phodopus, the sandbox-first fork of +`piccolo`, per [ADR 0012](https://github.com/bitty-terminal/bitty-docs/blob/main/docs/decisions/adrs/ADR-0012-phodopus-runtime.md) +(accepted 2026-09-20), which refines the `piccolo` watch-list clause without +rewriting the accepted baseline. The plugin-side consequences are recorded in +the [Phodopus Plugin Runtime (Candidate)](phodopus-runtime-candidate.md): it refines this RFC's module-resolution, sandbox-quota, pattern, and async consequences at the design level only. The accepted runtime choice, sandbox, restricted standard-library subset, rooted module search, source-only loading, -and diagnostics contract above are unchanged, and that candidate promotes no -status or compatibility promise. +and diagnostics contract above are unchanged, the accepted `mlua`/Lua 5.4 +baseline stands, and the current `bitty-lua` `piccolo` pin remains accurate +until a migration task lands. It targets OQ-009; it feeds, but does not decide, OQ-010 (configuration model), OQ-011/OQ-012 (Plugin API v1 and capabilities), OQ-014 (isolation and resource @@ -70,7 +74,7 @@ Normative sources this specification must not weaken: - [Core boundaries](https://github.com/bitty-terminal/bitty-terminal-docs/blob/main/architecture/core-boundaries.md): security policy cannot be delegated to Lua; plugins never enter the terminal, render, or input hot paths. -- [Technology strategy](https://github.com/bitty-terminal/bitty-docs/blob/main/docs/project/technology-strategy.md) and [ADR 0004](https://github.com/bitty-terminal/bitty-docs/blob/main/docs/decisions/adrs/ADR-0004-upstream-dependencies.md): `mlua` with Lua 5.4 is the P0 baseline (`vendored` Lua 5.4 sources built with the core crate; `piccolo` remains a watch-list candidate). Required validation covering Windows/macOS/Linux/BSD builds, sandbox capability, VM cost, and async/Send requirements still applies; Lua 5.4 is preferred over LuaJIT. +- [Technology strategy](https://github.com/bitty-terminal/bitty-docs/blob/main/docs/project/technology-strategy.md) and [ADR 0004](https://github.com/bitty-terminal/bitty-docs/blob/main/docs/decisions/adrs/ADR-0004-upstream-dependencies.md): `mlua` with Lua 5.4 is the P0 baseline (`vendored` Lua 5.4 sources built with the core crate; `piccolo` was the watch-list candidate). The plugin-VM successor direction is Phodopus per [ADR 0012](https://github.com/bitty-terminal/bitty-docs/blob/main/docs/decisions/adrs/ADR-0012-phodopus-runtime.md), which refines that watch-list clause. Required validation covering Windows/macOS/Linux/BSD builds, sandbox capability, VM cost, and async/Send requirements still applies; Lua 5.4 is preferred over LuaJIT. - [Threat model](https://github.com/bitty-terminal/bitty-docs/blob/main/docs/security/threat-model.md): T-06 (VM escape via unrestricted libraries) and T-14 (unsafe/FFI defects), with risks R-006, R-007, and R-018 in the [risk register](https://github.com/bitty-terminal/bitty-docs/blob/main/docs/security/risk-register.md). diff --git a/runtime/plugin-host-runtime-rfc.md b/runtime/plugin-host-runtime-rfc.md index c450166..8e237d8 100644 --- a/runtime/plugin-host-runtime-rfc.md +++ b/runtime/plugin-host-runtime-rfc.md @@ -23,6 +23,16 @@ sidebar_order: 30 > Draft -> experimental review evidence -> Accepted -> normative; only > Accepted or normative documents authorize shipped behavior. +Successor direction (2026-09-20): the plugin VM behind the `bitty-lua` seam +moves from `piccolo` toward **Phodopus**, the sandbox-first successor fork, per +[ADR 0012](https://github.com/bitty-terminal/bitty-docs/blob/main/docs/decisions/adrs/ADR-0012-phodopus-runtime.md), +which refines the `piccolo` retention in +[ADR 0005](https://github.com/bitty-terminal/bitty-docs/blob/main/docs/decisions/adrs/ADR-0005-lua-pins-and-stdlib.md). +The host bridge boundary, per-plugin VM lifecycle, host-service wiring, and the +current `bitty-lua` `piccolo` 0.3.3 pin specified below are unchanged; the seam +stays accurate until a migration task lands. This refinement adds direction +only and promotes no status. + ## Purpose and scope The `bitty` live campaign `CTX-0320` reported defect D4 (P0): the plugin host is @@ -58,7 +68,10 @@ Out of scope, owned elsewhere and only referenced here: - Restricted standard library, rooted module resolution rules, diagnostics classes ([Lua Runtime RFC](lua-runtime-rfc.md), accepted), the `mlua` versus `piccolo` split and pins - ([ADR 0005](https://github.com/bitty-terminal/bitty-docs/blob/main/docs/decisions/adrs/ADR-0005-lua-pins-and-stdlib.md)), environment + ([ADR 0005](https://github.com/bitty-terminal/bitty-docs/blob/main/docs/decisions/adrs/ADR-0005-lua-pins-and-stdlib.md); + plugin-VM successor direction is Phodopus per + [ADR 0012](https://github.com/bitty-terminal/bitty-docs/blob/main/docs/decisions/adrs/ADR-0012-phodopus-runtime.md), + current `piccolo` pin accurate until migration), environment reads ([ADR 0006](https://github.com/bitty-terminal/bitty-docs/blob/main/docs/decisions/adrs/ADR-0006-os-env-policy.md)), and the Config VM async boundary ([ADR 0007](https://github.com/bitty-terminal/bitty-docs/blob/main/docs/decisions/adrs/ADR-0007-async-gc.md)). - Resource ceilings and their numbers @@ -242,7 +255,10 @@ Unloaded -> Loading -> Activating -> Active -> Suspended -> Disposing -> Dispose - A `piccolo` VM is not `Send`. A VM is created, executed, suspended, and disposed on a single owning executor thread. Host service handles that must cross thread boundaries are `Send` and the VM holds only generation-local - handles or task ids. + handles or task ids. The successor runtime direction is Phodopus per + [ADR 0012](https://github.com/bitty-terminal/bitty-docs/blob/main/docs/decisions/adrs/ADR-0012-phodopus-runtime.md), + which preserves this single-owner-thread boundary; the current `piccolo` VM + remains accurate until a migration task lands. - Failure is contained: a bridge or callback failure suspends or disposes only the owning generation and never crashes the host.