Skip to content
DotBoxD

Glossary

Short, plain-language definitions of the core DotBoxD terms, each linking to the page that covers it in depth. If you landed mid-tree - say on Pushdown or Kernel runtime - look the unfamiliar words up here first, then follow the link for the full treatment.

Sandbox and kernels

Section titled “Sandbox and kernels”
  • Kernel - Client/plugin-supplied logic the host runs safely under policy, as validated, capability-gated, fuel-metered restricted IR - never C#, IL, or reflection.
  • IR (intermediate representation) - The restricted, JSON-authored instruction format a kernel is expressed in; the host rejects anything outside the allowed shape before it runs.
  • Lowering - Compile-time rewriting of authored C# (a .Where/.Select chain or a [ServerExtension] batch) into verified IR that runs server-side.
  • Host binding - A [HostBinding] method the host explicitly exposes; the only way a kernel reaches outside pure computation, and only when the matching capability is granted.
  • Capability - A named grant (e.g. file.read) the host policy must give before a kernel may use the matching effect; derived from the IR the kernel actually touches, and fail-closed.
  • Effect (SandboxEffect) - The category of outside-world impact an operation has (Cpu, Alloc, file/network/host effects, Time, Random, Concurrency, Audit), controlled by the policy.
  • Fuel and metering (quota) - Fuel is an abstract instruction budget; metering charges every operation and enforces loop, call-depth, list-length, output, and per-capability quotas, stopping a kernel that runs over.
  • SandboxPolicy - The immutable hard budget every kernel run is bounded by: fuel, loop/depth/output limits, capability grants, and effect controls.
  • Manifest - The public artifact declaring a kernel’s required capabilities (the union of what its IR touches); install fails closed if the host policy does not grant them.
  • Trust boundary - The line that actually contains untrusted code: validated kernel IR is one; loading a .NET assembly (AssemblyLoadContext) is not.

Modes and authoring

Section titled “Modes and authoring”
  • Event pipeline - The react mode: one fluent chain - server.Hooks.On<TEvent>().Where(...).Select(...).<terminal>(...) - whose Where/Select lower to server-side kernel IR, so only matching, projected data is pushed to the plugin. Some API surfaces and older pages call this mode Query (RunLocal).
  • Pushdown - Collapsing many small remote calls into one validated server-side batch that loops the host’s existing bindings next to its data.
  • Server extension - A plugin’s [ServerExtension] batch aggregate, lowered to a sandboxed kernel and installed into a frozen host without recompiling it.
  • Hook / Subscription - The two event registries a plugin attaches reactions to: server.Hooks are awaited decision points whose logic can influence the outcome; server.Subscriptions are fire-and-forget notifications.
  • Event-pipeline terminals (RunLocal / Run / RegisterLocal / Register / Use) - The last call in an event pipeline, chosen on two axes: where your handler runs - in your plugin as native C# (RunLocal, RegisterLocal) or server-side as sandboxed IR (Run, Register) - and whether it returns a decision - Register / RegisterLocal hand an IHookResult back to the server, while Run / RunLocal are fire-and-forget. Use<TKernel> installs a separately-authored kernel. Result terminals (Register / RegisterLocal) exist only on server.Hooks (awaited decisions), never on fire-and-forget server.Subscriptions.

Services, RPC, and transport

Section titled “Services, RPC, and transport”
  • RPC - Remote procedure call: a discrete, typed request→response to a host capability behind a shared C# [RpcService] contract.
  • Peer - An RpcPeer/RpcHost endpoint; the runtime is peer-based and bidirectional, so one connection can both serve and call services.
  • Proxy / dispatcher - The generated client-side stub (proxy) that marshals a call over the wire and the server-side dispatcher that routes it to your implementation.
  • IPC (inter-process communication) - Two OS processes (host and plugin/client) talking over a transport such as a named pipe or TCP.
  • DTO (data transfer object) - A plain data type that crosses the wire; MessagePack DTOs are annotated with [MessagePackObject] and a stable [Key] per member - see Services.