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

package/docs/licensing.md

@@ -0,0 +1,38 @@
+# Licensing
+
+Synapsor Runner is open source under the Apache License 2.0 (`Apache-2.0`).
+
+This page is a plain-English summary, not legal advice. If this summary
+conflicts with `../LICENSE`, the `LICENSE` file controls.
+
+Apache-2.0 applies to the code in this runner repository. It grants copyright
+and patent rights under the license terms.
+
+Apache-2.0 does not grant trademark rights. The Synapsor name, Synapsor Runner
+name, logos, hosted Cloud service, and proprietary Synapsor platform features
+remain separate. See `../TRADEMARKS.md`.
+
+This license change applies only to `synapsor-runner`.
+
+It does not open source:
+
+- Synapsor Cloud;
+- the hosted control plane;
+- hosted capability registry;
+- advanced policy/capability compiler;
+- team approvals, RBAC, or SSO;
+- hosted audit/evidence ledger;
+- managed runners;
+- production writeback orchestration;
+- workflow builder;
+- native Synapsor engine;
+- C++/DBMS internals;
+- branching, time travel, or settlement;
+- compliance exports or production support/SLA.
+
+Synapsor Cloud is a separate hosted commercial service. Use Cloud when your team
+needs shared approvals, RBAC, hosted evidence/replay search, runner fleet
+status, leases, retention, audit visibility, enterprise controls, and support.
+
+Before public release, license and trademark text must be reviewed by qualified
+counsel.

package/docs/limitations.md

@@ -0,0 +1,75 @@
+# Limitations
+
+Synapsor Runner is intentionally narrow in the current alpha.
+
+## Supported
+
+- Stdio MCP server for semantic database capabilities.
+- Local read and proposal tools.
+- Local SQLite evidence/proposal/query-audit/replay store.
+- Human approval through CLI commands.
+- Public protocol objects:
+  - `synapsor.change-set.v1`
+  - `synapsor.writeback-job.v1`
+  - `synapsor.execution-receipt.v1`
+  - `synapsor.runner-registration.v1`
+- Guarded single-row `UPDATE` for Postgres and MySQL.
+- App/API handler writeback through approved `http_handler` executors.
+- Local script writeback through approved `command_handler` executors.
+- Primary-key guard.
+- Tenant guard.
+- Allowed-column validation.
+- Version-column or explicit weak row-hash conflict guard.
+- Idempotency receipts.
+- Named local trusted contexts for capability configs.
+- Capability recipes that generate reviewed starter configs.
+- Shadow-mode proposal-vs-human-action comparison.
+- Static MCP database risk review.
+
+## Runtime Contract
+
+Local capabilities are config-defined, not built into the server. The runtime
+does not special-case billing, support, orders, refunds, invoices, or tickets.
+Those domains appear only in demos, smoke tests, and optional recipe JSON files.
+When you connect your own database, `synapsor.runner.json` is the source of
+truth for the model-facing tools.
+
+## Not Supported
+
+- Arbitrary SQL.
+- Model-generated SQL.
+- DDL.
+- INSERT.
+- DELETE.
+- UPSERT.
+- Multi-row UPDATE.
+- Stored procedures.
+- Cross-database transactions.
+- Physical branching of Postgres/MySQL.
+- Full Synapsor workflow/DAG execution.
+- `CREATE AGENT WORKFLOW` or hosted Synapsor SQL generation.
+- Auto-merge or settlement policy semantics.
+- Automatic rollback of external database writes.
+- Model-callable approval or commit tools.
+- Generic MCP firewall behavior.
+- Prompt-injection prevention.
+- High availability, SLA, compliance certification, or production support guarantee.
+
+## Important External Database Semantics
+
+External Postgres/MySQL databases are not branched or merged by Synapsor Runner.
+
+The proposal, evidence, replay, and approval state live in Synapsor Runner locally or in Synapsor Cloud. The external source database changes only when a trusted runner applies an approved writeback job.
+
+Use this wording:
+
+```text
+External DB = Synapsor review state + trusted writeback
+Synapsor-native = real branch + merge
+```
+
+Do not describe external approval as merge.
+
+## Weak Conflict Guards
+
+A version/timestamp column is the preferred conflict guard. A weak row-hash guard can be acknowledged for local/dev use, but it should not be presented as equivalent to a durable version column.

package/docs/local-mode.md

