@synapsor/runner 0.1.0 → 0.1.2

package/docs/production.md

@@ -0,0 +1,289 @@
+# Production-Candidate Guide
+
+Synapsor Runner is not self-hosted Synapsor Cloud. This guide is for the
+narrow OSS production-candidate shape:
+
+```text
+MCP agent
+-> reviewed semantic capability
+-> trusted tenant/principal context
+-> scoped Postgres/MySQL read
+-> evidence/query audit/proposal
+-> approval outside MCP
+-> guarded one-row update or app-owned executor
+-> receipt/replay
+```
+
+Use this only for bounded database workflows where you can accept a single-node
+local ledger and local/operator approval. Use Synapsor Cloud when you need HA,
+central audit, RBAC/SSO, multi-reviewer approvals, hosted retention, managed
+runners, policy packs, or production support/SLA.
+
+## Supported Scope
+
+Production-candidate OSS scope:
+
+- Postgres/MySQL reads through fixed semantic MCP tools;
+- trusted context from environment/session values, not model arguments;
+- local SQLite ledger for evidence, query audit, proposals, receipts, replay,
+  and lifecycle events;
+- direct guarded single-row `UPDATE` for simple approved edits;
+- app-owned `http_handler` or `command_handler` executors for richer approved
+  business transactions;
+- stdio MCP and Streamable HTTP MCP.
+
+Out of scope:
+
+- raw `execute_sql` or model-generated SQL;
+- generic direct `INSERT`, `DELETE`, `UPSERT`, DDL, or multi-row SQL writeback;
+- physical branching of external Postgres/MySQL;
+- workflow DAGs, auto-merge/settlement, RBAC/SSO, HA ledger, or compliance
+  retention;
+- making prompt injection impossible.
+
+## Database Roles
+
+Use separate read and write credentials.
+
+Read credential:
+
+- can connect to the selected database;
+- can inspect metadata for selected schemas;
+- can `SELECT` only the tables/views used by capabilities;
+- should be restricted by views/RLS where possible.
+
+Write credential for direct `sql_update`:
+
+- can update only the allowed business columns;
+- cannot modify primary-key or tenant columns;
+- can create/write the `synapsor_writeback_receipts` table, or the table is
+  pre-created and granted by an administrator;
+- is never exposed to MCP clients.
+
+Example config:
+
+```json
+{
+  "sources": {
+    "billing_postgres": {
+      "engine": "postgres",
+      "read_url_env": "SYNAPSOR_DATABASE_READ_URL",
+      "write_url_env": "SYNAPSOR_DATABASE_WRITE_URL"
+    }
+  }
+}
+```
+
+`synapsor-runner apply --config ...` reads the writer env var named by
+`write_url_env`. `SYNAPSOR_DATABASE_URL` is only a legacy fallback for direct
+worker flows that do not pass a local config.
+
+## Receipt Table
+
+Direct SQL writeback stores idempotency receipts in the source database. Runner
+creates this table if allowed:
+
+```sql
+CREATE TABLE IF NOT EXISTS synapsor_writeback_receipts (...);
+```
+
+Before using direct writeback in staging or production-like environments:
+
+```bash
+synapsor-runner writeback migration --engine postgres
+synapsor-runner writeback grants --engine postgres --writer-role app_writer
+synapsor-runner doctor --config synapsor.runner.json --check-writeback
+```
+
+For MySQL, replace `postgres` with `mysql`.
+
+If the writer should not create application-schema tables, pre-create the
+receipt table with an administrator role, grant only the needed receipt-table
+permissions to the writer, or use an app-owned executor that stores receipts in
+your application boundary.
+
+## Direct Writeback Vs App-Owned Executor
+
+Use direct `sql_update` when the approved change is:
+
+```text
+one existing row -> one allowed-column patch -> one guarded UPDATE
+```
+
+Use an app-owned executor when the change is richer:
+
+- insert a credit/refund/review row;
+- update more than one row;
+- touch more than one table;
+- emit an event or call another internal service;
+- enforce business logic that belongs in your app.
+
+Handlers must re-check tenant/scope, expected version, idempotency, allowed
+business action, transaction boundaries, and safe errors. See
+[Writeback Executors](writeback-executors.md) and
+[Handler Helper](handler-helper.md).
+
+## Local Ledger
+
+Default local ledger path:
+
+```text
+./.synapsor/local.db
+```
+
+This SQLite file stores local evidence, query audit, proposals, approvals,
+receipts, replay, and events. Back it up like local operational state if you
+depend on replay after restarts.
+
+Recommended single-node practices:
+
+- keep the ledger on persistent disk;
+- back up `local.db`, `local.db-wal`, and `local.db-shm` together when the
+  server is stopped, or use your platform's filesystem snapshot mechanism;
+- do not run multiple active MCP server modes against the same ledger unless
+  you intentionally pass `--allow-concurrent-store` for local debugging;
+- use `store prune --dry-run` before retention cleanup;
+- use `store vacuum` during a planned maintenance window.
+
+Useful commands:
+
+```bash
+synapsor-runner store stats --store ./.synapsor/local.db
+synapsor-runner events tail --store ./.synapsor/local.db --follow
+synapsor-runner store prune --store ./.synapsor/local.db --older-than 30d --dry-run
+synapsor-runner store vacuum --store ./.synapsor/local.db
+```
+
+Details: [Store Lifecycle](store-lifecycle.md).
+
+## Restart And Recovery
+
+Runner stores proposal/evidence/replay state before writeback.
+
+Expected restart behavior:
+
+- after proposal creation: proposal, evidence, query audit, and replay remain
+  inspectable from the local ledger;
+- after approval but before apply: rerun `apply`; the approved proposal remains
+  pending until a terminal receipt is recorded;
+- after apply succeeds: retry returns an idempotent receipt, not a second write;
+- after stale row or tenant mismatch: retry returns the recorded conflict path.
+
+Inspection commands:
+
+```bash
+synapsor-runner proposals show latest --store ./.synapsor/local.db
+synapsor-runner receipts list --proposal wrp_... --store ./.synapsor/local.db
+synapsor-runner replay show latest --store ./.synapsor/local.db
+synapsor-runner activity search --proposal wrp_... --store ./.synapsor/local.db
+```
+
+## Deployment Recipes
+
+### Docker Compose Shape
+
+Use Compose to run the MCP server next to your app and database network. Keep
+secrets in environment variables or your platform secret manager.
+
+```yaml
+services:
+  synapsor-runner:
+    image: node:22-bookworm
+    working_dir: /app
+    command: >
+      sh -lc "npm install -g @synapsor/runner &&
+      synapsor-runner up --review --config /config/synapsor.runner.json
+      --store /data/local.db --host 0.0.0.0 --port 8766"
+    environment:
+      SYNAPSOR_DATABASE_READ_URL: ${SYNAPSOR_DATABASE_READ_URL}
+      SYNAPSOR_DATABASE_WRITE_URL: ${SYNAPSOR_DATABASE_WRITE_URL}
+      SYNAPSOR_TENANT_ID: ${SYNAPSOR_TENANT_ID}
+      SYNAPSOR_PRINCIPAL: ${SYNAPSOR_PRINCIPAL}
+    volumes:
+      - ./synapsor.runner.json:/config/synapsor.runner.json:ro
+      - synapsor-runner-data:/data
+    ports:
+      - "8766:8766"
+
+volumes:
+  synapsor-runner-data:
+```
+
+### systemd Shape
+
+```ini
+[Unit]
+Description=Synapsor Runner MCP server
+After=network-online.target
+
+[Service]
+Type=simple
+User=synapsor-runner
+WorkingDirectory=/opt/synapsor-runner
+EnvironmentFile=/etc/synapsor-runner.env
+ExecStart=/usr/bin/synapsor-runner up --review --config /etc/synapsor.runner.json --store /var/lib/synapsor-runner/local.db --host 127.0.0.1 --port 8766
+Restart=on-failure
+RestartSec=5
+NoNewPrivileges=true
+PrivateTmp=true
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Put database credentials in `/etc/synapsor-runner.env` or your system secret
+manager, not in `synapsor.runner.json`.
+
+## TLS And SSL
+
+For staging or production-like databases:
+
+- keep certificate verification enabled;
+- use provider CA bundles when required;
+- do not use `sslmode=disable` except disposable local fixtures;
+- do not document or paste real DB URLs into logs, tickets, prompts, or MCP
+  client config.
+
+For disposable local Docker fixtures, `sslmode=disable` is acceptable when the
+database is bound to loopback and contains only test data.
+
+## Health And Doctor
+
+Run these before exposing tools to an agent:
+
+```bash
+synapsor-runner config validate --config synapsor.runner.json
+synapsor-runner doctor --config synapsor.runner.json --report --redact --output synapsor-doctor.md
+synapsor-runner doctor --config synapsor.runner.json --check-writeback
+synapsor-runner tools preview --config synapsor.runner.json --store ./.synapsor/local.db
+```
+
+Doctor reports should be redacted by default before sharing. They must not
+include database passwords, bearer tokens, handler secrets, or raw driver
+connection strings.
+
+## Logging And Redaction
+
+Expected public outputs must avoid secrets in:
+
+- demo output;
+- doctor reports;
+- evidence exports;
+- query-audit output;
+- replay exports;
+- thrown errors and logs.
+
+If you find a leak, treat it as a security bug. See [SECURITY.md](../SECURITY.md).
+
+## Release Gate
+
+Before promoting a package or calling a build production-candidate:
+
+```bash
+./scripts/verify-release-gate.sh
+```
+
+The release gate should cover typecheck, focused tests, packed-package install,
+quick demo, own-db fixture, MCP stdio/HTTP checks, direct writeback,
+app-owned executor paths, package dry-run, and docs/package consistency.
+

package/docs/release-notes.md

@@ -10,6 +10,38 @@ npx -y -p @synapsor/runner synapsor-runner demo --quick
 The OSS runner command is `synapsor-runner`. The `synapsor` command is reserved
 for the Synapsor Cloud CLI.
 
+## 0.1.2
+
+### Contract Compatibility
+
+- Documents the canonical `synapsor.contract.json` path for contracts produced
+  by the DSL, Cloud, or the C++ exporter.
+- Adds OSS-side conformance notes for C++/Cloud export snapshots that validate
+  with `@synapsor/spec` and load in Runner.
+- Keeps `@synapsor/runner` publishable after `0.1.1` by reserving the next
+  stable patch version for this contract round-trip readiness pass.
+
+## 0.1.1
+
+### OSS Launch Readiness
+
+- Reworked the README and packaged npm README so the first screen leads with
+  the `execute_sql` risk, the reviewed-business-action alternative, badges, and
+  the no-database quick demo.
+- Added the self-contained `examples/support-billing-agent/` flagship demo with
+  schema, seed data, reviewed contract, app-boundary note, one-command
+  `make demo`, and the exact support/billing model-facing tool list.
+- Added copy-paste example entry points for raw SQL vs Synapsor, Claude
+  Desktop, Cursor, OpenAI Agents SDK over Streamable HTTP and stdio, and MySQL
+  refund review.
+- Added agent-native repo guidance files and verified that an agent can create
+  an inspect/propose capability with the non-interactive CLI without reading
+  generated `dist/` files.
+- Restructured the docs index into a task-first path and added release-gate
+  repo hygiene assets.
+- Hardened package building so generated `.synapsor` local ledgers are not
+  included in npm examples.
+
 ## 0.1.0
 
 ### Stable Channel

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

package/examples/claude-desktop-postgres/README.md

@@ -0,0 +1,40 @@
+# Claude Desktop + Postgres
+
+This example prints a Claude Desktop MCP config for a reviewed Postgres-backed
+Synapsor Runner capability set.
+
+It uses the local `examples/mcp-postgres-billing/synapsor.runner.json` fixture.
+The config contains command paths and environment variable names only; it does
+not include database URLs or write credentials.
+
+## Run
+
+```bash
+make config
+```
+
+Expected output includes:
+
+```json
+{
+  "mcpServers": {
+    "synapsor": {
+      "command": "...",
+      "args": ["...", "mcp", "serve", "..."]
+    }
+  }
+}
+```
+
+Then paste the JSON into Claude Desktop's MCP settings and set these
+environment variables in the client environment:
+
+```bash
+export BILLING_POSTGRES_READ_URL="postgres://readonly:..."
+export SYNAPSOR_TENANT_ID="acme"
+export SYNAPSOR_PRINCIPAL="local_billing_agent"
+```
+
+The model sees semantic tools such as `billing.inspect_invoice` and
+`billing.propose_late_fee_waiver`; it does not see raw SQL or approval/commit
+tools.

package/examples/cursor-postgres/Makefile

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

package/examples/cursor-postgres/README.md

@@ -0,0 +1,30 @@
+# Cursor + Postgres
+
+This example prints a Cursor MCP config for a reviewed Postgres-backed Synapsor
+Runner capability set.
+
+It uses the local `examples/mcp-postgres-billing/synapsor.runner.json` fixture.
+The config contains command paths and environment variable names only; it does
+not include database URLs or write credentials.
+
+## Run
+
+```bash
+make config
+```
+
+Expected output includes a Cursor-compatible `mcpServers.synapsor` entry that
+launches:
+
+```text
+synapsor-runner mcp serve --config ./examples/mcp-postgres-billing/synapsor.runner.json --store ./.synapsor/local.db
+```
+
+Set the database and trusted-context variables in the environment that launches
+Cursor:
+
+```bash
+export BILLING_POSTGRES_READ_URL="postgres://readonly:..."
+export SYNAPSOR_TENANT_ID="acme"
+export SYNAPSOR_PRINCIPAL="local_billing_agent"
+```

package/examples/mysql-refund-agent/Makefile

@@ -0,0 +1,4 @@
+.PHONY: demo
+
+demo:
+	cd ../.. && corepack pnpm test:mcp-local

package/examples/mysql-refund-agent/README.md

@@ -0,0 +1,36 @@
+# MySQL Refund Agent
+
+This example points at the MySQL order/refund fixture and proves Synapsor
+Runner is not Postgres-only.
+
+The reviewed tools are:
+
+- `orders.inspect_order`
+- `orders.propose_refund_review`
+- `orders.propose_status_change`
+
+The refund proposal updates only review fields on one existing order. It does
+not issue money movement, call a payment provider, or expose a generic SQL
+tool.
+
+## Run
+
+```bash
+make demo
+```
+
+Expected output includes the shared local MCP smoke passing for the MySQL orders
+scenario:
+
+```text
+MySQL orders
+ACCEPT execute_sql approval and commit tools absent
+```
+
+The source database remains unchanged until a proposal is approved outside MCP
+and applied through guarded writeback.
+
+## Underlying Fixture
+
+This folder wraps `../mcp-mysql-orders/`, which contains the Docker compose
+file, seed SQL, and `synapsor.runner.json` contract.

package/examples/openai-agents-http/Makefile

@@ -0,0 +1,6 @@
+.PHONY: smoke
+
+smoke:
+	python3 -m py_compile agent.py
+	npx -y -p @synapsor/runner synapsor-runner mcp serve-streamable-http --help >/dev/null
+	@printf '%s\n' "OpenAI Agents Streamable HTTP example smoke passed."

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

@@ -20,6 +20,20 @@ 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.
 
+## Smoke Check
+
+Run this without an OpenAI API key:
+
+```bash
+make smoke
+```
+
+Expected output:
+
+```text
+OpenAI Agents Streamable HTTP example smoke passed.
+```
+
 ## Terminal 1: Start Synapsor Runner HTTP MCP
 
 ```bash

