Storage and Distributed Runtime

Storage and Distributed Runtime

Two storage profiles

Profile	Authoritative state	Intended use
SQLite	Local transaction database plus inspectable JSON artifacts	One machine and local agents
PostgreSQL 16+	PostgreSQL tables; JSON is a content-addressed export	Multiple API and worker processes

SQLite is CCR's default. Connections close after each operation, state changes use immediate transactions, and task leases use monotonic fencing tokens.

Distributed workers

Install the optional dependencies:

python -m pip install "collective-capability-runtime[distributed]"

PostgreSQL workers use FOR UPDATE SKIP LOCKED, database time, lease expiry, and monotonic fencing tokens. Delivery is at least once, not exactly once. Idempotency keys make completion safe to retry. A transactional outbox records committed state changes without requiring an external broker.

ccr server run --auth-config oidc.json --host 127.0.0.1 --port 8787
ccr worker run --role verifier --worker-id worker:verifier-1 --once

Use an environment variable for the database URL rather than placing credentials in a command line or documentation artifact.

API authentication

All /v1 write requests require an OIDC access token under the DPoP authorization scheme, plus a matching RFC 9449 proof. CCR validates issuer, audience, expiry, access-token hash, method, target URI, key thumbprint, proof age, and one-time jti value. Replay identifiers are consumed in the authoritative database.

Worker identities and human approval identities use separate configured subject prefixes. An authorization token or incoming trace context is not treated as a general authority signal.

Reconciliation and telemetry

ccr storage doctor --json
ccr storage migrate --json
ccr storage migrate --apply --json
ccr storage reconcile --json

The inspection commands do not silently repair disagreement. Reconciliation reports missing files, digest mismatches, and path escapes without choosing which side is correct.

Events carry CloudEvents-compatible fields, a locally generated W3C traceparent, and PROV-oriented provenance. OpenTelemetry is opt-in. Prompts, secrets, credentials, cookies, and PII-like fields are excluded from default telemetry.

A practical deployment boundary

Distributed coordination improves availability and throughput; it does not change the evidentiary rules. A queued task is not an accepted result, a completed task is not automatically settled, and at-least-once delivery is not exactly-once execution.

For the local object model, see Core Concepts and Status. For side effects, see Operations and Authority.