# Governance service contract 1.0.0

This is an implementation contract, not a list of deployed endpoints. The offline checker does not authenticate people, access wallets, tally a production election, execute a mandate or publish content.

## Persistence and invariants

Use durable relational records for immutable versions, drafts, electorate snapshots, ballots, delegations, credit entries, decisions, mandates, intents, receipts, reservations and events. Graph/vector indexes are rebuildable ACL-filtered projections. Persist the state transition and outbox event in one transaction.

Unique constraints: record (kind,id,revision); immutable authored proposal revision; one effective ballot per proposal revision and voting unit with explicit supersession; credit issuance per proposal and unit; intent idempotency key within Realm; provider transaction binding; resource reservation identity. Enforce at write time, not solely in the client.

All commands authenticate principal and scope, check expected revision, include idempotency key and trace ID, and re-evaluate current policy and revocation. Return actual stored revision, field-level blockers and receipt references. Same key/same payload returns the original result; same key/different payload conflicts. A failed HTTP response is not evidence that an action did not occur.

## Hashing and immutable references

Profile GJ-1: UTF-8 JSON, lexicographically sorted object keys, compact separators, no ASCII escaping, no NaN/Infinity and no floating point numbers. Do not normalize Unicode. Restrict integers to the interoperable safe range ±(2^53−1). Monetary values use positive integer micro-USDC with decimals=6; no binary floating point. Production implementations must pass matching cross-language vectors.

payload_hash covers the complete typed payload. revision_hash covers all ProposalRevision fields except revision_hash, status and eligibility_ref. The exact body therefore binds policy, cycle, author, source references and payload. Status is a mutable projection; append-only events preserve its history. eligibility_ref is attached at voting opening and cannot then change on the same voting revision. Ballots and Decisions independently bind proposal hash, policy and snapshot. Policy body_hash covers the exact referenced immutable body using GJ-1 for JSON or raw UTF-8 bytes for a Markdown policy body; record its MIME/profile in the content service.

Synthetic fixtures cannot be used as adoption or execution evidence for operational records.

## Proposed command interface

| Command | Principal checks | Result |
|---|---|---|
| CreateProposalDraft | Author scope; known DUNA/Realm relationship | Editable draft |
| SaveProposalDraft | Exact base/If-Match; permitted fields | New draft or conflict |
| SubmitProposal | Typed payload, complete referenced evidence, proposer eligibility, applicable rule/class | Submitted revision; no execution |
| PublishPolicyDraft | Content publication rights and hashes | Immutable proposed policy text |
| OpenVoting | Adopted governing rules, calendar, frozen proposal and electorate | Voting state and snapshot |
| CastBallot | Current identity/delegation, voting window, eligible unit, policy and revision hashes | Effective ballot with supersession history |
| RecordNegotiation | Applicable adopted mechanism, mandate, credit reservations if required | Attributable event |
| CloseAndDecide | Closed window, supported deterministic ruleset, eligible effective inputs | Immutable decision and reasons |
| ResolveChallenge | Authorized resolver, notice/evidence and rule | Decision-linked resolution |
| ActivatePolicy | Decision under prior policy or evidenced bootstrap, exact body, transition | Effective PolicyVersion |
| ActivateMandate | Adopted decision, valid grantor, scope/limits and tools | Bounded active mandate |
| PrepareExecution | Decision, delay, challenge resolution, dependencies and current authority | Exact ExecutionIntent |
| DispatchExecution | Fresh preflight, reservation, adapter permissions and unchanged payload | Submitted intent |
| ReconcileExecution | Query provider by original reference/key | Verified receipt, unknown, or failure |
| RevokeMandate | Current revoker authority and expected version | Revocation event and queued-use invalidation |

409 for stale revision, occupied voting unit without allowed supersession, or key/payload conflict; 403 for authority failures; 422 for unresolved policy, incomplete effect or unsupported mechanism; 503 for unavailable dependencies. Avoid leaking private inaccessible identifiers.

## Preflight at the action boundary

Resolve proposal, decision, exact payload hash, policy and electorate. Check adopted result, elapsed delay, resolved challenges, unexpired decision/mandate and any new revocation. Resolve the actual DUNA-to-Realm mapping, current execution class, required consent, legal-review conditions, provider/network, funds and immutable target records. One failed or unknown check blocks dispatch.

A policy decision authorizes only its exact effects. If an external transaction needs preparation after voting, the original proposal must have bounded its preparation rule; otherwise changed instructions require a revised proposal. This version's treasury-management payload pins instruction_hash; it does not support unconstrained future construction.

## Treasury and external services

TreasuryAdapter separates configured accounts, balance/reservation, prepare, simulate, signer approvals, submission and receipt reconciliation. Pin network and asset identifier, recipient, amount, fees and instruction hash. Kiduna adoption does not itself create a wallet signature. Check external spending allowances on offboarding independently of internal role revocation. Adapter implementation must verify current provider documentation before deployment.

A payment marked unknown is neither failed nor paid; query the same provider reference before retry. Confirmed success plus evidence is required to update settlement. A refusal or failure keeps reasons and obligations. Compensation, refund and reversal are new records, never deletion.

For communications, bind exact artifact hash and destinations. For organizational changes or partnerships, record external-action-required until actual signatures/filing evidence is captured. For Activities and Initiatives, call their existing scoped services; never directly set reviewed reality, accomplished work or Paid.

## Audit and privacy

Events contain event ID, aggregate/revision, actor and principal, authority reference, timestamp, correlation/causation IDs, policy revision and classified payload. At-least-once consumers deduplicate by event ID. Read/search checks happen before retrieval and ranking; revocation invalidates cached views. Separate public reasons from restricted member data and secret ballots. Never log private agent instructions or hidden reasoning as evidence.

## Acceptance boundary

Offline tests cover schema, hashes, duplicate IDs, selected state and binding checks, and representative execution blockers. Production acceptance additionally requires simultaneous ballots/reservations, real ACL and grant enforcement, provider reconciliation, independent legal/adoption evidence, tamper-resistant audit and all adapters. See [acceptance scenarios](../docs/ACCEPTANCE.md).