@synapsor/runner 0.1.0-alpha.9 → 0.1.1

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

@@ -14,11 +14,11 @@ tools from your selections.
 
 ## Fast path
 
-Set one read-only database URL and run the wrapper from this repo:
+Set one read-only database URL and run the public guided path:
 
 ```bash
 export DATABASE_URL="<postgres-or-mysql-read-url>"
-./scripts/use-your-db.sh
+npx -y -p @synapsor/runner synapsor-runner start --from-env DATABASE_URL
 ```
 
 That command does the useful local mini-Synapsor path:
@@ -30,6 +30,8 @@ inspect your schema
 -> optionally choose proposal/writeback rules
 -> generate synapsor.runner.json
 -> preview MCP tools exposed to the model
+-> run a local smoke check of the tool boundary
+-> optionally write .synapsor/smoke-input.json for one real row
 -> print mcp serve and local UI commands
 ```
 
@@ -37,10 +39,23 @@ It does not print your database URL, put the URL in MCP client config, expose
 `execute_sql`, expose approval/commit tools, or give the model write
 credentials.
 
+`start --from-env` is the shortest public command for first-run onboarding.
+`onboard db --from-env DATABASE_URL` is the same explicit path if you prefer the
+older command name in scripts.
+
+During the wizard, provide the optional sample object id if you know one safe
+row in the selected table. Runner writes `./.synapsor/smoke-input.json` with
+that id and prints the exact `smoke call` command. If you skip it, use
+`--json '{"<lookup_arg>":"<real_id>"}'` when you are ready to test one real
+row.
+
 The rest of this page shows the same flow step by step using the public
 `synapsor-runner ...` CLI. From a source checkout, use `./bin/synapsor-runner ...` if the
 global binary is not linked yet.
 
+From a source checkout, `./scripts/use-your-db.sh` runs the same kind of
+guided flow plus local repository checks.
+
 ## 1. Put the read URL in an environment variable
 
 Do not pass connection strings on the command line.
@@ -81,7 +96,7 @@ other trusted database TLS setup.
 ## 2. Inspect metadata
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner inspect \
+npx -y -p @synapsor/runner synapsor-runner inspect \
   --engine auto \
   --from-env DATABASE_URL \
   --schema public
@@ -90,13 +105,13 @@ npx -y -p @synapsor/runner@alpha synapsor-runner inspect \
 For a disposable staging URL, this also works:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner inspect "$DATABASE_URL" --engine auto --schema public
+npx -y -p @synapsor/runner synapsor-runner inspect "$DATABASE_URL" --engine auto --schema public
 ```
 
 For automation:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner inspect \
+npx -y -p @synapsor/runner synapsor-runner inspect \
   --engine postgres \
   --from-env DATABASE_URL \
   --schema public \
@@ -113,9 +128,9 @@ to your staging table, primary key, tenant key, conflict column, visible fields,
 allowed write fields, and business limits.
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner recipes list
-npx -y -p @synapsor/runner@alpha synapsor-runner recipes show billing.late_fee_waiver
-npx -y -p @synapsor/runner@alpha synapsor-runner recipes init billing.late_fee_waiver --output synapsor.runner.json
+npx -y -p @synapsor/runner synapsor-runner recipes list
+npx -y -p @synapsor/runner synapsor-runner recipes show billing.late_fee_waiver
+npx -y -p @synapsor/runner synapsor-runner recipes init billing.late_fee_waiver --output synapsor.runner.json
 ```
 
 Use a recipe when the shape is close. Use the guided wizard or explicit flags
@@ -130,7 +145,7 @@ only the capabilities in your generated `synapsor.runner.json`.
 In an interactive terminal, run the guided wizard:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner init --from-env DATABASE_URL --mode read_only --wizard
+npx -y -p @synapsor/runner synapsor-runner init --from-env DATABASE_URL --mode read_only --wizard
 ```
 
 The generated context and capabilities are based on your selections. Synapsor
