@synapsor/runner 1.5.4 → 1.6.1

package/docs/current-scope.md

@@ -2,40 +2,72 @@
 
 The canonical scope page is [Current Limitations](limitations.md).
 
-Current `1.4` scope:
+Current `1.6` scope:
 
-- local semantic MCP tools for Postgres/MySQL-backed business actions;
-- schema inspection and guided config generation;
-- trusted context from environment/session values;
-- evidence handles, query audit, proposals, receipts, and local replay;
-- guarded single-row `INSERT`, `UPDATE`, and `DELETE` writeback with explicit
-  receipt authority;
+- local semantic MCP tools over Postgres/MySQL without raw SQL tools;
+- deterministic whole-schema Auto Boundary drafting from database metadata,
+  statically parsed Prisma/Drizzle schemas, OpenAPI documents, and existing
+  Synapsor definitions;
+- disabled generated `.synapsor.sql`, canonical JSON, tests, review evidence,
+  and generation locks; no generated authority activates itself;
+- local development/staging Scoped Explore through exactly two temporary MCP
+  tools, using typed row plans or a reviewed PM-style analytical cube;
+- aggregate `count`, reviewed `count_distinct`, `sum`, `avg`, reviewed
+  dimensions and day/week/month buckets, typed filters, bounded top-N, and at
+  most one proven many-to-one relationship;
+- cohort suppression plus durable extraction, differencing, rate, query,
+  response, and complexity limits;
+- Protect This Query from a successful local plan to public DSL, canonical
+  Spec, tests, and a disabled digest-bound named production capability;
+- schema, grant, ownership, RLS, role, compiler, and Spec drift checks for
+  generated authority explicitly bound to a generation lock;
+- trusted context from environment, verified HTTP claims, Cloud sessions, or
+  explicit development-only static values;
+- evidence handles, normalized query audit, proposals, receipts, local replay,
+  and read-only lifecycle inspection without copying proposal ids;
+- optional proposal/evidence freshness: live target and declared same-source
+  supporting-row checks before every approval, proof-bound human/quorum/policy
+  decisions, and atomic direct-SQL dependency revalidation at apply;
+- guarded single-row `INSERT`, `UPDATE`, and `DELETE`;
 - fixed-predicate set `UPDATE`/`DELETE` and exact-review batch `INSERT`, with
   mandatory row/value caps, frozen members, human approval, atomic execution,
   and protocol-v3 exact receipts;
-- opt-in reviewed compensation for direct SQL UPDATE, INSERT, soft-delete, and
-  exact frozen sets, using a separate operator proposal and protocol-v4 receipt;
-- app-owned `http_handler` and `command_handler` executors for richer approved
-  business transactions;
-- stdio MCP, Streamable HTTP MCP, and a small JSON-RPC bridge.
-- a bounded small-fleet shape with asymmetric claim-bound sessions, shared
-  Postgres review state, source pools, fleet rate limits, readiness, protected
-  metrics, verified quorum review, dead letters, and backup/restore/retention;
+- opt-in reviewed compensation for supported direct SQL changes, using a
+  separate operator proposal and protocol-v4 receipt;
+- safety-wrapped app-owned `http_handler` and `command_handler` executors for
+  richer approved business transactions;
+- stdio MCP, authenticated Streamable HTTP MCP, and a legacy JSON-RPC bridge;
+- bounded small-fleet operation with signed claim-bound sessions, shared
+  Postgres review state, pools, rate limits, readiness, quorum, dead letters,
+  and backup/restore/retention.
+
+Scoped Explore is an authoring-plane feature, not a production runtime feature.
+It is disabled by default, requires an explicit development/staging profile and
+a demonstrably read-only non-owner role, and is never advertised by production,
+unknown-profile, shared HTTP, remote, or non-loopback surfaces. Production uses
+only activated named capabilities, including capabilities created through
+Protect.
 
 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.
+config schema version `1`, canonical public contracts, result envelopes,
+stdio/Streamable HTTP, established onboarding and CI routes, proposal/evidence/
+replay inspection, guarded writeback, and app-owned executor contracts.
+Existing hand-authored projects do not need Auto Boundary, Workbench,
+generation locks, schema rescans, or new fields; their tool lists do not change
+unless the feature is explicitly adopted.
 
 Out of scope:
 
