@synapsor/runner 1.1.1 → 1.4.1

package/docs/dsl-reference.md

@@ -98,15 +98,16 @@ different capability design.
 `ALLOW READ` is required and becomes the visible-field allowlist. `KEEP OUT`
 records fields that must remain outside the model/evidence surface. Keep-out
 fields must not also be visible. `REQUIRE EVIDENCE` records the scoped read and
-query audit. `MAX ROWS n` bounds the result; local 0.1 capabilities are designed
-around one primary-key row.
+query audit. For ordinary read/single-row proposal capabilities, `MAX ROWS 1`
+keeps primary-key lookup exact. Bounded set proposals use the separate guarded
+form below.
 
 ## Proposal and patch
 
 Read capabilities end after the read clauses. A proposal capability adds:
 
 ```sql
-  PROPOSE ACTION waive_late_fee
+  PROPOSE ACTION waive_late_fee UPDATE
   ALLOW WRITE late_fee_cents, waiver_reason
   PATCH late_fee_cents = 0
   PATCH waiver_reason = ARG reason
@@ -115,7 +116,8 @@ Read capabilities end after the read clauses. A proposal capability adds:
   PATCH obsolete_note = NULL
 ```
 
-`PROPOSE ACTION` must precede proposal-only clauses. `ALLOW WRITE` is the exact
+`PROPOSE ACTION name [UPDATE|INSERT|DELETE]` must precede proposal-only clauses.
+The operation defaults to `UPDATE` for compatibility. `ALLOW WRITE` is the exact
 patch-column allowlist. Each `PATCH` uses one of:
 
 - `ARG name`: value comes from a validated model argument;
@@ -126,6 +128,78 @@ patch-column allowlist. Each `PATCH` uses one of:
 Fixed strings such as `PATCH status = 'approved'` are supported. The patch is
 saved as a proposal; it is not executed by the model-facing tool.
 
