@synapsor/runner 0.1.0-alpha.11 → 0.1.0-alpha.14

package/docs/README.md

@@ -16,6 +16,18 @@ detail.
   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 opt-in
+  `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
 
@@ -25,14 +37,20 @@ detail.
 - [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
 
@@ -42,6 +60,9 @@ detail.
   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`: local lifecycle events such as
+  `proposal_created`, `proposal_approved`, `writeback_applied`, and
+  `writeback_conflict`.
 
 Useful examples:
 

package/docs/app-owned-executors.md

@@ -19,3 +19,8 @@ the receipt, and includes the result in replay.
 
 Do not use generic SQL for rich business transactions. Let the model propose,
 let Synapsor Runner approve/replay, and let your app execute the transaction.
+
+For TypeScript services, prefer the first-party helper in `packages/handler`.
+It enforces bearer/HMAC auth, tenant scope, expected-version guards,
+idempotency, transaction rollback, and safe receipt formatting around your
+business effect. See [Handler Helper](handler-helper.md).

package/docs/capability-authoring.md

@@ -0,0 +1,265 @@
+# Capability Authoring
+
+Use `synapsor.runner.json` to define the database actions an MCP client can see.
+The model sees semantic capabilities such as `billing.inspect_invoice`, not raw
+SQL, table names, write credentials, approval tools, or commit tools.
+
+For editor validation, use the JSON Schema:
+
+```text
+schemas/synapsor.runner.schema.json
+```
+
+## Minimal Shape
+
+```json
+{
+  "version": 1,
+  "mode": "review",
+  "result_format": 2,
+  "storage": { "sqlite_path": "./.synapsor/local.db" },
+  "sources": {
+    "app_postgres": {
+      "engine": "postgres",
+      "read_url_env": "DATABASE_URL",
+      "write_url_env": "SYNAPSOR_DATABASE_WRITE_URL",
+      "statement_timeout_ms": 3000
+    }
+  },
+  "trusted_context": {
+    "provider": "environment",
+    "values": {
+      "tenant_id_env": "SYNAPSOR_TENANT_ID",
+      "principal_env": "SYNAPSOR_PRINCIPAL"
+    }
+  },
+  "capabilities": []
+}
+```
+
+`result_format: 2` makes every MCP tool call return one envelope:
+
+```json
+{
+  "ok": true,
+  "summary": "Created proposal wrp_123. Source database changed: no.",
+  "action": "billing.propose_late_fee_waiver",
+  "kind": "proposal",
+  "data": null,
+  "proposal": {},
+  "error": null,
+  "evidence": {
+    "bundle_id": "ev_123",
+    "note": "audit/replay handle; you do not need to act on it during this turn"
+  },
+  "source_database_changed": false,
+  "_meta": {
+    "canonical_capability": "billing.propose_late_fee_waiver"
+  }
+}
+```
+
+Use `--result-format v2` on `mcp serve` or `mcp serve-streamable-http` if you
+want to opt in from the command line instead of config.
+
+## Read Capability
+
+Read capabilities inspect one scoped row or view and save evidence/query-audit
+records locally.
+
+```json
+{
+  "name": "billing.inspect_invoice",
+  "kind": "read",
+  "description": "Inspect one invoice in the trusted tenant before proposing a waiver or credit.",
+  "returns_hint": "Returns invoice amount, late fee, status, policy facts, and an audit evidence handle.",
+  "source": "app_postgres",
+  "target": {
+    "schema": "public",
+    "table": "invoices",
+    "primary_key": "id",
+    "tenant_key": "tenant_id"
+  },
+  "args": {
+    "invoice_id": {
+      "type": "string",
+      "required": true,
+      "max_length": 128,
+      "description": "Invoice id, e.g. INV-3001."
+    }
+  },
+  "lookup": { "id_from_arg": "invoice_id" },
+  "visible_columns": ["id", "tenant_id", "status", "late_fee_cents", "updated_at"],
+  "evidence": "required",
+  "max_rows": 1
+}
+```
+
+Model-facing descriptions matter. They should explain when to use the tool and
+what the result contains. Runner also adds evidence-handle guidance so the model
+does not waste a turn trying to call an audit handle.
+
+## Proposal Capability
+
+Proposal capabilities create an exact before/after diff. They do not mutate your
+source database. Approval and writeback stay outside the model-facing MCP tool
+surface.
+
+```json
+{
+  "name": "billing.propose_late_fee_waiver",
+  "kind": "proposal",
+  "description": "Propose waiving one invoice late fee after inspecting invoice and policy evidence.",
+  "returns_hint": "Returns a review-required proposal id, exact field diff, evidence handle, and source_database_changed:false.",
+  "source": "app_postgres",
+  "target": {
+    "schema": "public",
+    "table": "invoices",
+    "primary_key": "id",
+    "tenant_key": "tenant_id"
+  },
+  "args": {
+    "invoice_id": {
+      "type": "string",
+      "required": true,
+      "description": "Invoice id, e.g. INV-3001."
+    },
+    "reason": {
+      "type": "string",
+      "required": true,
+      "max_length": 500,
+      "description": "Business reason for the proposed waiver."
+    }
+  },
+  "lookup": { "id_from_arg": "invoice_id" },
+  "visible_columns": ["id", "tenant_id", "status", "late_fee_cents", "waiver_reason", "updated_at"],
+  "patch": {
+    "late_fee_cents": { "fixed": 0 },
+    "waiver_reason": { "from_arg": "reason" }
+  },
+  "allowed_columns": ["late_fee_cents", "waiver_reason"],
+  "numeric_bounds": {
+    "late_fee_cents": { "minimum": 0, "maximum": 10000 }
+  },
+  "conflict_guard": { "column": "updated_at" },
+  "approval": { "mode": "human", "required_role": "billing_lead" }
+}
+```
+
+## Trusted Context
+
+Tenant, principal, approval authority, source ids, and row-version authority
+must come from trusted backend/session context, not from model arguments.
+
+Good:
+
+```json
+"trusted_context": {
+  "provider": "environment",
+  "values": {
+    "tenant_id_env": "SYNAPSOR_TENANT_ID",
+    "principal_env": "SYNAPSOR_PRINCIPAL"
+  }
+}
+```
+
+Bad:
+
+```json
+"args": {
+  "tenant_id": { "type": "string" }
+}
+```
+
+Runner rejects model-facing trust-scope arguments.
+
+## Direct SQL Writeback
+
+Use direct SQL writeback only for simple bounded single-row `UPDATE` proposals.
+Runner validates:
+
+- fixed table and column names;
+- primary-key targeting;
+- tenant guard;
+- `allowed_columns`;
+- numeric bounds and transition guards;
+- optimistic conflict guard such as `updated_at`;
+- one affected row;
+- idempotency receipt.
+
+Runner does not expose generic SQL, model-generated SQL, DDL, INSERT, DELETE,
+UPSERT, or multi-row writes.
+
+Direct SQL writeback uses the source `write_url_env`, such as
+`SYNAPSOR_DATABASE_WRITE_URL`. The writer needs permission for
+`synapsor_writeback_receipts` or an administrator must pre-create and grant that
+table.
+
+## App-Owned Executors
+
+Use an app-owned executor when an approved proposal needs richer business work:
+creating a credit row, inserting an outbox event, updating multiple app tables,
+or calling your own service.
+
+```json
+"executors": {
+  "billing_handler": {
+    "type": "http_handler",
+    "url_env": "BILLING_WRITEBACK_URL",
+    "method": "POST",
+    "auth": {
+      "type": "bearer_env",
+      "token_env": "BILLING_WRITEBACK_TOKEN"
+    },
+    "signing_secret_env": "BILLING_WRITEBACK_SIGNING_SECRET",
+    "timeout_ms": 5000
+  }
+}
+```
+
+Then reference it from a proposal capability:
+
+```json
+{
+  "name": "billing.propose_account_credit",
+  "kind": "proposal",
+  "executor": "billing_handler"
+}
+```
+
+Approval still happens outside MCP. Runner sends the approved job to your
+handler, and the handler returns an applied/conflict/failed receipt for replay.
+See [App-Owned Executors](app-owned-executors.md) and
+[Writeback Executors](writeback-executors.md).
+
+## OpenAI Aliases
+
+Canonical Synapsor names use dots, such as `billing.inspect_invoice`. Some
+clients require function-safe names. Use:
+
+```bash
+synapsor-runner mcp serve-streamable-http \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN \
+  --alias-mode openai
+```
+
+The model sees aliases such as `billing__inspect_invoice`. Runner includes the
+canonical name in tool metadata and descriptions so audit/replay still use the
+real capability name.
+
+## Why Not `execute_sql`
+
+`execute_sql(sql)` gives the model database authority. Synapsor Runner gives the
+model proposal authority:
+
+```text
+model-facing MCP tool -> trusted context -> scoped read -> evidence -> proposal
+```
+
+Commit authority stays outside the model:
+
+```text
+human/operator approval -> guarded writeback or app-owned handler -> receipt/replay
+```

