Proposed integration contracts · 2026.10.26.1
These are engineering proposals derived from the call and existing kit boundaries. They are not claims about an implemented API. Reuse the production team's actual service names once supplied; keep the invariants below.
Intent envelope
Required fields: id, schemaVersion, source (chat/voice/page/automation), actorMemberId, representationId, conversationId, intent, context, createdAt, correlationId, idempotencyKey.
Context carries the selected DUNA, Initiative, Activity instance and Action IDs; the current object revision; permitted memberships; references to relevant wisdom and previous stage receipts; scope and visibility. References are preferable to copying unrestricted conversation or private evidence. Automation requests additionally identify their definition/version, run, trigger event, owner and current grant. Never accept client-provided permissions as authority.
Route decision
Return one of: route, clarify, reroute, escalate, reject. A route has a typed destination (envoy, mask, scout, guide, ki, actor), stable destination ID, bounded task, rationale, evidence references, missing context, proposed capabilities and policy version. A reroute preserves original request/draft IDs, previous destinations, consent and reason. Set limits on attempts, elapsed time and repeated destinations; unresolved loops escalate with context. A model’s score is evidence, never an authorization grant.
Capability bundle
Resolve entity and Ally IDs, instruction version, permitted wisdom scopes, Skill versions, Tool grants, automation definitions and Vibe version. Store the resolution receipt with the run. A Skill update is a reviewed version transition, not an in-place change to already accepted work. A Mask's internal member association is restricted; only the permitted representation is emitted to other participants.
Commands and authority
| Proposed command | Required guards | Result |
|---|---|---|
| route_intent | Authenticated representation; current scope; visibility-filtered references | Route/clarification receipt. |
| create_draft | Valid parent type; purpose fit; permission; idempotency | Stable draft ID and revision. |
| revise_draft | Owner/editor authority; expected revision | New version and change receipt; stale edit conflict. |
| publish_draft | Validated parent, content, visibility, dependencies and authority | Atomic publication receipt; child links reference committed versions. |
| claim_activity | Template/version; scope; instance availability; existing completion check | Instance/participation record or existing-result reference. |
| submit_evidence | Active participant/authorized delegate; artifact access; explicit submission | Immutable evidence revision with source and hash. |
| review_evidence | Current submitted revision; reviewer role; conflicts; governing review policy | Decision, rationale and escalation/return state. |
| complete_activity | Accepted required evidence and prerequisites; closer authority | Completion receipt; no implicit payment. |
| prepare_outreach | Permitted recipient discovery; scope; disclosure review | Reviewable message draft. |
| execute_outreach | Approved recipient and content; valid Tool grant; idempotency | Provider receipt or explicit failure; retries do not double-send. |
| prepare_distribution | Reviewed contribution references; budget; pinned adopted policy; conflicts | Versioned proposal; no transfer. |
| execute_mandate | Unexpired mandate; exact effect; signer authority; asset restrictions; remaining budget | Idempotent execution receipt and reconciliation state. |
State and event invariants
Draft → validated draft → published; failures retain draft/checkpoints. Activity template and instance are different identities. Evidence: draft → submitted revision → accepted or returned; returned → changed revision → explicit resubmission. Action completion is separate from Activity closure. Closure is separate from distribution eligibility, decision, mandate and settlement. The Governance Kit owns proposal lifecycle details; this document does not invent a competing enum.
Each effect emits eventId, aggregateId, aggregateVersion, eventType, actor, occurredAt, correlationId, causationId, requestId, source references and result/receipt. Consume with idempotency and ordering per aggregate. Recheck authority on execution, even if the task was prepared earlier. Tool disconnection or mandate revocation blocks dispatch and preserves a resumable record.
Database and client integration
Structured state is authoritative for IDs, permissions and balances. Graph/vector results refer back to canonical IDs and their access controls. Search indexes are replaceable projections; they cannot authorize state changes. Chat widgets and page controls call the same mutation; list/detail updates use versioned events. On reload, rebuild from canonical server state rather than trusting local UI labels. The current prototype's local storage must be migrated explicitly; it is not the production authority.
Required adverse cases
Reject wrong-parent Action creation; denied private membership retrieval; stale policy or draft version; duplicate claim of a completed instance; acceptance of returned/unchanged evidence; unauthorized reviewer; exceeded budget; revoked mandate; duplicate send/payment retry. Preserve useful results on timeout. When no safe route is known, ask one focused question or escalate rather than guessing authority.