+`INSERT` requires a source-enforced deduplication identity:
+
+```sql
+  PROPOSE ACTION create_credit INSERT
+  DEDUP KEY tenant_id = TRUSTED TENANT, request_id = PROPOSAL ID
+  ALLOW WRITE customer_id, amount_cents
+  PATCH customer_id = ARG customer_id
+  PATCH amount_cents = ARG amount_cents
+```
+
+Dedup components are `column = TRUSTED TENANT`, `column = PROPOSAL ID`, or
+`column = FIXED value`. The key must include both trusted tenant and proposal
+identity and must map to an inspected source primary/unique constraint.
+
+`DELETE` contains no `ALLOW WRITE` or `PATCH`, requires `CONFLICT GUARD`, and
+cannot use `AUTO APPROVE`. Hard delete always requires human/operator review.
+
+Runner-ledger UPDATE must explicitly advance its exact conflict guard:
+
+```sql
+  ADVANCE VERSION version USING INTEGER INCREMENT
+  ADVANCE VERSION updated_at USING DATABASE GENERATED
+```
+
+Use one strategy, and make its column match `CONFLICT GUARD`.
+
+## Bounded set proposals
+
+Add `SET` after the operation to opt into the bounded set model. Existing-row
+UPDATE/DELETE requires a contract-fixed selection, mandatory row and aggregate
+bounds, exact version guards, and human/operator approval:
+
+```sql
+  PROPOSE ACTION close_overdue UPDATE SET
+  SELECT WHERE status = 'overdue'
+  MAX ROWS 10
+  MAX TOTAL balance_cents BEFORE 50000
+  ALLOW WRITE status
+  PATCH status = 'closed'
+  ADVANCE VERSION version USING INTEGER INCREMENT
+  APPROVAL ROLE billing_reviewer
+  WRITEBACK DIRECT SQL
+```
+
+`SELECT WHERE` accepts one or more literal equality terms joined by `AND`.
+Columns, operators, values, ordering, ranges, and raw SQL cannot come from a
+model argument. Runner reads `MAX ROWS + 1` and rejects overflow rather than
+truncating. `MAX TOTAL column BEFORE|AFTER|ABSOLUTE DELTA maximum` is a
+reviewer-visible aggregate value bound.
+
+Batch INSERT takes a complete typed item array:
+
+```sql
+  ARG items ROWS MAX 10 REQUIRED
+  ITEM FIELD items.id STRING REQUIRED MAX LENGTH 128
+  ITEM FIELD items.amount_cents NUMBER REQUIRED MIN 1 MAX 2500
+  PROPOSE ACTION create_credits INSERT SET
+  BATCH ITEMS FROM ARG items
+  MAX ROWS 10
+  MAX TOTAL amount_cents AFTER 25000
+  DEDUP KEY tenant_id = TRUSTED TENANT, id = ITEM id
+  ALLOW WRITE amount_cents
+  PATCH amount_cents = ITEM amount_cents
+  APPROVAL ROLE billing_reviewer
+  WRITEBACK DIRECT SQL
+```
+
+The first release caps every set at 100 members and forbids `AUTO APPROVE`.
+Set hard DELETE is trigger/cascade checked and soft delete is preferred. See
+[Bounded Set Writeback](bounded-set-writeback.md) for transaction, receipt,
+reconciliation, and executor boundaries.
+
 ## Bounds and transitions
 
 ```sql
@@ -189,11 +263,20 @@ Writeback forms:
 
 | Clause | Meaning |
 | --- | --- |
-| `WRITEBACK DIRECT SQL` | Runner performs one guarded single-row update after approval. |
+| `WRITEBACK DIRECT SQL` | Runner performs one guarded single-row INSERT, UPDATE, or DELETE after approval. Runtime receipt authority stays in `synapsor.runner.json`. |
 | `WRITEBACK APP HANDLER EXECUTOR name` | Runner calls a configured app-owned executor after approval. URL/token wiring stays outside the contract. |
 | `WRITEBACK CLOUD WORKER` | Delegates approved execution to Cloud worker infrastructure. |
 | `WRITEBACK NONE` | Proposal-only; local apply is intentionally unavailable. |
 
+`REVERSIBLE` opts a direct SQL proposal into reviewed inverse capture. It does
+not add an MCP tool or automatic rollback. UPDATE requires an exact conflict
+guard and `ADVANCE VERSION ... USING INTEGER INCREMENT`; INSERT requires a
+deterministic primary-key dedup component; policy auto-approval and app-owned
+handlers are rejected. After an unambiguous apply, an operator may run
+`synapsor-runner revert <proposal_id>` to create a separately reviewed
+compensation proposal. See [Reviewed Reversible Change
+Sets](reversible-change-sets.md).
+
 ## Workflow declarations
 
 ```sql
@@ -218,5 +301,8 @@ Unknown clauses fail instead of being ignored. Cloud-generated concepts such as
 `ROOT EXTERNAL`, `JOIN EXTERNAL`, `RETURN ANSWER WITH CITATIONS`, `AUTO BRANCH`,
 and `AUTO MERGE` are not local DSL 0.1 clauses.
 
+Bounded multi-row direct writes and reversible change sets are not part of the
+1.2 DSL. Use an app-owned executor until their separate safety gates ship.
+
 The canonical JSON output, not parser implementation details, is the portable
 contract. Validate generated JSON with `synapsor-runner contract validate`.

package/docs/getting-started-own-database.md

@@ -3,9 +3,9 @@
 Use this path after the Docker demo passes and you want to try Synapsor Runner
 against a staging or disposable Postgres/MySQL database.
 
-Do not start with your most sensitive production database. The current alpha
-runner is a local commit-safety runtime for reviewed single-row business
-actions, not a production certification.
+Do not start with your most sensitive production database. Runner is a
+commit-safety runtime for reviewed single-row business actions, not a
+production certification.
 
 If you only ran `synapsor-runner demo --quick`, you have tested the fixture-only
 teaching path and local ledger commands. This page is the real own-database
