Core Concepts

Settlement policies

Policy-driven proposal settlement approves, commits, merges, or holds Synapsor-native writes; external targets are approved for trusted writeback.

Overview

Settlement policy outcome depends on target type. For Synapsor-native tables, settlement can approve, commit, and merge the staged branch into Synapsor main. For external Postgres/MySQL targets, settlement can approve or reject the Synapsor proposal and mark it ready for trusted writeback. It does not merge into the external database.

Settlement is opt-in. A proposal stays staged unless a caller explicitly uses SETTLE WRITE, SETTLE AGENT RUN, or a capability invocation names a settlement policy.

Policies evaluate deterministic structured payload fields and trusted reason codes, not arbitrary model prose.

PAYLOAD fields come from the proposal capability's structured result. The proposal argument to SETTLE WRITE is the Synapsor-produced wrp:// handle returned by that proposal, not a value the model invents.

A proposal settlement records the policy version used, the decision, every lifecycle step, and why the proposal was merged or left for review. A workflow-scoped policy uses FOR WORKFLOW and can be applied only through SETTLE AGENT RUN.

Workflow settlement evaluates the linked proposals for that run and returns one run-level summary. Use FOR CAPABILITY for direct SETTLE WRITE on a single wrp:// handle; use FOR WORKFLOW for SETTLE AGENT RUN.

Before a workflow-level auto-commit path mutates data, Synapsor preflights the linked proposal set for authorization and same-target proposal conflicts. Conflicting proposals stay staged for review instead of partially committing a run.

AUTO MERGE is allowed only for Synapsor-native targets after the same policy has approved and committed the proposal. External Postgres/MySQL proposals can be auto-approved by policy, but final database updates must be applied by a trusted worker.

Branching modes Auto-branching Existing DB write proposals

Outcome map by target type

APPROVE means a Synapsor-native proposal can be committed; for external targets it becomes approved for writeback.

AUTO COMMIT records commit inside Synapsor for native targets; for external targets it records approval/settlement state, but the external write still requires a worker.

AUTO MERGE merges a Synapsor-native branch into Synapsor main. It is not valid as a direct external DB merge; use approved_for_writeback semantics for external targets.

HOLD leaves a native branch staged or an external review branch/proposal staged. REJECT rejects the proposal and leaves production-visible state unchanged.

Synapsor-native targets

APPROVE: proposal can be committed
AUTO COMMIT: records commit inside Synapsor
AUTO MERGE: merges Synapsor branch into Synapsor main
HOLD/REJECT: branch remains staged or isolated

External Postgres/MySQL targets

APPROVE: proposal becomes approved for writeback
AUTO COMMIT: records approval/settlement state only
AUTO MERGE: not a direct external DB merge
HOLD/REJECT: review branch/proposal remains staged or rejected

Settlement branch diagram

Settlement policies are the controlled auto-merge path for low-risk Synapsor-native proposals. External proposals are approved for trusted writeback instead.

proposal branch

The capability stages a write proposal on an isolated branch and returns a wrp:// handle.

structured payload

The settlement policy evaluates typed fields such as decision, risk lane, amount, and trusted reason codes.

low-risk match

When every deterministic condition matches, the policy can record approval/commit/merge for native targets or approved-for-writeback for external targets.

hold for review

Yellow, red, missing-field, disabled-policy, or conflict cases stay proposed and visible to reviewers.

native merge or writeback

Native changes can merge into Synapsor main. External updates wait for trusted worker writeback.

Developer notes

Use settlement only for low-risk workflows with deterministic conditions.
Use JSON_VALUE(run.output, '$.field') for workflow-run conditions and PAYLOAD for each linked proposal's structured fields.
Run-output conditions are checked once before any linked proposal is approved, committed, merged, rejected, or left staged.
Workflow settlement preflights authorization and duplicate target effects before mutating any linked proposal.
Keep yellow, red, conflicting, or disabled-policy proposals staged by default.
Require RBAC for approve, commit, and merge or writeback-ready steps.
Audit policy version changes before enabling automatic merge paths.
Reject or warn on AUTO MERGE for external Postgres/MySQL proposal targets; use approved-for-writeback instead.

Settlement grammar

SQL

-- AUTO MERGE is for Synapsor-native proposal targets.
-- External Postgres/MySQL proposals can be auto-approved by policy, then marked ready for trusted writeback.
CREATE SETTLEMENT POLICY expenses.green_auto_settle -- developer-defined policy name
FOR CAPABILITY expenses.propose_expense_decision    -- proposal capability governed
TARGET BRANCH main                                  -- Synapsor-native merge target for low-risk commits
AUTO APPROVE WHEN
  PAYLOAD decision = 'approved'                     -- structured decision field
  AND PAYLOAD reason_codes CONTAINS 'synapsor_auto_approval_gate' -- required reason code
  AND PAYLOAD risk_lane = 'green'                   -- low-risk policy-approved only
AUTO COMMIT                                         -- commit after policy approval
AUTO MERGE                                          -- merge Synapsor-native branch into target
ELSE LEAVE PROPOSED;                                -- non-green cases stay staged

SETTLE WRITE 'wrp://1' USING POLICY expenses.green_auto_settle; -- wrp://1 is returned by Synapsor

CREATE SETTLEMENT POLICY expenses.workflow_green_auto_settle -- run-level policy name
FOR WORKFLOW expenses.review_expense_flow          -- workflow name from CREATE AGENT WORKFLOW
TARGET BRANCH main                                 -- Synapsor-native merge target
AUTO APPROVE WHEN
  JSON_VALUE(run.output, '$.risk') = 'low'        -- run output from END AGENT RUN
  AND PAYLOAD decision = 'approved'               -- each linked proposal payload
  AND PAYLOAD reason_codes CONTAINS 'synapsor_auto_approval_gate'
  AND PAYLOAD risk_lane = 'green'
AUTO COMMIT
AUTO MERGE
ELSE LEAVE PROPOSED;

END AGENT RUN 'run_...'                            -- run_id from BEGIN AGENT RUN
STATUS waiting_approval
WITH JSON '{"risk":"low","decision":"proposal_ready"}';

-- Settle all proposals linked to a workflow run with one retry-safe command.
SETTLE AGENT RUN 'run_...'                           -- run_id from BEGIN AGENT RUN
USING POLICY expenses.workflow_green_auto_settle      -- requires a FOR WORKFLOW policy
IDEMPOTENCY KEY 'settle-run-...';                    -- optional app retry key

Examples

sql

-- ALTER changes future settlement behavior; audit policy-version changes.
ALTER SETTLEMENT POLICY expenses.green_auto_settle -- existing policy name
SET TARGET BRANCH main                             -- merge target for approved commits
AUTO APPROVE WHEN
  PAYLOAD decision = 'approved'                    -- structured decision field
  AND PAYLOAD reason_codes CONTAINS 'synapsor_auto_approval_gate' -- required reason code
  AND PAYLOAD risk_lane = 'green'                  -- low-risk policy-approved only
  AND PAYLOAD amount_cents <= 750000               -- policy-specific amount cap
AUTO COMMIT                                        -- commit only after approve
AUTO MERGE                                         -- merge only after commit
ELSE LEAVE PROPOSED;                               -- hold anything else

ALTER SETTLEMENT POLICY expenses.green_auto_settle -- operational metadata change
SET DESCRIPTION 'Green-lane expense auto-settlement'; -- human-readable policy note

ALTER SETTLEMENT POLICY expenses.green_auto_settle SET ENABLED false; -- pause auto-settle
ALTER SETTLEMENT POLICY expenses.green_auto_settle SET ENABLED true;  -- resume auto-settle