@synapsor/runner 0.1.15 → 1.0.0

package/docs/release-notes.md

@@ -1,7 +1,7 @@
 # Release Notes
 
-These notes track public Synapsor Runner behavior. Starting with `0.1.0`, the
-normal install path uses the untagged stable package:
+These notes track public Synapsor Runner behavior. Starting with `1.0.0`, the
+documented production-loop compatibility line uses the untagged stable package:
 
 ```bash
 npx -y -p @synapsor/runner synapsor-runner demo --quick
@@ -12,6 +12,48 @@ for the Synapsor Cloud CLI.
 
 ## Unreleased
 
+## 1.0.0
+
+### Production Approval Loop
+
+- Adds batch apply for approved proposals with independent per-proposal
+  outcomes, rerun-safe idempotency, and `--capability`, `--tenant`, and
+  `--max` filters.
+- Adds aggregate policy ceilings to canonical contracts and DSL authoring so
+  small proposals fall back to human review once daily count or total limits are
+  reached.
+- Adds signed operator-key approval/apply enforcement, tamper-evident approval
+  records, operational counters/logs, and a supervised local writeback worker.
+- Adds shared Postgres ledger support, runtime-store mode, per-session trusted
+  context, managed secret hydration, token rotation hooks, and Streamable HTTP
+  mTLS for scale-out deployments.
+- Keeps local SQLite as the default while allowing runtime-store workers to run
+  long-lived shared ledger drain loops under a Postgres advisory lock.
+- Declares the first semver contract for the documented CLI, schema, contract,
+  MCP result, writeback, approval, metrics, and replay surfaces.
+
+Prepared package versions: `@synapsor/spec@1.0.0`,
+`@synapsor/dsl@1.0.0`, and `@synapsor/runner@1.0.0`.
+
+## 0.1.16
+
+### Fleet-Lab Runner Hardening
+
+- Preserves Postgres microseconds in proposal conflict guards and proves normal
+  `now()` rows apply exactly once while genuinely stale rows conflict.
+- Allows a new proposal after conflict without deleting or rewriting the old
+  proposal, receipt, or replay history.
+- Returns semantic active-proposal errors and rejects non-primary DSL lookups.
+- Removes schema-creation requirements from steady-state writeback, aligns audit
+  paths and JSON Schema with contract configs, and creates local ledgers with
+  owner-only POSIX permissions.
+- Adds complete DSL, Runner config, and ledger inspection/security references.
+
+Prepared package versions: `@synapsor/dsl@0.1.6` and
+`@synapsor/runner@0.1.16`. `@synapsor/spec@0.1.4` remains unchanged.
+
+## 0.1.15
+
 ### Editor-Friendly DSL Source Files
 
 - Prefers `.synapsor.sql` for DSL source files so editors can provide generic
@@ -24,6 +66,8 @@ Prepared package versions: `@synapsor/dsl@0.1.5` and
 `@synapsor/runner@0.1.15`. The already-published `@synapsor/spec@0.1.4` does
 not change and must not be republished for this release.
 
+## 0.1.12
+
 ### Runner Version Invocation
 
 - Keeps `synapsor-runner --version`, `synapsor-runner -v`, and
@@ -398,9 +442,9 @@ not change and must not be republished for this release.
   `SYNAPSOR_DATABASE_WRITE_URL`.
 - `SYNAPSOR_DATABASE_URL` is accepted only as a legacy fallback for older
   direct worker/apply flows without a local config.
-- Direct SQL writeback creates or writes `synapsor_writeback_receipts` for
-  idempotency and replay. The trusted writer needs permission for that receipt
-  table, or an administrator must pre-create the table and grant access.
+- Direct SQL writeback writes `synapsor_writeback_receipts` for idempotency and
+  replay. Current releases require an administrator-created table and grant the
+  trusted writer table access without schema `CREATE`.
 - Use `synapsor-runner writeback doctor`, `writeback migration`, and
   `writeback grants` to inspect and prepare the direct writeback path.
 - Use app-owned `http_handler` or `command_handler` executors for rich writes
@@ -457,10 +501,9 @@ not change and must not be republished for this release.
 
 ## Stable Release Policy
 
-Use untagged `@synapsor/runner` for stable installs. Use `@alpha` or an exact
-prerelease only when intentionally testing preview behavior. Stable `0.1.x`
-releases should keep the compatibility promise documented in
-`docs/release-policy.md`.
+Use untagged `@synapsor/runner` for stable installs. Use an exact prerelease
+only when intentionally testing preview behavior. Stable `1.x` releases should
+keep the compatibility promise documented in `docs/release-policy.md`.
 
 The first stable `0.1.0` release was gated on:
 

package/docs/release-policy.md

@@ -1,7 +1,10 @@
 # Release Policy
 
-Synapsor Runner `0.1.0` is the first stable local runner line. Use the stable
-package for normal installs:
+Synapsor Runner `0.1.0` was the first stable local runner line. Synapsor
+Runner `1.0.0` is the first production approval-loop semver line: batch apply,
+aggregate policy limits, verified operator identity, structured operations, and
+shared runtime-store deployment are part of the documented compatibility
+surface. Use the stable package for normal installs:
 
 ```bash
 npx -y -p @synapsor/runner synapsor-runner demo --quick