@@ -170,6 +170,8 @@ The wizard:
   mode, semantic capability names, and proposal patch mappings;
 - asks review-mode users to choose direct guarded SQL writeback, an app-owned
   HTTP handler, or an app-owned command handler;
+- for direct SQL, asks for UPDATE/INSERT/DELETE and source receipt
+  auto-migrate, precreated receipt, or zero-source-schema Runner-ledger mode;
 - previews the MCP tools and what is not exposed, then lets you revise visible
   fields or capability names before writing files;
 - attempts a first smoke call when you supplied a real object id and the
@@ -238,6 +240,27 @@ writeback is disabled.
 Use `--writeback command_handler --handler-command-env APP_WRITEBACK_COMMAND`
 when your app-owned writer is a local command/script instead of HTTP.
 
+For native single-row CRUD, use operation-aware onboarding. INSERT requires a
+source primary/unique dedup key; DELETE requires an exact conflict guard and
+safe cascade/trigger inspection:
+
+```bash
+npx -y -p @synapsor/runner synapsor-runner onboard db \
+  --from-env DATABASE_URL \
+  --table account_credits \
+  --mode review \
+  --operation insert \
+  --dedup-columns request_id \
+  --receipt-mode runner_ledger \
+  --patch amount_cents=arg:amount_cents \
+  --write-url-env SYNAPSOR_DATABASE_WRITE_URL \
+  --yes
+```
+
+Review [Guarded Single-Row CRUD Writeback](guarded-crud-writeback.md) before
+choosing receipt authority. Runner-ledger mode creates no source receipt table,
+but ambiguous post-commit crashes stop for operator reconciliation.
+
 Or generate from a saved inspection snapshot without reconnecting:
 
 ```bash

package/docs/guarded-crud-writeback.md

@@ -0,0 +1,218 @@
+# Guarded Single-Row CRUD Writeback
+
+Synapsor Runner can apply reviewed, approved, single-row `INSERT`, `UPDATE`,
+and `DELETE` operations to Postgres and MySQL. The model only creates a
+proposal. Approval and apply remain outside MCP.
+
+This is not a general SQL surface. Every direct operation is generated from a
+validated contract and must preserve these invariants:
+
+- fixed schema, table, primary key, tenant key, and columns;
+- tenant supplied by trusted context, never by the model;
+- parameterized values and no model-generated SQL or predicates;
+- one reviewed row and exactly one source effect;
+- source-enforced conflict or deduplication guard;
+- approval before apply;
+- durable intent, receipt, events, and replay;
+- ambiguous outcomes fail closed for operator reconciliation.
+
+Use [bounded set writeback](bounded-set-writeback.md) only when a fixed
+predicate or complete reviewed item list can satisfy its stronger caps,
+freezing, atomicity, and receipt rules. Use an [app-owned
+executor](writeback-executors.md) for free-form/unbounded multi-row or
+multi-table transactions, UPSERT, DDL, external effects, or business logic that
+does not fit either direct boundary.
+
+## Operation guarantees
+
+| Operation | Required source guard | Direct-write behavior |
+| --- | --- | --- |
+| `UPDATE` | Primary key, trusted tenant, exact version/conflict column | Patches only allowlisted columns and affects exactly one row. In Runner-ledger mode, the version must advance in the same source transaction. |
+| `INSERT` | Source `PRIMARY KEY` or `UNIQUE` constraint over the reviewed dedup identity | Runner injects tenant and proposal-derived identity values, inserts only allowlisted fields, and requires exactly one row. |
+| `DELETE` | Primary key, trusted tenant, exact version column | Deletes exactly one reviewed row. Hard delete requires human/operator approval and is refused when Runner detects write triggers or widening cascades. Prefer soft delete as guarded `UPDATE`. |
+
+Existing proposal capabilities with no `operation` field continue to mean
+single-row `UPDATE`.
+
+## Receipt authority
+
+Receipt authority and source-table provisioning are separate decisions:
+
+| Authority | Provisioning | Source schema change | Completion classification |
+| --- | --- | --- | --- |
+| `source_db` | `precreated` | Administrator creates the fixed receipt table; Runner never runs DDL. | Mutation and receipt commit in one source transaction. Strongest already-applied versus conflict classification. |
+| `source_db` | `auto_migrate` | Runner runs an idempotent, reviewed receipt-table migration. Writer needs bounded `CREATE` permission. | Same atomic source transaction after migration. |
+| `runner_ledger` | Not applicable | No Synapsor receipt table or receipt DML in the source database. | Durable Runner intent precedes the source transaction. A crash after source commit but before ledger completion may require reconciliation. |
+
+`runner_ledger` does not claim distributed exactly-once semantics across two
+databases. Source-enforced versions and unique keys prevent a known duplicate
+effect. If Runner cannot prove whether an interrupted attempt committed, it
+records `reconciliation_required`, stops automatic retry, and preserves the
+intent for an operator.
+
+Local SQLite is valid for one local operator process. A networked or
+multi-Runner deployment using `runner_ledger` requires
+`storage.shared_postgres.mode = "runtime_store"` so the intent ledger is
+authoritative before any source mutation. Mirror mode is rejected.
+
+## Runtime configuration
+
+Atomic source receipts with an administrator-created table:
+
+```json
+{
+  "sources": {
+    "billing_postgres": {
+      "engine": "postgres",
+      "read_url_env": "BILLING_POSTGRES_READ_URL",
+      "write_url_env": "BILLING_POSTGRES_WRITE_URL",
+      "receipts": {
+        "authority": "source_db",
+        "provisioning": "precreated",
+        "schema": "synapsor",
+        "table": "writeback_receipts"
+      }
+    }
+  }
+}
+```
+
+Set `provisioning` to `auto_migrate` to let Runner create that fixed table.
+Use Runner-ledger authority with no source receipt fields:
+
+```json
+{
+  "sources": {
+    "billing_postgres": {
+      "engine": "postgres",
+      "read_url_env": "BILLING_POSTGRES_READ_URL",
+      "write_url_env": "BILLING_POSTGRES_WRITE_URL",
+      "receipts": { "authority": "runner_ledger" }
+    }
+  }
+}
+```
+
+Receipt schema and table names are fixed, validated runtime identifiers. They
+are not portable contract fields or model arguments.
+
+## Contract and DSL examples
+
+Runner-ledger `UPDATE` must advance its exact guard:
+
+```sql
+PROPOSE ACTION waive_late_fee UPDATE
+ALLOW WRITE late_fee_cents, waiver_reason
+PATCH late_fee_cents = 0
+PATCH waiver_reason = ARG reason
+ADVANCE VERSION version USING INTEGER INCREMENT
+APPROVAL ROLE billing_reviewer
+WRITEBACK DIRECT SQL
+```
+
+Guarded `INSERT` needs a source-unique, Runner-supplied dedup identity:
+
+```sql
+PROPOSE ACTION create_credit INSERT
+DEDUP KEY tenant_id = TRUSTED TENANT, request_id = PROPOSAL ID
+ALLOW WRITE customer_id, amount_cents, reason
+PATCH customer_id = ARG customer_id
+PATCH amount_cents = ARG amount_cents
+PATCH reason = ARG reason
+BOUND amount_cents 1..50000
+APPROVAL ROLE support_reviewer
+WRITEBACK DIRECT SQL
+```
+
+The source must enforce the declared dedup columns with a primary key or unique
+constraint. Ledger memory by itself is not an INSERT deduplication guard.
+
+Hard `DELETE` has no patch and cannot use policy auto-approval:
+
+```sql
+PROPOSE ACTION delete_session DELETE
+APPROVAL ROLE security_reviewer
+WRITEBACK DIRECT SQL
+```
+
+The capability still declares `PRIMARY KEY`, `TENANT KEY`, `CONFLICT GUARD`,
+reviewed visible fields, evidence, and `MAX ROWS 1` in its enclosing block.
+
+## Database privileges
+
+Keep read and write credentials separate. The writer needs only the target
+table operations declared by its capabilities plus the selected receipt mode.
+
+| Mode | Postgres writer | MySQL writer |
+| --- | --- | --- |
+| `source_db` + `precreated` | Schema usage, reviewed target `SELECT` and operation-specific `INSERT`/`UPDATE`/`DELETE`, sequence use for identity INSERT, receipt-table `SELECT`/`INSERT`/`UPDATE`; no `CREATE`. | Reviewed target `SELECT` and operation-specific `INSERT`/`UPDATE`/`DELETE`, receipt-table `SELECT`/`INSERT`/`UPDATE`; no `CREATE`. |
+| `source_db` + `auto_migrate` | Same, plus bounded schema `CREATE` for the fixed receipt table. | Same, plus database `CREATE` for the fixed receipt table. |
+| `runner_ledger` | Reviewed target `SELECT` and operation-specific DML only; no source receipt or `CREATE` privilege. | Reviewed target `SELECT` and operation-specific DML only; no source receipt or `CREATE` privilege. |
+
+Hard DELETE requires enough metadata visibility to prove that the effect cannot
+widen. Postgres reads system catalogs. MySQL requires scoped `TRIGGER` metadata
+visibility on the target table and global `PROCESS` visibility for incoming
+InnoDB foreign-key metadata. If those privileges are unacceptable, use a soft
+delete capability or an app-owned executor; Runner fails closed rather than
+claiming an unverified one-row effect.
+
+The same MySQL metadata visibility is required when reviewed compensation may
+delete a row, including reversal of an INSERT. See [Reviewed Reversible Change
+Sets](reversible-change-sets.md). App-owned executors are not automatically
+reversible; they need an application-defined, separately reviewed compensation
+capability.
+
+Generate or inspect source-receipt SQL without exposing credentials:
+
+```bash
+synapsor-runner writeback migration --engine postgres --schema synapsor --table writeback_receipts
+synapsor-runner writeback grants --engine postgres --writer-role app_writer --schema synapsor --table writeback_receipts
+synapsor-runner doctor --config ./synapsor.runner.json --check-writeback
+synapsor-runner tools preview --config ./synapsor.runner.json --store ./.synapsor/local.db
+```
+
+`precreated` uses rollback-only permission probes and never executes `CREATE`.
+`doctor` also checks operation-specific version, unique-key, generated-column,
+trigger, cascade, and topology prerequisites.
+
+## Reconciliation
+
+An incomplete Runner-ledger intent is not proof of success or failure. Inspect
+only the reviewed target projection under the trusted tenant, then record a
+verified operator decision:
+
+```bash
+synapsor-runner writeback reconcile list \
+  --status reconciliation_required \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+
+synapsor-runner writeback reconcile inspect latest \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+
+synapsor-runner writeback reconcile resolve wbi:... \
+  --outcome applied \
+  --reason "verified source state" \
+  --yes \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+```
+
+Resolution appends immutable events and a reconciliation receipt. It does not
+rewrite history or retry the source mutation. Configured production operator
+identity is required when enabled.
+
+## Verification
+
+The repository includes a disposable Postgres/MySQL test that proves every
+receipt mode, native INSERT/UPDATE/DELETE, idempotent retry, stale and tenant
+guards, two-store races, crash boundaries, no source receipt table in
+Runner-ledger mode, and hard-delete trigger/cascade refusal:
+
+```bash
+corepack pnpm test:guarded-crud
+```
+
+Use synthetic staging data first. Run `doctor --check-writeback` and review
+`tools preview` before connecting an MCP client or applying a proposal.

package/docs/limitations.md

@@ -1,7 +1,9 @@
 # Limitations
 
-Synapsor Runner is intentionally narrow. Version 1.1 adds a bounded small-fleet
-shape; it does not claim Synapsor Cloud scale or an enterprise SLA.
+Synapsor Runner is intentionally narrow. Version 1.4 adds opt-in reviewed
+compensation on top of guarded bounded-set writeback, single-row CRUD, and
+explicit receipt authority; it does not claim Synapsor Cloud scale or an
+enterprise SLA.
 
 ## Supported
 
@@ -20,8 +22,20 @@ shape; it does not claim Synapsor Cloud scale or an enterprise SLA.
   - `synapsor.change-set.v1`
   - `synapsor.writeback-job.v1`
   - `synapsor.execution-receipt.v1`
+  - backward-compatible operation-aware v2 change sets, jobs, and receipts
+  - bounded-set v3 change sets, jobs, and receipts
+  - compensation change sets and protocol-v4 jobs/receipts with bounded inverse
+    descriptors
   - `synapsor.runner-registration.v1`
-- Guarded single-row `UPDATE` for Postgres and MySQL.
+- Guarded single-row `INSERT`, `UPDATE`, and `DELETE` for Postgres and MySQL.
+- Fixed-predicate set `UPDATE`/`DELETE` and exact-review batch `INSERT` with
+  mandatory row/value caps, a hard 100-row ceiling, human approval, frozen
+  members, atomic apply, and exact receipts.
+- Opt-in reviewed compensation for direct SQL UPDATE, INSERT, soft-delete, and
+  exact frozen sets. Revert is a new operator proposal with independent
+  approval and a fresh conflict guard.
+- Atomic source receipts with precreated or auto-migrated tables, or
+  zero-source-schema Runner-ledger receipts with explicit reconciliation.
 - App/API handler writeback through approved `http_handler` executors.
 - Local script writeback through approved `command_handler` executors.
 - Primary-key guard.
@@ -49,17 +63,19 @@ truth for the model-facing tools.
 - Arbitrary SQL.
 - Model-generated SQL.
 - DDL.
-- INSERT.
-- DELETE.
 - UPSERT.
-- Multi-row UPDATE.
+- Model-generated/free-form set predicates or dynamic identifiers.
+- Unbounded set writes or more than 100 reviewed members.
+- Policy auto-approval for bounded sets.
 - Stored procedures.
 - Cross-database transactions.
 - Physical branching of Postgres/MySQL.
 - Full Synapsor workflow/DAG execution.
 - `CREATE AGENT WORKFLOW` or hosted Synapsor SQL generation.
 - Auto-merge or settlement policy semantics.
-- Automatic rollback of external database writes.
+- Automatic rollback, database time travel, or model-facing revert.
+- Inferred compensation for app-owned handlers or external effects.
+- General restoration of hard-deleted rows, cascades, or trigger side effects.
 - Model-callable approval or commit tools.
 - Generic MCP firewall behavior.
 - Prompt-injection prevention.
@@ -92,8 +108,9 @@ not a hosted central evidence service, organization RBAC/SSO, compliance
 retention system, or unbounded search engine. Each bridge operation serializes
 through an advisory lock and fails above configured `max_entries`.
 
-Only homogeneous 1.1 fleet operation is currently verified. Mixed 1.0/1.1
-rolling operation is not claimed. See [Running A Small Runner
+Only homogeneous 1.4 fleet operation is claimed for protocol-v4 compensation
+jobs. Mixed-minor v3/v4 rolling compensation is not claimed.
+See [Running A Small Runner
 Fleet](running-a-runner-fleet.md).
 
 Use this wording:
@@ -108,3 +125,7 @@ Do not describe external approval as merge.
 ## Weak Conflict Guards
 
 A version/timestamp column is the preferred conflict guard. A weak row-hash guard can be acknowledged for local/dev use, but it should not be presented as equivalent to a durable version column.
+
+Runner-ledger UPDATE and DELETE require an exact guard; UPDATE must advance it
+inside the source transaction. INSERT requires a reviewed source-unique dedup
+identity. See [Guarded Single-Row CRUD Writeback](guarded-crud-writeback.md).

package/docs/oss-vs-cloud.md

@@ -21,7 +21,7 @@ and investigation surfaces for enabled design-partner deployments.
 | Capabilities | Local semantic MCP tools | Registry, version history, and capability inspection |
 | Evidence and replay | Local SQLite ledger by default; optional shared Postgres runtime store | Shared activity and evidence surfaces where enabled |
 | Approval | Local CLI or localhost UI | Team approval surfaces where enabled |
-| Writeback | Guarded one-row update or app-owned executor | Cloud-linked jobs with local execution; managed production orchestration is future work |
+| Writeback | Guarded one-row CRUD, fixed/frozen bounded sets, or app-owned executor | Cloud-linked jobs with local execution; managed production orchestration is future work |
 | MCP risk audit | Static local audit | Organization-wide continuous audit is future work |
 | Identity | Local operator boundary | Workspace RBAC where configured; SAML and SCIM are future work |
 | Operations | Customer-operated single node or bounded small fleet | Managed fleet remains Cloud work; no enterprise SLA in the current beta |

package/docs/production.md

@@ -10,7 +10,7 @@ MCP agent
 -> scoped Postgres/MySQL read
 -> evidence/query audit/proposal
 -> approval outside MCP
--> guarded one-row update or app-owned executor
+-> guarded one-row CRUD, bounded frozen set, or app-owned executor
 -> receipt/replay
 ```
 
