External integrator guide
Turn AI-agent work into reviewable proof.
Blackboard captures AI tools, agent sessions, evidence, approvals, access events and exports as append-only event truth, then presents the work in Proof Desk and deterministic Proof Packet v1.
Rook is the reference harness. BYO harnesses integrate through the public API/MCP/SDK contract. Context, Switchboard, if.bus, if-cli, WSL and maintenance bridges are implementation or operator details, not the customer product story.
Example UI reference
This static demo shows the intended product shape: AI registry, transparent five-dimension risk scoring, approval routing, evidence timeline, claim boundary and Proof Packet preview. It uses bundled JSON fixtures only.
The browser demo risk engine is a reference implementation for builders. The production risk service is roadmap work and must write signed or hash-bound events before approvals become authoritative.
Builder feature parity gaps
Customer frontends and builder UIs should build to Blackboard as API clients. The missing work is not a prettier registry; it is the event-backed governance substrate behind the screens.
| Gap | Proactive fill |
|---|---|
| Risk score is not yet a production API service. | POST /v1/risk/evaluations with formula version, input hash, policy hash, event id and signed/hash-bound output. |
| Regulatory posture needs a control profile catalog. | GET /v1/regulatory/profiles plus framework-specific posture updates as evidence posture, not legal advice. |
| Approvals must be reconstructable. | Append reviewer, role, scope, conditions, checklist, timestamp and access.logged evidence. |
| Raw evidence is unsafe for agents and proof claims. | POST /v1/evidence/sanitize before search snippets, recall, packets or claim-boundary use. |
| CSV/PDF exports are not proof packets. | Make Proof Packet v1 the external artifact; keep normal exports as convenience outputs with access logs. |
| Search cannot be proof authority. | Use search as discovery only, then hydrate from event truth before approval, export or proof claims. |
Keeping agents honest
A registry UI can be heavy on promised governance. Blackboard fills the reality gap by making agent claims reconstructable, reviewable and hard to overstate.
| Risk | Control |
|---|---|
| Agent says work is done but evidence is missing. | Closeout templates default missing claims to missing or not_claimed; task.closed is blocked until evidence or non-claims are explicit. |
| Agent uses stale or untrusted retrieved text. | Evidence sanitisation and content_trust gates stop raw text becoming proof, prompts or memory. |
| Agent loses device/session provenance. | Session provenance binds tenant, user/service account, agent, client app, host, IP class, transport and source harness. |
| Reviewer memory becomes the enforcement system. | API policy gates reject, quarantine, downgrade or block first; reviewers or review agents are assigned only for judgment triggers. |
| Agents choose fast templates over hard truth. | Safe prefill templates prefill context and checklists, never verified claims. Validation returns blockers and next evidence. |
The product trick is simple: make the honest path faster than the shortcut.
Core workflow
| Step | What happens | Authoritative surface |
|---|---|---|
| Register | AI tool, use case, agent workflow or task is registered as a governed asset/work item. | POST /v1/governance/assets, POST /v1/events |
| Score | Risk dimensions are scored and routed to auto-approval, compliance, legal/security or blocked state. | GET /v1/governance/assets/{asset_id}/risk |
| Review | Approver records decision, conditions, notes and checklist with timestamped access evidence. | POST /v1/approvals/{approval_id}/decision |
| Evidence | Logs, documents, provider refs, tickets and receipts are attached, quarantined and sanitized before agent-facing reuse. | evidence.attached, content_trust |
| Export | Proof Packet v1 is assembled with event range, hash-chain root, redaction manifest, access log ids and non-claims. | POST /v1/proof-packets |
Trust boundaries
- Receipts prove bytes and binding metadata, not semantic correctness.
- Search is a rebuildable discovery index, not proof authority.
- WebSocket is live notification only; durable proof lives in event truth.
- Raw evidence text is untrusted content until sanitized or reviewer-approved.
- SSH, tunnels, stdio MCP and maintenance bridges are operator or break-glass only.
demo_token_not_a_secret. The local preview uses a per-run token; target-contract examples use the demo token only as a rejected placeholder.Integration routes
| Route | Use | Status |
|---|---|---|
| HTTPS REST API | Durable writes, timeline reads, search and export. | Target |
| Local HTTP preview | Start implementation against event, timeline, search, Claim Boundary and Proof Packet JSON shapes. | Smoked fixture |
| Managed MCP | Scoped agent tools for events, search, evidence and packets. | Target |
| WebSocket live | Progress, wake/contact and shared UI notifications. | Target live-only |
blackboard CLI | Developer smoke, auth, event submit, timeline/search/export. | Target |
| Local verifier | Schema and deterministic binding checks for examples. | Smoked |
Verification gates
- Sample events and Proof Packet v1 examples validate against the published schemas.
- The contract smoke checks reject missing event signatures and Proof Packets without non-claims.
- The local API preview smoke checks per-run token auth, preflight behavior, event writes, timeline reads, search, Claim Boundary, Proof Packet assembly, customer-SSH rejection, cross-tenant packet blocking and same-tenant cross-workspace scope blocking over HTTP.
- The ensemble conformance gate checks required Blackboard boundary terms, source links, event-type coverage and forbidden customer-doc wording.
- The target customer CLI shape is
blackboard contracts smokeandblackboard contracts conformance.