Skip to main content

Bundle Entry: docs/spec/HOST_RUNTIME_BUNDLE_v0.1.md Legacy Split Doc: Prefer the bundle entrypoint for agent retrieval; this file retains detailed, topic-local semantics.

caps.toml (Capability Policy) v0.2

This file defines the deny-by-default capability policy used by genesis run and by effectful obligations.

Top-Level Keys

  • allow (required): array of strings. Each string is a fully-qualified op symbol, e.g. "sys/time::now".
  • log (optional): table controlling effect log behavior (see below).
  • store (optional): table controlling the artifact store used by core/store::* capabilities (see below).
  • refs (optional): table controlling the local refs database used by core/refs::* capabilities (see below).
  • task (optional): table controlling task scheduler defaults and limits for core/task::* (see below).
  • runtime (optional): deterministic runtime budgets for effect programs (see below).

Example:

allow = ["sys/time::now", "io/fs::read"]

Store Policy ([store])

Supported keys: - dir (string): directory used for content-addressed artifacts for core/store::*. - If omitted, defaults to <caps.toml directory>/.genesis/store. - max_run_bytes (int, optional): cumulative byte budget for store writes during a single genesis run. - Applies to core/store::put, remote cache writes from core/store::get, sync/gpk ingest, and log artifact externalization. - Exceeding this budget returns sealed ERROR core/caps/resource-limit. - remote (string, optional): remote registry base used as a read-through source for core/store::{has,get}. - If set, the runner may query/download artifacts from the remote when they are missing locally. - Remote normalization and allowlisting are enforced (see below). - remote_allow (array of strings, optional): allowlist of normalized remote base URL prefixes permitted for store.remote. - If store.remote is set, store.remote_allow must be non-empty or the remote is denied. - allow_http (bool, optional): if true, http:// remotes are permitted (default false). - auth_token (string, optional): bearer token for remote registry auth. - auth_token_env (string, optional): env var name containing bearer token (mutually exclusive with auth_token). - basic_username (string, optional): username for HTTP Basic authentication (mutually exclusive with bearer authentication). - basic_password (string, optional): inline Basic password (mutually exclusive with basic_password_env; requires basic_username). - basic_password_env (string, optional): env var name containing the Basic password (mutually exclusive with basic_password; requires basic_username). - mtls_ca_pem (string, optional): PEM file path for additional trusted CA roots. - mtls_identity_pem (string, optional): PEM file path containing client cert+key for mTLS.

Example:

[store]
dir = "./.genesis/store"
max_run_bytes = 16777216
remote = "gen://registry.example.com/registry"
remote_allow = ["https://registry.example.com/registry/v1/"]
auth_token_env = "GENESIS_REGISTRY_TOKEN"
mtls_ca_pem = "./certs/registry-ca.pem"
mtls_identity_pem = "./certs/client-identity.pem"

Remote normalization and matching: - gen://host/path is normalized to https://host/path. - Remotes are normalized to a .../v1/ base (e.g. https://example.com/registry/v1/). - remote_allow is matched by prefix against the normalized base.

Artifact-only production loads transport store.remote, store.remote_allow, store.allow_http, all global credential-source observations, and both mTLS path observations through core/effects::resource-policy-authority. GenesisCode trims and classifies the remote target and allowlist, preserves list order and duplicates, removes empty list entries, and emits a closed HTTP permission state. It also decides credential type/conflict/dependency errors, bearer and Basic source modes, Basic username, and mTLS path admission. Inline secrets are represented only by presence markers and never enter an authority term or its hash. Store and package-registry consumers have no raw fallback for these global fields. URL parsing/normalization and matching, environment/secret lookup, relative-path resolution, PEM loading, TLS construction, and HTTP transport remain bounded host mechanisms.

Refs Policy ([refs])

Supported keys: - path (string): local refs database file used by core/refs::*. - If omitted, defaults to <caps.toml directory>/.genesis/refs.gc.

Example:

[refs]
path = "./.genesis/refs.gc"

Task Policy ([task])