package/docs/doctor.md

@@ -0,0 +1,98 @@
+# Doctor
+
+Use `doctor` to check a local Runner setup without printing database URLs,
+passwords, bearer tokens, signing secrets, or private keys.
+
+```bash
+synapsor-runner doctor --config synapsor.runner.json
+synapsor-runner doctor --config synapsor.runner.json --json
+synapsor-runner doctor --config synapsor.runner.json --report --redact --output synapsor-doctor.md
+```
+
+The default check validates:
+
+- config shape;
+- trusted context environment variables;
+- read credential environment variables;
+- read/write credential separation;
+- reachable source metadata when the read env var is set;
+- configured target tables and columns;
+- MCP tool boundary, including absence of raw SQL and commit tools;
+- local store stats.
+
+## App-Owned Handler Checks
+
+For `http_handler` executors, add `--check-handlers`:
+
+```bash
+synapsor-runner doctor --config synapsor.runner.json --check-handlers
+```
+
+This checks handler URL/token/signing-secret env vars and sends a reachability
+probe to the handler endpoint. It does not apply a proposal and does not send a
+writeback job.
+
+Use `signing_secret_env` for non-loopback handler deployments so Runner signs
+requests with:
+
+```text
+X-Synapsor-Signature
+X-Synapsor-Issued-At
+X-Synapsor-Proposal-Id
+Idempotency-Key
+```
+
+## Direct SQL Writeback Checks
+
+For direct `sql_update` writeback, add `--check-writeback` only after reviewing
+the receipt-table DDL/grants:
+
+```bash
+synapsor-runner doctor --config synapsor.runner.json --check-writeback
+```
+
+This connects with the trusted writer env var named by `write_url_env` and
+checks:
+
+- writer database connectivity;
+- `synapsor_writeback_receipts` permission through the adapter doctor;
+- rollback-only access to each configured proposal target table;
+- rollback-only update permission for configured allowed write columns.
+
+The target-table probe uses fixed schema/table/column identifiers from the
+reviewed config. It does not accept model SQL, user SQL, arbitrary table names,
+or arbitrary column names. It runs inside a transaction and rolls back.
+
+The receipt-table probe can create `synapsor_writeback_receipts` if the writer
+has permission. If your policy does not allow Runner to create tables in the
+application schema, pre-create the table and grant access:
+
+```bash
+synapsor-runner writeback migration --engine postgres --schema synapsor
+synapsor-runner writeback grants --engine postgres --schema synapsor --writer-role app_writer
+```
+
+For MySQL:
+
+```bash
+synapsor-runner writeback migration --engine mysql --schema appdb
+synapsor-runner writeback grants --engine mysql --schema appdb --writer-role "'app_writer'@'%'"
+```
+
+Use an app-owned `http_handler` or `command_handler` executor when your
+application should own richer business writes or receipt storage.
+
+## Redaction
+
+Doctor output intentionally uses safe categories such as:
+
+```text
+connection failed
+authentication failed
+permission denied
+configured object not found
+database probe failed
+```
+
+Raw driver errors, connection strings, passwords, tokens, signing secrets, and
+handler URLs are not printed in the report.

