Skip to content

docs(spec): record Phodopus successor direction in plugin runtime RFCs (CTX-0043) #80

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Xuepoo merged 1 commit into from
Sep 20, 2026
Merged

docs(spec): record Phodopus successor direction in plugin runtime RFCs (CTX-0043) #80

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 19 additions & 10 deletions runtime/isolation-resource-rfc.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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:

Expand All @@ -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 |
Expand Down
Loading
Loading