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

package/README.md

@@ -15,12 +15,28 @@ npx -y -p @synapsor/runner@alpha synapsor demo --quick
 npx -y -p @synapsor/runner@alpha synapsor audit --example dangerous-db-mcp
 ```
 
+The local-ledger quick fixture, audit `--format markdown`, local evidence
+search, and store maintenance commands are in this checkout and package version
+`0.1.0-alpha.4`. If
+`npm view @synapsor/runner@alpha version` still reports an older alpha, use
+`./bin/synapsor ...` from this checkout or wait for the next alpha publish
+before relying on those npm examples.
+
 `synapsor` is the public command. `synapsor-runner` remains available as a
 backward-compatible alias for earlier alpha commands.
 
-`synapsor demo --quick` is fixture-only and does not require Docker. Use
+`synapsor demo --quick` is fixture-only, does not require Docker, and writes an
+inspectable local ledger fixture to `./.synapsor/quick-demo.db`. Use
 `synapsor demo` for the disposable local Postgres-backed demo.
 
+Inspect the quick 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
+```
+
 Use it with a local or staging database:
 
 ```bash
@@ -31,6 +47,15 @@ synapsor tools preview
 synapsor mcp serve
 ```
 
+The disposable reference app includes proposal-first write examples for:
+
+- `billing.propose_late_fee_waiver`
+- `support.propose_plan_credit`
+- `orders.propose_status_change`
+
+Each tool creates evidence, a before/after diff, and a proposal. The source
+database remains unchanged until approval outside MCP and guarded writeback.
+
 For a longer local session, you can install the alpha package explicitly:
 
 ```bash
@@ -55,6 +80,84 @@ MCP tool call
 Your Postgres/MySQL database remains the source of truth. The runner stores
 local proposals, evidence, receipts, and replay data in a local SQLite store.
 
+## Why Not Just Use A Read-Only Database User?
+
+You should use one.
+
+Synapsor Runner is not a replacement for least-privilege database permissions.
+Start with a read-only user, restricted views, row-level security, and staging
+data where appropriate.
+
+The difference is that database permissions protect the connection. Synapsor
+Runner shapes the model-facing interface.
+
+Instead of exposing `execute_sql`, `query_database`, table names, or
+model-controlled tenant filters, Synapsor exposes reviewed business
+capabilities such as `billing.inspect_invoice` and
+`billing.propose_late_fee_waiver`.
+
+For read-only use cases, Runner provides scoped semantic tools, trusted context
+binding, evidence handles, query audit, and local inspection. Proposal
+workflows add full replay across evidence, approval, writeback receipts, and
+events.
+
+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.
+
+## Find Evidence And Replay
+
+The commands in this section require this checkout or an alpha package that
+includes the local-ledger CLI surface.
+
+The runner stores a local SQLite evidence/replay ledger. Search it without
+relying on `latest`:
+
+```bash
+synapsor activity search --tenant acme --object invoice:INV-3001
+synapsor proposals list --tenant acme --object invoice:INV-3001 --status approved
+synapsor evidence show ev_...
+synapsor query-audit list --evidence ev_...
+synapsor receipts list --proposal wrp_...
+synapsor receipts show <receipt_id>
+synapsor replay show --proposal wrp_...
+synapsor replay show --replay replay_wrp_...
+```
+
+Export captured evidence or proposal replay:
+
+```bash
+synapsor evidence export ev_... --format markdown --output evidence.md
+synapsor replay export --proposal wrp_... --format json --output replay.json
+synapsor replay export --proposal wrp_... --format markdown --output replay.md
+```
+
+Create a redacted local diagnostic report:
+
+```bash
+synapsor doctor --config synapsor.runner.json --report --redact --output synapsor-doctor.md
+```
+
+Inspect or compact the local ledger:
+
+```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
+```
+
+This is local indexed search for local/dev/staging usage. It is not external
+database time travel, not cross-runner search, and not hosted compliance
+retention.
+
+## App-Owned Writeback
+
+Use direct guarded DB writeback for simple local/staging single-row updates. If
+your application service already owns business writes, configure an
+`http_handler` or `command_handler` executor. Approval still happens outside
+MCP, and the handler returns an applied/conflict/failed receipt for replay.
+
 ## Command Name
 
 This package installs `synapsor` as the primary binary and `synapsor-runner` as

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAiBA,OAAO,EAOL,KAAK,gBAAgB,EAEtB,MAAM,mCAAmC,CAAC;AA0H3C,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAqC1D;AA0DD,KAAK,SAAS,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAE9E,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,GAAE;IACP,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,MAAM,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;CACvC,GACL,OAAO,CAAC,MAAM,CAAC,CA0KjB"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AA8BA,OAAO,EAOL,KAAK,gBAAgB,EAEtB,MAAM,mCAAmC,CAAC;AA4H3C,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA8C1D;AA0DD,KAAK,SAAS,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAE9E,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,GAAE;IACP,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,MAAM,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;CACvC,GACL,OAAO,CAAC,MAAM,CAAC,CA0KjB"}

package/dist/cli.js

@@ -6,6 +6,11 @@ import { fileURLToPath } from 'node:url';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const invoked = basename(process.argv[1] || 'synapsor');
 const commandName = invoked === 'synapsor-runner' ? 'synapsor-runner' : 'synapsor';
+const [major, minor] = process.versions.node.split('.').map(Number);
+if (!(major > 22 || (major === 22 && minor >= 5))) {
+  console.error(`Synapsor Runner requires Node >= 22.5.0 because the local ledger uses Node's node:sqlite runtime. Current Node: ${process.versions.node}. Upgrade Node or use the Docker demo from a source checkout.`);
+  process.exit(1);
+}
 const result = spawnSync(process.execPath, ['--no-warnings', join(__dirname, 'runner.mjs'), ...process.argv.slice(2)], {
   stdio: 'inherit',
   env: { ...process.env, NODE_NO_WARNINGS: '1', SYNAPSOR_RUNNER_COMMAND_NAME: commandName },