@synapsor/runner 1.1.1 → 1.4.0

package/docs/README.md

@@ -45,6 +45,14 @@ no-database demo, wire your database, then read deeper concepts.
   links to the canonical own-database guide.
 - [Doctor](doctor.md): redacted setup checks, handler probes, direct SQL
   writeback probes, and receipt-table guidance.
+- [Guarded Single-Row CRUD Writeback](guarded-crud-writeback.md): native
+  INSERT/UPDATE/DELETE, receipt modes, crash semantics, privileges, and
+  reconciliation.
+- [Bounded Set Writeback](bounded-set-writeback.md): fixed-predicate set
+  UPDATE/DELETE, exact-review batch INSERT, mandatory caps, atomicity, and
+  exact receipts.
+- [Reviewed Reversible Change Sets](reversible-change-sets.md): opt-in bounded
+  inverse capture and the separate operator proposal/approval/apply flow.
 
 ## 05 Generate Capabilities
 
@@ -89,6 +97,11 @@ no-database demo, wire your database, then read deeper concepts.
 
 - [Result Envelope v2](result-envelope-v2.md): stable
   `ok`/`summary`/`data`/`proposal`/`error` MCP tool results.
+- [Result Envelope v3](result-envelope-v3.md): frozen-set jobs and receipts
+  with every bounded member identity and safe digest.
+- [Compensation Protocol v4](result-envelope-v4.md): reviewed inverse
+  descriptors, compensation proposals/jobs/receipts, lineage, and
+  reconciliation semantics.
 - [Store Lifecycle](store-lifecycle.md): active-store leases, prune safety,
   deleted-store behavior, and concurrent server guardrails.
 - `synapsor-runner activity search`, `evidence`, `query-audit`, `receipts`,
@@ -130,7 +143,10 @@ no-database demo, wire your database, then read deeper concepts.
 - RFC source context:
   [001 result envelope](rfcs/001-result-envelope-v2.md),
   [002 handler helper](rfcs/002-app-owned-handler-helper.md),
-  [003 integrator teardown](rfcs/003-integrator-feedback-teardown.md).
+  [003 integrator teardown](rfcs/003-integrator-feedback-teardown.md),
+  [004 guarded CRUD and receipt authority](rfcs/004-guarded-crud-receipt-authority.md),
+  [005 bounded set writeback](rfcs/005-bounded-set-writeback.md), and
+  [006 reviewed reversible change sets](rfcs/006-reviewed-reversible-change-sets.md).
 
 The public docs intentionally stay task-first. Historical implementation
 reports, release checklists, and internal planning notes are not part of the
@@ -144,8 +160,8 @@ getting-started path.
   database.
 - Writeback: execution of an approved proposal outside the model-facing MCP
   surface.
-- Executor: Runner's guarded one-row updater or an app-owned handler for richer
-  approved business transactions.
+- Executor: Runner's guarded one-row/bounded-set database adapter or an
+  app-owned handler for richer approved business transactions.
 
 ## Repository Map
 

package/docs/capability-authoring.md

@@ -138,6 +138,7 @@ reviewed runner JSON capabilities. Current parity:
 | proposal `approval` | `APPROVAL ROLE billing_lead` | 0.1 | Local mode records the required role; enforcement is still outside the model-facing MCP tool. |
 | proposal `approval.required_approvals` | `REQUIRE 2 APPROVALS` | 1.1 | Optional 1..10 distinct-reviewer quorum; defaults to 1. |
 | proposal `writeback` | `WRITEBACK DIRECT SQL`, `WRITEBACK APP HANDLER EXECUTOR name`, `WRITEBACK CLOUD WORKER`, `WRITEBACK NONE` | 0.1.7 | Handler URLs/tokens stay in `synapsor.runner.json`; contracts carry only the handler name. |
+| proposal `reversibility` | `REVERSIBLE` | 1.4 | Direct SQL only. Captures a bounded inverse after unambiguous apply; operator `revert` creates a new independently approved proposal. |
 | evidence options | `REQUIRE EVIDENCE` | 0.1 | Detailed evidence sources/handle prefixes are not expressible in DSL yet; use embedded JSON or generated contract JSON for those. |
 
 ## Direct Runner Config Path
