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

package/docs/own-db-20-minutes.md

@@ -1,185 +0,0 @@
-# Own Database In 10 Minutes
-
-This path is for a developer who already understands the local demo and wants
-to try one staging Postgres/MySQL table without writing `synapsor.runner.json`
-by hand.
-
-Do not start with your most sensitive production database. Start with staging,
-a disposable database, or a least-privilege view.
-
-## 1. Create A Read-Only Credential
-
-Use a database user that can inspect metadata and read only the tables/views
-needed for the experiment.
-
-Set the connection string in an environment variable:
-
-```bash
-export DATABASE_URL="<postgres-or-mysql-read-url>"
-```
-
-Do not paste database URLs into MCP client configs or committed JSON files.
-
-## 2. Inspect The Database
-
-Fast path:
-
-```bash
-./scripts/use-your-db.sh
-```
-
-That command runs inspection, guided config generation, and tool preview. The
-rest of this page shows the same steps explicitly.
-
-```bash
-npx -y -p @synapsor/runner@alpha synapsor inspect --from-env DATABASE_URL --engine auto
-```
-
-This prints discovered tables/views, primary keys, possible tenant/scope
-columns, possible conflict/version columns, and fields suggested for review.
-Inspection reads metadata and table shape. It does not expose raw SQL tools or
-write credentials to the model.
-
-For disposable staging databases, this shorter form also works:
-
-```bash
-npx -y -p @synapsor/runner@alpha synapsor inspect "$DATABASE_URL" --engine auto
-```
-
-Prefer `--from-env` on shared machines so URLs do not land in shell history.
-
-## 3. Run The Guided Wizard
-
-```bash
-npx -y -p @synapsor/runner@alpha synapsor init --from-env DATABASE_URL --mode review --wizard
-```
-
-The wizard asks for:
-
-- database engine;
-- read URL environment-variable name;
-- schema/database;
-- table or view;
-- primary key;
-- tenant/scope column;
-- conflict/version column;
-- read-visible fields;
-- mode: `read_only`, `shadow`, or `review`;
-- business object name and namespace;
-- proposal patch mapping if you choose `shadow` or `review`;
-- trusted tenant/principal env vars;
-- approval role;
-- final confirmation before files are written.
-
-The default mode for unknown schemas should be treated as a cautious staging
-path. Do not enable real writeback until the read/proposal path is reviewed.
-
-You can still run the complete wrapper:
-
-```bash
-./scripts/use-your-db.sh
-```
-
-It runs inspection, guided init, tool preview, and next-step printing in one
-flow. For the lower-level CLI path, `synapsor onboard db --from-env
-DATABASE_URL` runs the same own-database onboarding from the runner command.
-
-## 4. What Gets Generated
-
-The wizard creates:
-
-- `synapsor.runner.json`;
-- `.env.example`;
-- `.synapsor/mcp/generic-stdio.json`;
-- `.synapsor/mcp/claude-desktop.json`;
-- `.synapsor/mcp/cursor.json`;
-- `.synapsor/mcp/vscode.json`.
-
-The generated config stores environment-variable names, not database secrets.
-
-## 5. Preview What The Model Sees
-
-```bash
-npx -y -p @synapsor/runner@alpha synapsor config validate --config synapsor.runner.json
-npx -y -p @synapsor/runner@alpha synapsor doctor --config synapsor.runner.json
-npx -y -p @synapsor/runner@alpha synapsor tools preview --config synapsor.runner.json --store ./.synapsor/local.db
-```
-
-`doctor` checks config shape, trusted context env vars, source env vars,
-read/write credential separation, source metadata when reachable, handler env
-vars, and the semantic MCP tool boundary.
-
-`tools preview` lists what the model would see and confirms:
-
-- semantic tools present;
-- `execute_sql` absent;
-- approval tools absent;
-- commit tools absent;
-- database URLs absent;
-- write credentials absent.
-
-## 6. Serve MCP
-
-```bash
-export SYNAPSOR_TENANT_ID="acme"
-export SYNAPSOR_PRINCIPAL="local_operator"
-
-npx -y -p @synapsor/runner@alpha synapsor mcp serve \
-  --config ./synapsor.runner.json \
-  --store ./.synapsor/local.db
-```
-
-The MCP server exposes only the configured semantic tools. It does not expose
-raw SQL, approval tools, commit tools, database URLs, write credentials, or
-model-controlled tenant authority.
-
-## 7. Review Proposals
-
-If a proposal is created:
-
-```bash
-npx -y -p @synapsor/runner@alpha synapsor proposals list --store ./.synapsor/local.db
-npx -y -p @synapsor/runner@alpha synapsor proposals show <proposal_id> --store ./.synapsor/local.db
-npx -y -p @synapsor/runner@alpha synapsor replay show <proposal_id> --store ./.synapsor/local.db
-```
-
-Open the UI:
-
-```bash
-npx -y -p @synapsor/runner@alpha synapsor ui --tour --config ./synapsor.runner.json --store ./.synapsor/local.db
-```
-
-## 8. Apply Only After Review
-
-For direct SQL writeback, set a separate writer credential only when ready:
-
-```bash
-export SYNAPSOR_DATABASE_WRITE_URL="<postgres-or-mysql-writer-url>"
-```
-
-Then:
-
-```bash
-npx -y -p @synapsor/runner@alpha synapsor proposals approve <proposal_id> --store ./.synapsor/local.db --actor local_reviewer --yes
-npx -y -p @synapsor/runner@alpha synapsor proposals writeback-job <proposal_id> --store ./.synapsor/local.db --output job.json
-
-SYNAPSOR_ENGINE=postgres \
-SYNAPSOR_DATABASE_URL="$SYNAPSOR_DATABASE_WRITE_URL" \
-npx -y -p @synapsor/runner@alpha synapsor apply --job job.json --config synapsor.runner.json --store ./.synapsor/local.db
-```
-
-If your application should own the business write, configure an `http_handler`
-or `command_handler` executor instead of direct SQL writeback. See
-[writeback-executors.md](writeback-executors.md).
-
-## Safety Rules
-
-- Never infer write authority silently.
-- Every allowed write column must be explicitly reviewed.
-- Every patch mapping must be explicitly reviewed.
-- If no tenant column exists, use a safe view or explicitly acknowledge
-  single-tenant dev mode.
-- If no conflict column exists, stay in `read_only` or `shadow` unless you
-  intentionally accept a weak guard for local testing.
-- Never write during onboarding.
-- Never put secrets in generated config.