@@ -0,0 +1,246 @@
+# Local mode
+
+Local mode runs Synapsor Runner inside the developer or customer environment. No Synapsor Cloud account is required for local review flows.
+
+Command model:
+
+- `./scripts/demo-docker.sh` runs the no-install Docker demo.
+- `synapsor <command>` is the public CLI surface.
+- From a source checkout, use `./bin/synapsor <command>` if the global binary is
+  not linked yet.
+
+Current local-mode foundation:
+
+- strict JSON capability config validation in `packages/config`;
+- local SQLite proposal/event/evidence/query-audit/writeback/replay store in `packages/proposal-store`;
+- local proposal review CLI in `apps/runner`;
+- local localhost proposal review UI through `synapsor ui`;
+- static MCP database risk review with `synapsor audit`;
+- local stdio MCP server with semantic read/proposal tools;
+- MCP resource reads for `synapsor://proposals/*`, `synapsor://evidence/*`, and `synapsor://replay/*`;
+- local approved proposal to `synapsor.writeback-job.v1` job generation;
+- guarded Postgres/MySQL writeback adapters for approved structured jobs.
+
+Still pending:
+
+- Public-release hardening around the experimental `node:sqlite` dependency.
+
+## Initialize a config
+
+Create a starter config without putting credentials in the file:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor init --engine postgres --mode review
+```
+
+For MySQL:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor init --engine mysql --mode review --output synapsor.mysql.runner.json
+```
+
+The generated config uses environment-variable names for read/write URLs and trusted context. Edit the table, column, and capability names before serving tools.
+
+Do not include credential-bearing columns in reviewed visible fields or
+evidence. The local store rejects obvious database URLs, bearer tokens, runner
+tokens, private-key blocks, and secret-like field names before they can be
+persisted into proposals, evidence, query audit, runner state, or replay.
+
+For a reviewed own-database setup generated from explicit selections, use:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor init --spec onboarding-selection.json --non-interactive
+npx -y -p @synapsor/runner@alpha synapsor doctor --config synapsor.runner.json
+```
+
+`doctor --config` checks config validation, required environment variables,
+read/write credential separation, metadata visibility for configured targets,
+and the semantic MCP tool boundary without printing credential values.
+
+## Local safety modes
+
+The local runner modes are intentionally narrow:
+
+- `read_only`: exposes read tools only; proposal tools fail closed.
+- `shadow`: lets proposal tools create local proposals, evidence, query audit, and replay records, but approval and writeback-job creation are disabled.
+- `review`: lets proposal tools create local proposals, then a human/operator can approve and create a guarded writeback job.
+- `cloud`: delegates reviewed tools to Synapsor Cloud through a runner token.
+
+Use `shadow` when you want to test the shape of proposals without any path to mutate the source database. Use `review` only when you are ready to exercise the trusted writeback worker.
+
+## Store path
+
+Commands use `--store` or `SYNAPSOR_LOCAL_STORE`.
+
+```bash
+export SYNAPSOR_LOCAL_STORE="./.synapsor/local.db"
+```
+
+If neither is set, the CLI uses:
+
+```text
+./.synapsor/local.db
+```
+
+## Proposal review
+
+List proposals:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor proposals list --store ./.synapsor/local.db
+```
+
+Show a proposal:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor proposals show wrp_123 --store ./.synapsor/local.db
+```
+
+Approve:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor proposals approve wrp_123 \
+  --store ./.synapsor/local.db \
+  --actor local_reviewer \
+  --yes
+```
+
+Before approval, the CLI prints the reviewer-critical proposal details: trusted principal, tenant, target row, primary key, required role, proposal hash/version, allowed columns, conflict guard, evidence bundle/query fingerprint, writeback boundary, source mutation state, and exact before/after diff. Interactive approval still requires typing `yes`; noninteractive scripts must pass `--yes`.
+
+Create a guarded writeback job from an approved proposal:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor proposals writeback-job wrp_123 \
+  --store ./.synapsor/local.db \
+  --project local \
+  --runner local_runner \
+  --output job.json
+```
+
+The generated job uses the public `synapsor.writeback-job.v1` protocol and can be applied by the guarded worker:
+
+```bash
+SYNAPSOR_ENGINE=postgres \
+SYNAPSOR_DATABASE_URL="postgresql://writer:<password>@localhost:5432/app" \
+npx -y -p @synapsor/runner@alpha synapsor apply --job job.json --config synapsor.runner.json --store ./.synapsor/local.db
+```
+
+Passing `--store` records the terminal `synapsor.execution-receipt.v1` locally. Replay then links the proposal, approval, writeback job, applied/conflict/failed receipt, evidence, and query audit.
+
+Reject:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor proposals reject wrp_123 \
+  --store ./.synapsor/local.db \
+  --reason "policy evidence is incomplete" \
+  --yes
+```
+
+`approve` and `reject` require either interactive confirmation or explicit `--yes`.
+
+Approval records the approver against the exact proposal hash/version. The proposal patch is immutable after creation.
+
+Shadow-mode proposals are inspectable through `proposals show` and `replay show`, but `proposals approve` and `proposals writeback-job` reject them. Shadow mode never mutates Postgres/MySQL.
+
+## Browser review UI
+
+Start a localhost-only review UI:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor ui --config synapsor.runner.json --store ./.synapsor/local.db
+```
+
+The UI shows setup summary, semantic tools, proposal states, exact diffs,
+evidence, approval state, receipts, and replay. It binds to `127.0.0.1` by
+default, uses a per-run local session token, and requires CSRF protection for
+approve/reject actions.
+
+The UI does not expose raw SQL, database URLs, password values, MCP approval
+tools, MCP commit tools, or controls that widen configured tables/columns.
+
+## Replay
+
+Show replay:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor replay show wrp_123 --store ./.synapsor/local.db
+```
+
+Export replay:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor replay export wrp_123 \
+  --store ./.synapsor/local.db \
+  --output replay.json
+```
+
+Replay records include proposal metadata, before/after diff, events, writeback receipts, evidence summaries, and query audit rows currently stored for the proposal.
+
+## Boundary
+
+Local mode does not expose `approve_proposal` or `commit_proposal` as model-callable MCP tools. The intended flow is:
+
+```text
+MCP tool call
+  -> reviewed semantic proposal
+  -> local store
+  -> human/policy approval outside the model
+  -> guarded worker writeback
+  -> terminal receipt
+  -> replay
+```
+
+The external Postgres/MySQL database is not physically branched. It remains unchanged until a trusted runner applies an approved writeback job.
+
+## Local MCP smoke
+
+The repository includes a one-command Docker-only local demo:
+
+```bash
+./scripts/demo-docker.sh
+```
+
+This path requires Docker only. It builds the runner image locally, starts disposable Postgres/MySQL fixtures, runs the stdio MCP proof, and tears down the disposable resources. No Synapsor Cloud account, API key, hosted workspace, or host Node/Corepack setup is required.
+
+If you already have Node/Corepack installed for contributor work, the direct wrapper is also available:
+
+```bash
+./scripts/demo-local.sh
+corepack pnpm demo:local
+```
+
+The Docker-only script is also available through pnpm after dependencies are installed:
+
+```bash
+corepack pnpm demo:docker
+```
+
+The contributor script checks Docker/Corepack, installs dependencies if needed, starts disposable Postgres/MySQL containers, and runs the stdio MCP proof flow.
+
+For CI or direct verification, use:
+
+```bash
+corepack pnpm test:mcp-local
+```
+
+It launches the official MCP stdio client transport against `synapsor mcp serve`, exercises the Postgres billing, Postgres support, and MySQL orders examples, checks that source rows are unchanged before approval, approves locally, generates versioned writeback jobs, applies them, retries idempotently, and then proves stale-row conflict:
+
+```text
+The business state changed after the agent saw it, so Synapsor refused to commit.
+```
+
+## Optional MCP client configs
+
+After the Docker demo passes, developers who want to attach an MCP client can use the checked-in stdio config shapes in:
+
+```text
+examples/mcp-client-configs/
+```
+
+Verify those config files without launching any client UI:
+
+```bash
+corepack pnpm test:mcp-client-configs
+```
+
+That command starts the runner through each config shape, calls MCP `tools/list`, and verifies that the server exposes semantic tools such as `billing.inspect_invoice` and `billing.propose_late_fee_waiver` without exposing raw SQL, approval, or commit tools. It verifies the stdio contract and config shape; it does not claim that a specific client application's UI was manually tested.

package/docs/local-ui.md

@@ -0,0 +1,163 @@
+# Local UI
+
+`synapsor ui` starts a lightweight browser review surface for a local Runner
+store.
+
+From a source checkout, use `./bin/synapsor ui ...` if the global binary is not
+linked yet.
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor ui --config ./synapsor.runner.json --store ./.synapsor/local.db
+```
+
+By default it binds to localhost only and prints a per-run URL:
+
+```text
+Synapsor Runner local UI: http://127.0.0.1:51234/?token=...
+```
+
+Use the UI after `synapsor mcp serve` has created local proposals. The UI is a
+review surface; it is not a raw SQL console and it does not serve MCP tools.
+
+## The Review Console
+
+Selecting a proposal opens a **Review** tab that tells the story of what
+happened, step by step, instead of leading with raw JSON:
+
+1. **Agent requested a change** — the semantic tool that was called and the
+   object it targeted (for example `billing.propose_late_fee_waiver for
+   INV-3001`). The model could request, but had no SQL, approve, or commit
+   tools.
+2. **Synapsor Runner created a proposal** — proposal id, tenant, and principal.
+3. **The proposed change** — an exact before/proposed field diff.
+4. **Safety result** — `Source database changed: No/Yes`.
+5. **Approval boundary** — “Approval happened outside MCP. The model did not get
+   approve or commit tools,” plus the current approval status.
+6. **Commit result** — the terminal outcome in plain language, e.g. “Conflict:
+   the row changed after the proposal. No write applied,” with an expandable
+   guard checklist.
+7. **Replay** — a timeline of evidence, proposal, approval, writeback receipt,
+   and conflict events.
+
+A second **View raw JSON** tab exposes the full proposal, events, receipts, and
+evidence payloads for developers who want the underlying records. Each
+configuration card also keeps its raw JSON behind a per-card drawer.
+
+## What It Shows
+
+The setup summary shows:
+
+- config path and local store path;
+- Runner mode;
+- source engine and environment-variable names;
+- trusted context binding;
+- selected table/view targets;
+- semantic capabilities;
+- config validation status;
+- whether forbidden model-facing tools such as raw SQL or approval/commit tools
+  are present.
+
+The tools view shows:
+
+- semantic tool names;
+- read/proposal labels;
+- target table/view;
+- input schema;
+- hidden trusted bindings;
+- visible columns;
+- allowed patch columns;
+- conflict guard;
+- clear “No raw SQL” status.
+
+The proposals view shows:
+
+- pending, approved, rejected, applied, conflict, and failed states;
+- tenant/object/principal;
+- source database changed: yes/no;
+- source row before approval/writeback;
+- proposed patch values;
+- expected version guard;
+- exact before/proposed field diff;
+- evidence handle and summary;
+- receipts when present.
+
+The review panel lets a local reviewer:
+
+- approve outside the model-facing MCP tool surface;
+- reject with a reason;
+- see the message “The model can propose this change. It cannot approve or
+  commit it.” before execution;
+- see “Commit executed by trusted runner” after terminal writeback;
+- see “Conflict: source row changed after proposal” for stale-row cases;
+- inspect the guard checklist for tenant scope, allowed columns, primary key,
+  conflict/version column, idempotency key, and affected-row count;
+- inspect writeback mode and executor status;
+- inspect replay for the selected proposal.
+
+Approval and rejection record the reviewer identity against the exact proposal
+hash/version in the local SQLite proposal store.
+
+## Security Boundary
+
+The local UI keeps the same authority split as the CLI:
+
+```text
+MCP tool call = request/proposal authority
+Trusted local UI/CLI reviewer = approval authority
+Trusted runner apply path = execution authority
+```
+
+Security behavior:
+
+- binds to `127.0.0.1` by default;
+- refuses non-localhost binding unless `--allow-remote-bind` is explicitly
+  passed;
+- requires a per-run local session token;
+- sets the local session token in an HttpOnly SameSite cookie after the first
+  token URL load;
+- requires a CSRF token for approve/reject actions;
+- does not expose database URLs, passwords, bearer tokens, runner tokens, or
+  obvious secret strings in JSON API responses;
+- does not expose a raw SQL editor;
+- does not expose approval, commit, or writeback tools through MCP;
+- does not allow widening configured tables, columns, or mutable fields from the
+  browser.
+
+The UI displays proposal business data from the local store, so use reviewed
+visible columns and denied-column rules before creating proposals. Obvious
+secret-looking fields and connection strings are redacted defensively, but the
+UI is not a replacement for selecting safe capability projections.
+
+## Remote Binding
+
+For normal use, do not bind the UI to anything except localhost.
+
+For a deliberate trusted local-network demo:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor ui --host 0.0.0.0 --allow-remote-bind
+```
+
+Do this only in an isolated environment. The local UI is not a hosted
+multi-user approval product; use Synapsor Cloud when a team needs shared RBAC,
+approval queues, audit retention, and hosted replay search.
+
+## Current Limits
+
+The UI is intentionally small in the current alpha:
+
+- proposal review and replay only;
+- no graphical capability builder;
+- no raw SQL editor;
+- no direct writeback apply button;
+- no hosted/team auth;
+- no Cloud approval queue replacement.
+
+Use the CLI apply path after approval:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor proposals writeback-job wrp_123 --store ./.synapsor/local.db --output job.json
+SYNAPSOR_ENGINE=postgres \
+SYNAPSOR_DATABASE_URL="$SYNAPSOR_DATABASE_WRITE_URL" \
+npx -y -p @synapsor/runner@alpha synapsor apply --job job.json --config synapsor.runner.json --store ./.synapsor/local.db
+```

