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

package/docs/config-migrations.md

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

@@ -0,0 +1,73 @@
+# First-Run Demo Transcript
+
+This is the expected high-level transcript for:
+
+```bash
+./scripts/try-synapsor.sh
+```
+
+Exact timings and log paths vary.
+
+```text
+Synapsor Runner first-run demo
+
+You are about to see an MCP agent propose a database change without receiving SQL or write credentials.
+Full logs will be written to: ./.synapsor/logs/try-synapsor-<timestamp>.log
+
+Step 1: MCP tools exposed
+  In this fixture, the model sees semantic tools such as billing.inspect_invoice and billing.propose_late_fee_waiver.
+
+Step 2: Agent inspects business object
+Step 3: Agent proposes change
+Step 4: Source DB changed: No
+Step 5: Human approval outside MCP
+Step 6: Trusted runner applies guarded writeback
+Step 7: Replay explains what happened
+Step 8: Extra safety checks catch stale rows and unsafe tools
+
+Running the disposable Docker proof. This can take a few minutes...
+
+Success. You saw the Synapsor commit boundary.
+
+In the included fixture, the model got:
+* billing.inspect_invoice
+* billing.propose_late_fee_waiver
+
+The model did not get:
+* execute_sql
+* write credentials
+* approve/commit tools
+
+Next:
+
+1. Open proposal UI:
+   npx -y -p @synapsor/runner@alpha synapsor-runner ui --tour --config ./examples/mcp-postgres-billing/synapsor.runner.json --store ./.synapsor/local.db
+
+2. Run the reference app:
+   corepack pnpm demo:reference
+
+3. Generate MCP client config:
+   npx -y -p @synapsor/runner@alpha synapsor-runner mcp config --absolute-paths --config ./examples/mcp-postgres-billing/synapsor.runner.json --store ./.synapsor/local.db
+
+4. Use your own staging Postgres/MySQL:
+   export DATABASE_URL='<postgres-or-mysql-read-url>'
+   npx -y -p @synapsor/runner@alpha synapsor-runner inspect --from-env DATABASE_URL
+   npx -y -p @synapsor/runner@alpha synapsor-runner init --wizard --from-env DATABASE_URL
+```
+
+The full log should include the lower-level proof:
+
+- local MCP Postgres example passed;
+- local MCP MySQL example passed;
+- `ACCEPT semantic tools present`;
+- `ACCEPT execute_sql approval and commit tools absent`;
+- `ACCEPT proposal created successfully`;
+- `ACCEPT source row unchanged after proposal`;
+- `ACCEPT approval happened outside MCP`;
+- `ACCEPT guarded writeback applied`;
+- retry was idempotent;
+- `ACCEPT stale-row conflict detected`;
+- `ACCEPT replay export contains applied receipt`.
+
+The first-run script fails if the log appears to contain database URLs,
+fixture passwords, or bearer tokens.

package/docs/dependency-license-inventory.md

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

@@ -0,0 +1,147 @@
+# First 10 Minutes
+
+This path is for a developer who cloned Synapsor Runner and wants to understand
+the product without reading the full docs first.
+
+## 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-runner 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-runner 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-runner 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/getting-started-own-database.md