Supported keys: - default_workers (int >= 1, optional): default worker budget used when task.max_workers is unset. - default when omitted: host parallelism (available_parallelism) with minimum 1. - max_workers (int >= 0, optional): hard worker ceiling. - max_tasks (int >= 0, optional): maximum concurrently tracked tasks. - max_queue (int >= 0, optional): maximum queued (not yet running) tasks. - max_steps_per_task (int >= 0, optional): logical-step ceiling per task. - max_time_ms_per_task (int >= 0, optional): logical elapsed-step budget per task.

Task workers are owned by one effect run. Every run exit cancels unfinished jobs, closes worker admission, and joins all workers in creation order before returning. A failed join or post-join liveness check takes precedence over the run outcome as typed EffectsError::Cleanup with subsystem task-worker; simultaneous task and host-bridge cleanup failures are retained in deterministic owner order. Cancellation is cooperative within a task worker, not hard thread preemption.

Example:

[task]
default_workers = 8
max_workers = 16
max_tasks = 128
max_queue = 256
max_steps_per_task = 100000
max_time_ms_per_task = 10000

Runtime Policy ([runtime])

Supported keys: - max_effect_ops (int >= 0, optional): maximum number of effect requests processed in a single run. - Exceeding the limit returns sealed ERROR core/caps/resource-limit. - max_payload_bytes_per_op (int >= 0, optional): maximum canonical payload size (bytes) for a single effect request. - max_payload_bytes_per_run (int >= 0, optional): cumulative canonical payload-byte budget for the full run. - max_response_bytes_per_op (int >= 0, optional): maximum canonical response size (bytes) for a single effect response. - max_response_bytes_per_run (int >= 0, optional): cumulative canonical response-byte budget for the full run.

Behavior: - Payload/response sizes are computed from canonical CoreForm serialization, not host RSS/process memory. - Limits are fail-closed and deterministic: the runner returns a sealed core/caps/resource-limit error and records a denied decision for that entry. - Runtime limit errors include :runtime/budget, :runtime/unit, :runtime/observed, and :runtime/limit in :error/context.

Example:

[runtime]
max_effect_ops = 20000
max_payload_bytes_per_op = 65536
max_payload_bytes_per_run = 8388608
max_response_bytes_per_op = 1048576
max_response_bytes_per_run = 16777216

Log Policy ([log])

Supported keys: - inline_max_bytes (int): maximum number of bytes to inline inside .gclog :resp entries. - If a response exceeds this limit, the runner stores the response as a content-addressed artifact and records an artifact reference in the log. - store_dir (string): directory used for content-addressed artifacts referenced by logs. - If omitted and inline_max_bytes is set, store_dir defaults to <caps.toml directory>/.genesis/store. - max_artifact_bytes_per_run (int, optional): cumulative byte budget for log response artifacts externalized to store in a single run. - Exceeding this budget returns sealed ERROR core/caps/resource-limit.

Example:

[log]
inline_max_bytes = 1048576
store_dir = "./.genesis/store"
max_artifact_bytes_per_run = 8388608

Per-Op Configuration

Some ops may accept a per-op policy object. This is represented as a TOML table keyed by op symbol.