@@ -55,10 +58,37 @@ A stable `0.1.0` release should only be tagged after:
 - there are no known docs/code mismatches around transport, credentials,
   receipt tables, or handler expectations.
 
+## 1.0 Stability Gate
+
+Do not tag `1.0.0` only because the package is useful. `1.0.0` is the public
+semver contract for the Runner production approval loop, and it should be cut
+only after the following are true in the current tree and release artifacts:
+
+- batch apply can apply all approved proposals independently, reports
+  applied/conflict/skipped IDs, is safe to rerun through idempotency receipts,
+  and supports `--capability`, `--tenant`, and `--max`;
+- aggregate auto-approval limits are authored in DSL, represented in the
+  canonical contract spec, enforced as human-review fallback, persisted with
+  tripped-limit details, and visible in doctor/tools preview output;
+- approve/reject/apply can require a verified operator identity, enforce
+  contract reviewer roles and apply roles, and bind tamper-evident identity
+  records into the proposal ledger;
+- designed rejections and writeback outcomes emit structured logs, operational
+  counters are available per tenant and capability, and owner-only local store
+  permissions remain under test;
+- the documented public surfaces below have release-gate coverage from packed
+  artifacts, not only source-tree tests.
+
+After `1.0.0`, changes to the documented CLI, schema, contract, MCP result,
+writeback, approval, metrics, and replay surfaces must follow semantic
+versioning. Breaking changes require a new major version, except for security
+fixes that close a vulnerability while preserving the safest possible
+compatibility path.
+
 ## Stable Compatibility Promise
 
-Starting with `0.1.0`, Synapsor Runner keeps these public surfaces compatible
-through the `0.1.x` line unless a release note marks a deprecation first:
+Starting with `1.0.0`, Synapsor Runner keeps these public surfaces compatible
+through the `1.x` line unless a release note marks a deprecation first:
 
 - the `synapsor-runner` binary name and README quickstart commands;
 - `synapsor.runner.json` schema version `1` for documented fields;
@@ -73,8 +103,9 @@ through the `0.1.x` line unless a release note marks a deprecation first:
 Stable does not promise production SLA, hosted Cloud features, compliance
 certification, physical Postgres/MySQL branching, generic SQL writeback,
 generic multi-row writes, or compatibility for undocumented local SQLite
-internals. Local store migrations may happen inside `0.1.x`, but documented CLI
-inspection commands should remain the supported way to read the store.
+internals. Local store migrations may happen inside `1.x` and later minor
+versions, but documented CLI inspection commands should remain the supported way
+to read the store.
 
 Alpha users should pin an exact alpha version in package.json, CI, and MCP
 client snippets. Use `@alpha` only when intentionally testing the moving

package/docs/runner-config-reference.md

