@synapsor/runner 1.4.1 → 1.4.121

package/docs/README.md

@@ -70,6 +70,12 @@ no-database demo, wire your database, then read deeper concepts.
 - [Recipes](recipes.md): starter business-capability templates.
 - [JSON Schema](../schemas/synapsor.runner.schema.json): editor validation for
   `synapsor.runner.json`.
+- [Contract Review](contract-review.md): LSP setup, plain-language explanation,
+  and deterministic lint/SARIF output.
+- [Contract Testing](contract-testing.md): adopter-owned static and disposable
+  PostgreSQL/MySQL allow/deny/redaction assertions.
+- [Bounded Aggregate Reads](aggregate-reads.md): fixed scalar count/sum/avg,
+  tenant scope, suppression, and no-row evidence.
 
 ## 06 Serve MCP
 
@@ -113,6 +119,10 @@ no-database demo, wire your database, then read deeper concepts.
   and lifecycle inspection.
 - `examples/mysql-refund-agent/`: MySQL order/refund review example using the
   same proposal, approval, guarded writeback, and replay loop.
+- [Scoped Ledger Reports](compliance-reports.md): object/principal JSON,
+  Markdown, and PDF exports with digest/signature verification.
+- [Graduated Trust](graduated-trust.md): off-by-default operator
+  recommendations that never auto-activate a policy.
 
 ## 09 App-Owned Handlers
 

package/docs/aggregate-reads.md

@@ -0,0 +1,49 @@
+# Bounded Aggregate Reads
+
+An `aggregate_read` capability returns one reviewed scalar rather than source
+rows. It is intended for questions such as a tenant-scoped overdue balance
+total where exposing individual records would be unnecessary.
+
+```sql
+CREATE CAPABILITY billing.overdue_balance_total
+  DESCRIPTION 'Return the reviewed overdue balance total for the trusted tenant.'
+  USING CONTEXT local_operator
+  SOURCE billing_postgres
+  ON public.invoices
+  PRIMARY KEY id
+  TENANT KEY tenant_id
+  AGGREGATE READ SUM balance_cents
+  SELECT WHERE status = 'overdue'
+  MIN GROUP SIZE 5
+  REQUIRE EVIDENCE
+END
+```
+
+Compile the packaged example with:
+
+```bash
+synapsor-runner dsl compile ./fixtures/dsl/aggregate-read.synapsor.sql \
+  --out ./synapsor.contract.json --strict
+```
+
+A permitted call returns one aggregate scalar; an undersized group returns a
+stable suppressed result. Neither result contains source rows or member IDs.
+
+Supported operations are `COUNT ROWS`, `COUNT NON NULL column`, `SUM column`,
+and `AVG column`. The source, table/view, tenant key, function, column, optional
+equality selection, and minimum group size are contract-authored. The first
+release permits no model arguments, dynamic columns, joins, grouping, arbitrary
+expressions, or model-controlled predicates.
+
+When fewer records match than `MIN GROUP SIZE`, the stable result is suppressed
+and contains no aggregate value or member identity. Allowed results contain one
+scalar plus evidence/query-audit handles. Evidence records the contract digest,
+trusted scope reference, reviewed operation, fixed predicate summary, and
+suppression state; it never stores member rows or IDs.
+
+PostgreSQL and MySQL execution is parameterized and uses the configured
+statement timeout. A dependency outage or statement timeout returns a safe,
+retryable unavailable result without exposing a driver error. Minimum-group
+suppression reduces single-record inference; it does not solve every statistical
+inference risk. Review the underlying view, database role, and aggregation
+policy as well.

package/docs/bounded-set-writeback.md

@@ -129,20 +129,25 @@ CREATE CAPABILITY tickets.close_overdue
   CONFLICT GUARD version
   LOOKUP reason BY id
   ARG reason STRING REQUIRED MAX LENGTH 100
-  ALLOW READ id, tenant_id, status, cost_cents, version
+  ALLOW READ id, tenant_id, risk_level, case_status, cost_cents, version
   REQUIRE EVIDENCE
   PROPOSE ACTION close_overdue UPDATE SET
-  SELECT WHERE status = 'overdue'
+  SELECT WHERE risk_level = 'high' AND case_status = 'active'
   MAX ROWS 10
   MAX TOTAL cost_cents BEFORE 50000