@@ -319,7 +320,11 @@ Runner rejects model-facing trust-scope arguments.
 
 ## Direct SQL Writeback
 
-Use direct SQL writeback only for simple bounded single-row `UPDATE` proposals.
+Use direct SQL writeback for reviewed guarded single-row INSERT, UPDATE, or
+DELETE proposals. Version 1.3 also supports the narrower [bounded set
+form](bounded-set-writeback.md): fixed-predicate UPDATE/DELETE or complete-item
+batch INSERT with mandatory row/value caps, a frozen exact set, human approval,
+atomic apply, and exact receipts.
 Runner validates:
 
 - fixed table and column names;
@@ -331,19 +336,26 @@ Runner validates:
 - one affected row;
 - idempotency receipt.
 
-Runner does not expose generic SQL, model-generated SQL, DDL, INSERT, DELETE,
-UPSERT, or multi-row writes.
+INSERT additionally requires a source-unique dedup key. DELETE requires an exact
+version guard and fails closed on widening cascades or write triggers.
+
+Runner does not expose generic/model-generated SQL, DDL, UPSERT, a model-chosen
+predicate, unbounded writes, or cross-table transactions. Set writes that
+cannot meet every bounded-set invariant stay on the app-owned executor path.
 
 Direct SQL writeback uses the source `write_url_env`, such as
-`SYNAPSOR_DATABASE_WRITE_URL`. The writer needs permission for
-`synapsor_writeback_receipts` or an administrator must pre-create and grant that
-table.
+`SYNAPSOR_DATABASE_WRITE_URL`. Select atomic `source_db` receipts (precreated or
+auto-migrated) or zero-source-schema `runner_ledger` receipts. Ledger authority
+has an explicit post-source-commit crash window and reconciliation workflow; it
+is not distributed exactly-once. See
+[Guarded Single-Row CRUD Writeback](guarded-crud-writeback.md).
 
 ## App-Owned Executors
 
 Use an app-owned executor when an approved proposal needs richer business work:
-creating a credit row, inserting an outbox event, updating multiple app tables,
-or calling your own service.
+inserting an outbox event, updating multiple app tables, calling your own
+service, or creating a row whose source constraints cannot satisfy native
+single-row INSERT guards.
 
 In DSL, keep the reviewed business contract portable and name the executor:
 

package/docs/conformance.md

@@ -29,12 +29,24 @@ Current fixture groups:
 - `auto-approval`
 - `aggregate-policy-limits`
 - `numeric-bounds`
+- `bounded-set-threats`
+- `reversible-change-sets`
 
 The fixture set is intentionally small in 0.1. It covers the runner-supported
 semantic surface first: trusted context, scoped reads, evidence handles,
 proposal boundaries, kept-out fields, manual approval, and replay envelopes.
 The aggregate-policy fixture additionally proves that reviewed daily ceilings
 fall back to human review atomically and record the limit that tripped.
+The bounded-set fixture maps threats R1-R7 to executable expectations: fixed
+selection, count/value caps, frozen-version drift checks, atomic rollback,
+exact receipts, hard-delete side-effect refusal, and human approval. Adapter
+tests and `corepack pnpm test:bounded-set` complete the live PostgreSQL/MySQL
+matrix.
+The reversible-change-set fixture proves that undo is a new reviewed
+compensation proposal, not rollback: apply-time receipts capture only
+allowlisted inverse data, compensation uses fresh guards and exact members,
+ambiguous outcomes fail closed pending reconciliation, and hard delete reports
+a specific best-effort-unavailable reason.
 
 Additional 0.1 parity coverage currently lives in tests and verification
 scripts rather than separate `cloud-push/` or `dsl-json-parity/` conformance

package/docs/current-scope.md

@@ -2,13 +2,19 @@
 
 The canonical scope page is [Current Limitations](limitations.md).
 
-Current `1.1` scope:
+Current `1.4` scope:
 
 - local semantic MCP tools for Postgres/MySQL-backed business actions;
 - schema inspection and guided config generation;
 - trusted context from environment/session values;
 - evidence handles, query audit, proposals, receipts, and local replay;
