@synapsor/runner 0.1.1 → 0.1.2

package/docs/README.md

@@ -92,6 +92,9 @@ then read the concepts once the safety boundary is visible.
 
 - [Current Scope](current-scope.md): compact v0.1 scope summary.
 - [Current Limitations](limitations.md): intentional safety limits.
+- [Production-Candidate Guide](production.md): single-node OSS deployment
+  scope, database roles, receipt grants, local ledger backup, restart behavior,
+  Docker/systemd shapes, TLS, and release-gate expectations.
 - [Cloud Mode](cloud-mode.md): what stays local and what Cloud-linked mode adds.
 - [Release Notes](release-notes.md): release history and behavior changes.
 - [Release Policy](release-policy.md): stable gates and publish verification.

package/docs/conformance.md

@@ -0,0 +1,91 @@
+# Conformance Fixtures
+
+Conformance fixtures prove behavior, not just JSON shape.
+
+`@synapsor/spec` owns the fixtures under:
+
+```text
+packages/spec/fixtures/conformance/
+```
+
+Each fixture contains:
+
+- `contract.json`: canonical `@synapsor/spec` contract;
+- `scenario.json`: trusted context, invocation, and mocked source data;
+- `expected.*.json`: expected evidence, proposal, receipt, replay, redaction,
+  or external action result.
+
+Current fixture groups:
+
+- `read-capability`
+- `proposal-capability`
+- `kept-out-fields`
+- `manual-approval`
+
+The fixture set is intentionally small in 0.1. It covers the runner-supported
+semantic surface first: trusted context, scoped reads, evidence handles,
+proposal boundaries, kept-out fields, manual approval, and replay envelopes.
+
+## Runner Usage
+
+Runner tests load every conformance `contract.json` and verify that the MCP
+runtime can expose the contract as semantic tools without exposing raw SQL,
+approval, commit, or writeback tools.
+
+Run:
+
+```bash
+corepack pnpm --filter @synapsor-runner/mcp-server test
+```
+
+The spec package also validates every conformance contract:
+
+```bash
+corepack pnpm --filter @synapsor/spec test
+```
+
+## Cloud/C++ Usage
+
+The proprietary Cloud/C++ engine uses the same fixture contracts for
+import/export alignment of the 0.1 overlapping subset:
+
+1. load `contract.json`;
+2. validate the 0.1 core fields and extension policy;
+3. compile the overlapping subset to internal context/capability/workflow
+   models;
+4. emit normalized `@synapsor/spec` JSON;
+5. compare unsupported fields and extension handling explicitly.
+
+The main Synapsor repo also keeps C++ export fixtures under:
+
+```text
+tests/fixtures/synapsor_contract_exports/
+```
+
+Those exported contracts are validated by `@synapsor/spec` and loaded by
+`@synapsor/runner` through the main repo verifier:
+
+```bash
+SYNAPSOR_RUNNER_REPO=/path/to/synapsor-runner \
+  ./scripts/verify_contract_roundtrip.sh
+```
+
+Full runtime parity is not required for every Cloud-only feature in 0.1, but
+unsupported fields must fail clearly or be represented through documented
+`x-cloud-*` extensions.
+
+## Add A Fixture
+
+1. Create a new directory under `packages/spec/fixtures/conformance/<name>/`.
+2. Add a valid `contract.json`.
+3. Add a minimal `scenario.json`.
+4. Add one or more `expected.*.json` files.
+5. Run:
+
+```bash
+corepack pnpm --filter @synapsor/spec test
+corepack pnpm --filter @synapsor-runner/mcp-server test
+```
+
+Keep fixtures deterministic. Do not include secrets, database URLs, live table
+rows, bearer tokens, or customer data.

package/docs/migrating-to-synapsor-spec.md