-- raw `execute_sql`;
-- model-generated SQL;
-- UPSERT, DDL, model-generated predicates, or unguarded INSERT/DELETE;
-- model-generated, unbounded, or cross-table set writeback;
-- physical branching of external Postgres/MySQL;
-- automatic rollback/time travel and inferred compensation for app-owned or
-  external effects;
-- self-hosted Synapsor Cloud;
-- unbounded or multi-region shared-ledger scale and a managed Runner fleet;
-- production SLA or compliance certification.
+- raw `execute_sql`, SQL strings, model-generated SQL, or arbitrary identifiers;
+- production Scoped Explore or a general-purpose analytics/query AST;
+- general join planning, many-to-many exploration, arbitrary formulas,
+  functions, windows, `HAVING`, subqueries, or statistical privacy guarantees;
+- model-selected tenant/principal, activation, approval, or commit authority;
+- UPSERT, DDL, free-form predicates, unbounded writes, or cross-table direct
+  transactions;
+- strict atomic freshness for app-owned handlers, APIs, or cross-source
+  dependencies; those executors own their transaction preconditions;
+- physical branching of external Postgres/MySQL or automatic rollback/time
+  travel;
+- self-hosted Synapsor Cloud, an unbounded/multi-region shared ledger, a managed
+  Runner fleet, production SLA, or compliance certification.

package/docs/cursor-plugin.md

@@ -14,12 +14,12 @@ plugin-reference, MCP, and deeplink documentation on 2026-07-20:
 - <https://cursor.com/docs/reference/deeplinks>
 
 The locally installed Cursor version used for validation is recorded in
-`development/runner-1.5.3-progress.md`. Protocol/static validation is not a
+`development/runner-1.6.0-progress.md`. Protocol/static validation is not a
 claim that Cursor Marketplace review has completed.
 
 ## What the plugin installs
 
-- one stdio MCP server pinned to `@synapsor/runner@1.5.3`;
+- one production stdio MCP server pinned to `@synapsor/runner@1.6.1`;
 - one `/synapsor-protect` agent command;
 - one discoverable Safe Action skill;
 - one file-scoped rule for `synapsor/actions/**/*.ts`;
@@ -29,6 +29,23 @@ The MCP entry uses Cursor's documented `${workspaceFolder}` interpolation for
 `synapsor.runner.json` and `.synapsor/local.db`. It exposes only `mcp serve`.
 Approval, apply, activation, commit, and revert remain outside MCP.
 