package/examples/openai-agents-stdio/Makefile

@@ -0,0 +1,6 @@
+.PHONY: smoke
+
+smoke:
+	python3 -m py_compile agent.py
+	npx -y -p @synapsor/runner synapsor-runner mcp serve --help >/dev/null
+	@printf '%s\n' "OpenAI Agents stdio example smoke passed."

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

@@ -11,6 +11,20 @@ it. The model
 does not receive raw SQL, database URLs, write credentials, approval tools, or
 commit tools.
 
+## Smoke Check
+
+Run this without an OpenAI API key:
+
+```bash
+make smoke
+```
+
+Expected output:
+
+```text
+OpenAI Agents stdio example smoke passed.
+```
+
 ## Prerequisites
 
 Generate `synapsor.runner.json` first:

package/examples/raw-sql-vs-synapsor/Makefile

@@ -0,0 +1,11 @@
+.PHONY: demo
+
+demo:
+	@printf '%s\n' "Unsafe shortcut:"
+	@printf '%s\n' '  agent -> execute_sql("UPDATE invoices SET late_fee_cents = 0 ...")'
+	@printf '%s\n' ""
+	@printf '%s\n' "Synapsor quick proof:"
+	npx -y @synapsor/runner demo --quick --no-interactive
+	@printf '%s\n' ""
+	@printf '%s\n' "Risk audit example:"
+	npx -y @synapsor/runner audit --example dangerous-db-mcp --format markdown

