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

package/docs/cloud-mode.md

@@ -1,140 +0,0 @@
-# Cloud Mode
-
-Cloud mode connects the local Synapsor Runner to Synapsor Cloud without sending database credentials to Cloud.
-
-Command examples use the public `synapsor ...` runner CLI. From a source
-checkout, use `./bin/synapsor ...` if the global binary is not linked yet. Do
-not use the separate hosted Synapsor Cloud CLI for these local runner commands.
-
-```text
-MCP client
-  -> local Synapsor Runner MCP server
-  -> Synapsor Cloud adapter/capability API
-  -> Cloud evidence/proposal/approval/replay
-  -> approved writeback job
-  -> local guarded runner
-  -> Postgres/MySQL
-```
-
-## What Cloud Owns
-
-- Reviewed adapter tool catalog.
-- Capability invocation envelope.
-- Evidence handles.
-- Proposal state.
-- Approval queue.
-- Writeback job leases.
-- Hosted replay and activity search.
-- Runner status, scopes, and receipts.
-
-## What Stays Local
-
-- Postgres/MySQL read and write credentials.
-- Database network access.
-- Guarded writeback transaction.
-- Receipt table in the target database.
-- Local runner process logs and diagnostics.
-
-## Config Shape
-
-Cloud mode uses the same MCP server command with a `mode: "cloud"` config:
-
-```json
-{
-  "version": 1,
-  "mode": "cloud",
-  "storage": {
-    "sqlite_path": "./.synapsor/local.db"
-  },
-  "trusted_context": {
-    "provider": "cloud_session"
-  },
-  "cloud": {
-    "base_url_env": "SYNAPSOR_CLOUD_BASE_URL",
-    "runner_token_env": "SYNAPSOR_RUNNER_TOKEN",
-    "runner_id": "synapsor_runner_local",
-    "runner_version": "0.1.0-alpha.4",
-    "project_id": "token_scope",
-    "adapter_id": "mcp.your_adapter",
-    "source_id": "src_replace_me",
-    "engines": ["postgres"],
-    "capabilities": ["adapter:read", "adapter:invoke", "writeback:claim", "writeback:complete"],
-    "session": {
-      "tenant_id": "acme"
-    }
-  }
-}
-```
-
-Run:
-
-```bash
-SYNAPSOR_CLOUD_BASE_URL="https://api.synapsor.ai" \
-SYNAPSOR_RUNNER_TOKEN="syn_wbr_..." \
-npx -y -p @synapsor/runner@alpha synapsor mcp serve --config ./synapsor.cloud.json
-```
-
-Validate the Cloud runner token and source scope before serving tools:
-
-```bash
-SYNAPSOR_CLOUD_BASE_URL="https://api.synapsor.ai" \
-SYNAPSOR_RUNNER_TOKEN="syn_wbr_..." \
-npx -y -p @synapsor/runner@alpha synapsor cloud connect --config ./synapsor.cloud.json
-```
-
-`cloud connect` verifies the runner token, registers the runner id/version, sends engine/capability/source metadata, and posts an initial heartbeat. It does not send Postgres/MySQL URLs, passwords, write credentials, prompts, or table data. The `project_id` field may be the literal `token_scope` because Synapsor Cloud validates the real project/source from the scoped runner token.
-
-The runner token should be scoped to adapter read/invoke and writeback claim/result reporting for the intended source. It should not grant proposal approval permission.
-
-## Tool Calls
-
-In Cloud mode, the local MCP server fetches the adapter tool catalog from Synapsor Cloud and delegates tool calls to Cloud adapter APIs. The returned result remains structured and must not expose raw SQL or database credentials.
-
-## Hosted Compatibility Check
-
-After you have a compatible Cloud workspace, external source, MCP adapter, and
-scoped runner token, verify the hosted adapter/tool path:
-
-```bash
-SYNAPSOR_CLOUD_BASE_URL="https://synapsor.ai" \
-SYNAPSOR_RUNNER_TOKEN="syn_wbr_..." \
-SYNAPSOR_SOURCE_ID="src_..." \
-SYNAPSOR_ADAPTER_ID="mcp.your_adapter" \
-SYNAPSOR_MCP_TOOL_NAME="your_namespace.propose_your_object_update" \
-SYNAPSOR_MCP_TOOL_INPUT_JSON='{"object_id":"replace-me","reason":"reviewed change"}' \
-corepack pnpm verify:hosted-cloud-linked
-```
-
-That command checks runner-token auth, runner registration, heartbeat, adapter
-`tools/list`, semantic tool invocation, proposal/evidence/replay linkage, and
-that the tool response does not report source mutation before trusted
-writeback. It never creates runner tokens and never prints token values.
-
-To claim and apply one already approved writeback job through the guarded local
-adapter, add:
-
-```bash
-SYNAPSOR_HOSTED_E2E_APPLY_JOB=1
-SYNAPSOR_ENGINE="postgres|mysql"
-SYNAPSOR_DATABASE_URL="postgresql://..."
-```
-
-Use the trusted worker credential in `SYNAPSOR_DATABASE_URL`. Do not put that
-credential in an MCP client config or model-facing tool definition.
-
-## Writeback
-
-The model-facing tool call creates or returns Cloud-managed proposal state. The external database is unchanged until:
-
-1. a human or deterministic Cloud policy approves the exact proposal version/hash;
-2. Cloud creates an approved writeback job;
-3. the scoped runner claims the job;
-4. the local worker applies a guarded single-row update;
-5. the runner returns an applied/conflict/failed receipt.
-
-## Current Limits
-
-- Cloud mode requires a compatible Synapsor Cloud deployment and runner token.
-- Local and Cloud histories are separate unless an explicit import feature is added later.
-- Streamable HTTP transport is not enabled by default; stdio is the primary local MCP transport.
-- Approval remains outside model-callable MCP tools.

