@synapsor/runner 1.1.1 → 1.4.0

package/docs/security-boundary.md

@@ -67,17 +67,35 @@ outside the model-facing MCP server and verifies:
 - allowed mutable columns;
 - conflict/version guard;
 - idempotency key;
+- operation-specific version or source-unique deduplication guard;
 - job expiry;
-- exactly one affected row.
+- exactly one reviewed row or every member of one bounded frozen set.
 
 If any authority check cannot be verified, the write fails closed.
 
 For direct SQL writeback, the writer connection is the env var named by the
-source `write_url_env` in `synapsor.runner.json`. Direct SQL writeback writes an
-administrator-created `synapsor_writeback_receipts` table for idempotency and
-replay. The writer needs `SELECT`/`INSERT`/`UPDATE` on that table, but not schema
-`CREATE`. If your database policy forbids the receipt table, use an app-owned
-`http_handler` or `command_handler` executor instead.
+source `write_url_env` in `synapsor.runner.json`. With `source_db` receipt
+authority, the source mutation and receipt commit atomically; the receipt table
+can be administrator-precreated or explicitly auto-migrated. With
+`runner_ledger` authority, Runner creates no source receipt table, but a crash
+after source commit and before ledger completion can require verified operator
+reconciliation. It is not distributed exactly-once. See
+[Guarded Single-Row CRUD Writeback](guarded-crud-writeback.md).
+
+Bounded-set direct writeback additionally requires a contract-fixed predicate
+or complete reviewed item list, `MAX ROWS` plus aggregate bounds,
+human/operator approval, exact frozen identities and versions, deterministic
+locks, one atomic source transaction, and per-member receipt digests. The
+model cannot supply the predicate or cap. See [Bounded Set
+Writeback](bounded-set-writeback.md).
+
+When a direct SQL capability opts into reviewed reversibility, an applied
+receipt may carry a bounded inverse containing only trusted identity, version,
+and reviewed writable values. `revert` is operator-only and creates a new
+proposal; it never mutates or approves. Compensation rechecks the exact forward
+result under the trusted tenant and uses the normal approval, receipt,
+reconciliation, and replay boundaries. See [Reviewed Reversible Change
+Sets](reversible-change-sets.md).
 
 When a capability uses an `http_handler` or `command_handler` executor, the
 same approval boundary applies. The runner sends a structured proposal/job
@@ -96,6 +114,8 @@ approve/reject actions. It does not expose raw SQL, database URLs, write
 credentials, approval tools, commit tools, or controls that widen reviewed
 tables/columns.
 
-Synapsor Runner supports reviewed single-row business actions only in the
-current alpha. It does not support arbitrary SQL, DDL, `INSERT`, `DELETE`,
-`UPSERT`, or multi-row updates.
+Synapsor Runner supports reviewed single-row CRUD and the narrowly bounded set
+path documented above. It does not support arbitrary SQL, DDL, UPSERT,
+model-generated predicates, unbounded sets, or cross-table direct writeback.
+Hard DELETE fails closed when cascades, write triggers, or required metadata
+visibility prevent a bounded-effect proof.

package/docs/writeback-executors.md

@@ -42,19 +42,19 @@ For `synapsor-runner apply --job ... --config ...`, set the env var named by
 `write_url_env`. `SYNAPSOR_DATABASE_URL` is only a legacy fallback for direct
 worker flows that do not pass a local config.
 
-Direct SQL writeback also stores idempotency receipts in the source database.
-By default it runs:
+Direct SQL writeback uses the receipt authority selected under the source
+config. `source_db` can use an administrator-precreated table or explicitly run
+an idempotent migration:
 
 ```sql
 CREATE TABLE IF NOT EXISTS synapsor_writeback_receipts (...);
 ```
 
-That means the writer needs permission to create and write that receipt table in
-the target schema/database, or the table must be pre-created by an administrator
-and granted to the writer. If you do not want Runner to create a table in the
-application schema, create a dedicated schema/database for receipts where your
-database policy allows it, or use `http_handler`/`command_handler` so your
-application owns receipt storage and business writes.
+`precreated` needs only receipt-table DML; `auto_migrate` also needs bounded
+`CREATE`. `runner_ledger` creates no source receipt table and uses a durable
+Runner intent plus operator reconciliation for ambiguous post-commit crashes.
+It does not claim distributed exactly-once. See
+[Guarded Single-Row CRUD Writeback](guarded-crud-writeback.md).
 
 Use the helper commands before enabling direct SQL writeback:
 
