Synapsor
Log inGet access
All docs
Docs
Core Concepts

Branches

Branches isolate data changes for review, tests, cleanup, and proposal workflows.

Overview

Important: branches are real database branches for Synapsor-native hosted data. When a workflow uses an existing external Postgres/MySQL source, Synapsor does not branch that external database.

External source workflows create a Synapsor review branch for proposal state: source row references, evidence, query audit, proposed field changes, approval state, replay metadata, and trusted writeback intent. The external source remains unchanged until a customer-controlled trusted worker applies an approved writeback.

Hosted database-scoped keys are pinned to one runtime branch.

Operator and trusted control-plane flows can create, diff, merge, or drop branches.

Explicit branch names are user-defined. Auto-created proposal branch names are returned by Synapsor in the proposal/capability response and are visible in synapsor_agent_write_proposals.

Agent write proposals use Synapsor-native branches or Synapsor review branches to show the diff before production-visible state changes.

Green-lane proposals can be auto-approved, committed, and merged only when a deterministic settlement policy explicitly allows AUTO COMMIT and AUTO MERGE. Yellow, red, conflicting, or disabled-policy proposals stay staged for review.

Branching modesAuto-branchingExisting DB write proposals

Branch review flow

Synapsor-native branches let hosted-data writes stay isolated until a reviewer or deterministic settlement policy decides what can move to Synapsor main. External database workflows use Synapsor review branches instead.

Branch review flowA branch carries cleanup or agent-assisted edits through diff review, then either merges or remains isolated for cleanup.mainreview branchmainsourcecreatebrancheditsisolateddiffrowsreviewdecisionreject pathcleanupmergereviewed
1
Synapsor main

Production-visible Synapsor-native state stays unchanged while the proposal branch is evaluated.

2
create Synapsor-native branch

Synapsor creates an isolated branch for the hosted-data proposal or cleanup workflow.

3
stage proposal

A write proposal records target rows, evidence lookup records, reason codes, and the proposed diff.

4
preview diff

Reviewers inspect row-level changes, evidence, and proposal metadata before production-visible state changes.

5
green auto-merge

For Synapsor-native targets, a green settlement policy can auto-approve, auto-commit, and auto-merge.

6
review hold

Yellow, red, ambiguous, or conflicting proposals remain staged for human approval or rejection.

7
audit

The branch/proposal/evidence history remains inspectable after merge, rejection, or cleanup.

Developer notes

  • Run destructive cleanup on a branch first.
  • Review diffs before merging to main.
  • Allow auto-merge only through deterministic settlement policies with explicit AUTO COMMIT and AUTO MERGE.
  • Use Synapsor review branch language for external Postgres/MySQL proposals; do not claim Synapsor branches or merges the external database.
  • Keep non-approved proposal branches staged until a reviewer decides.
  • Drop abandoned branches to release quota.
  • Keep branch switching unavailable to database-scoped app keys.