package/docs/handler-helper.md

@@ -0,0 +1,217 @@
+# App-Owned Handler Helper
+
+Use the TypeScript handler helper when an approved Synapsor proposal should be
+executed by your application service, not by Runner's direct SQL writer.
+
+The helper is the safe-by-default path for rich writes such as:
+
+- inserting account-credit, refund-review, ticket, or ledger rows;
+- updating multiple related rows inside your app transaction;
+- applying business rules that belong in your application service.
+
+The model-facing MCP tool still creates a proposal only. A human/operator
+approves outside MCP. After approval, Runner sends the structured writeback
+request to your handler.
+
+## Scope
+
+Current alpha scope:
+
+- TypeScript helper in `packages/handler`;
+- bearer token verification;
+- optional HMAC verification over the raw request body;
+- typed request parsing;
+- action dispatch;
+- idempotency receipt lookup;
+- transaction wrapper;
+- `SELECT ... FOR UPDATE` target-row lock;
+- tenant guard;
+- expected-version stale-row guard;
+- safe applied/conflict/failed receipts;
+- no raw driver errors in HTTP responses.
+
+Python helper is planned. For now, Python handlers should follow the documented
+request/receipt schema and the FastAPI template in `examples/app-owned-writeback`.
+
+## Distribution Status
+
+The helper implementation exists in this source repo under `packages/handler`
+and is used by the app-owned executor example and tests. It is not published as
+a standalone `@synapsor/handler` npm package yet.
+
+If you installed `@synapsor/runner` from npm, use one of these alpha paths:
+
+- generate a starter handler with `synapsor-runner handler template ...`;
+- copy from `examples/app-owned-writeback/`;
+- run `examples/mcp-postgres-billing-app-handler/`, which includes a bundled
+  `synapsor-handler.mjs` shim inside the runner package.
+
+The `@synapsor/handler` import below is the source-checkout API and the planned
+standalone package API. Do not `npm install @synapsor/handler` until that
+package is published.
+
+## Schemas
+
+Published schemas:
+
+- `schemas/synapsor.app-handler-request.v1.json`
+- `schemas/synapsor.app-handler-receipt.v1.json`
+
+The helper accepts both the new `protocol_version: "1.0"` shape and the current
+Runner `schema_version: "synapsor.handler-writeback.v1"` request shape during
+the alpha migration.
+
+## TypeScript Usage From A Source Checkout
+
+```ts
+import { createWritebackHandler } from "@synapsor/handler";
+
+export const handler = createWritebackHandler({
+  tokenEnv: "SYNAPSOR_APP_HANDLER_TOKEN",
+  signingSecretEnv: "SYNAPSOR_APP_HANDLER_SIGNING_SECRET",
+  source: {
+    engine: "postgres",
+    writeUrlEnv: "SYNAPSOR_APP_WRITE_URL",
+    receiptTable: { schema: "synapsor", table: "handler_receipts" }
+  },
+  capabilities: {
+    "support.propose_plan_credit": async (job, tx) => {
+      const creditId = `CR-${job.proposalId.slice(-12)}`;
+
+      await tx.insert("credits", {
+        id: creditId,
+        tenant_id: job.tenantId,
+        invoice_id: job.objectId,
+        amount_cents: Number(job.patch.credit_requested_cents),
+        reason: String(job.patch.credit_reason),
+        created_by: job.principal
+      });
+
+      await tx.update("invoices", {
+        id: job.objectId,
+        tenant_id: job.tenantId
+      }, {
+        credited_cents:
+          Number(job.row.credited_cents ?? 0) +
+          Number(job.patch.credit_requested_cents)
+      });
+
+      return {
+        rowsAffected: 2,
+        effects: [{ type: "db.insert", table: "credits", id: creditId }]
+      };
+    }
+  }
+});
+```
+
+Mount the returned handler at your app route, for example
+`POST /synapsor/writeback`.
+
+The handler author writes only the business effect. The helper owns the safety
+loop around that effect.
+
+## What The Helper Enforces
+
+The helper checks these before your business function can mutate state:
+
+- the bearer token matches the configured environment variable;
+- the optional HMAC signature is valid and fresh;
+- the request protocol is supported;
+- the action maps to a configured capability function;
+- the target row exists inside the trusted tenant;
+- the row version still matches the proposal's expected version;
+- the idempotency key was not already applied.
+
+If the row is missing or belongs to another tenant, the helper returns:
+
+```json
+{
+  "status": "conflict",
+  "rows_affected": 0,
+  "source_database_mutated": false,
+  "safe_error_code": "ROW_NOT_FOUND_OR_WRONG_TENANT"
+}
+```
+
+If the row changed after proposal creation, the helper returns:
+
+```json
+{
+  "status": "conflict",
+  "rows_affected": 0,
+  "source_database_mutated": false,
+  "safe_error_code": "ROW_CHANGED_AFTER_PROPOSAL"
+}
+```
+
+If your business function throws, the helper rolls back the transaction and
+returns a safe failed receipt. Raw driver and exception text are not exposed to
+the caller.
+
+## Runner-Side Signing Config
+
+Configure the matching `http_handler` executor with the same signing-secret env
+name:
+
+```json
+{
+  "executors": {
+    "billing_handler": {
+      "type": "http_handler",
+      "url_env": "BILLING_WRITEBACK_URL",
+      "method": "POST",
+      "auth": {
+        "type": "bearer_env",
+        "token_env": "BILLING_WRITEBACK_TOKEN"
+      },
+      "signing_secret_env": "SYNAPSOR_APP_HANDLER_SIGNING_SECRET",
+      "timeout_ms": 5000
+    }
+  }
+}
+```
+
+When this field is set, Runner signs the exact request body and sends
+`X-Synapsor-Signature`, `X-Synapsor-Issued-At`,
+`X-Synapsor-Proposal-Id`, and `Idempotency-Key`. The helper verifies those
+headers before parsing or applying the writeback request.
+
+## Signing
+
+For loopback-only development, bearer auth may be enough. For any handler that
+is reachable outside the local process, enable HMAC:
+
+```ts
+createWritebackHandler({
+  tokenEnv: "SYNAPSOR_APP_HANDLER_TOKEN",
+  signingSecretEnv: "SYNAPSOR_APP_HANDLER_SIGNING_SECRET",
+  // ...
+});
+```
+
+Runner sends:
+
+```text
+Authorization: Bearer <token>
+X-Synapsor-Signature: sha256=<hmac>
+X-Synapsor-Issued-At: <iso timestamp>
+X-Synapsor-Proposal-Id: wrp_...
+Idempotency-Key: wrp_...
+```
+
+The HMAC is computed over the raw body. The helper enforces a short issued-at
+skew window.
+
+## Receipt Storage
+
+The helper's Postgres adapter stores idempotency receipts in a receipt table.
+Prefer a dedicated schema, for example:
+
+```sql
+CREATE SCHEMA IF NOT EXISTS synapsor;
+GRANT USAGE, CREATE ON SCHEMA synapsor TO app_writeback_user;
+```
+
+If your application already has a receipt/idempotency table, implement the
+`WritebackHandlerDatabase` interface and pass it as `database`.