-- guarded single-row `UPDATE` writeback for simple edits;
+- guarded single-row `INSERT`, `UPDATE`, and `DELETE` writeback with explicit
+  receipt authority;
+- fixed-predicate set `UPDATE`/`DELETE` and exact-review batch `INSERT`, with
+  mandatory row/value caps, frozen members, human approval, atomic execution,
+  and protocol-v3 exact receipts;
+- opt-in reviewed compensation for direct SQL UPDATE, INSERT, soft-delete, and
+  exact frozen sets, using a separate operator proposal and protocol-v4 receipt;
 - app-owned `http_handler` and `command_handler` executors for richer approved
   business transactions;
 - stdio MCP, Streamable HTTP MCP, and a small JSON-RPC bridge.
@@ -25,9 +31,11 @@ Out of scope:
 
 - raw `execute_sql`;
 - model-generated SQL;
-- generic INSERT/DELETE/UPSERT/DDL;
-- generic multi-row SQL writeback;
+- UPSERT, DDL, model-generated predicates, or unguarded INSERT/DELETE;
+- model-generated, unbounded, or cross-table set writeback;
 - physical branching of external Postgres/MySQL;
+- automatic rollback/time travel and inferred compensation for app-owned or
+  external effects;
 - self-hosted Synapsor Cloud;
 - unbounded or multi-region shared-ledger scale and a managed Runner fleet;
 - production SLA or compliance certification.

package/docs/doctor.md

@@ -44,8 +44,9 @@ Idempotency-Key
 
 ## Direct SQL Writeback Checks
 
-For direct `sql_update` writeback, add `--check-writeback` only after reviewing
-the receipt-table DDL/grants:
+For direct guarded single-row CRUD or bounded-set writeback, add
+`--check-writeback` after reviewing the selected receipt mode and
+operation-specific grants:
 
 ```bash
 synapsor-runner doctor --config synapsor.runner.json --check-writeback
@@ -55,17 +56,23 @@ This connects with the trusted writer env var named by `write_url_env` and
 checks:
 
 - writer database connectivity;
-- `synapsor_writeback_receipts` permission through the adapter doctor;
+- source receipt migration/permissions when authority is `source_db`;
+- no source receipt DDL/DML when authority is `runner_ledger`;
 - rollback-only access to each configured proposal target table;
-- rollback-only update permission for configured allowed write columns.
+- operation-specific version, unique/dedup, generated-column, trigger,
+  cascade, RLS, and DML prerequisites.
+
+For bounded sets, the normal doctor report also identifies operation kind,
+fixed selection or exact batch source, row cap, aggregate bounds, and the
+mandatory human/operator approval boundary. It fails validation before any
+proposal exists when those portable guards are incomplete.
 
 The target-table probe uses fixed schema/table/column identifiers from the
 reviewed config. It does not accept model SQL, user SQL, arbitrary table names,
 or arbitrary column names. It runs inside a transaction and rolls back.
 
-An administrator must pre-create `synapsor_writeback_receipts` and grant the
-steady-state writer access. The doctor probe does not execute DDL or require
-schema `CREATE`:
+For `source_db` + `precreated`, an administrator creates the receipt table and
+grants steady-state access. Doctor never executes DDL in this mode:
 
 ```bash
 synapsor-runner writeback migration --engine postgres --schema synapsor
@@ -79,6 +86,13 @@ synapsor-runner writeback migration --engine mysql --schema appdb
 synapsor-runner writeback grants --engine mysql --schema appdb --writer-role "'app_writer'@'%'"
 ```
 
+Use `source_db` + `auto_migrate` only when the writer may create the fixed
+receipt table. Use `runner_ledger` for no source receipt table; doctor then
+checks the local/small-fleet topology and crash-reconciliation prerequisites.
+See [Guarded Single-Row CRUD Writeback](guarded-crud-writeback.md).
+For set-specific prerequisites, see [Bounded Set
+Writeback](bounded-set-writeback.md).
+
 Use an app-owned `http_handler` or `command_handler` executor when your
 application should own richer business writes or receipt storage.
 

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.