@@ -58,7 +58,14 @@ Production-candidate OSS scope:
 - asymmetric RS256/ES256 session authentication, readiness probes, separately
   protected metrics, source pools, and fleet-wide rate limits;
 - distinct-reviewer approval quorum from the canonical contract;
-- direct guarded single-row `UPDATE` for simple approved edits;
+- direct guarded single-row `INSERT`, `UPDATE`, and `DELETE` for approved
+  operations whose source constraints satisfy the operation-specific guards;
+- fixed-predicate set `UPDATE`/`DELETE` and exact-review batch `INSERT`, with
+  human approval, mandatory row/value caps, a hard 100-row ceiling, frozen
+  members, atomic execution, and exact per-member receipts;
+- opt-in reviewed compensation for direct SQL UPDATE, INSERT, soft-delete, and
+  exact frozen sets, using a separate operator proposal, fresh guards, and
+  protocol-v4 receipts;
 - app-owned `http_handler` or `command_handler` executors for richer approved
   business transactions;
 - stdio MCP and Streamable HTTP MCP.
@@ -66,8 +73,12 @@ Production-candidate OSS scope:
 Out of scope:
 
 - raw `execute_sql` or model-generated SQL;
-- generic direct `INSERT`, `DELETE`, `UPSERT`, DDL, or multi-row SQL writeback;
+- direct `UPSERT`, DDL, model-generated predicates, unbounded set writes,
+  cross-table transactions, or INSERT/DELETE whose source constraints cannot
+  prove the reviewed effect;
 - physical branching of external Postgres/MySQL;