package/docs/config-migrations.md

@@ -1,67 +0,0 @@
-# Config Migrations
-
-Synapsor Runner config files are versioned with `version: 1`.
-
-Command examples use the public `synapsor ...` runner CLI. From a source
-checkout, use `./bin/synapsor ...` if the global binary is not linked yet.
-
-Current behavior:
-
-- `synapsor config validate` validates the current schema;
-- `synapsor config show --redacted` prints a secret-safe view;
-- `synapsor config migrate` checks whether the config is already current;
-- `synapsor init --spec onboarding-selection.json --non-interactive` generates
-  a version 1 config from reviewed selections.
-
-The current alpha keeps `version: 1` and adds optional fields without requiring
-a file rewrite:
-
-- `contexts` lets capabilities reference named trusted context bindings;
-- `capabilities[].context` selects one of those named contexts;
-- `executors` and `capabilities[].executor` select `sql_update`,
-  `http_handler`, or `command_handler` writeback execution.
-
-Existing `trusted_context` configs remain valid. If both global
-`trusted_context` and a named capability context exist, the capability-level
-context wins for that capability. Missing context or executor references fail
-validation.
-
-Because version 1 is the only supported schema today, migration is conservative:
-
-```bash
-npx -y -p @synapsor/runner@alpha synapsor config migrate --config synapsor.runner.json
-```
-
-prints that the config is already current and writes nothing.
-
-To write a normalized copy:
-
-```bash
-npx -y -p @synapsor/runner@alpha synapsor config migrate \
-  --config synapsor.runner.json \
-  --output migrated.json \
-  --yes
-```
-
-To rewrite in place, the command requires an explicit write and creates a
-timestamped backup:
-
-```bash
-npx -y -p @synapsor/runner@alpha synapsor config migrate \
-  --config synapsor.runner.json \
-  --write \
-  --yes
-```
-
-The migration command rejects invalid configs and unsupported versions. It does
-not silently reinterpret an old config as broader authority.
-
-Future migrations should follow these rules:
-
-- require an explicit `synapsor config migrate` command;
-- keep secrets out of migrated files;
-- preserve or narrow permissions by default;
-- never widen source, table, tenant, conflict, or mutable-column authority
-  without explicit user confirmation;
-- write a backup before modifying a config;
-- test old-to-new migrations with fixtures.

package/docs/demo-transcript.md

