@synapsor/runner 0.1.15 → 1.0.0

package/docs/README.md

@@ -41,6 +41,10 @@ no-database demo, wire your database, then read deeper concepts.
 - [Capability Authoring](capability-authoring.md): define read/proposal
   capabilities, model-facing descriptions, result envelopes, trusted context,
   and writeback guards.
+- [DSL Reference](dsl-reference.md): complete supported grammar, clause order,
+  compiled meaning, and constraints.
+- [Runner Config Reference](runner-config-reference.md): every public wiring
+  key, default, environment binding, and path-resolution rule.
 - [Recipes](recipes.md): starter business-capability templates.
 - [JSON Schema](../schemas/synapsor.runner.schema.json): editor validation for
   `synapsor.runner.json`.

package/docs/capability-authoring.md

@@ -12,6 +12,11 @@ Use `.synapsor.sql` as the preferred DSL source extension because editors can
 provide generic SQL highlighting. Legacy `.synapsor` files remain supported;
 the suffix does not change DSL semantics or generated canonical JSON.
 
+For exact clause grammar, ordering, constraints, fixed-string patches, and the
+primary-key-only lookup rule, see the [DSL Reference](dsl-reference.md). For all
+local wiring keys and path rules, see the
+[Runner Config Reference](runner-config-reference.md).
+
 Use `synapsor.runner.json` for local wiring: database env var names, SQLite
 store path, MCP transport settings, and local development flags. The model sees
 semantic capabilities such as `billing.inspect_invoice`, not raw SQL, table

package/docs/conformance.md

@@ -26,10 +26,15 @@ Current fixture groups:
 - `proposal-capability`
 - `kept-out-fields`
 - `manual-approval`
+- `auto-approval`
+- `aggregate-policy-limits`
+- `numeric-bounds`
 
 The fixture set is intentionally small in 0.1. It covers the runner-supported
 semantic surface first: trusted context, scoped reads, evidence handles,
 proposal boundaries, kept-out fields, manual approval, and replay envelopes.
+The aggregate-policy fixture additionally proves that reviewed daily ceilings
+fall back to human review atomically and record the limit that tripped.
 
 Additional 0.1 parity coverage currently lives in tests and verification
 scripts rather than separate `cloud-push/` or `dsl-json-parity/` conformance
@@ -38,6 +43,9 @@ fixture directories:
 - `docs/dsl-json-parity.md`, DSL/spec tests, and the
   `numeric-bounds-transition` C++ export fixture cover richer DSL/JSON parity
   fields such as `returns_hint`, numeric bounds, and transition guards.
+- `packages/dsl/fixtures/invalid/non-primary-lookup.synapsor.sql` proves the
+  DSL rejects a lookup meaning that canonical spec 0.1 cannot represent,
+  instead of silently rewriting it to primary-key access.
 - The main Synapsor repo script `scripts/verify_contract_cloud_push.sh`
   verifies real Cloud push, retrieval, idempotent versioning, unauthorized
   rejection, and runner-bundle download against a live local control-plane.

package/docs/current-scope.md

@@ -2,7 +2,7 @@
 
 The canonical scope page is [Current Limitations](limitations.md).
 
-Current `0.1.x` scope:
+Current `1.0` scope:
 
 - local semantic MCP tools for Postgres/MySQL-backed business actions;
 - schema inspection and guided config generation;
@@ -13,7 +13,7 @@ Current `0.1.x` scope:
   business transactions;
 - stdio MCP, Streamable HTTP MCP, and a small JSON-RPC bridge.
 
-Stable `0.1.x` compatibility covers the documented `synapsor-runner` binary,
+Stable `1.x` compatibility 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.

package/docs/doctor.md

@@ -63,9 +63,9 @@ The target-table probe uses fixed schema/table/column identifiers from the
 reviewed config. It does not accept model SQL, user SQL, arbitrary table names,
 or arbitrary column names. It runs inside a transaction and rolls back.
 
