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

package/docs/open-source-feature-inventory.md

@@ -0,0 +1,254 @@
+# 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/security-boundary.md

@@ -3,6 +3,23 @@
 Synapsor Runner controls a narrow database path for MCP agents. It does not make
 MCP generally secure and it does not solve prompt injection.
 
+## Least-privilege database access
+
+Use a read-only database user, restricted views, row-level security, and staging
+data where appropriate. Synapsor Runner is not a replacement for database
+permissions.
+
+Database permissions protect the connection. Synapsor Runner shapes the
+model-facing interface: reviewed semantic capabilities, trusted context
+binding, evidence handles, query audit, local inspection, and proposal-first
+writes instead of model-facing commit authority.
+
+If all you need is restricted reads, database permissions are a good start.
+Use Synapsor Runner when you also want the agent-facing layer: semantic tools,
+trusted context, evidence handles, query audit, local inspection, and
+proposal-first writes. Proposal workflows add full replay across evidence,
+approval, writeback receipts, and events.
+
 The model-facing MCP server exposes reviewed semantic tools such as
 `billing.inspect_invoice` and `billing.propose_late_fee_waiver`.
 

package/examples/reference-support-billing-app/README.md

@@ -54,11 +54,62 @@ The model-facing MCP tools are:
 
 - `support.inspect_ticket`
 - `support.propose_ticket_resolution`
+- `support.inspect_customer_account`
+- `support.propose_plan_credit`
 - `billing.inspect_invoice`
 - `billing.propose_late_fee_waiver`
+- `orders.inspect_order`
+- `orders.propose_status_change`
 
 The model does not receive approval tools, commit tools, write credentials, raw SQL, arbitrary table names, arbitrary column names, or tenant authority.
 
+## Safe Write Examples
+
+After `synapsor demo` or after starting this fixture manually, try the same
+proposal-first loop without connecting an MCP client:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor propose billing.propose_late_fee_waiver --sample
+npx -y -p @synapsor/runner@alpha synapsor proposals show latest
+npx -y -p @synapsor/runner@alpha synapsor proposals approve latest --yes
+npx -y -p @synapsor/runner@alpha synapsor apply latest
+npx -y -p @synapsor/runner@alpha synapsor replay latest
+```
+
+Expected safety output:
+
+```text
+Source DB changed:
+no
+
+Guarded writeback applied.
+* proposal approved: yes
+* primary key matched: yes
+* tenant guard matched: yes
+* allowed columns only: yes
+* conflict guard passed: yes
+```
+
+Other proposal examples use the same review/apply/replay path:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor propose support.propose_plan_credit --sample
+npx -y -p @synapsor/runner@alpha synapsor propose orders.propose_status_change --sample
+```
+
+Safety guarantees:
+
+- proposals store evidence, a before/after diff, trusted tenant/principal
+  context, and query audit before any write;
+- approval stays outside the model-facing MCP tool surface;
+- writeback is single-row, primary-key targeted, tenant guarded,
+  allowed-column checked, idempotent, and conflict guarded;
+- stale rows return `conflict` and are replayable.
+
+Current limitation: v0.1 is intentionally local and single-user. It does not
+provide hosted RBAC, workflow DAGs, branches, settlement policies, auto-merge,
+or production-scale runner orchestration.
+
 ## Review And Replay
 
 After a proposal exists:

package/examples/reference-support-billing-app/schema.sql

@@ -11,6 +11,8 @@ CREATE TABLE IF NOT EXISTS public.customers (
   name text NOT NULL,
   email text,
   plan text NOT NULL,
+  plan_credit_cents integer NOT NULL DEFAULT 0,
+  credit_reason text,
   created_at timestamptz NOT NULL DEFAULT now(),
   updated_at timestamptz NOT NULL DEFAULT now()
 );
@@ -36,6 +38,15 @@ CREATE TABLE IF NOT EXISTS public.invoices (
   updated_at timestamptz NOT NULL DEFAULT now()
 );
 
+CREATE TABLE IF NOT EXISTS public.orders (
+  id text PRIMARY KEY,
+  tenant_id text NOT NULL REFERENCES public.tenants(id),
+  customer_id text NOT NULL REFERENCES public.customers(id),
+  status text NOT NULL,
+  status_change_reason text,
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+
 DO $$
 BEGIN
   IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'synapsor_reader') THEN
@@ -50,6 +61,8 @@ $$;
 GRANT CONNECT ON DATABASE synapsor_reference_support_billing TO synapsor_reader, synapsor_writer;
 GRANT USAGE ON SCHEMA public TO synapsor_reader, synapsor_writer;
 GRANT CREATE ON SCHEMA public TO synapsor_writer;
