@synapsor/runner 0.1.0-alpha.1 → 0.1.0-alpha.2

package/docs/schema-inspection.md

@@ -0,0 +1,88 @@
+# Schema Inspection
+
+`synapsor inspect` reads database metadata so you can choose a
+narrow reviewed capability without writing an entire runner config by hand.
+
+Use the public `synapsor ...` runner CLI. From a source checkout, use
+`./bin/synapsor ...` if the global binary is not linked yet.
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner inspect \
+  --engine auto \
+  --from-env SYNAPSOR_DATABASE_READ_URL \
+  --schema public
+```
+
+JSON output:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner inspect \
+  --engine mysql \
+  --from-env SYNAPSOR_DATABASE_READ_URL \
+  --schema app \
+  --json
+```
+
+## What It Reads
+
+The inspector collects metadata only:
+
+- engine and server version;
+- current database user;
+- schemas/databases visible to the credential;
+- tables and views;
+- columns, types, nullability, defaults, and generated status;
+- primary keys;
+- unique constraints;
+- foreign keys;
+- index summaries;
+- best-effort table writability from object type;
+- suggested tenant columns;
+- suggested conflict/version columns;
+- suggested sensitive or large/binary fields.
+
+It does not sample normal business rows by default.
+
+## Suggestions Are Not Authority
+
+Tenant, conflict, sensitive-field, and default-visible-column suggestions are
+heuristics. You must review them before generating or serving a capability.
+
+Suggested tenant column names include:
+
+```text
+tenant_id, account_id, organization_id, org_id, workspace_id, customer_id
+```
+
+Suggested conflict/version columns include:
+
+```text
+updated_at, modified_at, row_version, version, lock_version, etag
+```
+
+Likely sensitive fields include names containing:
+
+```text
+password, secret, token, api_key, private_key, session, cookie, ssn,
+credit_card, card_number, cvv, refresh_token, oauth
+```
+
+Binary/blob/vector columns are excluded from generated default visible columns.
+
+## Safety Behavior
+
+- Use a read-only database credential.
+- Pass the connection through an environment variable name, not a command-line
+  URL.
+- Inspection opens read-only transactions where supported.
+- Inspection applies statement timeouts.
+- Inspection does not issue DDL or DML.
+- Errors are sanitized to avoid printing connection strings.
+
+## Next Step
+
+Use the inspection result to create `onboarding-selection.json`, then run:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner init --spec onboarding-selection.json --non-interactive
+```

package/docs/security-boundary.md

@@ -0,0 +1,70 @@
+# Security Boundary
+
+Synapsor Runner controls a narrow database path for MCP agents. It does not make
+MCP generally secure and it does not solve prompt injection.
+
+The model-facing MCP server exposes reviewed semantic tools such as
+`billing.inspect_invoice` and `billing.propose_late_fee_waiver`.
+
+The model does not receive:
+
+- raw SQL;
+- a generic `execute_sql` tool;
+- arbitrary table, schema, or column names;
+- database URLs or credentials;
+- approval tools;
+- commit/writeback tools;
+- trusted tenant or principal authority as ordinary model arguments.
+
+Trusted context comes from local configuration, environment bindings, or Cloud
+session context in Cloud mode. Tenant, principal, and authorization scope must
+not be accepted from the model as authority.
+
+Proposal tools read the current row through the read credential, store evidence
+and an exact before/after diff, and leave the source database unchanged.
+
+The local proposal store rejects obvious credential material before persistence:
+database URLs, bearer tokens, Synapsor runner tokens, private-key blocks, and
+secret-like fields such as password, token, API key, private key, cookie,
+credential, connection string, read URL, or write URL. If a selected table
+contains one of those fields, remove it from the reviewed visible/evidence
+projection before creating proposals.
+
+Writeback is separate. A trusted local runner/apply path uses a write credential
+outside the model-facing MCP server and verifies:
+
+- local reviewed config;
+- source and capability identity;
+- fixed safe schema, table, and column identifiers;
+- local approval state;
+- proposal and job digests;
+- target schema/table;
+- primary-key and tenant guards;
+- allowed mutable columns;
+- conflict/version guard;
+- idempotency key;
+- job expiry;
+- exactly one affected row.
+
+If any authority check cannot be verified, the write fails closed.
+
+When a capability uses an `http_handler` or `command_handler` executor, the
+same approval boundary applies. The runner sends a structured proposal/job
+payload to the configured handler after approval. Handler URLs, commands, bearer
+tokens, database URLs, and write credentials come from environment variables and
+are not exposed to MCP tools.
+
+Writeback jobs and change sets also reject path-traversal or SQL-fragment-like
+database identifiers such as `../private`, `id/../../tenant_id`, or
+`status; DROP TABLE tickets` before adapter execution. Local CLI file paths
+remain explicit user-provided paths; they are not model-facing authority.
+
+Local review can happen through the CLI or `synapsor ui`. The UI is a localhost
+review surface with a per-run session token and CSRF protection for
+approve/reject actions. It does not expose raw SQL, database URLs, write
+credentials, approval tools, commit tools, or controls that widen reviewed
+tables/columns.
+
+Synapsor Runner supports reviewed single-row business actions only in the
+current alpha. It does not support arbitrary SQL, DDL, `INSERT`, `DELETE`,
+`UPSERT`, or multi-row updates.

package/docs/shadow-mode.md

@@ -0,0 +1,67 @@
+# Shadow Mode
+
+Shadow mode lets you evaluate autonomy before allowing writes.
+
+The model can create proposals and evidence, but the source database is never
+mutated. A human continues doing the real work in the application. You can then
+record what the human actually did and compare it to the agent proposal.
+
+Run a shadow config:
+
+```json
+{
+  "mode": "shadow"
+}
+```
+
+List shadow proposals:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner shadow list --store ./.synapsor/local.db
+```
+
+Record the human action:
+
+```bash
+cat > human-action.json <<'JSON'
+{
+  "late_fee_cents": 0,
+  "waiver_reason": "customer requested review"
+}
+JSON
+
+npx -y -p @synapsor/runner@alpha synapsor-runner shadow record-human-action wrp_123 \
+  --store ./.synapsor/local.db \
+  --patch human-action.json \
+  --actor human_operator \
+  --notes "matched support lead decision"
+```
+
+Compare:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner shadow compare wrp_123 --store ./.synapsor/local.db
+```
+
+Report:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner shadow report --store ./.synapsor/local.db
+```
+
+The report counts:
+
+- total shadow proposals;
+- proposals with human actions;
+- exact matches;
+- partial matches;
+- mismatches;
+- proposals with no human action yet.
+
+Use this path to move gradually:
+
+```text
+read-only -> shadow proposals -> human-reviewed commits -> policy-approved commits later
+```
+
+This goal does not add policy auto-approval.

