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

package/docs/mcp-client-setup.md

@@ -0,0 +1,155 @@
+# MCP Client Setup
+
+The primary local proof path is still the one-command Docker demo:
+
+```bash
+./scripts/demo-docker.sh
+```
+
+Use this page after that demo passes and you want to attach a local MCP client. The tested integration contract here is stdio. Client-specific UIs change, so the checked-in examples verify config shape and `tools/list`, not every client screen.
+
+Command examples use the published alpha package through `npx`. From a source
+checkout, use `./bin/synapsor ...` only when you intentionally want the local
+source wrapper.
+
+Checked examples live in:
+
+```text
+examples/mcp-client-configs/
+```
+
+Validate them with:
+
+```bash
+corepack pnpm test:mcp-client-configs
+```
+
+## Generate A Client Snippet
+
+Print a snippet without modifying any client files:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner mcp config claude-desktop \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+```
+
+Supported client names:
+
+```text
+generic-stdio
+generic
+claude-desktop
+cursor
+vscode
+```
+
+The older form is still supported:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner mcp configure --client claude-desktop --config ./synapsor.runner.json --store ./.synapsor/local.db
+```
+
+Write is opt-in and requires an explicit destination:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner mcp configure \
+  --client cursor \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --write \
+  --destination ./cursor-mcp.json
+```
+
+When the destination already exists, Synapsor Runner creates a timestamped
+backup before writing. Noninteractive scripts must add `--yes`.
+
+The command writes only the local stdio MCP command and args. It does not write
+database URLs or passwords into the client config.
+
+## Start Command
+
+From the runner repository:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner mcp serve --config ./examples/mcp-postgres-billing/synapsor.runner.json --store ./.synapsor/local.db
+```
+
+For the alpha package, keep the package tag explicit in client configuration.
+
+## Generic stdio Client
+
+```json
+{
+  "mcpServers": {
+    "synapsor-runner": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "-p",
+        "@synapsor/runner@alpha",
+        "synapsor-runner",
+        "mcp",
+        "serve",
+        "--config",
+        "./examples/mcp-postgres-billing/synapsor.runner.json",
+        "--store",
+        "./.synapsor/local.db"
+      ],
+      "env": {
+        "BILLING_POSTGRES_READ_URL": "postgresql://synapsor_reader:...@localhost:55433/synapsor_runner_mcp_billing",
+        "SYNAPSOR_TENANT_ID": "acme",
+        "SYNAPSOR_PRINCIPAL": "local_billing_agent"
+      }
+    }
+  }
+}
+```
+
+The MCP server should list semantic tools such as:
+
+```text
+billing.inspect_invoice
+billing.propose_late_fee_waiver
+```
+
+It should not list:
+
+```text
+execute_sql
+run_query
+approve_proposal
+commit_proposal
+```
+
+## Claude Desktop / Cursor / VS Code
+
+Use the matching checked-in example as the starting point:
+
+```text
+examples/mcp-client-configs/claude-desktop.json
+examples/mcp-client-configs/cursor.json
+examples/mcp-client-configs/vscode.json
+```
+
+Each example uses the same stdio command/args/env structure. Replace the placeholder environment variables in your client settings or shell environment.
+
+Do not add a write database URL to the MCP server environment unless you are intentionally running a local review/writeback demo. For normal read/proposal tool calls, use the read URL and trusted context values only.
+
+Before documenting a client UI as officially tested, verify:
+
+1. the server starts;
+2. `tools/list` returns semantic tools;
+3. read tools return evidence handles;
+4. proposal tools return exact diffs and `source_database_changed: false`;
+5. no approval or commit tool is model-callable;
+6. resource reads work for proposal/evidence/replay handles.
+
+## Troubleshooting
+
+- Server not listed: check the command path, working directory, and config path.
+- Tool schema mismatch: run `synapsor audit <exported-tools.json>`.
+- Missing trusted context: set `SYNAPSOR_TENANT_ID` and `SYNAPSOR_PRINCIPAL`, or use the environment variables configured in `trusted_context.values`.
+- Database unavailable: verify the read credential and host access.
+- Proposal waiting review: approve outside the model with `synapsor proposals approve`.
+- Stale-row conflict: inspect replay; the source row changed after the proposal was created, so the guarded worker refused to commit.