-The receipt-table probe can create `synapsor_writeback_receipts` if the writer
-has permission. If your policy does not allow Runner to create tables in the
-application schema, pre-create the table and grant access:
+An administrator must pre-create `synapsor_writeback_receipts` and grant the
+steady-state writer access. The doctor probe does not execute DDL or require
+schema `CREATE`:
 
 ```bash
 synapsor-runner writeback migration --engine postgres --schema synapsor

package/docs/dsl-reference.md

@@ -0,0 +1,215 @@
+# Synapsor DSL Reference
+
+The Synapsor DSL is a reviewable SQL-like authoring format that compiles to the
+canonical `@synapsor/spec` contract. Prefer `.synapsor.sql`; legacy `.synapsor`
+files remain valid. The filename does not change semantics.
+
+Validate and compile with strict safety warnings enabled:
+
+```bash
+synapsor-runner dsl validate ./contract.synapsor.sql --strict
+synapsor-runner dsl compile ./contract.synapsor.sql \
+  --out ./synapsor.contract.json --strict
+```
+
+Keywords are case-insensitive. Blocks start with `CREATE ...` and end with
+`END` or `END;`. Lines may end in semicolons. `--` starts a line comment.
+Unsupported clauses fail explicitly.
+
+## Agent context
+
+```sql
+CREATE AGENT CONTEXT local_operator
+  BIND tenant_id FROM ENVIRONMENT SYNAPSOR_TENANT_ID REQUIRED
+  BIND principal FROM ENVIRONMENT SYNAPSOR_PRINCIPAL REQUIRED
+  TENANT BINDING tenant_id
+  PRINCIPAL BINDING principal
+END
+```
+
+| Clause | Meaning |
+| --- | --- |
+| `BIND name FROM source key [REQUIRED]` | Defines trusted context. Sources: `SESSION`, `ENV`/`ENVIRONMENT`, `CLOUD_SESSION`, `STATIC_DEV`, `HTTP_CLAIM`. Model tool arguments cannot set these bindings. |
+| `TENANT BINDING name` | Selects the binding used for tenant scope. Defaults to a binding named `tenant_id`. |
+| `PRINCIPAL BINDING name` | Selects the actor binding. Defaults to a binding named `principal`. |
+
+At least one `BIND` is required. The selected tenant/principal bindings must be
+provided by the trusted runtime environment, not by the model.
+
+## Capability identity and target
+
+```sql
+CREATE CAPABILITY billing.inspect_invoice
+  DESCRIPTION 'Inspect one invoice in the trusted tenant.'
+  RETURNS HINT 'Returns reviewed fields and an evidence handle.'
+  USING CONTEXT local_operator
+  SOURCE billing_postgres
+  ON public.invoices
+  PRIMARY KEY id
+  TENANT KEY tenant_id
+  CONFLICT GUARD updated_at
+  ...
+END
+```
+
+| Clause | Requirement and compiled meaning |
+| --- | --- |
+| `CREATE [AGENT] CAPABILITY namespace.name` | Starts a qualified capability. |
+| `DESCRIPTION 'text'` | Model-facing `tools/list` description. Recommended for every tool and required by strict review for proposal quality. |
+| `RETURNS HINT 'text'` | Model-facing result guidance. |
+| `USING CONTEXT name` | Required. References an agent context. |
+| `SOURCE name` | Source key that must match `synapsor.runner.json.sources`. |
+| `ON schema.table` | Required fixed target. Table/schema are never model inputs. |
+| `PRIMARY KEY column` | Fixed single-row target key. Defaults to `id` in DSL 0.1. Declare it explicitly. |
+| `TENANT KEY column` | Required in DSL 0.1. Adds trusted tenant scope to every read/write. |
+| `CONFLICT GUARD column` | Captures the row-version value for exact guarded writeback. Prefer a monotonic version or native-precision timestamp. |
+
+## Arguments and lookup
+
+```sql
+  LOOKUP invoice_id BY id
+  ARG invoice_id STRING REQUIRED MAX LENGTH 128 DESCRIPTION 'Invoice id.'
+  ARG amount_cents NUMBER REQUIRED MIN 1 MAX 2500 DESCRIPTION 'Amount in cents.'
+  ARG confirmed BOOLEAN REQUIRED
+```
+
+Argument types are `STRING`/`TEXT`, `NUMBER`, and `BOOLEAN`/`BOOL`.
+
+- `REQUIRED` makes the model-facing argument mandatory.
+- `DESCRIPTION 'text'` documents the argument in MCP `tools/list`.
+- `MIN n` and `MAX n` are numeric bounds for `NUMBER`.
+- `MAX LENGTH n` bounds `STRING`/`TEXT`. Legacy text `MAX n` remains accepted.
+- `LOOKUP arg BY column` binds one argument to the target row lookup.
+
+In spec 0.1, lookup is primary-key-only. The `BY` column must equal the declared
+`PRIMARY KEY`. A different column fails with `LOOKUP_COLUMN_UNSUPPORTED`; Runner
+never silently rewrites it. List/filter queries require a reviewed view or a
+different capability design.
+
+## Read surface and evidence
+
+```sql
+  ALLOW READ id, tenant_id, status, amount_cents, updated_at
+  KEEP OUT card_token, private_notes
+  REQUIRE EVIDENCE
+  MAX ROWS 1
+```
+
+`ALLOW READ` is required and becomes the visible-field allowlist. `KEEP OUT`
+records fields that must remain outside the model/evidence surface. Keep-out
+fields must not also be visible. `REQUIRE EVIDENCE` records the scoped read and
+query audit. `MAX ROWS n` bounds the result; local 0.1 capabilities are designed
+around one primary-key row.
+
+## Proposal and patch
+
+Read capabilities end after the read clauses. A proposal capability adds:
+
+```sql
+  PROPOSE ACTION waive_late_fee
+  ALLOW WRITE late_fee_cents, waiver_reason
+  PATCH late_fee_cents = 0
+  PATCH waiver_reason = ARG reason
+  PATCH status = 'approved'
+  PATCH reviewed = TRUE
+  PATCH obsolete_note = NULL
+```
+
+`PROPOSE ACTION` must precede proposal-only clauses. `ALLOW WRITE` is the exact
+patch-column allowlist. Each `PATCH` uses one of:
+
+- `ARG name`: value comes from a validated model argument;
+- a quoted fixed string;
+- a fixed number;
+- `TRUE`, `FALSE`, or `NULL`.
+
+Fixed strings such as `PATCH status = 'approved'` are supported. The patch is
+saved as a proposal; it is not executed by the model-facing tool.
+
+## Bounds and transitions
+
+```sql
+  BOUND amount_cents 1..2500
+  BOUND discount_cents ..500
+  BOUND score 1..
+  TRANSITION status ALLOW reported -> approved|rejected
+  TRANSITION status FROM current_status ALLOW open -> closed, held -> open
+```
+
+`BOUND column min..max` applies to a patched numeric column. Either side may be
+open, but not both. Strict mode warns when a numeric argument reaches a patch
+without argument bounds or a patch bound.
+
+`TRANSITION patched_column [FROM source_column] ALLOW from -> to|to, ...`
+allowlists state changes. Without `FROM`, the current value is read from the
+patched column. Values may be identifiers or quoted strings.
+
+## Approval and writeback
+
+```sql
+  APPROVAL ROLE billing_lead
+  AUTO APPROVE WHEN amount_cents <= 2500
+  LIMIT 20 PER DAY
+  LIMIT TOTAL 100000 PER DAY
+  WRITEBACK DIRECT SQL
+```
+
+`APPROVAL ROLE role` records the required local reviewer role. Local OSS
+approval identity is operator-provided; enterprise identity/RBAC belongs to the
+Cloud boundary.
+
+`AUTO APPROVE WHEN field <= non_negative_integer` is supported only for a
+numeric patched field and must follow `APPROVAL ROLE`. Its maximum cannot exceed
+the field's `BOUND`. Policy approval still does not apply the write.
+
+Aggregate limits follow the auto-approval clause:
+
+```sql
+LIMIT 20 PER DAY
+LIMIT TOTAL 100000 PER DAY
+```
+
+`LIMIT n PER DAY` caps policy approvals for the trusted tenant and policy in
+the UTC calendar day. `LIMIT TOTAL n PER DAY` sums the policy's numeric patch
+field over the same scope. Use `PER OBJECT DAY` instead of `PER DAY` to scope a
+limit to one trusted tenant, policy, and business object. The check and approval
+are one atomic ledger transaction. When any ceiling would be exceeded, Runner
+leaves the proposal in `pending_review` and records
+`policy_auto_approval_deferred` with observed, proposed, and projected values.
+It does not reject or auto-apply the proposal.
+
+Writeback forms:
+
+| Clause | Meaning |
+| --- | --- |
+| `WRITEBACK DIRECT SQL` | Runner performs one guarded single-row update after approval. |
+| `WRITEBACK APP HANDLER EXECUTOR name` | Runner calls a configured app-owned executor after approval. URL/token wiring stays outside the contract. |
+| `WRITEBACK CLOUD WORKER` | Delegates approved execution to Cloud worker infrastructure. |
+| `WRITEBACK NONE` | Proposal-only; local apply is intentionally unavailable. |
+
+## Workflow declarations
+
+```sql
+CREATE AGENT WORKFLOW support.refund_review
+  USING CONTEXT local_operator
+  ALLOW CAPABILITY support.inspect_order
+  ALLOW CAPABILITY support.propose_refund
+  REQUIRE EVIDENCE
+  APPROVAL REQUIRED ROLE support_lead
+  CHECKPOINT PROPOSAL ONLY
+END
+```
+
+`USING CONTEXT` and at least one `ALLOW CAPABILITY` are required. Optional
+clauses are `REQUIRE EVIDENCE`, `APPROVAL REQUIRED ROLE role`, and `CHECKPOINT
+NONE|EVERY STEP|PROPOSAL ONLY`. Contracts can declare workflows; Runner 0.1 does
+not execute arbitrary Cloud workflow DAGs, settlement, branching, or auto-merge.
+
+## Unsupported syntax
+
+Unknown clauses fail instead of being ignored. Cloud-generated concepts such as
+`ROOT EXTERNAL`, `JOIN EXTERNAL`, `RETURN ANSWER WITH CITATIONS`, `AUTO BRANCH`,
+and `AUTO MERGE` are not local DSL 0.1 clauses.
+
+The canonical JSON output, not parser implementation details, is the portable
+contract. Validate generated JSON with `synapsor-runner contract validate`.

package/docs/http-mcp.md

@@ -72,6 +72,47 @@ sessions: in-memory
 
 Use `/mcp` as the MCP endpoint. Health is available at `/healthz`.
 
+## TLS And mTLS
+
+For a non-local long-running service, terminate TLS at a trusted proxy or start
+Runner with env-backed PEM material:
+
+```bash
+export SYNAPSOR_TLS_CERT_PEM="$(cat ./server.crt)"
+export SYNAPSOR_TLS_KEY_PEM="$(cat ./server.key)"
+
+synapsor-runner mcp serve-streamable-http \
+  --host 0.0.0.0 \
+  --port 8766 \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN \
+  --tls-cert-env SYNAPSOR_TLS_CERT_PEM \
+  --tls-key-env SYNAPSOR_TLS_KEY_PEM
+```
+
+To require client certificates:
+
+```bash
+export SYNAPSOR_TLS_CA_PEM="$(cat ./client-ca.crt)"
+
+synapsor-runner mcp serve-streamable-http \
+  --host 0.0.0.0 \
+  --port 8766 \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN \
+  --tls-cert-env SYNAPSOR_TLS_CERT_PEM \
+  --tls-key-env SYNAPSOR_TLS_KEY_PEM \
+  --tls-ca-env SYNAPSOR_TLS_CA_PEM \
+  --require-client-cert
+```
+
+The CLI reads PEM contents from environment variables and never prints them.
+Runner-owned mTLS currently protects the Streamable HTTP MCP boundary. For
+app-owned `http_handler` executors, terminate mTLS in your service mesh/proxy
+or handler process and keep bearer/signature checks enabled in the handler.
+
 ## Start The JSON-RPC Bridge
 
 ```bash