+Auto Boundary authoring uses a separate CLI-managed project entry rather than
+the production plugin entry:
+
+```bash
+synapsor-runner mcp install cursor \
+  --project \
+  --authoring \
+  --project-root . \
+  --yes
+```
+
+That temporary local stdio entry is accepted only after exact boundary
+activation and advertises exactly `app.describe_data` and `app.explore_data`.
+After Protect activation, reinstall the normal project config; production then
+advertises only named reviewed capabilities. The plugin never makes Scoped
+Explore available to production, shared HTTP, remote, or non-loopback serving.
+
 ## Build and verify
 
 ```bash
@@ -63,7 +80,7 @@ Required listing media:
 
 ## Submission checklist
 
-- [ ] Runner 1.5.3 package and plugin version agree.
+- [ ] Runner 1.6.1 package and plugin version agree.
 - [ ] `corepack pnpm verify:cursor-plugin` passes from a clean checkout.
 - [ ] Plugin is manually loaded in current stable Cursor at workspace scope.
 - [ ] `/synapsor-protect` drafts and validates without activation.

package/docs/dsl-reference.md

@@ -168,6 +168,84 @@ Aggregate reads cannot declare model arguments, lookup, visible row fields,
 proposal clauses, joins, grouping, or arbitrary expressions. See [Bounded
 Aggregate Reads](aggregate-reads.md).
 
+## Protected named reads
+
+`PROTECTED READ` is the public DSL emitted by Protect This Query. It freezes a
+successful local authoring plan into a named capability. It is not the
+temporary `app.explore_data` plan grammar and it is not a generic query AST.
+
+This aggregate example is representative:
+
+```sql
+CREATE CAPABILITY analytics.churn_contributors_by_week
+  DESCRIPTION 'Describe reviewed weekly churn contributors.'
+  RETURNS HINT 'Returns privacy-suppressed reviewed groups.'
+  USING CONTEXT analytics_operator
+  SOURCE local_postgres
+  ON public.account_churn
+  PRIMARY KEY id
+  TENANT KEY tenant_id
+  ARG period_start STRING REQUIRED MAX LENGTH 32
+  ARG period_end STRING REQUIRED MAX LENGTH 32
+  PROTECTED READ AGGREGATE
+  BOUNDARY DIGEST sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+  GENERATION LOCK sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
+  PROTECTED FILTER status EQ FIXED 'churned'
+  PROTECTED FILTER churned_at GTE ARG period_start
+  PROTECTED FILTER churned_at LT ARG period_end
+  MEASURE churned_accounts COUNT ROWS
+  MEASURE affected_customers COUNT DISTINCT customer_id
+  GROUP DIMENSION region BY region
+  GROUP DIMENSION reason BY churn_reason
+  TIME DIMENSION churn_week BY WEEK OF churned_at
+  AGGREGATE ORDER BY MEASURE churned_accounts DESC
+  TOP 20 GROUPS
+  MIN GROUP SIZE 5
+  KEEP OUT email, private_notes
+  REQUIRE EVIDENCE
+  PROTECTED LIMITS ROWS 50 GROUPS 50 CELLS 500 BYTES 65536 TIMEOUT MS 3000 QUERIES 40 EXTRACTED CELLS 4000 DIFFERENCING 6 RATE PER MINUTE 20
+END
+```
+
+In that example, uppercase phrases such as `PROTECTED READ AGGREGATE`,
+`BOUNDARY DIGEST`, `MEASURE`, `GROUP DIMENSION`, and `TOP ... GROUPS` are DSL
+keywords. Names such as `analytics.churn_contributors_by_week`,
+`churned_accounts`, `affected_customers`, `region`, and `churn_week` are
+user-reviewed identifiers. Table/column references such as
+`public.account_churn`, `customer_id`, and `churned_at` come from inspected
+schema evidence and are frozen into the capability.
+
+The protected clauses mean:
+
+| Clause | Reviewed meaning |
+| --- | --- |
+| `PROTECTED READ ROWS` / `AGGREGATE` | Selects a frozen row or aggregate protected-read shape. |
+| `BOUNDARY DIGEST sha256:...` | Binds the capability to the exact human-activated exploration authority. |
+| `GENERATION LOCK sha256:...` | Binds it to the reviewed schema, role/grant/RLS posture, compiler, and Spec fingerprint. |
+| `PROTECTED RELATIONSHIP name ON local_key REFERENCES schema.table.target_key PRIMARY KEY pk TENANT KEY tenant [PRINCIPAL SCOPE KEY principal]` | Freezes at most one inspected, reviewed many-to-one path with fan-out one. |
+| `PROTECTED FILTER field OP FIXED value` | Freezes a reviewed literal. `OP` is `EQ`, `NEQ`, `LT`, `LTE`, `GT`, `GTE`, or bounded fixed-list `IN`. |
+| `PROTECTED FILTER field OP ARG name` | Allows only one declared typed/bounded argument at that reviewed literal position. |
+| `ALLOW READ ...` / `ROW ORDER BY ...` | Freezes row projection and up to three fixed sort fields for row mode. |
+| `MEASURE alias COUNT ROWS` | Counts the reviewed subject entity. |
+| `MEASURE alias COUNT DISTINCT field` | Counts distinct values of a field approved for aggregate use; the raw values need not be visible. |
+| `MEASURE alias SUM|AVG field` | Uses an explicitly approved aggregate-safe numeric measure. |
+| `GROUP DIMENSION alias BY field` | Freezes a reviewed categorical grouping. |
+| `TIME DIMENSION alias BY DAY|WEEK|MONTH OF field` | Freezes one reviewed timestamp and bucket. |
+| `COMPARE RANGE field FROM value TO value` | Freezes at most two bounded reviewed time ranges. |
+| `TOP n GROUPS` / `MIN GROUP SIZE n` | Fixes output breadth and cohort suppression. |
+| `PROTECTED LIMITS ...` | Fixes row/group/response/time/query/extraction/differencing/rate budgets; MCP arguments cannot widen them. |
+
+Protect normally generates this verbose authority block so that reviewers do
+not have to transcribe digests or limits. The generated DSL compiles through
+`@synapsor/dsl` into the optional default-deny `protected_read` field in the
+canonical Spec. Existing contracts with no `protected_read` field normalize
+and hash exactly as before.
+
+Protected row and aggregate capabilities can be served after exact-digest
+activation even when temporary Scoped Explore is disabled. Production never
+needs or advertises `app.explore_data`. See [Auto Boundary, Scoped Explore, And
+Protect](auto-boundary-and-scoped-explore.md).
+
 ## Read surface and evidence
 
 ```sql

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

