@synapsor/runner 1.1.1 → 1.4.1

package/docs/why-synapsor-vs-app-guardrails.md

@@ -0,0 +1,169 @@
+# Why Synapsor Over Prompt And Application Guardrails
+
+You can build a safe database tool in application code. The important question
+is not whether the code is custom or packaged. It is where authority lives and
+which safety properties are enforced outside the model.
+
+Synapsor Runner is useful when a narrow application function is no longer the
+whole requirement. It adds a shared, reviewable contract and an operational
+record around model-facing reads and writes: trusted context, evidence, query
+audit, proposals, approval outside MCP, guarded writeback, idempotency
+receipts, replay, and opt-in reviewed compensation.
+
+It does not make prompts trustworthy, prevent prompt injection, replace
+database permissions, or make an application compliant by itself.
+
+## Prompt Instructions Are Not A Security Boundary
+
+A system prompt can improve normal model behavior. It cannot grant or remove
+database authority. **Prompt-only enforcement is not a security boundary.** A
+confused or prompt-injected model can ignore an instruction, so a rule such as
+"only access this tenant" must be enforced by trusted code, database policy,
+or both.
+
+This is a general agent-security issue, not a hypothetical specific to one
+vendor:
+
+- [OWASP LLM01: Prompt Injection](https://genai.owasp.org/llmrisk/llm01-prompt-injection/)
+  describes direct and indirect prompt injection and recommends constrained
+  model behavior plus human approval for high-risk actions.
+- [General Analysis published a controlled Supabase MCP
+  demonstration](https://generalanalysis.com/blog/supabase-mcp-blog) in which
+  untrusted support-ticket content influenced an agent with broad database
+  access and exposed integration-token data. The demonstration disabled
+  read-only mode and used a privileged `service_role`; it was a controlled
+  security test, not evidence that every Supabase MCP deployment is
+  vulnerable.
+- [Supabase's defense-in-depth
+  response](https://supabase.com/blog/defense-in-depth-mcp) likewise recommends
+  a protective layer, least privilege, and avoiding direct production access.
+
+The lesson is not that a prompt can never be useful. It is that prompt text
+must not be the control that protects tenant scope, hidden fields, approval,
+or commit authority.
+
+## First Ask: Who Produces The SQL?
+
+### The model produces SQL
+
+If the model emits arbitrary SQL and application code decides whether to run
+it, that validator must correctly understand the database grammar,
+subqueries, functions, views, permissions, row scope, side effects, and future
+schema changes. A blocklist or regular expression is not an authorization
+system. This remains the `execute_sql` problem with an extra parser in front
+of it.
+
+Prefer fixed, parameterized statements selected by trusted application code,
+restricted database roles, views, and row-level security. Do not make the
+model the query planner for privileged production access.
+
+### Your application produces SQL
+
+If application code selects a fixed parameterized statement and exposes a
+narrow function such as `billing.inspect_invoice`, you have already made the
+most important architectural move: a semantic business tool replaces raw SQL.
+For a small application, that may be enough.
+
+The next question is whether you also need a consistent review and operations
+layer. Without one, each function must separately implement and preserve:
+
+- trusted tenant and principal binding;
+- read and write field allowlists;
+- evidence and query-audit records;
+- exact proposed diffs before a write;
+- approval identity and quorum outside the model;
+- conflict, transition, numeric, row-count, and aggregate guards;
+- idempotent execution and receipts;
+- activity search and replay;
+- bounded, separately approved compensation where reversibility is possible.
+
+Synapsor centralizes those mechanics in a contract and runtime instead of
+requiring every tool handler to invent them independently.
+
+## What Runner Adds
+
+| Concern | Prompt or one-off handler | Synapsor Runner |
+| --- | --- | --- |
+| Model-facing authority | Depends on instructions and handler design | Only reviewed semantic capabilities are served |
+| Tenant/principal scope | Often passed as model arguments or scattered checks | Bound from trusted environment or authenticated session context |
+| Data exposure | Handler-specific projection | Contract-reviewed visible fields and kept-out fields |
+| Risky writes | Handler may write during the tool call | MCP creates a proposal; approval and apply stay outside MCP |
+| Concurrency | Must be designed per handler | Version/conflict guards and frozen-set drift checks fail closed |
+| Retry behavior | Must be designed per handler | Idempotency keys and source or Runner-ledger receipts |
+| Investigation | Application logs | Evidence handles, query audit, proposal events, receipts, activity, and replay |
+| Undo | Usually another bespoke endpoint | Opt-in reviewed compensation for supported direct writes |
+| Review surface | Prompt, code, and policies may diverge | Portable canonical contract plus SQL-like DSL |
+
+This is structural enforcement only for traffic that actually passes through
+Runner and its reviewed capabilities. An unrestricted credential, a second raw
+SQL MCP server, or a bypass path in the application remains outside the
+boundary.
+
+The local SQLite or shared Postgres ledger is durable through Runner's
+supported interfaces, but a trusted host or database administrator can alter
+local state. Use Synapsor Cloud or your own tamper-evident retention and access
+controls when organizational audit requirements demand a stronger shared
+record.
+
+## Build Or Adopt
+
+Your own code is probably enough when all of these are true:
+
+- the agent is read-only or has one or two fixed, low-risk functions;
+- the application already derives tenant scope from authenticated server
+  state;
+- database roles, views, and row-level security provide the required floor;
+- you do not need approval history, evidence, receipts, replay, or reviewed
+  compensation;
+- one team owns every tool and can test every change consistently.
+
+Consider Runner when one or more of these are true:
+
+- agents can propose writes to customer, billing, support, health, finance,
+  or other consequential data;
+- tenant or principal isolation must not depend on model-supplied arguments;
+- a human or operator must approve some changes outside the agent loop;
+- retries, stale writes, bounded sets, or partial failures need explicit
+  fail-closed behavior;
+- investigators need to answer what the agent read, requested, approved, and
+  changed;
+- capabilities are growing across teams, agents, databases, or MCP clients;
+- the safety boundary needs to be reviewed in source control as one portable
+  contract.
+
+This is not a claim that the mechanics are impossible to build. It is a choice
+between maintaining them independently in every integration and adopting a
+tested contract/runtime that makes the same controls visible and repeatable.
+
+## Regulated And High-Consequence Data
+
+Health, finance, and other regulated workloads make the distinction more
+important, but Runner does not confer HIPAA, PCI DSS, SOC 2, or any other
+compliance status. A real deployment still needs the appropriate legal and
+organizational controls, least-privilege roles, encryption, retention,
+monitoring, incident response, vendor agreements, and human access policy.
+
+Runner can contribute technical evidence for that program: tenant-bound
+capabilities, explicit field projections, proposal/approval separation,
+signed operator identity where configured, guarded writeback receipts, and
+replay. Validate those controls with your security and compliance owners
+before using production regulated data.
+
+## Evaluate It Against Your Existing Layer
+
+1. Run the static MCP risk review against your current tools:
+
+   ```bash
+   npx -y @synapsor/runner audit ./tools-list.json
+   ```
+
+2. List every rule currently enforced only by a prompt.
+3. Identify whether the model or trusted code chooses SQL, tenant scope,
+   columns, predicates, approval, and commit timing.
+4. Pick one consequential staging workflow and compare its current evidence,
+   retry, conflict, approval, receipt, and investigation behavior with the
+   [own-database Runner flow](getting-started-own-database.md).
+
+Keep your existing database permissions either way. Runner shapes the
+agent-facing interface; it does not replace the database's own authorization
+boundary.

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"
+      }
     }
   }
 }