@@ -0,0 +1,299 @@
+# Runner Config Reference
+
+`synapsor.runner.json` wires portable reviewed contracts to one local runtime.
+It contains environment-variable names and fixed identifiers, never database
+URLs, passwords, bearer tokens, prompts, or model-selected tenant authority.
+
+Validate before serving:
+
+```bash
+synapsor-runner config validate --config ./synapsor.runner.json
+```
+
+Editor schema:
+
+```text
+schemas/synapsor.runner.schema.json
+```
+
+Unknown keys fail when `strict` is true (the default).
+
+## Top-level keys
+
+| Key | Required | Meaning |
+| --- | --- | --- |
+| `version` | Yes | Must be `1`. |
+| `mode` | Yes | `read_only`, `shadow`, `review`, or `cloud`. |
+| `result_format` | No | `1` legacy or `2` stable `ok/summary/data/proposal/error` envelope. Default `1`. |
+| `strict` | No | Reject unknown config keys. Default `true`. |
+| `storage` | Local | Local SQLite ledger plus optional shared Postgres mirror or runtime-store wiring. |
+| `sources` | Local | Named Postgres/MySQL source wiring. |
+| `trusted_context` | Conditional | Default trusted tenant/principal binding. |
+| `contexts` | No | Named trusted contexts referenced by capabilities/contracts. |
+| `contracts` | No | Portable contract file paths. Preferred for reviewed authoring. |
+| `capabilities` | Conditional | Embedded compatibility capabilities; may be `[]` with `contracts`. |
+| `policies` | No | Embedded reviewed policies; contract policies merge into the same catalog. |
+| `approvals` | No | Local approval overrides. |
+| `operator_identity` | No | Verified operator identity and apply-role wiring for approve/reject/apply. |
+| `executors` | No | App-owned writeback wiring. |
+| `cloud` | Cloud mode | Scoped Cloud adapter configuration. |
+
+## Path resolution
+
+- `contracts` entries resolve relative to the directory containing the config
+  file. Every command uses this rule, including audit, validate, doctor, tools,
+  smoke, MCP serve, propose, and apply.
+- `storage.sqlite_path` is resolved by the Runner process working directory.
+  Pass an absolute path when an MCP client launches Runner from another CWD.
+- Executor paths/URLs come from environment variables, not relative contract
+  content.
+
+## Storage
+
+```json
+{
+  "storage": {
+    "sqlite_path": "./.synapsor/local.db",
+    "shared_postgres": {
+      "mode": "mirror",
+      "url_env": "SYNAPSOR_LEDGER_DATABASE_URL",
+      "schema": "synapsor_runner",
+      "lock_timeout_ms": 10000
+    }
+  }
+}
+```
+
+The ledger stores proposals, visible evidence copies, query audit, approvals,
+receipts, events, and replay. New POSIX stores are owner-only (`0600`). Protect
+the file like a database extract; see [Store Lifecycle](store-lifecycle.md).
+
+`storage.shared_postgres.mode = "mirror"` makes mutating CLI commands restore
+from the shared Postgres ledger before the local mutation and sync back after
+the command while holding a schema-scoped Postgres advisory lock. Mirror mode is
+a bounded operator handoff bridge; MCP serving still uses the local SQLite
+store.
+
+`storage.shared_postgres.mode = "runtime_store"` makes MCP serving use the
+shared Postgres ledger as the primary proposal/evidence/replay store. Runner
+creates a connection from the environment variable named by `url_env`, auto-runs
+the shared-ledger migration at startup, and uses a schema-scoped transaction
+advisory lock around runtime mutations. The URL is still referenced by
+environment variable name; never put the database URL in the config file.
+Bounded CLI approval/apply/worker commands bridge through the same Postgres
+ledger by restoring into a temporary local store under the Postgres advisory
+lock, running the existing mutation, and syncing back. Long-running worker
+processes repeat bounded drain cycles and release the advisory lock while idle.
+
+`synapsor-runner doctor --config ./synapsor.runner.json` checks shared Postgres
+wiring when this block is present: the URL env var must be set, and the
+configured schema must already contain `ledger_entries`, `proposal_locks`, and
+`worker_leases`. Doctor reports env var names and table readiness only; it does
+not print database URLs or create the schema.
+
+## Sources
+
+```json
+{
+  "sources": {
+    "billing_postgres": {
+      "engine": "postgres",
+      "read_url_env": "BILLING_POSTGRES_READ_URL",
+      "write_url_env": "BILLING_POSTGRES_WRITE_URL",
+      "read_only": false,
+      "statement_timeout_ms": 3000
+    }
+  }
+}
+```
+
+`engine` is `postgres` or `mysql`. `read_url_env` is required. Use a
+least-privilege read credential. `write_url_env` is optional unless direct SQL
+writeback must apply; it should name a separate restricted writer. `read_only:
+true` forbids direct SQL writeback. `statement_timeout_ms` is a positive read
+timeout. `ssl` carries adapter-specific reviewed SSL options when used.
+
+A contract's `SOURCE billing_postgres` must exactly match a `sources` key.
+
+## Trusted context
+
+```json
+{
+  "trusted_context": {
+    "provider": "environment",
+    "values": {
+      "tenant_id_env": "SYNAPSOR_TENANT_ID",
+      "principal_env": "SYNAPSOR_PRINCIPAL"
+    }
+  }
+}
+```
+
+Providers are `environment`, `static_dev`, `http_claims`, and `cloud_session`.
+`static_dev` is only for local fixtures. Named `contexts` use the same shape.
+Capabilities may reference a context by name. The model never receives tenant
+or principal as an overridable argument.
+
+For multi-tenant Streamable HTTP services, use `http_claims` plus signed
+session auth:
+
+```json
+{
+  "trusted_context": {
+    "provider": "http_claims",
+    "values": {
+      "tenant_id_key": "tenant_id",
+      "principal_key": "sub"
+    }
+  },
+  "session_auth": {
+    "provider": "jwt_hs256",
+    "secret_env": "SYNAPSOR_SESSION_JWT_SECRET",
+    "previous_secret_env": "SYNAPSOR_PREVIOUS_SESSION_JWT_SECRET",
+    "issuer": "https://identity.example",
+    "audience": "synapsor-runner"
+  }
+}
+```
+
+`previous_secret_env` is optional and is only for rotation windows. Runner tries
+the active secret first, then the previous secret. Existing MCP sessions remain
+bound to the exact token fingerprint, so clients cannot swap tenant/principal
+identity inside an initialized session.
+
+## Contracts and embedded capabilities
+
+```json
+{
+  "contracts": ["./billing.contract.json"],
+  "capabilities": []
+}
+```
+
+Contracts are normalized `@synapsor/spec` JSON. Runner merges their contexts,
+capabilities, and policies into one runtime catalog. Duplicate names across
+embedded config and contracts fail; there is no silent shadowing.
+
+Embedded capabilities remain supported for generated/legacy configs. Their
+fields are documented in the JSON Schema and
+[Capability Authoring](capability-authoring.md): fixed target, args, primary-key
+lookup, visible fields, evidence, patch allowlist, bounds/transitions, conflict
+guard, approval, and writeback mode.
+
+## Executors
+
+```json
+{
+  "executors": {
+    "billing_handler": {
+      "type": "http_handler",
+      "url_env": "BILLING_HANDLER_URL",
+      "method": "POST",
+      "auth": {
+        "type": "bearer_env",
+        "token_env": "BILLING_HANDLER_TOKEN"
+      },
+      "signing_secret_env": "BILLING_HANDLER_SIGNING_SECRET",
+      "timeout_ms": 5000
+    }
+  }
+}
+```
+
+Types are `sql_update`, `http_handler`, and `command_handler`. HTTP handlers use
+`url_env`, optional `POST|PUT|PATCH`, bearer auth, signing secret, and timeout.
+Command handlers use `command_env` and timeout. Secrets stay in the environment.
+See [Writeback Executors](writeback-executors.md).
+
+## Policies and approvals
+
+`policies` is an array of reviewed policy objects. Local approval policies use
+`kind: "approval"` and numeric rules such as `{ "field": "amount_cents",
+"max": 2500 }`. Canonical policies may also carry daily `count` or `total`
+limits scoped to `tenant_policy` or `tenant_policy_object`. These limits come
+from reviewed DSL `LIMIT` clauses, not an unreviewed local override. A tripped
+limit falls back to human review and is recorded in the ledger.
+`approvals.disable_auto_approval: true` disables local policy auto-approval
+without changing the reviewed contract. Approval never becomes an MCP tool.
+
+## Operator identity
+
+Local development compatibility uses an explicitly unverified environment
+identity:
+
+```json
+{
+  "operator_identity": {
+    "provider": "dev_env",
+    "actor_env": "SYNAPSOR_OPERATOR_ID",
+    "roles_env": "SYNAPSOR_OPERATOR_ROLES",
+    "apply_roles": ["writeback_operator"]
+  }
+}
+```
+
+Shared or production-like operation should register signed operator keys:
+
+```json
+{
+  "operator_identity": {
+    "provider": "signed_key",
+    "apply_roles": ["writeback_operator"],
+    "operators": {
+      "alice": {
+        "public_key_path": "./operators/alice.pub.pem",
+        "roles": ["support_reviewer", "writeback_operator"]
+      }
+    }
+  }
+}
+```
+
+The public key path resolves relative to `synapsor.runner.json`. Keep the
+private key outside the repository and invoke decisions with `--identity alice
+--identity-key /secure/path/alice.pem`. Runner verifies key possession and the
+contract's required role, then binds the exact proposal hash/version, action,
+subject, timestamp, roles, signature, and integrity hash into the approval
+ledger. `apply_roles` independently gates writeback. The local browser UI
+refuses approval/rejection in signed-key mode so it cannot bypass this check.
+
+## Cloud mode
+
+Cloud mode omits local sources/capabilities and requires:
+
+```json
+{
+  "version": 1,
+  "mode": "cloud",
+  "cloud": {
+    "base_url_env": "SYNAPSOR_CLOUD_BASE_URL",
+    "runner_token_env": "SYNAPSOR_RUNNER_TOKEN",
+    "adapter_id": "mcp.billing",
+    "runner_id": "runner_local_1",
+    "project_id": "project_123",
+    "engines": ["postgres"],
+    "capabilities": ["adapter:read", "adapter:invoke"],
+    "session": {}
+  }
+}
+```
+
+`base_url_env`, `runner_token_env`, and `adapter_id` are required. Optional keys
+are `runner_id`, `runner_version`, `project_id`, `source_id`, `engines`, scoped
+capability permissions, and trusted session metadata.
+
+## Direct SQL readiness
+
+An administrator must apply `writeback migration` once. The steady-state writer
+needs target-table SELECT/allowed UPDATE plus receipt-table
+SELECT/INSERT/UPDATE; it does not need schema CREATE.
+
+```bash
+synapsor-runner writeback migration --engine postgres --schema synapsor
+synapsor-runner writeback grants --engine postgres \
+  --schema synapsor --writer-role synapsor_writer
+synapsor-runner doctor --config ./synapsor.runner.json --check-writeback
+```
+
+The doctor probe uses a rolled-back receipt insert and target-table check. It
+does not mutate business rows.