@@ -65,9 +65,10 @@ npx -y -p @synapsor/runner synapsor-runner writeback grants --engine postgres --
 ```
 
 `writeback doctor --check-db` connects with the configured writer credential and
-checks the pre-created receipt table path in a rolled-back transaction. Apply
-the printed migration as an administrator first; the steady-state writer needs
-table `SELECT`/`INSERT`/`UPDATE`, not schema `CREATE`.
+checks the selected receipt authority plus operation-specific target guards in
+a rolled-back transaction. In `precreated` mode, apply the printed migration as
+an administrator first; the steady-state writer needs table
+`SELECT`/`INSERT`/`UPDATE`, not schema `CREATE`.
 
 ## `http_handler`
 

package/examples/runner-fleet/seed/mysql.sql

@@ -7,6 +7,39 @@ CREATE TABLE invoices (
   updated_at datetime(6) NOT NULL
 );
 
+CREATE TABLE guard_crud_items (
+  id bigint NOT NULL AUTO_INCREMENT PRIMARY KEY,
+  tenant_id varchar(128) NOT NULL,
+  request_id varchar(128) NOT NULL,
+  value_cents integer NOT NULL,
+  version bigint NOT NULL DEFAULT 1,
+  UNIQUE KEY guard_crud_items_tenant_request (tenant_id, request_id)
+);
+
+CREATE TABLE synapsor_receipts_precreated (
+  idempotency_key varchar(191) PRIMARY KEY,
+  job_id varchar(191) UNIQUE NOT NULL,
+  proposal_id varchar(191) NOT NULL,
+  status varchar(64) NOT NULL,
+  result_hash varchar(255),
+  created_at datetime(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
+  completed_at datetime(6)
+);
+
+INSERT INTO guard_crud_items (id, tenant_id, request_id, value_cents, version) VALUES
+  (1001, 'acme', 'update-precreated', 100, 1),
+  (1002, 'acme', 'delete-precreated', 200, 1),
+  (1011, 'acme', 'update-auto', 110, 1),
+  (1012, 'acme', 'delete-auto', 210, 1),
+  (1021, 'acme', 'update-ledger', 120, 1),
+  (1022, 'acme', 'delete-ledger', 220, 1),
+  (1031, 'globex', 'wrong-tenant', 230, 1),
+  (1041, 'acme', 'stale-version', 240, 2),
+  (1051, 'acme', 'crash-after-commit', 250, 1),
+  (1052, 'acme', 'crash-before-commit', 260, 1),
+  (1061, 'acme', 'concurrent-apply', 270, 1);
+ALTER TABLE guard_crud_items AUTO_INCREMENT = 2001;
+
 INSERT INTO invoices (id, tenant_id, status, late_fee_cents, waiver_reason, updated_at) VALUES
   ('MYSQL-ACME', 'acme', 'overdue', 700, NULL, '2026-07-12 12:00:00.000000');
 
@@ -15,6 +48,20 @@ SELECT invoices.*, SLEEP(0.35) AS synthetic_delay
 FROM invoices;
 
 CREATE USER IF NOT EXISTS 'synapsor_reader'@'%' IDENTIFIED BY 'synapsor_reader_password';
+CREATE USER IF NOT EXISTS 'synapsor_crud_precreated'@'%' IDENTIFIED BY 'synapsor_crud_precreated_password';
+CREATE USER IF NOT EXISTS 'synapsor_crud_auto'@'%' IDENTIFIED BY 'synapsor_crud_auto_password';
+CREATE USER IF NOT EXISTS 'synapsor_crud_ledger'@'%' IDENTIFIED BY 'synapsor_crud_ledger_password';
 GRANT SELECT ON synapsor_fleet.invoices TO 'synapsor_reader'@'%';
 GRANT SELECT ON synapsor_fleet.slow_invoices TO 'synapsor_reader'@'%';
+GRANT SELECT, INSERT, UPDATE, DELETE ON synapsor_fleet.guard_crud_items TO 'synapsor_crud_precreated'@'%';
+GRANT SELECT, INSERT, UPDATE, DELETE ON synapsor_fleet.guard_crud_items TO 'synapsor_crud_auto'@'%';
+GRANT SELECT, INSERT, UPDATE, DELETE ON synapsor_fleet.guard_crud_items TO 'synapsor_crud_ledger'@'%';
+GRANT TRIGGER ON synapsor_fleet.guard_crud_items TO 'synapsor_crud_precreated'@'%';
+GRANT TRIGGER ON synapsor_fleet.guard_crud_items TO 'synapsor_crud_auto'@'%';
+GRANT TRIGGER ON synapsor_fleet.guard_crud_items TO 'synapsor_crud_ledger'@'%';
+GRANT PROCESS ON *.* TO 'synapsor_crud_precreated'@'%';
+GRANT PROCESS ON *.* TO 'synapsor_crud_auto'@'%';
+GRANT PROCESS ON *.* TO 'synapsor_crud_ledger'@'%';
+GRANT SELECT, INSERT, UPDATE ON synapsor_fleet.synapsor_receipts_precreated TO 'synapsor_crud_precreated'@'%';
+GRANT SELECT, INSERT, UPDATE, CREATE ON synapsor_fleet.* TO 'synapsor_crud_auto'@'%';
 FLUSH PRIVILEGES;

package/examples/runner-fleet/seed/postgres.sql

@@ -25,10 +25,47 @@ CREATE TABLE public.synthetic_handler_receipts (
   created_at timestamptz NOT NULL DEFAULT now()
 );
 
+CREATE TABLE public.guard_crud_items (
+  id bigint GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+  tenant_id text NOT NULL,
+  request_id text NOT NULL,
+  value_cents integer NOT NULL,
+  version bigint NOT NULL DEFAULT 1,
+  UNIQUE (tenant_id, request_id)
+);
+
+CREATE SCHEMA synapsor_precreated;
+CREATE TABLE synapsor_precreated.receipts (
+  idempotency_key text PRIMARY KEY,
+  job_id text UNIQUE NOT NULL,
+  proposal_id text NOT NULL,
+  status text NOT NULL,
+  result_hash text,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  completed_at timestamptz
+);
+CREATE SCHEMA synapsor_auto;
+
+INSERT INTO public.guard_crud_items (id, tenant_id, request_id, value_cents, version) VALUES
+  (1001, 'acme', 'update-precreated', 100, 1),
+  (1002, 'acme', 'delete-precreated', 200, 1),
+  (1011, 'acme', 'update-auto', 110, 1),
+  (1012, 'acme', 'delete-auto', 210, 1),
+  (1021, 'acme', 'update-ledger', 120, 1),
+  (1022, 'acme', 'delete-ledger', 220, 1),
+  (1031, 'globex', 'wrong-tenant', 230, 1),
+  (1041, 'acme', 'stale-version', 240, 2),
+  (1051, 'acme', 'crash-after-commit', 250, 1),
+  (1052, 'acme', 'crash-before-commit', 260, 1),
+  (1061, 'acme', 'concurrent-apply', 270, 1);
+SELECT setval(pg_get_serial_sequence('public.guard_crud_items', 'id'), 2000, true);
+
 INSERT INTO public.invoices (id, tenant_id, status, late_fee_cents, waiver_reason, updated_at) VALUES
   ('INV-ACME', 'acme', 'overdue', 2500, NULL, '2026-07-12T12:00:00Z'),
   ('INV-GLOBEX', 'globex', 'overdue', 3100, NULL, '2026-07-12T12:00:00Z'),
   ('INV-RATECO', 'rateco', 'overdue', 900, NULL, '2026-07-12T12:00:00Z'),
+  ('INV-BATCH-A', 'acme', 'overdue', 1100, NULL, '2026-07-12T12:00:00Z'),
+  ('INV-BATCH-B', 'acme', 'overdue', 1300, NULL, '2026-07-12T12:00:00Z'),
   ('INV-QUORUM-RACE', 'acme', 'overdue', 1400, NULL, '2026-07-12T12:00:00Z'),
   ('INV-WORKER-RACE', 'acme', 'overdue', 1600, NULL, '2026-07-12T12:00:00Z'),
   ('INV-DEAD-REQUEUE', 'acme', 'overdue', 1700, NULL, '2026-07-12T12:00:00Z'),
@@ -53,6 +90,9 @@ DO $$
 BEGIN
   CREATE ROLE synapsor_reader LOGIN PASSWORD 'synapsor_reader_password';
   CREATE ROLE synapsor_writer LOGIN PASSWORD 'synapsor_writer_password';
+  CREATE ROLE synapsor_crud_precreated LOGIN PASSWORD 'synapsor_crud_precreated_password';
+  CREATE ROLE synapsor_crud_auto LOGIN PASSWORD 'synapsor_crud_auto_password';
+  CREATE ROLE synapsor_crud_ledger LOGIN PASSWORD 'synapsor_crud_ledger_password';
 EXCEPTION WHEN duplicate_object THEN NULL;
 END
 $$;
@@ -64,6 +104,14 @@ GRANT SELECT ON public.slow_invoices TO synapsor_reader;
 GRANT UPDATE (late_fee_cents, waiver_reason, updated_at) ON public.invoices TO synapsor_writer;
 GRANT SELECT, INSERT, UPDATE ON public.synapsor_writeback_receipts TO synapsor_writer;
 
+GRANT CONNECT ON DATABASE synapsor_fleet TO synapsor_crud_precreated, synapsor_crud_auto, synapsor_crud_ledger;
+GRANT USAGE ON SCHEMA public TO synapsor_crud_precreated, synapsor_crud_auto, synapsor_crud_ledger;
+GRANT SELECT, INSERT, UPDATE, DELETE ON public.guard_crud_items TO synapsor_crud_precreated, synapsor_crud_auto, synapsor_crud_ledger;
+GRANT USAGE, SELECT ON SEQUENCE public.guard_crud_items_id_seq TO synapsor_crud_precreated, synapsor_crud_auto, synapsor_crud_ledger;
+GRANT USAGE ON SCHEMA synapsor_precreated TO synapsor_crud_precreated;
+GRANT SELECT, INSERT, UPDATE ON synapsor_precreated.receipts TO synapsor_crud_precreated;
+GRANT USAGE, CREATE ON SCHEMA synapsor_auto TO synapsor_crud_auto;
+
 -- Docker's Postgres entrypoint briefly starts a temporary postmaster while it
 -- runs init scripts. The Compose health check compares this timestamp with the
 -- current postmaster start time so dependents wait for the final server.

package/examples/support-plan-credit/README.md

@@ -6,6 +6,12 @@ This example shows three enforcement tiers on one support action:
 - `$100` (`10000` cents): saved as `pending_review` until a local operator approves.
 - `$1000` (`100000` cents): rejected before proposal creation by the contract bound.
 
+It also shows native guarded single-row INSERT through
+`support.propose_plan_credit_record`. Runner supplies the trusted tenant and a
+proposal-derived request ID; the database enforces `(tenant_id, request_id)` as
+a unique deduplication key. The existing UPDATE scenario above remains the
+policy-tier demonstration.
+
 ## Prerequisites
 
 - Docker
@@ -132,6 +138,30 @@ synapsor-runner apply latest --config examples/support-plan-credit/synapsor.runn
 The live smoke test mutates `updated_at` before apply and proves stale proposals
 return `VERSION_CONFLICT` without changing the source row.
 
+Create one reviewed credit record with native INSERT:
+
+```bash
+synapsor-runner propose support.propose_plan_credit_record \
+  --config examples/support-plan-credit/synapsor.runner.json \
+  --store ./tmp/support-plan-credit/local.db \
+  --json '{"customer_id":"CUS-3001","credit_cents":2500,"reason":"SLA outage ticket SUP-481"}'
+
+synapsor-runner proposals approve latest --yes \
+  --config examples/support-plan-credit/synapsor.runner.json \
+  --store ./tmp/support-plan-credit/local.db
+synapsor-runner apply latest \
+  --config examples/support-plan-credit/synapsor.runner.json \
+  --store ./tmp/support-plan-credit/local.db
+synapsor-runner replay show latest --store ./tmp/support-plan-credit/local.db
+```
+
+The insert is exactly one row. The model cannot set `tenant_id`, `request_id`,
+table names, or columns. Retry is classified from the atomic source receipt and
+the source-unique deduplication key. Use an
+[app-owned executor](../../docs/writeback-executors.md) for multi-table writes,
+external effects, UPSERT, or business actions that cannot fit this one-row
+boundary.
+
 Run the complete Docker-backed scenario, including all three policy tiers and
 the stale-row conflict:
 
@@ -153,6 +183,7 @@ The contract keeps these fields out:
 ```text
 support.inspect_customer
 support.propose_plan_credit