Supported keys: - base_dir (string): base directory sandbox for io/fs::* ops. Paths must remain under this directory after canonicalization. - create_dirs (bool): if true, io/fs::write and io/fs::rename may create parent directories. - timeout_ms (int): optional runner-side hard timeout (milliseconds). Supported for non-mutating bridge operations under both bridge transports; timeout terminates and reaps the isolated bridge process tree before returning. - log_inline_max_bytes (int): optional per-op override for log inlining. - bridge_cmd (string): optional host-bridge executable path under base_dir. - used by host-integrated ops such as host/plugin::command, editor/plugin::command, gfx/window::*, gfx/input::*, gfx/audio::*, gfx/gpu::*, gpu/compute::*, io/net::*, io/db::*, and sys/process::*. - first-party runtime domains (canonical gpu/compute::*, gfx/gpu::*, gfx/window::*, gfx/input::*, gfx/audio::*, editor/clipboard::*, editor/dialog::*, editor/watch::*, editor/task::*) do not require bridge_cmd; bridge remains an explicit override. - bridge_args (array): optional fixed args passed to bridge_cmd before the op symbol. - bridge_transport (string): optional transport mode for bridge-backed ops. - supported values: - spawn-per-op (default): spawn a new bridge process for each op request. - persistent-stdio: keep a per-op bridge process/session alive and exchange framed request/response payloads over persistent stdio. - persistent-stdio requires the bridge executable to support repeated framed request processing in a single process lifetime. - timeout_ms terminates and evicts a timed-out persistent-stdio session; the uncertain request is never retried. - artifact-backed production loads use GenesisCode authority protocol v0.19 to select the command, compatibility-filter fixed arguments, select or reject the transport, and activate an explicitly configured WASI profile before host execution. - first_party_profile (string): optional profile selector for first-party host backends. - currently used by gfx/window::*, gfx/input::*, gfx/audio::*. - supported values: - headless (default): deterministic no-event CI/runtime profile. - interactive: host-integrated terminal adapter profile (terminal-host) for local window/input/audio interactivity. - desktop: non-terminal desktop adapter profile (desktop-host) for local window/input/audio workflows. - browser: deterministic browser-host profile (browser-host) for wasm/browser-aligned window/input/audio behavior. - gfx_first_party_profile is the compatibility alias; a present first_party_profile always takes precedence, including when its type is invalid. - absent or non-string profile selection uses the compile-target production default only when runtime_profile (or compatibility alias host_runtime_profile) is production, prod, or release; otherwise it selects headless. A present runtime primary likewise blocks its alias. - explicit production and prod select the compile-target production default; unsupported explicit strings select headless. - artifact-backed production loads use GenesisCode authority protocol v0.19; GFX dispatch consumes only the validated installed profile and never rereads the raw policy fields. - xr_backend (string): optional backend selector for gfx/xr::*. - first-party, first-party-runtime, headless-sim, and xr-headless-sim select the deterministic first-party runtime. - webxr-device, device-runtime, and browser-device select the WebXR device lane, whose host enforcement requires an explicit bridge profile. - production, prod, and release, or an absent/non-string backend under a selected production runtime profile, select WebXR only when GenesisCode’s bridge-active decision is true; otherwise they fail closed as gfx/xr-policy-disabled. - unsupported strings are canonicalized and rejected; a present non-string runtime_profile blocks host_runtime_profile. - artifact-backed production loads use GenesisCode authority protocol v0.19; XR dispatch consumes only the installed closed backend state. - allow_haptics_inputs (array): required input-ID allowlist for gfx/xr::haptics-pulse. - max_haptics_amplitude (int): optional positive amplitude limit in the range 1..1000 (default 1000). - max_haptics_duration_ms (int): optional positive pulse-duration limit (default 250). - allow_hand_tracking, allow_hit_test, allow_spatial_mesh (bool): optional advanced-feature gates, each defaulting to true. - max_hand_joints, max_hit_results, max_meshes, max_mesh_vertices, max_anchors, max_layers, max_layer_opacity (int): optional positive XR bounds with defaults 25, 8, 4, 4096, 64, 16, and 1000 respectively. - allow_anchor_spaces, allow_layer_types (array): optional case-insensitive allowlists, defaulting respectively to ["local", "local-floor", "bounded-floor", "viewer"] and ["quad", "cylinder", "equirect"]. - Artifact-backed production loads transport all 15 XR device fields with the backend/runtime observations through GenesisCode authority protocol v0.19. GenesisCode owns trimming, empty removal, anchor/layer ASCII lowercasing, malformed-state classification, and positive-limit classification while preserving per-operation lazy error timing. First-party XR dispatch never rereads these raw fields; Rust retains matching, bounds enforcement, deterministic runtime state, bridge/adapter execution, replay, and resource lifecycle. - gpu_backend (string): optional backend selector for first-party GPU runtime domains (gpu/compute::*, gfx/gpu::*). - supported values: - first-party-runtime (default): deterministic in-memory runtime backend. - device-runtime: in-repo device-backed backend for submit/introspection ops (submit, limits, features). - device-runtime-full: in-repo device-backed backend request for canonical lifecycle ops (create*, write*, read*, destroy-resource, submit, limits, features). - legacy aliases are not supported; use canonical values only. - applies only when no explicit bridge profile is configured for the op. - artifact-backed production loads use GenesisCode authority protocol v0.19 to normalize and select the backend; GPU dispatch does not reread this field. - gpu_backend_policy (string): optional fail behavior for gpu_backend = "device-runtime" or "device-runtime-full". - supported values: - allow-fallback (default): on device backend unavailability/error, fail open to first-party-runtime and annotate response with fallback metadata. - require-device: fail closed with sealed error when device backend is unavailable/errors. - strict runtime profiles may override the implicit default using GENESIS_GPU_BACKEND_POLICY_DEFAULT=require-device; explicit per-op gpu_backend_policy entries still take precedence. - automation profile contract: - GENESIS_AGENT_GPU_PROFILE=agent-gpu-strict requires GENESIS_GPU_BACKEND_POLICY_DEFAULT=require-device. - GENESIS_AGENT_GPU_PROFILE=agent-gpu-fallback requires explicit fallback (allow-fallback/dev-allow-fallback). - enforced by scripts/check_agent_gpu_profile_contract.sh. - artifact-backed production loads transport the explicit setting and exact host-observed default through GenesisCode authority protocol v0.19. GenesisCode owns explicit-over-default precedence and the closed fallback decision; GPU dispatch does not reread TOML or the environment. - bridge_cmd_allowlist (array): optional explicit identity allowlist for bridge binaries. - entries may match configured bridge_cmd, resolved absolute path, or executable filename. - GenesisCode authority protocol v0.19 trims entries while preserving order and duplicates, treats [] as a valid deny-all list, and rejects non-string or empty entries before host matching. - bridge_cmd_sha256 (string): executable digest pin (64 hex; optional sha256: prefix). - required for host/plugin::command and editor/plugin::command when bridge_cmd transport is configured. - required for host/ffi::call, host/ffi::buffer-pin, and host/ffi::buffer-unpin when bridge_cmd transport is configured. - mismatches are denied with deterministic sealed error <family>/bridge-identity-denied. - artifact-backed production loads use GenesisCode authority protocol v0.19 to decide whether the pin is required and to trim, validate, and lowercase the configured digest before any plugin or FFI bridge preflight or execution. Rust retains command resolution, executable hashing, digest comparison, transport, cancellation, and provider lifecycle, and has no raw digest fallback in those consumers. - wasi_bridge_profile (bool): when true, enables deterministic WASI bridge response mode for this op (also always enabled on actual WASI targets). - wasi_bridge_response (string): optional CoreForm term used as deterministic host response for bridge-backed ops under WASI bridge profile. - wasi_bridge_response_file (string): optional path (under base_dir) to a CoreForm term or op->response map used under WASI bridge profile. - GenesisCode decides whether any explicit bridge profile is active from the nonempty bridge_cmd, wasi_bridge_response, or wasi_bridge_response_file strings or literal wasi_bridge_profile = true. Process, database, network, crypto, editor, browser, GPU, GFX, and XR routing consume that installed decision without rereading these raw fields. Rust retains response parsing/file resolution and bridge execution. - max_bytes (int): optional per-op byte budget for payload-heavy operations. - core/store::put: maximum artifact byte size accepted for each put request. - core/store::get and io/fs::read: maximum bytes allowed in the fetched/read payload. - bridge-backed ops (editor/*, gfx/*, gpu/compute::*): maximum bytes for both framed request payload and framed response payload. - remote_allow (array of strings): allowlist of remote base URL prefixes for core/sync::* and core/pkg-low::publish (see below). - url_allow (array of strings): URL prefix allowlist for network target ops (io/net::http-request, io/net::ws-open, io/net::tcp-open, io/net::tcp-listen, io/net::udp-bind, io/net::udp-send, io/net::dns-resolve, io/net::http-listen). - allow_http (bool): if true, http:// URLs are permitted for core/sync::*, core/pkg-low::publish, and io/net::http-* (default is false). - wasi_network_profile (string): optional WASI network scope (none|local|preview2) for remote/network ops such as core/sync::*, core/pkg-low::publish, and io/net::*. - allow_bind_hosts (array): required bind-host allowlist for inbound network listeners (io/net::tcp-listen, io/net::http-listen). - allow_bind_ports (array): required bind-port allowlist for inbound network listeners (io/net::tcp-listen, io/net::http-listen). - max_request_bytes (int): required positive request-size bound for inbound accept/listen flows (io/net::tcp-accept, io/net::http-listen, io/net::ws-accept).

For artifact-only production policy loads, GenesisCode authority protocol v0.19 normalizes url_allow, remote_allow, allow_http, wasi_network_profile, allow_bind_hosts, allow_bind_ports, and max_request_bytes into closed typed states before any network, sync, publication, or store-remote consumer runs. Host code retains URL/authority parsing, matching, WASI backend availability, transport, cancellation, and byte enforcement; raw TOML interpretation remains reachable only through the explicit compatibility/oracle path during R4.2.d. - db_target_allow (array): allowlist of durable-data targets (DSN/path prefixes) for io/db::connect and io/db::kv-open. - allow_query_classes (array): required query/statement class allowlist for SQL-like durable-data ops (io/db::query, io/db::exec). - max_row_count (int): required positive row-count bound for io/db::query. - max_result_bytes (int): required positive result envelope byte bound for io/db::query, io/db::exec, and io/db::kv-get. - max_value_bytes (int): required positive value-size bound for io/db::kv-put. - File-backed production policy loads transport all five database fields through core/effects::policy-authority; GenesisCode normalizes their closed state, and host dispatch enforces only the validated installed result. - allow_algorithms (array): required algorithm allowlist for core/crypto::{hash,sign,verify,kdf,aead-seal,aead-open}. Entries are trimmed and ASCII-lowercased by the GenesisCode policy authority before matching. - allow_key_ids (array): required signing, verification, KDF, or AEAD key-ID allowlist. Entries are trimmed and remain case-sensitive. - max_input_bytes, max_message_bytes, max_context_bytes, max_signature_bytes, max_info_bytes, max_output_bytes, max_salt_bytes, max_plaintext_bytes, max_aad_bytes, max_nonce_bytes, max_ciphertext_bytes, and max_tag_bytes (int): required positive, platform-sized limits consumed by their corresponding crypto operation inputs or outputs. - File-backed production policy loads transport all fourteen crypto fields through core/effects::policy-authority; GenesisCode normalizes their closed states, and host dispatch enforces only the validated installed result. Matching, key custody, cryptographic execution, measurement, and output enforcement remain host mechanisms. - allow_programs (array): required allowlist for process launch ops (sys/process::exec, sys/process::spawn) program names. - allow_plugins (array): required allowlist for host/plugin::command and editor/plugin::command plugin identifiers. - allow_commands (array): required command allowlist for host/plugin::command and editor/plugin::command. - allow_schema_ids (array): required when typed plugin schemas are used (:request-schema-id / :response-schema-id); every schema id must be allowlisted. - File-backed production policy loads transport plugin, command, and schema-ID lists through core/effects::policy-authority; GenesisCode normalizes their closed states, and plugin dispatch enforces only the validated installed result. Matching, bridge identity, schema validation, and execution remain host mechanisms. - allow_abi_ids (array): required ABI allowlist for host/ffi::call, host/ffi::buffer-pin, and host/ffi::buffer-unpin. - allow_libraries (array): required allowlist for host/ffi::call library names. - allow_symbols (array): required allowlist for host/ffi::call symbols. - max_buffer_bytes (int): required positive payload bound for host/ffi::buffer-pin. - signed_policy_required (bool): when true, FFI op requires release signed-policy metadata fields. - policy_artifact_h (string): 64-hex immutable policy artifact hash required when signed_policy_required = true. - policy_signature_h (string): 64-hex signature envelope hash required when signed_policy_required = true. - policy_key_id (string): non-empty signing key identity required when signed_policy_required = true. - evidence_mode (string): must be "deterministic" when signed_policy_required = true. - max_call_payload_bytes (int): required positive payload bound for host/ffi::call when signed_policy_required = true. - File-backed production policy loads transport ABI-ID, library, symbol, and schema-ID lists, buffer and call-payload bounds, exact signed-policy opt-in, and all four optional signed-policy metadata strings through core/effects::policy-authority; GenesisCode rejects malformed opt-in, decides required-field precedence, validates hash form and deterministic evidence mode, and emits one closed signed-policy state. FFI dispatch has no raw metadata fallback and enforces only that validated installed result. Signed-policy artifact provenance and cryptographic signature verification, bridge identity, schema implementation, matching, payload measurement, transport, cancellation, and replay remain host mechanisms. - auth_token (string): optional bearer token for remote auth. - auth_token_env (string): optional env var name for bearer token (mutually exclusive with auth_token). - basic_username (string): optional Basic-auth username (mutually exclusive with bearer auth). - basic_password (string): optional inline Basic password (mutually exclusive with basic_password_env; requires basic_username). - basic_password_env (string): optional env var name for the Basic password (mutually exclusive with basic_password; requires basic_username). - mtls_ca_pem (string): optional PEM path for trusted CA roots. - mtls_identity_pem (string): optional PEM path for client cert+key. - File-backed production policy loads transport all seven field states through core/effects::policy-authority. Inline secret values are represented only as :present; GenesisCode selects the source, resolves conflict/dependency precedence, admits username and TLS paths, and returns a closed decision. Rust injects retained inline bytes only after strict decode. Environment lookup, relative-path joining, PEM reads, and client construction remain bounded host mechanisms, and sync dispatch has no raw credential fallback.

String allowlist wildcard semantics: - For string allowlists, * matches any value. - A trailing * performs prefix matching (for example https://registry.example.com/*). - allow_bind_ports also accepts "*" (string) to allow any bind port.

Note: the effect log (.gclog) does not record base_dir values.

Example:

allow = ["io/fs::read", "io/fs::write"]

[op."io/fs::read"]
base_dir = "./sandbox"
timeout_ms = 250

[op."io/fs::write"]
base_dir = "./sandbox"
create_dirs = true

[op."host/plugin::command"]
base_dir = "./workspace"
bridge_cmd = "./tools/editor_bridge.sh"
bridge_cmd_sha256 = "sha256:4f85c19e5f0f7e3fef58e31e0f4bb3ad73df0b1b2e27fe8f79c2fbe4f6f4cfd2"
bridge_args = ["--mode", "stdio-coreform"]
allow_plugins = ["demo-plugin"]
allow_commands = ["run", "health"]
allow_schema_ids = [
  "genesis/plugin.request.exec.v1",
  "genesis/plugin.response.result.v1",
]

[op."host/ffi::call"]
base_dir = "./workspace"
bridge_cmd = "./tools/native_ffi_bridge.sh"
bridge_cmd_sha256 = "sha256:4f85c19e5f0f7e3fef58e31e0f4bb3ad73df0b1b2e27fe8f79c2fbe4f6f4cfd2"
signed_policy_required = true
policy_artifact_h = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
policy_signature_h = "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
policy_key_id = "ops-root-ed25519"
evidence_mode = "deterministic"
allow_abi_ids = ["abi.math.v1"]
allow_libraries = ["libmath.so"]
allow_symbols = ["sum_f64"]
max_call_payload_bytes = 131072
allow_schema_ids = [
  "genesis/ffi.request.call.v1",
  "genesis/ffi.response.call.v1",
]

[op."host/ffi::buffer-pin"]
base_dir = "./workspace"
bridge_cmd = "./tools/native_ffi_bridge.sh"
bridge_cmd_sha256 = "sha256:4f85c19e5f0f7e3fef58e31e0f4bb3ad73df0b1b2e27fe8f79c2fbe4f6f4cfd2"
allow_abi_ids = ["abi.math.v1"]
allow_schema_ids = [
  "genesis/ffi.request.buffer-pin.v1",
  "genesis/ffi.response.buffer-handle.v1",
]
max_buffer_bytes = 1048576

[op."host/ffi::buffer-unpin"]
base_dir = "./workspace"
bridge_cmd = "./tools/native_ffi_bridge.sh"
bridge_cmd_sha256 = "sha256:4f85c19e5f0f7e3fef58e31e0f4bb3ad73df0b1b2e27fe8f79c2fbe4f6f4cfd2"
allow_abi_ids = ["abi.math.v1"]
allow_schema_ids = [
  "genesis/ffi.request.buffer-unpin.v1",
  "genesis/ffi.response.status.v1",
]

[op."gfx/gpu::create-buffer"]
base_dir = "./workspace"
bridge_cmd = "./tools/host_bridge.sh"

[op."gfx/window::create-surface"]
base_dir = "./workspace"
bridge_cmd = "./tools/host_bridge.sh"

[op."io/net::http-request"]
url_allow = ["https://registry.example.com/api/"]
wasi_network_profile = "preview2"
bridge_cmd = "./tools/host_bridge.sh"

[op."io/net::ws-open"]
url_allow = ["wss://realtime.example.com/ws/"]
wasi_network_profile = "preview2"
bridge_cmd = "./tools/host_bridge.sh"

[op."io/net::ws-send"]
bridge_cmd = "./tools/host_bridge.sh"

[op."io/net::ws-recv"]
bridge_cmd = "./tools/host_bridge.sh"

[op."io/net::ws-close"]
bridge_cmd = "./tools/host_bridge.sh"

[op."io/net::tcp-listen"]
url_allow = ["tcp://127.0.0.1:9000"]
allow_bind_hosts = ["127.0.0.1"]
allow_bind_ports = [9000]
wasi_network_profile = "preview2"
max_request_bytes = 4096
bridge_cmd = "./tools/host_bridge.sh"

[op."io/net::tcp-accept"]
max_request_bytes = 4096
bridge_cmd = "./tools/host_bridge.sh"

[op."io/net::http-listen"]
url_allow = ["http://127.0.0.1:8080"]
allow_http = true
allow_bind_hosts = ["127.0.0.1"]
allow_bind_ports = [8080]
wasi_network_profile = "preview2"
max_request_bytes = 8192
bridge_cmd = "./tools/host_bridge.sh"

[op."io/net::http-respond"]
bridge_cmd = "./tools/host_bridge.sh"

[op."io/net::ws-accept"]
max_request_bytes = 4096
bridge_cmd = "./tools/host_bridge.sh"

[op."io/db::connect"]
db_target_allow = ["sqlite://data/app.db"]
bridge_cmd = "./tools/host_bridge.sh"

[op."io/db::tx-begin"]
bridge_cmd = "./tools/host_bridge.sh"

[op."io/db::query"]
allow_query_classes = ["read-only", "analytics"]
max_row_count = 500
max_result_bytes = 8192
bridge_cmd = "./tools/host_bridge.sh"

[op."io/db::exec"]
allow_query_classes = ["write", "ddl"]
max_result_bytes = 4096
bridge_cmd = "./tools/host_bridge.sh"

[op."io/db::tx-commit"]
bridge_cmd = "./tools/host_bridge.sh"

[op."io/db::tx-rollback"]
bridge_cmd = "./tools/host_bridge.sh"

[op."io/db::kv-open"]
db_target_allow = ["kv://state/main"]
bridge_cmd = "./tools/host_bridge.sh"

[op."io/db::kv-get"]
max_result_bytes = 4096
bridge_cmd = "./tools/host_bridge.sh"

[op."io/db::kv-put"]
max_value_bytes = 4096
bridge_cmd = "./tools/host_bridge.sh"

[op."io/db::kv-delete"]
bridge_cmd = "./tools/host_bridge.sh"

[op."sys/process::exec"]
allow_programs = ["gcpm"]
bridge_cmd = "./tools/host_bridge.sh"

Sync/Publish Remotes (core/sync::*, core/pkg-low::publish)

core/sync::pull, core/sync::push, and core/pkg-low::publish are secure-by-default: - They require a per-op remote_allow allowlist (deny otherwise). - http:// is rejected unless allow_http = true.

Remote normalization: - gen://host/path is normalized to https://host/path. - Remotes are normalized to a .../v1/ base (e.g. https://example.com/registry/v1/). - Matching is prefix-based against the normalized base.

Example:

allow = ["core/sync::pull", "core/sync::push", "core/pkg-low::publish"]

[op."core/sync::pull"]
remote_allow = ["https://registry.example.com/v1/"]
auth_token_env = "GENESIS_REGISTRY_TOKEN"
mtls_ca_pem = "./certs/registry-ca.pem"
mtls_identity_pem = "./certs/client-identity.pem"

[op."core/sync::push"]
remote_allow = ["https://registry.example.com/v1/"]
auth_token_env = "GENESIS_REGISTRY_TOKEN"
mtls_ca_pem = "./certs/registry-ca.pem"
mtls_identity_pem = "./certs/client-identity.pem"

[op."core/pkg-low::publish"]
remote_allow = ["https://registry.example.com/v1/"]
auth_token_env = "GENESIS_REGISTRY_TOKEN"

base_dir For Non-io/fs::* Ops

The runner also uses base_dir to sandbox filesystem paths carried in payloads for some non-io/fs::* ops:

  • core/pkg-low::snapshot: payload key :pkg (package.toml path)
  • core/pkg-low::init: payload key :lock (lockfile path)
  • core/pkg-low::add: payload key :lock (lockfile path)
  • core/pkg-low::lock: payload key :lock (lockfile path)
  • core/pkg-low::update: payload key :lock (lockfile path)
  • core/pkg-low::install: payload key :lock (lockfile path)
  • core/pkg-low::verify: payload key :lock (lockfile path)
  • core/pkg-low::list: payload key :lock (lockfile path)
  • core/pkg-low::info: payload key :lock (lockfile path)
  • core/gpk-low::export: payload key :out (output .gpk path)
  • core/gpk-low::import: payload key :in (input .gpk path), and optional :set-refs entries (:name, :hash|nil, :policy, optional :expected-old) applied through the local refs policy gate
  • core/gc-low::*: payload keys :lock, :pins, and (optionally) :quarantine-dir

These payload paths must remain under base_dir after canonicalization, using the same rules as io/fs::*.

For core/gc-low::*, paths may refer to files/directories that do not exist yet (e.g. .genesis/pins.toml or .genesis/quarantine/). The runner validates the longest existing ancestor is within base_dir, rejects .., and then uses the resulting under-base path.

Notes on timeout_ms: - Timeouts are enforced via cancellable worker jobs for in-process capabilities and hard process supervision for bridge spawn-per-op commands. - If the timeout elapses, the runner returns a sealed ERROR response with code core/caps/timeout and records it in the log. - Timeouts are rejected for mutating ops such as io/fs::write, io/fs::mkdir, io/fs::remove, io/fs::rename, sys/process::exec, sys/process::spawn, sys/process::kill, and sys/process::stdin-write (policy error), to avoid “timed out but side-effect happened” ambiguity. - Bridge-backed ops honor timeout_ms under both transports; timeout yields deterministic <family>/bridge-timeout only after process-tree termination, child reap, and I/O worker quiescence. - A timed-out persistent-stdio session is evicted and recreated only for a later request; the timed-out request is never automatically replayed.

Bridge protocol: - Bridge-backed ops use framed stdin/stdout payloads as defined in docs/spec/HOST_BRIDGE_PROTOCOL.md. - Under WASI bridge profile, command spawning is replaced by deterministic configured responses: - per-op wasi_bridge_response / wasi_bridge_response_file, or - process-level GENESIS_WASI_BRIDGE_RESPONSES (CoreForm map op -> response).

Normative Behavior

  • Ops not in allow are denied.
  • Denied ops must be recorded in the effect log with decision :deny.
  • Allowed ops must be recorded with decision :allow and include a stable :cap term capturing the policy fields used.

Path Resolution

When loaded from disk, relative base_dir paths are resolved relative to the directory containing the caps.toml file.