@@ -1,62 +1,66 @@
 # Connect Your Own Database
 
-Use this path after the Docker demo passes and you want to try Synapsor Runner
-against a staging or disposable Postgres/MySQL database.
+Use this path after the synthetic proof passes and you want to try Synapsor
+Runner against a staging or disposable Postgres/MySQL database.
 
 Do not start with your most sensitive production database. Runner is a
-commit-safety runtime for reviewed single-row business actions, not a
-production certification.
+reviewed data boundary, not a production certification.
 
 If you only ran `synapsor-runner demo --quick`, you have tested the fixture-only
 teaching path and local ledger commands. This page is the real own-database
-path: it inspects your Postgres/MySQL metadata and generates reviewed semantic
-tools from your selections.
+path. Auto Boundary inspects the whole selected schema, combines deterministic
+database/Prisma/Drizzle/OpenAPI/Synapsor evidence, and generates disabled
+review artifacts without sampling source rows or using an LLM.
 
 ## Fast path
 
-Set one read-only database URL and run the public guided path:
+Set a dedicated SELECT-only, non-owner database URL plus trusted development
+scope and run the public guided path:
 
 ```bash
 export DATABASE_URL="<postgres-or-mysql-read-url>"
+export SYNAPSOR_TENANT_ID="<staging-tenant>"
+export SYNAPSOR_PRINCIPAL="<developer-id>"
 npx -y -p @synapsor/runner synapsor-runner start --from-env DATABASE_URL
 ```
 
-That command does the useful local mini-Synapsor path:
+A fresh interactive project with no existing config, selector, or automation
+input follows:
 
 ```text
-inspect your schema
--> choose one table/view
--> choose trusted scope and visible fields
--> optionally choose proposal/writeback rules
--> generate synapsor.runner.json + canonical synapsor.contract.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
--> open the secured localhost first-action workbench in an interactive terminal
+inspect the whole selected schema and structured application artifacts
+-> draft disabled public DSL, canonical JSON, tests, and generation lock
+-> review scope, fields, analytics permissions, relationships, and budgets
+-> activate the exact exploration-boundary digest in local Workbench
+-> install exactly app.describe_data and app.explore_data in Cursor
+-> ask a bounded row or PM-style aggregate question against staging
+-> Protect This Query into a disabled named capability
+-> activate that exact digest and remove broad Explore
+-> serve only the named protected capability in production
 ```
 
 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.