package/docs/production-readiness.md

@@ -1,39 +0,0 @@
-# Production Readiness
-
-Synapsor Runner is a local, open-source MCP data-plane/runtime for reviewed
-Postgres/MySQL business actions. It is not Synapsor Cloud and it is not the
-Synapsor C++ DBMS.
-
-Use a staging or disposable database first.
-
-Allowed current claims:
-
-- semantic MCP tools instead of raw SQL;
-- source database remains unchanged during proposal creation;
-- separate read and write credentials;
-- exact row diff;
-- local approval outside MCP;
-- tenant, column, version, affected-row, and idempotency checks;
-- approved app/API handler writeback with handler secrets kept in environment
-  variables;
-- shadow-mode comparison between agent proposals and human actions;
-- stale-row conflict detection in included fixtures;
-- local replay for proposal/evidence/approval/writeback receipts.
-
-Do not claim from this repository alone:
-
-- high availability;
-- compliance certification;
-- mission-critical SLA;
-- exactly-once across networks;
-- general MCP security;
-- prompt-injection immunity;
-- physical branches for Postgres/MySQL;
-- arbitrary business invariants are automatically understood.
-
-Synapsor Cloud is the production/team control plane for shared approvals, RBAC,
-hosted evidence/replay search, runner fleet status, leases, retention, audit
-visibility, and support.
-
-Before a public production-data claim, complete the release checklist, counsel
-review, security review, and operational validation.

package/docs/protocol.md