-  ALLOW WRITE status
-  PATCH status = 'closed'
+  ALLOW WRITE case_status
+  PATCH case_status = 'closed'
   ADVANCE VERSION version USING INTEGER INCREMENT
   APPROVAL ROLE ops_manager
   WRITEBACK DIRECT SQL
 END
 ```
 
+Each `SELECT WHERE` term is a reviewer-fixed literal equality, and every term
+must match. Up to eight terms may be joined by `AND`; quoted `AND` text remains
+part of the value. `OR`, parentheses, inequalities, ranges, and free-form or
+model-authored predicates are not supported.
+
 Compile the contract and create `synapsor.runner.json`:
 
 ```bash

package/docs/compliance-reports.md

@@ -0,0 +1,42 @@
+# Export Scoped Ledger Reports
+
+Runner can export a deterministic chronology for one business object or one
+principal inside an explicit tenant scope:
+
+```bash
+synapsor-runner report --object invoice:INV-3001 --tenant tenant_acme \
+  --store ./.synapsor/local.db --format markdown --out ./invoice-report.md
+
+synapsor-runner report --principal support.operator --tenant tenant_acme \
+  --store ./.synapsor/local.db --format pdf --out ./operator-report.pdf
+```
+
+Runner prints the output path and canonical `sha256:...` integrity digest. A
+successful verification prints `PASS`, `REPORT_DIGEST_VERIFIED`, or
+`REPORT_SIGNATURE_VERIFIED` when a public key is supplied.
+
+For `storage.shared_postgres.mode = "runtime_store"`, include `--config
+./synapsor.runner.json`; Runner reads through a bounded local bridge to the same
+shared ledger.
+
+Reports include scoped proposal, query-audit, approval/rejection, writeback,
+receipt, replay, compensation, and graduated-trust decision metadata when those
+records exist. Evidence rows are never exported. Kept-out values, credentials,
+keys, raw driver errors, and database URLs are excluded.
+
+JSON, Markdown, and PDF reports carry a canonical manifest digest. Optional
+operator signing binds the export to the existing key model:
+
+```bash
+synapsor-runner report --object invoice:INV-3001 --tenant tenant_acme \
+  --store ./.synapsor/local.db --format json --out ./invoice-report.json \
+  --signing-key ./operator-private.pem --key-id review-key-1
+
+synapsor-runner report verify ./invoice-report.json \
+  --public-key ./operator-public.pem
+```
+
+Verification detects content, ordering, digest, and signature tampering. A
+verified export is tamper-evident; it does not make local SQLite immutable,
+append-only compliance storage. Protect report files and signing keys with the
+same care as the ledger.

package/docs/conformance.md

@@ -28,6 +28,7 @@ Current fixture groups:
 - `manual-approval`
 - `auto-approval`
 - `aggregate-policy-limits`
+- `aggregate-read`
 - `numeric-bounds`
 - `bounded-set-threats`
 - `reversible-change-sets`
@@ -42,6 +43,12 @@ selection, count/value caps, frozen-version drift checks, atomic rollback,
 exact receipts, hard-delete side-effect refusal, and human approval. Adapter
 tests and `corepack pnpm test:bounded-set` complete the live PostgreSQL/MySQL
 matrix.
+The aggregate-read fixture proves a reviewer-fixed scalar operation, trusted
+tenant scope, fixed equality selection, minimum-group suppression, and an
+evidence/query-audit surface containing no member rows or identities. The live
+`corepack pnpm test:aggregate-read` gate runs COUNT/SUM/AVG, suppression,
+timeout, and dependency classification against disposable PostgreSQL and
+MySQL.
 The reversible-change-set fixture proves that undo is a new reviewed
 compensation proposal, not rollback: apply-time receipts capture only
 allowlisted inverse data, compensation uses fresh guards and exact members,
@@ -72,6 +79,8 @@ Run:
 
 ```bash
 corepack pnpm --filter @synapsor-runner/mcp-server test
+corepack pnpm test:contract-conformance
+corepack pnpm test:aggregate-read
 ```
 
 The spec package also validates every conformance contract:

package/docs/contract-review.md