package/docs/telemetry.md

@@ -0,0 +1,28 @@
+# Telemetry
+
+Local mode does not send telemetry to Synapsor Cloud.
+
+By default, Synapsor Runner local commands do not upload:
+
+- schema metadata;
+- table names;
+- database rows;
+- prompts;
+- proposal contents;
+- credentials or database URLs;
+- usage data.
+
+Cloud communication occurs only after an explicit Cloud action, such as
+`synapsor cloud connect`, or when a config uses `mode: "cloud"`.
+
+The local MCP server keeps database credentials in the local environment. MCP
+client snippets reference the local command and store path; they must not
+include database URLs or passwords.
+
+Cloud mode may exchange documented control-plane metadata for runner
+registration, heartbeats, tool catalogs, proposal/job leases, result reporting,
+and replay/audit workflows. Cloud mode must remain testable and must not upload
+database credentials.
+
+If a future feature adds opt-in telemetry, it must be documented, disabled by
+default for local mode, and must not include secrets or row payloads.

package/docs/threat-model.md

@@ -0,0 +1,25 @@
+# Threat Model
+
+## Boundary
+
+Synapsor Runner is the local trusted writeback boundary. The write credential stays in the customer environment. Synapsor Cloud sends approved structured jobs, not database URLs, passwords, raw SQL, prompts, or model confidence.
+
+## Threats covered
+
+- Compromised or prompt-injected model: runner ignores prompts and accepts only structured approved jobs.
+- Malicious model arguments: target, tenant, allowed columns, conflict guard, and idempotency key come from Synapsor proposal state.
+- Over-broad proposal target: runner requires primary key and tenant guard.
+- Compromised runner token: token is scoped to one source and limited to configured runner permissions such as adapter read/invoke, runner heartbeat, job claim, and result reporting; it does not grant approval or arbitrary SQL authority.
+- Replayed job: receipt table makes applied retries idempotent.
+- Concurrent runners: receipt row and target row are locked inside a transaction.
+- Stale row/version conflict: version-column mismatch returns `conflict`.
+- Tenant mismatch: missing target row under tenant guard returns conflict and does not write.
+- Multi-row impact: affected rows must equal one.
+- Database outage mid-transaction: transaction rolls back and reports failed.
+- Control-plane outage after commit: receipt table allows safe idempotent result retry.
+- Log leakage: default logs redact tokens and database URLs.
+- Dependency compromise: CI, lockfile review, and dependency audit are release gates.
+
+## Limitations
+
+The current alpha does not support arbitrary SQL, inserts, deletes, DDL, stored procedures, multi-row updates, cross-database transactions, automatic schema changes, or a self-hosted Synapsor control plane.