package/docs/mcp-efficiency-benchmark.md

@@ -0,0 +1,84 @@
+# MCP Efficiency Benchmark
+
+Run:
+
+From a source checkout, use `corepack pnpm runner benchmark mcp-efficiency`.
+The global `synapsor` command is only needed after installing or linking the
+CLI.
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner benchmark mcp-efficiency
+```
+
+For machine-readable output:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner benchmark mcp-efficiency --json
+```
+
+The benchmark compares an included fixture, not universal model behavior.
+
+Current fixture:
+
+```text
+late-fee-waiver
+```
+
+Checked-in snapshots:
+
+```text
+fixtures/benchmark/mcp-efficiency.txt
+fixtures/benchmark/mcp-efficiency.json
+```
+
+The CLI tests compare both human-readable and machine-readable output against
+those snapshots, so changes to the fixture, tokenizer, measurements, or wording
+are reviewable.
+
+Reference path:
+
+```text
+list_tables
+describe_table invoices
+query_database SELECT invoice
+formulate raw UPDATE
+execute_sql UPDATE invoice
+```
+
+Synapsor Runner semantic path:
+
+```text
+billing.inspect_invoice
+billing.propose_late_fee_waiver
+```
+
+It measures:
+
+- number of exposed tools;
+- serialized `tools/list` bytes;
+- token count with a pinned deterministic fixture tokenizer;
+- scripted tool-call count;
+- schema/context bytes and tokens exposed;
+- business result bytes and tokens;
+- whether raw SQL is exposed;
+- whether write credentials are exposed;
+- whether approval is separated;
+- whether stale-row conflict is checked.
+
+Tokenizer:
+
+```text
+synapsor-fixture-tokenizer-v1
+```
+
+This tokenizer is a deterministic regex tokenizer used only for repeatable
+fixture comparison. It is not a model billing tokenizer.
+
+Allowed README phrasing after implementation:
+
+> In the included fixture, semantic capabilities replace generic schema
+> exploration and raw SQL with two compact business tools. Run the benchmark to
+> inspect tool definitions, reference tool-call count, and tokenized context
+> size.
+
+Do not claim guaranteed percentage savings across workloads.

package/docs/operations.md