package/examples/raw-sql-vs-synapsor/README.md

@@ -0,0 +1,41 @@
+# Raw SQL vs Synapsor
+
+This minimal example shows the fear and the fix without requiring Docker, an
+agent SDK, or a database.
+
+## Run
+
+```bash
+make demo
+```
+
+Expected output includes:
+
+```text
+execute_sql
+Synapsor quick demo complete.
+proposal created
+source DB changed: no
+approval required outside MCP
+```
+
+The raw-SQL shortcut is:
+
+```text
+agent -> execute_sql("UPDATE invoices SET late_fee_cents = 0 ...")
+```
+
+The Synapsor path is:
+
+```text
+agent -> billing.propose_late_fee_waiver(...)
+human approves outside MCP
+guarded writeback applies exactly one row
+replay records what happened
+```
+
+## Why This Exists
+
+Use this folder when you want to show the core idea quickly. It is not a full
+database fixture; the full support/billing walkthrough lives in
+`../support-billing-agent/`.

package/examples/support-billing-agent/Makefile

@@ -0,0 +1,19 @@
+.PHONY: demo unsafe clean
+
+demo:
+	cd ../.. && examples/support-billing-agent/scripts/run-demo.sh
+
+unsafe:
+	@printf '%s\n' "Unsafe raw-SQL shortcut this demo avoids:"
+	@printf '%s\n' ""
+	@printf '%s\n' '  agent -> execute_sql("UPDATE invoices SET late_fee_cents = 0 WHERE status = '\''overdue'\''")'
+	@printf '%s\n' ""
+	@printf '%s\n' "Why it is risky:"
+	@printf '%s\n' "  - the model controls SQL shape and scope"
+	@printf '%s\n' "  - tenant filters can be omitted or hallucinated"
+	@printf '%s\n' "  - there is no proposal, approval boundary, conflict receipt, or replay"
+	@printf '%s\n' ""
+	@printf '%s\n' "Run 'make demo' to see the Synapsor path: semantic tool -> proposal -> approval -> guarded writeback -> replay."
+
+clean:
+	docker compose down -v --remove-orphans

