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

package/docs/README.md

@@ -20,7 +20,7 @@ detail.
   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
+- [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.
@@ -60,8 +60,8 @@ 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
+- `synapsor-runner events tail` and `events webhook`: local lifecycle events
+  such as `proposal_created`, `proposal_approved`, `writeback_applied`, and
   `writeback_conflict`.
 
 Useful examples:

package/docs/app-owned-executors.md

@@ -17,6 +17,13 @@ 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.
 
+> **Important:** your app handler owns the final business write. Runner creates
+> the proposal and calls your handler only after approval, but your handler must
+> still enforce tenant/scope checks, expected-version or conflict guards,
+> idempotency keys, allowed business actions, transaction/rollback, and safe
+> error receipts. If you skip those checks, you can reintroduce cross-tenant
+> writes, lost updates, or duplicate writes. Keep handler credentials out of MCP.
+
 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

package/docs/current-scope.md

@@ -13,6 +13,12 @@ Current alpha scope:
   business transactions;
 - stdio MCP, Streamable HTTP MCP, and a small JSON-RPC bridge.
 
+Stable `0.1.x` compatibility, once `0.1.0` is promoted to `latest`, covers the
+documented `synapsor-runner` binary, config schema version `1`, result envelope
+v2 with v1 opt-out, stdio/Streamable HTTP MCP surfaces, documented MCP client
+snippets, proposal/evidence/replay inspection commands, direct SQL writeback,
+and app-owned executor contracts.
+
 Out of scope:
 
 - raw `execute_sql`;

package/docs/getting-started-own-database.md

@@ -179,7 +179,8 @@ The wizard:
   mode, semantic capability names, and proposal patch mappings;
 - asks review-mode users to choose direct guarded SQL writeback, an app-owned
   HTTP handler, or an app-owned command handler;
-- previews the MCP tools and what is not exposed;
+- previews the MCP tools and what is not exposed, then lets you revise visible
+  fields or capability names before writing files;
 - attempts a first smoke call when you supplied a real object id and the
   required trusted env vars are present;
 - writes the generated config, `.env.example`, and MCP client snippets only
@@ -208,12 +209,17 @@ npx -y -p @synapsor/runner@alpha synapsor-runner init \
   --mode review \
   --visible-columns id,tenant_id,late_fee_cents,waiver_reason,updated_at \
   --allowed-columns late_fee_cents,waiver_reason \
-  --patch-fixed late_fee_cents=0 \
-  --patch-from-arg waiver_reason=reason \
-  --numeric-bound late_fee_cents=0:5500 \
+  --tenant-column tenant_id \
+  --id-arg invoice_id \
+  --patch late_fee_cents=fixed:0,waiver_reason=arg:reason \
+  --patch-bounds late_fee_cents=0:5500 \
   --write-url-env SYNAPSOR_DATABASE_WRITE_URL
 ```
 
+If you omit `--namespace`, Runner derives the namespace from the table name
+instead of defaulting to `source.*`. Add `--read-tool` and `--proposal-tool`
+when you want exact capability names in the generated contract.
+
 For app-owned writeback, replace the direct writer env with a handler executor:
 
 ```bash
@@ -225,13 +231,19 @@ npx -y -p @synapsor/runner@alpha synapsor-runner init \
   --namespace billing \
   --object-name invoice \
   --mode review \
-  --patch-fixed late_fee_cents=0 \
-  --patch-from-arg waiver_reason=reason \
+  --tenant-column tenant_id \
+  --id-arg invoice_id \
+  --patch late_fee_cents=fixed:0,waiver_reason=arg:reason \
   --writeback http_handler \
   --handler-url-env APP_WRITEBACK_URL \
-  --handler-token-env APP_WRITEBACK_TOKEN
+  --handler-token-env APP_WRITEBACK_TOKEN \
+  --emit-handler
 ```
 
+Handler-owned configs mark the Runner source as read-only unless you explicitly
+pass `--write-url-env`, so `config validate` does not warn that direct SQL
+writeback is disabled.
+
 Use `--writeback command_handler --handler-command-env APP_WRITEBACK_COMMAND`
 when your app-owned writer is a local command/script instead of HTTP.
 
@@ -244,8 +256,7 @@ npx -y -p @synapsor/runner@alpha synapsor-runner init \
   --namespace billing \
   --object-name invoice \
   --mode review \
-  --patch-fixed late_fee_cents=0 \
-  --patch-from-arg waiver_reason=reason
+  --patch late_fee_cents=fixed:0,waiver_reason=arg:reason
 ```
 
 The command uses inspected metadata for primary-key, tenant-key, conflict-column,
@@ -253,15 +264,15 @@ and default-visible-column suggestions. If a suggestion is ambiguous or missing,
 pass explicit flags such as `--primary-key`, `--tenant-key`, and
 `--conflict-column`.
 
-Review mode requires at least one explicit `--patch-fixed` or
-`--patch-from-arg` mapping. Use `--mode read_only` if you only want an inspect
-tool.
+Review mode requires at least one explicit `--patch` mapping, or the older
+`--patch-fixed` / `--patch-from-arg` flags. Use `--mode read_only` if you only
+want an inspect tool.
 
 For bounded business actions, add reviewed value guards:
 
 ```bash
---numeric-bound credit_cents=0:10000
---transition-guard status=open:pending_review
+--patch-bounds credit_cents=0:10000
+--status-guards status=open:pending_review
 ```
 
 `--numeric-bound` keeps a proposed numeric column inside a fixed range before a
@@ -279,6 +290,7 @@ Create `onboarding-selection.json` from one table and one safe business action.
   "version": 1,
   "engine": "postgres",
   "mode": "review",
+  "result_format": 2,
   "read_url_env": "SYNAPSOR_DATABASE_READ_URL",
   "write_url_env": "SYNAPSOR_DATABASE_WRITE_URL",
   "schema": "public",
@@ -288,6 +300,8 @@ Create `onboarding-selection.json` from one table and one safe business action.
   "conflict_column": "updated_at",
   "namespace": "billing",
   "object_name": "invoice",
+  "read_tool": "billing.inspect_invoice",
+  "proposal_tool": "billing.propose_late_fee_waiver",
   "visible_columns": ["id", "tenant_id", "late_fee_cents", "waiver_reason", "updated_at"],
   "allowed_columns": ["late_fee_cents", "waiver_reason"],
   "patch": {
@@ -386,6 +400,20 @@ export SYNAPSOR_TENANT_ID="acme"
 export SYNAPSOR_PRINCIPAL="local_operator"
 export SYNAPSOR_RUNNER_HTTP_TOKEN="dev-local-token"
 
+npx -y -p @synapsor/runner@alpha synapsor-runner up --serve \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
+```
+
+`up --serve` runs the review-mode checklist first, then starts Streamable HTTP.
+Use `--dry-run` for the checklist only, or `--with-handler` when the config uses
+an app-owned executor and you want Runner to check the handler endpoint before
+serving.
+
+The lower-level MCP command starts the same transport directly:
+
+```bash
 npx -y -p @synapsor/runner@alpha synapsor-runner mcp serve-streamable-http \
   --config ./synapsor.runner.json \
   --store ./.synapsor/local.db \

package/docs/handler-helper.md

@@ -17,6 +17,13 @@ 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.
 
+> **Important:** your app handler owns the final business write. Runner creates
+> the proposal and calls your handler only after approval, but your handler must
+> still enforce tenant/scope checks, expected-version or conflict guards,
+> idempotency keys, allowed business actions, transaction/rollback, and safe
+> error receipts. If you skip those checks, you can reintroduce cross-tenant
+> writes, lost updates, or duplicate writes. Keep handler credentials out of MCP.
+
 ## Scope
 
 Current alpha scope:
@@ -41,7 +48,7 @@ request/receipt schema and the FastAPI template in `examples/app-owned-writeback
 
 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.
+a standalone npm package yet.
 
 If you installed `@synapsor/runner` from npm, use one of these alpha paths:
 
@@ -50,10 +57,6 @@ If you installed `@synapsor/runner` from npm, use one of these alpha paths:
 - 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:
@@ -67,8 +70,12 @@ the alpha migration.
 
 ## TypeScript Usage From A Source Checkout
 
+The source checkout has an internal helper under `packages/handler`. It is not
+an npm install path. Import it by workspace-relative path while developing this
+repository, or use the bundled example shim in the packaged runner.
+
 ```ts
-import { createWritebackHandler } from "@synapsor/handler";
+import { createWritebackHandler } from "../packages/handler/src/index.js";
 
 export const handler = createWritebackHandler({
   tokenEnv: "SYNAPSOR_APP_HANDLER_TOKEN",

package/docs/local-mode.md

@@ -274,6 +274,7 @@ 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 events webhook --url http://127.0.0.1:8788/synapsor/events --kind proposal_created --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
@@ -286,6 +287,11 @@ ledger, including proposal creation, approval/rejection, writeback jobs, and
 writeback applied/conflict/failed receipts. Add `--follow` to keep polling a
 running local store.
 
+`events webhook` pushes the same local lifecycle events to a local/dev/staging
+HTTP endpoint, one event envelope per POST. Use it for a review UI, Slack bridge,
+or app-local notification path when polling is awkward. It is not a hosted
+central ledger and does not expose database credentials.
+
 `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

package/docs/release-notes.md

@@ -11,6 +11,81 @@ 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.17
+
+### Scripted Onboarding
+
+- `onboard db` and `init` now have a prompt-free path for scripts, CI, and LLM
+  agents. Use `--yes`, `--non-interactive`, or `--answers <file.json>`.
+- Added friendly flags that match the first-run mental model:
+  `--tenant-column`, `--id-arg`, `--patch column=fixed:value|arg:name`,
+  `--patch-bounds`, `--status-guards`, `--read-description`,
+  `--read-returns-hint`, `--read-tool`, `--proposal-tool`,
+  `--handler-output`, and `--emit-handler`.
+- Answers-file onboarding writes the reviewed config, `.env.example`, MCP
+  snippets, and optional handler template without opening a TTY prompt.
+- When `--namespace` is omitted, generated capability names now derive a
+  namespace from the selected table instead of falling back to `source.*`.
+- The guided wizard now has a final "what I am about to write" preview where
+  users can revise visible fields or capability names before files are written.
+- README Start Here now tells users to run `tools preview` and `smoke call`
+  before wiring an MCP client.
+- `events webhook` / `events push` can POST local proposal/writeback lifecycle
+  events to a local/dev/staging HTTP endpoint for review UIs or notifications.
+
+### Writeback Readiness
+
+- App-owned executor configs generated by Runner now mark the Runner source as
+  `read_only: true` when no writer env is supplied. `config validate` no longer
+  reports `WRITEBACK_DISABLED` for handler-owned writeback paths.
+- Direct SQL review-mode proposals still surface `WRITEBACK_DISABLED` if the
+  source has no `write_url_env`, because Runner cannot apply those proposals
+  without a trusted writer connection.
+
+### Handler Docs
+
+- README and runner README now include a short "How An External Handler Works"
+  section: agent proposes, human approves outside MCP, Runner POSTs to your
+  endpoint, and your code writes in its own transaction.
+- Published docs/examples no longer include install-looking imports for a
+  separate handler package. Use `synapsor-runner handler template ...` or the
+  bundled `synapsor-handler.mjs` shim in the app-owned example.
+
+## 0.1.0-alpha.16
+
+### Review-Mode Bring-Up
+
+- Added `synapsor-runner up` as the local review-mode orientation command. It
+  validates the config/store, checks active store leases, summarizes
+  model-facing tools, identifies direct SQL versus app-owned executor writeback
+  paths, and prints the next smoke, approval, apply, replay, UI, and doctor
+  commands.
+- `up` is guidance-only by default. `up --serve` starts the standard MCP
+  Streamable HTTP server after the same validation and guidance.
+- `up --dry-run` gives the full checklist without starting a server.
+- `up --handler-check` or `up --with-handler` runs the redacted handler
+  env/reachability doctor path before serving.
+- The guided wizard now writes model-facing capability descriptions,
+  per-argument descriptions, returns hints, and defaults generated configs to
+  `result_format: 2`.
+- `result_format: 2` gives MCP clients a stable envelope with `ok`, `summary`,
+  `data`, `proposal`, `error`, `evidence`, `source_database_changed`, and
+  `_meta.canonical_capability`. Pass `--result-format v1` or
+  `"result_format": 1` only when an older client needs the legacy shape.
+- `tools list`, `tools list --aliases`, and
+  `mcp client-config --include-instructions` help users inspect exposed tools
+  and generate client snippets without source reading.
+
+### Handler Security
+
+- Generated handler templates, template-list output, app-owned writeback docs,
+  and examples now explicitly warn that the app handler owns the final business
+  write. Handlers must re-check tenant/scope, expected-version or conflict
+  guard, idempotency, allowed business action, transaction/rollback, and safe
+  error receipts before mutating application state.
+- The guided review-mode wizard can now write a starter handler template when
+  the app-owned HTTP or command handler path is selected.
+
 ## 0.1.0-alpha.15
 
 ### Handler Wording Clarification
@@ -23,10 +98,10 @@ for the Synapsor Cloud CLI.
 
 ### 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`.
+- Public docs now state that the handler helper is not 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
@@ -160,6 +235,9 @@ for the Synapsor Cloud CLI.
   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.
+- `synapsor-runner events webhook` pushes those local lifecycle events to a
+  local/dev/staging HTTP endpoint for review UIs or notifications without
+  polling. It is not a hosted central ledger.
 - 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.
@@ -209,13 +287,18 @@ changing. A stable `0.1.0` release should only be tagged after:
 For the local tarball before publish, run:
 
 ```bash
-./scripts/verify-packed-runner.sh
-./scripts/verify-packed-own-db.sh
+./scripts/verify-release-gate.sh
 ```
 
 After publishing an alpha, verify the public package from a clean temporary
 directory:
 
 ```bash
-./scripts/verify-published-alpha.sh 0.1.0-alpha.15
+VERIFY_PUBLISHED_ALPHA=1 ./scripts/verify-release-gate.sh 0.1.0-alpha.17
+```
+
+After publishing/promoting stable `latest`, verify the stable channel:
+
+```bash
+./scripts/verify-published-stable.sh 0.1.0
 ```

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.15
+npm install -g @synapsor/runner@0.1.0-alpha.17
 ```
 
 Do not rely on the untagged `latest` dist-tag until a stable release is
@@ -38,16 +38,52 @@ 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;
+- one-command review-mode `synapsor-runner up` is verified from a clean
+  directory and clearly prints model-facing tools, writeback path, handler
+  requirements, and next commands;
+- review-mode wizard output is verified for one read capability plus one
+  proposal capability;
+- handler template security warnings are verified in docs, CLI output, and
+  generated templates;
 - 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.
+- at least one external developer can follow the README without reading source;
+- there are no known docs/code mismatches around transport, credentials,
+  receipt tables, or handler expectations.
+
+## Stable Compatibility Promise
+
+After `0.1.0` is promoted to the untagged `latest` dist-tag, Synapsor Runner
+keeps these public surfaces compatible through the `0.1.x` line unless a
+release note marks a deprecation first:
+
+- the `synapsor-runner` binary name and README quickstart commands;
+- `synapsor.runner.json` schema version `1` for documented fields;
+- result envelope v2 for new configs, with the documented v1 opt-out;
+- stdio MCP and Streamable HTTP MCP command surfaces;
+- generated MCP client snippets for documented clients;
+- proposal, approval, guarded writeback, receipt, evidence, query-audit, and
+  replay inspection commands;
+- direct SQL writeback and app-owned executor contracts documented in README
+  and `docs/writeback-executors.md`.
+
+Stable does not promise production SLA, hosted Cloud features, compliance
+certification, physical Postgres/MySQL branching, generic SQL writeback,
+generic multi-row writes, or compatibility for undocumented local SQLite
+internals. Local store migrations may happen inside `0.1.x`, but documented CLI
+inspection commands should remain the supported way to read the store.
+
+Serious alpha users should pin an exact alpha version in package.json, CI, and
+MCP client snippets. Use `@alpha` only when intentionally testing the moving
+preview channel.
 
 ## Result Envelope Migration
 
-`result_format: 2` is opt-in during alpha migration:
+New `init` and `onboard db` configs default to:
 
 ```json
 {
@@ -55,32 +91,36 @@ A stable `0.1.0` release should only be tagged after:
 }
 ```
 
-or:
+Existing hand-written configs without `result_format` keep the legacy runtime
+default for compatibility. To force v2 or opt an older client back to v1, use:
 
 ```bash
 synapsor-runner mcp serve --result-format v2
 synapsor-runner mcp serve-streamable-http --result-format v2
+synapsor-runner mcp serve --result-format v1
 ```
 
-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.
+v2 makes `ok` the only required branch point for MCP client code. Do not remove
+the v1 escape hatch until the stable compatibility policy says legacy result
+shapes are no longer supported.
 
 ## 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
+./scripts/verify-release-gate.sh
 ```
 
 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
+VERIFY_PUBLISHED_ALPHA=1 ./scripts/verify-release-gate.sh 0.1.0-alpha.17
+```
+
+Before promoting `latest` to stable, bump and publish a non-prerelease version,
+then verify the stable channel from a clean temporary directory:
+
+```bash
+./scripts/verify-published-stable.sh 0.1.0
 ```

package/docs/result-envelope-v2.md

@@ -144,5 +144,8 @@ INTERNAL
 ```
 
 Current alpha implementation redacts raw connection and driver messages from v2
-MCP results. Legacy result format v1 remains the default for compatibility in
-this alpha.
+MCP results. New `init` and `onboard db` configs write `result_format: 2` by
+default. Existing hand-written configs without `result_format` keep the legacy
+runtime default for compatibility; pass `--result-format v2` when serving an
+older config to force the v2 envelope, or `--result-format v1` for an older
+client that still depends on the legacy shape.

package/docs/rfcs/002-app-owned-handler-helper.md

@@ -56,7 +56,7 @@ Receipt the handler must return (today's status vocabulary, kept):
 ## Helper API (TypeScript — first-party, since the runner is TS/Node)
 
 ```ts
-import { createWritebackHandler } from "@synapsor/handler";
+import { createWritebackHandler } from "../packages/handler/src/index.js";
 
 export const handler = createWritebackHandler({
   // 1. Authenticity: helper verifies bearer AND the HMAC signature for you.

package/docs/rfcs/003-integrator-feedback-teardown.md

@@ -15,7 +15,7 @@ The SQLite store is shared state, and the running server holds it open. Deleting
 Direct writeback does CREATE TABLE IF NOT EXISTS synapsor_writeback_receipts, which a least-privilege writer can't do (PG15+ no CREATE on public). Now documented, but doctor could detect it and print the exact GRANT/DDL (or a flag to pre-create). I had to invent the dedicated-schema trick myself.
 
 5. App-owned handlers re-implement security by hand.
-The executor contract is "match the example": you must re-check tenant, parse change_set, enforce the expected_version stale-row guard, and do idempotency yourself. It's easy to write an insecure handler (skip the version check, forget tenant scope). There's no handler SDK/helper and no request signing — the only auth is a bearer token, so the handler trusts the POST body's tenant/version. A @synapsor/handler helper (verify + parse + enforce guards, optional HMAC signature) would remove a whole class of mistakes.
+The executor contract is "match the example": you must re-check tenant, parse change_set, enforce the expected_version stale-row guard, and do idempotency yourself. It's easy to write an insecure handler (skip the version check, forget tenant scope). There's no published handler SDK/helper and no request signing — the only auth is a bearer token, so the handler trusts the POST body's tenant/version. A first-party handler helper (verify + parse + enforce guards, optional HMAC signature) would remove a whole class of mistakes.
 
 6. Versioning discipline.
 @alpha is a moving tag and behavior changed meaningfully across alpha.6→11 (transport, arg types string→number, credential resolution). I had to pin and bump six times. A stable channel + changelog + semver promise is table stakes before serious devs build on it.

package/docs/writeback-executors.md

@@ -115,6 +115,13 @@ The handler receives proposal fields, the exact patch, evidence metadata,
 guards, and an idempotency key. It does not receive arbitrary model SQL or DB
 credentials from Synapsor Runner.
 
+> **Important:** your app handler owns the final business write. Runner creates
+> the proposal and calls your handler only after approval, but your handler must
+> still enforce tenant/scope checks, expected-version or conflict guards,
+> idempotency keys, allowed business actions, transaction/rollback, and safe
+> error receipts. If you skip those checks, you can reintroduce cross-tenant
+> writes, lost updates, or duplicate writes. Keep handler credentials out of MCP.
+
 When `signing_secret_env` is set, Runner signs the exact JSON body with HMAC
 SHA-256 and sends:
 
@@ -220,6 +227,12 @@ npx -y -p @synapsor/runner@alpha synapsor-runner handler template command \
 The command receives the same structured JSON request on stdin and should print
 a JSON receipt body on stdout.
 
+> **Important:** command handlers have the same responsibility as HTTP
+> handlers. Re-check tenant/scope, expected-version or conflict guard,
+> idempotency, allowed business action, transaction/rollback, and safe error
+> receipt before mutating state. Otherwise the script can reintroduce
+> cross-tenant writes, lost updates, or duplicate writes.
+
 Use `examples/app-owned-writeback/command-handler.mjs` as a starting point when
 your safest apply path is an app script or job runner.
 

package/examples/app-owned-writeback/README.md

@@ -14,6 +14,13 @@ The model-facing MCP tool still only creates a proposal. Approval happens
 outside MCP. After approval, `synapsor-runner apply` sends a structured request
 to your handler, and the handler returns an execution receipt for replay.
 
+> **Important:** your app handler owns the final business write. Runner creates
+> the proposal and calls your handler only after approval, but your handler must
+> still enforce tenant/scope checks, expected-version or conflict guards,
+> idempotency keys, allowed business actions, transaction/rollback, and safe
+> error receipts. If you skip those checks, you can reintroduce cross-tenant
+> writes, lost updates, or duplicate writes. Keep handler credentials out of MCP.
+
 ## Config Snippet
 
 Add an executor and point one proposal capability at it:

package/examples/app-owned-writeback/command-handler.mjs

@@ -26,6 +26,15 @@ if (request.dry_run) {
 }
 
 /*
+ * IMPORTANT: your app handler owns the final business write.
+ * Runner creates the proposal and calls your handler only after approval,
+ * but your handler must still enforce tenant/scope, expected-version or
+ * conflict guard, idempotency key, allowed business action,
+ * transaction/rollback, and safe error receipt.
+ *
+ * If you skip those checks, you can reintroduce cross-tenant writes,
+ * lost updates, or duplicate writes. Keep handler credentials out of MCP.
+ *
  * Put your app-owned command transaction here.
  *
  * Examples:

package/examples/app-owned-writeback/node-fastify-handler.mjs

@@ -28,6 +28,15 @@ app.post("/synapsor/writeback", async (request, reply) => {
   }
 
   /*
+   * IMPORTANT: your app handler owns the final business write.
+   * Runner creates the proposal and calls your handler only after approval,
+   * but your handler must still enforce tenant/scope, expected-version or
+   * conflict guard, idempotency key, allowed business action,
+   * transaction/rollback, and safe error receipt.
+   *
+   * If you skip those checks, you can reintroduce cross-tenant writes,
+   * lost updates, or duplicate writes. Keep handler credentials out of MCP.
+   *
    * Put your app-owned transaction here.
    *
    * Examples:

package/examples/app-owned-writeback/python-fastapi-handler.py

@@ -36,6 +36,15 @@ def writeback(request: HandlerRequest, authorization: str | None = Header(defaul
             "details": {"dry_run": True},
         }
 
+    # IMPORTANT: your app handler owns the final business write.
+    # Runner creates the proposal and calls your handler only after approval,
+    # but your handler must still enforce tenant/scope, expected-version or
+    # conflict guard, idempotency key, allowed business action,
+    # transaction/rollback, and safe error receipt.
+    #
+    # If you skip those checks, you can reintroduce cross-tenant writes,
+    # lost updates, or duplicate writes. Keep handler credentials out of MCP.
+    #
     # Put your app-owned transaction here.
     #
     # Examples:

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

@@ -26,6 +26,13 @@ App-owned rich writeback:
 The model never receives `execute_sql`, approval tools, commit/apply tools,
 database URLs, or write credentials.
 
+> **Important:** the app handler owns the final business write. Runner creates
+> the proposal and calls the handler only after approval, but the handler must
+> still enforce tenant/scope checks, expected-version or conflict guards,
+> idempotency keys, allowed business actions, transaction/rollback, and safe
+> error receipts. If those checks are skipped, the app can reintroduce
+> cross-tenant writes, lost updates, or duplicate writes.
+
 ## Run
 
 From the repository root:

package/examples/mcp-postgres-billing-app-handler/app-handler.mjs

@@ -54,6 +54,12 @@ async function shutdown() {
 }
 
 async function applyAccountCredit(job, tx) {
+  /*
+   * IMPORTANT: this app handler owns the final business write.
+   * The helper has already verified auth, tenant scope, expected version,
+   * idempotency, and transaction wrapping before this function runs. Keep that
+   * pattern if you replace the helper or move this logic into your app.
+   */
   const amountCents = Number(job.patch.credit_requested_cents);
   const reason = String(job.patch.credit_reason || "approved account credit");
   if (!Number.isInteger(amountCents) || amountCents <= 0) {
@@ -113,13 +119,5 @@ function writeJson(response, statusCode, body) {
 }
 
 async function loadHandlerHelper() {
-  try {
-    return await import("@synapsor/handler");
-  } catch (workspaceError) {
-    try {
-      return await import(new URL("./synapsor-handler.mjs", import.meta.url));
-    } catch {
-      throw workspaceError;
-    }
-  }
+  return await import(new URL("./synapsor-handler.mjs", import.meta.url));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synapsor/runner",
-  "version": "0.1.0-alpha.15",
+  "version": "0.1.0-alpha.17",
   "description": "Commit-safe MCP runner for Postgres and MySQL agents",
   "license": "Apache-2.0",
   "type": "module",