@synapsor/runner 1.1.1 → 1.4.1

package/docs/README.md

@@ -24,6 +24,10 @@ no-database demo, wire your database, then read deeper concepts.
 ## 02 Why Raw SQL Is Dangerous
 
 - [Security Boundary](security-boundary.md): what the model can and cannot see.
+- [Why Synapsor Over Prompt And Application
+  Guardrails](why-synapsor-vs-app-guardrails.md): where SQL authority lives,
+  what a hand-built semantic tool already gets right, and when the shared
+  contract, approval, receipt, and replay layer is worth adopting.
 - [MCP Audit](mcp-audit.md): static review for risky database MCP tools such as
   `execute_sql`, broad query tools, model-controlled tenant filters, or
   model-facing approval/commit tools.
@@ -45,6 +49,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 +101,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 +147,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 +164,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/benchmarks/bounded-set-local.md

@@ -0,0 +1,27 @@
+# Bounded Set Local Measurements
+
+These measurements are test evidence, not throughput claims or capacity
+guidance. They record one run of `corepack pnpm test:bounded-set` on 2026-07-13
+using synthetic rows and disposable local Docker databases.
+
+Environment:
+
+- Linux laptop, Intel Core i7-13800H, 20 logical CPUs, 30 GiB RAM;
+- Node.js 22.22.2 and pnpm 10.14.0;
+- Docker 29.5.2;
+- PostgreSQL 16 and MySQL 8 containers;
+- source-database receipt authority with an administrator-precreated receipt
+  table;
+- one sequential set UPDATE per measurement, including connection setup,
+  source receipt, lock/preflight, transaction, and exact receipt generation.
+
+| Engine | 1 row | 10 rows | 100 rows |
+| --- | ---: | ---: | ---: |
+| PostgreSQL | 30.42 ms | 53.88 ms | 154.90 ms |
+| MySQL | 25.30 ms | 53.91 ms | 163.20 ms |
+
+These figures are not portable across hardware, network topology, source
+indexes, lock contention, triggers, database configuration, or receipt mode.
+The claim supported by this gate is only that execution stays bounded and the
+hard 100-row ceiling is exercised on both adapters. Operators must benchmark
+their own reviewed contracts and database topology.

package/docs/bounded-set-writeback.md