@@ -0,0 +1,38 @@
+# Operations
+
+## Required configuration
+
+- `SYNAPSOR_CONTROL_PLANE_URL`
+- `SYNAPSOR_RUNNER_TOKEN`
+- `SYNAPSOR_RUNNER_ID`
+- `SYNAPSOR_SOURCE_ID`
+- `SYNAPSOR_DATABASE_URL`
+- `SYNAPSOR_ENGINE=postgres|mysql`
+
+## Routine checks
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner doctor
+npx -y -p @synapsor/runner@alpha synapsor-runner validate --job examples/postgres-support/job.approved.json
+npx -y -p @synapsor/runner@alpha synapsor-runner validate --job examples/mysql-orders/job.approved.json
+```
+
+`doctor` validates local configuration, calls Synapsor's runner-token doctor endpoint, confirms the token is authenticated for the configured source, checks database reachability and engine version, creates/verifies `synapsor_writeback_receipts`, and performs a rollback-only receipt insert to prove the configured credential can write runner receipts. It does not mutate business tables.
+
+## Local fixture smoke
+
+Run this before cutting a release or changing the adapters:
+
+```bash
+corepack pnpm test:docker
+```
+
+The smoke starts the local Postgres and MySQL fixtures, validates approved jobs, applies one guarded single-row update, retries the same idempotency key, verifies stale-version conflict, verifies tenant mismatch rejection, verifies disallowed-column validation, and tears down the containers with volumes.
+
+## Shutdown
+
+The runner handles `SIGINT` and `SIGTERM` by stopping the poll loop. In-flight database transactions complete or roll back through the adapter.
+
+## Logs
+
+Default logs include runner id, job id, proposal id, source id, engine, schema/table names, patch column names, status/error code, and durations. Logs must not include database URL/password, runner token, full patch values, full source rows, or customer data.

package/docs/own-db-20-minutes.md

@@ -0,0 +1,185 @@
+# Own Database In 10 Minutes
+
+This path is for a developer who already understands the local demo and wants
+to try one staging Postgres/MySQL table without writing `synapsor.runner.json`
+by hand.
+
+Do not start with your most sensitive production database. Start with staging,
+a disposable database, or a least-privilege view.
+
+## 1. Create A Read-Only Credential
+
+Use a database user that can inspect metadata and read only the tables/views
+needed for the experiment.
+
+Set the connection string in an environment variable:
+
+```bash
+export DATABASE_URL="<postgres-or-mysql-read-url>"
+```
+
+Do not paste database URLs into MCP client configs or committed JSON files.
+
+## 2. Inspect The Database
+
+Fast path:
+
+```bash
+./scripts/use-your-db.sh
+```
+
+That command runs inspection, guided config generation, and tool preview. The
+rest of this page shows the same steps explicitly.
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner inspect --from-env DATABASE_URL --engine auto
+```
+
+This prints discovered tables/views, primary keys, possible tenant/scope
+columns, possible conflict/version columns, and fields suggested for review.
+Inspection reads metadata and table shape. It does not expose raw SQL tools or
+write credentials to the model.
+
+For disposable staging databases, this shorter form also works:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner inspect "$DATABASE_URL" --engine auto
+```
+
+Prefer `--from-env` on shared machines so URLs do not land in shell history.
+
+## 3. Run The Guided Wizard
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner init --from-env DATABASE_URL --mode review --wizard
+```
+
+The wizard asks for:
+
+- database engine;
+- read URL environment-variable name;
+- schema/database;
+- table or view;
+- primary key;
+- tenant/scope column;
+- conflict/version column;
+- read-visible fields;
+- mode: `read_only`, `shadow`, or `review`;
+- business object name and namespace;
+- proposal patch mapping if you choose `shadow` or `review`;
+- trusted tenant/principal env vars;
+- approval role;
+- final confirmation before files are written.
+
+The default mode for unknown schemas should be treated as a cautious staging
+path. Do not enable real writeback until the read/proposal path is reviewed.
+
+You can still run the complete wrapper:
+
+```bash
+./scripts/use-your-db.sh
+```
+
+It runs inspection, guided init, tool preview, and next-step printing in one
+flow. For the lower-level CLI path, `synapsor onboard db --from-env
+DATABASE_URL` runs the same own-database onboarding from the runner command.
+
+## 4. What Gets Generated
+
+The wizard creates:
+
+- `synapsor.runner.json`;
+- `.env.example`;
+- `.synapsor/mcp/generic-stdio.json`;
+- `.synapsor/mcp/claude-desktop.json`;
+- `.synapsor/mcp/cursor.json`;
+- `.synapsor/mcp/vscode.json`.
+
+The generated config stores environment-variable names, not database secrets.
+
+## 5. Preview What The Model Sees
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner config validate --config synapsor.runner.json
+npx -y -p @synapsor/runner@alpha synapsor-runner doctor --config synapsor.runner.json
+npx -y -p @synapsor/runner@alpha synapsor-runner tools preview --config synapsor.runner.json --store ./.synapsor/local.db
+```
+
+`doctor` checks config shape, trusted context env vars, source env vars,
+read/write credential separation, source metadata when reachable, handler env
+vars, and the semantic MCP tool boundary.
+
+`tools preview` lists what the model would see and confirms:
+
+- semantic tools present;
+- `execute_sql` absent;
+- approval tools absent;
+- commit tools absent;
+- database URLs absent;
+- write credentials absent.
+
+## 6. Serve MCP
+
+```bash
+export SYNAPSOR_TENANT_ID="acme"
+export SYNAPSOR_PRINCIPAL="local_operator"
+
+npx -y -p @synapsor/runner@alpha synapsor-runner mcp serve \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+```
+
+The MCP server exposes only the configured semantic tools. It does not expose
+raw SQL, approval tools, commit tools, database URLs, write credentials, or
+model-controlled tenant authority.
+
+## 7. Review Proposals
+
+If a proposal is created:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner proposals list --store ./.synapsor/local.db
+npx -y -p @synapsor/runner@alpha synapsor-runner proposals show <proposal_id> --store ./.synapsor/local.db
+npx -y -p @synapsor/runner@alpha synapsor-runner replay show <proposal_id> --store ./.synapsor/local.db
+```
+
+Open the UI:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner ui --tour --config ./synapsor.runner.json --store ./.synapsor/local.db
+```
+
+## 8. Apply Only After Review
+
+For direct SQL writeback, set a separate writer credential only when ready:
+
+```bash
+export SYNAPSOR_DATABASE_WRITE_URL="<postgres-or-mysql-writer-url>"
+```
+
+Then:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner proposals approve <proposal_id> --store ./.synapsor/local.db --actor local_reviewer --yes
+npx -y -p @synapsor/runner@alpha synapsor-runner proposals writeback-job <proposal_id> --store ./.synapsor/local.db --output job.json
+
+SYNAPSOR_ENGINE=postgres \
+SYNAPSOR_DATABASE_URL="$SYNAPSOR_DATABASE_WRITE_URL" \
+npx -y -p @synapsor/runner@alpha synapsor-runner apply --job job.json --config synapsor.runner.json --store ./.synapsor/local.db
+```
+
+If your application should own the business write, configure an `http_handler`
+or `command_handler` executor instead of direct SQL writeback. See
+[writeback-executors.md](writeback-executors.md).
+
+## Safety Rules
+
+- Never infer write authority silently.
+- Every allowed write column must be explicitly reviewed.
+- Every patch mapping must be explicitly reviewed.
+- If no tenant column exists, use a safe view or explicitly acknowledge
+  single-tenant dev mode.
+- If no conflict column exists, stay in `read_only` or `shadow` unless you
+  intentionally accept a weak guard for local testing.
+- Never write during onboarding.
+- Never put secrets in generated config.