package/docs/limitations.md

@@ -6,7 +6,8 @@ Synapsor Runner is intentionally narrow in the current alpha.
 
 - Stdio MCP server for semantic database capabilities.
 - Local read and proposal tools.
-- Local SQLite evidence/proposal/query-audit/replay store.
+- Local SQLite evidence/proposal/query-audit/replay store by default.
+- Optional shared Postgres proposal/evidence/replay runtime store for MCP serving.
 - Human approval through CLI commands.
 - Public protocol objects:
   - `synapsor.change-set.v1`

package/docs/oss-vs-cloud.md

@@ -6,7 +6,8 @@ contract, but they solve different operational problems.
 Runner is the open-source runtime that stays next to your application and
 database. It serves reviewed MCP tools, binds trusted context, stores local
 evidence and proposals, keeps approval outside MCP, applies or routes approved
-writeback, and records receipts and replay in a local SQLite ledger.
+writeback, and records receipts and replay in the default local SQLite ledger
+or an opt-in shared Postgres runtime store.
 
 Cloud is the team control plane. It stores versioned contracts, produces
 downloadable Runner bundles, and provides shared activity, evidence, approval,
@@ -18,7 +19,7 @@ and investigation surfaces for enabled design-partner deployments.
 | Contract source | Local files reviewed in Git | Shared registry with immutable versions and digests |
 | Trusted context | Local environment/session bindings | Registered bindings plus deployment-specific Cloud session context |
 | Capabilities | Local semantic MCP tools | Registry, version history, and capability inspection |
