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

package/docs/release-notes.md

@@ -11,6 +11,55 @@ 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.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
+
+- 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
@@ -67,7 +116,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.
 
@@ -100,6 +150,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.
@@ -154,5 +209,5 @@ After publishing an alpha, verify the public package from a clean temporary
 directory:
 
 ```bash
-./scripts/verify-published-alpha.sh 0.1.0-alpha.11
+./scripts/verify-published-alpha.sh 0.1.0-alpha.14
 ```

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.14
+```
+
+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
+```

package/docs/result-envelope-v2.md

@@ -0,0 +1,148 @@
+# Result Envelope v2
+
+Result envelope v2 gives every model-facing MCP tool call one stable shape.
+Client code and agents branch only on `ok`.
+
+Enable it in config:
+
+```json
+{
+  "result_format": 2
+}
+```
+
+Or at serve time:
+
+```bash
+synapsor-runner mcp serve \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --result-format v2
+
+synapsor-runner mcp serve-streamable-http \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN \
+  --result-format v2
+```
+
+## Shape
+
+```json
+{
+  "ok": true,
+  "summary": "Read invoice INV-3001 through billing.inspect_invoice. Source database changed: no.",
+  "action": "billing.inspect_invoice",
+  "kind": "read",
+  "data": {},
+  "proposal": null,
+  "error": null,
+  "evidence": {
+    "bundle_id": "ev_...",
+    "note": "audit/replay handle; you do not need to act on it during this turn"
+  },
+  "source_database_changed": false,
+  "_meta": {
+    "tenant_id": "tenant_acme",
+    "principal": "demo-operator",
+    "provenance": "environment",
+    "canonical_capability": "billing.inspect_invoice"
+  }
+}
+```
+
+Rules:
+
+- `ok` is the only field callers need to branch on.
+- `summary` is always present and safe for an agent to read or echo.
+- On success, exactly one of `data` or `proposal` is non-null.
+- On failure, both `data` and `proposal` are null.
+- `source_database_changed` is always present.
+- `_meta.canonical_capability` is always the dotted Synapsor capability name,
+  even when the model sees an OpenAI-safe alias.
+
+## Proposal Result
+
+Proposal tools create reviewable changes. They do not commit to the source
+database.
+
+```json
+{
+  "ok": true,
+  "summary": "Created proposal wrp_123 for invoices INV-3001. Source database changed: no.",
+  "action": "billing.propose_late_fee_waiver",
+  "kind": "proposal",
+  "data": null,
+  "proposal": {
+    "id": "wrp_123",
+    "state": "review_required",
+    "target": "invoices:INV-3001",
+    "diff": {
+      "late_fee_cents": {
+        "before": 2500,
+        "proposed": 0
+      }
+    },
+    "approval_required": true,
+    "writeback": {
+      "mode": "direct_update",
+      "applied": false
+    },
+    "next": "A human must approve outside this model-facing tool surface; nothing is committed yet."
+  },
+  "error": null,
+  "evidence": {
+    "bundle_id": "ev_..."
+  },
+  "source_database_changed": false,
+  "_meta": {
+    "canonical_capability": "billing.propose_late_fee_waiver"
+  }
+}
+```
+
+For app-owned executors, `proposal.writeback.mode` is `app_handler`.
+
+## Error Result
+
+Model-facing errors are safe and stable. Raw driver details stay in local logs
+or ledger inspection, not in the MCP result.
+
+```json
+{
+  "ok": false,
+  "summary": "The database is temporarily unavailable. Retry later.",
+  "action": "billing.inspect_invoice",
+  "kind": "read",
+  "data": null,
+  "proposal": null,
+  "error": {
+    "code": "TEMPORARILY_UNAVAILABLE",
+    "message": "The database is temporarily unavailable. Retry later.",
+    "retryable": true
+  },
+  "evidence": null,
+  "source_database_changed": false,
+  "_meta": {
+    "canonical_capability": "billing.inspect_invoice"
+  }
+}
+```
+
+Safe error codes:
+
+```text
+NOT_FOUND_IN_TENANT
+INVALID_ARGUMENT
+POLICY_VIOLATION
+CAPABILITY_NOT_FOUND
+VERSION_CONFLICT
+MULTI_ROW_BLOCKED
+APPROVAL_REQUIRED
+TEMPORARILY_UNAVAILABLE
+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.

package/docs/rfcs/001-result-envelope-v2.md

@@ -0,0 +1,143 @@
+# Proposal: One Result Envelope for all Synapsor Runner tool results
+
+Status: draft for synapsor-runner (OSS)
+Author: external integrator feedback (built a full OpenAI Agents SDK + Postgres lab on alpha.6→alpha.11)
+Goal: make every tool result (read, proposal, error) share one shape that is both
+**machine-branchable** and **LLM-legible**, so agents behave reliably and client
+code stops special-casing.
+
+## Why
+
+Observed today (alpha.11), the shapes diverge:
+
+```jsonc
+// read success
+{ "status": "ok", "action": "billing.inspect_invoice", "data": { ... },
+  "evidence_bundle_id": "ev_…", "trusted_context": { ... }, "source_database_changed": false }
+
+// read not-found / tenant mismatch
+{ "ok": false, "code": "ROW_NOT_FOUND", "error": "The scoped capability read did not find exactly one authorized row." }
+
+// proposal success
+{ "status": "review_required", "proposal_id": "wrp_…", "diff": { "late_fee_cents": { "before": 2500, "proposed": 0 } },
+  "source_database_changed": false }
+```
+
+Three different top-level keys (`status` vs `ok`), two different success vocabularies,
+and raw infra strings leaking into `error`. An LLM driving these has to learn three
+branches; in my live tests the model **stalled / misreported** ("database access issue")
+when it hit the off-shape error path.
+
+## The envelope
+
+Every tool returns exactly this top-level shape:
+
+```jsonc
+{
+  "ok": true,                       // boolean — the ONLY field client code must branch on
+  "summary": "Invoice INV-3001: $100 + $25 late fee, status overdue.",  // one-line NL for the model to read/echo
+  "action": "billing.inspect_invoice",
+  "kind": "read",                   // read | proposal
+  "data": { ... } | null,           // read payload (the row), or null
+  "proposal": { ... } | null,       // proposal payload (see below), or null
+  "error": { ... } | null,          // populated iff ok=false (see below)
+  "evidence": { "bundle_id": "ev_…", "note": "audit handle; you do not need to act on it" } | null,
+  "source_database_changed": false, // ALWAYS present; true only after applied writeback
+  "_meta": { "tenant_id": "tenant_acme", "principal": "demo-operator", "provenance": "environment",
+             "canonical_capability": "billing.inspect_invoice" }
+}
+```
+
+Rules:
+- `ok` is the single branch point. No more `status` vs `ok`.
+- `summary` is mandatory and is the field the model is expected to read first and can
+  echo back to the user. Keep it short, factual, no internal ids unless useful.
+- Exactly one of `data` / `proposal` is non-null on success; both null on error.
+- `_meta` carries the trusted context and the canonical capability name (so OpenAI-safe
+  aliases like `billing__inspect_invoice` still expose their real name for reasoning/audit).
+
+### Proposal payload
+
+```jsonc
+"proposal": {
+  "id": "wrp_…",
+  "state": "review_required",      // review_required | approved | applied | conflict | rejected
+  "target": "invoices:INV-3001",
+  "diff": { "late_fee_cents": { "before": 2500, "proposed": 0 } },
+  "approval_required": true,
+  "writeback": { "mode": "direct_update" | "app_handler", "applied": false },
+  "next": "A human must approve outside this loop; nothing is committed yet."
+}
+```
+
+This part of today's output is already the best-designed — keep `diff.before/proposed`
+and `approval_required` verbatim, just move it under `proposal`.
+
+### Error payload (safe + stable)
+
+```jsonc
+"error": {
+  "code": "NOT_FOUND_IN_TENANT",   // STABLE enum (below) — never a raw infra string
+  "message": "No invoice INV-9999 is visible in your tenant.",  // safe, terse, actionable
+  "retryable": false
+}
+```
+
+Never surface raw driver text (`connect ECONNREFUSED 127.0.0.1:5433`) to the tool
+caller — log that to the local ledger only. Leaking it is a small info disclosure
+**and** degrades LLM behavior (the model parrots infra errors to the user).
+
+## Stable error code enum
+
+| code | meaning | retryable |
+|---|---|---|
+| `NOT_FOUND_IN_TENANT` | lookup found 0 authorized rows (missing OR wrong tenant — do not distinguish, it's a scoping signal) | no |
+| `INVALID_ARGUMENT` | arg failed schema/`numeric_bounds` | no |
+| `POLICY_VIOLATION` | request outside an allowed bound/transition | no |
+| `CAPABILITY_NOT_FOUND` | unknown tool name | no |
+| `VERSION_CONFLICT` | row changed since the agent saw it (stale-row guard) | no (re-inspect first) |
+| `MULTI_ROW_BLOCKED` | a write would touch ≠1 row | no |
+| `APPROVAL_REQUIRED` | attempted to apply without approval | no |
+| `TEMPORARILY_UNAVAILABLE` | DB/handler unreachable or timed out | yes |
+| `INTERNAL` | anything else (details only in ledger) | maybe |
+
+Keep this list small and documented; the model can be told "on `VERSION_CONFLICT`,
+re-inspect then re-propose" and act correctly.
+
+## Tool descriptions (ships with the envelope, same impact)
+
+The envelope fixes *results*; descriptions fix *whether the model calls the right
+tool at all*. Today they're generic ("Read public.outage_events through a reviewed
+Synapsor capability…"). Let capability config carry model-facing text:
+
+```jsonc
+{
+  "name": "support.inspect_outage",
+  "description": "Look up an outage event: its time window, affected plan, and the credit policy that governs waivers/credits. Use this before deciding whether a waiver or credit is justified.",
+  "args": {
+    "outage_id": { "type": "string", "description": "Outage/incident id, e.g. OUT-9001 (often referenced in the support ticket)." }
+  },
+  "returns_hint": "Returns the outage window, affected_plan, and credit_policy."
+}
+```
+
+In my live runs, the difference between a reliable agent and one that stalled before
+proposing was exactly this: whether the outage tool's description told the model it
+returns the *policy*. Surface `description` + per-arg `description` + `returns_hint`
+in `tools/list`. Fall back to today's auto-text only when the author omits them.
+
+## Migration
+
+- Add `"result_format": 2` to `synapsor.runner.json` (or a server flag
+  `--result-format v2`); default stays v1 for one minor cycle, then flips.
+- During transition the server can **dual-emit**: v2 envelope with a `legacy` mirror
+  of the old keys, so existing parsers don't break.
+- Document a one-line mapping: `status:"ok"` → `ok:true`; `status:"review_required"`
+  → `ok:true, proposal.state:"review_required"`; top-level `code/error` → `error.{code,message}`.
+
+## Acceptance
+
+- All of `tools/call` (read + proposal) and tool-level failures return the envelope.
+- `ok` alone is sufficient to branch in client code.
+- No raw driver/infra strings appear in any `error.message`.
+- `tools/list` exposes author-supplied `description` / arg `description` / `returns_hint`.

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

@@ -0,0 +1,161 @@
+# Proposal: An app-owned writeback handler helper (safe-by-default executors)
+
+Status: draft for synapsor-runner (OSS)
+Goal: make `http_handler` / `command_handler` executors **safe by default**. Today a
+handler author must re-implement tenant scoping, the stale-row (`expected_version`)
+guard, and idempotency by hand — "match the example." That's a security-critical loop
+to leave to copy-paste. Ship a tiny helper that enforces the guards and hands the
+developer only the business write.
+
+## The problem, concretely
+
+I wrote a working credit handler for the lab. To be correct it had to, in order:
+re-auth the bearer token, reject the wrong `action`, extract tenant/object/version
+from a loosely-typed `change_set` (with 3 fallback paths each, copied from the
+example), check idempotency, `SELECT … FOR UPDATE`, compare a normalized
+`expected_version`, INSERT + UPDATE, and format a receipt with the right status
+vocabulary. **Every one of those is a place to introduce a vulnerability** (skip the
+version check → lost-update; skip tenant → cross-tenant write; trust body tenant
+without signature → spoofing). Most integrators will get at least one wrong.
+
+## The contract (formalize what's currently implicit)
+
+Request the runner POSTs to an `http_handler` (make this a published, versioned schema):
+
+```jsonc
+{
+  "protocol_version": "1.0",
+  "proposal_id": "wrp_…",
+  "idempotency_key": "wrp_…:INV-3001",
+  "issued_at": "2026-06-28T…Z",
+  "signature": "sha256=…",            // NEW: HMAC over the raw body (see Security)
+  "change_set": {
+    "action": "support.propose_plan_credit",
+    "scope":   { "tenant_id": "tenant_acme", "object_id": "INV-3001" },
+    "principal": { "id": "human-reviewer" },
+    "target":  { "schema": "public", "table": "invoices", "primary_key": { "column": "id", "value": "INV-3001" } },
+    "patch":   { "credit_requested_cents": 1500, "credit_reason": "outage credit" },
+    "guards":  { "tenant": { "column": "tenant_id", "value": "tenant_acme" },
+                 "expected_version": { "column": "updated_at", "value": "2026-05-16T00:00:00Z" } }
+  }
+}
+```
+
+Receipt the handler must return (today's status vocabulary, kept):
+
+```jsonc
+{ "status": "applied" | "already_applied" | "conflict" | "failed",
+  "rows_affected": 2,
+  "source_database_mutated": true,
+  "previous_version": "2026-05-16T00:00:00Z",
+  "new_version": "2026-06-28T…Z",
+  "safe_error_code": "ROW_CHANGED_AFTER_PROPOSAL",   // on conflict/failed
+  "details": { "effects": [ { "type": "db.insert", "table": "credits", "id": "CR-…" } ] } }
+```
+
+## Helper API (TypeScript — first-party, since the runner is TS/Node)
+
+```ts
+import { createWritebackHandler } from "@synapsor/handler";
+
+export const handler = createWritebackHandler({
+  // 1. Authenticity: helper verifies bearer AND the HMAC signature for you.
+  tokenEnv: "SYNAPSOR_APP_HANDLER_TOKEN",
+  signingSecretEnv: "SYNAPSOR_APP_HANDLER_SIGNING_SECRET",   // optional but recommended
+
+  // 2. Bind one apply() per capability. The helper has ALREADY:
+  //    - verified auth + signature + protocol_version
+  //    - matched the action
+  //    - parsed scope/target/patch/guards into a typed `job`
+  //    - opened a transaction, taken `SELECT … FOR UPDATE` on the target row,
+  //      enforced tenant match + expected_version (stale-row), and short-circuited
+  //      idempotency via the receipts table.
+  //  You only write business effects with the provided tx; throw to roll back.
+  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,
+        customer_id: job.row.customer_id, amount_cents: job.patch.credit_requested_cents,
+        reason: job.patch.credit_reason, created_by: job.principal,
+      });
+      await tx.update("invoices", job.objectId, {
+        credited_cents: job.row.credited_cents + job.patch.credit_requested_cents,
+      });
+      return { effects: [{ type: "db.insert", table: "credits", id: creditId }] };
+    },
+  },
+
+  // 3. DB binding (helper owns the tx + FOR UPDATE + version compare + receipt write).
+  source: { engine: "postgres", writeUrlEnv: "SYNAPSOR_APP_WRITE_URL" },
+});
+// handler is a (req,res) you mount at POST /synapsor/writeback, or an express/fastify route.
+```
+
+The helper turns conflict/idempotency/auth into framework concerns. The author writes
+**only** the INSERT/UPDATE and returns `effects`; status/`rows_affected`/version
+bookkeeping/receipt shape are produced by the helper.
+
+## Helper API (Python reference — handlers are often the app, not Node)
+
+```python
+from synapsor_handler import writeback_handler, Job, Tx   # pip install synapsor-handler
+
+@writeback_handler(
+    token_env="SYNAPSOR_APP_HANDLER_TOKEN",
+    signing_secret_env="SYNAPSOR_APP_HANDLER_SIGNING_SECRET",
+    write_url_env="SYNAPSOR_APP_WRITE_URL",
+)
+def support_propose_plan_credit(job: Job, tx: Tx):
+    credit_id = f"CR-{job.proposal_id[-12:]}"
+    tx.insert("credits", id=credit_id, tenant_id=job.tenant_id, invoice_id=job.object_id,
+              customer_id=job.row["customer_id"], amount_cents=job.patch["credit_requested_cents"],
+              reason=job.patch["credit_reason"], created_by=job.principal)
+    tx.update("invoices", job.object_id,
+              credited_cents=job.row["credited_cents"] + job.patch["credit_requested_cents"])
+    return {"effects": [{"type": "db.insert", "table": "credits", "id": credit_id}]}
+
+# Mount as a FastAPI/Flask route:  app.post("/synapsor/writeback")(support_propose_plan_credit.asgi)
+```
+
+`Job` is fully typed/validated: `proposal_id`, `idempotency_key`, `tenant_id`,
+`object_id`, `principal`, `patch`, and `row` (the locked current row). `Tx` only
+exposes scoped `insert`/`update`/`query` against the configured write URL.
+
+## What the helper guarantees (so the author can't forget)
+
+1. **Authenticity** — bearer + HMAC signature over the raw body. Without signing,
+   a handler trusts body-supplied `tenant_id`; with it, spoofing a writeback requires
+   the secret, not just network reach.
+2. **Tenant scope** — the locked-row `SELECT` always includes `tenant_id = scope.tenant_id`.
+3. **Stale-row guard** — `expected_version` compared at second precision (matching the
+   runner's own `versionValuesMatch`); mismatch → `conflict`, auto-rollback.
+4. **Idempotency** — a receipts/dedup row keyed by `idempotency_key`; replay → `already_applied`, no double write.
+5. **Atomicity** — author effects + receipt commit in one tx; any throw rolls back and returns a safe `failed`.
+6. **Safe receipts** — never leaks raw driver errors; maps exceptions to `safe_error_code`.
+
+## Security notes
+
+- **Sign requests.** Add `signature = HMAC_SHA256(signing_secret, raw_body)` and a
+  short `issued_at` skew window. Document it as recommended for any handler not on loopback.
+- The handler's DB credential should still be least-privilege (in the lab: `synapsor_app`
+  = SELECT/UPDATE invoices + SELECT/INSERT credits, nothing else). The helper doesn't
+  replace DB perms; it complements them.
+- Receipts table/dedup store: the helper should create-or-require it and, on permission
+  error, print the exact `GRANT`/DDL (same gap as the direct-writeback receipts table).
+
+## Why this matters for adoption
+
+App-owned executors are the answer to "rich writes" (INSERT/multi-row/events) — the
+thing the runner deliberately won't do itself. But that answer is only safe if the
+handler is safe, and right now safety is the integrator's homework. A first-party
+helper makes the secure path the easy path, which is exactly the framing the whole
+product is built on: don't hand people a footgun, hand them a reviewed capability.
+
+## Acceptance
+
+- `createWritebackHandler` (TS) + `synapsor_handler` (Python) enforce auth, signature,
+  tenant, version, idempotency, atomicity with no author code.
+- A handler written with the helper passes the same conflict/idempotency/tenant tests
+  the runner ships for direct writeback.
+- Request/receipt schemas are published and versioned (`protocol_version`).