package/examples/support-billing-agent/README.md

@@ -0,0 +1,89 @@
+# Support/Billing Agent Demo
+
+This is the flagship Synapsor Runner demo.
+
+It uses a disposable Postgres support/billing app and shows the full loop:
+
+```text
+agent inspects scoped evidence
+-> agent creates a proposal
+-> source database is unchanged
+-> human approves outside MCP
+-> guarded writeback applies exactly one row
+-> replay shows evidence, diff, approval, receipt, and conflict behavior
+```
+
+## Run It
+
+From this folder:
+
+```bash
+make demo
+```
+
+Expected end state:
+
+```text
+Reference support/billing app smoke passed.
+```
+
+The model-facing tools are exactly:
+
+- `support.inspect_ticket`
+- `support.propose_plan_credit`
+- `billing.inspect_invoice`
+- `billing.propose_late_fee_waiver`
+
+The demo proves:
+
+- the model-facing tool list contains semantic capabilities such as
+  `billing.inspect_invoice` and `billing.propose_late_fee_waiver`;
+- the model does not receive `execute_sql`, approval tools, commit/apply tools,
+  database URLs, write credentials, arbitrary table names, arbitrary column
+  names, or tenant authority;
+- proposals do not mutate the source database;
+- approved writeback uses tenant, primary-key, allowed-column,
+  idempotency, and `updated_at` conflict guards;
+- replay contains the evidence and writeback receipt.
+
+## Compare The Unsafe Shortcut
+
+To see why the boundary matters:
+
+```bash
+make unsafe
+```
+
+That target prints the raw-SQL shape this demo avoids. It does not mutate the
+fixture; it shows the path an MCP client should not expose to the model:
+
+```text
+execute_sql("UPDATE invoices SET late_fee_cents = 0 ...")
+```
+
+Use `make demo` for the real proposal, approval, writeback, idempotent retry,
+stale-row conflict, and replay proof.
+
+## What This Wraps
+
+This folder is self-contained for readers and agents looking for the canonical
+support/billing demo. The smoke logic is shared with the reference fixture so
+the product-facing walkthrough and package tests exercise the same safety
+checks.
+
+Relevant files:
+
+- `db/schema.sql`
+- `db/seed.sql`
+- `synapsor.runner.json`
+- `scripts/run-demo.sh`
+- `app/README.md`
+
+## Stop And Clean Up
+
+The demo script cleans up its disposable Docker database automatically. If you
+interrupt it, run:
+
+```bash
+make clean
+```