Overview
A capability names what the agent can do.
ARG declarations name caller-provided values. HIDDEN declarations read trusted SESSION values. The caller can choose ARG values, but cannot choose HIDDEN tenant/principal/current-object scope unless your backend sets those session values.
Read-only capabilities can answer or classify without mutating state, and their contexts can include hybrid search steps for policy, memory, or evidence retrieval. Developers do not need to pull external model embeddings into app code to use the documented hybrid-search path.
PROPOSAL capabilities are write proposal actions: the agent or app calls one approved capability, and Synapsor stages the write as a proposal instead of letting the agent mutate production directly.
Proposal target determines branch behavior. If the proposal target is a Synapsor-native table, auto_branch stages the write on a real Synapsor branch. If the proposal target references an external Postgres/MySQL mapping, auto_branch stages a Synapsor review branch with the proposed external row update and trusted writeback intent.
When an HTTP or SDK proposal-capable invocation uses auto_branch, the caller receives compact Synapsor-produced ids for the branch/review branch, proposal, evidence bundle, and replay record.
Applications can request auto_branch at invocation time. Capabilities that should auto-merge policy-approved results by default do that with SQL-authored settlement policy attached to the capability, not by trusting the app or prompt.
Production-visible changes happen only after a human approval path or deterministic settlement policy. Synapsor-native targets can merge into Synapsor main; external Postgres/MySQL targets can be approved for trusted worker writeback. The model still never receives raw SQL or direct write credentials.
Proposal target determines branch behavior
If the proposal target is a Synapsor-native table, auto_branch stages the write on a real Synapsor branch. If the proposal target references an external Postgres/MySQL mapping, auto_branch stages a Synapsor review branch with the proposed external row update and trusted writeback intent.
The app should display external source proposals as reviewable row diffs, not as writes already applied to Postgres/MySQL.
Capability-owned auto branch
Auto-branching is part of the proposal-capability runtime path: one capability call creates the branch, proposal, evidence, and replay records.
Production-visible state is untouched while the capability runs.
The app or agent framework invokes a reviewed EXECUTION PROPOSAL capability.
Tenant, principal, current object, and optional branch policy come from SESSION bindings, not the prompt.
Synapsor creates an isolated branch for this invocation when auto_branch is enabled on the HTTP or SDK call.
The capability writes only allowed columns to a wrp:// proposal on that branch.
A reviewer previews the diff, or a deterministic settlement policy handles policy-approved cases.
Only approved/settled proposals merge to main; rejected, canceled, conflicting, or ambiguous proposals stay isolated.
Developer notes
- Default risky HTTP/SDK workflows to EXECUTION PROPOSAL with auto_branch enabled.
- Use SQL settlement policies for default auto-approve, auto-commit, and auto-merge behavior; do not put that authority in app prompts.
- For SQL shell tests, create and use an explicit review branch before proposing.
- Require evidence when output affects customers or money.
- Treat returned branch and wrp:// proposal lookup ids as durable Synapsor workflow state.
- Limit write proposal targets to the exact tables the capability owns.
- Merge auto-branch results only through human approval or deterministic settlement policy.
- Audit capability changes like schema migrations.