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

package/docs/MCP_RUNNER_IMPLEMENTATION_PLAN.md

@@ -152,7 +152,7 @@ This plan maps the existing open-source runner repository to the commit-safe dat
 ## Release blockers
 
 - Live hosted Cloud-linked E2E still requires a compatible Synapsor Cloud workspace, adapter, and scoped runner token. A local hosted-compatible Cloud-linked smoke now covers the protocol/API lifecycle against a mock Cloud API and real disposable Postgres writeback.
-- `packages/proposal-store` currently uses Node 22 `node:sqlite`, which is still marked experimental by Node. Before a public runner release, either pin/support that runtime explicitly or replace it with a stable SQLite dependency.
+- `packages/proposal-store` uses Node 22 `node:sqlite`. The alpha package pins Node >= 22.5.0 in `engines` and the package/source wrappers fail early with a clear message on older Node versions. Replacing this with a broader-LTS SQLite dependency remains a future compatibility option.
 - Release docs present: `LICENSE` is Apache License 2.0, and `CONTRIBUTING.md` / `CODE_OF_CONDUCT.md` exist with project-specific safety guidance.
 
 ## Verification log

package/docs/cloud-mode.md

@@ -53,7 +53,7 @@ Cloud mode uses the same MCP server command with a `mode: "cloud"` config:
     "base_url_env": "SYNAPSOR_CLOUD_BASE_URL",
     "runner_token_env": "SYNAPSOR_RUNNER_TOKEN",
     "runner_id": "synapsor_runner_local",
-    "runner_version": "0.1.0-alpha.3",
+    "runner_version": "0.1.0-alpha.4",
     "project_id": "token_scope",
     "adapter_id": "mcp.your_adapter",
     "source_id": "src_replace_me",

package/docs/demo-transcript.md

@@ -1,73 +1,161 @@
-# First-Run Demo Transcript
+# Demo Transcript
 
-This is the expected high-level transcript for:
+This transcript shows the intended public demo path. Exact timestamps, hashes,
+ports, and generated proposal ids vary.
+
+## Quick demo
 
 ```bash
-./scripts/try-synapsor.sh
+npx -y -p @synapsor/runner@alpha synapsor demo --quick
 ```
 
-Exact timings and log paths vary.
+The local-ledger fixture output below requires this checkout or package version
+`0.1.0-alpha.4` or newer.
+
+Expected shape:
 
 ```text
-Synapsor Runner first-run demo
+Synapsor Runner quick 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
+This is a fixture-only first look. It does not start Docker, connect a database,
+or require an MCP client. It writes an inspectable local ledger fixture to:
+./.synapsor/quick-demo.db
 
-Step 1: MCP tools exposed
-  In this fixture, the model sees semantic tools such as billing.inspect_invoice and billing.propose_late_fee_waiver.
+Raw MCP shape:
+execute_sql(sql: string)
+Risk: the model can write arbitrary SQL with database authority.
 
-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
+Synapsor shape:
+billing.inspect_invoice(invoice_id)
+billing.propose_late_fee_waiver(invoice_id, reason)
 
-Running the disposable Docker proof. This can take a few minutes...
+Agent requested:
+billing.propose_late_fee_waiver(invoice_id="INV-3001", reason="approved support waiver")
 
-Success. You saw the Synapsor commit boundary.
+Trusted context:
+tenant_id = acme
+principal = support.agent
 
-In the included fixture, the model got:
-* billing.inspect_invoice
-* billing.propose_late_fee_waiver
+Proposal:
+invoice.late_fee_cents: 5500 -> 0
 
-The model did not get:
-* execute_sql
-* write credentials
-* approve/commit tools
+Source DB changed:
+no
 
-Next:
+Approval:
+required outside MCP
+
+Replay:
+replay_wrp_quick_INV_3001 captures the local proposal, evidence handle, query audit, and events.
+```
 
-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
+Inspect the fixture:
+
+```bash
+synapsor proposals show latest --store ./.synapsor/quick-demo.db
+synapsor activity search --object invoice:INV-3001 --store ./.synapsor/quick-demo.db
+synapsor replay show latest --store ./.synapsor/quick-demo.db
+```
 
-2. Run the reference app:
-   corepack pnpm demo:reference
+## Full Docker-backed demo
 
-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
+Start the disposable local Postgres demo:
 
-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
+```bash
+synapsor demo
 ```
 
