Runtime Context Providers

IMPLEMENTED in 0.4.0. Contract context-provider.v1. Implementations: HTTP/JSON and read-only SQLite.

A provider supplies data. It never decides participation: the profile rule, applicability, currentness, the Context Kernel and the budget decide what is selected, projected and rendered.

Declaring a requirement (Context Project)

"providers": [{ "id": "customer-data", "name": "Customer data", "lookup": { "input": "customerId", "pattern": "^CUST-[0-9]{4}$" }, "maxItems": 2 }],
"layers": [{ "id": "customer-profile", "name": "Customer profile", "bindings": [{ "provider": "customer-data" }] }]

Endpoints, secrets and databases are refused in the Project ("belongs in a Deployment Binding"). The Build records the requirement and an unpinned entry (RUNTIME_PROVIDER).

Invocation

For each request the runtime invokes a provider only if a layer bound to it is in the profile (not excluded), in scope for the objective and consumer, its requiresInput keys are present, and the lookup input is present and matches the pattern. Nothing else is fetched. Missing input keeps the layer UNKNOWN (PROVIDER_INPUT_NOT_PROVIDED); an out-of-scope layer is NOT_REQUESTED.

HTTP wire (POST to the bound endpoint, Authorization: Bearer <bound secret> if configured):

→ {"contract":"context-provider.v1","capability":"lookup","provider":"customer-data","key":"customerId","value":"CUST-1042","limit":2}
← {"contract":"context-provider.v1","version":"5.0.1","revision":"crm-r9","currentness":"CURRENT",
   "items":[{"id":"CUST-1042","title":"Current account state","content":"…","metadata":{"plan":"Enterprise"},"updatedAt":"2026-10-08"}]}
→ {"contract":"context-provider.v1","capability":"describe"}      (readiness probe)
← {"contract":"context-provider.v1","version":"5.0.1","capabilities":["describe","lookup"]}

404 means no record (NOT_FOUND → layer EMPTY). The lookup value is the only request-derived input; it is validated ([A-Za-z0-9][A-Za-z0-9._:@-]{0,255} plus the declared pattern) and sent in the body, so request data can never choose a host, path or query.

Bounds and safety

Per-provider timeout (50–10 000 ms), response bytes (≤ 1 MiB), items (≤ 100), 64 KiB per item; HTTPS required except loopback; redirects refused; credential reflection in headers or body refused; secret patterns refused; returned content is rendered as reference data under the data notice and never executed. Failures are explicit statuses: TIMEOUT, UNAVAILABLE, LIMIT_EXCEEDED, INVALID_RESPONSE, SECRET_DETECTED, INCOMPATIBLE, NOT_BOUND, INVALID_REQUEST, NOT_EVALUATED. A failure makes the layer UNAVAILABLE with an unknown (“current facts are unknown”); a required layer blocks the turn. A provider timeout is never reported as RUNTIME_UNAVAILABLE.

Provenance in traces (context.provider.v1)

provider, contract, binding revision and digest, provider type, version and version source (response / describe / binding), keyed request digest, lookup key name (never value), observed time, upstream revision, currentness, item locators (customer-data/item-<16 hex>, never the record id), item fingerprints, material digest, duration, retention and whether content was retained. Selection records mark provider materials with provider; trace search supports provider= and providerStatus=.

Determinism: fixtures

Context Tests may supply "providers": {"customer-data": {"items": [...]}} or {"status": "TIMEOUT"}. They are synthetic test data (never production records) and make tests and regression deterministic. Preview and the Workstation's local runtime reuse them by lookup value (TEST_FIXTURE). Regression reports evaluation.providers FIXTURE/LIVE and determinism; tests whose provider has no fixture are UNKNOWN and warned (PROVIDER_FIXTURE_MISSING).

Reproduction

See Reproduction: exact only with retained, digest-verified provider content; provider failures replay exactly; otherwise LIVE_DEPENDENCY_UNAVAILABLE.