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

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.

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

@@ -1,185 +0,0 @@
-# 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 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 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 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 config validate --config synapsor.runner.json
-npx -y -p @synapsor/runner@alpha synapsor doctor --config synapsor.runner.json
-npx -y -p @synapsor/runner@alpha synapsor 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 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 proposals list --store ./.synapsor/local.db
-npx -y -p @synapsor/runner@alpha synapsor proposals show <proposal_id> --store ./.synapsor/local.db
-npx -y -p @synapsor/runner@alpha synapsor replay show <proposal_id> --store ./.synapsor/local.db
-```
-
-Open the UI:
-
-```bash
-npx -y -p @synapsor/runner@alpha synapsor 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 proposals approve <proposal_id> --store ./.synapsor/local.db --actor local_reviewer --yes
-npx -y -p @synapsor/runner@alpha synapsor 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 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

@@ -1,39 +0,0 @@
-# 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

@@ -1,90 +0,0 @@
-# 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/roadmap.md

@@ -1,13 +0,0 @@
-# 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.
-