@@ -0,0 +1,57 @@
+# Review Contracts Before Serving Them
+
+Runner uses the same DSL parser and canonical Spec validator for compilation,
+editor diagnostics, explanation, and lint. These tools reduce authoring errors;
+they do not replace a human review of database permissions, visible fields,
+tenant binding, or business policy.
+
+## Explain The Boundary
+
+```bash
+synapsor-runner contract explain ./contract.synapsor.sql --format markdown
+synapsor-runner contract explain ./synapsor.contract.json --format json
+```
+
+The explanation lists trusted context bindings, model-facing arguments, fixed
+targets and selections, visible and kept-out fields, evidence requirements,
+proposal/writeback controls, approval, bounds, reversibility, and unresolved
+runtime dependencies. It is derived from normalized canonical contract JSON.
+It never reads environment values or prints database URLs, tokens, keys, or
+evidence rows.
+
+## Lint In CI
+
+```bash
+synapsor-runner contract lint ./contract.synapsor.sql --strict
+synapsor-runner contract lint ./synapsor.contract.json \
+  --config ./synapsor.runner.json --format sarif --out ./contract-lint.sarif
+```
+
+`--strict` is equivalent to `--fail-on warning`; the default fails on errors.
+Lint rule IDs, ordering, severity, and source ranges are deterministic. Rules
+cover objective review gaps such as missing descriptions/evidence, unbounded
+strings, unresolved wiring, irreversible operations, and policy/writeback
+contradictions. Lint does not claim to discover every sensitive column.
+
+Expected successful output ends with:
+
+```text
+Summary: 0 error / 0 warning / N info
+```
+
+## Language Server
+
+```bash
+synapsor-runner language-server --stdio
+```
+
+The stdio LSP supports `.synapsor.sql` and legacy `.synapsor` documents. It
+publishes parser/validator diagnostics and provides context-aware completion,
+hover, and formatting. Configure a generic LSP client to launch the command
+above with the workspace as its working directory. For VS Code, use any stdio
+language-client extension that can associate both filename patterns with that
+command. Generic SQL highlighting remains useful for `.synapsor.sql`; the LSP
+adds Synapsor-specific semantics.
+
+The server never suggests raw SQL, model-authored predicates, approval tools,
+or clauses that are illegal for the current capability kind.

package/docs/contract-testing.md

@@ -0,0 +1,47 @@
+# Test A Contract Boundary
+
+Adopter-owned contract tests exercise reviewed allow/deny behavior without an
+LLM. The public manifest schema is
+[`schemas/synapsor.contract-tests.schema.json`](../schemas/synapsor.contract-tests.schema.json).
+
+```bash
+synapsor-runner contract test \
+  --contract ./synapsor.contract.json \
+  --tests ./synapsor.contract-tests.json \
+  --config ./synapsor.runner.json
+```
+
+Static mode checks tool exposure, operator-only boundaries, argument limits,
+transition guards, bounded-set caps, and other assertions that do not require a
+database. Add `--live` to call the actual MCP runtime for scoped reads,
+proposals, evidence/replay redaction, and source-unchanged checks.
+
+```bash
+synapsor-runner contract test \
+  --contract ./synapsor.contract.json \
+  --tests ./synapsor.contract-tests.json \
+  --config ./synapsor.runner.json \
+  --live --format junit --out ./contract-tests.xml
+```
+
+Live mode accepts local/disposable PostgreSQL and MySQL targets. Runner refuses
+remote hosts by default; `--allow-remote` is an explicit operator override and
+does not grant implicit write permission. Use synthetic fixtures and a
+disposable database. Unknown assertions and unresolved required tests fail
+rather than being skipped.
+
+A successful run ends with a stable count such as:
+
+```text
+Summary: 6 passed / 0 failed / 6 total
+```
+
+Supported assertions cover valid scoped tools, cross-tenant denial, kept-out
+fields, argument constraints, transition guards, set caps, unchanged source
+state before approval, and the absence of model-facing approval/writeback.
+Trusted tenant and principal values belong in test setup, not tool arguments.
+
+The flagship example includes a working manifest at
+[`examples/support-plan-credit/synapsor.contract-tests.json`](../examples/support-plan-credit/synapsor.contract-tests.json).
+Contract tests prove the declared cases, not every possible threat or database
+permission error.

package/docs/dsl-reference.md

@@ -71,6 +71,7 @@ END
   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