package/docs/troubleshooting-first-run.md

@@ -0,0 +1,248 @@
+# Troubleshooting First Run
+
+Run the friendly doctor first:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner doctor --first-run
+```
+
+Use JSON for automation:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner doctor --first-run --json
+```
+
+## Docker Missing
+
+What happened:
+
+```text
+Docker CLI is missing.
+```
+
+Why it matters:
+
+The first-run demo starts disposable Postgres/MySQL containers.
+
+Fix:
+
+Install Docker Desktop or Docker Engine, then rerun:
+
+```bash
+./scripts/try-synapsor.sh
+```
+
+## Docker Daemon Stopped
+
+What happened:
+
+```text
+Docker daemon is not reachable.
+```
+
+Why it matters:
+
+The demo cannot start disposable databases without the daemon.
+
+Fix:
+
+Start Docker Desktop or the Docker service, then rerun:
+
+```bash
+./scripts/try-synapsor.sh
+```
+
+If the doctor reports Docker socket permission problems, add your user to the
+Docker group or start Docker Desktop.
+
+## Port Conflict
+
+What happened:
+
+```text
+Port 55433 is already in use.
+```
+
+Why it matters:
+
+The fixtures bind predictable local ports.
+
+Fix:
+
+```bash
+./scripts/try-synapsor.sh --reset
+```
+
+If another application owns the port, stop that application and rerun.
+
+## Stale Containers
+
+What happened:
+
+Doctor reports stale Synapsor demo containers.
+
+Why it matters:
+
+Old containers can hold ports or stale fixture state.
+
+Fix:
+
+```bash
+./scripts/try-synapsor.sh --reset
+```
+
+## Missing Source Dependencies
+
+What happened:
+
+```text
+Dependencies are not installed yet.
+```
+
+Why it matters:
+
+Source checkout commands such as `synapsor ...` need workspace
+dependencies.
+
+Fix:
+
+```bash
+corepack enable
+corepack pnpm install
+```
+
+The Docker-only first-run demo does not require host Node dependencies.
+
+## Config Missing
+
+What happened:
+
+```text
+Runner config not found at synapsor.runner.json.
+```
+
+Why it matters:
+
+Own-database MCP setup needs a reviewed config before serving tools.
+
+Fix:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner init --from-env DATABASE_URL --mode review --wizard
+```
+
+Or pass an example config:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner tools preview --config ./examples/mcp-postgres-billing/synapsor.runner.json --store ./.synapsor/local.db
+```
+
+## SQLite Store Missing
+
+What happened:
+
+```text
+SQLite local store not found at ./.synapsor/local.db.
+```
+
+Why it matters:
+
+The local UI and replay read proposal/evidence state from the store.
+
+Fix:
+
+Run a demo or create a proposal first:
+
+```bash
+./scripts/try-synapsor.sh
+```
+
+or:
+
+```bash
+corepack pnpm demo:reference
+```
+
+## DB URL Env Var Missing
+
+What happened:
+
+```text
+SYNAPSOR_DATABASE_READ_URL is not set.
+```
+
+Why it matters:
+
+Configured capabilities need a read credential to inspect/propose against your
+database.
+
+Fix:
+
+```bash
+export SYNAPSOR_DATABASE_READ_URL="<read-only-url>"
+npx -y -p @synapsor/runner@alpha synapsor-runner doctor --config synapsor.runner.json
+```
+
+## Read/Write Credential Split Failed
+
+What happened:
+
+```text
+Read and write env vars resolve to the same credential.
+```
+
+Why it matters:
+
+Read/proposal authority and writeback authority must be separated.
+
+Fix:
+
+Use a read-only credential for MCP reads and a separate writer credential only
+for trusted apply.
+
+## MCP Client Config Contains A Secret
+
+What happened:
+
+Doctor reports a generated MCP client config appears to contain a database URL,
+password, or token.
+
+Why it matters:
+
+MCP clients must receive only the local runner command and args.
+
+Fix:
+
+Regenerate the snippet:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner mcp config claude-desktop \
+  --absolute-paths \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+```
+
+Keep database URLs in environment variables, not client JSON.
+
+## Demo Did Not Prove The Boundary
+
+What happened:
+
+```text
+Demo did not prove the Synapsor boundary.
+```
+
+Why it matters:
+
+The first-run demo must prove semantic tools, proposal creation, source row
+unchanged, approval outside MCP, guarded writeback/conflict, replay, and no
+secret leakage.
+
+Fix:
+
+Inspect the printed log path, then reset:
+
+```bash
+./scripts/try-synapsor.sh --reset
+./scripts/try-synapsor.sh
+```

package/docs/trusted-context.md

@@ -0,0 +1,70 @@
+# Trusted Context
+
+Trusted context is the data Synapsor Runner uses as authority but does not allow
+the model to choose freely.
+
+Examples:
+
+- tenant ID;
+- principal/user ID;
+- role;
+- environment or workspace scope.
+
+In local mode, the supported provider is environment binding:
+
+```json
+{
+  "trusted_context": {
+    "provider": "environment",
+    "values": {
+      "tenant_id_env": "SYNAPSOR_TENANT_ID",
+      "principal_env": "SYNAPSOR_PRINCIPAL"
+    }
+  }
+}
+```
+
+For larger configs, use named contexts so each capability says which trusted
+binding it uses:
+
+```json
+{
+  "contexts": {
+    "local_support_operator": {
+      "provider": "environment",
+      "values": {
+        "tenant_id_env": "SYNAPSOR_TENANT_ID",
+        "principal_env": "SYNAPSOR_PRINCIPAL"
+      }
+    }
+  },
+  "capabilities": [
+    {
+      "name": "support.inspect_ticket",
+      "context": "local_support_operator"
+    }
+  ]
+}
+```
+
+Backward compatibility: `trusted_context` still works as the global fallback.
+If a capability names `context`, that named context is used for that capability.
+If a capability does not name `context`, the global `trusted_context` is used.
+Config validation fails when a capability references a missing named context.
+
+At runtime:
+
+```bash
+export SYNAPSOR_TENANT_ID="acme"
+export SYNAPSOR_PRINCIPAL="local_operator"
+```
+
+The model may pass business identifiers such as `invoice_id` or `ticket_id`.
+Those identifiers are validated inside the trusted tenant scope.
+
+The model must not pass `tenant_id`, principal, role, or authorization scope as
+ordinary authority arguments. If a tool schema appears to require those fields
+from the model, treat it as a bug.
+
+Cloud mode may bind trusted context from Cloud runner/session context, but
+database credentials still stay local.