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

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

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+import http from "node:http";
+import { createRequire } from "node:module";
+
+const { Pool } = await loadPg();
+
+const port = Number(process.env.BILLING_APP_HANDLER_PORT || "8787");
+const expectedToken = process.env.BILLING_APP_HANDLER_TOKEN || "dev-handler-token";
+const databaseUrl = process.env.BILLING_APP_WRITE_URL;
+
+if (!databaseUrl) {
+  console.error("BILLING_APP_WRITE_URL is required.");
+  process.exit(1);
+}
+
+const pool = new Pool({ connectionString: databaseUrl });
+
+const server = http.createServer(async (request, response) => {
+  try {
+    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", safe_error_code: "NOT_FOUND", source_database_mutated: false });
+    }
+    if (request.headers.authorization !== `Bearer ${expectedToken}`) {
+      return writeJson(response, 401, { status: "failed", safe_error_code: "UNAUTHORIZED", source_database_mutated: false });
+    }
+    const body = await readJson(request);
+    const receipt = await applyAccountCredit(body);
+    return writeJson(response, 200, receipt);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return writeJson(response, 500, {
+      status: "failed",
+      safe_error_code: "HANDLER_EXCEPTION",
+      source_database_mutated: false,
+      details: { message: message.slice(0, 300) },
+    });
+  }
+});
+
+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();
+  await pool.end();
+  process.exit(0);
+}
+
+async function applyAccountCredit(request) {
+  const changeSet = request.change_set || request;
+  if (changeSet.action !== "billing.propose_account_credit") {
+    return {
+      status: "failed",
+      safe_error_code: "UNSUPPORTED_ACTION",
+      source_database_mutated: false,
+    };
+  }
+
+  const proposalId = String(request.proposal_id || "");
+  const idempotencyKey = String(request.idempotency_key || proposalId);
+  const tenantId = String(changeSet.scope?.tenant_id || changeSet.tenant_guard?.value || changeSet.guards?.tenant?.value || "");
+  const principal = String(changeSet.principal?.id || changeSet.runner_hint || "approved_operator");
+  const invoiceId = String(changeSet.scope?.object_id || changeSet.target?.primary_key?.value || changeSet.source?.primary_key?.value || "");
+  const amountCents = Number(changeSet.patch?.credit_requested_cents);
+  const reason = String(changeSet.patch?.credit_reason || "approved account credit");
+  const expectedVersion = changeSet.guards?.expected_version?.value;
+
+  if (!proposalId || !tenantId || !invoiceId || !Number.isInteger(amountCents) || amountCents <= 0 || !expectedVersion) {
+    return {
+      status: "failed",
+      safe_error_code: "BAD_WRITEBACK_REQUEST",
+      source_database_mutated: false,
+    };
+  }
+
+  const client = await pool.connect();
+  try {
+    await client.query("BEGIN");
+
+    const duplicate = await client.query(
+      "SELECT id FROM public.account_credits WHERE idempotency_key = $1",
+      [idempotencyKey],
+    );
+    if (duplicate.rowCount && duplicate.rows[0]) {
+      await client.query("COMMIT");
+      return {
+        status: "already_applied",
+        rows_affected: 0,
+        source_database_mutated: false,
+        details: {
+          credit_id: duplicate.rows[0].id,
+        },
+      };
+    }
+
+    const invoiceResult = await client.query(
+      "SELECT id, tenant_id, customer_id, updated_at FROM public.invoices WHERE id = $1 AND tenant_id = $2 FOR UPDATE",
+      [invoiceId, tenantId],
+    );
+    const invoice = invoiceResult.rows[0];
+    if (!invoice) {
+      await client.query("ROLLBACK");
+      return {
+        status: "conflict",
+        rows_affected: 0,
+        safe_error_code: "INVOICE_NOT_FOUND_OR_WRONG_TENANT",
+        source_database_mutated: false,
+      };
+    }
+
+    const currentVersion = timestampString(invoice.updated_at);
+    const expected = timestampString(expectedVersion);
+    if (currentVersion !== expected) {
+      await client.query("ROLLBACK");
+      return {
+        status: "conflict",
+        rows_affected: 0,
+        previous_version: currentVersion,
+        safe_error_code: "ROW_CHANGED_AFTER_PROPOSAL",
+        source_database_mutated: false,
+      };
+    }
+
+    const creditId = `CR-${proposalId.replace(/[^A-Za-z0-9]/g, "").slice(-12) || Date.now()}`;
+    await client.query(
+      `INSERT INTO public.account_credits
+        (id, tenant_id, invoice_id, customer_id, amount_cents, reason, idempotency_key, created_by)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8)`,
+      [creditId, tenantId, invoiceId, invoice.customer_id, amountCents, reason, idempotencyKey, principal],
+    );
+    const update = await client.query(
+      `UPDATE public.invoices
+       SET credit_requested_cents = $1,
+           credit_reason = $2,
+           credited_cents = credited_cents + $1,
+           updated_at = now()
+       WHERE id = $3 AND tenant_id = $4
+       RETURNING updated_at`,
+      [amountCents, reason, invoiceId, tenantId],
+    );
+    await client.query("COMMIT");
+
+    return {
+      status: "applied",
+      rows_affected: 2,
+      previous_version: currentVersion,
+      new_version: timestampString(update.rows[0]?.updated_at),
+      source_database_mutated: true,
+      details: {
+        effects: [
+          { type: "db.insert", table: "account_credits", id: creditId },
+          { type: "db.update", table: "invoices", id: invoiceId },
+          { type: "event", name: "billing.account_credit_created" },
+        ],
+      },
+    };
+  } catch (error) {
+    await client.query("ROLLBACK").catch(() => {});
+    throw error;
+  } finally {
+    client.release();
+  }
+}
+
+function timestampString(value) {
+  if (value instanceof Date) return value.toISOString().replace(".000Z", "Z");
+  return new Date(String(value)).toISOString().replace(".000Z", "Z");
+}
+
+async function readJson(request) {
+  const chunks = [];
+  for await (const chunk of request) chunks.push(Buffer.from(chunk));
+  const text = Buffer.concat(chunks).toString("utf8");
+  return text ? JSON.parse(text) : {};
+}
+
+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 loadPg() {
+  try {
+    return await import("pg");
+  } catch {
+    const requireFromRunnerPackage = createRequire(new URL("../../apps/runner/package.json", import.meta.url));
+    return requireFromRunnerPackage("pg");
+  }
+}

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,99 @@
+#!/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 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;

