Description
Audited Code Execution Runs provide the one trusted host boundary every sandbox request crosses. Before dispatch, the runner compares the request's grant with the selected executor's advertised capabilities and denies any network, Dots API, secret, filesystem, language, or limit demand the provider cannot enforce. It also applies a host-side wall-clock timeout and converts unexpected provider throws into sanitized terminal results.
After every terminal outcome, including disabled or capability-denied requests that never reached a sandbox, the runner writes one immutable audit record. The ledger captures run ID, company and actor, purpose, language, a SHA-256 hash of the code, capability grant, provider, status, and usage without storing source code, auth material, or untrusted error text. Audit persistence is mandatory: if recording fails, the caller receives a dedicated audit failure that preserves the run's true terminal status.
Selling Points
- Every code path shares one capability check, preventing a consumer from bypassing provider limits through a direct call.
- Denied and disabled attempts are observable alongside successful, failed, and timed-out executions.
- Code hashing supports incident correlation without copying potentially sensitive source into the audit ledger.
- Immutable, actor- and company-attributed records give operators a durable answer to who ran what class of code and under which grant.
- Mandatory audit failure signaling prevents an unrecorded run from being reported as a clean success.
User Story
An organization investigates a plugin run that timed out after requesting network access. The audit ledger identifies the actor, provider, purpose, language, exact capability grant, code hash, terminal status, and duration. If another run used the same code, operators can correlate hashes without reading the source. A request that exceeded the provider's envelope appears as capability-denied even though no sandbox was launched.
Extension Surface
This feature is extensible. packages/code-execution/src/contracts/host-ports.ts defines the injected CodeExecutionAuditSink and actor-scoped data port contracts, and packages/code-execution/src/host/execution-runner.ts accepts any conforming executor and sink. Deployments can adapt storage behind the sink in-repo, but the mandatory one-record terminal audit semantics remain fixed.
Capabilities & Limits
- It checks executor capability envelopes before dispatch and applies host timeout containment.
- It records terminal outcomes with tenant, actor, purpose, provider, grant, usage, and code hash.
- It sanitizes thrown provider messages and surfaces audit-write failures explicitly.
- Limit: the record proves what the host observed and requested; it does not capture source code, sandbox-internal event history, or guarantees beyond the provider's declared and enforced envelope.
Implementation Map
packages/code-execution/src/host/execution-runner.tspackages/code-execution/src/host/audit-sink.tspackages/code-execution/src/contracts/host-ports.tspackages/code-execution/src/host/errors.tspackages/code-execution/src/host/dots-binding.ts