@synapsor/runner 0.1.0-alpha.10 → 0.1.0-alpha.13

package/docs/handler-helper.md

@@ -0,0 +1,200 @@
+# 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`.
+
+## 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
+
+```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/http-mcp.md

@@ -28,6 +28,38 @@ synapsor-runner mcp serve-streamable-http \
   --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
 ```
 
+For OpenAI Agents SDK, expose OpenAI-safe aliases because OpenAI function names
+cannot contain dots:
+
+```bash
+synapsor-runner mcp serve-streamable-http \
+  --host 127.0.0.1 \
+  --port 8766 \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN \
+  --alias-mode openai
+```
+
+Equivalent unified command:
+
+```bash
+synapsor-runner mcp serve \
+  --transport streamable-http \
+  --host 127.0.0.1 \
+  --port 8766 \
+  --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`. MCP tool metadata
+still includes `synapsor.canonical_tool_name`, and Runner maps calls back to
+the canonical Synapsor capability such as `billing.inspect_invoice`. Use
+`--alias-mode both` only during migrations where some clients still need
+canonical dotted names.
+
 Defaults:
 
 ```text
@@ -239,4 +271,6 @@ example connects to `synapsor-runner mcp serve-streamable-http` through
 want a small app-owned wrapper instead of standard HTTP MCP.
 
 The boundary is the same in both modes: the agent calls a semantic Synapsor
-tool, not raw SQL.
+tool, not raw SQL. OpenAI-facing examples use `--alias-mode openai` so
+the model sees OpenAI-valid aliases while Runner preserves canonical Synapsor
+tool names in metadata.

package/docs/licensing.md

@@ -0,0 +1,36 @@
+# Licensing
+
+Synapsor Runner is open source under the Apache License 2.0 (`Apache-2.0`).
+
+This page is a plain-English summary, not legal advice. If this summary
+conflicts with `../LICENSE`, the `LICENSE` file controls.
+
+Apache-2.0 applies to the code in this runner repository. It grants copyright
+and patent rights under the license terms.
+
+Apache-2.0 does not grant trademark rights. The Synapsor name, Synapsor Runner
+name, logos, hosted Cloud service, and proprietary Synapsor platform features
+remain separate. See `../TRADEMARKS.md`.
+
+This license applies only to `synapsor-runner`. It does not open source:
+
+- Synapsor Cloud;
+- the hosted control plane;
+- hosted capability registry;
+- advanced policy/capability compiler;
+- team approvals, RBAC, or SSO;
+- hosted audit/evidence ledger;
+- managed runners;
+- production writeback orchestration;
+- workflow builder;
+- native Synapsor engine;
+- C++/DBMS internals;
+- branching, time travel, or settlement;
+- compliance exports or production support/SLA.
+
+Synapsor Cloud is a separate hosted commercial service. Use Cloud when your team
+needs shared approvals, RBAC, hosted evidence/replay search, runner fleet
+status, leases, retention, audit visibility, enterprise controls, and support.
+
+Before public release, license and trademark text should be reviewed by the
+release owner or qualified counsel.

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
 

package/docs/mcp-client-setup.md

@@ -51,6 +51,34 @@ npx -y -p @synapsor/runner@alpha synapsor-runner mcp serve-streamable-http \
   --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
 ```
 
+OpenAI Agents SDK rejects dotted function/tool names such as
+`billing.inspect_invoice`. For OpenAI-facing transports, ask Runner to expose
+OpenAI-safe aliases while keeping canonical Synapsor capability names in MCP
+metadata:
+
+```bash
+npx -y -p @synapsor/runner@alpha 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 names such as `billing__inspect_invoice`; `_meta` includes
+`synapsor.canonical_tool_name = billing.inspect_invoice`, and Runner routes the
+alias back to the canonical capability. Use `--alias-mode both` only when a
+migration needs canonical dotted names and OpenAI-safe aliases exposed at the
+same time.
+
+Preview the exact alias mapping before wiring a client:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner tools preview \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --alias-mode openai
+```
+
 Use private networking/TLS before exposing HTTP MCP beyond localhost. Details:
 [HTTP MCP](http-mcp.md).
 
@@ -72,6 +100,17 @@ generic
 claude-desktop
 cursor
 vscode
+openai-agents
+```
+
+For OpenAI Agents SDK, generate the Streamable HTTP start command and Python
+snippet:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner mcp client-config \
+  --client openai-agents \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
 ```
 
 The older form is still supported:

package/docs/openai-agents-sdk.md