+  ARG risk_level STRING ENUM('low', 'medium', 'high') REQUIRED
 ```
 
 Argument types are `STRING`/`TEXT`, `NUMBER`, and `BOOLEAN`/`BOOL`.
@@ -80,12 +81,41 @@ Argument types are `STRING`/`TEXT`, `NUMBER`, and `BOOLEAN`/`BOOL`.
 - `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.
+- `ENUM(value, ...)` restricts an argument to reviewed string, numeric, or
+  boolean values of the declared type. Enums contain 1 through 64 unique,
+  non-null values and preserve declared order.
 
 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.
 
+## Aggregate read
+
+An aggregate capability returns one scalar and no source rows:
+
+```sql
+CREATE CAPABILITY billing.overdue_balance_total
+  DESCRIPTION 'Return overdue balance for the trusted tenant.'
+  USING CONTEXT local_operator
+  SOURCE billing_postgres
+  ON public.invoices
+  PRIMARY KEY id
+  TENANT KEY tenant_id
+  AGGREGATE READ SUM balance_cents
+  SELECT WHERE status = 'overdue'
+  MIN GROUP SIZE 5
+  REQUIRE EVIDENCE
+END
+```
+
+Use `COUNT ROWS`, `COUNT NON NULL column`, `SUM column`, or `AVG column`.
+`SELECT WHERE` is the same contract-fixed equality AST used by reviewed set
+operations. `MIN GROUP SIZE` is mandatory and must be 2 through 1,000,000.
+Aggregate reads cannot declare model arguments, lookup, visible row fields,
+proposal clauses, joins, grouping, or arbitrary expressions. See [Bounded
+Aggregate Reads](aggregate-reads.md).
+
 ## Read surface and evidence
 
 ```sql
@@ -162,7 +192,7 @@ bounds, exact version guards, and human/operator approval:
 
 ```sql
   PROPOSE ACTION close_overdue UPDATE SET
-  SELECT WHERE status = 'overdue'
+  SELECT WHERE risk_level = 'high' AND case_status = 'active'
   MAX ROWS 10
   MAX TOTAL balance_cents BEFORE 50000
   ALLOW WRITE status
@@ -172,11 +202,14 @@ bounds, exact version guards, and human/operator approval:
   WRITEBACK DIRECT SQL
 ```
 
-`SELECT WHERE` accepts one or more literal equality terms joined by `AND`.
-Columns, operators, values, ordering, ranges, and raw SQL cannot come from a
-model argument. Runner reads `MAX ROWS + 1` and rejects overflow rather than
-truncating. `MAX TOTAL column BEFORE|AFTER|ABSOLUTE DELTA maximum` is a
-reviewer-visible aggregate value bound.
+`SELECT WHERE` accepts one through eight literal equality terms joined by
+`AND`. The separator is recognized only outside quoted literals, so
+`description = 'salt AND pepper'` remains one term. `OR`, parentheses,
+inequalities, ranges, trailing expressions, and free-form or model-authored
+predicates are rejected during compilation. Runner reads `MAX ROWS + 1` and
+rejects overflow rather than truncating. `MAX TOTAL column
+BEFORE|AFTER|ABSOLUTE DELTA maximum` is a reviewer-visible aggregate value
+bound.
 
 Batch INSERT takes a complete typed item array:
 

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

@@ -368,7 +368,14 @@ npx -y -p @synapsor/runner synapsor-runner smoke call --config ./synapsor.runner
 
 `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.
+prints the commands to inspect evidence/proposals/replay. With the default
+storage topology those records are in local SQLite. With
+`storage.shared_postgres.mode = "runtime_store"`, Runner `1.4.12` and later
+write them to the authoritative shared Postgres ledger and include `--config`
+in follow-up commands. The supplied `--store` path is compatibility plumbing
+for those CLI commands; it does not receive an orphan proposal copy. If the
+shared ledger is unavailable, `smoke call` fails safely and does not fall back
+to SQLite.
 
 The snippets contain the local command and args. They must not contain database
 URLs, passwords, approval tools, commit tools, or write credentials.

package/docs/graduated-trust.md

