@synapsor/runner 0.1.0 → 0.1.2

package/docs/README.md

@@ -1,74 +1,112 @@
 # Synapsor Runner Docs
 
-Start with the README. Use these docs only when you need the next level of
-detail.
+Start with the README. Use this index when you need the task-specific next
+step. The order is intentional: run something first, wire your database second,
+then read the concepts once the safety boundary is visible.
 
-## First Setup
+## 01 Quickstart
+
+- [README](../README.md): wedge, no-DB quick demo, five-line model, and the
+  shortest own-database path.
+- [Troubleshooting First Run](troubleshooting-first-run.md): common first-run
+  failures, redacted diagnostics, and fixes.
+
+## 02 Why Raw SQL Is Dangerous
+
+- [Security Boundary](security-boundary.md): what the model can and cannot see.
+- [MCP Audit](mcp-audit.md): static review for risky database MCP tools such as
+  `execute_sql`, broad query tools, model-controlled tenant filters, or
+  model-facing approval/commit tools.
+
+## 03 Run The Demo
+
+- `examples/support-billing-agent/`: flagship support/billing agent demo with
+  `make demo`, expected output, and the raw-SQL-vs-Synapsor contrast.
+- `examples/raw-sql-vs-synapsor/`: no-database fear/fix demo.
+- `examples/reference-support-billing-app/`: shared fixture used by the
+  flagship demo and package smoke tests.
+
+## 04 Connect Your DB
 
 - [Connect Your Own Database](getting-started-own-database.md): inspect a
   staging Postgres/MySQL database, generate `synapsor.runner.json`, preview
   semantic tools, and serve them over MCP.
 - [Use Your Own Database](use-your-own-database.md): short entry point that
   links to the canonical own-database guide.
+- [Doctor](doctor.md): redacted setup checks, handler probes, direct SQL
+  writeback probes, and receipt-table guidance.
+
+## 05 Generate Capabilities
+
+- [Capability Authoring](capability-authoring.md): define read/proposal
+  capabilities, model-facing descriptions, result envelopes, trusted context,
+  and writeback guards.
+- [Recipes](recipes.md): starter business-capability templates.
+- [JSON Schema](../schemas/synapsor.runner.schema.json): editor validation for
+  `synapsor.runner.json`.
+
+## 06 Serve MCP
+
 - [MCP Client Setup](mcp-client-setup.md): connect Claude, Cursor, VS Code, or
   another stdio MCP client.
+- `examples/claude-desktop-postgres/`: copy-paste Claude Desktop config for the
+  Postgres billing fixture.
+- `examples/cursor-postgres/`: copy-paste Cursor config for the Postgres
+  billing fixture.
 - [HTTP MCP](http-mcp.md): run Synapsor Runner as an authenticated HTTP MCP
   service for app/server agents.
 - [OpenAI Agents SDK](openai-agents-sdk.md): use Streamable HTTP MCP with
   OpenAI-safe tool aliases.
-- [Capability Authoring](capability-authoring.md): define read/proposal
-  capabilities, model-facing descriptions, result envelopes, trusted context,
-  and writeback guards. JSON Schema:
-  `../schemas/synapsor.runner.schema.json`.
-- [Result Envelope v2](result-envelope-v2.md): the generated-config default
-  `ok`/`summary`/`data`/`proposal`/`error` response shape for MCP tools.
-- [Handler Helper](handler-helper.md): TypeScript helper for safe app-owned
-  rich-write handlers.
-- RFC source context:
-  [001 result envelope](rfcs/001-result-envelope-v2.md),
-  [002 handler helper](rfcs/002-app-owned-handler-helper.md),
-  [003 integrator teardown](rfcs/003-integrator-feedback-teardown.md).
 
-## Safety And Operations
+## 07 Propose, Approve, Apply
 
-- [Security Boundary](security-boundary.md): what the model can and cannot see.
-- [Current Limitations](limitations.md): current alpha scope.
-- [Current Scope](current-scope.md): compact alpha scope summary.
-- [Cloud Mode](cloud-mode.md): what stays local and what Cloud-linked mode adds.
-- [Release Notes](release-notes.md): alpha behavior, breaking changes, and the
-  stable release policy.
-- [Release Policy](release-policy.md): alpha expectations, stable gates,
-  result envelope migration, and publish verification.
-- [Licensing](licensing.md): Apache-2.0 scope, trademark boundary, and what is
-  not included in this runner repo.
-- [Dependency License Inventory](dependency-license-inventory.md): current
-  dependency license summary for release review.
-- [Troubleshooting First Run](troubleshooting-first-run.md): common setup
-  failures and fixes.
-- [Doctor](doctor.md): redacted setup checks, handler probes, direct SQL
-  writeback probes, and receipt-table guidance.
 - [Local Mode](local-mode.md): local store, proposals, approval, replay, and
   writeback flow.
-- [Store Lifecycle](store-lifecycle.md): active-store leases, prune safety,
-  deleted-store behavior, and concurrent server guardrails.
-
-## Features
-
-- [MCP Audit](mcp-audit.md): static risk review for database MCP tools.
-- [Recipes](recipes.md): starter business-capability templates.
 - [Writeback Executors](writeback-executors.md): app-owned writeback handlers
   for approved proposals.
 - [App-Owned Executors](app-owned-executors.md): short entry point for rich
   business transactions handled by your app.
-- `synapsor-runner events tail` and `events webhook`: local lifecycle events
-  such as `proposal_created`, `proposal_approved`, `writeback_applied`, and
-  `writeback_conflict`.
+- [Handler Helper](handler-helper.md): TypeScript helper for safe app-owned
+  rich-write handlers.
 
-Useful examples:
+## 08 Replay And Audit
 
-- `examples/mcp-postgres-billing-app-handler/`: disposable Postgres app showing
-  guarded SQL writeback and app-owned account-credit execution side by side.
+- [Result Envelope v2](result-envelope-v2.md): stable
+  `ok`/`summary`/`data`/`proposal`/`error` MCP tool results.
+- [Store Lifecycle](store-lifecycle.md): active-store leases, prune safety,
+  deleted-store behavior, and concurrent server guardrails.
+- `synapsor-runner activity search`, `evidence`, `query-audit`, `receipts`,
+  `events tail`, and `events webhook`: local evidence, audit, receipt, replay,
+  and lifecycle inspection.
+- `examples/mysql-refund-agent/`: MySQL order/refund review example using the
+  same proposal, approval, guarded writeback, and replay loop.
+
+## 09 App-Owned Handlers
+
+- [Writeback Executors](writeback-executors.md): call direction, endpoint
+  contract, receipt shape, and the requirement to re-check tenant/scope,
+  expected version, idempotency, and allowed action inside your handler.
+- [Handler Helper](handler-helper.md): helper API and examples.
+
+## 10 Concepts
+
+- [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.
+- [Licensing](licensing.md): Apache-2.0 scope, trademark boundary, and what is
+  not included in this runner repo.
+- [Dependency License Inventory](dependency-license-inventory.md): current
+  dependency license summary for release review.
+- RFC source context:
+  [001 result envelope](rfcs/001-result-envelope-v2.md),
+  [002 handler helper](rfcs/002-app-owned-handler-helper.md),
+  [003 integrator teardown](rfcs/003-integrator-feedback-teardown.md).
 
-The public docs intentionally stay small. Historical implementation reports,
-release checklists, and internal planning notes are not part of the public
+The public docs intentionally stay task-first. Historical implementation
+reports, release checklists, and internal planning notes are not part of the
 getting-started path.

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.