package/docs/production-readiness.md

@@ -0,0 +1,39 @@
+# Production Readiness
+
+Synapsor Runner is a local, open-source MCP data-plane/runtime for reviewed
+Postgres/MySQL business actions. It is not Synapsor Cloud and it is not the
+Synapsor C++ DBMS.
+
+Use a staging or disposable database first.
+
+Allowed current claims:
+
+- semantic MCP tools instead of raw SQL;
+- source database remains unchanged during proposal creation;
+- separate read and write credentials;
+- exact row diff;
+- local approval outside MCP;
+- tenant, column, version, affected-row, and idempotency checks;
+- approved app/API handler writeback with handler secrets kept in environment
+  variables;
+- shadow-mode comparison between agent proposals and human actions;
+- stale-row conflict detection in included fixtures;
+- local replay for proposal/evidence/approval/writeback receipts.
+
+Do not claim from this repository alone:
+
+- high availability;
+- compliance certification;
+- mission-critical SLA;
+- exactly-once across networks;
+- general MCP security;
+- prompt-injection immunity;
+- physical branches for Postgres/MySQL;
+- arbitrary business invariants are automatically understood.
+
+Synapsor Cloud is the production/team control plane for shared approvals, RBAC,
+hosted evidence/replay search, runner fleet status, leases, retention, audit
+visibility, and support.
+
+Before a public production-data claim, complete the release checklist, counsel
+review, security review, and operational validation.

package/docs/protocol.md