@@ -143,7 +158,12 @@ trusted context -> capability -> MCP tool
 
 You choose the source object, trusted tenant/principal bindings, namespace,
 object name, lookup argument, visible fields, proposal fields, guards, and
-approval role.
+approval role. You can also provide an optional real object id so Runner writes
+`./.synapsor/smoke-input.json` for the first local tool call. If the read URL
+env var and trusted tenant/principal env vars are already set, the wizard also
+attempts that smoke call immediately and stores the evidence/query audit in the
+local ledger. If not, it prints the exact smoke command to run after you set
+the env vars from `.env.example`.
 
 Start with `read_only` to prove safe database reads first. Use `--mode review`
 when you are ready to create proposal tools and guarded writeback setup.
@@ -157,7 +177,12 @@ The wizard:
 - asks which tenant/scope column and backend session env vars are trusted;
 - asks you to confirm primary key, conflict/version column, visible columns,
   mode, semantic capability names, and proposal patch mappings;
-- previews the MCP tools and what is not exposed;
+- 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, 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
   after final confirmation.
 
@@ -174,7 +199,7 @@ If you already know the reviewed table/action, generate config directly from
 metadata and explicit flags:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner init \
+npx -y -p @synapsor/runner synapsor-runner init \
   --from-env DATABASE_URL \
   --engine postgres \
   --schema public \
@@ -184,23 +209,54 @@ 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
+npx -y -p @synapsor/runner synapsor-runner init \
+  --from-env DATABASE_URL \
+  --engine postgres \
+  --schema public \
+  --table invoices \
+  --namespace billing \
+  --object-name invoice \
+  --mode review \
+  --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 \
+  --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.
+
 Or generate from a saved inspection snapshot without reconnecting:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner init \
+npx -y -p @synapsor/runner synapsor-runner init \
   --inspection-json schema-inspection.json \
   --table invoices \
   --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,
@@ -208,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
@@ -234,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",
@@ -243,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": {
@@ -261,7 +320,7 @@ contain database URLs or passwords.
 ## 6. Generate runner files
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner init \
+npx -y -p @synapsor/runner synapsor-runner init \
   --spec onboarding-selection.json \
   --non-interactive
 ```
@@ -281,20 +340,30 @@ files.
 Generate or refresh MCP client snippets later with:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner mcp config generic --config ./synapsor.runner.json --store ./.synapsor/local.db
-npx -y -p @synapsor/runner@alpha synapsor-runner mcp config claude-desktop --config ./synapsor.runner.json --store ./.synapsor/local.db
-npx -y -p @synapsor/runner@alpha synapsor-runner mcp config cursor --config ./synapsor.runner.json --store ./.synapsor/local.db
-npx -y -p @synapsor/runner@alpha synapsor-runner tools preview --config ./synapsor.runner.json --store ./.synapsor/local.db
+npx -y -p @synapsor/runner synapsor-runner mcp config generic --config ./synapsor.runner.json --store ./.synapsor/local.db
+npx -y -p @synapsor/runner synapsor-runner mcp config claude-desktop --config ./synapsor.runner.json --store ./.synapsor/local.db
+npx -y -p @synapsor/runner synapsor-runner mcp config cursor --config ./synapsor.runner.json --store ./.synapsor/local.db
+npx -y -p @synapsor/runner synapsor-runner tools preview --config ./synapsor.runner.json --store ./.synapsor/local.db
+```
+
+Call one generated tool locally before wiring an MCP client:
+
+```bash
+npx -y -p @synapsor/runner synapsor-runner smoke call --config ./synapsor.runner.json --store ./.synapsor/local.db
 ```
 
