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

package/docs/capability-config.md

@@ -1,180 +0,0 @@
-# Local capability config
-
-Synapsor Runner uses a strict JSON capability config for local MCP/database safety work.
-
-YAML can be added later, but the first supported format is JSON so the runtime can validate untrusted config without adding a parser dependency.
-
-Capabilities are not hardcoded into the runtime. The MCP server exposes only
-the reviewed `capabilities` listed in `synapsor.runner.json`, or the tool
-catalog returned by Synapsor Cloud in `cloud` mode. The billing examples in
-this document are examples only; use your own namespace, object names, tables,
-columns, patch mappings, and approval roles.
-
-Synapsor Runner does not implement full Synapsor workflows or
-`CREATE AGENT WORKFLOW` in v0.1. It models the local commit-safety loop for
-reviewed read/proposal capabilities.
-
-## Goals
-
-The config defines reviewed semantic capabilities. It must not define arbitrary SQL tools.
-
-The validator rejects:
-
-- raw SQL fields such as `sql`, `raw_sql`, `statement`, or `query_sql`;
-- inline database URLs or connection strings;
-- model-facing args named like `tenant_id`, `principal`, `source_id`, `allowed_columns`, `row_version`, `schema`, `table`, or `column`;
-- missing primary-key target;
-- missing tenant guard unless `target.single_tenant_dev` is explicitly true;
-- proposal capabilities with no `allowed_columns`;
-- proposal capabilities with no fixed patch mapping;
-- proposal capabilities with no conflict guard unless a weak-guard exception is explicitly acknowledged;
-- unknown fields when strict mode is enabled.
-
-## Example
-
-```json
-{
-  "version": 1,
-  "mode": "review",
-  "storage": {
-    "sqlite_path": "./.synapsor/local.db"
-  },
-  "sources": {
-    "app_postgres": {
-      "engine": "postgres",
-      "read_url_env": "APP_POSTGRES_READ_URL",
-      "write_url_env": "APP_POSTGRES_WRITE_URL",
-      "statement_timeout_ms": 3000
-    }
-  },
-  "trusted_context": {
-    "provider": "environment",
-    "values": {
-      "tenant_id_env": "SYNAPSOR_TENANT_ID",
-      "principal_env": "SYNAPSOR_PRINCIPAL"
-    }
-  },
-  "contexts": {
-    "local_billing_operator": {
-      "provider": "environment",
-      "values": {
-        "tenant_id_env": "SYNAPSOR_TENANT_ID",
-        "principal_env": "SYNAPSOR_PRINCIPAL"
-      }
-    }
-  },
-  "executors": {
-    "billing_api": {
-      "type": "http_handler",
-      "url_env": "SYNAPSOR_BILLING_HANDLER_URL",
-      "method": "POST",
-      "auth": {
-        "type": "bearer_env",
-        "token_env": "SYNAPSOR_BILLING_HANDLER_TOKEN"
-      },
-      "timeout_ms": 5000
-    }
-  },
-  "capabilities": [
-    {
-      "name": "billing.inspect_invoice",
-      "kind": "read",
-      "source": "app_postgres",
-      "context": "local_billing_operator",
-      "target": {
-        "schema": "public",
-        "table": "invoices",
-        "primary_key": "id",
-        "tenant_key": "tenant_id"
-      },
-      "args": {
-        "invoice_id": {
-          "type": "string",
-          "required": true,
-          "max_length": 128
-        }
-      },
-      "lookup": {
-        "id_from_arg": "invoice_id"
-      },
-      "visible_columns": ["id", "late_fee_cents", "waiver_reason", "updated_at"],
-      "evidence": "required",
-      "max_rows": 1
-    },
-    {
-      "name": "billing.propose_late_fee_waiver",
-      "kind": "proposal",
-      "source": "app_postgres",
-      "context": "local_billing_operator",
-      "executor": "billing_api",
-      "target": {
-        "schema": "public",
-        "table": "invoices",
-        "primary_key": "id",
-        "tenant_key": "tenant_id"
-      },
-      "args": {
-        "invoice_id": {
-          "type": "string",
-          "required": true,
-          "max_length": 128
-        },
-        "reason": {
-          "type": "string",
-          "required": true,
-          "max_length": 500
-        }
-      },
-      "lookup": {
-        "id_from_arg": "invoice_id"
-      },
-      "visible_columns": ["id", "late_fee_cents", "waiver_reason", "updated_at"],
-      "evidence": "required",
-      "max_rows": 1,
-      "patch": {
-        "late_fee_cents": {
-          "fixed": 0
-        },
-        "waiver_reason": {
-          "from_arg": "reason"
-        }
-      },
-      "allowed_columns": ["late_fee_cents", "waiver_reason"],
-      "conflict_guard": {
-        "column": "updated_at"
-      },
-      "approval": {
-        "mode": "human",
-        "required_role": "support_lead"
-      }
-    }
-  ]
-}
-```
-
-## Trusted context
-
-Supported providers:
-
-- `static_dev`: local/demo only; validator emits a warning.
-- `environment`: reads trusted values from environment variables owned by the launching process.
-- `http_claims`: reserved for authenticated HTTP deployments that verify claims before binding context.
-- `cloud_session`: reserved for Cloud-linked mode with scoped runner/session context.
-
-Model-facing tool arguments cannot override trusted context.
-
-`contexts` is the preferred shape for larger configs. A capability with
-`context: "local_billing_operator"` uses that named context. A capability
-without `context` falls back to the global `trusted_context` for backward
-compatibility. A missing named context fails validation.
-
-## Writeback executors
-
-Proposal capabilities default to `sql_update`, which means the trusted runner
-applies one guarded single-row `UPDATE` after approval. Set
-`executor: "billing_api"` to route approved proposals to a configured
-`http_handler` or `command_handler` instead.
-
-Executor URLs, commands, bearer tokens, and database credentials must be
-environment-variable references. They are never model-facing MCP arguments and
-are redacted from CLI/UI output. See `docs/writeback-executors.md`.

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.