@synapsor/runner 0.1.0-alpha.9 → 0.1.1

package/docs/README.md

@@ -1,34 +1,109 @@
 # Synapsor Runner Docs
 
-Start with the README. Use these docs only when you need the next level of
-detail.
+Start with the README. Use this index when you need the task-specific next
+step. The order is intentional: run something first, wire your database second,
+then read the concepts once the safety boundary is visible.
 
-## First Setup
+## 01 Quickstart
+
+- [README](../README.md): wedge, no-DB quick demo, five-line model, and the
+  shortest own-database path.
+- [Troubleshooting First Run](troubleshooting-first-run.md): common first-run
+  failures, redacted diagnostics, and fixes.
+
+## 02 Why Raw SQL Is Dangerous
+
+- [Security Boundary](security-boundary.md): what the model can and cannot see.
+- [MCP Audit](mcp-audit.md): static review for risky database MCP tools such as
+  `execute_sql`, broad query tools, model-controlled tenant filters, or
+  model-facing approval/commit tools.
+
+## 03 Run The Demo
+
+- `examples/support-billing-agent/`: flagship support/billing agent demo with
+  `make demo`, expected output, and the raw-SQL-vs-Synapsor contrast.
+- `examples/raw-sql-vs-synapsor/`: no-database fear/fix demo.
+- `examples/reference-support-billing-app/`: shared fixture used by the
+  flagship demo and package smoke tests.
+
+## 04 Connect Your DB
 
 - [Connect Your Own Database](getting-started-own-database.md): inspect a
   staging Postgres/MySQL database, generate `synapsor.runner.json`, preview
   semantic tools, and serve them over MCP.
+- [Use Your Own Database](use-your-own-database.md): short entry point that
+  links to the canonical own-database guide.
+- [Doctor](doctor.md): redacted setup checks, handler probes, direct SQL
+  writeback probes, and receipt-table guidance.
+
+## 05 Generate Capabilities
+
+- [Capability Authoring](capability-authoring.md): define read/proposal
+  capabilities, model-facing descriptions, result envelopes, trusted context,
+  and writeback guards.
+- [Recipes](recipes.md): starter business-capability templates.
+- [JSON Schema](../schemas/synapsor.runner.schema.json): editor validation for
+  `synapsor.runner.json`.
+
+## 06 Serve MCP
+
 - [MCP Client Setup](mcp-client-setup.md): connect Claude, Cursor, VS Code, or
   another stdio MCP client.
+- `examples/claude-desktop-postgres/`: copy-paste Claude Desktop config for the
+  Postgres billing fixture.
+- `examples/cursor-postgres/`: copy-paste Cursor config for the Postgres
+  billing fixture.
 - [HTTP MCP](http-mcp.md): run Synapsor Runner as an authenticated HTTP MCP
   service for app/server agents.
+- [OpenAI Agents SDK](openai-agents-sdk.md): use Streamable HTTP MCP with
+  OpenAI-safe tool aliases.
 
-## Safety And Operations
+## 07 Propose, Approve, Apply
 
-- [Security Boundary](security-boundary.md): what the model can and cannot see.
-- [Current Limitations](limitations.md): current alpha scope.
-- [Troubleshooting First Run](troubleshooting-first-run.md): common setup
-  failures and fixes.
 - [Local Mode](local-mode.md): local store, proposals, approval, replay, and
   writeback flow.
-
-## Features
-
-- [MCP Audit](mcp-audit.md): static risk review for database MCP tools.
-- [Recipes](recipes.md): starter business-capability templates.
 - [Writeback Executors](writeback-executors.md): app-owned writeback handlers
   for approved proposals.