+- automatic rollback/time travel, hard-delete restoration, and inferred
+  compensation for app-owned or external effects;
 - workflow DAGs, auto-merge/settlement, hosted team administration, SSO/SCIM,
   multi-region ledger replication, or compliance retention;
 - making prompt injection impossible.
@@ -85,11 +96,12 @@ Read credential:
 
 Write credential for direct `sql_update`:
 
-- can update only the allowed business columns;
+- can use only the operation-specific business DML and reviewed columns;
 - cannot modify primary-key or tenant columns;
-- can `SELECT`/`INSERT`/`UPDATE` the administrator-created
-  `synapsor_writeback_receipts` table;
-- does not need schema `CREATE` during doctor or apply;
+- has source receipt-table `SELECT`/`INSERT`/`UPDATE` only when receipt
+  authority is `source_db`;
+- needs schema `CREATE` only for explicitly selected `auto_migrate` receipt
+  provisioning;
 - is never exposed to MCP clients.
 
 Example config:
@@ -110,10 +122,17 @@ Example config:
 `write_url_env`. `SYNAPSOR_DATABASE_URL` is only a legacy fallback for direct
 worker flows that do not pass a local config.
 
-## Receipt Table
+Set `statement_timeout_ms` on each production source. PostgreSQL direct
+writeback uses it for transaction-local statement and lock limits. MySQL uses
+it for preflight execution and InnoDB lock waits; because MySQL does not apply
+`max_execution_time` to general DML, keep bounded sets small and enforce
+source-side operational query limits too.
 