@@ -1,90 +0,0 @@
-# Protocol
-
-The public protocol has four versioned identifiers:
-
-```text
-synapsor.change-set.v1
-synapsor.writeback-job.v1
-synapsor.execution-receipt.v1
-synapsor.runner-registration.v1
-```
-
-The schemas live in `schemas/`. Golden fixtures live in `fixtures/protocol/` and are copied into the main Synapsor repository so Cloud/C++/SDK work can validate the same contract.
-
-`fixtures/protocol/MANIFEST.json` is the shared checksum note for the public protocol set. The same logical manifest is copied to the main Synapsor repository as `protocol/MANIFEST.json`. Tests in both repositories verify the SHA-256 digest for every schema and fixture.
-
-The current alpha write path supports one operation:
-
-```text
-single_row_update
-```
-
-It does not support arbitrary SQL, DDL, INSERT, DELETE, UPSERT, stored procedures, dynamic table/column names from model input, or multi-row writes.
-Schema, table, primary-key, tenant, conflict-guard, allowed-column, and patch
-column identifiers must be fixed safe identifiers. Path-traversal strings and
-SQL-fragment-like identifiers are rejected by protocol validation before the
-Postgres/MySQL adapter can run.
-
-## Change set
-
-`synapsor.change-set.v1` describes the proposal created after a semantic capability reads the current row and derives an exact diff. It includes:
-
-- proposal id and version;
-- action name;
-- trusted principal provenance;
-- tenant/business-object scope;
-- source table and primary key;
-- before/patch/after maps;
-- allowed columns;
-- expected version guard;
-- evidence bundle/query fingerprint;
-- approval state;
-- writeback state;
-- `source_database_mutated: false`;
-- proposal hash.
-
-## Writeback job
-
-`synapsor.writeback-job.v1` is the only object a runner may use to mutate the external database. Required fields include:
-
-- `writeback_job_id`;
-- `proposal_id`;
-- `proposal_version`;
-- `proposal_hash`;
-- `runner_scope.project_id`;
-- `runner_scope.source_id`;
-- `engine`;
-- `operation: single_row_update`;
-- `target.schema`;
-- `target.table`;
-- `target.primary_key`;
-- `tenant_guard`;
-- `allowed_columns`;
-- `patch`;
-- `conflict_guard`;
-- `idempotency_key`;
-- `lease`.
-
-The protocol package normalizes this public shape into the existing internal `protocol_version: "1.0"` worker shape so current Postgres/MySQL adapters remain stable while the public contract evolves.
-
-## Execution receipt
-
-`synapsor.execution-receipt.v1` records the terminal result:
-
-```text
-applied
-conflict
-failed
-canceled
-already_applied
-```
-
-Receipts include the writeback job id, proposal id, runner id, rows affected, idempotency key, version fields when available, source mutation state, safe error code, execution timestamp, and receipt hash.
-
-## Runner registration
-
-`synapsor.runner-registration.v1` describes a runner's id, version, supported engines, capabilities, project/source scope, and registration timestamp.
-
-## Compatibility
-
-Existing Cloud endpoints may still return the legacy `protocol_version: "1.0"` job/result envelope during migration. The runner validates both formats. New public examples and MCP work should use the `synapsor.*.v1` schema ids.

package/docs/roadmap.md

@@ -1,13 +0,0 @@
-# Roadmap
-
-Future packages can live in this same monorepo:
-
-- MCP adapter
-- LangGraph adapter
-- OpenAI Agents SDK adapter
-- CrewAI adapter
-- ORM helpers for Prisma, Drizzle, Django, Rails, and SQLAlchemy
-- Local read runner when product requirements and security review are complete
-
-Do not add package stubs until the implementation is ready.
-

package/docs/schema-inspection.md

@@ -1,88 +0,0 @@
-# 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 inspect \
-  --engine auto \
-  --from-env SYNAPSOR_DATABASE_READ_URL \
-  --schema public
-```
-
-JSON output:
-
-```bash
-npx -y -p @synapsor/runner@alpha synapsor 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 init --spec onboarding-selection.json --non-interactive
-```

package/docs/shadow-mode.md

@@ -1,67 +0,0 @@
-# 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 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 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 shadow compare wrp_123 --store ./.synapsor/local.db
-```
-
-Report:
-
-```bash
-npx -y -p @synapsor/runner@alpha synapsor 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

@@ -1,28 +0,0 @@
-# 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

@@ -1,25 +0,0 @@
-# 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/trusted-context.md

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