package/docs/mcp-audit.md

@@ -0,0 +1,146 @@
+# MCP database risk review
+
+`npx -y -p @synapsor/runner@alpha synapsor audit <target>` performs a
+static MCP database risk review over an exported tool manifest, a remote MCP
+`tools/list` endpoint, or a stdio MCP server. The `mcp audit` subcommand is also
+available for users who look for the command under the MCP namespace.
+
+From a source checkout, use `./bin/synapsor ...` if the global binary is not
+linked yet.
+
+It does not call business tools. It only inspects names, descriptions, input schemas, output schemas, annotations, and examples when those are present.
+
+Every report includes this disclaimer:
+
+```text
+This is a static risk review, not proof that an MCP server is secure.
+```
+
+MCP annotations are treated as hints, not enforcement.
+
+## Usage
+
+Built-in database MCP risk example:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor audit --example dangerous-db-mcp
+```
+
+This bundled example does not require a source checkout or local examples file.
+It audits a deliberately risky database MCP shape with `execute_sql`,
+`run_query`, model-callable approval/update/delete tools, arbitrary
+table/column inputs, and model-controlled tenant/principal fields.
+
+Human-readable output:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor audit ./tools-list.json
+```
+
+Remote `tools/list` endpoint with a bearer token kept in the environment:
+
+```bash
+SYNAPSOR_MCP_AUDIT_BEARER="..." \
+npx -y -p @synapsor/runner@alpha synapsor audit https://mcp.example.com --json
+```
+
+Remote endpoint with a custom bearer-token environment variable:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor audit https://mcp.example.com --bearer-env MCP_AUDIT_TOKEN --json
+```
+
+Stdio MCP server:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor audit 'stdio:node ./server.mjs' --timeout-ms 5000
+```
+
+JSON output:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor audit ./tools-list.json --json
+```
+
+During local development, the repo-local wrapper can run the same command:
+
+```bash
+./bin/synapsor audit ./tools-list.json
+./bin/synapsor audit ./tools-list.json --json
+```
+
+## Supported inputs
+
+The audit accepts common exported shapes:
+
+```json
+{ "tools": [] }
+```
+
+```json
+{ "result": { "tools": [] } }
+```
+
+```json
+{ "data": { "tools": [] } }
+```
+
+It also scans nested `adapter`, `mcpServers`, and `servers` blocks when they include tool metadata.
+
+For live targets, the audit calls only JSON-RPC `tools/list`. It does not call business tools, approval tools, commit tools, or writeback tools.
+
+## Findings
+
+The audit flags database-commit risks such as:
+
+- generic `execute_sql`, `run_query`, or raw SQL tools;
+- tools accepting arbitrary SQL, schema, table, or column identifiers;
+- tools accepting `tenant_id`, `principal`, source ids, allowed columns, row versions, or approval identity as model input;
+- model-callable approval, commit, apply, settle, merge, or writeback tools;
+- write-like tools with no visible proposal, approval, or guarded-writeback boundary;
+- missing structured output schemas;
+- missing idempotency/request-key metadata for direct write-like tools;
+- missing row-version/conflict-guard metadata for direct write-like tools;
+- ambiguous read/write tool boundaries;
+- missing business descriptions, annotations, or fixture examples.
+
+## Recommended target shape
+
+A safer model-facing database MCP tool should look like a reviewed semantic proposal capability:
+
+```json
+{
+  "name": "billing.propose_late_fee_waiver",
+  "description": "Create an evidence-backed proposal for support lead approval before trusted writeback.",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "invoice_id": { "type": "string" },
+      "reason": { "type": "string" }
+    },
+    "required": ["invoice_id", "reason"]
+  },
+  "outputSchema": {
+    "type": "object",
+    "properties": {
+      "status": { "type": "string" },
+      "proposal_id": { "type": "string" },
+      "evidence_bundle_id": { "type": "string" },
+      "source_database_changed": { "type": "boolean" }
+    },
+    "required": ["status", "proposal_id", "source_database_changed"]
+  },
+  "annotations": {
+    "readOnlyHint": false,
+    "destructiveHint": false
+  },
+  "examples": [
+    {
+      "invoice_id": "INV-3001",
+      "reason": "customer requested review"
+    }
+  ]
+}
+```
+
+Trusted values such as tenant, principal, source, allowed columns, approval identity, row-version guard, and database credentials must come from Synapsor/runner context, not from model-facing arguments.