-| Evidence and replay | Local SQLite ledger | Shared activity and evidence surfaces where enabled |
+| Evidence and replay | Local SQLite ledger by default; optional shared Postgres runtime store | Shared activity and evidence surfaces where enabled |
 | Approval | Local CLI or localhost UI | Team approval surfaces where enabled |
 | Writeback | Guarded one-row update or app-owned executor | Cloud-linked jobs with local execution; managed production orchestration is future work |
 | MCP risk audit | Static local audit | Organization-wide continuous audit is future work |

package/docs/production.md

@@ -56,8 +56,9 @@ Write credential for direct `sql_update`:
 
 - can update only the allowed business columns;
 - cannot modify primary-key or tenant columns;
-- can create/write the `synapsor_writeback_receipts` table, or the table is
-  pre-created and granted by an administrator;
+- can `SELECT`/`INSERT`/`UPDATE` the administrator-created
+  `synapsor_writeback_receipts` table;
+- does not need schema `CREATE` during doctor or apply;
 - is never exposed to MCP clients.
 
 Example config:
@@ -81,7 +82,7 @@ worker flows that do not pass a local config.
 ## Receipt Table
 
 Direct SQL writeback stores idempotency receipts in the source database. Runner
-creates this table if allowed:
+expects an administrator to create this table before steady-state operation:
 
 ```sql
 CREATE TABLE IF NOT EXISTS synapsor_writeback_receipts (...);
@@ -97,10 +98,9 @@ synapsor-runner doctor --config synapsor.runner.json --check-writeback
 
 For MySQL, replace `postgres` with `mysql`.
 
-If the writer should not create application-schema tables, pre-create the
-receipt table with an administrator role, grant only the needed receipt-table
-permissions to the writer, or use an app-owned executor that stores receipts in
-your application boundary.
+Grant only receipt-table `SELECT`/`INSERT`/`UPDATE` and schema usage to the
+writer; schema `CREATE` is not required by doctor or apply. Use an app-owned
+executor when receipt storage belongs inside your application boundary.
 
 ## Direct Writeback Vs App-Owned Executor
 
@@ -150,12 +150,163 @@ Useful commands:
 ```bash
 synapsor-runner store stats --store ./.synapsor/local.db
 synapsor-runner events tail --store ./.synapsor/local.db --follow
