Deployment Bindings

IMPLEMENTED in 0.4.0. Contract context-deployment-binding.v1.

A Context Build is the immutable, portable description of context behavior. A Deployment Binding is what one environment needs to run it: live provider endpoints, secret references, retention, timeouts and the provider health policy. Changing a binding creates a new binding revision; it never changes a Build.

Context Build (immutable)              Deployment Binding (per environment, revisioned)
  policies, profiles, tests              provider endpoints + secret references
  pinned materials                       provider retention, bounds, timeouts
  provider REQUIREMENTS          +       runtime timeout classes, drain
                                         onProviderUnavailable: fail | degrade
                         ↓
               Deployment = exact Build + exact binding revision

Shape

{
  "description": "Production CRM",
  "providers": {
    "customer-data": {
      "type": "http",
      "endpoint": "https://crm.internal.example/context/lookup",
      "secretRef": "env:CONTEXT_PROVIDER_CRM_TOKEN",
      "timeoutMs": 2000, "maxItems": 20, "maxBytes": 262144,
      "retention": "metadata"
    }
  },
  "runtime": { "resolveTimeoutMs": 8000, "healthTimeoutMs": 2000, "startupTimeoutMs": 15000, "reportTimeoutMs": 5000, "collectionTimeoutMs": 10000, "drainMs": 10000 },
  "health": { "onProviderUnavailable": "fail" }
}

SQLite providers use "type": "sqlite" with database (absolute path on the runtime host, opened read-only), table, keyColumn, contentColumn and optional idColumn, titleColumn, updatedColumn (plain identifiers only). The database may never resolve into the Registry's data directory and, when the Registry config sets providerDatabaseRoots, must resolve inside one of them (DATABASE_PATH_REFUSED).

Refused at save time: plaintext secrets or credential patterns anywhere in the body; secret references outside the Registry's allowlist (default env:CONTEXT_PROVIDER_*, keychain:context-provider-*; configure providerSecretRefs); references used as Registry member credentials; non-HTTPS endpoints except loopback; endpoints with userinfo, query or fragment; unknown fields; a resolveTimeoutMs that does not exceed the slowest provider timeout by 1 s.

API

Call	Capability
`GET /v1/bindings?project=P` — current revision per environment	`binding.view`
`GET /v1/bindings/P/E`, `GET /v1/bindings/P/E/revisions`	`binding.view`
`POST /v1/bindings {project, environment, binding, expectedRevision}` — compare-and-swap; identical content returns `unchanged`	`binding.manage` (Admin)
`POST /v1/bindings/validate {project, environment, build}` — compatibility + secret resolvability, no values returned	`binding.view`

The per-binding trace key (used for keyed fingerprints) is generated once, persists across revisions and is never returned by the API.

Deploy-time checks (fail closed)

Before any process starts: required providers bound (PROVIDER_BINDING_MISSING), same contract (PROVIDER_CONTRACT_INCOMPATIBLE), declared capability (PROVIDER_CAPABILITY_MISSING), secrets resolvable by the Registry (SECRET_UNAVAILABLE). bindingRevision in the deploy request pins the exact revision (STALE_REF if it moved). After start, the runtime probes each provider (describe); required providers that are not ready block activation (PROVIDER_NOT_READY) unless the binding explicitly allows degrade, in which case the deployment is DEGRADED, never HEALTHY.

Secret injection

The Registry resolves only the references the binding names and passes them to the runtime as CONTEXT_PROVIDER_SECRET_<n>; the runtime binding file names the variable, never the value. The runtime process environment is exactly PATH, NODE_OPTIONS, SEIF_CONTEXT_RUNTIME_TOKEN, the bound provider secrets (and Node's own UV_USE_IO_URING on Linux). Proven by a wrapper executable on macOS and /proc/<pid>/environ on Linux: an unrelated Registry secret and the Registry's own credential are absent.

Standalone runtimes

Exported bundles and context-runtime accept the same shape with --binding binding.json (references resolved by the runtime's own environment). A Build with required providers refuses to start without one (BINDING_REQUIRED). Add "traceKey": "<64 hex>" to a standalone binding to get binding-keyed fingerprints in its traces; Registry-managed deployments always receive the binding's key.

Versioned tools

Context and tool delivery documents tool declarations and profile rules, v2 tool Builds, executor bindings, synthetic tests, operator approval, SDK integration and effect-free replay. Tool-free Builds preserve the v1 contract.