package/examples/mcp-postgres-billing-app-handler/synapsor.runner.json

@@ -0,0 +1,157 @@
+{
+  "version": 1,
+  "mode": "review",
+  "storage": {
+    "sqlite_path": "./tmp/billing-app-handler/local.db"
+  },
+  "sources": {
+    "billing_postgres": {
+      "engine": "postgres",
+      "read_url_env": "BILLING_APP_READ_URL",
+      "write_url_env": "BILLING_APP_WRITE_URL",
+      "statement_timeout_ms": 3000
+    }
+  },
+  "trusted_context": {
+    "provider": "environment",
+    "values": {
+      "tenant_id_env": "SYNAPSOR_TENANT_ID",
+      "principal_env": "SYNAPSOR_PRINCIPAL"
+    }
+  },
+  "contexts": {
+    "local_operator": {
+      "provider": "environment",
+      "values": {
+        "tenant_id_env": "SYNAPSOR_TENANT_ID",
+        "principal_env": "SYNAPSOR_PRINCIPAL"
+      }
+    }
+  },
+  "executors": {
+    "billing_app_handler": {
+      "type": "http_handler",
+      "url_env": "BILLING_APP_HANDLER_URL",
+      "method": "POST",
+      "auth": {
+        "type": "bearer_env",
+        "token_env": "BILLING_APP_HANDLER_TOKEN"
+      },
+      "timeout_ms": 5000
+    }
+  },
+  "capabilities": [
+    {
+      "name": "billing.inspect_invoice",
+      "kind": "read",
+      "source": "billing_postgres",
+      "context": "local_operator",
+      "target": {
+        "schema": "public",
+        "table": "invoices",
+        "primary_key": "id",
+        "tenant_key": "tenant_id"
+      },
+      "args": {
+        "invoice_id": { "type": "string", "required": true, "max_length": 128 }
+      },
+      "lookup": { "id_from_arg": "invoice_id" },
+      "visible_columns": [
+        "id",
+        "tenant_id",
+        "customer_id",
+        "status",
+        "balance_cents",
+        "late_fee_cents",
+        "waiver_reason",
+        "credit_requested_cents",
+        "credit_reason",
+        "credited_cents",
+        "updated_at"
+      ],
+      "evidence": "required",
+      "max_rows": 1
+    },
+    {
+      "name": "billing.propose_late_fee_waiver",
+      "kind": "proposal",
+      "source": "billing_postgres",
+      "context": "local_operator",
+      "target": {
+        "schema": "public",
+        "table": "invoices",
+        "primary_key": "id",
+        "tenant_key": "tenant_id"
+      },
+      "args": {
+        "invoice_id": { "type": "string", "required": true, "max_length": 128 },
+        "reason": { "type": "string", "required": true, "max_length": 500 }
+      },
+      "lookup": { "id_from_arg": "invoice_id" },
+      "visible_columns": [
+        "id",
+        "tenant_id",
+        "customer_id",
+        "status",
+        "balance_cents",
+        "late_fee_cents",
+        "waiver_reason",
+        "updated_at"
+      ],
+      "evidence": "required",
+      "max_rows": 1,
+      "patch": {
+        "late_fee_cents": { "fixed": 0 },
+        "waiver_reason": { "from_arg": "reason" }
+      },
+      "allowed_columns": ["late_fee_cents", "waiver_reason"],
+      "numeric_bounds": {
+        "late_fee_cents": { "minimum": 0, "maximum": 10000 }
+      },
+      "conflict_guard": { "column": "updated_at" },
+      "approval": { "mode": "human", "required_role": "billing_lead" }
+    },
+    {
+      "name": "billing.propose_account_credit",
+      "kind": "proposal",
+      "source": "billing_postgres",
+      "context": "local_operator",
+      "executor": "billing_app_handler",
+      "target": {
+        "schema": "public",
+        "table": "invoices",
+        "primary_key": "id",
+        "tenant_key": "tenant_id"
+      },
+      "args": {
+        "invoice_id": { "type": "string", "required": true, "max_length": 128 },
+        "amount_cents": { "type": "number", "required": true, "minimum": 1, "maximum": 10000 },
+        "reason": { "type": "string", "required": true, "max_length": 500 }
+      },
+      "lookup": { "id_from_arg": "invoice_id" },
+      "visible_columns": [
+        "id",
+        "tenant_id",
+        "customer_id",
+        "status",
+        "balance_cents",
+        "credited_cents",
+        "credit_requested_cents",
+        "credit_reason",
+        "updated_at"
+      ],
+      "evidence": "required",
+      "max_rows": 1,
+      "patch": {
+        "credit_requested_cents": { "from_arg": "amount_cents" },
+        "credit_reason": { "from_arg": "reason" }
+      },
+      "allowed_columns": ["credit_requested_cents", "credit_reason"],
+      "numeric_bounds": {
+        "credit_requested_cents": { "minimum": 1, "maximum": 10000 }
+      },
+      "conflict_guard": { "column": "updated_at" },
+      "approval": { "mode": "human", "required_role": "billing_lead" }
+    }
+  ]
+}

