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

package/CHANGELOG.md

@@ -0,0 +1,93 @@
+# Changelog
+
+## Unreleased
+
+### Added
+
+- `result_format: 2` for a stable MCP result envelope with
+  `ok`, `summary`, `data`, `proposal`, `error`, `evidence`,
+  `source_database_changed`, and `_meta.canonical_capability`.
+- `--result-format v1|v2` for `mcp serve`, `mcp serve --transport
+  streamable-http`, `mcp serve-streamable-http`, and the legacy JSON-RPC bridge.
+- Capability config fields `description`, per-argument `description`, and
+  `returns_hint`; these are surfaced in MCP tool metadata.
+- `tools list` as a first-class alias for `tools preview`, including
+  `tools list --aliases`.
+- `mcp client-config --include-instructions` for Claude/Cursor/OpenAI-style
+  client snippets with propose-first agent guidance.
+- `schemas/synapsor.runner.schema.json` for editor validation.
+- `docs/capability-authoring.md` and `docs/result-envelope-v2.md`.
+- RFC source docs under `docs/rfcs/`.
+
+### Changed
+
+- OpenAI-safe aliases include the canonical Synapsor capability name in
+  descriptions/metadata so model-visible aliases can still be audited against
+  dotted capability names.
+- v2 MCP errors redact raw driver/infra strings and map failures to a small
+  safe error-code enum.
+
+### Compatibility
+
+- Result envelope v1 remains the default in this alpha. Opt in with
+  `result_format: 2` or `--result-format v2`.
+- The public command remains `synapsor-runner`.
+
+## 0.1.0-alpha.15
+
+### Changed
+
+- Clarified that users install only `@synapsor/runner`. A handler is the
+  user's app endpoint or script for rich approved writes, and Runner includes
+  templates/examples to help build one.
+
+## 0.1.0-alpha.14
+
+### Changed
+
+- Clarified that `@synapsor/handler` is not published as a standalone npm
+  package yet. The TypeScript helper currently exists in the source monorepo
+  and as the bundled `synapsor-handler.mjs` shim used by the packaged
+  app-owned executor example.
+- Included `CHANGELOG.md` in the `@synapsor/runner` npm tarball so users can
+  inspect alpha changes without cloning the repository.
+
+## 0.1.0-alpha.13
+
+### Changed
+
+- Reworked the README opening around a five-line mental model: agent talks to
+  Runner, Runner exposes capabilities, proposals are saved but not applied, and
+  approval/writeback stay outside the model-facing tool surface.
+- Added plain definitions for capability, proposal, writeback, and executor near
+  the top of the README.
+- Added the direct-writeback versus app-owned-executor rule up front: guarded
+  one-row updates can use Runner direct writeback; richer business actions use
+  an app-owned executor.
+- Added a tiny readable own-database config example with one read capability and
+  one proposal capability so new users can picture what the guided wizard
+  creates.
+
+## 0.1.0-alpha.12
+
+### Added
+
+- `doctor --check-writeback` verifies direct SQL writer connectivity,
+  receipt-table readiness, and rollback-only access to configured proposal
+  target tables/columns without mutating business rows.
+- `docs/doctor.md` documents redacted setup checks, handler reachability,
+  direct SQL writeback probes, and receipt-table guidance.
+- `store reset --yes` removes only the local SQLite ledger files and refuses
+  active server leases unless `--force` is provided.
+
+### Changed
+
+- Doctor output now warns when direct SQL writeback has not been probed and
+  points to `--check-writeback`.
+- Packed/public verification scripts exercise `store reset` in addition to
+  stats/prune.
+
+## 0.1.0-alpha.11
+
+See [docs/release-notes.md](docs/release-notes.md) for the current published
+alpha notes.

package/README.md

@@ -25,6 +25,10 @@ After writeback, Runner keeps receipts and replay so you can inspect what happen
 - Executor: your app's writeback handler for anything richer than a guarded
   one-row update.
 
+You install only `@synapsor/runner`. There is no separate handler package to
+install. A handler is your app's endpoint or script for rich approved writes;
+Runner includes templates and examples to help you build one.
+
 ## Who Does What
 
 You write the config: sources, trusted context, capabilities, visible fields,
@@ -585,6 +589,9 @@ your application service already owns business writes, configure an
 `http_handler` or `command_handler` executor. Approval still happens outside
 MCP, and the handler returns an applied/conflict/failed receipt for replay.
 Starter handlers are included under `examples/app-owned-writeback`.