@@ -0,0 +1,64 @@
+# Graduated Trust Recommendations
+
+Graduated trust is an opt-in operator workflow that evaluates scoped ledger
+history and recommends a bounded policy threshold change. It is disabled by
+default. It never auto-approves itself, changes the active contract, pushes a
+contract, or activates a registry version.
+
+```json
+{
+  "graduated_trust": {
+    "enabled": true,
+    "kill_switch": false,
+    "criteria": [{
+      "capability": "support.propose_plan_credit",
+      "policy": "small_credit",
+      "field": "plan_credit_cents",
+      "minimum_human_reviews": 20,
+      "window_days": 30,
+      "maximum_rejection_rate": 0.05,
+      "maximum_conflict_rate": 0.01,
+      "maximum_failure_rate": 0.01,
+      "maximum_revert_rate": 0.01,
+      "maximum_threshold_increase": 500,
+      "absolute_ceiling": 5000
+    }]
+  }
+}
+```
+
+Evaluate human-reviewed outcomes for one trusted tenant/capability/policy:
+
+```bash
+synapsor-runner policy recommend --contract ./synapsor.contract.json \
+  --config ./synapsor.runner.json --tenant tenant_acme \
+  --capability support.propose_plan_credit --policy small_credit \
+  --store ./.synapsor/local.db
+```
+
+Eligible history produces `RECOMMENDATION_CREATED` and a pending `ptr_...`
+identifier. Disabled, insufficient, stale, or out-of-policy history returns a
+stable non-success code and creates no recommendation.
+
+Auto-approved outcomes do not count as independent human evidence. Missing or
+legacy provenance, mismatched contract digest/version, tampered approvals,
+cross-scope records, insufficient samples, or excessive rejection, conflict,
+failure, or revert rates fail closed. `kill_switch: true` disables evaluation
+even when `enabled` remains true.
+
+A recommendation remains operator-only. List it with `policy recommendations
+list`. Approval or rejection requires a cryptographically verified `signed_key`
+or `jwt_oidc` operator identity. Rejection is terminal. Approval permits only
+an explicit export of a separate reviewable contract artifact:
+
+```bash
+synapsor-runner policy recommendations export ptr_... --tenant tenant_acme \
+  --contract ./synapsor.contract.json \
+  --out ./synapsor.contract.recommended.json --actor policy-reviewer --yes \
+  --store ./.synapsor/local.db
+```
+
+Export rechecks the base contract digest, version, and current threshold. The
+artifact is not activated. Activation remains an explicit operator or Cloud
+registry action. Recommendation, decision, and export metadata remain in the
+local or shared Postgres runtime ledger and can appear in scoped reports.

package/docs/limitations.md

@@ -49,6 +49,12 @@ enterprise SLA.
 - Static MCP database risk review.
 - Local indexed search for proposals, evidence bundles, query audit, writeback
   receipts, and proposal replay.
+- DSL enum arguments and fixed, tenant-scoped aggregate count/sum/avg tools
+  with mandatory minimum-group suppression and no source-row output.
+- Contract LSP, explanation, deterministic lint, adopter-owned contract tests,
+  and scoped tamper-evident JSON/Markdown/PDF ledger reports.
+- Off-by-default graduated-trust recommendations that require verified operator
+  review and explicit artifact export without activation.
 
 ## Runtime Contract
 
@@ -81,6 +87,10 @@ truth for the model-facing tools.
 - Prompt-injection prevention.
 - Unbounded/high-throughput or multi-region ledger scale.
 - Managed fleet, SLA, compliance certification, or production support guarantee.
+- Arbitrary aggregate expressions, joins, grouping, dynamic columns,
+  model-controlled aggregate predicates, or a statistical privacy guarantee.
+- Automatic policy widening or activation from graduated-trust metrics.
+- Immutable/WORM compliance storage from the local report exporter.
 
 ## Important External Database Semantics
 

package/docs/production.md

@@ -340,6 +340,16 @@ 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.
 