+credentials. Before boundary activation it does not read source rows.
 
 `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.
-
-Interactive `start` opens the focused local workbench after config validation
-and an MCP boundary handshake. Use `--no-open` for CI or scripts. That handshake
-proves the reviewed tool surface; the workbench's **Test** step remains pending
-until a real scoped read is recorded in the local ledger.
-
-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.
+Read [Auto Boundary, Scoped Explore, And
+Protect](auto-boundary-and-scoped-explore.md) for the complete command and
+security reference.
+
+Established routes remain unchanged. `--table`, `--answers`, `onboard db`,
+explicit `init` flags, existing configs, headless startup, JSON output, and CI
+do not enter Auto Boundary, prompt unexpectedly, open a browser, rescan an
+existing project, or require a generation lock. For example:
+
+```bash
+synapsor-runner start --from-env DATABASE_URL --table invoices --no-open
+synapsor-runner onboard db --from-env DATABASE_URL --answers ./answers.json
+```
+
+The rest of this page documents those established one-object/manual routes.
+They remain supported for existing projects and automation. From a source
+checkout, use `./bin/synapsor-runner ...` if the global binary is not linked.
 
 From a source checkout, `./scripts/use-your-db.sh` runs the same kind of
 guided flow plus local repository checks.

package/docs/limitations.md

@@ -1,9 +1,11 @@
 # Limitations
 
-Synapsor Runner is intentionally narrow. Version 1.4 adds opt-in reviewed
-compensation on top of guarded bounded-set writeback, single-row CRUD, and
-explicit receipt authority; it does not claim Synapsor Cloud scale or an
-enterprise SLA.
+Synapsor Runner is intentionally narrow. Version 1.6 adds deterministic
+whole-application boundary drafting and a local authoring-only Explore ->
+Protect path on top of guarded writes. Version 1.6.1 also adds opt-in
+proposal/evidence freshness for exact same-source direct-SQL proposals. It does
+not turn Runner into a generic database query tool, claim Synapsor Cloud scale,
+or claim an enterprise SLA.
 
 ## Supported
 
@@ -15,6 +17,9 @@ enterprise SLA.
 - Native Postgres/MySQL source pools and operational/fleet-wide rate limits.
 - Verified operator approval through CLI, optional distinct-reviewer quorum,
   and shared local review UI reads.
+- Optional live target and explicitly declared supporting-row freshness checks
+  before every approval, with immutable proof binding and final transactional
+  revalidation for PostgreSQL/MySQL direct SQL writeback.
 - Separately protected scrapeable metrics and dead-letter recovery commands.
 - Shared-ledger backup/digest verification, clean restore, and
   archive-before-retention.
@@ -49,6 +54,19 @@ enterprise SLA.
 - Capability recipes that generate reviewed starter configs.
 - Shadow-mode proposal-vs-human-action comparison.
 - Static MCP database risk review.
+- Deterministic whole-schema Auto Boundary drafting from database metadata,
+  statically parsed Prisma/Drizzle schema artifacts, OpenAPI documents, and
+  existing Synapsor definitions. Generated authority starts disabled.
+- Local development/staging Scoped Explore through exactly
+  `app.describe_data` and `app.explore_data`, with no SQL-string argument.
+- Reviewed PM-style aggregate Explore with `count`, `count_distinct`, `sum`,
+  `avg`, categorical dimensions, fixed time buckets, typed filters, bounded
+  top-N, optional one-hop proven many-to-one relationships, cohort suppression,
+  and durable extraction/differencing budgets.
+- Protect This Query to public DSL, canonical JSON, tests, and a disabled named
+  capability that survives Explore shutdown after exact-digest activation.
+- Generation-lock drift detection for generated authority. Manually authored
+  projects without a lock retain their previous behavior.
 - 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
@@ -77,6 +95,8 @@ truth for the model-facing tools.
 - Policy auto-approval for bounded sets.
 - Stored procedures.
 - Cross-database transactions.
+- Strict atomic proposal freshness across databases, app-owned handlers, or
+  external APIs. Those paths must enforce their own final preconditions.
 - Physical branching of Postgres/MySQL.
 - Full Synapsor workflow/DAG execution.
 - `CREATE AGENT WORKFLOW` or hosted Synapsor SQL generation.
@@ -89,8 +109,12 @@ 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.
+- Production, shared HTTP, remote, or non-loopback Scoped Explore.
+- Arbitrary aggregate expressions, dynamic identifiers, unrestricted joins,
+  many-to-many joins, formulas, window functions, subqueries, `HAVING`,
+  user-defined functions, or a statistical privacy guarantee. Version 1.6
+  supports only the explicitly reviewed authoring cube described above and
+  fixed protected named capabilities produced from it.
 - Automatic policy widening or activation from graduated-trust metrics.
 - Immutable/WORM compliance storage from the local report exporter.
 
@@ -120,7 +144,7 @@ not a hosted central evidence service, organization RBAC/SSO, compliance
 retention system, or unbounded search engine. Each bridge operation serializes
 through an advisory lock and fails above configured `max_entries`.
 
-Only homogeneous 1.4 fleet operation is claimed for protocol-v4 compensation
+Only homogeneous 1.x fleet operation is claimed for protocol-v4 compensation
 jobs. Mixed-minor v3/v4 rolling compensation is not claimed.
 See [Running A Small Runner
 Fleet](running-a-runner-fleet.md).
@@ -146,3 +170,9 @@ as equivalent to a durable version column.
 Runner-ledger UPDATE and DELETE require an exact guard; UPDATE must advance it
 inside the source transaction. INSERT requires a reviewed source-unique dedup
 identity. See [Guarded Single-Row CRUD Writeback](guarded-crud-writeback.md).
+
+Approval-time freshness also depends on a correct exact version column. It
+does not freeze source state until apply. Direct SQL apply rechecks again;
+app-owned/cross-source effects do not receive that Runner-owned atomic
+guarantee. See
+[Proposal And Evidence Freshness](proposal-evidence-freshness.md).

package/docs/local-mode.md

@@ -140,10 +140,19 @@ Show a proposal:
 npx -y -p @synapsor/runner synapsor-runner proposals show wrp_123 --store ./.synapsor/local.db
 ```
 
