@synapsor/runner 0.1.0-alpha.1 → 0.1.0-alpha.11

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,46 @@
+#!/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);
+}
+
+/*
+ * 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,55 @@
+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 },
+    };
+  }
+
+  /*
+   * 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,57 @@
+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},
+        }
+
+    # 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/dangerous-mcp-tools.json

@@ -0,0 +1,88 @@
+{
+  "tools": [
+    {
+      "name": "execute_sql",
+      "description": "Execute arbitrary SQL against the application database.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "sql": { "type": "string" }
+        },
+        "required": ["sql"]
+      }
+    },
+    {
+      "name": "run_query",
+      "description": "Run any query and return database rows.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "query": { "type": "string" },
+          "table": { "type": "string" },
+          "columns": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        },
+        "required": ["query"]
+      }
+    },
+    {
+      "name": "approve_refund",
+      "description": "Approve and issue a customer refund immediately.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "refund_id": { "type": "string" },
+          "tenant_id": { "type": "string" },
+          "amount_cents": { "type": "number" }
+        },
+        "required": ["refund_id", "tenant_id", "amount_cents"]
+      }
+    },
+    {
+      "name": "update_customer",
+      "description": "Update a customer record directly.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "customer_id": { "type": "string" },
+          "tenant_id": { "type": "string" },
+          "column": { "type": "string" },
+          "value": { "type": "string" }
+        },
+        "required": ["customer_id", "tenant_id", "column", "value"]
+      }
+    },
+    {
+      "name": "delete_order",
+      "description": "Delete an order from the database.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "order_id": { "type": "string" },
+          "tenant_id": { "type": "string" }
+        },
+        "required": ["order_id", "tenant_id"]
+      }
+    },
+    {
+      "name": "query_database",
+      "description": "Query arbitrary tables and columns from the database.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "database": { "type": "string" },
+          "schema": { "type": "string" },
+          "table": { "type": "string" },
+          "columns": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "where": { "type": "string" }
+        },
+        "required": ["table"]
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,82 @@
+# 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 inserts an `account_credits` row and updates the invoice inside its
+  own 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 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.