@synapsor/runner 0.1.0-alpha.16 → 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/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

@@ -48,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:
 
@@ -57,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:
@@ -74,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,46 @@ 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
@@ -20,17 +60,18 @@ for the Synapsor Cloud CLI.
   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 --transport streamable-http` starts the standard MCP Streamable HTTP
-  server after the same validation and guidance.
-- `up --handler-check` runs the redacted handler env/reachability doctor path
-  before serving.
+- `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 can opt into
+  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`.
+  `_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.
@@ -57,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
@@ -194,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.
@@ -243,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.16
+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.16
+npm install -g @synapsor/runner@0.1.0-alpha.17
 ```
 
 Do not rely on the untagged `latest` dist-tag until a stable release is
@@ -55,13 +55,35 @@ A stable `0.1.0` release should only be tagged after:
 - 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
 {
@@ -69,32 +91,36 @@ preview channel.
 }
 ```
 
-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/examples/mcp-postgres-billing-app-handler/app-handler.mjs

@@ -119,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.16",
+  "version": "0.1.0-alpha.17",
   "description": "Commit-safe MCP runner for Postgres and MySQL agents",
   "license": "Apache-2.0",
   "type": "module",

package/schemas/onboarding-selection.v1.schema.json

@@ -22,6 +22,8 @@
     "conflict_column": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
     "namespace": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
     "object_name": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
+    "read_tool": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*(\\.[A-Za-z_][A-Za-z0-9_]*)+$" },
+    "proposal_tool": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*(\\.[A-Za-z_][A-Za-z0-9_]*)+$" },
     "inspect_tool_name": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*(\\.[A-Za-z_][A-Za-z0-9_]*)+$" },
     "proposal_tool_name": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*(\\.[A-Za-z_][A-Za-z0-9_]*)+$" },
     "inspect_description": { "type": "string", "minLength": 1 },

package/schemas/synapsor.runner.schema.json

@@ -99,6 +99,9 @@
         "write_url_env": {
           "$ref": "#/$defs/env_name"
         },
+        "read_only": {
+          "type": "boolean"
+        },
         "statement_timeout_ms": {
           "type": "integer",
           "minimum": 1