+synapsor-runner metrics show --store ./.synapsor/local.db
 synapsor-runner store prune --store ./.synapsor/local.db --older-than 30d --dry-run
 synapsor-runner store vacuum --store ./.synapsor/local.db
 ```
 
 Details: [Store Lifecycle](store-lifecycle.md).
 
+## Shared Postgres Ledger Setup
+
+The default runtime ledger is SQLite. For shared deployments, Runner now ships a
+Postgres ledger setup surface that creates the schema used for shared audit
+entries, proposal locks, and worker leases:
+
+```bash
+export SYNAPSOR_LEDGER_DATABASE_URL="postgresql://ledger_writer:..."
+
+synapsor-runner store shared-postgres migration --schema synapsor_runner
+synapsor-runner store shared-postgres apply-migration \
+  --url-env SYNAPSOR_LEDGER_DATABASE_URL \
+  --schema synapsor_runner \
+  --yes
+synapsor-runner store shared-postgres status \
+  --url-env SYNAPSOR_LEDGER_DATABASE_URL \
+  --schema synapsor_runner
+synapsor-runner store shared-postgres sync \
+  --store ./.synapsor/local.db \
+  --url-env SYNAPSOR_LEDGER_DATABASE_URL \
+  --schema synapsor_runner \
+  --yes
+synapsor-runner store shared-postgres restore \
+  --store ./.synapsor/restored.db \
+  --url-env SYNAPSOR_LEDGER_DATABASE_URL \
+  --schema synapsor_runner \
+  --yes
+```
+
+These commands do not print the database URL. `sync` upserts a stable snapshot
+of the local proposal/evidence/replay ledger into Postgres for shared audit,
+backup, and retention. `restore` rebuilds a local SQLite store from those
+shared ledger entries for recovery or offline investigation.
+
+Runner supports two shared Postgres modes:
+
+- `mirror`: bounded CLI mutations restore from Postgres into local SQLite,
+  mutate locally, then sync back under a schema-scoped advisory lock.
+- `runtime_store`: MCP serving uses Postgres as the primary
+  proposal/evidence/replay store instead of opening a local SQLite store.
+
+Local SQLite remains the default. Use `runtime_store` when several MCP sessions
+or runner processes need to share proposal/evidence/replay state through one
+ledger database. Use `mirror` when you want bounded operator handoff while still
+running CLI mutations against a local SQLite file.
+
+Mirror mode config:
+
+```json
+{
+  "storage": {
+    "sqlite_path": "./.synapsor/local.db",
+    "shared_postgres": {
+      "mode": "mirror",
+      "url_env": "SYNAPSOR_LEDGER_DATABASE_URL",
+      "schema": "synapsor_runner",
+      "lock_timeout_ms": 10000
+    }
+  }
+}
+```
+
+```bash
+export SYNAPSOR_LEDGER_DATABASE_URL="postgresql://ledger_writer:..."
+
+synapsor-runner doctor \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+
+synapsor-runner propose support.propose_plan_credit --sample \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+
+synapsor-runner proposals approve latest --yes \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+
+synapsor-runner apply --all-approved --yes \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+```
+
+When `storage.shared_postgres.mode` is `mirror`, `doctor` checks that the
+ledger URL environment variable is present and that `ledger_entries`,
+`proposal_locks`, and `worker_leases` exist in the configured schema. It reports
+environment variable names and table readiness only; it does not print database
+URLs or initialize the schema.
+
+Mirror mode restores the Postgres ledger into the local store before a mutation
+and syncs the local store back after the command, including failure events when
+they were recorded locally. While it runs, Runner holds a schema-scoped
+Postgres advisory lock so concurrent mirror-mode operators do not restore,
+mutate, and sync over one another. The default lock wait is 10 seconds; tune it
+with `--shared-ledger-lock-timeout-ms` or
+`SYNAPSOR_SHARED_LEDGER_LOCK_TIMEOUT_MS`.
+
+Mirror mode is explicit because the local SQLite store still executes the CLI
+mutation. It is useful for bounded operator workflows and finite workers
+(`worker run --once` or `--drain`); use `runtime_store` for long-lived MCP
+serving and shared worker loops that need one proposal/evidence/replay ledger.
+
+Runtime-store mode config:
+
+```json
+{
+  "storage": {
+    "shared_postgres": {
+      "mode": "runtime_store",
+      "url_env": "SYNAPSOR_LEDGER_DATABASE_URL",
+      "schema": "synapsor_runner",
+      "lock_timeout_ms": 10000
+    }
+  }
+}
+```
+
+When MCP serving starts in `runtime_store` mode, Runner opens the Postgres URL
+from `url_env`, auto-runs the shared-ledger migration, and serializes runtime
+mutations with a transaction-scoped advisory lock. The MCP tools still expose no
+database URLs or write credentials to the model.
+
+`runtime_store` covers MCP serving, CLI approval/apply, and supervised worker
+runs. For CLI mutations, Runner restores the shared ledger into a temporary
+local store while holding the Postgres advisory lock, runs the existing local
+mutation, then syncs the resulting ledger entries back to Postgres. A
+long-running `worker run --yes` repeats bounded drain cycles under that lock
+and sleeps between idle polls, so multiple workers can share one Postgres ledger
+without holding the lock while idle.
+
+For unattended policy-approved queues, declare reviewed aggregate `LIMIT`
+clauses first, then use the explicit batch command:
+
+```bash
+synapsor-runner apply --all-approved --yes \
+  --config ./synapsor.runner.json --store ./.synapsor/local.db \
+  --capability support.propose_plan_credit --tenant acme --max 20
+```
+
+Each proposal is independent: a stale-row conflict does not abort later jobs.
+The final summary reports applied, conflict, and skipped IDs. Re-running is
+idempotent through durable receipts. Do not schedule batch apply for a policy
+that has no reviewed aggregate limits.
+
+Runner writes newline-delimited JSON events to stderr for model-facing tool
+rejections, operator decisions, and terminal writeback outcomes. These events
+contain safe codes and identifiers, never tool arguments, row values, database
+URLs, tokens, private keys, or free-form driver errors. Prometheus/OpenMetrics
+counters are available with `metrics show` and are grouped by trusted tenant
+and reviewed capability.
+
 ## Restart And Recovery
 
 Runner stores proposal/evidence/replay state before writeback.
@@ -183,7 +334,26 @@ synapsor-runner activity search --proposal wrp_... --store ./.synapsor/local.db
 ### Docker Compose Shape
 
 Use Compose to run the MCP server next to your app and database network. Keep
-secrets in environment variables or your platform secret manager.
+secrets in environment variables or your platform secret manager. To hydrate
+Runner env vars from AWS Secrets Manager at startup, pass a JSON map through
+`SYNAPSOR_SECRET_MAP`:
+
+```bash
+export SYNAPSOR_SECRET_MAP='{
+  "SYNAPSOR_DATABASE_READ_URL": "prod/synapsor/runner#read_url",
+  "SYNAPSOR_DATABASE_WRITE_URL": "prod/synapsor/runner#write_url",
+  "SYNAPSOR_RUNNER_HTTP_TOKEN": "prod/synapsor/runner#http_token"
+}'
+
+synapsor-runner mcp serve-streamable-http \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --secrets-provider aws-secretsmanager-cli \
+  --secret-map-env SYNAPSOR_SECRET_MAP
+```
+
+The AWS provider shells out to `aws secretsmanager get-secret-value`; the runner
+logs only how many target env vars were loaded or skipped.
 
 ```yaml
 services:
@@ -286,4 +456,3 @@ Before promoting a package or calling a build production-candidate:
 The release gate should cover typecheck, focused tests, packed-package install,
 quick demo, own-db fixture, MCP stdio/HTTP checks, direct writeback,
 app-owned executor paths, package dry-run, and docs/package consistency.
-