-Direct SQL writeback stores idempotency receipts in the source database. Runner
-expects an administrator to create this table before steady-state operation:
+## Receipt Authority
+
+Direct SQL writeback supports atomic `source_db` receipts and
+zero-source-schema `runner_ledger` receipts. For source receipts, choose an
+administrator-precreated table or explicit idempotent auto-migration:
 
 ```sql
 CREATE TABLE IF NOT EXISTS synapsor_writeback_receipts (...);
@@ -129,26 +148,36 @@ synapsor-runner doctor --config synapsor.runner.json --check-writeback
 
 For MySQL, replace `postgres` with `mysql`.
 
-Grant only receipt-table `SELECT`/`INSERT`/`UPDATE` and schema usage to the
-writer; schema `CREATE` is not required by doctor or apply. Use an app-owned
-executor when receipt storage belongs inside your application boundary.
+Grant only receipt-table `SELECT`/`INSERT`/`UPDATE` and schema usage in
+`precreated` mode. `auto_migrate` additionally needs bounded `CREATE`.
+`runner_ledger` needs neither source receipt-table grants nor `CREATE`, but an
+ambiguous crash after source commit requires operator reconciliation and is not
+distributed exactly-once. See
+[Guarded Single-Row CRUD Writeback](guarded-crud-writeback.md) for the complete
+mode, operation, and privilege matrix.
 
 ## Direct Writeback Vs App-Owned Executor
 
-Use direct `sql_update` when the approved change is:
+Use direct writeback when the approved change is either:
 
 ```text