-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.
+Expected shape:
+
+```text
+Synapsor Runner demo
+
+Raw database MCP tools can hand the model SQL and write authority.
+Synapsor Runner exposes semantic capabilities instead:
+  billing.inspect_invoice
+  billing.propose_late_fee_waiver
+
+Demo flow:
+proposal first -> source unchanged -> approval outside MCP -> guarded writeback -> replay
+
+Starting disposable Postgres fixture...
+Synapsor Runner demo is ready.
+```
+
+Create the proposal the MCP tool would create:
+
+```bash
+synapsor propose billing.propose_late_fee_waiver --sample
+```
+
+Expected shape:
+
+```text
+Proposal created
+Capability: billing.propose_late_fee_waiver
+Proposal: wrp_...
+Status: review_required
+Source database changed: no
+```
+
+Review and approve outside MCP:
+
+```bash
+synapsor proposals show latest
+synapsor proposals approve latest --yes
+```
+
+Apply through guarded writeback:
+
+```bash
+synapsor apply latest
+```
+
+Expected shape:
+
+```text
+Guarded writeback applied.
+Proposal: wrp_...
+Status: applied
+Rows affected: 1
+Source database mutated: yes
+```
+
+Search by business object:
+
+```bash
+synapsor activity search --object invoice:INV-3001
+```
+
+Expected shape:
+
+```text
+Found local interactions
+
+kind: proposal
+capability: billing.propose_late_fee_waiver
+object: invoice:INV-3001
+proposal: wrp_...
+evidence: ev_...
+status: applied
+replay: replay_wrp_...
+```
+
+Export a copy-pasteable review artifact:
+
+```bash
+synapsor replay export --proposal wrp_... --format markdown --output replay.md
+```
+
+The Markdown includes:
+
+- what the agent requested;
+- trusted tenant/principal context;
+- captured evidence and query audit;
+- exact proposed diff;
+- approval event;
+- guarded writeback receipt;
+- replay note explaining this is local captured interaction replay, not
+  external database time travel.
+
+The full demo should show the happy path before the stale-row conflict path.

package/docs/first-10-minutes.md

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

package/docs/limitations.md

@@ -25,6 +25,8 @@ Synapsor Runner is intentionally narrow in the current alpha.
 - Capability recipes that generate reviewed starter configs.
 - Shadow-mode proposal-vs-human-action comparison.
 - Static MCP database risk review.
+- Local indexed search for proposals, evidence bundles, query audit, writeback
+  receipts, and proposal replay.
 
 ## Runtime Contract
 
@@ -61,6 +63,24 @@ External Postgres/MySQL databases are not branched or merged by Synapsor Runner.
 
 The proposal, evidence, replay, and approval state live in Synapsor Runner locally or in Synapsor Cloud. The external source database changes only when a trusted runner applies an approved writeback job.
 
+Local replay means replay of records captured by the runner:
+
+- trusted context values used by the capability;
+- captured/projected source-row excerpts;
+- query audit fingerprints and redacted parameter metadata;
+- proposal before/proposed diffs;
+- approval/rejection events;
+- guarded writeback jobs;
+- applied/conflict/failed receipts.
+
+It does not mean external Postgres/MySQL time travel. Runner cannot reconstruct
+arbitrary historical rows that were never captured as evidence, and it does not
+provide `AS OF` queries over an external source.
+
+Local search is single-node SQLite search over the local runner store. It is
+useful for local/dev/staging usage. It is not a hosted central evidence ledger,
+not cross-runner aggregation, not RBAC/SSO, and not compliance retention.
+
 Use this wording:
 
 ```text

package/docs/local-mode.md

@@ -23,7 +23,15 @@ Current local-mode foundation:
 
 Still pending:
 
-- Public-release hardening around the experimental `node:sqlite` dependency.
+The alpha package requires Node >= 22.5.0 because the local evidence/replay
+ledger uses Node's `node:sqlite` runtime. The published package declares that
+engine requirement and the CLI exits early with a clear message on older Node
+versions. The Docker-backed demo remains the recommended path when you do not
+want to change your host Node version.
+
+Commands in this page that use local ledger search/export or `synapsor store`
+require this checkout or package version `0.1.0-alpha.4` or newer while npm
+`@alpha` still points to an older alpha.
 
 ## Initialize a config
 
@@ -164,6 +172,9 @@ Show replay:
 
 ```bash
 npx -y -p @synapsor/runner@alpha synapsor replay show wrp_123 --store ./.synapsor/local.db
