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

package/docs/troubleshooting-first-run.md

@@ -0,0 +1,248 @@
+# Troubleshooting First Run
+
+Run the friendly doctor first:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner doctor --first-run
+```
+
+Use JSON for automation:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner doctor --first-run --json
+```
+
+## Docker Missing
+
+What happened:
+
+```text
+Docker CLI is missing.
+```
+
+Why it matters:
+
+The first-run demo starts disposable Postgres/MySQL containers.
+
+Fix:
+
+Install Docker Desktop or Docker Engine, then rerun:
+
+```bash
+./scripts/try-synapsor.sh
+```
+
+## Docker Daemon Stopped
+
+What happened:
+
+```text
+Docker daemon is not reachable.
+```
+
+Why it matters:
+
+The demo cannot start disposable databases without the daemon.
+
+Fix:
+
+Start Docker Desktop or the Docker service, then rerun:
+
+```bash
+./scripts/try-synapsor.sh
+```
+
+If the doctor reports Docker socket permission problems, add your user to the
+Docker group or start Docker Desktop.
+
+## Port Conflict
+
+What happened:
+
+```text
+Port 55433 is already in use.
+```
+
+Why it matters:
+
+The fixtures bind predictable local ports.
+
+Fix:
+
+```bash
+./scripts/try-synapsor.sh --reset
+```
+
+If another application owns the port, stop that application and rerun.
+
+## Stale Containers
+
+What happened:
+
+Doctor reports stale Synapsor demo containers.
+
+Why it matters:
+
+Old containers can hold ports or stale fixture state.
+
+Fix:
+
+```bash
+./scripts/try-synapsor.sh --reset
+```
+
+## Missing Source Dependencies
+
+What happened:
+
+```text
+Dependencies are not installed yet.
+```
+
+Why it matters:
+
+Source checkout commands such as `synapsor ...` need workspace
+dependencies.
+
+Fix:
+
+```bash
+corepack enable
+corepack pnpm install
+```
+
+The Docker-only first-run demo does not require host Node dependencies.
+
+## Config Missing
+
+What happened:
+
+```text
+Runner config not found at synapsor.runner.json.
+```
+
+Why it matters:
+
+Own-database MCP setup needs a reviewed config before serving tools.
+
+Fix:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner init --from-env DATABASE_URL --mode review --wizard
+```
+
+Or pass an example config:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner tools preview --config ./examples/mcp-postgres-billing/synapsor.runner.json --store ./.synapsor/local.db
+```
+
+## SQLite Store Missing
+
+What happened:
+
+```text
+SQLite local store not found at ./.synapsor/local.db.
+```
+
+Why it matters:
+
+The local UI and replay read proposal/evidence state from the store.
+
+Fix:
+
+Run a demo or create a proposal first:
+
+```bash
+./scripts/try-synapsor.sh
+```
+
+or:
+
+```bash
+corepack pnpm demo:reference
+```
+
+## DB URL Env Var Missing
+
+What happened:
+
+```text
+SYNAPSOR_DATABASE_READ_URL is not set.
+```
+
+Why it matters:
+
+Configured capabilities need a read credential to inspect/propose against your
+database.
+
+Fix:
+
+```bash
+export SYNAPSOR_DATABASE_READ_URL="<read-only-url>"
+npx -y -p @synapsor/runner@alpha synapsor-runner doctor --config synapsor.runner.json
+```
+
+## Read/Write Credential Split Failed
+
+What happened:
+
+```text
+Read and write env vars resolve to the same credential.
+```
+
+Why it matters:
+
+Read/proposal authority and writeback authority must be separated.
+
+Fix:
+
+Use a read-only credential for MCP reads and a separate writer credential only
+for trusted apply.
+
+## MCP Client Config Contains A Secret
+
+What happened:
+
+Doctor reports a generated MCP client config appears to contain a database URL,
+password, or token.
+
+Why it matters:
+
+MCP clients must receive only the local runner command and args.
+
+Fix:
+
+Regenerate the snippet:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner mcp config claude-desktop \
+  --absolute-paths \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+```
+
+Keep database URLs in environment variables, not client JSON.
+
+## Demo Did Not Prove The Boundary
+
+What happened:
+
+```text
+Demo did not prove the Synapsor boundary.
+```
+
+Why it matters:
+
+The first-run demo must prove semantic tools, proposal creation, source row
+unchanged, approval outside MCP, guarded writeback/conflict, replay, and no
+secret leakage.
+
+Fix:
+
+Inspect the printed log path, then reset:
+
+```bash
+./scripts/try-synapsor.sh --reset
+./scripts/try-synapsor.sh
+```

package/docs/writeback-executors.md

@@ -0,0 +1,209 @@
+# Writeback Executors
+
+Synapsor Runner separates proposal authority from execution authority.
+
+The model-facing MCP server can inspect and propose. It cannot approve or
+commit. After a human or trusted process approves a proposal, the local runner
+uses a configured writeback executor.
+
+## `sql_update`
+
+`sql_update` is the default executor.
+
+It applies one guarded `UPDATE` through the database adapter:
+
+- fixed schema/table from reviewed config;
+- fixed primary key column;
+- tenant guard;
+- allowed-column validation;
+- conflict/version guard;
+- idempotency key;
+- affected-row check;
+- terminal receipt in replay.
+
+Use this when the trusted runner is allowed to update the selected business row
+directly.
+
+The source config controls which writer env var is used:
+
+```json
+{
+  "sources": {
+    "local_postgres": {
+      "engine": "postgres",
+      "read_url_env": "SYNAPSOR_DATABASE_READ_URL",
+      "write_url_env": "SYNAPSOR_DATABASE_WRITE_URL"
+    }
+  }
+}
+```
+
+For `synapsor-runner apply --job ... --config ...`, set the 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.
+
+Direct SQL writeback also stores idempotency receipts in the source database.
+By default it runs:
+
+```sql
+CREATE TABLE IF NOT EXISTS synapsor_writeback_receipts (...);
+```
+
+That means the writer needs permission to create and write that receipt table in
+the target schema/database, or the table must be pre-created by an administrator
+and granted to the writer. If you do not want Runner to create a table in the
+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@alpha synapsor-runner writeback doctor --config ./synapsor.runner.json
+npx -y -p @synapsor/runner@alpha synapsor-runner writeback migration --engine postgres
+npx -y -p @synapsor/runner@alpha 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.
+
+The approved proposal becomes a structured HTTP request to an internal handler.
+The handler URL and bearer token come from environment variables, not config
+literal values.
+
+```json
+{
+  "executors": {
+    "billing_api": {
+      "type": "http_handler",
+      "url_env": "SYNAPSOR_BILLING_HANDLER_URL",
+      "method": "POST",
+      "auth": {
+        "type": "bearer_env",
+        "token_env": "SYNAPSOR_BILLING_HANDLER_TOKEN"
+      },
+      "timeout_ms": 5000
+    }
+  },
+  "capabilities": [
+    {
+      "name": "billing.propose_late_fee_waiver",
+      "kind": "proposal",
+      "executor": "billing_api"
+    }
+  ]
+}
+```
+
+Run after approval:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner apply \
+  --proposal wrp_123 \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+```
+
+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.
+
+Handler responses:
+
+```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 terminal statuses:
+
+- `applied`
+- `already_applied`
+- `conflict`
+- `failed`
+
+Non-2xx responses and timeouts become failed execution receipts. The terminal
+receipt is stored in replay.
+
+Use your application/API for business logic. Use Synapsor Runner for proposal,
+approval, evidence, policy boundary, and replay.
+
+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
+```
+
+Or generate one into your app:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner handler template node-fastify \
+  --output ./synapsor-writeback-handler.mjs
+
+npx -y -p @synapsor/runner@alpha synapsor-runner handler template python-fastapi \
+  --output ./synapsor_writeback_handler.py
+
+npx -y -p @synapsor/runner@alpha synapsor-runner handler template command \
+  --output ./synapsor-command-handler.mjs
+```
+
+## `command_handler`
+
+`command_handler` is a local integration path for scripts:
+
+```json
+{
+  "executors": {
+    "local_billing_script": {
+      "type": "command_handler",
+      "command_env": "SYNAPSOR_BILLING_HANDLER_COMMAND",
+      "timeout_ms": 5000
+    }
+  }
+}
+```
+
+The command receives the same structured JSON request on stdin and should print
+a JSON receipt body on stdout.
+
+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:
+
+- approval tools;
+- commit tools;
+- write credentials;
+- handler bearer tokens;
+- arbitrary SQL authority;
+- tenant/principal authority.
+
+`MCP tool call = request/proposal authority. Trusted runner = execution
+authority.`

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

@@ -0,0 +1,120 @@
+# 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.
+
+## 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"
+      },
+      "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.