+`smoke call` uses the same runtime-store resolver as MCP serving. Its evidence,
+query audit, proposal, events, and replay records therefore land directly in
+the shared Postgres ledger and are immediately visible to another Runner using
+the same config. `--store` remains accepted so the printed follow-up CLI
+commands have a compatibility/bridge path, but that SQLite path is not an
+authoritative copy and normally is not created by the smoke call. Shared-ledger
+connection failure returns the safe availability error and a nonzero exit; it
+never causes a local fallback. This consistency fix is present in Runner
+`1.4.12` and later.
+
 `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

package/docs/release-notes.md

@@ -10,6 +10,59 @@ npx -y -p @synapsor/runner synapsor-runner demo --quick
 The OSS runner command is `synapsor-runner`. The `synapsor` command is reserved
 for the Synapsor Cloud CLI.
 
+## 1.4.121 (prepared, not published)
+
+### Contract trust surface and bounded-set parser correctness
+
+- Fixes BUG-018, where a documented fixed predicate containing multiple
+  equality terms joined by `AND` could compile as one string-valued term and
+  then fail closed with no matching source rows.
+- The DSL compiler now consumes the complete clause, keeps `AND` inside quoted
+  strings, preserves ordered typed literals, and rejects malformed or
+  unsupported expressions before serving or proposal creation.
+- This does not add free-form SQL predicates: only fixed literal equality terms
+  joined by `AND` are supported. `OR`, parentheses, inequalities, ranges, and
+  model-authored predicates remain unsupported.
+- PostgreSQL and MySQL live verification proves all terms are applied together
+  within trusted tenant scope, source rows remain unchanged before approval,
+  and guarded apply, receipt/replay, retry, caps, and drift checks remain green.
+- Contract authors gain one parser-backed review path: stdio LSP diagnostics,
+  completion, hover, and formatting; plain-language explanation; deterministic
+  lint; and adopter-owned static/disposable contract tests.
+- Scoped object/principal reports export redacted JSON, Markdown, or PDF ledger
+  metadata with digest/signature verification. They are tamper-evident exports,
+  not a claim that local SQLite is immutable compliance storage.
+- DSL enum arguments compile to the canonical enum shape and are enforced by
+  every Runner transport. Canonical aggregate reads return one fixed
+  tenant-scoped COUNT/SUM/AVG scalar, suppress small groups, and persist no
+  member rows or identities in evidence/query audit.
+- Graduated trust remains disabled by default and operator-only. It can create
+  and export a verified, bounded policy recommendation artifact, but cannot
+  auto-approve, push, or activate it.
+- C++/Cloud validators and exporters preserve the new additive enum/aggregate
+  fields for canonical round-trip compatibility.
+
+Prepared package versions: `@synapsor/spec@1.4.1`,
+`@synapsor/dsl@1.4.2`, and `@synapsor/runner@1.4.121`.
+
+## 1.4.12 (prepared, not published)
+
+### Runtime-store smoke-call consistency
+
+- Fixes BUG-017, where `smoke call` could put proposal artifacts in the
+  requested local SQLite path even though the config selected authoritative
+  shared Postgres `runtime_store` mode.
+- Smoke calls now use the same runtime storage resolver as MCP tool calls. A
+  second Runner can immediately inspect the proposal, evidence, query audit,
+  events, and replay from the shared ledger.
+- Shared-ledger unavailability fails closed with a safe retryable error,
+  nonzero exit status, no credential leakage, and no local orphan proposal.
+- Local SQLite and mirror modes retain their existing behavior; no source row
+  changes before the normal external approval/apply path.
+
+Prepared package version: `@synapsor/runner@1.4.12`.
+`@synapsor/dsl` remains `1.4.1`; `@synapsor/spec` remains `1.4.0`.
+
 ## 1.4.1 (prepared, not published)
 
 ### Bounded-set digest compatibility patch

package/docs/runner-config-reference.md

@@ -38,6 +38,7 @@ Unknown keys fail when `strict` is true (the default).
 | `session_auth` | HTTP claims | HS256 development or asymmetric RS256/ES256 session-token verification. |
 | `rate_limits` | No | Operational fixed-window limits; fleet-wide only with shared `runtime_store`. |
 | `metrics` | No | Separately authorized scrapeable HTTP metrics. Disabled by default. |
+| `graduated_trust` | No | Off-by-default, operator-only policy recommendation criteria and kill switch. |
 | `executors` | No | App-owned writeback wiring. |
 | `cloud` | Cloud mode | Scoped Cloud adapter configuration. |
 
@@ -375,6 +376,21 @@ metrics token; the MCP bearer does not authorize metrics. Labels are bounded to
 trusted tenant, capability, source, engine, and readiness component. Object
 IDs, principals, URLs, tokens, and raw errors are never labels.
 
+## Graduated trust
+
+`graduated_trust` is runtime/operator policy, not model-facing authority. It is
+disabled unless `enabled` is exactly `true`; `kill_switch: true` stops all
+evaluation. Each criterion fixes one capability, approval policy, numeric
+field, minimum human-reviewed sample (10..10000), window (1..365 days), maximum
+rejection/conflict/failure/revert rates, maximum threshold increment, and
+absolute ceiling. Optional `workspace_id` and `project_id` further scope stored
+recommendations.
+
+Auto-approved outcomes never count as human evidence. Recommendation decisions
+require verified operator identity. Approval only permits exporting a new
+contract artifact bound to the current digest/version; Runner never activates
+it. See [Graduated Trust Recommendations](graduated-trust.md).
+
 ## Operator identity
 
 Local development compatibility uses an explicitly unverified environment

package/docs/security-boundary.md

@@ -40,6 +40,12 @@ The model does not receive:
 - commit/writeback tools;
 - trusted tenant or principal authority as ordinary model arguments.
 
+Reviewed aggregate tools expose one scalar only. Their function, column,
+tenant key, optional equality selection, and minimum-group threshold are fixed
+in the contract; the model receives no predicate arguments or member rows.
+Suppression reduces single-record inference but does not replace statistical
+privacy review. See [Bounded Aggregate Reads](aggregate-reads.md).
+
 Trusted context comes from local configuration, environment bindings, or Cloud
 session context in Cloud mode. Tenant, principal, and authorization scope must
 not be accepted from the model as authority.
@@ -121,6 +127,13 @@ approve/reject actions. It does not expose raw SQL, database URLs, write
 credentials, approval tools, commit tools, or controls that widen reviewed
 tables/columns.
 
+Contract lint and tests are review aids rather than a proof of complete
+security. Scoped report exports omit evidence rows and kept-out values and are
+tamper-evident when their digest/signature verifies; local SQLite is not an
+immutable compliance service. Graduated-trust evaluation is operator-only,
+disabled by default, and can recommend/export a separate artifact but cannot
+approve itself or activate policy.
+
 Synapsor Runner supports reviewed single-row CRUD and the narrowly bounded set
 path documented above. It does not support arbitrary SQL, DDL, UPSERT,
 model-generated predicates, unbounded sets, or cross-table direct writeback.

package/docs/troubleshooting-first-run.md

@@ -12,6 +12,26 @@ Use JSON for automation:
 npx -y -p @synapsor/runner synapsor-runner doctor --first-run --json
 ```
 
