Spoolis docs

Evidence sources

Connect arbitrary systems through immutable evidence capsules and reproducibly derived facts.

Source contract

A source declares authentication, pagination, checkpointing, replay, schema-change, deletion, correction, and health semantics. Tier 0 supports CSV, JSON, file upload, HTTP with OpenAPI, signed webhooks, read-only SQL, S3-compatible object storage, and CloudEvents.

Secrets are environment or vault references. They are not returned from the API or written to logs. Signed webhook connections must use an environment reference named SOURCE_WEBHOOK_SECRET_ followed by 1–64 uppercase letters, digits, or underscores.

Capsules and facts

Every read creates an immutable cap_ capsule. Its raw artifact is addressed by SHA-256 in private storage. A new read creates a new capsule. Extractors create immutable fct_ facts and record extractor, schema, derivation, and provenance versions. Inferred facts require confidence; deterministic facts forbid it.

Evidence from another system is what Spoolis observed, with provenance. It is not truth by itself. Spoolis maintains the canonical accepted commercial state under the agreement's rules and authority model.

Add and sync a source

API

POST /api/v1/sources
GET /api/v1/sources
POST /api/v1/sources/{id}/sync
GET /api/v1/spools/{id}/facts

Sync work is chunked and checkpointed. Replayed job ids are no-ops. Failed chunks retain their checkpoint in a dead-letter row.