package/docs/security-boundary.md

@@ -66,11 +66,11 @@ outside the model-facing MCP server and verifies:
 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 also
-creates or writes `synapsor_writeback_receipts` for idempotency and replay, so
-the writer needs permission for that receipt table or an administrator must
-pre-create and grant it. If your database policy forbids Runner-managed receipt
-tables, use an app-owned `http_handler` or `command_handler` executor instead.
+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.
 
 When a capability uses an `http_handler` or `command_handler` executor, the
 same approval boundary applies. The runner sends a structured proposal/job

package/docs/store-lifecycle.md

@@ -9,6 +9,44 @@ Default path:
 ./.synapsor/local.db
 ```
 
+## Data sensitivity and permissions
+
+The ledger contains copies of the business fields allowed by each capability:
+visible before/after evidence, proposal diffs, actor/tenant metadata, query
+fingerprints, approvals, receipts, and replay events. Treat it like a scoped
+database extract, not disposable cache data.
+
+Runner creates new POSIX store files with owner-only mode `0600` and tightens an
+owned existing store when it opens it. On Windows, use the operating system's
+file ACLs. Use encrypted disks, restrict OS accounts, and set a retention policy
+appropriate for the visible business data.
+
+`KEEP OUT` fields and redacted query parameters are not written to normal
+evidence records. They do not make the rest of the ledger non-sensitive.
+
+Direct SQLite inspection is supported **read-only** for independent verification:
+
+```bash
+sqlite3 -readonly ./.synapsor/local.db '.tables'
+```
+
+Do not mutate the database directly. Its internal tables may change between
+releases and are not a public storage API; use Runner commands for automation.
+
+## Inspect the ledger
+
+| Question | Command |
+| --- | --- |
+| What did the model propose? | `synapsor-runner proposals show <proposal-id> --details` |
+| What data supported it? | `synapsor-runner evidence list --proposal <proposal-id>` then `evidence show <evidence-id> --details` |
+| What query was run? | `synapsor-runner query-audit list --proposal <proposal-id>` |
+| Who approved or rejected it? | `synapsor-runner proposals show <proposal-id> --details` |
+| Did guarded writeback apply? | `synapsor-runner receipts list --proposal <proposal-id>` |
+| What happened end to end? | `synapsor-runner replay show --proposal <proposal-id> --details` |
+| What happened to one object? | `synapsor-runner activity search --object invoice:INV-3001` |
+| What are the latest events? | `synapsor-runner events tail` |
+| How large is the store? | `synapsor-runner store stats --store ./.synapsor/local.db` |
+
 ## Server leases
 
 MCP server modes write a small lease file next to the store:

package/docs/writeback-executors.md

@@ -65,9 +65,9 @@ npx -y -p @synapsor/runner synapsor-runner writeback grants --engine postgres --
 ```
 
 `writeback doctor --check-db` connects with the configured writer credential and
