@synapsor/runner 0.1.0-alpha.9 → 0.1.1

package/docs/writeback-executors.md

@@ -56,6 +56,19 @@ 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.
 
+Use the helper commands before enabling direct SQL writeback:
+
+```bash
+npx -y -p @synapsor/runner synapsor-runner writeback doctor --config ./synapsor.runner.json
+npx -y -p @synapsor/runner synapsor-runner writeback migration --engine postgres
+npx -y -p @synapsor/runner synapsor-runner writeback grants --engine postgres --writer-role app_writer
+```
+
+`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.
+
 ## `http_handler`
 
 Use `http_handler` when your application/API should own business execution.
@@ -75,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
     }
   },
@@ -91,7 +105,7 @@ literal values.
 Run after approval:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner apply \
+npx -y -p @synapsor/runner synapsor-runner apply \
   --proposal wrp_123 \
   --config ./synapsor.runner.json \
   --store ./.synapsor/local.db
@@ -101,6 +115,24 @@ 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.
 
+> **Important:** your app handler owns the final business write. Runner creates
+> the proposal and calls your handler only after approval, but your handler must
+> still enforce tenant/scope checks, expected-version or conflict guards,
+> idempotency keys, allowed business actions, transaction/rollback, and safe
+> error receipts. If you skip those checks, you can reintroduce cross-tenant
+> writes, lost updates, or duplicate writes. Keep handler credentials out of MCP.
+
+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
@@ -126,6 +158,56 @@ 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:
+
+- creating a refund review;
+- inserting an account credit row;
+- opening a support ticket;
+- updating multiple related rows in one app transaction.
+
+Starter templates are in:
+
+```text
+examples/app-owned-writeback/
+```
+
+Concrete business-action examples are in:
+
+```text
+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
+npx -y -p @synapsor/runner synapsor-runner handler template node-fastify \
+  --output ./synapsor-writeback-handler.mjs
+
+npx -y -p @synapsor/runner synapsor-runner handler template python-fastapi \
+  --output ./synapsor_writeback_handler.py
+
+npx -y -p @synapsor/runner synapsor-runner handler template command \
+  --output ./synapsor-command-handler.mjs
+```
+
 ## `command_handler`
 
 `command_handler` is a local integration path for scripts:
@@ -145,6 +227,15 @@ approval, evidence, policy boundary, and replay.
 The command receives the same structured JSON request on stdin and should print
 a JSON receipt body on stdout.
 
+> **Important:** command handlers have the same responsibility as HTTP
+> handlers. Re-check tenant/scope, expected-version or conflict guard,
+> idempotency, allowed business action, transaction/rollback, and safe error
+> receipt before mutating state. Otherwise the script can reintroduce
+> cross-tenant writes, lost updates, or duplicate writes.
+
+Use `examples/app-owned-writeback/command-handler.mjs` as a starting point when
+your safest apply path is an app script or job runner.
+
 ## Safety Boundary
 
 Executor secrets are never exposed over MCP. The model never receives:

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

@@ -0,0 +1,128 @@
+# App-Owned Writeback Templates
+
+Use app-owned writeback when an approved Synapsor proposal should be executed
+by your application service instead of Runner writing SQL directly.
+
+This is the right path for rich business actions:
+
+- create a refund review;
+- insert an account credit row;
+- open a support ticket;
+- update multiple related rows through your app service.
+
+The model-facing MCP tool still only creates a proposal. Approval happens
+outside MCP. After approval, `synapsor-runner apply` sends a structured request
+to your handler, and the handler returns an execution receipt for replay.
+
+> **Important:** your app handler owns the final business write. Runner creates
+> the proposal and calls your handler only after approval, but your handler must
+> still enforce tenant/scope checks, expected-version or conflict guards,
+> idempotency keys, allowed business actions, transaction/rollback, and safe
+> error receipts. If you skip those checks, you can reintroduce cross-tenant
+> writes, lost updates, or duplicate writes. Keep handler credentials out of MCP.
+
+## Config Snippet
+
+Add an executor and point one proposal capability at it:
+
+```json
+{
+  "executors": {
+    "app_writeback_api": {
+      "type": "http_handler",
+      "url_env": "SYNAPSOR_APP_WRITEBACK_URL",
+      "method": "POST",
+      "auth": {
+        "type": "bearer_env",
+        "token_env": "SYNAPSOR_APP_WRITEBACK_TOKEN"
+      },
+      "signing_secret_env": "SYNAPSOR_APP_WRITEBACK_SIGNING_SECRET",
+      "timeout_ms": 5000
+    }
+  },
+  "capabilities": [
+    {
+      "name": "refunds.propose_refund_review",
+      "kind": "proposal",
+      "executor": "app_writeback_api"
+    }
+  ]
+}
+```
+
+Run after approval:
+
+```bash
+export SYNAPSOR_APP_WRITEBACK_URL="http://127.0.0.1:8787/synapsor/writeback"
+export SYNAPSOR_APP_WRITEBACK_TOKEN="dev-handler-token"
+
+synapsor-runner apply \
+  --proposal wrp_... \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+```
+
+## Handler Request Shape
+
+Your handler receives JSON like:
+
+```json
+{
+  "schema_version": "synapsor.handler-writeback.v1",
+  "writeback_job_id": "hwb_wrp_...",
+  "proposal_id": "wrp_...",
+  "idempotency_key": "wrp_...",
+  "change_set": {
+    "action": "refunds.propose_refund_review",
+    "scope": {
+      "tenant_id": "acme",
+      "object_id": "INV-3001"
+    },
+    "before": {},
+    "patch": {},
+    "after": {},
+    "guards": {},
+    "evidence": {
+      "bundle_id": "ev_..."
+    }
+  },
+  "executor": "app_writeback_api",
+  "dry_run": false
+}
+```
+
+Do not trust request fields blindly. Your service should re-check tenant,
+principal, authorization, idempotency, row versions, and business rules before
+mutating state.
+
+## Handler Response Shape
+
+Return one terminal receipt:
+
+```json
+{
+  "status": "applied",
+  "rows_affected": 1,
+  "previous_version": "2026-06-20T14:31:08Z",
+  "new_version": "2026-06-20T14:34:19Z",
+  "source_database_mutated": true
+}
+```
+
+Allowed statuses:
+
+- `applied`
+- `already_applied`
+- `conflict`
+- `failed`
+
+## Templates
+
+- `node-fastify-handler.mjs`: HTTP handler template for a Node/Fastify service.
+- `python-fastapi-handler.py`: HTTP handler template for a Python/FastAPI service.
+- `command-handler.mjs`: local command handler template for scripts.
+- `business-actions.md`: concrete examples for refund reviews, account
+  credits, support tickets, and multi-row app transactions.
+
+Each template returns safe demo receipts and marks where your application
+should run its own transaction.

package/examples/app-owned-writeback/business-actions.md

@@ -0,0 +1,221 @@
+# App-Owned Business Action Examples
+
+These examples show the kinds of approved proposals an app-owned handler can
+apply. They are intentionally not direct SQL examples. Your application service
+owns the write transaction, re-checks authorization and row/version guards, and
+returns a terminal receipt to Synapsor Runner.
+
+Each request uses the same boundary:
+
+```text
+model-facing MCP tool -> proposal
+human/operator approval -> app-owned handler
+handler transaction -> applied/conflict/failed receipt
+local replay
+```
+
+The handler must not trust request fields blindly. Re-check tenant,
+principal/role, idempotency, row versions, and business policy before mutating
+state.
+
+## Create A Refund Review
+
+Use this when an agent may request a refund review, but your application must
+create the review record through normal business logic.
+
+Capability:
+
+```text
+refunds.propose_refund_review(order_id, reason, requested_amount_cents)
+```
+
+Handler request:
+
+```json
+{
+  "schema_version": "synapsor.handler-writeback.v1",
+  "writeback_job_id": "hwb_wrp_refund_001",
+  "proposal_id": "wrp_refund_001",
+  "idempotency_key": "wrp_refund_001",
+  "change_set": {
+    "action": "refunds.propose_refund_review",
+    "scope": {
+      "tenant_id": "acme",
+      "principal": "support_lead@example.com",
+      "object_type": "order",
+      "object_id": "ORD-3001"
+    },
+    "before": {
+      "order_status": "delivered",
+      "refund_review_id": null
+    },
+    "patch": {
+      "requested_amount_cents": 2500,
+      "reason": "duplicate charge"
+    },
+    "after": {
+      "refund_review_status": "pending_review"
+    },
+    "guards": {
+      "expected_version": {
+        "column": "updated_at",
+        "value": "2026-06-20T14:31:08Z"
+      }
+    },
+    "evidence": {
+      "bundle_id": "ev_refund_001"
+    }
+  },
+  "executor": "app_writeback_api",
+  "dry_run": false
+}
+```
+
+Handler transaction sketch:
+
+```text
+BEGIN
+  verify principal can request refunds for tenant acme
+  verify order ORD-3001 still belongs to tenant acme
+  verify order.updated_at still matches expected_version
+  verify no receipt exists for idempotency_key
+  INSERT INTO refund_reviews (...)
+  INSERT INTO synapsor_app_receipts (...)
+COMMIT
+```
+
+Receipt:
+
+```json
+{
+  "status": "applied",
+  "rows_affected": 1,
+  "new_object_id": "RR-9001",
+  "source_database_mutated": true
+}
+```
+
+## Insert An Account Credit Row
+
+Use this when the safe write is an append-only ledger/accounting operation.
+
+Capability:
+
+```text
+credits.propose_account_credit(customer_id, amount_cents, reason)
+```
+
+Handler transaction sketch:
+
+```text
+BEGIN
+  verify customer belongs to trusted tenant
+  verify amount is within app policy
+  verify idempotency_key has not already created a credit
+  INSERT INTO account_credits (...)
+  UPDATE customers SET credit_balance_cents = credit_balance_cents + amount
+  INSERT INTO synapsor_app_receipts (...)
+COMMIT
+```
+
+Conflict receipt if the app policy no longer allows the credit:
+
+```json
+{
+  "status": "conflict",
+  "safe_error_code": "CREDIT_POLICY_CHANGED",
+  "source_database_mutated": false,
+  "details": {
+    "reason": "customer credit limit changed after proposal"
+  }
+}
+```
+
+## Open A Support Ticket
+
+Use this when the agent may propose opening a ticket, but ticket creation must
+go through your helpdesk/application service.
+
+Capability:
+
+```text
+support.propose_open_ticket(customer_id, subject, body)
+```
+
+Handler transaction sketch:
+
+```text
+BEGIN
+  verify principal can open support tickets for tenant
+  verify customer belongs to tenant
+  validate subject/body against app policy
+  INSERT INTO support_tickets (...)
+  INSERT INTO ticket_events (...)
+  INSERT INTO synapsor_app_receipts (...)
+COMMIT
+```
+
+Receipt:
+
+```json
+{
+  "status": "applied",
+  "rows_affected": 2,
+  "new_object_id": "T-9100",
+  "source_database_mutated": true
+}
+```
+
+## Update Multiple Related Rows
+
+Use this when an approved business action spans several tables and should stay
+inside your normal application transaction.
+
+Capability:
+
+```text
+subscriptions.propose_trial_extension(customer_id, extension_days, reason)
+```
+
+Handler transaction sketch:
+
+```text
+BEGIN
+  verify tenant/principal authorization
+  SELECT subscription FOR UPDATE
+  verify expected subscription version
+  UPDATE subscriptions SET trial_ends_at = ...
+  INSERT INTO customer_events (...)
+  INSERT INTO billing_notes (...)
+  INSERT INTO synapsor_app_receipts (...)
+COMMIT
+```
+
+Receipt:
+
+```json
+{
+  "status": "applied",
+  "rows_affected": 3,
+  "previous_version": "2026-06-20T14:31:08Z",
+  "new_version": "2026-06-20T14:34:19Z",
+  "source_database_mutated": true
+}
+```
+
+## Idempotent Retry
+
+If the same `idempotency_key` reaches your handler again after a successful
+apply, return `already_applied` and the original receipt details rather than
+running the transaction again.
+
+```json
+{
+  "status": "already_applied",
+  "rows_affected": 0,
+  "source_database_mutated": false,
+  "details": {
+    "original_receipt_id": "rct_abc123"
+  }
+}
+```

package/examples/app-owned-writeback/command-handler.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+
+const chunks = [];
+for await (const chunk of process.stdin) chunks.push(chunk);
+
+const request = JSON.parse(Buffer.concat(chunks).toString("utf8") || "{}");
+const changeSet = request.change_set || {};
+
+if (!request.proposal_id || !request.idempotency_key || !changeSet.scope?.tenant_id) {
+  process.stdout.write(JSON.stringify({
+    status: "failed",
+    safe_error_code: "BAD_WRITEBACK_REQUEST",
+    source_database_mutated: false,
+  }));
+  process.exit(0);
+}
+
+if (request.dry_run) {
+  process.stdout.write(JSON.stringify({
+    status: "applied",
+    rows_affected: 0,
+    source_database_mutated: false,
+    details: { dry_run: true },
+  }));
+  process.exit(0);
+}
+
+/*
+ * IMPORTANT: your app handler owns the final business write.
+ * Runner creates the proposal and calls your handler only after approval,
+ * but your handler must still enforce tenant/scope, expected-version or
+ * conflict guard, idempotency key, allowed business action,
+ * transaction/rollback, and safe error receipt.
+ *
+ * If you skip those checks, you can reintroduce cross-tenant writes,
+ * lost updates, or duplicate writes. Keep handler credentials out of MCP.
+ *
+ * Put your app-owned command transaction here.
+ *
+ * Examples:
+ * - call an internal service;
+ * - enqueue a review job;
+ * - run an app migration-safe script that uses your normal ORM.
+ *
+ * Re-check tenant/principal authorization, idempotency, row/version guards,
+ * and business policy before mutating application state.
+ */
+
+process.stdout.write(JSON.stringify({
+  status: "applied",
+  rows_affected: 1,
+  previous_version: String(changeSet.guards?.expected_version?.value || ""),
+  new_version: new Date().toISOString(),
+  source_database_mutated: true,
+}));

package/examples/app-owned-writeback/node-fastify-handler.mjs

@@ -0,0 +1,64 @@
+import Fastify from "fastify";
+
+const port = Number(process.env.PORT || 8787);
+const expectedToken = process.env.SYNAPSOR_APP_WRITEBACK_TOKEN || "dev-handler-token";
+
+const app = Fastify({ logger: true });
+
+app.post("/synapsor/writeback", async (request, reply) => {
+  const auth = request.headers.authorization || "";
+  if (auth !== `Bearer ${expectedToken}`) {
+    return reply.code(401).send({ status: "failed", error_code: "UNAUTHORIZED" });
+  }
+
+  const body = request.body || {};
+  const changeSet = body.change_set || {};
+
+  if (!body.proposal_id || !body.idempotency_key || !changeSet.scope?.tenant_id) {
+    return reply.code(400).send({ status: "failed", error_code: "BAD_WRITEBACK_REQUEST" });
+  }
+
+  if (body.dry_run) {
+    return {
+      status: "applied",
+      rows_affected: 0,
+      source_database_mutated: false,
+      details: { dry_run: true },
+    };
+  }
+
+  /*
+   * IMPORTANT: your app handler owns the final business write.
+   * Runner creates the proposal and calls your handler only after approval,
+   * but your handler must still enforce tenant/scope, expected-version or
+   * conflict guard, idempotency key, allowed business action,
+   * transaction/rollback, and safe error receipt.
+   *
+   * If you skip those checks, you can reintroduce cross-tenant writes,
+   * lost updates, or duplicate writes. Keep handler credentials out of MCP.
+   *
+   * Put your app-owned transaction here.
+   *
+   * Examples:
+   * - insert a refund_review row;
+   * - insert an account_credit row;
+   * - open a support_ticket row;
+   * - update invoice + ledger rows together.
+   *
+   * Re-check:
+   * - tenant and principal authorization;
+   * - idempotency_key has not already been applied;
+   * - row/version guards still match;
+   * - requested business action is allowed by your app policy.
+   */
+
+  return {
+    status: "applied",
+    rows_affected: 1,
+    previous_version: String(changeSet.guards?.expected_version?.value || ""),
+    new_version: new Date().toISOString(),
+    source_database_mutated: true,
+  };
+});
+
+app.listen({ host: "127.0.0.1", port });

package/examples/app-owned-writeback/python-fastapi-handler.py

@@ -0,0 +1,66 @@
+import os
+from datetime import datetime, timezone
+
+from fastapi import FastAPI, Header, HTTPException
+from pydantic import BaseModel
+
+
+class HandlerRequest(BaseModel):
+    schema_version: str
+    writeback_job_id: str
+    proposal_id: str
+    idempotency_key: str
+    change_set: dict
+    executor: str | None = None
+    dry_run: bool = False
+
+
+app = FastAPI()
+EXPECTED_TOKEN = os.environ.get("SYNAPSOR_APP_WRITEBACK_TOKEN", "dev-handler-token")
+
+
+@app.post("/synapsor/writeback")
+def writeback(request: HandlerRequest, authorization: str | None = Header(default=None)):
+    if authorization != f"Bearer {EXPECTED_TOKEN}":
+        raise HTTPException(status_code=401, detail="UNAUTHORIZED")
+
+    scope = request.change_set.get("scope", {})
+    if not scope.get("tenant_id"):
+        raise HTTPException(status_code=400, detail="BAD_WRITEBACK_REQUEST")
+
+    if request.dry_run:
+        return {
+            "status": "applied",
+            "rows_affected": 0,
+            "source_database_mutated": False,
+            "details": {"dry_run": True},
+        }
+
+    # IMPORTANT: your app handler owns the final business write.
+    # Runner creates the proposal and calls your handler only after approval,
+    # but your handler must still enforce tenant/scope, expected-version or
+    # conflict guard, idempotency key, allowed business action,
+    # transaction/rollback, and safe error receipt.
+    #
+    # If you skip those checks, you can reintroduce cross-tenant writes,
+    # lost updates, or duplicate writes. Keep handler credentials out of MCP.
+    #
+    # Put your app-owned transaction here.
+    #
+    # Examples:
+    # - insert a refund_review row;
+    # - insert an account_credit row;
+    # - open a support_ticket row;
+    # - update invoice + ledger rows together.
+    #
+    # Re-check tenant/principal authorization, idempotency, row/version guards,
+    # and business policy before mutating application state.
+
+    expected = request.change_set.get("guards", {}).get("expected_version", {})
+    return {
+        "status": "applied",
+        "rows_affected": 1,
+        "previous_version": str(expected.get("value", "")),
+        "new_version": datetime.now(timezone.utc).isoformat(),
+        "source_database_mutated": True,
+    }

package/examples/claude-desktop-postgres/Makefile

@@ -0,0 +1,6 @@
+.PHONY: config
+
+config:
+	cd ../.. && corepack pnpm runner mcp config claude-desktop \
+	  --config ./examples/mcp-postgres-billing/synapsor.runner.json \
+	  --store ./.synapsor/local.db