@@ -0,0 +1,367 @@
+# Connect Your Own Database
+
+Use this path after the Docker demo passes and you want to try Synapsor Runner
+against a staging or disposable Postgres/MySQL database.
+
+Do not start with your most sensitive production database. The current alpha
+runner is a local commit-safety runtime for reviewed single-row business
+actions, not a production certification.
+
+## Fast path
+
+Set one read-only database URL and run the wrapper from this repo:
+
+```bash
+export DATABASE_URL="<postgres-or-mysql-read-url>"
+./scripts/use-your-db.sh
+```
+
+That command does the useful local mini-Synapsor path:
+
+```text
+inspect your schema
+-> choose one table/view
+-> choose trusted scope and visible fields
+-> optionally choose proposal/writeback rules
+-> generate synapsor.runner.json
+-> preview MCP tools exposed to the model
+-> print mcp serve and local UI commands
+```
+
+It does not print your database URL, put the URL in MCP client config, expose
+`execute_sql`, expose approval/commit tools, or give the model write
+credentials.
+
+The rest of this page shows the same flow step by step using the public
+`synapsor ...` CLI. From a source checkout, use `./bin/synapsor ...` if the
+global binary is not linked yet.
+
+## 1. Put the read URL in an environment variable
+
+Do not pass connection strings on the command line.
+
+```bash
+export DATABASE_URL="<postgres-or-mysql-read-url>"
+```
+
+Use a read-only credential for inspection and model-facing read/proposal tools.
+
+### TLS notes for AWS RDS and other managed databases
+
+If you see an error like:
+
+```text
+self-signed certificate in certificate chain
+```
+
+that is not a Postgres permission issue. It means the client reached the
+database, but your local Node/Postgres TLS stack could not verify the server's
+certificate chain.
+
+For disposable dev RDS fixtures, you can allow an insecure retry:
+
+```bash
+./scripts/use-your-db.sh --allow-insecure-ssl
+```
+
+or put `sslmode=no-verify` in the disposable test URL.
+
+For real staging or production-like testing, do not disable verification.
+Install/use the AWS RDS CA bundle and keep certificate verification enabled.
+For example, download the AWS RDS global bundle and configure your Postgres URL
+or client environment so the Node Postgres client trusts that CA. The exact
+mechanism depends on your deployment environment and should be treated like any
+other trusted database TLS setup.
+
+## 2. Inspect metadata
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner inspect \
+  --engine auto \
+  --from-env DATABASE_URL \
+  --schema public
+```
+
+For a disposable staging URL, this also works:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner inspect "$DATABASE_URL" --engine auto --schema public
+```
+
+For automation:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner inspect \
+  --engine postgres \
+  --from-env DATABASE_URL \
+  --schema public \
+  --json > schema-inspection.json
+```
+
+Inspection reads metadata only by default. It does not sample business rows.
+
+## 3. Start from a recipe when one matches
+
+Recipes give you a reviewed starter contract for a common business action. They
+do not silently infer write authority from your schema; you still map the recipe
+to your staging table, primary key, tenant key, conflict column, visible fields,
+allowed write fields, and business limits.
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner recipes list
+npx -y -p @synapsor/runner@alpha synapsor-runner recipes show billing.late_fee_waiver
+npx -y -p @synapsor/runner@alpha synapsor-runner recipes init billing.late_fee_waiver --output synapsor.runner.json
+```
+
+Use a recipe when the shape is close. Use the guided wizard or explicit flags
+when your action is custom.
+
+Built-in recipes are JSON files under `recipes/`. You can copy one and pass the
+edited file path to `recipes show` or `recipes init`; the runtime still serves
+only the capabilities in your generated `synapsor.runner.json`.
+
+## 4. Generate from reviewed selections
+
+In an interactive terminal, run the guided wizard:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner init --from-env DATABASE_URL --mode read_only --wizard
+```
+
+The generated capabilities are based on your selections. Synapsor Runner does
+not force billing, support, order, or any other built-in domain. You choose the
+namespace, object name, lookup argument, visible fields, proposal fields, guards,
+and approval role.
+
+Start with `read_only` to prove safe database reads first. Use `--mode review`
+when you are ready to create proposal tools and guarded writeback setup.
+
+The wizard:
+
+- asks for the engine and read URL environment-variable name;
+- tests read connectivity through schema inspection;
+- lists discovered schemas and tables/views;
+- asks you to confirm primary key, tenant/scope column, conflict/version
+  column, visible columns, mode, semantic names, trusted context env vars, and
+  proposal patch mappings;
+- previews the MCP tools and what is not exposed;
+- writes the generated config, `.env.example`, and MCP client snippets only
+  after final confirmation.
+
+For proposal modes, the current runner supports explicit field-update mappings such as:
+
+```text
+late_fee_cents=fixed:0,waiver_reason=arg:reason
+```
+
+Use `--starter` only when you intentionally want the old starter skeleton
+instead of the reviewed wizard.
+
+If you already know the reviewed table/action, generate config directly from
+metadata and explicit flags:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner init \
+  --from-env DATABASE_URL \
+  --engine postgres \
+  --schema public \
+  --table invoices \
+  --namespace billing \
+  --object-name invoice \
+  --mode review \
+  --visible-columns id,tenant_id,late_fee_cents,waiver_reason,updated_at \
+  --allowed-columns late_fee_cents,waiver_reason \
+  --patch-fixed late_fee_cents=0 \
+  --patch-from-arg waiver_reason=reason \
+  --numeric-bound late_fee_cents=0:5500 \
+  --write-url-env SYNAPSOR_DATABASE_WRITE_URL
+```
+
+Or generate from a saved inspection snapshot without reconnecting:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner init \
+  --inspection-json schema-inspection.json \
+  --table invoices \
+  --namespace billing \
+  --object-name invoice \
+  --mode review \
+  --patch-fixed late_fee_cents=0 \
+  --patch-from-arg waiver_reason=reason
+```
+
+The command uses inspected metadata for primary-key, tenant-key, conflict-column,
+and default-visible-column suggestions. If a suggestion is ambiguous or missing,
+pass explicit flags such as `--primary-key`, `--tenant-key`, and
+`--conflict-column`.
+
+Review mode requires at least one explicit `--patch-fixed` or
+`--patch-from-arg` mapping. Use `--mode read_only` if you only want an inspect
+tool.
+
+For bounded business actions, add reviewed value guards:
+
+```bash
+--numeric-bound credit_cents=0:10000
+--transition-guard status=open:pending_review
+```
+
+`--numeric-bound` keeps a proposed numeric column inside a fixed range before a
+proposal is created. `--transition-guard` keeps a status-like column on an
+approved state path such as `open -> pending_review`. For multiple states, use
+semicolon-separated paths, for example
+`status=open:pending_review;pending_review:resolved`.
+
+## 5. Or create a reviewed selection spec
+
+Create `onboarding-selection.json` from one table and one safe business action.
+
+```json
+{
+  "version": 1,
+  "engine": "postgres",
+  "mode": "review",
+  "read_url_env": "SYNAPSOR_DATABASE_READ_URL",
+  "write_url_env": "SYNAPSOR_DATABASE_WRITE_URL",
+  "schema": "public",
+  "table": "invoices",
+  "primary_key": "id",
+  "tenant_key": "tenant_id",
+  "conflict_column": "updated_at",
+  "namespace": "billing",
+  "object_name": "invoice",
+  "visible_columns": ["id", "tenant_id", "late_fee_cents", "waiver_reason", "updated_at"],
+  "allowed_columns": ["late_fee_cents", "waiver_reason"],
+  "patch": {
+    "late_fee_cents": { "fixed": 0 },
+    "waiver_reason": { "from_arg": "reason" }
+  },
+  "numeric_bounds": {
+    "late_fee_cents": { "minimum": 0, "maximum": 5500 }
+  }
+}
+```
+
+The selection file contains reviewed metadata selections only. It must not
+contain database URLs or passwords.
+
+## 6. Generate runner files
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner init \
+  --spec onboarding-selection.json \
+  --non-interactive
+```
+
+This creates:
+
+- `synapsor.runner.json`
+- `.env.example`
+- `.synapsor/mcp/generic-stdio.json`
+- `.synapsor/mcp/claude-desktop.json`
+- `.synapsor/mcp/cursor.json`
+- `.synapsor/mcp/vscode.json`
+
+Use `--force` only if you intentionally want to overwrite existing generated
+files.
+
+Generate or refresh MCP client snippets later with:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner mcp config generic --config ./synapsor.runner.json --store ./.synapsor/local.db
+npx -y -p @synapsor/runner@alpha synapsor-runner mcp config claude-desktop --config ./synapsor.runner.json --store ./.synapsor/local.db
+npx -y -p @synapsor/runner@alpha synapsor-runner mcp config cursor --config ./synapsor.runner.json --store ./.synapsor/local.db
+npx -y -p @synapsor/runner@alpha synapsor-runner tools preview --config ./synapsor.runner.json --store ./.synapsor/local.db
+```
+
+The snippets contain the local command and args. They must not contain database
+URLs, passwords, approval tools, commit tools, or write credentials.
+
+## 7. Validate the config
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner config validate --config synapsor.runner.json
+npx -y -p @synapsor/runner@alpha synapsor-runner config show --config synapsor.runner.json --redacted
+```
+
+The config stores environment-variable names, not connection-string values.
+
+Run doctor after setting the referenced environment variables:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner doctor --config synapsor.runner.json
+```
+
+Doctor validates config shape, trusted context env vars, source env vars,
+read/write credential separation, table/column metadata when the read URL is
+available, and the semantic MCP tool boundary. Use JSON for automation:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner doctor --config synapsor.runner.json --json
+```
+
+## 8. Serve semantic MCP tools
+
+```bash
+export SYNAPSOR_TENANT_ID="acme"
+export SYNAPSOR_PRINCIPAL="local_operator"
+npx -y -p @synapsor/runner@alpha synapsor-runner mcp serve --config ./synapsor.runner.json --store ./.synapsor/local.db
+```
+
+The model-facing MCP server exposes semantic tools such as:
+
+```text
+billing.inspect_invoice
+billing.propose_invoice_update
+```
+
+Those names come from the example namespace/object. A custom setup might expose
+`clinic.inspect_appointment` and `clinic.propose_appointment_update`, or any
+other reviewed names you generated. It does not expose `execute_sql`, approval
+tools, commit tools, database URLs, write credentials, or tenant authority.
+
+## 9. Review and apply outside MCP
+
+Proposal tools leave the source database unchanged. Review locally:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner proposals list --store ./.synapsor/local.db
+npx -y -p @synapsor/runner@alpha synapsor-runner proposals show wrp_123 --store ./.synapsor/local.db
+npx -y -p @synapsor/runner@alpha synapsor-runner proposals approve wrp_123 --store ./.synapsor/local.db --actor local_reviewer --yes
+npx -y -p @synapsor/runner@alpha synapsor-runner proposals writeback-job wrp_123 --store ./.synapsor/local.db --output job.json
+```
+
+Apply through the trusted worker path with a separate writer credential:
+
+```bash
+export SYNAPSOR_DATABASE_WRITE_URL="<postgres-or-mysql-write-url>"
+SYNAPSOR_ENGINE=postgres \
+SYNAPSOR_DATABASE_URL="$SYNAPSOR_DATABASE_WRITE_URL" \
+npx -y -p @synapsor/runner@alpha synapsor-runner apply --job job.json --config synapsor.runner.json --store ./.synapsor/local.db
+```
+
+If your application/API should own the business write, use an `http_handler`
+executor instead of direct SQL writeback. Handler URLs and bearer tokens come
+from environment variables, and the handler receives a structured proposal/job
+payload, not arbitrary model SQL:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner apply --proposal wrp_123 --config synapsor.runner.json --store ./.synapsor/local.db
+```
+
+See `docs/writeback-executors.md`.
+
+Replay afterward:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner replay show wrp_123 --store ./.synapsor/local.db
+npx -y -p @synapsor/runner@alpha synapsor-runner replay export wrp_123 --store ./.synapsor/local.db --output replay.json
+```
+
+## Boundary
+
+MCP tool call equals request/proposal authority. Trusted runner equals
+execution authority.
+
+If tenant scope, primary key, allowed columns, expected version, approval state,
+or local config cannot be verified, do not apply the write.