-checks the receipt table path. That check can create the receipt table if the
-writer has `CREATE`, so run it only against staging/disposable databases or
-after reviewing the printed migration/grants.
+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`.
 
 ## `http_handler`
 

package/examples/mcp-postgres-billing-app-handler/schema.sql

@@ -40,6 +40,16 @@ CREATE TABLE IF NOT EXISTS public.account_credits (
   created_at timestamptz NOT NULL DEFAULT now()
 );
 
+CREATE TABLE IF NOT EXISTS public.synapsor_writeback_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
+);
+
 DO $$
 BEGIN
   IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'synapsor_reader') THEN
@@ -53,7 +63,7 @@ $$;
 
 GRANT CONNECT ON DATABASE synapsor_billing_app_handler TO synapsor_reader, synapsor_writer;
 GRANT USAGE ON SCHEMA public TO synapsor_reader, synapsor_writer;
-GRANT CREATE ON SCHEMA public TO synapsor_writer;
 GRANT SELECT ON public.tenants, public.customers, public.invoices, public.account_credits TO synapsor_reader, synapsor_writer;
+GRANT SELECT, INSERT, UPDATE ON public.synapsor_writeback_receipts TO synapsor_writer;
 GRANT UPDATE (late_fee_cents, waiver_reason, credit_requested_cents, credit_reason, credited_cents, updated_at) ON public.invoices TO synapsor_writer;
 GRANT INSERT ON public.account_credits TO synapsor_writer;

package/examples/reference-support-billing-app/schema.sql

@@ -47,6 +47,16 @@ CREATE TABLE IF NOT EXISTS public.orders (
   updated_at timestamptz NOT NULL DEFAULT now()
 );
 
+CREATE TABLE IF NOT EXISTS public.synapsor_writeback_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
+);
+
 DO $$
 BEGIN
   IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'synapsor_reader') THEN
@@ -60,8 +70,8 @@ $$;
 
 GRANT CONNECT ON DATABASE synapsor_reference_support_billing TO synapsor_reader, synapsor_writer;
 GRANT USAGE ON SCHEMA public TO synapsor_reader, synapsor_writer;
-GRANT CREATE ON SCHEMA public TO synapsor_writer;
 GRANT SELECT ON public.tenants, public.customers, public.support_tickets, public.invoices, public.orders TO synapsor_reader, synapsor_writer;
+GRANT SELECT, INSERT, UPDATE ON public.synapsor_writeback_receipts TO synapsor_writer;
 GRANT UPDATE (plan_credit_cents, credit_reason, updated_at) ON public.customers TO synapsor_writer;
 GRANT UPDATE (status, resolution_note, updated_at) ON public.support_tickets TO synapsor_writer;
 GRANT UPDATE (late_fee_cents, waiver_reason, updated_at) ON public.invoices TO synapsor_writer;

package/examples/support-billing-agent/db/schema.sql

@@ -70,6 +70,16 @@ CREATE TABLE IF NOT EXISTS public.orders (
   updated_at timestamptz NOT NULL DEFAULT now()
 );
 
+CREATE TABLE IF NOT EXISTS public.synapsor_writeback_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
+);
+
 DO $$
 BEGIN
   IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'synapsor_reader') THEN
@@ -83,8 +93,8 @@ $$;
 
 GRANT CONNECT ON DATABASE synapsor_support_billing_agent TO synapsor_reader, synapsor_writer;
 GRANT USAGE ON SCHEMA public TO synapsor_reader, synapsor_writer;
-GRANT CREATE ON SCHEMA public TO synapsor_writer;
 GRANT SELECT ON public.tenants, public.customers, public.support_tickets, public.invoices, public.credits, public.agent_actions, public.orders TO synapsor_reader, synapsor_writer;
+GRANT SELECT, INSERT, UPDATE ON public.synapsor_writeback_receipts TO synapsor_writer;
 GRANT UPDATE (plan_credit_cents, credit_reason, updated_at) ON public.customers TO synapsor_writer;
 GRANT UPDATE (status, resolution_note, updated_at) ON public.support_tickets TO synapsor_writer;
 GRANT UPDATE (late_fee_cents, waiver_reason, updated_at) ON public.invoices TO synapsor_writer;

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

@@ -196,10 +196,15 @@ The auto-approval policy lives in `contract.synapsor.sql`:
 
 ```sql
 AUTO APPROVE WHEN plan_credit_cents <= 2500
+LIMIT 20 PER DAY
+LIMIT TOTAL 100000 PER DAY
 ```
 
 That compiles into `synapsor.contract.json` as a reviewed approval policy. It is
-stored in git, validated by `@synapsor/spec`, and included in Cloud push payloads.
+stored in git, validated by `@synapsor/spec`, and included in Cloud push
+payloads. The policy may approve at most 20 qualifying credits or 100,000 cents
+in total per trusted tenant and UTC day. The first ceiling reached leaves later
+proposals in `pending_review` and records why the policy deferred to a human.
 
 To disable local policy approval without changing the contract:
 
@@ -214,6 +219,16 @@ To disable local policy approval without changing the contract:
 Auto-approval never applies the write. It only records an approval row and audit
 event with actor `policy:<policy_name>`.
 
+After reviewing the ceilings and running `doctor`, an operator can drain the
+approved queue without letting one stale-row conflict abort the remaining jobs:
+
+```bash
+synapsor-runner apply --all-approved --yes \
+  --capability support.propose_plan_credit --tenant acme --max 20 \
+  --config examples/support-plan-credit/synapsor.runner.json \
+  --store ./tmp/support-plan-credit/local.db
+```
+
 ## Cloud
 
 Dry-run the Cloud payload:

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

@@ -46,6 +46,8 @@ CREATE CAPABILITY support.propose_plan_credit
   BOUND plan_credit_cents 1..50000
   APPROVAL ROLE support_reviewer
   AUTO APPROVE WHEN plan_credit_cents <= 2500
+  LIMIT 20 PER DAY
+  LIMIT TOTAL 100000 PER DAY
   WRITEBACK DIRECT SQL
 END