@@ -0,0 +1,298 @@
+# Bounded Set Writeback
+
+Synapsor Runner can apply a deliberately narrow class of reviewed
+multi-row database changes to PostgreSQL and MySQL:
+
+- fixed-predicate set `UPDATE`;
+- fixed-predicate set `DELETE`;
+- exact-review batch `INSERT`.
+
+This is not model-generated SQL and it is not a generic batch API. The model
+can ask to run a reviewed business action, but it cannot choose a table,
+column, operator, ordering, predicate, tenant, or unbounded set.
+
+## Safety invariant
+
+The worst action available to a prompt-injected model is to request one
+contract-authored rule, against the trusted tenant, up to the reviewer-authored
+row and value caps. Before approval, Runner freezes the exact ordered members.
+Apply later touches only those members in one transaction and records every
+identity and bounded digest.
+
+Every bounded set requires:
+
+1. a fixed typed selection for existing-row UPDATE/DELETE, or the complete
+   reviewed item array for batch INSERT;
+2. `MAX ROWS n`, where `1 <= n <= 100`;
+3. at least one aggregate `MAX TOTAL` bound;
+4. trusted tenant binding;
+5. exact version guards and integer advancement for set UPDATE;
+6. source-unique per-item identities for batch INSERT;
+7. human/operator approval outside MCP;
+8. one atomic source transaction and an exact affected-row count;
+9. source or Runner-ledger receipts with the documented crash semantics.
+
+A row cap is a rejection threshold, never `LIMIT n` truncation. Proposal reads
+fetch at most `n + 1`; finding the extra row rejects before proposal
+persistence. Aggregate overflow also rejects before persistence.
+
+## DSL examples
+
+Fixed set UPDATE:
+
+```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
+```
+
+The selection is a contract literal. It is not an argument and is never taken
+from the model. The first release supports equality terms joined by `AND`.
+
+Exact-review batch INSERT:
+
+```sql
+ARG items ROWS MAX 10 REQUIRED
+ITEM FIELD items.id STRING REQUIRED MAX LENGTH 128
+ITEM FIELD items.external_id STRING REQUIRED MAX LENGTH 128
+ITEM FIELD items.amount_cents NUMBER REQUIRED MIN 1 MAX 2500
+ITEM FIELD items.reason STRING REQUIRED MAX LENGTH 500
+
+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, external_id = ITEM external_id
+ALLOW WRITE amount_cents, reason
+PATCH amount_cents = ITEM amount_cents
+PATCH reason = ITEM reason
+APPROVAL ROLE billing_reviewer
+WRITEBACK DIRECT SQL
+```
+
+The reviewer sees every allowlisted candidate item before approval. The source
+must enforce the declared identity with a primary or unique constraint.
+
+Set DELETE uses `DELETE SET`, a fixed selection, `MAX ROWS`, `MAX TOTAL`, and
+an exact conflict guard. It has no patch. Runner rejects hard DELETE if it
+cannot prove trigger/FK visibility or detects write triggers or widening
+cascades. Prefer a set UPDATE of `deleted_at` or status when possible.
+
+## Worked contract-to-apply example
+
+This PostgreSQL example closes two overdue tickets. MySQL is supported with
+the same contract semantics; change the source engine and schema/database name
+to match the inspected MySQL object.
+
+Create the fixture with an administrator account, then give the Runner reader
+`SELECT` and its separate writer only `SELECT, UPDATE` on this table:
+
+```sql
+CREATE TABLE public.service_tickets (
+  id bigint PRIMARY KEY,
+  tenant_id text NOT NULL,
+  status text NOT NULL,
+  cost_cents integer NOT NULL,
+  version integer NOT NULL
+);
+
+INSERT INTO public.service_tickets
+  (id, tenant_id, status, cost_cents, version)
+VALUES
+  (3, 'acme', 'overdue', 8000, 1),
+  (4, 'acme', 'overdue', 15000, 1),
+  (99, 'globex', 'overdue', 49000, 1);
+```
+
+Save this as `tickets.synapsor.sql`:
+
+```sql
+CREATE AGENT CONTEXT local_operator
+  BIND tenant_id FROM ENVIRONMENT SYNAPSOR_TENANT_ID REQUIRED
+  BIND principal FROM ENVIRONMENT SYNAPSOR_PRINCIPAL REQUIRED
+  TENANT BINDING tenant_id
+  PRINCIPAL BINDING principal
+END
+
+CREATE CAPABILITY tickets.close_overdue
+  USING CONTEXT local_operator
+  SOURCE local_db
+  ON public.service_tickets
+  PRIMARY KEY id
+  TENANT KEY tenant_id
+  CONFLICT GUARD version
+  LOOKUP reason BY id
+  ARG reason STRING REQUIRED MAX LENGTH 100
+  ALLOW READ id, tenant_id, status, cost_cents, version
+  REQUIRE EVIDENCE
+  PROPOSE ACTION close_overdue UPDATE SET
+  SELECT WHERE status = 'overdue'
+  MAX ROWS 10
+  MAX TOTAL cost_cents BEFORE 50000
+  ALLOW WRITE status
+  PATCH status = 'closed'
+  ADVANCE VERSION version USING INTEGER INCREMENT
+  APPROVAL ROLE ops_manager
+  WRITEBACK DIRECT SQL
+END
+```
+
+Compile the contract and create `synapsor.runner.json`:
+
+```bash
+synapsor-runner dsl compile ./tickets.synapsor.sql \
+  --out ./synapsor.contract.json --strict
+synapsor-runner contract validate ./synapsor.contract.json
+```
+
+```json
+{
+  "version": 1,
+  "mode": "review",
+  "storage": { "sqlite_path": "./.synapsor/local.db" },
+  "sources": {
+    "local_db": {
+      "engine": "postgres",
+      "read_url_env": "SYNAPSOR_DATABASE_READ_URL",
+      "write_url_env": "SYNAPSOR_DATABASE_WRITE_URL",
+      "statement_timeout_ms": 3000,
+      "receipts": { "authority": "runner_ledger" }
+    }
+  },
+  "contracts": ["./synapsor.contract.json"]
+}
+```
+
+Load database URLs from your shell or secret manager. The config stores only
+environment-variable names. Trusted tenant/principal values are process-owned,
+not tool arguments:
+
+```bash
+export SYNAPSOR_TENANT_ID=acme
+export SYNAPSOR_PRINCIPAL=local_operator
+
+synapsor-runner config validate --config ./synapsor.runner.json
+synapsor-runner doctor --config ./synapsor.runner.json --check-writeback
+synapsor-runner propose tickets.close_overdue \
+  --json '{"reason":"reviewed overdue-ticket close"}' \
+  --config ./synapsor.runner.json --store ./.synapsor/local.db
+synapsor-runner proposals show latest --store ./.synapsor/local.db --details
+```
+
+At this point IDs `3` and `4` are frozen in the proposal, but both source rows
+are still `overdue` at version `1`; the `globex` row is outside trusted tenant
+scope. Approval and apply remain operator-side commands and are not MCP tools:
+
+```bash
+synapsor-runner proposals approve latest --actor ops_manager --yes \
+  --store ./.synapsor/local.db
+synapsor-runner apply latest --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+synapsor-runner receipts list --proposal <proposal_id> \
+  --store ./.synapsor/local.db
+synapsor-runner replay show --proposal <proposal_id> --details \
+  --store ./.synapsor/local.db
+```
+
+Exactly IDs `3` and `4` become `closed` at version `2` in one transaction.
+The receipt/replay list both safe primary-key identities and their bounded
+digests. ID `99` is unchanged.
+
+To test drift on a freshly seeded copy, create the proposal, then use a
+database-operator session to increment one frozen row's version before
+approval. `apply` returns `SET_DRIFT_CONFLICT`; the other frozen row remains
+unchanged because no partial set mutation is committed:
+
+```sql
+UPDATE public.service_tickets SET version = version + 1 WHERE id = 4;
+```
+
+The example uses `runner_ledger`, which creates no receipt table in the source
+database. For one local process, the local store is the authority; a fleet must
+use authoritative shared-Postgres `runtime_store`. `source_db` authority
+instead writes the mutation and receipt atomically in one source transaction
+and requires its fixed precreated or auto-migrated receipt table. See
+[Guarded CRUD receipt authority](guarded-crud-writeback.md).
+
+## Proposal and apply behavior
+
+Proposal creation stores:
+
+- the exact ordered primary keys and trusted tenant;
+- every exact expected version;
+- allowlisted before/after values or bounded digests;
+- reviewed row count and aggregate values;
+- a digest over the complete frozen set;
+- pending human/operator approval.
+
+Member and set digests use SHA-256 over JSON whose object keys are sorted
+recursively. Array order remains significant because it is the reviewed,
+deterministic primary-key order. JSON strings, finite numbers, booleans, and
+null retain their protocol representation; unsupported runtime objects and
+non-finite values are rejected rather than stringified implicitly. Runner
+1.4.1 also verifies the narrowly known deterministic raw-object order emitted
+by 1.4.0, reconstructed from the complete stored reviewed data, so unchanged
+1.4.0 proposals remain applyable without weakening the drift checks.
+
+Apply locks the frozen rows in deterministic primary-key order, rechecks every
+reviewed value/version, performs every member mutation in one transaction, and
+requires the affected count to equal the frozen count. One missing/stale row or
+one database error rolls back the whole set.
+
+Set `sources.<name>.statement_timeout_ms` to bound source waits. PostgreSQL
+uses transaction-local statement and lock timeouts. MySQL applies the value to
+read/preflight execution and rounds it up to whole seconds for InnoDB lock
+waits; MySQL does not offer the same general DML statement timeout as
+PostgreSQL.
+
+The protocol-v3 receipt and replay include every primary key plus the bounded
+before/after or tombstone digests. Kept-out fields are never added merely to
+support a set operation.
+
+## Receipt authority and ambiguity
+
+`source_db` authority commits the mutation and receipt in the same source
+transaction. It gives the strongest retry classification.
+
+`runner_ledger` authority creates no source receipt table, but no atomic
+transaction spans the source and Runner ledger. A process loss after source
+commit can therefore produce `reconciliation_required`. Runner does not retry
+or guess. The operator reconciliation path re-inspects only the frozen,
+allowlisted identities and records an immutable decision.
+
+## Explicit boundary
+
+Use an [app-owned executor](writeback-executors.md) for:
+
+- model-supplied or free-form predicates;
+- ranges, wildcards, ordering, subqueries, or dynamic identifiers;
+- more than 100 rows or any unbounded batch;
+- UPSERT/MERGE, DDL, stored procedures, or cross-table/database transactions;
+- external API calls, events, files, emails, payments, or other side effects;
+- a hard DELETE whose trigger/cascade effects cannot be proven bounded.
+
+Policy auto-approval is not supported for bounded sets. Every set proposal
+requires a verified human/operator decision.
+
+## Verification
+
+Run the disposable-engine gate:
+
+```bash
+corepack pnpm test:bounded-set
+```
+
+It verifies both PostgreSQL and MySQL: the exact DSL/contract path under both
+receipt authorities; cap+1 and aggregate rejection before persistence; exact
+UPDATE/DELETE; batch INSERT; idempotent retry; independent version, predicate,
+aggregate, writable-value, missing-member, and tenant drift; injected mid-set
+rollback; insert dedup/atomicity; delete trigger/cascade refusal; exact receipt
+members; Runner-ledger reconciliation; and 1/10/100-row bounds. See the
+[local benchmark note](benchmarks/bounded-set-local.md) and the normative
+[safety RFC](rfcs/005-bounded-set-writeback.md).

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:
 
@@ -435,3 +447,9 @@ Commit authority stays outside the model:
 ```text
 human/operator approval -> guarded writeback or app-owned handler -> receipt/replay
 ```
+
+If your application already exposes fixed parameterized functions, that is a
+good foundation rather than an anti-pattern. Read [Why Synapsor Over Prompt And
+Application Guardrails](why-synapsor-vs-app-guardrails.md) to decide whether
+you also need Runner's shared contract, trusted context, evidence, approval,
+receipt, replay, and compensation lifecycle.

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.