@@ -0,0 +1,191 @@
+# Migrating To `@synapsor/spec`
+
+`@synapsor/spec` is the canonical Synapsor contract format.
+
+Older Runner configs may still embed capabilities directly inside
+`synapsor.runner.json`. That remains supported. New projects should separate
+the portable business contract from local runtime wiring.
+
+## Old Shape
+
+```json
+{
+  "version": 1,
+  "mode": "review",
+  "storage": { "sqlite_path": "./.synapsor/local.db" },
+  "sources": {
+    "local_postgres": {
+      "engine": "postgres",
+      "read_url_env": "DATABASE_URL"
+    }
+  },
+  "trusted_context": {
+    "provider": "environment",
+    "values": {
+      "tenant_id_env": "SYNAPSOR_TENANT_ID",
+      "principal_env": "SYNAPSOR_PRINCIPAL"
+    }
+  },
+  "capabilities": [
+    {
+      "name": "billing.inspect_invoice",
+      "kind": "read",
+      "source": "local_postgres",
+      "target": {
+        "schema": "public",
+        "table": "invoices",
+        "primary_key": "id",
+        "tenant_key": "tenant_id"
+      },
+      "args": {
+        "invoice_id": { "type": "string", "required": true }
+      },
+      "lookup": { "id_from_arg": "invoice_id" },
+      "visible_columns": ["id", "tenant_id", "status", "late_fee_cents"],
+      "evidence": "required",
+      "max_rows": 1
+    }
+  ]
+}
+```
+
+## New Shape
+
+Put context, resources, capabilities, workflows, evidence requirements,
+proposal boundaries, and kept-out fields in `synapsor.contract.json`.
+
+```json
+{
+  "spec_version": "0.1",
+  "kind": "SynapsorContract",
+  "metadata": {
+    "name": "billing invoice review",
+    "version": "0.1.0"
+  },
+  "resources": [
+    {
+      "name": "billing_invoices",
+      "engine": "postgres",
+      "schema": "public",
+      "table": "invoices",
+      "primary_key": "id",
+      "tenant_key": "tenant_id",
+      "conflict_key": "updated_at"
+    }
+  ],
+  "contexts": [
+    {
+      "name": "local_operator",
+      "tenant_binding": "tenant_id",
+      "principal_binding": "principal",
+      "bindings": [
+        { "name": "tenant_id", "source": "environment", "key": "SYNAPSOR_TENANT_ID", "required": true },
+        { "name": "principal", "source": "environment", "key": "SYNAPSOR_PRINCIPAL", "required": true }
+      ]
+    }
+  ],
+  "capabilities": [
+    {
+      "name": "billing.inspect_invoice",
+      "kind": "read",
+      "context": "local_operator",
+      "source": "local_postgres",
+      "subject": {
+        "resource": "billing_invoices"
+      },
+      "args": {
+        "invoice_id": { "type": "string", "required": true, "max_length": 128 }
+      },
+      "lookup": { "id_from_arg": "invoice_id" },
+      "visible_fields": ["id", "tenant_id", "status", "late_fee_cents", "updated_at"],
+      "kept_out_fields": ["internal_notes"],
+      "evidence": { "required": true, "query_audit": true },
+      "max_rows": 1
+    }
+  ]
+}
+```
+
+Then keep only local wiring in `synapsor.runner.json`.
+
+```json
+{
+  "version": 1,
+  "mode": "read_only",
+  "result_format": 2,
+  "storage": {
+    "sqlite_path": "./.synapsor/local.db"
+  },
+  "contracts": ["./synapsor.contract.json"],
+  "sources": {
+    "local_postgres": {
+      "engine": "postgres",
+      "read_url_env": "DATABASE_URL",
+      "statement_timeout_ms": 3000
+    }
+  }
+}
+```
+
+## Validate
+
+```bash
+synapsor-runner contract validate ./synapsor.contract.json
+synapsor-runner contract normalize ./synapsor.contract.json --out ./synapsor.contract.normalized.json
+synapsor-runner tools preview --config ./synapsor.runner.json --store ./.synapsor/local.db
+```
+
+You can also compile from the SQL-like authoring layer:
+
+```bash
+synapsor-runner dsl validate ./contract.synapsor
+synapsor-runner dsl compile ./contract.synapsor --out ./synapsor.contract.json
+```
+
+## Bundle For Local Runner
+
+Cloud/exported or hand-written contracts can become a local Runner bundle:
+
+```bash
+synapsor-runner contract bundle ./synapsor.contract.json --out ./synapsor-runner-bundle
+```
+
+The bundle includes:
+
+- `synapsor.contract.json`
+- `synapsor.runner.json`
+- `.env.example`
+- `README.md`
+- `mcp-client-examples/generic-stdio.json`
+
+It does not include database passwords, write credentials, bearer tokens,
+customer rows, or table data.
+
+## Common Errors
+
+`UNKNOWN_FIELD`
+
+The contract has a field outside the 0.1 core schema. Use explicit extension
+fields such as `x-cloud-*`, `x-runner-*`, or `x-experimental-*`.
+
+`MODEL_CONTROLLED_TRUST_SCOPE`
+
+A capability argument tries to accept trusted scope from the model, such as
+`tenant_id`, `principal`, table names, column names, or `expected_version`.
+Bind those values from trusted context instead.
+
+`KEPT_OUT_VISIBLE_CONFLICT`
+
+A field appears in both `visible_fields` and `kept_out_fields`. Remove it from
+`visible_fields`. Kept-out fields must not reach evidence, proposals, or replay.
+
+`PROPOSAL_CONFLICT_GUARD_REQUIRED`
+
+A proposal capability needs a conflict guard, or an explicit weak-guard
+acknowledgement for a known dev-only path.
+
+## Compatibility
+
+Embedded Runner capabilities are still supported for existing users. The new
+contract split is the forward path because it lets OSS Runner, Cloud, C++ import
+tests, and the DSL compiler all validate the same canonical shape.