+support.propose_plan_credit_record
 auto-approval: enabled
 ```
 

package/examples/support-plan-credit/contract.synapsor.sql

@@ -51,10 +51,36 @@ CREATE CAPABILITY support.propose_plan_credit
   WRITEBACK DIRECT SQL
 END
 
+CREATE CAPABILITY support.propose_plan_credit_record
+  DESCRIPTION 'Propose creating one bounded plan-credit record with source-enforced deduplication.'
+  RETURNS HINT 'Returns a proposal id for one new account_credits row; source database unchanged until human approval and guarded apply.'
+  USING CONTEXT support_agent_context
+  SOURCE local_postgres
+  ON public.account_credits
+  PRIMARY KEY id
+  TENANT KEY tenant_id
+  ARG customer_id STRING REQUIRED MAX LENGTH 128 DESCRIPTION 'Customer id such as CUS-3001.'
+  ARG credit_cents NUMBER REQUIRED MIN 1 MAX 50000 DESCRIPTION 'Requested plan credit in cents.'
+  ARG reason TEXT REQUIRED MAX LENGTH 500 DESCRIPTION 'Business reason tied to support evidence.'
+  ALLOW READ id, tenant_id, request_id, customer_id, amount_cents, reason, created_at
+  REQUIRE EVIDENCE
+  MAX ROWS 1
+  PROPOSE ACTION create_plan_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 credit_cents
+  PATCH reason = ARG reason
+  BOUND amount_cents 1..50000
+  APPROVAL ROLE support_reviewer
+  WRITEBACK DIRECT SQL
+END
+
 CREATE AGENT WORKFLOW support.plan_credit_request
   USING CONTEXT support_agent_context
   ALLOW CAPABILITY support.inspect_customer
   ALLOW CAPABILITY support.propose_plan_credit
+  ALLOW CAPABILITY support.propose_plan_credit_record
   REQUIRE EVIDENCE
   APPROVAL REQUIRED ROLE support_reviewer
   CHECKPOINT PROPOSAL ONLY

package/examples/support-plan-credit/expected-output/tools-preview.txt

@@ -3,6 +3,7 @@ Synapsor tools preview: ok
 Exposed to MCP:
   - support.inspect_customer
   - support.propose_plan_credit
+  - support.propose_plan_credit_record
 
 Not exposed to MCP:
   - execute_sql / raw query tools

package/examples/support-plan-credit/seed/001_seed.sql

@@ -24,6 +24,17 @@ CREATE TABLE IF NOT EXISTS public.synapsor_writeback_receipts (
   completed_at timestamptz
 );
 
+CREATE TABLE IF NOT EXISTS public.account_credits (
+  id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  tenant_id text NOT NULL,
+  request_id text NOT NULL,
+  customer_id text NOT NULL,
+  amount_cents integer NOT NULL CHECK (amount_cents BETWEEN 1 AND 50000),
+  reason text NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT account_credits_tenant_request_unique UNIQUE (tenant_id, request_id)
+);
+
 INSERT INTO public.customers (
   id,
   tenant_id,
@@ -97,6 +108,8 @@ $$;
 
 GRANT CONNECT ON DATABASE synapsor_runner_plan_credit TO synapsor_reader, synapsor_writer;
 GRANT USAGE ON SCHEMA public TO synapsor_reader, synapsor_writer;
-GRANT SELECT ON public.customers TO synapsor_reader, synapsor_writer;
+GRANT SELECT ON public.customers, public.account_credits TO synapsor_reader, synapsor_writer;
 GRANT UPDATE (plan_credit_cents, credit_reason, updated_at) ON public.customers TO synapsor_writer;
+GRANT INSERT (tenant_id, request_id, customer_id, amount_cents, reason) ON public.account_credits TO synapsor_writer;
+GRANT USAGE, SELECT ON SEQUENCE public.account_credits_id_seq TO synapsor_writer;
 GRANT SELECT, INSERT, UPDATE ON public.synapsor_writeback_receipts TO synapsor_writer;

package/examples/support-plan-credit/synapsor.contract.json

@@ -139,6 +139,105 @@
         "credit_reason",
         "updated_at"
       ]
+    },
+    {
+      "args": {
+        "credit_cents": {
+          "description": "Requested plan credit in cents.",
+          "maximum": 50000,
+          "minimum": 1,
+          "required": true,
+          "type": "number"
+        },
+        "customer_id": {
+          "description": "Customer id such as CUS-3001.",
+          "max_length": 128,
+          "required": true,
+          "type": "string"
+        },
+        "reason": {
+          "description": "Business reason tied to support evidence.",
+          "max_length": 500,
+          "required": true,
+          "type": "string"
+        }
+      },
+      "context": "support_agent_context",
+      "description": "Propose creating one bounded plan-credit record with source-enforced deduplication.",
+      "evidence": {
+        "query_audit": true,
+        "required": true
+      },
+      "kind": "proposal",
+      "max_rows": 1,
+      "name": "support.propose_plan_credit_record",
+      "proposal": {
+        "action": "create_plan_credit",
+        "allowed_fields": [
+          "customer_id",
+          "amount_cents",
+          "reason"
+        ],
+        "approval": {
+          "mode": "human",
+          "required_role": "support_reviewer"
+        },
+        "conflict_guard": {
+          "weak_guard_ack": true
+        },
+        "numeric_bounds": {
+          "amount_cents": {
+            "maximum": 50000,
+            "minimum": 1
+          }
+        },
+        "operation": {
+          "deduplication": {
+            "components": [
+              {
+                "column": "tenant_id",
+                "source": "trusted_tenant"
+              },
+              {
+                "column": "request_id",
+                "source": "proposal_id"
+              }
+            ]
+          },
+          "kind": "insert"
+        },
+        "patch": {
+          "amount_cents": {
+            "from_arg": "credit_cents"
+          },
+          "customer_id": {
+            "from_arg": "customer_id"
+          },
+          "reason": {
+            "from_arg": "reason"
+          }
+        },
+        "writeback": {
+          "mode": "direct_sql"
+        }
+      },
+      "returns_hint": "Returns a proposal id for one new account_credits row; source database unchanged until human approval and guarded apply.",
+      "source": "local_postgres",
+      "subject": {
+        "primary_key": "id",
+        "schema": "public",
+        "table": "account_credits",
+        "tenant_key": "tenant_id"
+      },
+      "visible_fields": [
+        "id",
+        "tenant_id",
+        "request_id",
+        "customer_id",
+        "amount_cents",
+        "reason",
+        "created_at"
+      ]
     }
   ],
   "contexts": [
@@ -196,7 +295,8 @@
     {
       "allowed_capabilities": [
         "support.inspect_customer",
-        "support.propose_plan_credit"
+        "support.propose_plan_credit",
+        "support.propose_plan_credit_record"
       ],
       "approval": {
         "required": true,

package/examples/support-plan-credit/synapsor.runner.json

@@ -12,7 +12,13 @@
       "engine": "postgres",
       "read_url_env": "PLAN_CREDIT_POSTGRES_READ_URL",
       "write_url_env": "PLAN_CREDIT_POSTGRES_WRITE_URL",
-      "statement_timeout_ms": 3000
+      "statement_timeout_ms": 3000,
+      "receipts": {
+        "authority": "source_db",
+        "provisioning": "precreated",
+        "schema": "public",
+        "table": "synapsor_writeback_receipts"
+      }
     }
   }
 }