@synapsor/runner 0.1.16 → 1.0.0

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

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/dsl-reference.md

@@ -149,6 +149,8 @@ patched column. Values may be identifiers or quoted strings.
 ```sql
   APPROVAL ROLE billing_lead
   AUTO APPROVE WHEN amount_cents <= 2500
+  LIMIT 20 PER DAY
+  LIMIT TOTAL 100000 PER DAY
   WRITEBACK DIRECT SQL
 ```
 
@@ -160,6 +162,22 @@ Cloud boundary.
 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 |

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

@@ -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:

package/docs/release-notes.md

@@ -1,7 +1,7 @@
 # Release Notes
 
-These notes track public Synapsor Runner behavior. Starting with `0.1.0`, the
-normal install path uses the untagged stable package:
+These notes track public Synapsor Runner behavior. Starting with `1.0.0`, the
+documented production-loop compatibility line uses the untagged stable package:
 
 ```bash
 npx -y -p @synapsor/runner synapsor-runner demo --quick
@@ -12,6 +12,29 @@ for the Synapsor Cloud CLI.
 
 ## Unreleased
 
+## 1.0.0
+
+### Production Approval Loop
+
+- Adds batch apply for approved proposals with independent per-proposal
+  outcomes, rerun-safe idempotency, and `--capability`, `--tenant`, and
+  `--max` filters.
+- Adds aggregate policy ceilings to canonical contracts and DSL authoring so
+  small proposals fall back to human review once daily count or total limits are
+  reached.
+- Adds signed operator-key approval/apply enforcement, tamper-evident approval
+  records, operational counters/logs, and a supervised local writeback worker.
+- Adds shared Postgres ledger support, runtime-store mode, per-session trusted
+  context, managed secret hydration, token rotation hooks, and Streamable HTTP
+  mTLS for scale-out deployments.
+- Keeps local SQLite as the default while allowing runtime-store workers to run
+  long-lived shared ledger drain loops under a Postgres advisory lock.
+- Declares the first semver contract for the documented CLI, schema, contract,
+  MCP result, writeback, approval, metrics, and replay surfaces.
+
+Prepared package versions: `@synapsor/spec@1.0.0`,
+`@synapsor/dsl@1.0.0`, and `@synapsor/runner@1.0.0`.
+
 ## 0.1.16
 
 ### Fleet-Lab Runner Hardening
@@ -478,10 +501,9 @@ not change and must not be republished for this release.
 
 ## Stable Release Policy
 
-Use untagged `@synapsor/runner` for stable installs. Use `@alpha` or an exact
-prerelease only when intentionally testing preview behavior. Stable `0.1.x`
-releases should keep the compatibility promise documented in
-`docs/release-policy.md`.
+Use untagged `@synapsor/runner` for stable installs. Use an exact prerelease
+only when intentionally testing preview behavior. Stable `1.x` releases should
+keep the compatibility promise documented in `docs/release-policy.md`.
 
 The first stable `0.1.0` release was gated on:
 

package/docs/release-policy.md

@@ -1,7 +1,10 @@
 # Release Policy
 
-Synapsor Runner `0.1.0` is the first stable local runner line. Use the stable
-package for normal installs:
+Synapsor Runner `0.1.0` was the first stable local runner line. Synapsor
+Runner `1.0.0` is the first production approval-loop semver line: batch apply,
+aggregate policy limits, verified operator identity, structured operations, and
+shared runtime-store deployment are part of the documented compatibility
+surface. Use the stable package for normal installs:
 
 ```bash
 npx -y -p @synapsor/runner synapsor-runner demo --quick
@@ -55,10 +58,37 @@ 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.
 
+## 1.0 Stability Gate
+
+Do not tag `1.0.0` only because the package is useful. `1.0.0` is the public
+semver contract for the Runner production approval loop, and it should be cut
+only after the following are true in the current tree and release artifacts:
+
+- batch apply can apply all approved proposals independently, reports
+  applied/conflict/skipped IDs, is safe to rerun through idempotency receipts,
+  and supports `--capability`, `--tenant`, and `--max`;
+- aggregate auto-approval limits are authored in DSL, represented in the
+  canonical contract spec, enforced as human-review fallback, persisted with
+  tripped-limit details, and visible in doctor/tools preview output;
+- approve/reject/apply can require a verified operator identity, enforce
+  contract reviewer roles and apply roles, and bind tamper-evident identity
+  records into the proposal ledger;
+- designed rejections and writeback outcomes emit structured logs, operational
+  counters are available per tenant and capability, and owner-only local store
+  permissions remain under test;
+- the documented public surfaces below have release-gate coverage from packed
+  artifacts, not only source-tree tests.
+
+After `1.0.0`, changes to the documented CLI, schema, contract, MCP result,
+writeback, approval, metrics, and replay surfaces must follow semantic
+versioning. Breaking changes require a new major version, except for security
+fixes that close a vulnerability while preserving the safest possible
+compatibility path.
+
 ## Stable Compatibility Promise
 