package/docs/production.md

@@ -0,0 +1,289 @@
+# Production-Candidate Guide
+
+Synapsor Runner is not self-hosted Synapsor Cloud. This guide is for the
+narrow OSS production-candidate shape:
+
+```text
+MCP agent
+-> reviewed semantic capability
+-> trusted tenant/principal context
+-> scoped Postgres/MySQL read
+-> evidence/query audit/proposal
+-> approval outside MCP
+-> guarded one-row update or app-owned executor
+-> receipt/replay
+```
+
+Use this only for bounded database workflows where you can accept a single-node
+local ledger and local/operator approval. Use Synapsor Cloud when you need HA,
+central audit, RBAC/SSO, multi-reviewer approvals, hosted retention, managed
+runners, policy packs, or production support/SLA.
+
+## Supported Scope
+
+Production-candidate OSS scope:
+
+- Postgres/MySQL reads through fixed semantic MCP tools;
+- trusted context from environment/session values, not model arguments;
+- local SQLite ledger for evidence, query audit, proposals, receipts, replay,
+  and lifecycle events;
+- direct guarded single-row `UPDATE` for simple approved edits;
+- app-owned `http_handler` or `command_handler` executors for richer approved
+  business transactions;
+- stdio MCP and Streamable HTTP MCP.
+
+Out of scope:
+
+- raw `execute_sql` or model-generated SQL;
+- generic direct `INSERT`, `DELETE`, `UPSERT`, DDL, or multi-row SQL writeback;
+- physical branching of external Postgres/MySQL;
+- workflow DAGs, auto-merge/settlement, RBAC/SSO, HA ledger, or compliance
+  retention;
+- making prompt injection impossible.
+
+## Database Roles
+
+Use separate read and write credentials.
+
+Read credential:
+
+- can connect to the selected database;
+- can inspect metadata for selected schemas;
+- can `SELECT` only the tables/views used by capabilities;
+- should be restricted by views/RLS where possible.
+
+Write credential for direct `sql_update`:
+
+- can update only the allowed business columns;
+- cannot modify primary-key or tenant columns;
+- can create/write the `synapsor_writeback_receipts` table, or the table is
+  pre-created and granted by an administrator;
+- is never exposed to MCP clients.
+
+Example config:
+
+```json
+{
+  "sources": {
+    "billing_postgres": {
+      "engine": "postgres",
+      "read_url_env": "SYNAPSOR_DATABASE_READ_URL",
+      "write_url_env": "SYNAPSOR_DATABASE_WRITE_URL"
+    }
+  }
+}
+```
+
+`synapsor-runner apply --config ...` reads the writer env var named by
+`write_url_env`. `SYNAPSOR_DATABASE_URL` is only a legacy fallback for direct
+worker flows that do not pass a local config.
+
+## Receipt Table
+
+Direct SQL writeback stores idempotency receipts in the source database. Runner
+creates this table if allowed:
+
+```sql
+CREATE TABLE IF NOT EXISTS synapsor_writeback_receipts (...);
+```
+
+Before using direct writeback in staging or production-like environments:
+
+```bash
+synapsor-runner writeback migration --engine postgres
+synapsor-runner writeback grants --engine postgres --writer-role app_writer
+synapsor-runner doctor --config synapsor.runner.json --check-writeback
+```
+
+For MySQL, replace `postgres` with `mysql`.
+
+If the writer should not create application-schema tables, pre-create the
+receipt table with an administrator role, grant only the needed receipt-table
+permissions to the writer, or use an app-owned executor that stores receipts in
+your application boundary.
+
+## Direct Writeback Vs App-Owned Executor
+
+Use direct `sql_update` when the approved change is:
+
+```text
+one existing row -> one allowed-column patch -> one guarded UPDATE
+```
+
+Use an app-owned executor when the change is richer:
+
+- insert a credit/refund/review row;
+- update more than one row;
+- touch more than one table;
+- emit an event or call another internal service;
+- enforce business logic that belongs in your app.
+
+Handlers must re-check tenant/scope, expected version, idempotency, allowed
+business action, transaction boundaries, and safe errors. See
+[Writeback Executors](writeback-executors.md) and
+[Handler Helper](handler-helper.md).
+
+## Local Ledger
+
+Default local ledger path:
+
+```text
+./.synapsor/local.db
+```
+
+This SQLite file stores local evidence, query audit, proposals, approvals,
+receipts, replay, and events. Back it up like local operational state if you
+depend on replay after restarts.
+
+Recommended single-node practices:
+
+- keep the ledger on persistent disk;
+- back up `local.db`, `local.db-wal`, and `local.db-shm` together when the
+  server is stopped, or use your platform's filesystem snapshot mechanism;
+- do not run multiple active MCP server modes against the same ledger unless
+  you intentionally pass `--allow-concurrent-store` for local debugging;
+- use `store prune --dry-run` before retention cleanup;
+- use `store vacuum` during a planned maintenance window.
+
+Useful commands:
+
+```bash
+synapsor-runner store stats --store ./.synapsor/local.db
+synapsor-runner events tail --store ./.synapsor/local.db --follow
+synapsor-runner store prune --store ./.synapsor/local.db --older-than 30d --dry-run
+synapsor-runner store vacuum --store ./.synapsor/local.db
+```
+
+Details: [Store Lifecycle](store-lifecycle.md).
+
+## Restart And Recovery
+
+Runner stores proposal/evidence/replay state before writeback.
+
+Expected restart behavior:
+
+- after proposal creation: proposal, evidence, query audit, and replay remain
+  inspectable from the local ledger;
+- after approval but before apply: rerun `apply`; the approved proposal remains
+  pending until a terminal receipt is recorded;
+- after apply succeeds: retry returns an idempotent receipt, not a second write;
+- after stale row or tenant mismatch: retry returns the recorded conflict path.
+
+Inspection commands:
+
+```bash
+synapsor-runner proposals show latest --store ./.synapsor/local.db
+synapsor-runner receipts list --proposal wrp_... --store ./.synapsor/local.db
+synapsor-runner replay show latest --store ./.synapsor/local.db
+synapsor-runner activity search --proposal wrp_... --store ./.synapsor/local.db
+```
+
+## Deployment Recipes
+
+### Docker Compose Shape
+
+Use Compose to run the MCP server next to your app and database network. Keep
+secrets in environment variables or your platform secret manager.
+
+```yaml
+services:
+  synapsor-runner:
+    image: node:22-bookworm
+    working_dir: /app
+    command: >
+      sh -lc "npm install -g @synapsor/runner &&
+      synapsor-runner up --review --config /config/synapsor.runner.json
+      --store /data/local.db --host 0.0.0.0 --port 8766"
+    environment:
+      SYNAPSOR_DATABASE_READ_URL: ${SYNAPSOR_DATABASE_READ_URL}
+      SYNAPSOR_DATABASE_WRITE_URL: ${SYNAPSOR_DATABASE_WRITE_URL}
+      SYNAPSOR_TENANT_ID: ${SYNAPSOR_TENANT_ID}
+      SYNAPSOR_PRINCIPAL: ${SYNAPSOR_PRINCIPAL}
+    volumes:
+      - ./synapsor.runner.json:/config/synapsor.runner.json:ro
+      - synapsor-runner-data:/data
+    ports:
+      - "8766:8766"
+
+volumes:
+  synapsor-runner-data:
+```
+
+### systemd Shape
+
+```ini
+[Unit]
+Description=Synapsor Runner MCP server
+After=network-online.target
+
+[Service]
+Type=simple
+User=synapsor-runner
+WorkingDirectory=/opt/synapsor-runner
+EnvironmentFile=/etc/synapsor-runner.env
+ExecStart=/usr/bin/synapsor-runner up --review --config /etc/synapsor.runner.json --store /var/lib/synapsor-runner/local.db --host 127.0.0.1 --port 8766
+Restart=on-failure
+RestartSec=5
+NoNewPrivileges=true
+PrivateTmp=true
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Put database credentials in `/etc/synapsor-runner.env` or your system secret
+manager, not in `synapsor.runner.json`.
+
+## TLS And SSL
+
+For staging or production-like databases:
+
+- keep certificate verification enabled;
+- use provider CA bundles when required;
+- do not use `sslmode=disable` except disposable local fixtures;
+- do not document or paste real DB URLs into logs, tickets, prompts, or MCP
+  client config.
+
+For disposable local Docker fixtures, `sslmode=disable` is acceptable when the
+database is bound to loopback and contains only test data.
+
+## Health And Doctor
+
+Run these before exposing tools to an agent:
+
+```bash
+synapsor-runner config validate --config synapsor.runner.json
+synapsor-runner doctor --config synapsor.runner.json --report --redact --output synapsor-doctor.md
+synapsor-runner doctor --config synapsor.runner.json --check-writeback
+synapsor-runner tools preview --config synapsor.runner.json --store ./.synapsor/local.db
+```
+
+Doctor reports should be redacted by default before sharing. They must not
+include database passwords, bearer tokens, handler secrets, or raw driver
+connection strings.
+
+## Logging And Redaction
+
+Expected public outputs must avoid secrets in:
+
+- demo output;
+- doctor reports;
+- evidence exports;
+- query-audit output;
+- replay exports;
+- thrown errors and logs.
+
+If you find a leak, treat it as a security bug. See [SECURITY.md](../SECURITY.md).
+
+## Release Gate
+
+Before promoting a package or calling a build production-candidate:
+
+```bash
+./scripts/verify-release-gate.sh
+```
+
+The release gate should cover typecheck, focused tests, packed-package install,
+quick demo, own-db fixture, MCP stdio/HTTP checks, direct writeback,
+app-owned executor paths, package dry-run, and docs/package consistency.
+

package/docs/release-notes.md

@@ -10,6 +10,17 @@ npx -y -p @synapsor/runner synapsor-runner demo --quick
 The OSS runner command is `synapsor-runner`. The `synapsor` command is reserved
 for the Synapsor Cloud CLI.
 
+## 0.1.2
+
+### Contract Compatibility
+
+- Documents the canonical `synapsor.contract.json` path for contracts produced
+  by the DSL, Cloud, or the C++ exporter.
+- Adds OSS-side conformance notes for C++/Cloud export snapshots that validate
+  with `@synapsor/spec` and load in Runner.
+- Keeps `@synapsor/runner` publishable after `0.1.1` by reserving the next
+  stable patch version for this contract round-trip readiness pass.
+
 ## 0.1.1
 
 ### OSS Launch Readiness

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synapsor/runner",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Stop giving AI agents execute_sql; expose reviewed Postgres/MySQL MCP actions with proposals, approval, writeback, and replay.",
   "license": "Apache-2.0",
   "type": "module",
@@ -52,11 +52,6 @@
   "engines": {
     "node": ">=22.5.0"
   },
-  "scripts": {
-    "build": "tsc -b && node ../../scripts/build-runner-package.mjs",
-    "prepack": "cd ../.. && corepack pnpm build:runner-package",
-    "test": "vitest run"
-  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.29.0",
     "mysql2": "^3.11.0",
@@ -77,5 +72,9 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b && node ../../scripts/build-runner-package.mjs",
+    "test": "vitest run"
   }
-}
+}