+`smoke call` uses the same runtime as the MCP server. It records evidence and
+query audit for read tools, or creates a proposal for proposal tools, then
+prints the commands to inspect evidence/proposals/replay from the local store.
+
 The snippets contain the local command and args. They must not contain database
 URLs, passwords, approval tools, commit tools, or write credentials.
 
 ## 7. Validate the config
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner config validate --config synapsor.runner.json
-npx -y -p @synapsor/runner@alpha synapsor-runner config show --config synapsor.runner.json --redacted
+npx -y -p @synapsor/runner synapsor-runner config validate --config synapsor.runner.json
+npx -y -p @synapsor/runner synapsor-runner config show --config synapsor.runner.json --redacted
 ```
 
 The config stores environment-variable names, not connection-string values.
@@ -302,7 +371,7 @@ The config stores environment-variable names, not connection-string values.
 Run doctor after setting the referenced environment variables:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner doctor --config synapsor.runner.json
+npx -y -p @synapsor/runner synapsor-runner doctor --config synapsor.runner.json
 ```
 
 Doctor validates config shape, trusted context env vars, source env vars,
@@ -310,7 +379,7 @@ read/write credential separation, table/column metadata when the read URL is
 available, and the semantic MCP tool boundary. Use JSON for automation:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner doctor --config synapsor.runner.json --json
+npx -y -p @synapsor/runner synapsor-runner doctor --config synapsor.runner.json --json
 ```
 
 ## 8. Serve semantic MCP tools
@@ -320,25 +389,41 @@ Use stdio when a local MCP client can launch Synapsor Runner:
 ```bash
 export SYNAPSOR_TENANT_ID="acme"
 export SYNAPSOR_PRINCIPAL="local_operator"
-npx -y -p @synapsor/runner@alpha synapsor-runner mcp serve --config ./synapsor.runner.json --store ./.synapsor/local.db
+npx -y -p @synapsor/runner synapsor-runner mcp serve --config ./synapsor.runner.json --store ./.synapsor/local.db
 ```
 
-Use HTTP when an app/server agent connects to a long-running Runner process:
+Use Streamable HTTP when an app/server agent connects through a standard HTTP
+MCP client:
 
 ```bash
 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 mcp serve-http \
+npx -y -p @synapsor/runner 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 synapsor-runner mcp serve-streamable-http \
   --config ./synapsor.runner.json \
   --store ./.synapsor/local.db \
   --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
 ```
 
-HTTP defaults to `127.0.0.1:8765` and requires bearer auth by default. Use
-private networking/TLS before exposing it beyond localhost. See
-[HTTP MCP](http-mcp.md).
+Streamable HTTP defaults to `127.0.0.1:8766` and requires bearer auth by
+default. Use private networking/TLS before exposing it beyond localhost. See
+[HTTP MCP](http-mcp.md). If you want the smaller JSON-RPC bridge instead, use
+`synapsor-runner mcp serve-http`.
 
 The model-facing MCP server exposes semantic tools such as:
 
@@ -357,10 +442,10 @@ tools, commit tools, database URLs, write credentials, or tenant authority.
 Proposal tools leave the source database unchanged. Review locally:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner proposals list --store ./.synapsor/local.db
-npx -y -p @synapsor/runner@alpha synapsor-runner proposals show wrp_123 --store ./.synapsor/local.db
-npx -y -p @synapsor/runner@alpha synapsor-runner proposals approve wrp_123 --store ./.synapsor/local.db --actor local_reviewer --yes
-npx -y -p @synapsor/runner@alpha synapsor-runner proposals writeback-job wrp_123 --store ./.synapsor/local.db --output job.json
+npx -y -p @synapsor/runner synapsor-runner proposals list --store ./.synapsor/local.db
+npx -y -p @synapsor/runner synapsor-runner proposals show wrp_123 --store ./.synapsor/local.db
+npx -y -p @synapsor/runner synapsor-runner proposals approve wrp_123 --store ./.synapsor/local.db --actor local_reviewer --yes
+npx -y -p @synapsor/runner synapsor-runner proposals writeback-job wrp_123 --store ./.synapsor/local.db --output job.json
 ```
 
 Apply through the trusted worker path with a separate writer credential:
