Core Concepts

Write proposals

Write proposals stage risky agent writes for human or policy approval.

Overview

EXECUTION PROPOSAL capabilities create a proposal and branch diff instead of committing writes.

A proposal lookup id such as wrp://1 is returned by Synapsor when the proposal is created. Use that returned handle for PREVIEW, APPROVE, COMMIT, SETTLE, READ RESOURCE, and audit queries; last_proposal is only a current-session learning alias.

Reviewers can approve, reject, or commit after inspecting evidence. Policy-matched proposals can also be settled by a deterministic policy that explicitly enables auto-commit and auto-merge.

Rejected proposals leave production unchanged.

Agent Activity Find evidence later Evidence bundles Replay

Write proposal lifecycle

Proposal mode is the write proposal flow for agent-assisted changes.

Invoke proposal capability

The app calls an approved capability with hidden tenant and principal bindings.

Stage on branch

Synapsor writes proposed changes away from main and returns a proposal lookup id.

Preview

Reviewers inspect the diff, target rows, evidence bundle, and audit metadata.

Approve or settle

A human or deterministic settlement policy approves policy-matched proposals.

Commit/merge

Only approved changes reach main; rejected proposals leave production unchanged.

Developer notes

Require reviewer identity on approval.
Show row-level diffs before commit.
Keep evidence attached to proposal records.
Make commit idempotent and auditable.

Proposal capability

SQL

CREATE AGENT CAPABILITY billing.propose_late_fee_waiver -- returns wrp:// handles for review
DESCRIPTION 'Create a previewable late-fee waiver proposal'
ARG invoice_id INT64 REQUIRED                -- caller-provided invoice id
ARG reason VARCHAR REQUIRED                  -- caller-provided reason/note
HIDDEN tenant_id FROM SESSION tenant_id      -- trusted tenant/account id
HIDDEN principal FROM SESSION principal      -- authenticated actor
USE CONTEXT billing.invoice_context          -- reviewed invoice context
EXECUTION PROPOSAL                           -- returns proposal lookup id instead of direct write
RETURNS JSON '{"type":"object","properties":{"proposal":{},"branch":{},"evidence_bundle":{}}}'
PROFILE MINIMAL
INLINE EVIDENCE handles_only
WRITE PROPOSAL TARGET invoices               -- table that may be updated
OPERATION UPDATE                             -- only UPDATE allowed
LOOKUP id FROM ARG invoice_id                -- target row lookup
TENANT tenant_id FROM BINDING tenant_id      -- tenant ownership guard
COLUMNS late_fee_cents FROM VALUE 0,         -- literal proposed value
        reviewer FROM BINDING principal,     -- trusted actor
        decision_note FROM ARG reason        -- caller-provided note
AUDIT billing_audit                          -- audit table
SUMMARY TEMPLATE 'Waive late fee for invoice {invoice_id}'; -- {invoice_id} from ARG

Examples

python

proposal = db.invoke_agent_capability(
    "billing.propose_late_fee_waiver",
    {"invoice_id": 3001, "reason": "card update failure"},
    mode="propose_only",
    auto_branch=True,
    response_envelope=True,
)

proposal_id = proposal["proposal"]["proposal_id"]
db.approve_write(proposal_id, reason="Reviewed policy evidence")
db.commit_write(proposal_id)

# Green-lane alternative when a settlement policy applies:
db.settle_write(proposal_id, settlement_policy="billing.green_late_fee_settle")