-GRANT SELECT ON public.tenants, public.customers, public.support_tickets, public.invoices TO synapsor_reader, synapsor_writer;
+GRANT SELECT ON public.tenants, public.customers, public.support_tickets, public.invoices, public.orders TO synapsor_reader, synapsor_writer;
+GRANT UPDATE (plan_credit_cents, credit_reason, updated_at) ON public.customers TO synapsor_writer;
 GRANT UPDATE (status, resolution_note, updated_at) ON public.support_tickets TO synapsor_writer;
 GRANT UPDATE (late_fee_cents, waiver_reason, updated_at) ON public.invoices TO synapsor_writer;
+GRANT UPDATE (status, status_change_reason, updated_at) ON public.orders TO synapsor_writer;

package/examples/reference-support-billing-app/seed.sql

@@ -4,12 +4,12 @@ VALUES
   ('otherco', 'OtherCo Labs', '2026-06-20T10:00:00Z', '2026-06-20T10:00:00Z')
 ON CONFLICT (id) DO UPDATE SET name = EXCLUDED.name, updated_at = EXCLUDED.updated_at;
 
-INSERT INTO public.customers (id, tenant_id, name, email, plan, created_at, updated_at)
+INSERT INTO public.customers (id, tenant_id, name, email, plan, plan_credit_cents, credit_reason, created_at, updated_at)
 VALUES
-  ('cust_acme_1', 'acme', 'Acme Robotics', 'ops@example.invalid', 'enterprise', '2026-06-20T10:00:00Z', '2026-06-20T10:00:00Z'),
-  ('cust_acme_2', 'acme', 'Acme Field Ops', 'field@example.invalid', 'builder', '2026-06-20T10:00:00Z', '2026-06-20T10:00:00Z'),
-  ('cust_other_1', 'otherco', 'OtherCo Labs', 'ops@otherco.invalid', 'builder', '2026-06-20T10:00:00Z', '2026-06-20T10:00:00Z')
-ON CONFLICT (id) DO UPDATE SET tenant_id = EXCLUDED.tenant_id, name = EXCLUDED.name, email = EXCLUDED.email, plan = EXCLUDED.plan, updated_at = EXCLUDED.updated_at;
+  ('cust_acme_1', 'acme', 'Acme Robotics', 'ops@example.invalid', 'enterprise', 0, NULL, '2026-06-20T10:00:00Z', '2026-06-20T10:00:00Z'),
+  ('cust_acme_2', 'acme', 'Acme Field Ops', 'field@example.invalid', 'builder', 0, NULL, '2026-06-20T10:00:00Z', '2026-06-20T10:00:00Z'),
+  ('cust_other_1', 'otherco', 'OtherCo Labs', 'ops@otherco.invalid', 'builder', 0, NULL, '2026-06-20T10:00:00Z', '2026-06-20T10:00:00Z')
+ON CONFLICT (id) DO UPDATE SET tenant_id = EXCLUDED.tenant_id, name = EXCLUDED.name, email = EXCLUDED.email, plan = EXCLUDED.plan, plan_credit_cents = EXCLUDED.plan_credit_cents, credit_reason = EXCLUDED.credit_reason, updated_at = EXCLUDED.updated_at;
 
 INSERT INTO public.support_tickets (id, tenant_id, customer_id, subject, status, resolution_note, updated_at)
 VALUES
@@ -24,3 +24,10 @@ VALUES
   ('INV-3002', 'acme', 'cust_acme_2', 'paid', 0, 0, NULL, '2026-06-20T14:40:00Z'),
   ('INV-9001', 'otherco', 'cust_other_1', 'overdue', 25500, 5500, NULL, '2026-06-20T14:31:08Z')
 ON CONFLICT (id) DO UPDATE SET tenant_id = EXCLUDED.tenant_id, customer_id = EXCLUDED.customer_id, status = EXCLUDED.status, balance_cents = EXCLUDED.balance_cents, late_fee_cents = EXCLUDED.late_fee_cents, waiver_reason = EXCLUDED.waiver_reason, updated_at = EXCLUDED.updated_at;
+
+INSERT INTO public.orders (id, tenant_id, customer_id, status, status_change_reason, updated_at)
+VALUES
+  ('O-1001', 'acme', 'cust_acme_1', 'paid', NULL, '2026-06-20T13:00:00Z'),
+  ('O-1002', 'acme', 'cust_acme_2', 'processing', NULL, '2026-06-20T13:05:00Z'),
+  ('O-9001', 'otherco', 'cust_other_1', 'paid', NULL, '2026-06-20T13:00:00Z')
+ON CONFLICT (id) DO UPDATE SET tenant_id = EXCLUDED.tenant_id, customer_id = EXCLUDED.customer_id, status = EXCLUDED.status, status_change_reason = EXCLUDED.status_change_reason, updated_at = EXCLUDED.updated_at;