+- [App-Owned Executors](app-owned-executors.md): short entry point for rich
+  business transactions handled by your app.
+- [Handler Helper](handler-helper.md): TypeScript helper for safe app-owned
+  rich-write handlers.
+
+## 08 Replay And Audit
+
+- [Result Envelope v2](result-envelope-v2.md): stable
+  `ok`/`summary`/`data`/`proposal`/`error` MCP tool results.
+- [Store Lifecycle](store-lifecycle.md): active-store leases, prune safety,
+  deleted-store behavior, and concurrent server guardrails.
+- `synapsor-runner activity search`, `evidence`, `query-audit`, `receipts`,
+  `events tail`, and `events webhook`: local evidence, audit, receipt, replay,
+  and lifecycle inspection.
+- `examples/mysql-refund-agent/`: MySQL order/refund review example using the
+  same proposal, approval, guarded writeback, and replay loop.
+
+## 09 App-Owned Handlers
+
+- [Writeback Executors](writeback-executors.md): call direction, endpoint
+  contract, receipt shape, and the requirement to re-check tenant/scope,
+  expected version, idempotency, and allowed action inside your handler.
+- [Handler Helper](handler-helper.md): helper API and examples.
+
+## 10 Concepts
+
+- [Current Scope](current-scope.md): compact v0.1 scope summary.
+- [Current Limitations](limitations.md): intentional safety limits.
+- [Cloud Mode](cloud-mode.md): what stays local and what Cloud-linked mode adds.
+- [Release Notes](release-notes.md): release history and behavior changes.
+- [Release Policy](release-policy.md): stable gates and publish verification.
+- [Licensing](licensing.md): Apache-2.0 scope, trademark boundary, and what is
+  not included in this runner repo.
+- [Dependency License Inventory](dependency-license-inventory.md): current
+  dependency license summary for release review.
+- RFC source context:
+  [001 result envelope](rfcs/001-result-envelope-v2.md),
+  [002 handler helper](rfcs/002-app-owned-handler-helper.md),
+  [003 integrator teardown](rfcs/003-integrator-feedback-teardown.md).
 
-The public docs intentionally stay small. Historical implementation reports,
-release checklists, and internal planning notes are not part of the public
+The public docs intentionally stay task-first. Historical implementation
+reports, release checklists, and internal planning notes are not part of the
 getting-started path.

package/docs/app-owned-executors.md

@@ -0,0 +1,38 @@
+# App-Owned Executors
+
+The canonical guide is [Writeback Executors](writeback-executors.md).
+
+Use app-owned executors when an approved proposal needs a real business
+transaction instead of Runner-managed single-row SQL.
+
+Examples:
+
+- create a credit row;
+- open a ticket;
+- call Stripe or Zendesk;
+- write ledger/event rows;
+- update multiple tables in one application transaction.
+
+The model-facing MCP tool only creates a proposal. Approval happens outside MCP.
+After approval, Runner calls your `http_handler` or `command_handler`, records
+the receipt, and includes the result in 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.
+
+A handler is your application endpoint or script. It is not a second Synapsor
+package that users need to install. Install `@synapsor/runner`, then generate
+or copy a handler template only when your approved write needs app-owned
+business logic.
+
+Do not use generic SQL for rich business transactions. Let the model propose,
+let Synapsor Runner approve/replay, and let your app execute the transaction.
+
+For TypeScript services, prefer the first-party helper in `packages/handler`.
+It enforces bearer/HMAC auth, tenant scope, expected-version guards,
+idempotency, transaction rollback, and safe receipt formatting around your
+business effect. See [Handler Helper](handler-helper.md).

package/docs/capability-authoring.md

