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

package/docs/demo-transcript.md

@@ -1,73 +0,0 @@
-# First-Run Demo Transcript
-
-This is the expected high-level transcript for:
-
-```bash
-./scripts/try-synapsor.sh
-```
-
-Exact timings and log paths vary.
-
-```text
-Synapsor Runner first-run demo
-
-You are about to see an MCP agent propose a database change without receiving SQL or write credentials.
-Full logs will be written to: ./.synapsor/logs/try-synapsor-<timestamp>.log
-
-Step 1: MCP tools exposed
-  In this fixture, the model sees semantic tools such as billing.inspect_invoice and billing.propose_late_fee_waiver.
-
-Step 2: Agent inspects business object
-Step 3: Agent proposes change
-Step 4: Source DB changed: No
-Step 5: Human approval outside MCP
-Step 6: Trusted runner applies guarded writeback
-Step 7: Replay explains what happened
-Step 8: Extra safety checks catch stale rows and unsafe tools
-
-Running the disposable Docker proof. This can take a few minutes...
-
-Success. You saw the Synapsor commit boundary.
-
-In the included fixture, the model got:
-* billing.inspect_invoice
-* billing.propose_late_fee_waiver
-
-The model did not get:
-* execute_sql
-* write credentials
-* approve/commit tools
-
-Next:
-
-1. Open proposal UI:
-   npx -y -p @synapsor/runner@alpha synapsor ui --tour --config ./examples/mcp-postgres-billing/synapsor.runner.json --store ./.synapsor/local.db
-
-2. Run the reference app:
-   corepack pnpm demo:reference
-
-3. Generate MCP client config:
-   npx -y -p @synapsor/runner@alpha synapsor mcp config --absolute-paths --config ./examples/mcp-postgres-billing/synapsor.runner.json --store ./.synapsor/local.db
-
-4. Use your own staging Postgres/MySQL:
-   export DATABASE_URL='<postgres-or-mysql-read-url>'
-   npx -y -p @synapsor/runner@alpha synapsor inspect --from-env DATABASE_URL
-   npx -y -p @synapsor/runner@alpha synapsor init --wizard --from-env DATABASE_URL
-```
-
-The full log should include the lower-level proof:
-
-- local MCP Postgres example passed;
-- local MCP MySQL example passed;
-- `ACCEPT semantic tools present`;
-- `ACCEPT execute_sql approval and commit tools absent`;
-- `ACCEPT proposal created successfully`;
-- `ACCEPT source row unchanged after proposal`;
-- `ACCEPT approval happened outside MCP`;
-- `ACCEPT guarded writeback applied`;
-- retry was idempotent;
-- `ACCEPT stale-row conflict detected`;
-- `ACCEPT replay export contains applied receipt`.
-
-The first-run script fails if the log appears to contain database URLs,
-fixture passwords, or bearer tokens.

package/docs/dependency-license-inventory.md

@@ -1,35 +0,0 @@
-# Dependency License Inventory
-
-Generated during the ELv2 migration with:
-
-```bash
-corepack pnpm licenses list --json
-```
-
-Summary from the current lockfile/install:
-
-| 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 ELv2 migration.
-
-Before public release:
-
-- regenerate this inventory from a clean install;
-- review dependency notices with counsel or the release owner;
-- keep third-party notices separate from the first-party Synapsor Runner
-  license.

package/docs/first-10-minutes.md

