contract topology · 01-topology.md · guide · card

System topology

Contextful runs connectors, stores Parquet files and serves queries under access controls. Operators use this page to choose a binary and deployment. Implementers use the component, dependency and coordination requirements below.

Deployment instructions name the executables, embedded libraries and storage services:

Linux: native processes or Linux containers.
macOS: native processes or Docker containers.
Cloudflare: Workers, Linux Containers, D1 and R2.
AWS: Fargate, Postgres and S3.

compose

Execution, storage, queries, access controls and the contracts these components share.

workspacetestOne Cargo workspace compiles execution, storage and query code. These components share one binary, package scope and release.
read-pathtestStorage and query code manages the context store, catalog, queries, ranking, memory queries and bucket sync. A capability check admits each record before storage.
run-pathtestExecution code manages the journal, scheduler, cursor commits, awakeables and journaled connector steps. Execution code owns no store or ranking.
three-crossingstestExecution, storage and query code share exactly three contracts: the connector interface world, columnar-part-plus-manifest layout and capability-token format. No general internal API connects these components.
Why
A-topology#public-surfaces
crossing-versionitemEach shared contract has a version. Execution, storage and query code run its conformance suite. Adding a contract member requires a security review.
undeclared-crossingtestAn execution crate depends on storage or query crates only through crates implementing the three shared contracts. crate-graph checks each dependency.
Why
A-topology#public-surfaces
run-path-droppabletestA build without the execution engine, scheduler or component host reads data written by a full-profile build. Both builds use the same part-and-manifest layout and connector contract.
cli-binarytestThe runtime ships one command binary, contextful, and one package scope, @contextful/*; release assurance follows suite. The smallest deployable build is a profile, not a crate.
mediationtestEach function returning or releasing stored rows requires an access-control admission value (row-token). A call omitting that value fails to compile. Access controls have no disable option.
Why
A-topology#enforcement-stack
enforcement-spantestExecution enforces capability allowlists and records journal entries. Storage and queries enforce statement guards, visibility semi-joins, row and column restrictions, masking and the audit chain.
semantic-layertestAccess controls do not interpret content. Retrieval, memory synthesis, the operator console and inference placement interpret content and access enforcement through the three shared contracts alone.
one-treetestLocal and clustered deployments use one source tree. Single-node and edge deployments use no external queue, cache or coordination process. Multi-node deployments add one shared database.
queue-extensiontestWith a queue role, the target carries receive batches, object-arrival keys and post-commit wake-ups through the Queue port. Without that role, the target uses the local spool. Only the engine writes the store.
Why
A-topology#queue-ingress
queue-sqstestWith CONTEXTFUL_QUEUE_URL set, receive batches and object-arrival keys travel through that SQS standard queue, each request signed with Signature Version 4 under role-credentials; post-commit wake-ups stay in the local spool.
Why
because the aws target’s queue role is an SQS standard queue, and its task holds a workload role rather than a key pair
queue-sqs-absenttestA build linking no SQS adapter, given CONTEXTFUL_QUEUE_URL, refuses each queue use as capability-absent and never falls back to the local spool.
Why
because a batch queued where no consumer of the configured queue reads it is a batch lost
queue-sqs-waittestA receive long-polls the SQS queue for up to 20 s on its first call and waits on none after, stopping at the first empty answer.
Why
because a long poll answers an idle queue with one request rather than many, and later calls drain what already waits
queue-sqs-batchtestOne SQS receive call asks for at most 10 messages.
Why
because SQS answers no more per call
queue-sqs-visibilitytestA received SQS message stays hidden for 300 s; a consumer acknowledges it by deleting its receipt handle, and one left undeleted redelivers after that window.
Why
because a batch’s landing and push finish inside it, and a consumer that died must hand its messages to the next
queue-sqs-captestAn SQS message carries at most 1 MiB; a receive body past it spills under receive-queued-spill to the store’s [sync] bucket beneath its prefix’s queue/spill/.
Why
because SQS refuses a larger message, and the store’s bucket is the one object store every shape with a queue role already writes
queue-object-notificationtestAn S3 event notification on the queue delivers one object-arrival key per ObjectCreated record, its key URL-decoded; a message holding none, the test event among them, is deleted and delivers nothing.
Why
because S3 notifies object creation in its own envelope, and a message no read consumes must not redeliver forever
connector-pillartestA connector is an interface world run in a sandboxed component host that mediates every capability. A native connector, the first-party path for stateful sources, satisfies the same schema, record and cursor contract.
open-storetestTable data sits in columnar parts with a JSON manifest and a rebuildable catalog on plain object storage, readable by standard SQL tooling. No proprietary container or opaque blob holds table data.
inference-egresstestModel access leaves the process through one operator-configured endpoint speaking OpenAI-compatible HTTP. The one provider-shaped step serializes a tool’s parameter schema into the provider’s envelope.
Why
A-topology#one-egress
vendor-sdktestA model-vendor SDK or second outbound model path raises VendorSdkLinked in the dependency audit. The error names the crate and dependency.
Why
A-topology#one-egress
local-firsttestPipelines need no network beyond their sources, and bucket sync is opt-in per deployment. The engine makes no control-plane callback, no license check, and sends no telemetry to its authors.
script-runtimetestA JavaScript runtime linked into any profile raises ScriptRuntimeLinked. The authoring surface is a build-time compiler emitting a serialized, content-hashed plan.
Why
A-run#plan-compiled-content
memory-substratetestSynthesized memory uses ordinary store tables for episodes, facts, entities and preferences. The synthesis pipeline runs as an ordinary execution workflow using the same journal, cursor and retry machinery.
two-spinestestThe run record describes writes. The request ledger describes reads. No third interface combines these records.

package

Rust package dependencies and the capabilities each compiled binary includes.

crate-maptestTwenty crates compose the workspace. contextful-cli is the binary and wires every adapter per profile by dependency injection.
crate-map-drifttestAn unmapped crates/ package or crate-map count differing from the ## Shapes tree raises CrateMapDrift. The error names the package or both counts.
Why
because a package added without a map entry otherwise passes every other gate
domain-cratetestcontextful-core holds the pure domain types and the port traits every adapter implements, performs no I/O, and links into every profile.
Why
A-topology#domain-crate
domain-impuritytestAn async runtime, component host, HTTP client or columnar-format implementation in contextful-core raises DomainCrateImpurity. The error names the dependency and enabling feature.
Why
A-topology#domain-crate
dependency-directiontestA dependency edge from contextful-core toward an adapter crate raises TopologyDependencyInversion, naming both crates and the manifest line.
Why
A-topology#domain-crate
profiletestThree profiles compile from the workspace, each a Cargo feature bundle selected at build time: contextful-edge, contextful-full, contextful-control. Each links the dependencies its role names and nothing else.
Why
A-topology#build-profiles
fixed-at-buildtestNo run-time detection widens a running binary into another profile’s feature set. Build, release and automation tooling links into no profile.
Why
A-topology#build-profiles
profile-leaktestA dependency outside a profile’s role raises ProfileRoleLeak, naming the profile and dependency path. Disallowed dependencies include component hosts, execution or evaluation in edge/control; SQL in control; build tooling in any profile.
Why
A-topology#build-profiles
capability-absenttestA subcommand requiring an unlinked capability raises ProfileCapabilityAbsent, naming the subcommand and profile. The command performs no action. A subcommand absent from every profile is a usage error.
Why
A-topology#build-profiles
version-profiletestcontextful --version prints the workspace version and selected build profile. A build selecting no profile prints development as its profile.
edge-profiletestcontextful-edge syncs parts and manifests from a bucket and serves read-only SQL queries. This profile links no scheduler, execution engine, script runtime or component host.
edge-eligibilitytestThe edge profile is the one profile a function-class target hosts. Execution on such a deployment runs on a worker target.
Why
A-topology#aws-fargate
full-profiletestcontextful-full includes the execution engine, in-process scheduler, component host, SQL queries, transforms, full-text and vector sidecars, and tool server.
control-profiletestcontextful-control provides self-hosted team configuration and operator identity. Apply produces canonical TOML. This profile alone links the CRDT library.
Why
A-topology#control-crdt
control-team-statetestThe control profile stores ingest source, model and access-policy configuration in one loro document. Replicas merge concurrent edits. Apply uses this document as the editable configuration.
Why
A-topology#control-crdt
control-identitytestThe control profile identifies an operator by operator-attestation alone, refusing an apply without one, and keeps no account store.
Why
because the console already signs every Admin mutation, and a second account concept is a second identity to provision and revoke
canonical-tomltestApply sorts each table’s keys by byte order and places nested tables after values. The format-preserving editor chooses quoting and spacing, preserving comments. Applying canonicalization to canonical text changes no byte.
Why
because equal configurations then claim identical bytes, and a comment is the operator’s record of why a value holds
apply-hometestcontextful-snapshot is the one home of the snapshot directory local-claim claims into; contextful-engine and contextful-control both call it, and it links no run-path package.
Why
A-topology#control-crdt
component-hosttestBuilds that link a component host run component connectors: the full profile and container or worker deployments built from that profile.
Why
A-topology#build-profiles
host-missingtestDispatching a component connector without a component host raises ComponentHostMissing, naming the connector and profile. No similarly named native source substitutes.
Why
A-topology#build-profiles
crdt-leaktestThe CRDT library in the resolved dependency graph of the edge or full profile raises ProfileDependencyLeak, naming the profile and the path that pulled it. A daemon or replica reads materialized text.
Why
A-topology#build-profiles
store-write-engine-freetestWithout read, contextful-context excludes duckdb, libduckdb-sys, libsqlite3-sys, async runtimes, HTTP and TLS from normal dependencies on every target. A dependency reaching these raises StoreWriteLinksEngine, naming the package and path.
Why
because a host that lands, folds or scans a store serves no read and opens no connection, so an engine, runtime or network stack is code it never calls
transport-optionaltestWithout transport-ureq, contextful-outbound excludes ureq, hyper, reqwest, rustls and curl from normal dependencies. A dependency reaching these raises TransportStackLinked, naming the dependency path.
Why
A-connector#egress-passes-transport
decode-network-freetestcontextful-decode reaching contextful-outbound, ureq, hyper, reqwest, rustls, curl or tokio through a normal dependency raises DecodeLinksNetwork, naming the path that pulled it.
Why
A-connector#untrusted-input-decodes
exchange-optionaltestcontextful-policy links the external-assertion stack, jsonwebtoken and rsa, only under its non-default exchange feature, which only the binary may enable, and only alongside wiring surface. Another crates/ package whose resolved graph reaches either raises ExchangeDependencyLeak, naming the path.
Why
because an embedder admitting credentials with no identity provider then links no RSA code, and rsa carries a timing advisory with no patched release
sqlite-adaptertestcontextful-sqlite alone declares the SQLite binding as a normal dependency and enables no link feature itself; only contextful-cli turns on its bundled feature. Any other normal-dependency declaration or enablement raises SqliteLinkForced, naming the manifest line.
Why
A-store#sqlite-link-rule
s3-sync-optionaltestWithout s3-sync, contextful-sync excludes ureq, hyper, reqwest, rustls and curl from normal dependencies. A dependency reaching these raises SyncStackLinked, naming the dependency path.
Why
because a host syncing through a filesystem bucket, or embedding the sync package without a bucket, links no network stack
store-sqlite-freetestcontextful-context reaching libsqlite3-sys through a normal dependency, with its default features, on any target, raises StoreLinksSqlite, naming the path that pulled it.
Why
A-store#sqlite-link-rule
interchange-wholetestThe edge profile links the columnar interchange crates whole, as the full profile does; no slimmed interchange build exists.
Why
because a slimmed build forks the format code an edge replica reads with from the code the full profile writes with

Each profile selects the capabilities of one contextful executable at compilation. Deployment diagrams show where that executable runs: directly on Linux or macOS, or inside a Linux container.

unsettled: Does the edge profile pull native connectors through an execution core that links no scheduler? owner: topology affects: topology.package

deploy

Deployment configurations, provider services and comparison against the reference deployment.

unsupported-shapetestA target profile claiming a shape its provider does not provide raises TargetShapeUnsupported, naming the shape and the missing primitive.
Why
A-topology#deploy-observation
wall-clock-captestA target capping per-invocation wall clock at 15 min hosts neither a first-time backfill nor a component connector, and its target profile records both exclusions.
paritytestOne declaration produces byte-identical table parts on every control-plane target; contextful-ci deploy parity compares each target’s object-store parts with the reference target’s.
Why
A-topology#deploy-observation
parity-divergencetestA byte difference from the reference output raises ParityDivergence, naming the target, the table and the first differing part.
Why
A-topology#deploy-observation

Provider configurations live under spec/targets/; corpus.targets checks those files. The generated deployment tables and diagrams identify processes, embedded libraries and provider services. Diagram groups distinguish process, container and operating-system boundaries.

Native Linux deployment

The Linux reference map below places the scheduler, its run children, HTTP server and embedded libraries on one host. Each service uses the same project directory, including contextful.toml, applied control snapshots, execution files and corpus files. The directory persists across process restarts; the optional console has its own Node.js process and configured Rust HTTP endpoint.

The examples assume an existing project with an applied snapshot, readable issuer.key, independently configured issuer public-key pins, and the source credentials its declaration names. The scheduler and HTTP server inherit that environment. contextful-local is the example token audience; 4 is the example HTTP concurrency setting. From that project’s directory, two terminals or two service-manager units run:

contextful pipeline serve --issuer-key issuer.key

contextful serve --http 127.0.0.1:8080 --issuer-key issuer.key \
  --audience contextful-local --max-in-flight 4

Linux Docker Engine also runs the image and container commands below, sharing the host’s Linux kernel. Docker Desktop on macOS adds the Linux VM shown in the Docker map.

macOS without Docker

Apple Silicon uses the aarch64-apple-darwin executable; Intel uses x86_64-apple-darwin. From the repository root, a native source installation selects the full profile:

cargo install --locked --path crates/contextful-cli \
  --no-default-features --features contextful-full

The project’s two startup commands above run directly as macOS processes. Wasmtime, Tokio, DuckDB and SQLite stay embedded in those processes. For managed startup, launchd supervises the scheduler and HTTP server. Project state sits on the Mac’s filesystem. This path uses the Darwin binary and a native Rust/C++ build toolchain, with no Linux VM or Docker daemon. The optional Node.js console uses http://127.0.0.1:8080 as its configured store endpoint.

macOS with Docker

Docker Desktop supplies a Linux VM; its Docker Engine runs the same Linux image a Linux server uses. The Rust processes and embedded libraries run inside containers in that VM. The browser and optional native Node.js console reach a published localhost port.

The image build runs from the repository root. Apple Silicon selects ARM64 explicitly:

docker build --platform linux/arm64 --build-arg PLATFORM=linux/arm64 \
  --build-arg RUST_TARGET=aarch64-unknown-linux-musl -t contextful:local .

Intel Macs select AMD64; this also selects an emulated AMD64 build on Apple Silicon:

docker build --platform linux/amd64 --build-arg PLATFORM=linux/amd64 \
  --build-arg RUST_TARGET=x86_64-unknown-linux-musl -t contextful:local .

The Dockerfile’s PLATFORM and RUST_TARGET arguments select matching builder and executable architectures. --platform alone leaves the Dockerfile’s AMD64 defaults in place. Emulation adds translation cost; an ARM64 image matches an Apple Silicon Linux VM.

From the existing project directory, these commands use a shared bind mount at /data. runtime.env supplies the configured public-key pins and source credentials through Docker’s --env-file; the issuer seed stays in issuer.key. The invoking non-root user’s UID and GID keep writes owned by the project owner. Each terminal runs one container:

docker run --rm --init --name contextful-scheduler \
  --user "$(id -u):$(id -g)" --env-file runtime.env \
  --mount "type=bind,src=$PWD,dst=/data" \
  contextful:local pipeline serve --issuer-key /data/issuer.key

docker run --rm --init --name contextful-http \
  --user "$(id -u):$(id -g)" --env-file runtime.env \
  --mount "type=bind,src=$PWD,dst=/data" -p 127.0.0.1:8080:8080 \
  contextful:local serve --http 0.0.0.0:8080 --issuer-key /data/issuer.key \
  --audience contextful-local --max-in-flight 4

The container listens on 0.0.0.0:8080; Docker publishes it at 127.0.0.1:8080 on macOS. /data persists in the host project directory when --rm removes a container. A Docker named volume stores project state when the operator copies configuration and keys into that volume. Both containers mount the same volume. A project uses one writer mode at a time: switching between native and Docker stops its scheduler and run children before reusing the directory.

Declared file and component paths resolve inside the container; files outside /data need an explicit mount. A source or model endpoint running on the Mac uses host.docker.internal from Docker Desktop containers. Container localhost names the container itself; the native console uses the published Mac loopback port.

The Linux VM contains the containers; the project directory remains on macOS through Docker’s file sharing.

unsettled: Which role hosts heavy compute on a provider exposing neither a container primitive nor a long-running function? owner: topology affects: topology.deploy

Deployment targets

AWS

VPC-bound and regulated deployments, and teams already operating on AWS.

The scheduled-fargate target runs every process as the native Linux contextful-full executable in Fargate containers. EventBridge Scheduler starts contextful pipeline serve --cycle as an ECS task on a fixed rate; the cycle takes the cadence lease, runs every due unit and exits. A long-running contextful serve behind an Application Load Balancer answers queries and pulls the bucket every 30 s. The query process embeds DuckDB; component execution embeds Wasmtime. RDS Postgres supplies the shared catalog, the engine journal in it makes every run durable and resumable, and S3 holds corpus objects. The fargate-daemon alternative keeps scheduling in one always-on task for sub-minute cadences.

The OpenTofu configuration under apps/aws-fargate/ provisions either shape: a private VPC with its service endpoints, RDS Postgres, the S3 corpus bucket, the SQS queue with its dead-letter queue and object-arrival notification, the ECS cluster, the cycle task or daemon service, and the serve service behind the load balancer.

Role	`scheduled-fargate` (default)	`fargate-daemon`
cron tick	EventBridge Scheduler	in-process scheduler
reconciler	`pipeline serve --cycle` in the scheduled Fargate task	in-process reconcile loop
durable orchestrator	engine journal in the catalog	engine journal in the catalog
single-writer catalog	RDS Postgres via pg-catalog	RDS Postgres via pg-catalog
object store	S3	S3
hot-path query face	ALB → contextful serve on Fargate	ALB → contextful serve on Fargate
heavy compute	in-process component host of the scheduled task	in-process component host
secrets	Secrets Manager adapter through the task role	Secrets Manager adapter through the task role
realtime run projection	Fargate-hosted run projection	—
queue	SQS standard queue; S3 event notifications to SQS for object arrival	SQS standard queue; S3 event notifications to SQS for object arrival
kind · profiles	orchestrated · full	daemon · full
wall-clock cap · excluded	none · nothing	none · nothing

The scheduled-fargate runtime and process boundaries:

Cloudflare

Cloudflare deployments with a Linux Container, D1 execution metadata and R2 objects.

Cloudflare's default deployment configuration is worker-container-d1. The gateway and the reconciler run as TypeScript in Workers' V8 isolates. Cron Triggers schedule work; Workflows coordinates execution. A Durable Object controls the Linux Container's lifecycle. The Container runs the native contextful-full executable with embedded DuckDB and Wasmtime. Workers and Workflows call the Container through requests.

The Rust processes use CONTEXTFUL_STORAGE_PROFILE=cloudflare-d1. Requests to the private contextful.d1 host call a Worker binding handler. The handler reads and writes execution metadata in D1 and execution blobs in R2. A separate R2 bucket stores corpus parts and manifests through its S3-compatible API. Files inside the Container are a replaceable working copy.

Cloudflare Queues carries receive batches and object-arrival notifications. The Rust engine writes the store. A separate Durable Object manages hibernating WebSocket connections for run updates. Workers Secrets supplies credentials to configured bindings. The optional console server runs on a Node.js host. The React assets provide a static browser preview without that server.

The worker-container-d1-basin configuration adds an optional read face for exported audiences. The Container commits each audience's Iceberg export to Basin Catalog, the Iceberg REST catalog of an R2 bucket that holds that audience alone. The gateway sends a caller whose credential maps to an export namespace to Basin SQL over REST with that audience's read-only token, one Worker secret per audience bucket, and sends every other caller to the Container. Each export table runs with Basin compaction disabled; Basin snapshot expiration removes superseded exports.

The example under apps/cloudflare-execution/ exposes authenticated POST /conformance. Its Container runs contextful-conformance against the packaged Linux contextful binary. This endpoint tests execution storage; it serves no query or orchestration routes. status.md records clause implementation evidence.

Role	`worker-container-d1` (default)	`worker-container-d1-basin`
cron tick	Cron Trigger	Cron Trigger
reconciler	Worker	Worker
durable orchestrator	Workflows	Workflows
single-writer catalog	D1 through a private Worker outbound binding	D1 through a private Worker outbound binding
object store	R2	R2, with one Basin Catalog bucket per exported audience
hot-path query face	gateway → warm contextful-full Container	gateway → warm contextful-full Container, or Basin SQL for an exported audience
heavy compute	Container with cloudflare-d1 storage profile	Container with cloudflare-d1 storage profile, which also runs Iceberg exports
secrets	Workers Secrets	Workers Secrets
realtime run projection	Durable Object with a hibernating WebSocket	Durable Object with a hibernating WebSocket
queue	Cloudflare Queues with a pull consumer; R2 event notifications for object arrival	Cloudflare Queues with a pull consumer; R2 event notifications for object arrival
kind · profiles	orchestrated · full	orchestrated · full
wall-clock cap · excluded	none · nothing	none · nothing

The worker-container-d1 runtime and process boundaries:

Linux (reference)

Self-hosted Linux servers, development, and air-gapped single-node deployments.

The contextful-full Linux executable runs natively on x86-64 or ARM64, using the corresponding x86_64-unknown-linux-musl or aarch64-unknown-linux-musl release artifact. A long-lived contextful pipeline serve process owns the scheduler and launches the same executable as contextful pipeline run or contextful job fire children. A separate contextful serve process answers MCP and HTTP requests. A service manager such as systemd supervises these processes with the same project working directory and configured environment.

Wasmtime executes WebAssembly component connectors inside a run child; its Tokio runtime is embedded there. DuckDB executes SQL inside the process serving reads. SQLite is an embedded library for execution state, with files such as machine.sqlite; Parquet parts, manifests and control snapshots live under the project's configured filesystem root. These libraries have no separate service process.

The optional operator console is a separate Node.js 22 process, node apps/console/dist/server.js --http <host:port>, and reaches the Rust HTTP server through its configured store endpoint. The browser executes the React client. The local target uses the filesystem receive spool; bucket sync adds an explicitly configured S3-compatible endpoint.

The repository's Dockerfile packages the Linux executable in a shell-free, non-root image with /data as its project volume. Separate scheduler and HTTP containers share that persistent volume. On macOS, a Darwin executable runs the same process layout directly; Docker runs the Linux image inside a Linux VM. The topology's macOS sections give both execution paths.

Role	`process` (default)
cron tick	in-process scheduler
reconciler	in-process reconcile loop
durable orchestrator	engine journal in the catalog
single-writer catalog	local catalog file with embedded SQLite execution stores
object store	local filesystem under ./.contextful/, optional S3-compatible sync
hot-path query face	native contextful serve process with embedded DuckDB
heavy compute	native contextful pipeline run or job fire child; embedded Wasmtime for components
secrets	environment and configured secret providers
realtime run projection	in-process WebSocket
queue	—
kind · profiles	daemon · full
wall-clock cap · excluded	none · nothing

The process runtime and process boundaries:

publish-hostname

Hostname access policies, deployment checks and requests through the routing service to the query container.

posture-mismatchtestAn unreachable hostname or response outside its declared access policy raises HostnamePostureMismatch, naming the hostname, policy and observed response. contextful-ci deploy probe exits nonzero.
Why
A-topology#posture-probe
probe-tabletestBefore probing hostnames, the deploy tool compares descriptor and probe-table entries. An entry missing from either set raises ProbeTableDrift, naming the hostname and missing side.
Why
A-topology#posture-probe
empty-probetestAn absent descriptor directory, absent probe table or empty hostname set raises ProbeSetEmpty, naming the path. A passing probe checks at least one hostname.
Why
because a probe that checks nothing and exits zero reads as a proven access policy to the pipeline that invoked it.
unknown-fieldtestAn unmodelled descriptor property raises DescriptorUnknownField, naming the key and contract version. The decoder rejects the descriptor.
Why
P1
unconfigured-gatewaytestA gateway with no store configuration answers 503 on every route and raises GatewayUnconfigured.
Why
P3
issuer-keytestThe HTTP server requires a verification key that resolves and parses. An unusable key raises IssuerKeyUnusable, naming the input, and prevents startup. The server generates no replacement key.
Why
P3
container-readinesstestA retrieval container reaches readiness within 8 s of a cold start, before its snapshot-set hydration completes.

coordinate

Conditional metadata updates, writer leases and the databases that store coordination state.

primitivetestCoordination rests on one property: a linearizable conditional write. No component depends on a stronger one, and the tree ships no consensus implementation or external coordination service.
Why
A-store#coordination-probed-compare
inventoryitemSingle-writer operations comprise lease-row updates, cursor compare-and-swap, pointer-commit, lease acquisition, leased pipeline commit-log entries, bucket manifest commits and configuration version claims. No other operation needs a single writer.
Why
A-store#coordination-probed-compare
lease-rowtestA lease key names a pipeline, source partition, table compaction or deployment cadence. One conditional update assigns the row’s holder, expiry instant and fence.
Why
A-store#coordination-probed-compare
catalog-clocktestThe catalog evaluates a lease row’s expiry against its own clock, never a caller-supplied instant.
Why
A-store#coordination-probed-compare
fence-advancestestEach acquisition of a lease row increments its fence, and release keeps the fence, so the fence never repeats for a key.
Why
A-store#coordination-probed-compare
fenced-committestA commit under a lease is a conditional write predicated on the holder’s fence; a predicate matching nothing is stale-fence.
Why
A-store#coordination-probed-compare
cursor-castestA cursor compare-and-swap is one conditional update predicated on the stored version, read back by its affected-row count.
Why
A-store#store-s-catalogs
cadence-lease-ttltestThe catalog grants a cadence lease for 90 s.
Why
A-store#coordination-probed-compare
cadence-lease-renewaltestThe reconciler renews a cadence lease every 30 s while its applied document schedules a dispatchable unit.
Why
A-store#coordination-probed-compare
cadence-fallbacktestA deployment’s fallback cron fires only after taking the cadence lease itself, so one fire holds the current fence.
Why
A-store#coordination-probed-compare
catalog-porttestEngine code accesses catalog backends through the Catalog trait without naming a backend. contextful-cli selects the backend through dependency injection.
Why
A-store#store-s-catalogs
backendstestSingle-node self-hosting uses a local catalog file. Clusters use Postgres through pg-catalog. Cloudflare execution uses D1 through d1-catalog.
Why
A-store#store-s-catalogs, A-topology#cloudflare-d1
catalog-urltestWith pg-catalog, CONTEXTFUL_CATALOG_URL selects the named Postgres catalog instead of the local file. Without pg-catalog, setting this variable raises capability-absent.
Why
because a daemon falling back to its own file while its peers share the database holds leases no peer sees
postgres-transporttestBeyond loopback or Unix sockets, PostgreSQL requires TLS with WebPKI roots and hostname verification. Disabling TLS there raises DatabaseTransportUnprotected before DNS resolution. Preferred TLS mode permits no plaintext fallback there.
Why
because remote execution state and database credentials cross an untrusted network boundary
postgres-ca-bundletestsslrootcert=<path> in the connection string names a PEM bundle whose roots replace the WebPKI roots of postgres-transport for that connection; hostname verification still applies.
Why
because a managed database such as RDS chains its server certificate to a provider CA that WebPKI omits
postgres-ca-unreadabletestAn sslrootcert path that is unreadable or holds no certificate raises DatabaseCaBundleUnreadable, naming the path, before connecting.
Why
because a silent fallback to WebPKI roots fails later as an unknown issuer and hides the misconfigured path
postgres-verify-modestestsslmode=verify-ca and sslmode=verify-full parse and require TLS on every host, verifying the server’s chain and hostname as postgres-transport does.
postgres-system-rootstestsslrootcert=system selects the WebPKI roots of postgres-transport, as libpq’s system value does, and reads no file.
weak-backendtestA catalog backend whose conditional update is not linearizable refuses at open with weak-conditional-backend.
Why
A-store#coordination-probed-compare
cluster-availabilitytestCluster availability is the shared database’s availability. The engine adds no replication and no failover protocol between daemons.
air-gaptestSingle-node and edge deployments reach no process outside themselves for coordination, and run air-gapped with only their sources reachable.
no-clustered-catalogtestClustered availability behind the Catalog port comes from Postgres alone; the tree ships no self-contained clustered catalog.
Why
because a separate clustered catalog duplicates Postgres replication

unsettled: Does an encrypted store seal its rows in the Postgres catalog, or keep refusing that pairing at open? owner: topology affects: topology.coordinate

bound-application

Responsibilities of the engine and applications that use the engine.

domain-neutraltestThe engine processes declared data, schemas, policies, time bounds and capabilities. Consumer configuration, connectors, components or explicitly selected evaluation profiles supply domain meanings, business rules and sector-specific metrics.
Why
A-topology#public-surfaces
restated-casetestA case with neither a generated artifact nor a callable route stays with the application, which restates the engine rule at its site under mirror-exemption.
Why
because a restatement naming its clause id surfaces when the rule changes, and an adapter for one case costs more than it guards

Shapes

The workspace:

crates/
  contextful-core/         pure domain types and ports, no I/O
  contextful-fs/           exclusive-create publish the store and the journal share
  contextful-engine/       runner, journal, catalog, awakeables, cancellation
  contextful-outbound/     mediated client, credential resolution, quota metering, inference
  contextful-wasm/         sandboxed component host
  contextful-connectors/   native sources
  contextful-decode/       record decoders: JSON, JSON Lines, delimited text, workbook
  contextful-context/      table parts, query face, snapshot commit, retrieval
  contextful-memory/       deterministic memory synthesis
  contextful-sqlite/       the SQLite adapter behind the catalog and run store ports
  contextful-pg/           the Postgres adapter behind the catalog port
  contextful-d1/           the D1 adapter behind the execution store ports
  contextful-policy/       predicates, masks, redaction, zones, audit chain, token trait
  contextful-sync/         bucket push and pull
  contextful-agent/        tool server and connector scaffolder
  contextful-eval/         read-path quality harness
  contextful-snapshot/     control snapshot directory: versions, pointer, drafts, receipts
  contextful-control/      control plane; the one CRDT consumer
  contextful-cli/          the `contextful` binary; dependency injection per profile
  acceptance/              black-box suite driving the built binary
contextful.toml            the deployment declaration, identical across providers

The three profiles as feature bundles:

[features]
contextful-edge    = ["read-plane", "transport-ureq", "s3-sync"]
contextful-full    = ["data-plane", "transport-ureq", "s3-sync", "drive", "component-host", "pg-catalog", "d1-catalog", "aws-secrets-manager", "aws-sqs", "iceberg-export", "otlp"]
contextful-control = ["dep:contextful-control"]

A published-hostname descriptor:

{ "contract": 1, "worker": "contextful-docs", "hostname": "docs.example.org",
  "gate": { "_tag": "public", "acknowledged": true } }

A lease row and a fenced cursor commit, as the Catalog port issues them:

-- acquire: the catalog's clock decides expiry; the fence only grows
UPDATE leases SET holder = :me, expires_at = now() + :ttl, fence = fence + 1
 WHERE key = :key AND (holder IS NULL OR expires_at < now());

-- commit: one conditional update, predicated on version and on the holder's fence
UPDATE cursors SET position = :pos, version = version + 1
 WHERE stream = :stream AND version = :v
   AND EXISTS (SELECT 1 FROM leases WHERE key = :key AND fence = :fence);