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

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/open-source-feature-inventory.md

@@ -1,254 +0,0 @@
-# Synapsor Runner Open-Source Feature Inventory
-
-Date: 2026-06-23
-
-Branch inspected: `runner-segment-scale-adoption`
-
-This inventory tracks the open-source runner boundary. It is not a list of
-Synapsor Cloud or Synapsor DBMS features.
-
-## Summary
-
-Synapsor Runner now has a local evidence/replay ledger for real
-Postgres/MySQL-backed MCP interactions:
-
-- config-defined semantic MCP tools instead of raw SQL;
-- trusted tenant/principal context binding;
-- scoped source reads;
-- local evidence bundles and query audit;
-- proposal-first writes with before/proposed diffs;
-- local approval/rejection outside MCP;
-- guarded single-row writeback;
-- writeback receipts;
-- proposal replay;
-- local indexed search over proposals, evidence, query audit, receipts, and
-  replay links.
-- npm/package trust checks for the public `synapsor` bin and legacy
-  `synapsor-runner` alias;
-- a fixture-only `demo --quick` that seeds an inspectable local ledger without
-  Docker;
-- shareable MCP audit JSON/Markdown output;
-- redacted doctor Markdown report output.
-
-The local store is SQLite and intended for local/dev/staging usage. It is not a
-hosted central audit ledger, not RBAC/SSO, not cross-runner search, not
-enterprise retention, and not compliance export.
-
-## Implemented Local Concepts
-
-| Synapsor concept | Runner implementation | Status |
-| --- | --- | --- |
-| Context bindings | Trusted tenant/principal from env/static dev/HTTP/cloud session config | Implemented |
-| Capabilities | Reviewed semantic MCP tools from `synapsor.runner.json` | Implemented |
-| Evidence bundles | Captured/projected rows and metadata persisted locally | Implemented |
-| Query audit | Source/table/fingerprint/row-count/redacted-parameter records | Implemented |
-| Proposals | Immutable before/proposed change sets | Implemented |
-| Approval | Local CLI/UI approval/rejection outside MCP | Implemented |
-| Guarded writeback | Single-row Postgres/MySQL `UPDATE` with primary-key, tenant, allowed-column, conflict, idempotency, and affected-row checks | Implemented |
-| Receipts | Applied/conflict/failed writeback receipts | Implemented |
-| Replay | Proposal replay from local captured records | Implemented |
-| MCP audit | Static risk review for database MCP tool shapes | Implemented |
-| Local indexed search | CLI filters for activity, proposals, evidence, query audit, and receipts | Implemented |
-
-## New Local Ledger Commands
-
-```bash
-synapsor activity search --tenant acme --object invoice:INV-3001
-synapsor proposals list --tenant acme --capability billing.propose_late_fee_waiver --object invoice:INV-3001 --status approved
-synapsor evidence list --tenant acme --capability billing.inspect_invoice --source app_postgres --table invoices
-synapsor evidence show ev_...
-synapsor evidence export ev_... --format json --output evidence.json
-synapsor evidence export ev_... --format markdown --output evidence.md
-synapsor query-audit list --evidence ev_... --source app_postgres --table invoices
-synapsor query-audit show <audit_id>
-synapsor query-audit export <audit_id> --format json --output audit.json
-synapsor receipts list --proposal wrp_...
-synapsor receipts show <receipt_id>
-synapsor replay show --proposal wrp_...
-synapsor replay show --replay replay_wrp_...
-synapsor replay show --evidence ev_...
-synapsor replay export --proposal wrp_... --format json --output replay.json
-synapsor replay export --proposal wrp_... --format markdown --output replay.md
-synapsor doctor --config synapsor.runner.json --report --redact --output synapsor-doctor.md
-synapsor store stats --store ./.synapsor/local.db
-synapsor store vacuum --store ./.synapsor/local.db
-synapsor store prune --store ./.synapsor/local.db --older-than 30d --dry-run
-```
-
-Unknown top-level commands now return a nonzero error instead of generic help.
-Unsupported flags on the new search/list commands fail clearly rather than
-being silently ignored.
-
-## Local Store Schema And Search
-
-The store remains backward-compatible with existing local SQLite files. New
-metadata columns are nullable and are backfilled from existing JSON where safe.
-
-New/important searchable metadata:
-
-- proposal tenant, principal, capability/action, business object, object id,
-  state, source, table, created time;
-- evidence tenant, principal, capability, proposal id, business object, object
-  id, source, table, query fingerprint, created time;
-- query audit tenant, proposal id, evidence id, source, table, primary-key
-  value, query fingerprint, created time;
-- writeback receipt proposal id, writeback job id, idempotency key, status,
-  created time.
-
-Indexes are created idempotently on the local store for:
-
-- proposals by tenant/time, action/time, capability/time, principal/time,
-  object/time, state/time, source/table/time;
-- evidence bundles by tenant/time, proposal id, created time, capability/time,
-  principal/time, object/time, source/table/time, query fingerprint/time;
-- evidence items by evidence bundle id;
-- query audit by evidence id, proposal id, source/table/time,
-  query fingerprint/time, tenant/time, object/time, primary-key/time;
-- writeback receipts by proposal id, writeback job id, idempotency key,
-  status/time;
-- replay records by proposal id and created time;
-- approvals by proposal id and status/time;
-- proposal events by proposal id and kind/time.
-
-These are local metadata indexes. Runner does not index customer Postgres/MySQL
-tables.
-
-## Read-Only Evidence
-
-Read-only MCP tools can record evidence bundles and query-audit rows. The MCP
-tool response returns an evidence handle. The user can now inspect that handle
-later:
-
-```bash
-synapsor evidence show ev_...
-synapsor evidence list --tenant acme --capability billing.inspect_invoice
-synapsor query-audit list --evidence ev_...
-synapsor activity search --tenant acme --source app_postgres --table invoices
-```
-
-Read-only evidence inspection does not rerun the external database read. It
-shows captured/projected evidence that was already persisted locally.
-
-Proposal replay remains proposal-centric. `replay show --evidence ev_...`
-works only when the evidence bundle is linked to a replayable proposal.
-
-## Replay Versus Time Travel
-
-Runner replay is local captured interaction replay:
-
-```text
-trusted context
--> captured source-row excerpt
--> query audit/fingerprint
--> proposal before/proposed diff
--> approval/rejection events
--> writeback job
--> terminal receipt
-```
-
-It is not:
-
-- external DB time travel;
-- `AS OF` query support over Postgres/MySQL;
-- native branch creation;
-- external DB merge;
-- auto-merge;
-- settlement-policy execution.
-
-Synapsor-native branching, time travel, settlement, and workflow DAG execution
-remain proprietary Synapsor Cloud/DBMS features.
-
-## MCP Resource Boundary
-
-MCP resources remain read-only:
-
-- `synapsor://proposals/{proposal_id}`;
-- `synapsor://evidence/{evidence_bundle_id}`;
-- `synapsor://replay/{replay_id}`.
-
-They inspect local store records and do not mutate source databases. They also
-do not list/search all local records through MCP; local search is a CLI/local UI
-concern.
-
-## Not Included In OSS Runner
-
-- C++ DBMS internals;
-- native Synapsor branches;
-- external DB time travel;
-- `AS OF` external DB queries;
-- external DB merge;
-- auto-merge;
-- settlement policies;
-- workflow DAG engine;
-- `CREATE AGENT WORKFLOW`;
-- hosted workflow graph builder;
-- governed memory;
-- RBAC/SSO;
-- hosted evidence ledger;
-- central org-wide activity search;
-- managed runner fleet;
-- compliance exports;
-- enterprise retention controls;
-- production CDC machinery.
-
-## Safety Boundary Verification
-
-The runner keeps these out of the model-facing MCP tool surface:
-
-- `execute_sql`;
-- `raw_sql`;
-- `query_database`;
-- approval tools;
-- reject tools;
-- apply/commit/writeback tools;
-- database URLs;
-- write credentials;
-- model-controlled tenant authority.
-
-Approval, rejection, and writeback stay in CLI/UI/app-handler/runner paths
-outside the MCP tool surface.
-
-## Current Rough Edges
-
-- The local UI is still proposal-review oriented. The CLI now has first-class
-  local evidence/search commands, but UI search/export for evidence/query-audit
-  is not yet a full dedicated workflow.
-- Read-only evidence has CLI inspection and activity search, but read-only
-  replay is not a standalone replay object unless linked to a proposal.
-- The current direct DB writeback adapter intentionally supports guarded
-  single-row `UPDATE` only. App-owned HTTP/command handlers are the path for
-  richer business writes.
-- The alpha package requires Node >= 22.5.0 because the local ledger uses
-  Node's `node:sqlite` runtime. The package declares this and the bin wrapper
-  exits early with a clear message on older Node versions.
-
-## Tests Covering This Inventory
-
-Relevant local tests:
-
-```bash
-corepack pnpm exec vitest run packages/proposal-store/src/index.test.ts
-corepack pnpm exec vitest run apps/runner/src/cli.test.ts
-corepack pnpm exec vitest run packages/mcp-server/src/index.test.ts
-corepack pnpm test:first-run
-corepack pnpm test:mcp-client-configs
-./scripts/verify-public-commands.sh
-./scripts/verify-packed-runner.sh
-```
-
-The current implementation pass specifically added coverage for:
-
-- unknown command nonzero behavior;
-- unsupported search flags failing clearly;
-- proposal filters by tenant/capability/object/status;
-- evidence show/list/export JSON/Markdown;
-- query-audit list/show/export;
-- receipts list/show;
-- replay by proposal id, replay id, and linked evidence id;
-- replay JSON and Markdown export;
-- activity search by tenant/object;
-- local metadata indexes and idempotent migration/reopen.
-- `demo --quick` creating an inspectable local fixture store;
-- built-in audit example JSON/Markdown output;
-- clean packed-tarball command execution.
-- local store stats, vacuum, and dry-run/apply prune.

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.