Overview
Auto-branching means two things depending on the data source. For Synapsor-native tables, auto_branch creates a real Synapsor branch and approved proposals can commit and merge into Synapsor main.
For external Postgres/MySQL sources, auto_branch creates a Synapsor review branch that stores the proposal, row diff, evidence, query audit, replay record, and writeback plan. It does not create a branch inside Postgres/MySQL and it does not auto-merge into the external database.
The app receives compact Synapsor-produced ids in the response envelope: a branch_name or review-branch name, a write proposal lookup id such as wrp://1, an evidence bundle id, and an agent_run_id. Reviewers can preview the diff before production-visible state changes.
Applications can pass auto_branch from HTTP, Python, or Node. Whether a low-risk proposal auto-approves, auto-commits, and auto-merges for Synapsor-native data should be defined in SQL with CREATE SETTLEMENT POLICY. External-source proposals can be auto-approved by policy, but final database updates require trusted worker writeback.
External source auto-branch behavior
When a proposal capability is generated from an external Postgres/MySQL mapping, Synapsor can still create a review branch. That branch stores the proposed change and review state in Synapsor, while the external source remains read-only to the model and unchanged by the public/runtime proposal path.
Flow: agent calls approved proposal capability; Synapsor reads external rows through mappings; Synapsor records evidence and query audit; Synapsor creates a review branch and wrp:// proposal; reviewer or policy approves/rejects; trusted worker applies approved writeback to the external DB; Synapsor records writeback result or conflict.
Docs authors should not describe this as auto-merging Postgres/MySQL. Say approved for writeback or auto-approved by policy.
Auto-branch outcome map
Every proposal starts isolated. Synapsor-native proposals can merge into Synapsor main; external proposals become approved for trusted writeback.
- App calls a proposal capability
- Tenant and principal come from hidden session bindings
- auto_branch requests a Synapsor-native branch or Synapsor review branch
- Synapsor creates the branch/review branch
- The capability writes a wrp:// proposal
- Evidence and replay records are returned with the response
- Preview row-level diff
- Inspect evidence bundle and reason codes
- Approve, reject, or leave proposed
- Structured fields match deterministic policy
- Synapsor records approval/commit steps
- Native target: AUTO MERGE promotes to Synapsor main
- External target: approved for trusted writeback
- Missing policy fields, conflicts, or yellow/red lanes stay staged
- Rejected/canceled proposals leave production unchanged
- Old native branches or review branches can be cleaned up later
Auto-branch from capability invocation
The application calls one reviewed capability; Synapsor creates the branch, proposal, evidence, and replay records.
Production-visible state remains unchanged.
The app invokes a proposal capability with hidden tenant/principal bindings and auto_branch true.
Synapsor creates an isolated branch for this capability invocation.
The write proposal records target table, lookup row, allowed columns, evidence, and audit metadata.
Reviewers inspect proposed row changes before approval or settlement.
The branch, proposal, and evidence lookup records remain durable for later inspection.
Human approval path
Yellow, high-impact, or ambiguous proposals stay branch-staged until a person approves and commits.
The proposed update is isolated away from main.
A reviewer checks row-level diff, evidence bundle, hidden principal, and reason codes.
APPROVE WRITE records reviewer identity and reason.
COMMIT WRITE applies the approved proposal.
The branch merges only after approval and commit succeed.
Low-risk auto-merge path
Only deterministic settlement policies can auto-approve, auto-commit, and auto-merge low-risk proposals.
The capability returns fields such as decision, risk_lane, amount, and trusted reason_codes.
SETTLE WRITE evaluates policy conditions against structured fields, not free-form prose.
The policy records the approval when every low-risk condition matches.
The policy commits the approved proposal.
AUTO MERGE promotes the branch to main only after approve and commit steps are recorded.
Hold, reject, or cancel path
Unsafe or unclear proposals remain staged so production stays unchanged.
Missing fields, yellow/red risk, disabled policy, or conflict keeps the proposal proposed.
A reviewer can reject the proposal with a reason.
The app or operator can cancel abandoned proposals.
After review, abandoned proposal branches can be cleaned up to release quota.
Rejected, canceled, and held proposals do not mutate production.
Developer notes
- Use auto_branch true for proposal-capable agent workflows that might change production data.
- Use CREATE SETTLEMENT POLICY ... FOR CAPABILITY for a single proposal capability, or FOR WORKFLOW when SETTLE AGENT RUN should settle every proposal linked to that run.
- Use the returned branch id from the response envelope; auto-branch names are generated and should not be parsed by app code.
- Inspect auto branches through DIFF BRANCH, synapsor_agent_write_proposals, and synapsor_agent_settlement_events.
- Treat wrp:// handles as durable Synapsor-produced proposal references, not URLs.
- Use settlement only for deterministic low-risk cases; leave ambiguous proposals staged.
- Clean up abandoned proposal branches so branch quotas stay meaningful.