@@ -1,161 +0,0 @@
-# Demo Transcript
-
-This transcript shows the intended public demo path. Exact timestamps, hashes,
-ports, and generated proposal ids vary.
-
-## Quick demo
-
-```bash
-npx -y -p @synapsor/runner@alpha synapsor demo --quick
-```
-
-The local-ledger fixture output below requires this checkout or package version
-`0.1.0-alpha.4` or newer.
-
-Expected shape:
-
-```text
-Synapsor Runner quick demo
-
-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
-
-Raw MCP shape:
-execute_sql(sql: string)
-Risk: the model can write arbitrary SQL with database authority.
-
-Synapsor shape:
-billing.inspect_invoice(invoice_id)
-billing.propose_late_fee_waiver(invoice_id, reason)
-
-Agent requested:
-billing.propose_late_fee_waiver(invoice_id="INV-3001", reason="approved support waiver")
-
-Trusted context:
-tenant_id = acme
-principal = support.agent
-
-Proposal:
-invoice.late_fee_cents: 5500 -> 0
-
-Source DB changed:
-no
-
-Approval:
-required outside MCP
-
-Replay:
-replay_wrp_quick_INV_3001 captures the local proposal, evidence handle, query audit, and events.
-```
-
-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
-```
-
-## Full Docker-backed demo
-
-Start the disposable local Postgres demo:
-
-```bash
-synapsor demo
-```
-
-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/dependency-license-inventory.md

@@ -1,35 +0,0 @@
-# Dependency License Inventory
-
-Generated during the ELv2 migration with:
-
-```bash
-corepack pnpm licenses list --json
-```
-
-Summary from the current lockfile/install:
-
-| License | Package entries |
-| --- | ---: |
-| MIT | 149 |
-| Apache-2.0 | 4 |
-| BSD-3-Clause | 3 |
-| BSD-2-Clause | 1 |
-| ISC | 11 |
-
-Apache-2.0 dependency entries reported by pnpm:
-
-- `denque@2.1.0`
-- `expect-type@1.3.0`
-- `long@5.3.2`
-- `typescript@5.9.3`
-
-This file is an inventory summary, not a replacement for dependency license
-review. Third-party dependency licenses and notices are not changed by the
-first-party Synapsor Runner ELv2 migration.
-
-Before public release:
-
-- regenerate this inventory from a clean install;
-- review dependency notices with counsel or the release owner;
-- keep third-party notices separate from the first-party Synapsor Runner
-  license.

package/docs/first-10-minutes.md

@@ -1,172 +0,0 @@
-# First 10 Minutes
-
-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
-
-- Docker CLI.
-- Reachable Docker daemon.
-- Free local ports: `55433`, `55434`, `55435`, and `53307`.
-- A few GB of free disk for the local demo image and disposable databases.
-
-You do not need:
-
-- Synapsor Cloud account.
-- API key.
-- Hosted workspace.
-- Host Node/Corepack setup for the first command.
-- Database credentials.
-
-## Run One Command
-
-```bash
-./scripts/try-synapsor.sh
-```
-
-The script writes noisy logs to:
-
-```text
-./.synapsor/logs/try-synapsor-<timestamp>.log
-```
-
-If something fails, it prints the failing check and the log path.
-
-## What The Script Proves
-
-The script runs disposable Postgres and MySQL MCP examples and checks that the
-demo actually proves the Synapsor boundary:
-
-- MCP `tools/list` contains semantic tools.
-- MCP `tools/list` does not contain `execute_sql`.
-- The agent inspects one business row through trusted tenant scope.
-- The agent creates a proposal with an exact before/after diff.
-- The source row is unchanged after proposal creation.
-- Approval happens outside the model-facing MCP tool surface.
-- The trusted runner applies a reviewed single-row writeback or blocks a stale
-  row conflict.
-- Replay exists for the proposal, evidence, approval, receipt, and conflict
-  decision.
-- The first-run log does not contain database URLs, passwords, bearer tokens, or
-  write credentials.
-
-## The Mental Model
-
-```text
-MCP client
-  -> semantic business tool
-  -> trusted tenant/principal context
-  -> scoped read from Postgres/MySQL
-  -> evidence and exact proposal diff
-  -> local approval outside MCP
-  -> guarded single-row writeback
-  -> applied/conflict/failed receipt
-  -> local replay
-```
-
-The model gets inspect/propose authority. The trusted runner owns commit
-authority.
-
-## Next Command 1: Open The Local UI
-
-```bash
-npx -y -p @synapsor/runner@alpha synapsor ui --tour \
-  --config ./examples/mcp-postgres-billing/synapsor.runner.json \
-  --store ./.synapsor/local.db
-```
-
-The UI binds to `127.0.0.1`, prints a local URL with a per-run token, and shows
-the proposal/evidence/replay loop. Approval and rejection require CSRF
-protection.
-
-## Next Command 2: Run The Reference App
-
-```bash
-corepack pnpm demo:reference
-```
-
-The reference app uses a disposable support/billing Postgres database and proves:
-
-- semantic MCP tools;
-- source DB unchanged after proposal;
-- approval outside MCP;
-- guarded writeback;
-- stale-row conflict;
-- replay export.
-
-## Next Command 3: Generate MCP Client Config
-
-```bash
-npx -y -p @synapsor/runner@alpha synapsor mcp config claude-desktop \
-  --absolute-paths \
-  --config ./examples/mcp-postgres-billing/synapsor.runner.json \
-  --store ./.synapsor/local.db
-```
-
-Paste the printed JSON into your MCP client settings. The config contains
-command paths only. It must not contain database URLs, passwords, approval
-tools, commit tools, or write credentials.
-
-Verify the configured tool boundary with:
-
-```bash
-npx -y -p @synapsor/runner@alpha synapsor tools preview \
-  --config ./examples/mcp-postgres-billing/synapsor.runner.json \
-  --store ./.synapsor/local.db
-```
-
-## Next Command 4: Use Your Own Staging Database
-
-After the fixture demo makes sense, point the local runtime at one staging
-Postgres/MySQL database:
-
-```bash
-export DATABASE_URL="<postgres-or-mysql-read-url>"
-./scripts/use-your-db.sh
-```
-
-The wrapper inspects metadata, opens the guided config wizard, previews the MCP
-tool boundary, and prints the serve/UI commands. It does not print your
-database URL or write credentials.
-
-## Reset
-
-If a prior run left stale containers, ports, logs, or local stores:
-
-```bash
-./scripts/try-synapsor.sh --reset
-```
-
-For noninteractive cleanup in CI:
-
-```bash
-./scripts/try-synapsor.sh --reset --yes
-```
-
-The reset path removes demo containers, demo volumes, temporary local stores,
-generated MCP snippets under `.synapsor/mcp`, and first-run logs.

package/docs/licensing.md

@@ -1,38 +0,0 @@
-# Licensing
-
-Synapsor Runner is open source under the Apache License 2.0 (`Apache-2.0`).
-
-This page is a plain-English summary, not legal advice. If this summary
-conflicts with `../LICENSE`, the `LICENSE` file controls.
-
-Apache-2.0 applies to the code in this runner repository. It grants copyright
-and patent rights under the license terms.
-
-Apache-2.0 does not grant trademark rights. The Synapsor name, Synapsor Runner
-name, logos, hosted Cloud service, and proprietary Synapsor platform features
-remain separate. See `../TRADEMARKS.md`.
-
-This license change applies only to `synapsor-runner`.
-
-It does not open source:
-
-- Synapsor Cloud;
-- the hosted control plane;
-- hosted capability registry;
-- advanced policy/capability compiler;
-- team approvals, RBAC, or SSO;
-- hosted audit/evidence ledger;
-- managed runners;
-- production writeback orchestration;
-- workflow builder;
-- native Synapsor engine;
-- C++/DBMS internals;
-- branching, time travel, or settlement;
-- compliance exports or production support/SLA.
-
-Synapsor Cloud is a separate hosted commercial service. Use Cloud when your team
-needs shared approvals, RBAC, hosted evidence/replay search, runner fleet
-status, leases, retention, audit visibility, enterprise controls, and support.
-
-Before public release, license and trademark text must be reviewed by qualified
-counsel.