@@ -1,147 +0,0 @@
-# First 10 Minutes
-
-This path is for a developer who cloned Synapsor Runner and wants to understand
-the product without reading the full docs first.
-
-## What You Need
-
-- Docker CLI.
-- Reachable Docker daemon.
-- Free local ports: `55433`, `55434`, `55435`, and `53307`.
-- A few GB of free disk for the local demo image and disposable databases.
-
-You do not need:
-
-- Synapsor Cloud account.
-- API key.
-- Hosted workspace.
-- Host Node/Corepack setup for the first command.
-- Database credentials.
-
-## Run One Command
-
-```bash
-./scripts/try-synapsor.sh
-```
-
-The script writes noisy logs to:
-
-```text
-./.synapsor/logs/try-synapsor-<timestamp>.log
-```
-
-If something fails, it prints the failing check and the log path.
-
-## What The Script Proves
-
-The script runs disposable Postgres and MySQL MCP examples and checks that the
-demo actually proves the Synapsor boundary:
-
-- MCP `tools/list` contains semantic tools.
-- MCP `tools/list` does not contain `execute_sql`.
-- The agent inspects one business row through trusted tenant scope.
-- The agent creates a proposal with an exact before/after diff.
-- The source row is unchanged after proposal creation.
-- Approval happens outside the model-facing MCP tool surface.
-- The trusted runner applies a reviewed single-row writeback or blocks a stale
-  row conflict.
-- Replay exists for the proposal, evidence, approval, receipt, and conflict
-  decision.
-- The first-run log does not contain database URLs, passwords, bearer tokens, or
-  write credentials.
-
-## The Mental Model
-
-```text
-MCP client
-  -> semantic business tool
-  -> trusted tenant/principal context
-  -> scoped read from Postgres/MySQL
-  -> evidence and exact proposal diff
-  -> local approval outside MCP
-  -> guarded single-row writeback
-  -> applied/conflict/failed receipt
-  -> local replay
-```
-
-The model gets inspect/propose authority. The trusted runner owns commit
-authority.
-
-## Next Command 1: Open The Local UI
-
-```bash
-npx -y -p @synapsor/runner@alpha synapsor ui --tour \
-  --config ./examples/mcp-postgres-billing/synapsor.runner.json \
-  --store ./.synapsor/local.db
-```
-
-The UI binds to `127.0.0.1`, prints a local URL with a per-run token, and shows
-the proposal/evidence/replay loop. Approval and rejection require CSRF
-protection.
-
-## Next Command 2: Run The Reference App
-
-```bash
-corepack pnpm demo:reference
-```
-
-The reference app uses a disposable support/billing Postgres database and proves:
-
-- semantic MCP tools;
-- source DB unchanged after proposal;
-- approval outside MCP;
-- guarded writeback;
-- stale-row conflict;
-- replay export.
-
-## Next Command 3: Generate MCP Client Config
-
-```bash
-npx -y -p @synapsor/runner@alpha synapsor mcp config claude-desktop \
-  --absolute-paths \
-  --config ./examples/mcp-postgres-billing/synapsor.runner.json \
-  --store ./.synapsor/local.db
-```
-
-Paste the printed JSON into your MCP client settings. The config contains
-command paths only. It must not contain database URLs, passwords, approval
-tools, commit tools, or write credentials.
-
-Verify the configured tool boundary with:
-
-```bash
-npx -y -p @synapsor/runner@alpha synapsor tools preview \
-  --config ./examples/mcp-postgres-billing/synapsor.runner.json \
-  --store ./.synapsor/local.db
-```
-
-## Next Command 4: Use Your Own Staging Database
-
-After the fixture demo makes sense, point the local runtime at one staging
-Postgres/MySQL database:
-
-```bash
-export DATABASE_URL="<postgres-or-mysql-read-url>"
-./scripts/use-your-db.sh
-```
-
-The wrapper inspects metadata, opens the guided config wizard, previews the MCP
-tool boundary, and prints the serve/UI commands. It does not print your
-database URL or write credentials.
-
-## Reset
-
-If a prior run left stale containers, ports, logs, or local stores:
-
-```bash
-./scripts/try-synapsor.sh --reset
-```
-
-For noninteractive cleanup in CI:
-
-```bash
-./scripts/try-synapsor.sh --reset --yes
-```
-
-The reset path removes demo containers, demo volumes, temporary local stores,
-generated MCP snippets under `.synapsor/mcp`, and first-run logs.

package/docs/licensing.md

@@ -1,38 +0,0 @@
-# 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/local-ui.md

@@ -1,163 +0,0 @@
-# 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-efficiency-benchmark.md

@@ -1,84 +0,0 @@
-# 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 benchmark mcp-efficiency
-```
-
-For machine-readable output:
-
-```bash
-npx -y -p @synapsor/runner@alpha synapsor 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

@@ -1,38 +0,0 @@
-# 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 doctor
-npx -y -p @synapsor/runner@alpha synapsor validate --job examples/postgres-support/job.approved.json
-npx -y -p @synapsor/runner@alpha synapsor 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.