@@ -0,0 +1,57 @@
+# OpenAI Agents SDK
+
+Use Synapsor Runner with the OpenAI Agents SDK through standard MCP Streamable
+HTTP. Runner exposes semantic database tools to the model and keeps approval,
+writeback, database URLs, and write credentials outside the model-facing tool
+surface.
+
+## Start Runner
+
+```bash
+export SYNAPSOR_RUNNER_HTTP_TOKEN="dev-local-token"
+
+npx -y -p @synapsor/runner@alpha synapsor-runner mcp serve-streamable-http \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN \
+  --alias-mode openai
+```
+
+`--alias-mode openai` is important because OpenAI function/tool names cannot
+contain dots. Runner exposes names such as `billing__inspect_invoice` to the
+model and maps calls back to canonical Synapsor capability names such as
+`billing.inspect_invoice`.
+
+## Generate The Snippet
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner mcp client-config \
+  --client openai-agents \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+```
+
+The generated output includes:
+
+- the Streamable HTTP server command;
+- the `/mcp` URL;
+- a Python `MCPServerStreamableHttp` snippet;
+- the OpenAI alias note.
+
+It does not include database URLs, passwords, write credentials, API keys, or
+bearer token values.
+
+## Sanity Check
+
+Before giving the agent a real task, ask it to inspect one known object and
+return the tool name it called plus the evidence handle. A healthy setup calls a
+semantic tool such as `billing__inspect_invoice`. It should not expose
+`execute_sql`, approval tools, commit/apply tools, database URLs, or write
+credentials.
+
+## Examples
+
+```text
+examples/openai-agents-http/
+examples/openai-agents-stdio/
+```

package/docs/release-notes.md

@@ -11,6 +11,74 @@ npx -y -p @synapsor/runner@alpha synapsor-runner demo --quick
 The OSS runner command is `synapsor-runner`. The `synapsor` command is reserved
 for the Synapsor Cloud CLI.
 
+## 0.1.0-alpha.13
+
+### README First-Five-Minutes Polish
+
+- The README now opens with the plain mental model: the agent talks to Runner,
+  can inspect scoped data, can create proposals, cannot commit, and writeback
+  plus replay happen outside the model-facing tool.
+- Capability, proposal, writeback, and executor are defined before the first
+  command so a new reader can understand the rest of the docs.
+- The README now states the direct-writeback rule early: guarded one-row updates
+  can use Runner direct writeback; inserts, multi-table work, events, and other
+  rich writes belong in an app-owned executor.
+- The own-database section now includes a tiny readable config with one read
+  capability and one proposal capability so users can picture what the wizard
+  generates before they run it.
+
+## 0.1.0-alpha.12
+
+### Doctor And Writeback Checks
+
+- `synapsor-runner doctor --config synapsor.runner.json --check-writeback`
+  verifies direct SQL writer connectivity, receipt-table readiness, and
+  rollback-only target-table access for reviewed proposal capabilities.
+- Plain `doctor` warns when direct SQL writeback exists but has not been probed.
+- The writeback probe uses fixed identifiers from reviewed config only. It does
+  not accept model SQL, user SQL, arbitrary table names, or arbitrary columns.
+- Probe failures are redacted to safe categories such as `connection failed`,
+  `permission denied`, and `configured object not found`.
+- `docs/doctor.md` explains handler checks, direct SQL writeback checks, and
+  receipt-table DDL/grant guidance.
+
+### Store Lifecycle
+
+- `synapsor-runner store reset --store ./.synapsor/local.db --yes` removes only
+  local SQLite ledger files and reports `source_database_changed: false`.
+- Destructive store reset refuses active server leases by default and requires
+  `--force` for advanced/stale-lease recovery.
+- Packed and public verifier scripts now cover `store reset`.
+
+## 0.1.0-alpha.11
+
+### OpenAI MCP Aliases
+
+- `synapsor-runner mcp serve` and `synapsor-runner mcp serve-streamable-http`
+  now accept `--alias-mode openai` and `--openai-tool-aliases`.
+- `synapsor-runner mcp serve --transport streamable-http` is available as a
+  unified command form for the standard HTTP MCP server.
+- `synapsor-runner mcp client-config --client openai-agents` prints a
+  Streamable HTTP start command and OpenAI Agents SDK snippet.
+- `synapsor-runner tools preview --alias-mode openai` shows model-visible alias
+  names and the canonical Synapsor capability each alias maps to.
+- `examples/mcp-postgres-billing-app-handler/` adds a disposable Postgres proof
+  for the app-owned executor path: proposal first, approval outside MCP,
+  account-credit row inserted by the app handler, idempotent retry, and replay.
+- `--alias-mode both` exposes canonical dotted names and OpenAI-safe aliases
+  together for migration/debugging.
+- OpenAI alias mode exposes MCP tool names such as
+  `billing__inspect_invoice` instead of canonical dotted names such as
+  `billing.inspect_invoice`.
+- Tool metadata includes `synapsor.canonical_tool_name`,
+  `synapsor.exposed_tool_name`, and `synapsor.tool_name_style`, so reviewers
+  can still see the canonical Synapsor capability.
+- Runner routes alias calls back to the canonical capability. This removes the
+  need for user-written OpenAI wrapper code whose only job is replacing dots in
+  tool names.
+- The OpenAI Agents SDK stdio and Streamable HTTP examples now document the
+  built-in alias mode.
+
 ## 0.1.0-alpha.10
 
 ### First-Run Flow
@@ -38,7 +106,8 @@ for the Synapsor Cloud CLI.
   initialize/session behavior on the `/mcp` endpoint.
 - `synapsor-runner mcp serve-http` is an authenticated JSON-RPC bridge for
   simple `tools/list`, `tools/call`, and `resources/read` wrappers. It is not
-  the standard Streamable HTTP MCP transport.
+  the standard Streamable HTTP MCP transport and prints a runtime warning when
+  started.
 - The OpenAI Agents SDK HTTP example uses the Streamable HTTP MCP path. Use the
   JSON-RPC bridge only when you intentionally want a thin app-owned wrapper.
 
@@ -71,6 +140,11 @@ for the Synapsor Cloud CLI.
   binding, evidence handles, query audit, and local inspection records.
 - Proposal workflows add full local replay across evidence, approval,
   writeback jobs, execution receipts, and events.
+- `synapsor-runner events tail` prints local lifecycle events from the SQLite
+  ledger and can follow new proposal/writeback events while a local flow runs.
+- MCP server modes write an active-store lease next to the local SQLite file.
+  Destructive `store prune --yes` refuses while that lease points at a live
+  process unless `--force` is provided.
 - External Postgres/MySQL databases are not physically branched by Runner.
   Replay covers records captured by Runner; it is not external database
   time travel.
@@ -125,5 +199,5 @@ After publishing an alpha, verify the public package from a clean temporary
 directory:
 
 ```bash