-Starting with `0.1.0`, Synapsor Runner keeps these public surfaces compatible
-through the `0.1.x` line unless a release note marks a deprecation first:
+Starting with `1.0.0`, Synapsor Runner keeps these public surfaces compatible
+through the `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;
@@ -73,8 +103,9 @@ through the `0.1.x` line unless a release note marks a deprecation first:
 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.
+internals. Local store migrations may happen inside `1.x` and later minor
+versions, but documented CLI inspection commands should remain the supported way
+to read the store.
 
 Alpha users should pin an exact alpha version in package.json, CI, and MCP
 client snippets. Use `@alpha` only when intentionally testing the moving

package/docs/runner-config-reference.md

@@ -26,7 +26,7 @@ Unknown keys fail when `strict` is true (the default).
 | `mode` | Yes | `read_only`, `shadow`, `review`, or `cloud`. |
 | `result_format` | No | `1` legacy or `2` stable `ok/summary/data/proposal/error` envelope. Default `1`. |
 | `strict` | No | Reject unknown config keys. Default `true`. |
-| `storage` | Local | Local SQLite ledger. |
+| `storage` | Local | Local SQLite ledger plus optional shared Postgres mirror or runtime-store wiring. |
 | `sources` | Local | Named Postgres/MySQL source wiring. |
 | `trusted_context` | Conditional | Default trusted tenant/principal binding. |
 | `contexts` | No | Named trusted contexts referenced by capabilities/contracts. |
@@ -34,6 +34,7 @@ Unknown keys fail when `strict` is true (the default).
 | `capabilities` | Conditional | Embedded compatibility capabilities; may be `[]` with `contracts`. |
 | `policies` | No | Embedded reviewed policies; contract policies merge into the same catalog. |
 | `approvals` | No | Local approval overrides. |
+| `operator_identity` | No | Verified operator identity and apply-role wiring for approve/reject/apply. |
 | `executors` | No | App-owned writeback wiring. |
 | `cloud` | Cloud mode | Scoped Cloud adapter configuration. |
 
@@ -50,13 +51,46 @@ Unknown keys fail when `strict` is true (the default).
 ## Storage
 
 ```json
-{ "storage": { "sqlite_path": "./.synapsor/local.db" } }
+{
+  "storage": {
+    "sqlite_path": "./.synapsor/local.db",
+    "shared_postgres": {
+      "mode": "mirror",
+      "url_env": "SYNAPSOR_LEDGER_DATABASE_URL",
+      "schema": "synapsor_runner",
+      "lock_timeout_ms": 10000
+    }
+  }
+}
 ```
 
 The ledger stores proposals, visible evidence copies, query audit, approvals,
 receipts, events, and replay. New POSIX stores are owner-only (`0600`). Protect
 the file like a database extract; see [Store Lifecycle](store-lifecycle.md).
 
+`storage.shared_postgres.mode = "mirror"` makes mutating CLI commands restore
+from the shared Postgres ledger before the local mutation and sync back after
+the command while holding a schema-scoped Postgres advisory lock. Mirror mode is
+a bounded operator handoff bridge; MCP serving still uses the local SQLite
+store.
+
+`storage.shared_postgres.mode = "runtime_store"` makes MCP serving use the
+shared Postgres ledger as the primary proposal/evidence/replay store. Runner
+creates a connection from the environment variable named by `url_env`, auto-runs
+the shared-ledger migration at startup, and uses a schema-scoped transaction
+advisory lock around runtime mutations. The URL is still referenced by
+environment variable name; never put the database URL in the config file.
+Bounded CLI approval/apply/worker commands bridge through the same Postgres
+ledger by restoring into a temporary local store under the Postgres advisory
+lock, running the existing mutation, and syncing back. Long-running worker
+processes repeat bounded drain cycles and release the advisory lock while idle.
+
+`synapsor-runner doctor --config ./synapsor.runner.json` checks shared Postgres
+wiring when this block is present: the URL env var must be set, and the
+configured schema must already contain `ledger_entries`, `proposal_locks`, and
+`worker_leases`. Doctor reports env var names and table readiness only; it does
+not print database URLs or create the schema.
+
 ## Sources
 
 ```json
@@ -100,6 +134,33 @@ Providers are `environment`, `static_dev`, `http_claims`, and `cloud_session`.
 Capabilities may reference a context by name. The model never receives tenant
 or principal as an overridable argument.
 