+npx -y -p @synapsor/runner@alpha synapsor replay show --proposal wrp_123 --store ./.synapsor/local.db
+npx -y -p @synapsor/runner@alpha synapsor replay show --replay replay_wrp_123 --store ./.synapsor/local.db
+npx -y -p @synapsor/runner@alpha synapsor replay show --evidence ev_123 --store ./.synapsor/local.db
 ```
 
 Export replay:
@@ -172,10 +183,62 @@ Export replay:
 npx -y -p @synapsor/runner@alpha synapsor replay export wrp_123 \
   --store ./.synapsor/local.db \
   --output replay.json
+
+npx -y -p @synapsor/runner@alpha synapsor replay export --proposal wrp_123 \
+  --format markdown \
+  --store ./.synapsor/local.db \
+  --output replay.md
 ```
 
 Replay records include proposal metadata, before/after diff, events, writeback receipts, evidence summaries, and query audit rows currently stored for the proposal.
 
+## Local evidence, query audit, and receipts
+
+The local SQLite store is also searchable without relying on `latest`:
+
+```bash
+synapsor activity search \
+  --tenant acme \
+  --object invoice:INV-3001 \
+  --store ./.synapsor/local.db
+
+synapsor evidence list \
+  --tenant acme \
+  --capability billing.inspect_invoice \
+  --source app_postgres \
+  --table invoices \
+  --store ./.synapsor/local.db
+
+synapsor evidence show ev_123 --store ./.synapsor/local.db
+synapsor query-audit list --evidence ev_123 --store ./.synapsor/local.db
+synapsor receipts list --proposal wrp_123 --store ./.synapsor/local.db
+synapsor receipts show <receipt_id> --store ./.synapsor/local.db
+```
+
+Read-only MCP tools record evidence bundles and query-audit rows and return an
+evidence handle. Use `evidence show`, `evidence list`, and `query-audit list`
+to inspect those captured rows and fingerprints later without rerunning the
+external database read.
+
+This is local indexed search over the runner's SQLite ledger. It is not
+external Postgres/MySQL time travel, not native branching, and not a hosted
+cross-runner audit ledger.
+
+## Local store maintenance
+
+The local ledger is a developer/staging SQLite file. You can inspect, compact,
+or prune it without touching your source Postgres/MySQL database:
+
+```bash
+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
+synapsor store prune --store ./.synapsor/local.db --older-than 30d --yes
+```
+
+`store prune` defaults to dry-run. Use `--yes` only after reviewing the row
+counts it will remove.
+
 ## Boundary
 
 Local mode does not expose `approve_proposal` or `commit_proposal` as model-callable MCP tools. The intended flow is:
@@ -184,7 +247,7 @@ Local mode does not expose `approve_proposal` or `commit_proposal` as model-call
 MCP tool call
   -> reviewed semantic proposal
   -> local store
-  -> human/policy approval outside the model
+  -> human/operator approval outside the model
   -> guarded worker writeback
   -> terminal receipt
   -> replay

package/docs/mcp-audit.md

@@ -26,6 +26,10 @@ Built-in database MCP risk example:
 npx -y -p @synapsor/runner@alpha synapsor audit --example dangerous-db-mcp
 ```
 
+Markdown output requires this checkout or package version `0.1.0-alpha.4` or
+newer. Check `npm view @synapsor/runner@alpha version` before promoting npm
+snippets publicly.
+
 This bundled example does not require a source checkout or local examples file.
 It audits a deliberately risky database MCP shape with `execute_sql`,
 `run_query`, model-callable approval/update/delete tools, arbitrary
@@ -41,13 +45,13 @@ Remote `tools/list` endpoint with a bearer token kept in the environment:
 
 ```bash
 SYNAPSOR_MCP_AUDIT_BEARER="..." \
-npx -y -p @synapsor/runner@alpha synapsor audit https://mcp.example.com --json
+npx -y -p @synapsor/runner@alpha synapsor audit https://mcp.example.com --format json
 ```
 
 Remote endpoint with a custom bearer-token environment variable:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor audit https://mcp.example.com --bearer-env MCP_AUDIT_TOKEN --json
+npx -y -p @synapsor/runner@alpha synapsor audit https://mcp.example.com --bearer-env MCP_AUDIT_TOKEN --format json
 ```
 
 Stdio MCP server:
@@ -59,14 +63,20 @@ npx -y -p @synapsor/runner@alpha synapsor audit 'stdio:node ./server.mjs' --time
 JSON output:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor audit ./tools-list.json --json
+npx -y -p @synapsor/runner@alpha synapsor audit ./tools-list.json --format json
+```
+
+Markdown output for issues, PRs, or security review notes:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor audit --example dangerous-db-mcp --format markdown
 ```
 
 During local development, the repo-local wrapper can run the same command:
 
 ```bash
 ./bin/synapsor audit ./tools-list.json
-./bin/synapsor audit ./tools-list.json --json
+./bin/synapsor audit ./tools-list.json --format json
 ```
 
 ## Supported inputs