Kaiba Controller

A durable development-candidate inbox between kaiba-provisioning and kaiba-flow. The first slice imports the shared ProvisioningRecord, checks retained evidence, keeps revision history, and exposes scoped observation APIs. Every imported candidate remains ineligible for production admission.

This implementation uses Python 3.12 and SQLite. The shared wire contract is language-independent; schemas are bundled from the exact commit in vendor/kaiba-contracts/PIN.json.

Run the software rehearsal

python -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements.txt
python -m unittest discover -s tests -v
python -m kaiba_controller --database /tmp/kaiba-inbox.sqlite \
  --sources sources.example.json import-record --source provisioning-rehearsal \
  fixtures/rehearsal/records/*/*.json
python -m kaiba_controller --database /tmp/kaiba-inbox.sqlite \
  --sources sources.example.json list --tenant kaiba-lab --security-domain development

Repeat import to see duplicate. Restart and the same candidate/history remains. The checked-in fixture is a synthetic seven-operation campaign using provisioning's real control/audit services; its old timestamp deliberately appears stale today. It is not a hardware run or production evidence. To regenerate it from the provisioning checkout containing the adapter:

python tools/rehearse.py --provisioning ../kaiba-provisioning

Read API for Flow

Generate a private token file, then start the loopback-only service:

python -c 'import os,secrets; os.umask(0o077); open("/tmp/kaiba-read-token", "x").write(secrets.token_urlsafe(32))'
python -m kaiba_controller --database /tmp/kaiba-inbox.sqlite \
  --sources sources.example.json serve --tenant kaiba-lab \
  --security-domain development --token-file /tmp/kaiba-read-token

Send Authorization: Bearer <token> on every read. Endpoints:

Route	Result
GET /api/v1/candidates	Latest immutable observation per source transaction, age and admission blockers
GET /api/v1/candidates/{record_id}/history	Descending revision history
GET /api/v1/imports	Accepted, duplicate and rejected import metadata

Queries support limit (1–100) and offset; responses include next_offset. The server fixes tenant and security domain at startup. Query parameters cannot change scope. There is no HTTP import, enrollment, configuration publication or execution endpoint. Raw retained/rejected evidence is never exposed by these APIs. A future Flow server-side adapter should hold the read token and display source readiness separately from controller admission assessment. This service has not been deployed or connected to the published Flow prototype yet.

Trust and persistence

Review the integration boundary before real imports. sources.example.json trusts only the synthetic rehearsal. Real operator-owned configuration pins authority, scope, source commit, profile/bundle/policy and role-specific evidence directories. Import chooses this configured authority outside the payload. Never substitute evidence copied from an untrusted uploader.

The resolver verifies exact evidence bytes, source bindings, upstream event hashes, receipt membership and terminal evidence. It never fetches payload-selected URLs. retained_evidence_checked is explicitly not live authority verification. Historical observations can be stored; stale state, missing device identity and live verification remain visible blockers. Production admission is always false.

SQLite uses WAL and FULL synchronous commits. Snapshot insertion, latest pointer and acceptance history share one transaction. (scope, record_id, revision) is immutable; a changed retry is rejected. Unseen older revisions cannot replace the latest observation. Accepted historical retries acknowledge duplication without rolling back state. Rejected bounded input stays private in the database.

Use a private local disk for the database (not a network filesystem), protect its backups and authority evidence directories, and restart the read service to load source-policy changes. There is no production deployment manifest in this slice.

Pending provisioning integration

GitHub's integration rejected write access to PseudoDesign/kaiba-provisioning with HTTP 403. The complete tested source change is retained in integrations/provisioning-export.patch, with baseline and checksum in integrations/PIN.json. CI applies this patch to the pinned baseline before the software rehearsal. To review/apply in a clean checkout at that baseline:

git -C ../kaiba-provisioning apply --check "$(pwd)/integrations/provisioning-export.patch"
git -C ../kaiba-provisioning apply "$(pwd)/integrations/provisioning-export.patch"

The patch adds the read-only exporter, tests, documentation and a service-suite binary. It does not change existing source workflow semantics. Upstream landing is pending repository write access; the controller is usable with the bundled synthetic fixture now.