+For multi-tenant Streamable HTTP services, use `http_claims` plus signed
+session auth:
+
+```json
+{
+  "trusted_context": {
+    "provider": "http_claims",
+    "values": {
+      "tenant_id_key": "tenant_id",
+      "principal_key": "sub"
+    }
+  },
+  "session_auth": {
+    "provider": "jwt_hs256",
+    "secret_env": "SYNAPSOR_SESSION_JWT_SECRET",
+    "previous_secret_env": "SYNAPSOR_PREVIOUS_SESSION_JWT_SECRET",
+    "issuer": "https://identity.example",
+    "audience": "synapsor-runner"
+  }
+}
+```
+
+`previous_secret_env` is optional and is only for rotation windows. Runner tries
+the active secret first, then the previous secret. Existing MCP sessions remain
+bound to the exact token fingerprint, so clients cannot swap tenant/principal
+identity inside an initialized session.
+
 ## Contracts and embedded capabilities
 
 ```json
@@ -148,9 +209,53 @@ See [Writeback Executors](writeback-executors.md).
 
 `policies` is an array of reviewed policy objects. Local approval policies use
 `kind: "approval"` and numeric rules such as `{ "field": "amount_cents",
-"max": 2500 }`. `approvals.disable_auto_approval: true` disables local policy
-auto-approval without changing the reviewed contract. Approval never becomes an
-MCP tool.
+"max": 2500 }`. Canonical policies may also carry daily `count` or `total`
+limits scoped to `tenant_policy` or `tenant_policy_object`. These limits come
+from reviewed DSL `LIMIT` clauses, not an unreviewed local override. A tripped
+limit falls back to human review and is recorded in the ledger.
+`approvals.disable_auto_approval: true` disables local policy auto-approval
+without changing the reviewed contract. Approval never becomes an MCP tool.
+
+## Operator identity
+
+Local development compatibility uses an explicitly unverified environment
+identity:
+
+```json
+{
+  "operator_identity": {
+    "provider": "dev_env",
+    "actor_env": "SYNAPSOR_OPERATOR_ID",
+    "roles_env": "SYNAPSOR_OPERATOR_ROLES",
+    "apply_roles": ["writeback_operator"]
+  }
+}
+```
+
+Shared or production-like operation should register signed operator keys:
+
+```json
+{
+  "operator_identity": {
+    "provider": "signed_key",
+    "apply_roles": ["writeback_operator"],
+    "operators": {
+      "alice": {
+        "public_key_path": "./operators/alice.pub.pem",
+        "roles": ["support_reviewer", "writeback_operator"]
+      }
+    }
+  }
+}
+```
+
+The public key path resolves relative to `synapsor.runner.json`. Keep the
+private key outside the repository and invoke decisions with `--identity alice
+--identity-key /secure/path/alice.pem`. Runner verifies key possession and the
+contract's required role, then binds the exact proposal hash/version, action,
+subject, timestamp, roles, signature, and integrity hash into the approval
+ledger. `apply_roles` independently gates writeback. The local browser UI
+refuses approval/rejection in signed-key mode so it cannot bypass this check.
 
 ## Cloud mode
 

package/examples/support-plan-credit/README.md

@@ -196,10 +196,15 @@ The auto-approval policy lives in `contract.synapsor.sql`:
 
 ```sql
 AUTO APPROVE WHEN plan_credit_cents <= 2500
+LIMIT 20 PER DAY
+LIMIT TOTAL 100000 PER DAY
 ```
 
 That compiles into `synapsor.contract.json` as a reviewed approval policy. It is
-stored in git, validated by `@synapsor/spec`, and included in Cloud push payloads.
+stored in git, validated by `@synapsor/spec`, and included in Cloud push
+payloads. The policy may approve at most 20 qualifying credits or 100,000 cents
+in total per trusted tenant and UTC day. The first ceiling reached leaves later
+proposals in `pending_review` and records why the policy deferred to a human.
 
 To disable local policy approval without changing the contract:
 
@@ -214,6 +219,16 @@ To disable local policy approval without changing the contract:
 Auto-approval never applies the write. It only records an approval row and audit
 event with actor `policy:<policy_name>`.
 
+After reviewing the ceilings and running `doctor`, an operator can drain the
+approved queue without letting one stale-row conflict abort the remaining jobs:
+
+```bash
+synapsor-runner apply --all-approved --yes \
+  --capability support.propose_plan_credit --tenant acme --max 20 \
+  --config examples/support-plan-credit/synapsor.runner.json \
+  --store ./tmp/support-plan-credit/local.db
+```
+
 ## Cloud
 
 Dry-run the Cloud payload:

package/examples/support-plan-credit/contract.synapsor.sql

@@ -46,6 +46,8 @@ CREATE CAPABILITY support.propose_plan_credit
   BOUND plan_credit_cents 1..50000
   APPROVAL ROLE support_reviewer
   AUTO APPROVE WHEN plan_credit_cents <= 2500
+  LIMIT 20 PER DAY
+  LIMIT TOTAL 100000 PER DAY
   WRITEBACK DIRECT SQL
 END