-one existing row -> one allowed-column patch -> one guarded UPDATE
+one reviewed row -> one guarded INSERT/UPDATE/DELETE -> one exact effect
+
+or
+
+one fixed reviewed rule/item list -> <= 100 frozen rows -> one atomic bounded set
 ```
 
 Use an app-owned executor when the change is richer:
 
-- insert a credit/refund/review row;
-- update more than one row;
+- choose rows from a model-supplied predicate or exceed the reviewed cap;
 - touch more than one table;
 - emit an event or call another internal service;
 - enforce business logic that belongs in your app.
 
+Bounded sets must satisfy every invariant in [Bounded Set
+Writeback](bounded-set-writeback.md); otherwise they remain executor work.
+
 Handlers must re-check tenant/scope, expected version, idempotency, allowed
 business action, transaction boundaries, and safe errors. See
 [Writeback Executors](writeback-executors.md) and
@@ -336,9 +365,12 @@ synapsor-runner apply --all-approved --yes \
 ```
 
 Each proposal is independent: a stale-row conflict does not abort later jobs.
-The final summary reports applied, conflict, and skipped IDs. Re-running is
-idempotent through durable receipts. Do not schedule batch apply for a policy
-that has no reviewed aggregate limits.
+In `runtime_store` mode, the batch holds one authoritative bridge while every
+selected item applies, then syncs the resulting states, receipts, and events
+back together. The final summary reports applied, conflict, and skipped IDs;
+every skipped item includes a safe reason. Re-running is idempotent through
+durable receipts. Do not schedule batch apply for a policy that has no reviewed
+aggregate limits.
 
 Runner writes newline-delimited JSON events to stderr for model-facing tool
 rejections, operator decisions, and terminal writeback outcomes. These events