package/examples/reference-support-billing-app/synapsor.runner.json

@@ -83,6 +83,56 @@
       "conflict_guard": { "column": "updated_at" },
       "approval": { "mode": "human", "required_role": "support_lead" }
     },
+    {
+      "name": "support.inspect_customer_account",
+      "kind": "read",
+      "source": "app_postgres",
+      "context": "local_operator",
+      "target": {
+        "schema": "public",
+        "table": "customers",
+        "primary_key": "id",
+        "tenant_key": "tenant_id"
+      },
+      "args": {
+        "customer_id": { "type": "string", "required": true, "max_length": 128 }
+      },
+      "lookup": { "id_from_arg": "customer_id" },
+      "visible_columns": ["id", "tenant_id", "name", "plan", "plan_credit_cents", "credit_reason", "updated_at"],
+      "evidence": "required",
+      "max_rows": 1
+    },
+    {
+      "name": "support.propose_plan_credit",
+      "kind": "proposal",
+      "source": "app_postgres",
+      "context": "local_operator",
+      "target": {
+        "schema": "public",
+        "table": "customers",
+        "primary_key": "id",
+        "tenant_key": "tenant_id"
+      },
+      "args": {
+        "customer_id": { "type": "string", "required": true, "max_length": 128 },
+        "credit_cents": { "type": "number", "required": true, "minimum": 0, "maximum": 5000 },
+        "reason": { "type": "string", "required": true, "max_length": 500 }
+      },
+      "lookup": { "id_from_arg": "customer_id" },
+      "visible_columns": ["id", "tenant_id", "name", "plan", "plan_credit_cents", "credit_reason", "updated_at"],
+      "evidence": "required",
+      "max_rows": 1,
+      "patch": {
+        "plan_credit_cents": { "from_arg": "credit_cents" },
+        "credit_reason": { "from_arg": "reason" }
+      },
+      "allowed_columns": ["plan_credit_cents", "credit_reason"],
+      "numeric_bounds": {
+        "plan_credit_cents": { "minimum": 0, "maximum": 5000 }
+      },
+      "conflict_guard": { "column": "updated_at" },
+      "approval": { "mode": "human", "required_role": "support_lead" }
+    },
     {
       "name": "billing.inspect_invoice",
       "kind": "read",
@@ -131,6 +181,61 @@
       },
       "conflict_guard": { "column": "updated_at" },
       "approval": { "mode": "human", "required_role": "billing_lead" }
+    },
+    {
+      "name": "orders.inspect_order",
+      "kind": "read",
+      "source": "app_postgres",
+      "context": "local_operator",
+      "target": {
+        "schema": "public",
+        "table": "orders",
+        "primary_key": "id",
+        "tenant_key": "tenant_id"
+      },
+      "args": {
+        "order_id": { "type": "string", "required": true, "max_length": 128 }
+      },
+      "lookup": { "id_from_arg": "order_id" },
+      "visible_columns": ["id", "tenant_id", "customer_id", "status", "status_change_reason", "updated_at"],
+      "evidence": "required",
+      "max_rows": 1
+    },
+    {
+      "name": "orders.propose_status_change",
+      "kind": "proposal",
+      "source": "app_postgres",
+      "context": "local_operator",
+      "target": {
+        "schema": "public",
+        "table": "orders",
+        "primary_key": "id",
+        "tenant_key": "tenant_id"
+      },
+      "args": {
+        "order_id": { "type": "string", "required": true, "max_length": 128 },
+        "status": { "type": "string", "required": true, "enum": ["ready_to_ship", "canceled"] },
+        "reason": { "type": "string", "required": true, "max_length": 500 }
+      },
+      "lookup": { "id_from_arg": "order_id" },
+      "visible_columns": ["id", "tenant_id", "customer_id", "status", "status_change_reason", "updated_at"],
+      "evidence": "required",
+      "max_rows": 1,
+      "patch": {
+        "status": { "from_arg": "status" },
+        "status_change_reason": { "from_arg": "reason" }
+      },
+      "allowed_columns": ["status", "status_change_reason"],
+      "transition_guards": {
+        "status": {
+          "allowed": {
+            "paid": ["ready_to_ship", "canceled"],
+            "processing": ["ready_to_ship"]
+          }
+        }
+      },
+      "conflict_guard": { "column": "updated_at" },
+      "approval": { "mode": "human", "required_role": "orders_lead" }
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synapsor/runner",
-  "version": "0.1.0-alpha.3",
+  "version": "0.1.0-alpha.4",
   "description": "Commit-safe MCP runner for Postgres and MySQL agents",
   "license": "Apache-2.0",
   "type": "module",