+## Smoke Proposal Missing From Another Runner
+
+What happened:
+
+`smoke call` returned a proposal id, but `proposals list --config ...` on a
+second Runner cannot find it.
+
+Fix:
+
+1. Verify `synapsor-runner --version` is `1.4.12` or later.
+2. Confirm both commands use a config whose
+   `storage.shared_postgres.mode` is `runtime_store` and whose `url_env` and
+   `schema` identify the same ledger.
+3. Run `store shared-postgres status --url-env <ENV> --schema <SCHEMA>`.
+
+In `runtime_store` mode, `--store` is not the authoritative ledger. Runner does
+not fall back to that SQLite path when shared Postgres is unavailable. Versions
+before `1.4.12` could orphan smoke-call artifacts locally; recreate that test
+proposal after upgrading.
+
 ## Docker Missing
 
 What happened:

package/examples/runner-fleet/seed/postgres.sql

@@ -64,6 +64,7 @@ INSERT INTO public.invoices (id, tenant_id, status, late_fee_cents, waiver_reaso
   ('INV-ACME', 'acme', 'overdue', 2500, NULL, '2026-07-12T12:00:00Z'),
   ('INV-GLOBEX', 'globex', 'overdue', 3100, NULL, '2026-07-12T12:00:00Z'),
   ('INV-RATECO', 'rateco', 'overdue', 900, NULL, '2026-07-12T12:00:00Z'),
+  ('INV-SMOKE-CALL', 'acme', 'overdue', 2100, NULL, '2026-07-12T12:00:00Z'),
   ('INV-BATCH-A', 'acme', 'overdue', 1100, NULL, '2026-07-12T12:00:00Z'),
   ('INV-BATCH-B', 'acme', 'overdue', 1300, NULL, '2026-07-12T12:00:00Z'),
   ('INV-QUORUM-RACE', 'acme', 'overdue', 1400, NULL, '2026-07-12T12:00:00Z'),