@synapsor/runner 0.1.0-alpha.4 → 0.1.0-alpha.6

package/docs/first-10-minutes.md

@@ -1,172 +0,0 @@
-# First 10 Minutes
-
-This path is for a developer who wants to understand Synapsor Runner without
-reading the full docs first.
-
-## Fastest First Look
-
-If you only want the 15-second value proof and have Node >= 22.5.0:
-
-```bash
-npx -y -p @synapsor/runner@alpha synapsor demo --quick
-```
-
-The local-ledger quick fixture requires this checkout or package version
-`0.1.0-alpha.4` or newer. If `npm view @synapsor/runner@alpha version` reports
-an older alpha, run `./bin/synapsor demo --quick` from this checkout until the
-next alpha is published.
-
-That command does not require Docker, a database, a config file, an MCP client,
-or a Synapsor Cloud account. It seeds `./.synapsor/quick-demo.db` with a local
-proposal/evidence/replay fixture you can inspect:
-
-```bash
-synapsor activity search --object invoice:INV-3001 --store ./.synapsor/quick-demo.db
-synapsor replay show latest --store ./.synapsor/quick-demo.db
-```
-
-Use the Docker-backed path below when you want the full disposable
-Postgres/MySQL proof with guarded writeback.
-
-## 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.