# 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.