-./scripts/verify-published-alpha.sh 0.1.0-alpha.10
+./scripts/verify-published-alpha.sh 0.1.0-alpha.13
 ```

package/docs/release-policy.md

@@ -0,0 +1,86 @@
+# Release Policy
+
+Synapsor Runner is currently an alpha local runner. Use the explicit alpha tag
+or an exact version:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner demo --quick
+npm install -g @synapsor/runner@0.1.0-alpha.13
+```
+
+Do not rely on the untagged `latest` dist-tag until a stable release is
+published.
+
+## Alpha Expectations
+
+Alpha versions may change:
+
+- command names and help text;
+- MCP transport defaults;
+- config fields and JSON Schema;
+- local store layout;
+- result envelope format;
+- writeback/handler contracts;
+- example layout and docs.
+
+Alpha releases must keep the safety boundary intact:
+
+- no model-facing `execute_sql`;
+- no model-facing write credentials;
+- no model-facing approval/commit/apply tools;
+- no generic model-generated INSERT/DELETE/UPSERT/DDL/multi-row SQL;
+- proposal-first write path stays explicit.
+
+## Stable Expectations
+
+A stable `0.1.0` release should only be tagged after:
+
+- npm README commands match the published package;
+- `synapsor-runner demo --quick` works from a clean directory;
+- own-database onboarding works from a clean directory;
+- stdio MCP and Streamable HTTP MCP are both verified;
+- OpenAI alias mode is verified;
+- direct SQL writeback requirements are documented and tested;
+- app-owned executor requirements are documented and tested;
+- local evidence/proposal/receipt/replay inspection works;
+- current limitations are accurate.
+
+## Result Envelope Migration
+
+`result_format: 2` is opt-in during alpha migration:
+
+```json
+{
+  "result_format": 2
+}
+```
+
+or:
+
+```bash
+synapsor-runner mcp serve --result-format v2
+synapsor-runner mcp serve-streamable-http --result-format v2
+```
+
+v1 remains the default until the migration is explicitly called out in a future
+release note. v2 makes `ok` the only required branch point for MCP client code.
+
+## Publish Checklist
+
+Before publishing a new alpha:
+
+```bash
+corepack pnpm typecheck
+corepack pnpm exec vitest run packages/mcp-server/src/index.test.ts apps/runner/src/cli.test.ts
+./scripts/verify-packed-runner.sh
+npm pack --dry-run
+git diff --check
+```
+
+After publishing:
+
+```bash
+npm view @synapsor/runner@alpha version bin license
+npx -y -p @synapsor/runner@alpha synapsor-runner demo --quick --no-interactive
+npx -y -p @synapsor/runner@alpha synapsor-runner audit --example dangerous-db-mcp --format markdown
+```