+The packaged app-owned billing example also includes a bundled
+`synapsor-handler.mjs` helper shim; `@synapsor/handler` is not published as a
+standalone npm package yet.
 You can also generate a starter handler directly:
 
 ```bash

package/dist/runner.mjs

@@ -2747,7 +2747,7 @@ function assertPersistentStoreAvailable(storePath) {
 }
 function createSynapsorMcpServer(runtime, options = {}) {
   const server = new McpServer(
-    { name: "synapsor-runner", version: "0.1.0-alpha.13" },
+    { name: "synapsor-runner", version: "0.1.0-alpha.15" },
     { capabilities: { tools: {}, resources: {} } }
   );
   const toolNameStyle = options.toolNameStyle ?? "canonical";
@@ -9172,7 +9172,7 @@ async function cloudConnect(args) {
     return 1;
   }
   const runnerId = String(parsed.cloud.runner_id || process2.env.SYNAPSOR_RUNNER_ID || "synapsor_runner_local").trim();
-  const runnerVersion = String(parsed.cloud.runner_version || process2.env.npm_package_version || "0.1.0-alpha.13").trim();
+  const runnerVersion = String(parsed.cloud.runner_version || process2.env.npm_package_version || "0.1.0-alpha.15").trim();
   const engines = normalizeEngines(parsed.cloud.engines);
   const capabilities = normalizeCapabilities(parsed.cloud.capabilities);
   const client = new ControlPlaneClient({
@@ -13311,7 +13311,7 @@ function starterCloudConfig() {
       base_url_env: "SYNAPSOR_CLOUD_BASE_URL",
       runner_token_env: "SYNAPSOR_RUNNER_TOKEN",
       runner_id: "synapsor_runner_local",
-      runner_version: "0.1.0-alpha.13",
+      runner_version: "0.1.0-alpha.15",
       project_id: "token_scope",
       adapter_id: "mcp.your_adapter",
       source_id: "src_replace_me",

package/docs/app-owned-executors.md

@@ -17,6 +17,11 @@ The model-facing MCP tool only creates a proposal. Approval happens outside MCP.
 After approval, Runner calls your `http_handler` or `command_handler`, records
 the receipt, and includes the result in replay.
 
+A handler is your application endpoint or script. It is not a second Synapsor
+package that users need to install. Install `@synapsor/runner`, then generate
+or copy a handler template only when your approved write needs app-owned
+business logic.
+
 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.
 

package/docs/handler-helper.md

@@ -3,6 +3,10 @@
 Use the TypeScript handler helper when an approved Synapsor proposal should be
 executed by your application service, not by Runner's direct SQL writer.
 
+This is optional support code for your app-owned handler. Users install
+`@synapsor/runner`; they do not install a separate handler package in the
+current alpha.
+
 The helper is the safe-by-default path for rich writes such as:
 
 - inserting account-credit, refund-review, ticket, or ledger rows;
@@ -33,6 +37,23 @@ Current alpha scope:
 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:
@@ -44,7 +65,7 @@ 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
+## TypeScript Usage From A Source Checkout
 
 ```ts
 import { createWritebackHandler } from "@synapsor/handler";

package/docs/release-notes.md

@@ -11,6 +11,24 @@ 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.15
+
+### Handler Wording Clarification
+
+- README and app-owned executor docs now state that users install only
+  `@synapsor/runner`. A handler is the user's own app endpoint or script for
+  rich approved writes, not a second Synapsor package to install.
+
+## 0.1.0-alpha.14
+
+### Handler Helper And Changelog Clarity
+
+- Public docs now state that `@synapsor/handler` is not published as a
+  standalone npm package yet. The helper currently ships as source under
+  `packages/handler` and as the bundled `synapsor-handler.mjs` shim in the
+  app-owned executor example included with `@synapsor/runner`.
+- `CHANGELOG.md` is included in the `@synapsor/runner` npm tarball.
+
 ## 0.1.0-alpha.13
 
 ### README First-Five-Minutes Polish
@@ -199,5 +217,5 @@ After publishing an alpha, verify the public package from a clean temporary
 directory:
 
 ```bash
-./scripts/verify-published-alpha.sh 0.1.0-alpha.13
+./scripts/verify-published-alpha.sh 0.1.0-alpha.15
 ```

package/docs/release-policy.md

@@ -5,7 +5,7 @@ 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
+npm install -g @synapsor/runner@0.1.0-alpha.15
 ```
 
 Do not rely on the untagged `latest` dist-tag until a stable release is

package/examples/mcp-postgres-billing-app-handler/README.md

@@ -15,9 +15,10 @@ App-owned rich writeback:
 - model-facing MCP only creates a proposal;
 - approval happens outside MCP;
 - Runner calls `billing_app_handler`;
-- the app uses the first-party `@synapsor/handler` helper to verify bearer
-  auth, HMAC signature, tenant scope, expected row version, idempotency, and
-  transaction/receipt shape;
+- the app uses the first-party handler helper from the source workspace, or the
+  bundled `synapsor-handler.mjs` shim included in the runner npm package, to
+  verify bearer auth, HMAC signature, tenant scope, expected row version,
+  idempotency, and transaction/receipt shape;
 - the handler business code inserts an `account_credits` row and updates the
   invoice inside the helper-owned transaction;
 - Runner records the handler receipt and replay.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synapsor/runner",
-  "version": "0.1.0-alpha.13",
+  "version": "0.1.0-alpha.15",
   "description": "Commit-safe MCP runner for Postgres and MySQL agents",
   "license": "Apache-2.0",
   "type": "module",
@@ -25,6 +25,7 @@
     "schemas/**",
     "recipes/**/*.json",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE",
     "NOTICE",
     "TRADEMARKS.md"