Description
Grant-Scoped Dots API Access for Sandboxes lets authorized plugin or script code call selected Dots data operations without receiving a user token, company ID, or unrestricted client. A capability grant can allow reads or writes for a named Dotabase, scoped search, edge reads or writes, or file reads. The host builds a binding over an already actor-scoped data port and exposes only operations whose exact scope appears in the grant.
For providers that need a process boundary, the host also supplies a per-run RPC registry and token that marshals dots.* calls back to the trusted application. The execution request itself remains tenant-free. Manifest capabilities map to targetless graph/search scopes and, when a runtime target is known, Dotabase-specific row scopes. If the executor claims Dots API support but no actor-scoped port is wired, execution fails closed before dispatch.
Selling Points
- Sandboxed code can work with Dots data without embedding broad API credentials in an untrusted environment.
- Operation-by-operation grants keep a plugin authorized for one Dotabase from reading or writing another.
- Actor-scoped host services preserve the platform's existing tenancy and access checks behind the sandbox boundary.
- The RPC transport supports real provider isolation while keeping enforcement in the trusted host.
- Missing transport or excess scope produces a policy denial instead of a silent no-op or partially authorized run.
User Story
An SDK behavior is allowed to read and update rows in the Dotabase that triggered it, but not inspect the rest of the workspace. The host binds that target into a grant, exposes only the corresponding dots.* methods, and runs the plugin. Attempts to search globally or create an edge are rejected by the binding. The developer receives a clear capability-denied result and never handles a reusable workspace credential.
Extension Surface
This feature is extensible. packages/code-execution/src/contracts/host-ports.ts defines structural data-port and binding contracts, and packages/code-execution/src/host/dots-rpc.ts provides a provider-neutral RPC registry. Composition roots can adapt actor-scoped services or provider transports in-repo. The allowed scope vocabulary itself is frozen in the execution contract and cannot be widened through data alone.
Capabilities & Limits
- It grants targeted row read/write, scoped search, edge read/write, and file-read operations.
- It derives grants from SDK manifest atoms and binds row scopes only when a real target is known.
- It fails closed when a Dots-capable executor lacks an actor-scoped host port.
- Limit: a concrete sandbox provider must implement the host transport; the shipped Docker and E2B adapters currently advertise no Dots API capability.
Implementation Map
packages/code-execution/src/host/dots-binding.tsdots.*packages/code-execution/src/host/dots-rpc.tspackages/code-execution/src/contracts/host-ports.tspackages/code-execution/src/grants.tspackages/code-execution/src/host/execution-runner.ts