@@ -368,7 +453,7 @@ Apply through the trusted worker path with a separate writer credential:
 ```bash
 export SYNAPSOR_DATABASE_WRITE_URL="<postgres-or-mysql-write-url>"
 SYNAPSOR_ENGINE=postgres \
-npx -y -p @synapsor/runner@alpha synapsor-runner apply --job job.json --config synapsor.runner.json --store ./.synapsor/local.db
+npx -y -p @synapsor/runner synapsor-runner apply --job job.json --config synapsor.runner.json --store ./.synapsor/local.db
 ```
 
 For `apply --job ... --config ...`, Runner reads the write credential from the
@@ -382,7 +467,7 @@ from environment variables, and the handler receives a structured proposal/job
 payload, not arbitrary model SQL:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner apply --proposal wrp_123 --config synapsor.runner.json --store ./.synapsor/local.db
+npx -y -p @synapsor/runner synapsor-runner apply --proposal wrp_123 --config synapsor.runner.json --store ./.synapsor/local.db
 ```
 
 See [Writeback Executors](writeback-executors.md).
@@ -390,8 +475,8 @@ See [Writeback Executors](writeback-executors.md).
 Replay afterward:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner replay show wrp_123 --store ./.synapsor/local.db
-npx -y -p @synapsor/runner@alpha synapsor-runner replay export wrp_123 --store ./.synapsor/local.db --output replay.json
+npx -y -p @synapsor/runner synapsor-runner replay show wrp_123 --store ./.synapsor/local.db
+npx -y -p @synapsor/runner synapsor-runner replay export wrp_123 --store ./.synapsor/local.db --output replay.json
 ```
 
 ## Boundary

package/docs/handler-helper.md