package/examples/openai-agents-http/README.md

@@ -12,6 +12,11 @@ spec-compatible HTTP MCP transport with `initialize` and session behavior. Use
 `synapsor-runner mcp serve-http` only when you intentionally want the smaller
 JSON-RPC bridge and an app-owned wrapper.
 
+OpenAI function names cannot contain dots, so start Runner with
+`--alias-mode openai`. The model sees aliases such as
+`billing__inspect_invoice`; Runner keeps `billing.inspect_invoice` in MCP
+metadata and maps calls back to the canonical Synapsor capability.
+
 The model still sees a semantic action. It does not receive raw SQL, database
 URLs, write credentials, approval tools, or commit tools.
 
@@ -26,7 +31,8 @@ export SYNAPSOR_RUNNER_HTTP_TOKEN="dev-token"
 npx -y -p @synapsor/runner@alpha synapsor-runner mcp serve-streamable-http \
   --config ./synapsor.runner.json \
   --store ./.synapsor/local.db \
-  --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
+  --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN \
+  --alias-mode openai
 ```
 
 ## Terminal 2: Run The Agent
@@ -46,7 +52,9 @@ python agent.py
 
 Expected behavior:
 
-- the agent calls `billing.inspect_invoice` through Synapsor HTTP MCP;
+- the agent calls the OpenAI-safe alias `billing__inspect_invoice` through
+  Synapsor HTTP MCP;
+- Runner maps that alias back to canonical `billing.inspect_invoice`;
 - Synapsor applies trusted tenant/principal context from the server process;
 - the response includes scoped data and evidence handles;
 - no SQL/write/approval tool is exposed to the model;

package/examples/openai-agents-stdio/README.md

@@ -4,7 +4,10 @@ This example shows an OpenAI Agents SDK app launching Synapsor Runner as a
 local stdio MCP server.
 
 Use stdio when the agent process can start the MCP server on the same machine.
-The model sees Synapsor semantic tools such as `billing.inspect_invoice`. It
+The model sees Synapsor semantic tools through OpenAI-safe aliases such as
+`billing__inspect_invoice`. Runner keeps the canonical Synapsor capability
+name, such as `billing.inspect_invoice`, in MCP metadata and maps calls back to
+it. The model
 does not receive raw SQL, database URLs, write credentials, approval tools, or
 commit tools.
 
@@ -52,11 +55,12 @@ export SYNAPSOR_INVOICE_ID="INV-3001"
 
 Expected behavior:
 
-- the agent can inspect the scoped invoice through Synapsor;
+- the agent can inspect the scoped invoice through Synapsor using an
+  OpenAI-safe tool alias;
+- Runner maps the alias back to the canonical Synapsor capability;
 - the agent cannot run SQL;
 - the agent cannot approve or commit writes;
 - evidence/query audit are saved in the local Runner store.
 
 If your installed OpenAI Agents SDK does not expose `MCPServerStdio`, update the
-SDK or use the HTTP example, which wraps Synapsor HTTP MCP with a small JSON-RPC
-client.
+SDK or use the Streamable HTTP example.

package/examples/openai-agents-stdio/agent.py

@@ -35,6 +35,8 @@ async def main() -> None:
             config_path,
             "--store",
             store_path,
+            "--alias-mode",
+            "openai",
         ],
         "env": {
             **os.environ,