@@ -0,0 +1,265 @@
+# Capability Authoring
+
+Use `synapsor.runner.json` to define the database actions an MCP client can see.
+The model sees semantic capabilities such as `billing.inspect_invoice`, not raw
+SQL, table names, write credentials, approval tools, or commit tools.
+
+For editor validation, use the JSON Schema:
+
+```text
+schemas/synapsor.runner.schema.json
+```
+
+## Minimal Shape
+
+```json
+{
+  "version": 1,
+  "mode": "review",
+  "result_format": 2,
+  "storage": { "sqlite_path": "./.synapsor/local.db" },
+  "sources": {
+    "app_postgres": {
+      "engine": "postgres",
+      "read_url_env": "DATABASE_URL",
+      "write_url_env": "SYNAPSOR_DATABASE_WRITE_URL",
+      "statement_timeout_ms": 3000
+    }
+  },
+  "trusted_context": {
+    "provider": "environment",
+    "values": {
+      "tenant_id_env": "SYNAPSOR_TENANT_ID",
+      "principal_env": "SYNAPSOR_PRINCIPAL"
+    }
+  },
+  "capabilities": []
+}
+```
+
+`result_format: 2` makes every MCP tool call return one envelope:
+
+```json
+{
+  "ok": true,
+  "summary": "Created proposal wrp_123. Source database changed: no.",
+  "action": "billing.propose_late_fee_waiver",
+  "kind": "proposal",
+  "data": null,
+  "proposal": {},
+  "error": null,
+  "evidence": {
+    "bundle_id": "ev_123",
+    "note": "audit/replay handle; you do not need to act on it during this turn"
+  },
+  "source_database_changed": false,
+  "_meta": {
+    "canonical_capability": "billing.propose_late_fee_waiver"
+  }
+}
+```
+
+Use `--result-format v2` on `mcp serve` or `mcp serve-streamable-http` if you
+want to opt in from the command line instead of config.
+
+## Read Capability
+
+Read capabilities inspect one scoped row or view and save evidence/query-audit
+records locally.
+
+```json
+{
+  "name": "billing.inspect_invoice",
+  "kind": "read",
+  "description": "Inspect one invoice in the trusted tenant before proposing a waiver or credit.",
+  "returns_hint": "Returns invoice amount, late fee, status, policy facts, and an audit evidence handle.",
+  "source": "app_postgres",
+  "target": {
+    "schema": "public",
+    "table": "invoices",
+    "primary_key": "id",
+    "tenant_key": "tenant_id"
+  },
+  "args": {
+    "invoice_id": {
+      "type": "string",
+      "required": true,
+      "max_length": 128,
+      "description": "Invoice id, e.g. INV-3001."
+    }
+  },
+  "lookup": { "id_from_arg": "invoice_id" },
+  "visible_columns": ["id", "tenant_id", "status", "late_fee_cents", "updated_at"],
+  "evidence": "required",
+  "max_rows": 1
+}
+```
+
+Model-facing descriptions matter. They should explain when to use the tool and
+what the result contains. Runner also adds evidence-handle guidance so the model
+does not waste a turn trying to call an audit handle.
+
+## Proposal Capability
+
+Proposal capabilities create an exact before/after diff. They do not mutate your
+source database. Approval and writeback stay outside the model-facing MCP tool
+surface.
+
+```json
+{
+  "name": "billing.propose_late_fee_waiver",
+  "kind": "proposal",
+  "description": "Propose waiving one invoice late fee after inspecting invoice and policy evidence.",
+  "returns_hint": "Returns a review-required proposal id, exact field diff, evidence handle, and source_database_changed:false.",
+  "source": "app_postgres",
+  "target": {
+    "schema": "public",
+    "table": "invoices",
+    "primary_key": "id",
+    "tenant_key": "tenant_id"
+  },
+  "args": {
+    "invoice_id": {
+      "type": "string",
+      "required": true,
+      "description": "Invoice id, e.g. INV-3001."
+    },
+    "reason": {
+      "type": "string",
+      "required": true,
+      "max_length": 500,
+      "description": "Business reason for the proposed waiver."
+    }
+  },
+  "lookup": { "id_from_arg": "invoice_id" },
+  "visible_columns": ["id", "tenant_id", "status", "late_fee_cents", "waiver_reason", "updated_at"],
+  "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" }
+}
+```
+
+## Trusted Context
+
+Tenant, principal, approval authority, source ids, and row-version authority
+must come from trusted backend/session context, not from model arguments.
+
+Good:
+
+```json
+"trusted_context": {
+  "provider": "environment",
+  "values": {
+    "tenant_id_env": "SYNAPSOR_TENANT_ID",
+    "principal_env": "SYNAPSOR_PRINCIPAL"
+  }
+}
+```
+
+Bad:
+
+```json
+"args": {
+  "tenant_id": { "type": "string" }
+}
+```
+
+Runner rejects model-facing trust-scope arguments.
+
+## Direct SQL Writeback
+
+Use direct SQL writeback only for simple bounded single-row `UPDATE` proposals.
+Runner validates:
+
+- fixed table and column names;
+- primary-key targeting;
+- tenant guard;
+- `allowed_columns`;
+- numeric bounds and transition guards;
+- optimistic conflict guard such as `updated_at`;
+- one affected row;
+- idempotency receipt.
+
+Runner does not expose generic SQL, model-generated SQL, DDL, INSERT, DELETE,
+UPSERT, or multi-row writes.
+
+Direct SQL writeback uses the source `write_url_env`, such as
+`SYNAPSOR_DATABASE_WRITE_URL`. The writer needs permission for
+`synapsor_writeback_receipts` or an administrator must pre-create and grant that
+table.
+
+## App-Owned Executors
+
+Use an app-owned executor when an approved proposal needs richer business work:
+creating a credit row, inserting an outbox event, updating multiple app tables,
+or calling your own service.
+
+```json
+"executors": {
+  "billing_handler": {
+    "type": "http_handler",
+    "url_env": "BILLING_WRITEBACK_URL",
+    "method": "POST",
+    "auth": {
+      "type": "bearer_env",
+      "token_env": "BILLING_WRITEBACK_TOKEN"
+    },
+    "signing_secret_env": "BILLING_WRITEBACK_SIGNING_SECRET",
+    "timeout_ms": 5000
+  }
+}
+```
+
+Then reference it from a proposal capability:
+
+```json
+{
+  "name": "billing.propose_account_credit",
+  "kind": "proposal",
+  "executor": "billing_handler"
+}
+```
+
+Approval still happens outside MCP. Runner sends the approved job to your
+handler, and the handler returns an applied/conflict/failed receipt for replay.
+See [App-Owned Executors](app-owned-executors.md) and
+[Writeback Executors](writeback-executors.md).
+
+## OpenAI Aliases
+
+Canonical Synapsor names use dots, such as `billing.inspect_invoice`. Some
+clients require function-safe names. Use:
+
+```bash
+synapsor-runner mcp serve-streamable-http \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN \
+  --alias-mode openai
+```
+
+The model sees aliases such as `billing__inspect_invoice`. Runner includes the
+canonical name in tool metadata and descriptions so audit/replay still use the
+real capability name.
+
+## Why Not `execute_sql`
+
+`execute_sql(sql)` gives the model database authority. Synapsor Runner gives the
+model proposal authority:
+
+```text
+model-facing MCP tool -> trusted context -> scoped read -> evidence -> proposal
+```
+
+Commit authority stays outside the model:
+
+```text
+human/operator approval -> guarded writeback or app-owned handler -> receipt/replay
+```

