1.8 KiB
KAB ingestion contract (v1)
Note
For the authoritative contract specification, see spec/ingestion-contract.md.
Connector interface
full(config) -> (Document[], SyncCursor), incremental(config, cursor, changes?) -> (Document[], SyncCursor), and webhook(config, payload, headers) -> Change[]. Implementations must be deterministic for the same source revision, scope, and credentials. Config has connector_id, tenant_id, secret reference, source scope, and non-secret options.
Normalized document
Required fields: stable id, tenant_id, title, UTF-8 content (or extractor output), MIME type, SHA-256 content_hash, modified timestamp, provenance, acl, metadata, and deletion marker. Binary extraction may be delegated to a managed extractor; the connector still supplies original MIME and hash.
Provenance and ACL
Provenance includes source type/id, canonical URL, revision/eTag, retrieval time, webhook event, and connector version. ACL includes tenant, principals, groups, and visibility. Tenant equality is mandatory; downstream search must apply ACL predicates.
Cursor/triggers
Cursors contain connector id, mode, source revision or delta token, and update time. Full runs establish a baseline. Incremental runs advance the cursor only after publication succeeds. Triggers are on_demand, cron scheduled, or signed webhook; each carries full|incremental, idempotency key, retry policy, and dead-letter destination.
Governance
Upserts are idempotent by document id/hash. Deletes and retention events are auditable, tenant-scoped, and must use managed secret references. No token or document content is logged.