package/docs/local-mode.md

@@ -273,13 +273,24 @@ or prune it without touching your source Postgres/MySQL database:
 
 ```bash
 synapsor-runner store stats --store ./.synapsor/local.db
+synapsor-runner events tail --store ./.synapsor/local.db
 synapsor-runner store vacuum --store ./.synapsor/local.db
 synapsor-runner store prune --store ./.synapsor/local.db --older-than 30d --dry-run
 synapsor-runner store prune --store ./.synapsor/local.db --older-than 30d --yes
+synapsor-runner store prune --store ./.synapsor/local.db --older-than 30d --yes --force
+synapsor-runner store reset --store ./.synapsor/local.db --yes
 ```
 
-`store prune` defaults to dry-run. Use `--yes` only after reviewing the row
-counts it will remove.
+`events tail` shows local lifecycle events already recorded in the SQLite
+ledger, including proposal creation, approval/rejection, writeback jobs, and
+writeback applied/conflict/failed receipts. Add `--follow` to keep polling a
+running local store.
+
+`store prune` defaults to dry-run. `store reset` requires `--yes` and removes
+only the local SQLite ledger files. MCP server modes write a small active-store
+lease next to the SQLite file; destructive store operations refuse while that
+lease points at a live PID unless you pass `--force` after verifying the server
+is stopped or stale.
 
 ## Boundary