package/docs/cloud-mode.md

@@ -0,0 +1,24 @@
+# Cloud Mode
+
+Synapsor Runner is local-first. It does not require Synapsor Cloud for the local
+demo, own-database onboarding, MCP serving, proposal creation, local approval,
+guarded writeback, or replay.
+
+Cloud-linked mode is for teams that need a shared control plane:
+
+- team approvals and RBAC;
+- hosted evidence/replay search;
+- runner registration and heartbeat;
+- job leases;
+- receipt reporting;
+- retention and audit visibility.
+
+The local runner still keeps database credentials in your environment. MCP
+client config snippets should contain command paths and runner arguments, not
+database URLs or write credentials.
+
+Run the local smoke for this mode with:
+
+```bash
+corepack pnpm test:mcp-cloud-linked
+```

package/docs/current-scope.md

@@ -0,0 +1,29 @@
+# Current Scope
+
+The canonical scope page is [Current Limitations](limitations.md).
+
+Current alpha scope:
+
+- local semantic MCP tools for Postgres/MySQL-backed business actions;
+- schema inspection and guided config generation;
+- trusted context from environment/session values;
+- evidence handles, query audit, proposals, receipts, and local replay;
+- guarded single-row `UPDATE` writeback for simple edits;
+- app-owned `http_handler` and `command_handler` executors for richer approved
+  business transactions;
+- stdio MCP, Streamable HTTP MCP, and a small JSON-RPC bridge.
+
+Stable `0.1.x` compatibility covers the documented `synapsor-runner` binary,
+config schema version `1`, result envelope v2 with v1 opt-out, stdio/Streamable
+HTTP MCP surfaces, documented MCP client snippets, proposal/evidence/replay
+inspection commands, direct SQL writeback, and app-owned executor contracts.
+
+Out of scope:
+
+- raw `execute_sql`;
+- model-generated SQL;
+- generic INSERT/DELETE/UPSERT/DDL;
+- generic multi-row SQL writeback;
+- physical branching of external Postgres/MySQL;
+- self-hosted Synapsor Cloud;
+- production SLA or compliance certification.