+Check a freshness-enabled proposal without copying its id:
+
+```bash
+npx -y -p @synapsor/runner synapsor-runner proposals check-freshness latest \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+```
+
 Approve:
 
 ```bash
 npx -y -p @synapsor/runner synapsor-runner proposals approve wrp_123 \
+  --config ./synapsor.runner.json \
   --store ./.synapsor/local.db \
   --actor local_reviewer \
   --yes
@@ -151,6 +160,14 @@ npx -y -p @synapsor/runner synapsor-runner proposals approve wrp_123 \
 
 Before approval, the CLI prints the reviewer-critical proposal details: trusted principal, tenant, target row, primary key, required role, proposal hash/version, allowed columns, conflict guard, evidence bundle/query fingerprint, writeback boundary, source mutation state, and exact before/after diff. Interactive approval still requires typing `yes`; noninteractive scripts must pass `--yes`.
 
+When `proposal_freshness` is configured for that capability, approval also
+performs a live read-only check of the target and each declared same-source
+supporting dependency. A fresh result is bound to the approval by proof digest.
+A stale result records no approval and terminally conflicts the proposal; an
+unavailable source records no approval and leaves it pending. Apply always
+revalidates again because source data can change after approval. See
+[Proposal And Evidence Freshness](proposal-evidence-freshness.md).
+
 Create a guarded writeback job from an approved proposal:
 
 ```bash
@@ -203,9 +220,11 @@ npx -y -p @synapsor/runner synapsor-runner ui --config synapsor.runner.json --st
 ```
 
 The UI shows setup summary, semantic tools, proposal states, exact diffs,
-evidence, approval state, receipts, and replay. It binds to `127.0.0.1` by
-default, uses a per-run local session token, and requires CSRF protection for
-approve/reject actions.
+evidence, live freshness state, approval state, receipts, and replay. A
+freshness-required approve control stays disabled until the live result is
+fresh; the approve request performs another live check. The UI binds to
+`127.0.0.1` by default, uses a per-run local session token, and requires CSRF
+protection for approve/reject actions.
 
 The UI does not expose raw SQL, database URLs, password values, MCP approval
 tools, MCP commit tools, or controls that widen configured tables/columns.

package/docs/production.md

@@ -191,6 +191,16 @@ business action, transaction boundaries, and safe errors. See
 [Writeback Executors](writeback-executors.md) and
 [Handler Helper](handler-helper.md).
 
+For a direct SQL proposal whose approval depends on live source facts, use the
+optional `proposal_freshness` overlay. It rechecks the target and declared
+same-source supporting rows before approval, then locks and rechecks them again
+inside the final PostgreSQL/MySQL transaction. Run
+`doctor --check-writeback` to prove that the writer can perform every
+dependency locking read. App-owned and cross-source effects must enforce their
+own equivalent transactional preconditions; Runner rejects them from strict
+freshness mode. See
+[Proposal And Evidence Freshness](proposal-evidence-freshness.md).
+
 ## Local Ledger
 
 Default local ledger path:
@@ -589,6 +599,10 @@ Doctor reports should be redacted by default before sharing. They must not
 include database passwords, bearer tokens, handler secrets, or raw driver
 connection strings.
 
+For freshness-enabled proposals, `--check-writeback` includes rollback-only
+dependency lock probes. A passing metadata/read check alone does not prove that
+the writer has the locking privilege needed at apply.
+
 ## Logging And Redaction
 
 Expected public outputs must avoid secrets in:
@@ -613,3 +627,8 @@ 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.
+The 1.6.1 security gate additionally runs:
+
+```bash
+corepack pnpm test:proposal-freshness
+```