@@ -0,0 +1,90 @@
+# Protocol
+
+The public protocol has four versioned identifiers:
+
+```text
+synapsor.change-set.v1
+synapsor.writeback-job.v1
+synapsor.execution-receipt.v1
+synapsor.runner-registration.v1
+```
+
+The schemas live in `schemas/`. Golden fixtures live in `fixtures/protocol/` and are copied into the main Synapsor repository so Cloud/C++/SDK work can validate the same contract.
+
+`fixtures/protocol/MANIFEST.json` is the shared checksum note for the public protocol set. The same logical manifest is copied to the main Synapsor repository as `protocol/MANIFEST.json`. Tests in both repositories verify the SHA-256 digest for every schema and fixture.
+
+The current alpha write path supports one operation:
+
+```text
+single_row_update
+```
+
+It does not support arbitrary SQL, DDL, INSERT, DELETE, UPSERT, stored procedures, dynamic table/column names from model input, or multi-row writes.
+Schema, table, primary-key, tenant, conflict-guard, allowed-column, and patch
+column identifiers must be fixed safe identifiers. Path-traversal strings and
+SQL-fragment-like identifiers are rejected by protocol validation before the
+Postgres/MySQL adapter can run.
+
+## Change set
+
+`synapsor.change-set.v1` describes the proposal created after a semantic capability reads the current row and derives an exact diff. It includes:
+
+- proposal id and version;
+- action name;
+- trusted principal provenance;
+- tenant/business-object scope;
+- source table and primary key;
+- before/patch/after maps;
+- allowed columns;
+- expected version guard;
+- evidence bundle/query fingerprint;
+- approval state;
+- writeback state;
+- `source_database_mutated: false`;
+- proposal hash.
+
+## Writeback job
+
+`synapsor.writeback-job.v1` is the only object a runner may use to mutate the external database. Required fields include:
+
+- `writeback_job_id`;
+- `proposal_id`;
+- `proposal_version`;
+- `proposal_hash`;
+- `runner_scope.project_id`;
+- `runner_scope.source_id`;
+- `engine`;
+- `operation: single_row_update`;
+- `target.schema`;
+- `target.table`;
+- `target.primary_key`;
+- `tenant_guard`;
+- `allowed_columns`;
+- `patch`;
+- `conflict_guard`;
+- `idempotency_key`;
+- `lease`.
+
+The protocol package normalizes this public shape into the existing internal `protocol_version: "1.0"` worker shape so current Postgres/MySQL adapters remain stable while the public contract evolves.
+
+## Execution receipt
+
+`synapsor.execution-receipt.v1` records the terminal result:
+
+```text
+applied
+conflict
+failed
+canceled
+already_applied
+```
+
+Receipts include the writeback job id, proposal id, runner id, rows affected, idempotency key, version fields when available, source mutation state, safe error code, execution timestamp, and receipt hash.
+
+## Runner registration
+
+`synapsor.runner-registration.v1` describes a runner's id, version, supported engines, capabilities, project/source scope, and registration timestamp.
+
+## Compatibility
+
+Existing Cloud endpoints may still return the legacy `protocol_version: "1.0"` job/result envelope during migration. The runner validates both formats. New public examples and MCP work should use the `synapsor.*.v1` schema ids.

package/docs/recipes.md

@@ -0,0 +1,61 @@
+# Capability Recipes
+
+Recipes are reviewed starter contracts for common database-backed agent actions.
+
+They do not introspect and silently guess write authority. They generate a
+starter config that you must map to your actual staging table names, columns,
+tenant key, conflict column, and business limits.
+
+List recipes:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner recipes list
+```
+
+Inspect one:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner recipes show billing.late_fee_waiver
+```
+
+Initialize a starter config:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner recipes init billing.late_fee_waiver --output synapsor.runner.json
+npx -y -p @synapsor/runner@alpha synapsor-runner config validate --config synapsor.runner.json
+```
+
+Built-in recipes are JSON files under `recipes/`. They are starter data, not
+runtime hardcoding. You can copy one, edit table/column/tool names for your
+domain, and initialize from your file:
+
+```bash
+cp recipes/billing.late_fee_waiver.json my-recipe.json
+npx -y -p @synapsor/runner@alpha synapsor-runner recipes show ./my-recipe.json
+npx -y -p @synapsor/runner@alpha synapsor-runner recipes init ./my-recipe.json --output synapsor.runner.json
+```
+
+Available recipes:
+
+- `billing.late_fee_waiver`
+- `support.ticket_resolution`
+- `orders.refund_review`
+- `accounts.trial_extension`
+- `credits.account_credit`
+
+Each recipe includes:
+
+- expected table type;
+- required columns;
+- recommended primary key;
+- recommended tenant key;
+- recommended conflict/version column;
+- visible columns;
+- allowed write columns;
+- patch mapping;
+- numeric/status bounds where relevant;
+- semantic MCP tool names;
+- staging-first notes.
+
+Start with staging or a disposable database. Keep production write credentials
+out of the MCP client.

package/docs/roadmap.md

@@ -0,0 +1,13 @@
+# Roadmap
+
+Future packages can live in this same monorepo:
+
+- MCP adapter
+- LangGraph adapter
+- OpenAI Agents SDK adapter
+- CrewAI adapter
+- ORM helpers for Prisma, Drizzle, Django, Rails, and SQLAlchemy
+- Local read runner when product requirements and security review are complete
+
+Do not add package stubs until the implementation is ready.
+