package/docs/dependency-license-inventory.md

@@ -0,0 +1,35 @@
+# Dependency License Inventory
+
+Generated from the current lockfile/install with:
+
+```bash
+corepack pnpm licenses list --json
+```
+
+Summary from the current dependency set:
+
+| License | Package entries |
+| --- | ---: |
+| MIT | 149 |
+| Apache-2.0 | 4 |
+| BSD-3-Clause | 3 |
+| BSD-2-Clause | 1 |
+| ISC | 11 |
+
+Apache-2.0 dependency entries reported by pnpm:
+
+- `denque@2.1.0`
+- `expect-type@1.3.0`
+- `long@5.3.2`
+- `typescript@5.9.3`
+
+This file is an inventory summary, not a replacement for dependency license
+review. Third-party dependency licenses and notices are not changed by the
+first-party Synapsor Runner Apache-2.0 license.
+
+Before public release:
+
+- regenerate this inventory from a clean install;
+- review dependency notices with the release owner or qualified counsel;
+- keep third-party notices separate from the first-party Synapsor Runner
+  license.

package/docs/doctor.md

@@ -0,0 +1,98 @@
+# Doctor
+
+Use `doctor` to check a local Runner setup without printing database URLs,
+passwords, bearer tokens, signing secrets, or private keys.
+
+```bash
+synapsor-runner doctor --config synapsor.runner.json
+synapsor-runner doctor --config synapsor.runner.json --json
+synapsor-runner doctor --config synapsor.runner.json --report --redact --output synapsor-doctor.md
+```
+
+The default check validates:
+
+- config shape;
+- trusted context environment variables;
+- read credential environment variables;
+- read/write credential separation;
+- reachable source metadata when the read env var is set;
+- configured target tables and columns;
+- MCP tool boundary, including absence of raw SQL and commit tools;
+- local store stats.
+
+## App-Owned Handler Checks
+
+For `http_handler` executors, add `--check-handlers`:
+
+```bash
+synapsor-runner doctor --config synapsor.runner.json --check-handlers
+```
+
+This checks handler URL/token/signing-secret env vars and sends a reachability
+probe to the handler endpoint. It does not apply a proposal and does not send a
+writeback job.
+
+Use `signing_secret_env` for non-loopback handler deployments so Runner signs
+requests with:
+
+```text
+X-Synapsor-Signature
+X-Synapsor-Issued-At
+X-Synapsor-Proposal-Id
+Idempotency-Key
+```
+
+## Direct SQL Writeback Checks
+
+For direct `sql_update` writeback, add `--check-writeback` only after reviewing
+the receipt-table DDL/grants:
+
+```bash
+synapsor-runner doctor --config synapsor.runner.json --check-writeback
+```
+
+This connects with the trusted writer env var named by `write_url_env` and
+checks:
+
+- writer database connectivity;
+- `synapsor_writeback_receipts` permission through the adapter doctor;
+- rollback-only access to each configured proposal target table;
+- rollback-only update permission for configured allowed write columns.
+
+The target-table probe uses fixed schema/table/column identifiers from the
+reviewed config. It does not accept model SQL, user SQL, arbitrary table names,
+or arbitrary column names. It runs inside a transaction and rolls back.
+
+The receipt-table probe can create `synapsor_writeback_receipts` if the writer
+has permission. If your policy does not allow Runner to create tables in the
+application schema, pre-create the table and grant access:
+
+```bash
+synapsor-runner writeback migration --engine postgres --schema synapsor
+synapsor-runner writeback grants --engine postgres --schema synapsor --writer-role app_writer
+```
+
+For MySQL:
+
+```bash
+synapsor-runner writeback migration --engine mysql --schema appdb
+synapsor-runner writeback grants --engine mysql --schema appdb --writer-role "'app_writer'@'%'"
+```
+
+Use an app-owned `http_handler` or `command_handler` executor when your
+application should own richer business writes or receipt storage.
+
+## Redaction
+
+Doctor output intentionally uses safe categories such as:
+
+```text
+connection failed
+authentication failed
+permission denied
+configured object not found
+database probe failed
+```
+
+Raw driver errors, connection strings, passwords, tokens, signing secrets, and
+handler URLs are not printed in the report.