Skip to content

Define minimal cell ABI#210

Merged
seanwevans merged 2 commits into
mainfrom
codex/define-minimal-cell-abi-protocol
May 13, 2026
Merged

Define minimal cell ABI#210
seanwevans merged 2 commits into
mainfrom
codex/define-minimal-cell-abi-protocol

Conversation

@seanwevans
Copy link
Copy Markdown
Owner

Motivation

  • Pin and freeze the public cell surface to a very small, auditable ABI to avoid surface growth and ensure privileged operations go through broker capabilities.
  • Make channel events first-class (logs, metrics, broker requests) so the supervisor can treat guest emissions as structured, auditable envelopes.

Description

  • Add a versioned minimal ABI in pyisolate/runtime/protocol.py with CellOp, CellABI, MINIMAL_CELL_ABI, and new dataclasses: RecvRequest, PostEvent, LogEvent, MetricEvent, and BrokerRequest, and annotate ExecRequest/CallRequest with op fields.
  • Wire guest-facing helpers into the sandbox runtime in pyisolate/runtime/thread.py: log(level, message, **fields), metric(name, value, tags=None), and request(capability, action, payload=None) that emit the new channel event types and enforce capability gating for request(...).
  • Small refactors in SandboxThread to centralize emission (_emit) and keep post(...) semantics, and expose log/metric/request in the guest local_vars mapping supplied to executed code.
  • Update docs and public API wording to describe the frozen seven-operation surface (exec, call, post, recv, log, metric, request) in docs/ plus API.md and README.md.
  • Add and update conformance tests in tests/test_protocol_plane.py to assert the ABI is frozen, validate channel event shapes, and verify capability-gated broker requests.

Testing

  • Ran the focused test set: PYTHONPATH=. pytest tests/test_sandbox.py tests/test_protocol_plane.py -q, which passed (20 passed).
  • Ran PYTHONPATH=. python -m compileall pyisolate tests/test_protocol_plane.py -q and formatting checks with black --target-version py311 --check on the touched files; these succeeded after applying formatting.
  • Note: running the full test suite (PYTHONPATH=. pytest -q) exposed unrelated suite-order/test-double contamination around the test stub for BPFManager.load() (the stub does not accept the mode keyword), which causes many tests to fail; this is orthogonal to the ABI changes and unchanged by this PR.

Codex Task

@seanwevans seanwevans merged commit 4939b7e into main May 13, 2026
@seanwevans seanwevans deleted the codex/define-minimal-cell-abi-protocol branch May 13, 2026 13:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant