@synapsor/runner 0.1.0-alpha.10 → 0.1.0-alpha.13

package/docs/writeback-executors.md

@@ -88,6 +88,7 @@ literal values.
         "type": "bearer_env",
         "token_env": "SYNAPSOR_BILLING_HANDLER_TOKEN"
       },
+      "signing_secret_env": "SYNAPSOR_BILLING_HANDLER_SIGNING_SECRET",
       "timeout_ms": 5000
     }
   },
@@ -114,6 +115,17 @@ The handler receives proposal fields, the exact patch, evidence metadata,
 guards, and an idempotency key. It does not receive arbitrary model SQL or DB
 credentials from Synapsor Runner.
 
+When `signing_secret_env` is set, Runner signs the exact JSON body with HMAC
+SHA-256 and sends:
+
+- `X-Synapsor-Signature: sha256=...`
+- `X-Synapsor-Issued-At: ...`
+- `X-Synapsor-Proposal-Id: ...`
+- `Idempotency-Key: ...`
+
+Use signing for any handler that is not strictly loopback-only and protected by
+another trusted boundary.
+
 Handler responses:
 
 ```json
@@ -139,6 +151,12 @@ receipt is stored in replay.
 Use your application/API for business logic. Use Synapsor Runner for proposal,
 approval, evidence, policy boundary, and replay.
 
+For TypeScript services, use the source-level helper in `packages/handler`.
+It verifies bearer/HMAC auth, parses the request, locks the target row with the
+tenant guard, checks the expected version, handles idempotency, wraps the
+business effect in a transaction, and returns safe receipts without raw driver
+errors. See [Handler Helper](handler-helper.md).
+
 This is the recommended path for writes that are richer than the current
 `sql_update` scope, such as:
 
@@ -159,6 +177,17 @@ Concrete business-action examples are in:
 examples/app-owned-writeback/business-actions.md
 ```
 
+The full disposable Postgres account-credit demo is in:
+
+```text
+examples/mcp-postgres-billing-app-handler/
+```
+
+It proves the rich-write path end to end: the model creates a proposal, the
+source DB is unchanged before approval, the app-owned handler inserts an
+`account_credits` row after approval, retry is idempotent, and replay stores the
+handler receipt.
+
 Or generate one into your app:
 
 ```bash

package/examples/app-owned-writeback/README.md

@@ -29,6 +29,7 @@ Add an executor and point one proposal capability at it:
         "type": "bearer_env",
         "token_env": "SYNAPSOR_APP_WRITEBACK_TOKEN"
       },
+      "signing_secret_env": "SYNAPSOR_APP_WRITEBACK_SIGNING_SECRET",
       "timeout_ms": 5000
     }
   },

package/examples/mcp-postgres-billing-app-handler/README.md

@@ -0,0 +1,86 @@
+# Postgres Billing App Handler
+
+This example shows the two Synapsor Runner commit paths against one disposable
+Postgres billing database.
+
+Direct guarded SQL writeback:
+
+- `billing.propose_late_fee_waiver`
+- one-row `UPDATE`;
+- tenant guard, allowed-column guard, conflict guard, idempotency receipt.
+
+App-owned rich writeback:
+
+- `billing.propose_account_credit`
+- model-facing MCP only creates a proposal;
+- approval happens outside MCP;
+- Runner calls `billing_app_handler`;
+- the app uses the first-party `@synapsor/handler` helper to verify bearer
+  auth, HMAC signature, tenant scope, expected row version, idempotency, and
+  transaction/receipt shape;
+- the handler business code inserts an `account_credits` row and updates the
+  invoice inside the helper-owned transaction;
+- Runner records the handler receipt and replay.
+
+The model never receives `execute_sql`, approval tools, commit/apply tools,
+database URLs, or write credentials.
+
+## Run
+
+From the repository root:
+
+```bash
+examples/mcp-postgres-billing-app-handler/scripts/run-demo.sh
+```
+
+Expected ending:
+
+```text
+App-owned billing handler demo passed.
+Verified: proposal first, source unchanged before approval, account credit inserted by app handler, idempotent retry, replay.
+```
+
+## Manual Start
+
+```bash
+docker compose -f examples/mcp-postgres-billing-app-handler/docker-compose.yml up -d
+
+export BILLING_APP_READ_URL="postgresql://synapsor_reader:synapsor_reader_password@localhost:55437/synapsor_billing_app_handler"
+export BILLING_APP_WRITE_URL="postgresql://synapsor_writer:synapsor_writer_password@localhost:55437/synapsor_billing_app_handler"
+export BILLING_APP_HANDLER_URL="http://127.0.0.1:8787/synapsor/writeback"
+export BILLING_APP_HANDLER_TOKEN="dev-handler-token"
+export BILLING_APP_HANDLER_SIGNING_SECRET="dev-handler-signing-secret"
+export SYNAPSOR_TENANT_ID="acme"
+export SYNAPSOR_PRINCIPAL="local_billing_operator"
+
+node examples/mcp-postgres-billing-app-handler/app-handler.mjs
+```
+
+Then, in another terminal:
+
+```bash
+synapsor-runner tools preview \
+  --config examples/mcp-postgres-billing-app-handler/synapsor.runner.json \
+  --store ./tmp/billing-app-handler/local.db
+
+synapsor-runner propose billing.propose_account_credit \
+  --json '{"invoice_id":"INV-3001","amount_cents":2500,"reason":"support-approved credit"}' \
+  --config examples/mcp-postgres-billing-app-handler/synapsor.runner.json \
+  --store ./tmp/billing-app-handler/local.db
+
+synapsor-runner proposals approve latest --yes --store ./tmp/billing-app-handler/local.db
+synapsor-runner apply latest \
+  --config examples/mcp-postgres-billing-app-handler/synapsor.runner.json \
+  --store ./tmp/billing-app-handler/local.db
+synapsor-runner replay show latest --store ./tmp/billing-app-handler/local.db
+```
+
+## Why This Exists
+
+Direct Runner SQL writeback should stay intentionally narrow. It is good for
+simple, bounded, single-row updates.
+
+For richer business transactions such as creating credits, refund reviews,
+ledger rows, tickets, events, or multi-row updates, keep execution in your
+application service. Synapsor Runner still owns proposal creation, evidence,
+approval boundary, idempotency, receipt storage, and replay.

package/examples/mcp-postgres-billing-app-handler/app-handler.mjs

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+import http from "node:http";
+
+const { createWritebackHandler } = await loadHandlerHelper();
+
+const port = Number(process.env.BILLING_APP_HANDLER_PORT || "8787");
+
+if (!process.env.BILLING_APP_WRITE_URL) {
+  console.error("BILLING_APP_WRITE_URL is required.");
+  process.exit(1);
+}
+
+const writebackHandler = createWritebackHandler({
+  tokenEnv: "BILLING_APP_HANDLER_TOKEN",
+  signingSecretEnv: "BILLING_APP_HANDLER_SIGNING_SECRET",
+  source: {
+    engine: "postgres",
+    writeUrlEnv: "BILLING_APP_WRITE_URL",
+    receiptTable: {
+      schema: "public",
+      table: "synapsor_handler_receipts",
+    },
+  },
+  capabilities: {
+    "billing.propose_account_credit": applyAccountCredit,
+  },
+});
+
+const server = http.createServer(async (request, response) => {
+  if (request.method === "GET" && request.url === "/healthz") {
+    return writeJson(response, 200, { ok: true });
+  }
+  if (request.method !== "POST" || request.url !== "/synapsor/writeback") {
+    return writeJson(response, 404, {
+      status: "failed",
+      rows_affected: 0,
+      safe_error_code: "NOT_FOUND",
+      source_database_mutated: false,
+    });
+  }
+  await writebackHandler(request, response);
+});
+
+server.listen(port, "127.0.0.1", () => {
+  console.error(`Billing app handler listening on http://127.0.0.1:${port}/synapsor/writeback`);
+});
+
+process.once("SIGINT", shutdown);
+process.once("SIGTERM", shutdown);
+
+async function shutdown() {
+  server.close();
+  process.exit(0);
+}
+
+async function applyAccountCredit(job, tx) {
+  const amountCents = Number(job.patch.credit_requested_cents);
+  const reason = String(job.patch.credit_reason || "approved account credit");
+  if (!Number.isInteger(amountCents) || amountCents <= 0) {
+    throw new Error("credit amount must be a positive integer");
+  }
+
+  const creditId = `CR-${job.proposalId.replace(/[^A-Za-z0-9]/g, "").slice(-12) || Date.now()}`;
+  await tx.insert("account_credits", {
+    id: creditId,
+    tenant_id: job.tenantId,
+    invoice_id: job.objectId,
+    customer_id: String(job.row.customer_id),
+    amount_cents: amountCents,
+    reason,
+    idempotency_key: job.idempotencyKey,
+    created_by: job.principal,
+  }, { schema: "public" });
+
+  const newVersion = new Date().toISOString();
+  const update = await tx.update("invoices", {
+    id: job.objectId,
+    tenant_id: job.tenantId,
+  }, {
+    credit_requested_cents: amountCents,
+    credit_reason: reason,
+    credited_cents: Number(job.row.credited_cents ?? 0) + amountCents,
+    updated_at: newVersion,
+  }, {
+    schema: "public",
+    returning: ["updated_at"],
+  });
+
+  if (update.rowCount !== 1) {
+    throw new Error("invoice update affected an unexpected number of rows");
+  }
+
+  return {
+    rowsAffected: 2,
+    newVersion: timestampString(update.rows[0]?.updated_at ?? newVersion),
+    effects: [
+      { type: "db.insert", table: "account_credits", id: creditId },
+      { type: "db.update", table: "invoices", id: job.objectId },
+      { type: "event", name: "billing.account_credit_created" },
+    ],
+  };
+}
+
+function timestampString(value) {
+  if (value instanceof Date) return value.toISOString();
+  return new Date(String(value)).toISOString();
+}
+
+function writeJson(response, statusCode, body) {
+  response.statusCode = statusCode;
+  response.setHeader("content-type", "application/json; charset=utf-8");
+  response.end(`${JSON.stringify(body, null, 2)}\n`);
+}
+
+async function loadHandlerHelper() {
+  try {
+    return await import("@synapsor/handler");
+  } catch (workspaceError) {
+    try {
+      return await import(new URL("./synapsor-handler.mjs", import.meta.url));
+    } catch {
+      throw workspaceError;
+    }
+  }
+}

package/examples/mcp-postgres-billing-app-handler/docker-compose.yml

@@ -0,0 +1,13 @@
+services:
+  postgres:
+    image: postgres:16
+    container_name: synapsor_runner_billing_app_handler
+    environment:
+      POSTGRES_DB: synapsor_billing_app_handler
+      POSTGRES_USER: synapsor_admin
+      POSTGRES_PASSWORD: synapsor_admin_password
+    ports:
+      - "55437:5432"
+    volumes:
+      - ./schema.sql:/docker-entrypoint-initdb.d/001_schema.sql:ro
+      - ./seed.sql:/docker-entrypoint-initdb.d/002_seed.sql:ro

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

@@ -0,0 +1,59 @@
+CREATE TABLE IF NOT EXISTS public.tenants (
+  id text PRIMARY KEY,
+  name text NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS public.customers (
+  id text PRIMARY KEY,
+  tenant_id text NOT NULL REFERENCES public.tenants(id),
+  name text NOT NULL,
+  plan text NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS public.invoices (
+  id text PRIMARY KEY,
+  tenant_id text NOT NULL REFERENCES public.tenants(id),
+  customer_id text NOT NULL REFERENCES public.customers(id),
+  status text NOT NULL,
+  balance_cents integer NOT NULL,
+  late_fee_cents integer NOT NULL,
+  waiver_reason text,
+  credit_requested_cents integer NOT NULL DEFAULT 0,
+  credit_reason text,
+  credited_cents integer NOT NULL DEFAULT 0,
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS public.account_credits (
+  id text PRIMARY KEY,
+  tenant_id text NOT NULL REFERENCES public.tenants(id),
+  invoice_id text NOT NULL REFERENCES public.invoices(id),
+  customer_id text NOT NULL REFERENCES public.customers(id),
+  amount_cents integer NOT NULL CHECK (amount_cents > 0),
+  reason text NOT NULL,
+  idempotency_key text NOT NULL UNIQUE,
+  created_by text NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+
+DO $$
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'synapsor_reader') THEN
+    CREATE ROLE synapsor_reader LOGIN PASSWORD 'synapsor_reader_password';
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'synapsor_writer') THEN
+    CREATE ROLE synapsor_writer LOGIN PASSWORD 'synapsor_writer_password';
+  END IF;
+END
+$$;
+
+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 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/mcp-postgres-billing-app-handler/scripts/run-demo.sh

@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
+EXAMPLE_DIR="$ROOT/examples/mcp-postgres-billing-app-handler"
+COMPOSE_FILE="$EXAMPLE_DIR/docker-compose.yml"
+CONFIG="$EXAMPLE_DIR/synapsor.runner.json"
+STORE="$ROOT/tmp/billing-app-handler/local.db"
+BIN="${SYNAPSOR_RUNNER_BIN:-$ROOT/bin/synapsor-runner}"
+HANDLER_LOG="$ROOT/tmp/billing-app-handler/handler.log"
+
+cleanup() {
+  if [[ -n "${HANDLER_PID:-}" ]]; then
+    kill "$HANDLER_PID" >/dev/null 2>&1 || true
+    wait "$HANDLER_PID" >/dev/null 2>&1 || true
+  fi
+  docker compose -f "$COMPOSE_FILE" down -v >/dev/null 2>&1 || true
+}
+trap cleanup EXIT
+
+mkdir -p "$ROOT/tmp/billing-app-handler"
+rm -f "$STORE" "$HANDLER_LOG"
+
+docker compose -f "$COMPOSE_FILE" down -v >/dev/null 2>&1 || true
+docker compose -f "$COMPOSE_FILE" up -d >/dev/null
+
+for _ in $(seq 1 90); do
+  invoice_count="$(docker exec synapsor_runner_billing_app_handler psql -U synapsor_admin -d synapsor_billing_app_handler -Atc "SELECT count(*) FROM public.invoices" 2>/dev/null || true)"
+  if [[ "$invoice_count" == "2" ]]; then
+    sleep 1
+    invoice_count="$(docker exec synapsor_runner_billing_app_handler psql -U synapsor_admin -d synapsor_billing_app_handler -Atc "SELECT count(*) FROM public.invoices" 2>/dev/null || true)"
+    if [[ "$invoice_count" == "2" ]]; then
+      break
+    fi
+  fi
+  sleep 1
+done
+invoice_count="$(docker exec synapsor_runner_billing_app_handler psql -U synapsor_admin -d synapsor_billing_app_handler -Atc "SELECT count(*) FROM public.invoices")"
+if [[ "$invoice_count" != "2" ]]; then
+  echo "Postgres fixture did not finish seeding invoices." >&2
+  exit 1
+fi
+
+export BILLING_APP_READ_URL="postgresql://synapsor_reader:synapsor_reader_password@localhost:55437/synapsor_billing_app_handler"
+export BILLING_APP_WRITE_URL="postgresql://synapsor_writer:synapsor_writer_password@localhost:55437/synapsor_billing_app_handler"
+export BILLING_APP_HANDLER_URL="http://127.0.0.1:8787/synapsor/writeback"
+export BILLING_APP_HANDLER_TOKEN="dev-handler-token"
+export BILLING_APP_HANDLER_SIGNING_SECRET="dev-handler-signing-secret"
+export SYNAPSOR_TENANT_ID="acme"
+export SYNAPSOR_PRINCIPAL="local_billing_operator"
+
+node "$EXAMPLE_DIR/app-handler.mjs" >"$HANDLER_LOG" 2>&1 &
+HANDLER_PID="$!"
+
+for _ in $(seq 1 90); do
+  if node -e "fetch('http://127.0.0.1:8787/healthz').then((r)=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))" >/dev/null 2>&1; then
+    break
+  fi
+  sleep 1
+done
+node -e "fetch('http://127.0.0.1:8787/healthz').then((r)=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"
+
+"$BIN" config validate --config "$CONFIG" >/dev/null
+"$BIN" tools preview --config "$CONFIG" --store "$STORE" > "$ROOT/tmp/billing-app-handler/tools.txt"
+grep -F "billing.propose_account_credit" "$ROOT/tmp/billing-app-handler/tools.txt" >/dev/null
+grep -F "execute_sql absent" "$ROOT/tmp/billing-app-handler/tools.txt" >/dev/null
+
+printf '{"invoice_id":"INV-3001","amount_cents":2500,"reason":"support-approved credit"}\n' > "$ROOT/tmp/billing-app-handler/credit-input.json"
+"$BIN" propose billing.propose_account_credit \
+  --input "$ROOT/tmp/billing-app-handler/credit-input.json" \
+  --config "$CONFIG" \
+  --store "$STORE" > "$ROOT/tmp/billing-app-handler/propose-credit.txt"
+grep -F "Source DB changed:" "$ROOT/tmp/billing-app-handler/propose-credit.txt" >/dev/null
+grep -F "no" "$ROOT/tmp/billing-app-handler/propose-credit.txt" >/dev/null
+
+credit_count_before="$(docker exec synapsor_runner_billing_app_handler psql -U synapsor_admin -d synapsor_billing_app_handler -Atc "SELECT count(*) FROM public.account_credits")"
+if [[ "$credit_count_before" != "0" ]]; then
+  echo "expected no account credits before approval, got $credit_count_before" >&2
+  exit 1
+fi
+
+"$BIN" proposals approve latest --yes --store "$STORE" >/dev/null
+"$BIN" apply latest --config "$CONFIG" --store "$STORE" > "$ROOT/tmp/billing-app-handler/apply-credit.txt"
+grep -F "App-owned writeback applied." "$ROOT/tmp/billing-app-handler/apply-credit.txt" >/dev/null
+grep -F "source database changed by handler: yes" "$ROOT/tmp/billing-app-handler/apply-credit.txt" >/dev/null
+
+credit_count_after="$(docker exec synapsor_runner_billing_app_handler psql -U synapsor_admin -d synapsor_billing_app_handler -Atc "SELECT count(*) FROM public.account_credits WHERE invoice_id = 'INV-3001' AND amount_cents = 2500")"
+if [[ "$credit_count_after" != "1" ]]; then
+  echo "expected one inserted account credit, got $credit_count_after" >&2
+  exit 1
+fi
+
+"$BIN" apply latest --config "$CONFIG" --store "$STORE" > "$ROOT/tmp/billing-app-handler/apply-credit-retry.txt"
+grep -F "App-owned writeback already applied." "$ROOT/tmp/billing-app-handler/apply-credit-retry.txt" >/dev/null
+
+"$BIN" replay show latest --store "$STORE" > "$ROOT/tmp/billing-app-handler/replay.txt"
+grep -F "billing.propose_account_credit" "$ROOT/tmp/billing-app-handler/replay.txt" >/dev/null
+
+echo "App-owned billing handler demo passed."
+echo "Verified: proposal first, source unchanged before approval, account credit inserted by app handler, idempotent retry, replay."

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

@@ -0,0 +1,39 @@
+INSERT INTO public.tenants (id, name, created_at, updated_at)
+VALUES
+  ('acme', 'Acme Robotics', '2026-06-20T10:00:00Z', '2026-06-20T10:00:00Z'),
+  ('globex', 'Globex Labs', '2026-06-20T10:00:00Z', '2026-06-20T10:00:00Z')
+ON CONFLICT (id) DO UPDATE SET name = EXCLUDED.name, updated_at = EXCLUDED.updated_at;
+
+INSERT INTO public.customers (id, tenant_id, name, plan, created_at, updated_at)
+VALUES
+  ('cust_acme_1', 'acme', 'Acme Robotics', 'enterprise', '2026-06-20T10:00:00Z', '2026-06-20T10:00:00Z'),
+  ('cust_globex_1', 'globex', 'Globex Labs', 'builder', '2026-06-20T10:00:00Z', '2026-06-20T10:00:00Z')
+ON CONFLICT (id) DO UPDATE SET tenant_id = EXCLUDED.tenant_id, name = EXCLUDED.name, plan = EXCLUDED.plan, updated_at = EXCLUDED.updated_at;
+
+INSERT INTO public.invoices (
+  id,
+  tenant_id,
+  customer_id,
+  status,
+  balance_cents,
+  late_fee_cents,
+  waiver_reason,
+  credit_requested_cents,
+  credit_reason,
+  credited_cents,
+  updated_at
+)
+VALUES
+  ('INV-3001', 'acme', 'cust_acme_1', 'overdue', 25500, 5500, NULL, 0, NULL, 0, '2026-06-20T14:31:08Z'),
+  ('INV-9001', 'globex', 'cust_globex_1', 'overdue', 25500, 5500, NULL, 0, NULL, 0, '2026-06-20T14:31:08Z')
+ON CONFLICT (id) DO UPDATE SET
+  tenant_id = EXCLUDED.tenant_id,
+  customer_id = EXCLUDED.customer_id,
+  status = EXCLUDED.status,
+  balance_cents = EXCLUDED.balance_cents,
+  late_fee_cents = EXCLUDED.late_fee_cents,
+  waiver_reason = EXCLUDED.waiver_reason,
+  credit_requested_cents = EXCLUDED.credit_requested_cents,
+  credit_reason = EXCLUDED.credit_reason,
+  credited_cents = EXCLUDED.credited_cents,
+  updated_at = EXCLUDED.updated_at;