@@ -0,0 +1,228 @@
+# App-Owned Handler Helper
+
+Use the TypeScript handler helper when an approved Synapsor proposal should be
+executed by your application service, not by Runner's direct SQL writer.
+
+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;
+- updating multiple related rows inside your app transaction;
+- applying business rules that belong in your application service.
+
+The model-facing MCP tool still creates a proposal only. A human/operator
+approves outside MCP. After approval, Runner sends the structured writeback
+request to your handler.
+
+> **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:
+
+- TypeScript helper in `packages/handler`;
+- bearer token verification;
+- optional HMAC verification over the raw request body;
+- typed request parsing;
+- action dispatch;
+- idempotency receipt lookup;
+- transaction wrapper;
+- `SELECT ... FOR UPDATE` target-row lock;
+- tenant guard;
+- expected-version stale-row guard;
+- safe applied/conflict/failed receipts;
+- no raw driver errors in HTTP responses.
+
+Python helper is planned. For now, Python handlers should follow the documented
+request/receipt schema and the FastAPI template in `examples/app-owned-writeback`.
+
+## 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 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.
+
+## Schemas
+
+Published schemas:
+
+- `schemas/synapsor.app-handler-request.v1.json`
+- `schemas/synapsor.app-handler-receipt.v1.json`
+
+The helper accepts both the new `protocol_version: "1.0"` shape and the current
+Runner `schema_version: "synapsor.handler-writeback.v1"` request shape during
+the alpha migration.
+
+## TypeScript Usage 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 "../packages/handler/src/index.js";
+
+export const handler = createWritebackHandler({
+  tokenEnv: "SYNAPSOR_APP_HANDLER_TOKEN",
+  signingSecretEnv: "SYNAPSOR_APP_HANDLER_SIGNING_SECRET",
+  source: {
+    engine: "postgres",
+    writeUrlEnv: "SYNAPSOR_APP_WRITE_URL",
+    receiptTable: { schema: "synapsor", table: "handler_receipts" }
+  },
+  capabilities: {
+    "support.propose_plan_credit": async (job, tx) => {
+      const creditId = `CR-${job.proposalId.slice(-12)}`;
+
+      await tx.insert("credits", {
+        id: creditId,
+        tenant_id: job.tenantId,
+        invoice_id: job.objectId,
+        amount_cents: Number(job.patch.credit_requested_cents),
+        reason: String(job.patch.credit_reason),
+        created_by: job.principal
+      });
+
+      await tx.update("invoices", {
+        id: job.objectId,
+        tenant_id: job.tenantId
+      }, {
+        credited_cents:
+          Number(job.row.credited_cents ?? 0) +
+          Number(job.patch.credit_requested_cents)
+      });
+
+      return {
+        rowsAffected: 2,
+        effects: [{ type: "db.insert", table: "credits", id: creditId }]
+      };
+    }
+  }
+});
+```
+
+Mount the returned handler at your app route, for example
+`POST /synapsor/writeback`.
+
+The handler author writes only the business effect. The helper owns the safety
+loop around that effect.
+
+## What The Helper Enforces
+
+The helper checks these before your business function can mutate state:
+
+- the bearer token matches the configured environment variable;
+- the optional HMAC signature is valid and fresh;
+- the request protocol is supported;
+- the action maps to a configured capability function;
+- the target row exists inside the trusted tenant;
+- the row version still matches the proposal's expected version;
+- the idempotency key was not already applied.
+
+If the row is missing or belongs to another tenant, the helper returns:
+
+```json
+{
+  "status": "conflict",
+  "rows_affected": 0,
+  "source_database_mutated": false,
+  "safe_error_code": "ROW_NOT_FOUND_OR_WRONG_TENANT"
+}
+```
+
+If the row changed after proposal creation, the helper returns:
+
+```json
+{
+  "status": "conflict",
+  "rows_affected": 0,
+  "source_database_mutated": false,
+  "safe_error_code": "ROW_CHANGED_AFTER_PROPOSAL"
+}
+```
+
+If your business function throws, the helper rolls back the transaction and
+returns a safe failed receipt. Raw driver and exception text are not exposed to
+the caller.
+
+## Runner-Side Signing Config
+
+Configure the matching `http_handler` executor with the same signing-secret env
+name:
+
+```json
+{
+  "executors": {
+    "billing_handler": {
+      "type": "http_handler",
+      "url_env": "BILLING_WRITEBACK_URL",
+      "method": "POST",
+      "auth": {
+        "type": "bearer_env",
+        "token_env": "BILLING_WRITEBACK_TOKEN"
+      },
+      "signing_secret_env": "SYNAPSOR_APP_HANDLER_SIGNING_SECRET",
+      "timeout_ms": 5000
+    }
+  }
+}
+```
+
+When this field is set, Runner signs the exact request body and sends
+`X-Synapsor-Signature`, `X-Synapsor-Issued-At`,
+`X-Synapsor-Proposal-Id`, and `Idempotency-Key`. The helper verifies those
+headers before parsing or applying the writeback request.
+
+## Signing
+
+For loopback-only development, bearer auth may be enough. For any handler that
+is reachable outside the local process, enable HMAC:
+
+```ts
+createWritebackHandler({
+  tokenEnv: "SYNAPSOR_APP_HANDLER_TOKEN",
+  signingSecretEnv: "SYNAPSOR_APP_HANDLER_SIGNING_SECRET",
+  // ...
+});
+```
+
+Runner sends:
+
+```text
+Authorization: Bearer <token>
+X-Synapsor-Signature: sha256=<hmac>
+X-Synapsor-Issued-At: <iso timestamp>
+X-Synapsor-Proposal-Id: wrp_...
+Idempotency-Key: wrp_...
+```
+
+The HMAC is computed over the raw body. The helper enforces a short issued-at
+skew window.
+
+## Receipt Storage
+
+The helper's Postgres adapter stores idempotency receipts in a receipt table.
+Prefer a dedicated schema, for example:
+
+```sql
+CREATE SCHEMA IF NOT EXISTS synapsor;
+GRANT USAGE, CREATE ON SCHEMA synapsor TO app_writeback_user;
+```
+
+If your application already has a receipt/idempotency table, implement the
+`WritebackHandlerDatabase` interface and pass it as `database`.