Govern · Proposal contract

Receive and reconcile proposals

Govern persists an ActionProposal before notifying the configured host sink. The host creates or returns one local review record, decides what happens next, and reports lifecycle facts back to Tonetify.

Govern proposal
  → host proposal sink
  → operator review
  → host execution
  → authenticated lifecycle callback
  → Govern reconciliation

Proposal delivery

Tonetify sends the configured action_proposal_sink a bearer-authenticated POST with contract_version: "v1". The payload includes proposal identity, host context, kind, display copy, domain payload, context snapshot, optional review evidence, status, expiry, and idempotency key.

The host must create or return exactly one tenant-local record for the proposal ID or idempotency key. A successful response may return:

{
  "host_ref": "host-local-suggestion-id"
}

If delivery fails, the proposal remains persisted. Govern may retry the same logical delivery with the same idempotency key. Delivery failure does not erase or execute the proposal.

Review evidence boundary

review_payload may contain a summary, reason, evidence list, risk assessment, consequence, and authority-boundary copy. It helps the host render a review surface.

It is not host eligibility, mutation authority, an execution permit, or proof that execution is safe. The host must revalidate before acting.

Lifecycle callback

The host reports a lifecycle fact to Tonetify:

POST /api/action-proposals/<proposal-id>/lifecycle
Authorization: Bearer <host-api-key>
Idempotency-Key: <callback-idempotency-key>
Content-Type: application/json

{
  "action_proposal_lifecycle": {
    "contract_version": "v1",
    "status": "executed",
    "writer": "host",
    "idempotency_key": "callback-idempotency-key",
    "host_ref": "host-local-suggestion-id"
  }
}

The idempotency key may be supplied in the header or JSON body. Keep the values identical when both are present.

Status and writer authority

Status	Expected writer
`proposed`, `delivered`, `failed`	`tonetify`
`accepted`, `rejected`	`surface`
`executed`	`host`
`expired`	`tonetify` or `host`, according to expiry policy

Govern validates authentication, proposal correlation, status vocabulary, writer authority, and idempotency. Proposal update and lifecycle-event insert occur in one database transaction.

Tonetify never infers executed from acceptance or delivery. Execution truth requires an authenticated host callback.

Current proof boundary

The Hanken Golden Loop proves proposal delivery, operator accept or dismiss, host execution, lifecycle callback, reconciliation, trace, and outcome evidence.

It does not yet prove that every high-risk mutation is forced through AuthorityGrant → ExecutionPermit → PermitCredential → ExecutionReceipt. That permit-backed path remains an emerging contract.

Next: record host execution evidence.