@synapsor/runner 1.5.4 → 1.6.1

package/docs/README.md

@@ -47,10 +47,14 @@ no-database demo, wire your database, then read deeper concepts.
 
 ## 04 Connect Your DB
 
+- [Auto Boundary, Scoped Explore, And
+  Protect](auto-boundary-and-scoped-explore.md): deterministically inspect a
+  whole staging application, review one digest-bound boundary, ask bounded row
+  and PM-style aggregate questions in Cursor, and turn a useful query into a
+  disabled named production capability.
 - [Connect Your Own Database](getting-started-own-database.md): inspect a
-  staging Postgres/MySQL database, generate canonical reviewed artifacts, open
-  the first-action workbench, add the tools to Cursor, and inspect the local
-  activation report.
+  staging Postgres/MySQL database through the new whole-schema path or an
+  established one-object/headless route.
 - [Use Your Own Database](use-your-own-database.md): short entry point that
   links to the canonical own-database guide.
 - [Fresh-Developer Usability Protocol](fresh-developer-usability.md): the
@@ -72,6 +76,10 @@ no-database demo, wire your database, then read deeper concepts.
 
 ## 05 Generate Capabilities
 
+- [Auto Boundary, Scoped Explore, And
+  Protect](auto-boundary-and-scoped-explore.md): generate disabled public DSL
+  from deterministic schema/ORM/OpenAPI evidence, then Protect a reviewed
+  exploratory plan without giving the model SQL or activation authority.
 - [Connect Your Own
   Database](getting-started-own-database.md#draft-another-safe-action-with-a-coding-agent):
   describe one action, let a coding agent complete only the restricted
@@ -101,8 +109,8 @@ no-database demo, wire your database, then read deeper concepts.
 - [Agent Effect Regression](effect-regression.md): provider-neutral,
   propose-only fixtures that catch changed capability calls, business diffs,
   policy outcomes, tenant handling, and hidden-field behavior.
-- [Bounded Aggregate Reads](aggregate-reads.md): fixed scalar count/sum/avg,
-  tenant scope, suppression, and no-row evidence.
+- [Bounded Aggregate Reads](aggregate-reads.md): fixed production scalar
+  aggregates plus the separate authoring-only reviewed aggregate Explore path.
 
 ## 06 Serve MCP
 
@@ -172,7 +180,7 @@ no-database demo, wire your database, then read deeper concepts.
 
 ## 10 Concepts
 
-- [Current Scope](current-scope.md): compact v0.1 scope summary.
+- [Current Scope](current-scope.md): compact current 1.x scope summary.
 - [Current Limitations](limitations.md): intentional safety limits.
 - [Production-Candidate Guide](production.md): single-node and bounded-fleet
   OSS deployment scope, database roles, receipt grants, restart

package/docs/aggregate-reads.md

@@ -1,5 +1,18 @@
 # Bounded Aggregate Reads
 
+There are two distinct aggregate surfaces:
+
+1. A fixed named `aggregate_read` capability, described on this page, is
+   production-capable and returns one contract-authored scalar.
+2. Runner 1.6.0 Scoped Aggregate Explore is a temporary local development/
+   staging authoring tool. It accepts only a typed plan inside a human-activated
+   analytical boundary, supports reviewed dimensions and time buckets, and
+   must be converted through Protect into a named production capability.
+
+Neither surface accepts SQL strings or arbitrary identifiers. Read
+[Auto Boundary, Scoped Explore, And
+Protect](auto-boundary-and-scoped-explore.md) for the second path.
+
 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.
@@ -47,3 +60,12 @@ 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.
+
+Scoped Aggregate Explore reuses and extends this suppression machinery. Its
+reviewed boundary additionally fixes aggregate-safe measures,
+`count_distinct` identifiers, dimensions, day/week/month buckets, typed
+filters, optional one-hop proven many-to-one relationships, maximum groups,
+response/query/rate limits, and durable extraction/differencing budgets. A
+field may be approved for `count_distinct` while its raw values remain hidden.
+Production receives only the protected named capability; broad Explore is
+absent from production `tools/list`.

package/docs/app-owned-executors.md

@@ -24,6 +24,14 @@ the receipt, and includes the result in replay.
 > error receipts. If you skip those checks, you can reintroduce cross-tenant
 > writes, lost updates, or duplicate writes. Keep handler credentials out of MCP.
 
+Runner 1.6.1 strict `proposal_freshness` is limited to same-database direct SQL
+writeback. Runner rejects it for `http_handler`, `command_handler`, and
+cross-source dependencies because a local preflight cannot be atomic with an
+effect executed elsewhere. If supporting evidence matters, the app handler
+must lock and re-read those rows inside its own business transaction and fail
+closed on drift. See
+[Proposal And Evidence Freshness](proposal-evidence-freshness.md).
+
 A handler is your application endpoint or script. It is not a second Synapsor
 package that users need to install. Install `@synapsor/runner`, then generate
 or copy a handler template only when your approved write needs app-owned

package/docs/auto-boundary-and-scoped-explore.md

@@ -0,0 +1,338 @@
+# Auto Boundary, Scoped Explore, And Protect
+
+Runner 1.6.0 adds a deterministic authoring path for a real application:
+
+```text
+Connect staging
+-> draft the boundary
+-> review and activate its exact digest
+-> explore through two bounded MCP tools
+-> protect a useful query
+-> activate the named capability
+-> disable exploration
+-> serve only named production tools
+```
+
+This path does not give the model SQL, database credentials, tenant identity,
+approval, activation, or commit authority. Auto Boundary and Protect use no
+LLM. Existing hand-authored contracts and established onboarding commands
+continue to work without this feature.
+
+## Start With Staging
+
+Use a dedicated SELECT-only, non-owner database role. Keep database-level
+controls underneath Runner. PostgreSQL deployments should use forced row-level
+security (RLS) where possible; MySQL deployments should use restricted views or
+tenant-bound credentials.
+
+Export the connection and trusted context in the process that Cursor will use:
+
+```bash
+export DATABASE_URL='postgresql://runner_reader:REPLACE_ME@127.0.0.1:5432/app'
+export SYNAPSOR_TENANT_ID='acme'
+export SYNAPSOR_PRINCIPAL='pm-1'
+
+npx -y @synapsor/runner start --from-env DATABASE_URL --schema public
+```
+
+A fresh interactive invocation with no existing config, selector, or automation
+input enters Auto Boundary. It scans the whole selected schema and opens the
+secured loopback Workbench. The initial npm download is not part of Runner's
+measured onboarding time.
+
+For scripts or CI, draft without prompts or a browser:
+
+```bash
+synapsor-runner boundary draft \
+  --from-env DATABASE_URL \
+  --schema public \
+  --project-root . \
+  --json
+```
+
+Established `--table`, `--answers`, `onboard db`, `--mode`, JSON, and
+noninteractive routes keep their previous one-object behavior.
+
+## What Auto Boundary Reads
+
+Runner builds one deterministic evidence graph from:
+
+- database catalogs, keys, constraints, grants, ownership, RLS, triggers, and
+  cascades;
+- statically parsed Prisma schema files;
+- statically parsed Drizzle schema files;
+- OpenAPI documents;
+- existing Synapsor DSL, canonical JSON, and TypeScript definitions.
+
+It does not import or execute adopter code. Database, ORM, and API comments are
+naming evidence only. They never grant field access, trusted scope, write
+authority, approval, or activation.
+
+Runner can determine structure such as primary keys, foreign keys, enums,
+likely version columns, and possible deduplication keys. It cannot determine
+business authority such as:
+
+- which column is the real tenant boundary;
+- whether a principal may see every tenant row or only assigned rows;
+- whether a field is appropriate for an agent;
+- which state transition, refund, credit, or delete is permitted;
+- which evidence, bounds, reviewers, or auto-approval policy are required.
+
+Those decisions remain explicit human review.
+
+## Generated Files
+
+Auto Boundary writes disabled review artifacts:
+
+```text
+synapsor/generated/
+  domain.synapsor.sql
+  read-capabilities.synapsor.sql
+  synapsor.candidate.contract.json
+  exploration-boundary.draft.json
+  generation-review.json
+  contract-tests.json
+  REVIEW.md
+
+.synapsor/
+  generation-lock.json
+  review-report.json
+```
+
+The `.synapsor.sql` files compile through `@synapsor/dsl` into the canonical
+`@synapsor/spec` JSON contract. The generation lock records non-secret
+fingerprints of the inspected schema, compiler/spec version, exact database
+role, grants, ownership, and RLS posture. Generated read drafts and action
+candidates start disabled. Auto Boundary never replaces an active contract.
+
+No source rows, credentials, tenant values, or principal values are written to
+these files.
+
+## Review The Boundary
+
+The Workbench requires a human to narrow and confirm:
+
+- development or staging deployment profile;
+- trusted tenant and principal bindings supplied outside model arguments;
+- included resources and one-hop relationships;
+- selectable fields;
+- filterable fields and allowed operators;
+- sortable and groupable fields;
+- aggregate-safe numeric measures;
+- identifiers allowed only for `count_distinct`;
+- timestamp fields and permitted day/week/month buckets;
+- kept-out fields;
+- counted entity and relationship cardinality;
+- minimum cohort size;
+- row, group, measure, dimension, time-range, response, rate, extraction, and
+  differencing budgets;
+- the current schema fingerprint and exact database-role/RLS posture.
+
+Kept-out fields are unavailable for selection, filtering, sorting, grouping,
+joining, aggregation, and `count_distinct`.
+
+Raw visibility and aggregate use are separate permissions. A reviewer may
+allow `count_distinct(customer_id)` while keeping every `customer_id` value out
+of results.
+
+Workbench activation requires every generated decision, the operator identity,
+and the exact confirmation:
+
+```text
+ACTIVATE sha256:...
+```
+
+The immutable digest covers the reviewed resources, field permissions,
+relationships, scope, role posture, generation lock, compiler/spec version,
+profile, and every query/privacy budget. Model arguments cannot widen it.
+
+## Add The Authoring Tools To Cursor
+
+After activation, let Runner manage only its own project entry:
+
+```bash
+synapsor-runner mcp install cursor \
+  --project \
+  --authoring \
+  --project-root . \
+  --yes
+
+synapsor-runner mcp status cursor --project
+```
+
+The Cursor config contains command paths and package identity, not database
+URLs, credential values, tenant values, or principal values. Authoring mode
+uses local stdio and advertises exactly:
+
+```text
+app.describe_data
+app.explore_data
+```
+
+`app.describe_data` is bounded and paginated over only the activated resource
+pack. `app.explore_data` accepts a structured plan. Neither tool exposes SQL,
+approval, apply, activation, commit, or revert.
+
+## Scoped Row Explore
+
+A row plan can select, filter, sort, and limit only fields and operators in the
+activated boundary. Runner injects tenant and principal scope outside model
+arguments and compiles the validated plan into parameterized SQL.
+
+Scoped Explore does not accept:
+
+- a SQL string or fragment;
+- arbitrary identifiers, functions, expressions, aliases, or subqueries;
+- a model-supplied tenant or principal;
+- unreviewed fields or relationships;
+- model-widened row, byte, time, rate, or extraction limits.
+
+## Scoped Aggregate Explore
+
+The aggregate surface is a small reviewed analytical cube, not a generic
+analytics database tool. It supports:
+
+- `count`;
+- `count_distinct` on explicitly reviewed identifiers;
+- `sum` and `avg` on explicitly reviewed numeric measures;
+- reviewed categorical dimensions;
+- day, week, and month buckets on reviewed timestamps;
+- typed bounded filters;
+- ordering by a returned aggregate;
+- bounded top-N results;
+- at most two reviewed time ranges;
+- one resource by default;
+- at most one inspected, reviewed many-to-one foreign-key path with maximum
+  fan-out one.
+
+It does not support arbitrary `DISTINCT`, `HAVING`, formulas, window functions,
+unions, nested queries, many-to-many joins, system catalogs, user-defined
+functions, or a general join planner. Scope is enforced independently on every
+participating relation. Runner refuses a plan when cardinality, fan-out,
+counted entity, or scope cannot be proven.
+
+Before returning groups, Runner enforces the reviewed minimum cohort size.
+Small groups are suppressed and revealing totals are withheld. Durable
+per-session extraction and differencing budgets block repeated slightly
+different queries that could reconstruct a suppressed cohort. Pagination
+cannot bypass the maximum group count.
+
+Results describe changes, comparisons, correlations, and likely contributors.
+They do not establish causation.
+
+## Runtime Enforcement
+
+Scoped Explore is disabled by default and authoring-only. It starts only when
+all of these are true:
+
+- the profile is explicitly `development` or `staging`;
+- the transport is local stdio or secured loopback Workbench traffic;
+- the exact exploration-boundary digest is active;
+- the generation lock and compiler/spec versions are current;
+- the role/grant/ownership/RLS fingerprint still matches;
+- the credential is demonstrably SELECT-only and non-owner;
+- every query also runs in an enforced read-only transaction.
+
+Missing, malformed, unknown, and production profiles are treated as
+production. A superuser, relation owner, write-capable role, `BYPASSRLS` role,
+or unverifiable role may inspect metadata with a warning but cannot read source
+rows through Scoped Explore.
+
+Shared HTTP, Streamable HTTP, remote, and non-loopback runtimes never register
+or advertise broad Explore tools.
+
+## Audit And Temporary Protect State
+
+Every successful call records a normalized query audit in
+`.synapsor/local.db`. Audit may retain:
+
+- active boundary digest;
+- reviewed resource/relationship aliases;
+- operators and time buckets;
+- keyed hashes of filter literals;
+- timing, suppression decisions, and result-size metadata.
+
+It does not retain returned rows/groups, credentials, raw sensitive literals,
+or trusted tenant/principal values.
+
+A successful query also creates encrypted, expiring local Protect state. The
+Workbench discovers recent queries itself; developers do not copy opaque
+handles.
+
+## Protect This Query
+
+Choose the useful query in Workbench. Protect freezes:
+
+- resources and reviewed relationship path;
+- counted entity, measures, dimensions, and bucket structure;
+- filters, ordering, top-N, and comparison shape;
+- tenant/principal as trusted bindings;
+- cohort suppression and query/privacy budgets.
+
+Reviewed literals remain fixed by default. A human may convert selected
+literals into typed bounded arguments.
+
+Protect writes:
+
+```text
+synapsor/protected/drafts/analytics__churn_contributors_by_week/
+  capability.synapsor.sql
+  synapsor.contract.json
+  contract-tests.json
+  REVIEW.md
+  draft.json
+```
+
+The public DSL compiles into the canonical Spec. The generated capability
+starts disabled and includes positive, scope, suppression, differencing,
+join-safety, deny, drift, and boundary tests. It becomes active only after a
+human reviews and confirms its exact contract digest outside MCP.
+
+When activation disables temporary Explore, the named capability remains
+available. Update Cursor from authoring mode to the production config:
+
+```bash
+synapsor-runner mcp install cursor \
+  --project \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --yes
+```
+
+Production then advertises only reviewed named capabilities. It does not
+advertise `app.explore_data`.
+
+## Schema Drift
+
+Check generated authority against the current database:
+
+```bash
+synapsor-runner boundary status --json
+synapsor-runner boundary diff --json
+```
+
+Additive schema fields and objects receive no authority. A changed schema,
+database role, grant, ownership, RLS posture, compiler, or canonical Spec
+invalidates the generation lock. Lock-bound generated authority fails closed
+until the operator regenerates, reviews the semantic diff, and activates the
+new exact digest.
+
+This drift lifecycle applies only to generated authority explicitly bound to a
+generation lock. Existing manually authored projects without a lock retain
+their previous startup, `doctor`, contract, and tool behavior.
+
+## Verify The Reference Journey
+
+The packaged synthetic fixture is under `examples/auto-boundary-churn`.
+
+From a source checkout:
+
+```bash
+corepack pnpm test:auto-boundary-explore
+corepack pnpm test:auto-boundary-explore:packed
+```
+
+The packed gate proves the PostgreSQL + Next.js + Prisma + Cursor-compatible
+MCP + Workbench flow, all aggregate denial/suppression/budget checks, Protect,
+production Explore absence, protected-capability survival, durable redacted
+audit, and an unchanged source database.

package/docs/capability-authoring.md

@@ -180,6 +180,35 @@ near-duplicate tools. These checks make breadth drift visible; they do not
 change canonical validity or replace human review. See [Contract
 Review](contract-review.md) for exact codes and behavior.
 
+## Auto-Generated And Protected Reads
+
+For a new application, you do not need to hand-author the initial DSL.
+`start --from-env DATABASE_URL` can deterministically inspect the whole staging
+schema, combine static Prisma/Drizzle/OpenAPI/Synapsor evidence, and emit
+disabled `.synapsor.sql`, canonical JSON, tests, review evidence, and a
+generation lock. It does not sample source rows before activation or use an
+LLM.
+
+After a human activates the exact local exploration boundary, Cursor receives
+only `app.describe_data` and `app.explore_data`. A useful typed row or
+aggregate plan can be converted through Protect This Query into a named
+capability. Protect emits public DSL such as `PROTECTED READ ROWS` or
+`PROTECTED READ AGGREGATE`, compiles it to canonical `protected_read`
+authority, and starts it disabled. Exact-digest activation is still outside
+MCP.
+
+The named protected capability freezes resources, optional reviewed
+many-to-one relationship, predicates, projection or aggregate measures,
+dimensions, bucket, ordering, result bounds, suppression, and privacy/query
+budgets. Only explicitly selected typed literal positions become arguments.
+Tenant and principal remain trusted bindings.
+
+This is additive. Existing DSL, canonical JSON, TypeScript authoring, direct
+Runner config, active contracts, and CI/headless routes do not require Auto
+Boundary, Workbench, generation locks, or schema rescans. See [Auto Boundary,
+Scoped Explore, And Protect](auto-boundary-and-scoped-explore.md) and the
+[protected-read DSL](dsl-reference.md#protected-named-reads).
+
 ## DSL / JSON Capability Parity
 
 The DSL compiles to canonical `@synapsor/spec` JSON. It must not silently weaken
@@ -203,6 +232,7 @@ reviewed runner JSON capabilities. Current parity:
 | proposal `writeback` | `WRITEBACK DIRECT SQL`, `WRITEBACK APP HANDLER EXECUTOR name`, `WRITEBACK CLOUD WORKER`, `WRITEBACK NONE` | 0.1.7 | Handler URLs/tokens stay in `synapsor.runner.json`; contracts carry only the handler name. |
 | proposal `reversibility` | `REVERSIBLE` | 1.4 | Direct SQL only. Captures a bounded inverse after unambiguous apply; operator `revert` creates a new independently approved proposal. |
 | evidence options | `REQUIRE EVIDENCE` | 0.1 | Detailed evidence sources/handle prefixes are not expressible in DSL yet; use embedded JSON or generated contract JSON for those. |
+| capability `protected_read` | `PROTECTED READ ROWS\|AGGREGATE` plus `BOUNDARY DIGEST`, `GENERATION LOCK`, reviewed filters/read or aggregate clauses, and `PROTECTED LIMITS` | 1.5 | Optional default-deny named authority produced by Protect. Existing contracts without this field retain their previous normalization and digest. |
 
 ## Direct Runner Config Path
 
@@ -354,6 +384,38 @@ surface.
 }
 ```
 
+### Optional Live Freshness
+
+The proposal's exact `conflict_guard` already protects its target at apply.
+Runner 1.6.1 can additionally recheck that target before local approval and can
+bind explicitly reviewed supporting rows to both approval and apply.
+
+This is deployment wiring, not DSL or canonical contract syntax:
+
+```json
+{
+  "proposal_freshness": {
+    "billing.propose_late_fee_waiver": {
+      "approval": "required",
+      "dependencies": [
+        {
+          "id": "payment_status",
+          "capability": "billing.inspect_payment",
+          "identity_from_arg": "payment_id",
+          "version_column": "version"
+        }
+      ]
+    }
+  }
+}
+```
+
+`billing.inspect_payment` must be an existing reviewed single-row read on the
+same source and trusted context. `payment_id` is an existing scalar proposal
+argument; the model cannot choose the dependency table, version column, tenant,
+principal, or whether the check runs. See
+[Proposal And Evidence Freshness](proposal-evidence-freshness.md).
+
 ## Trusted Context
 
 Tenant, principal, approval authority, source ids, and row-version authority
@@ -438,6 +500,12 @@ Runner validates:
 - one affected row;
 - idempotency receipt.
 
+When the proposal opts into `proposal_freshness`, the direct SQL adapter also
+locks and compares every declared supporting row inside the same transaction
+before touching the target. A mismatch returns a freshness conflict and zero
+affected rows. Run `doctor --check-writeback` to verify that the writer can
+perform those dependency locking reads.
+
 INSERT additionally requires a source-unique dedup key. DELETE requires an exact
 version guard and fails closed on widening cascades or write triggers.
 
@@ -459,6 +527,13 @@ inserting an outbox event, updating multiple app tables, calling your own
 service, or creating a row whose source constraints cannot satisfy native
 single-row INSERT guards.
 
+Runner's strict `proposal_freshness` overlay does not support app-owned or
+cross-source effects because Runner cannot make their source checks and effect
+atomic. The handler must independently lock/re-read all relevant state and
+enforce the exact proposal, scope, version, transaction, and idempotency
+preconditions described in
+[Proposal And Evidence Freshness](proposal-evidence-freshness.md).
+
 In DSL, keep the reviewed business contract portable and name the executor:
 
 ```sql

package/docs/conformance.md

@@ -33,6 +33,9 @@ Current fixture groups:
 - `bounded-set-threats`
 - `reversible-change-sets`
 - `principal-row-scope`
+- protected named row/aggregate parity is covered by the Spec/DSL tests, the
+  packaged Auto Boundary golden path, and the Cloud/C++ fixture described
+  below.
 
 The fixture set is intentionally small in 0.1. It covers the runner-supported
 semantic surface first: trusted context, scoped reads, evidence handles,
@@ -59,6 +62,12 @@ The principal-row-scope fixture proves that a reviewed owner/assignee column is
 bound to a required trusted principal and AND-composed with tenant scope. Run
 `corepack pnpm test:principal-scope` for the live Postgres/MySQL proof covering
 same-tenant denial and shared-ledger evidence-handle isolation.
+The protected-read parity fixture proves digest- and generation-lock-bound
+named reads, fixed predicates, reviewed measures/dimensions/time buckets,
+one-hop many-to-one limits, suppression, response/query/extraction/
+differencing budgets, and rejection of raw SQL or model-controlled trusted
+scope. `corepack pnpm test:auto-boundary-explore:packed` proves the complete
+authoring-to-production behavior through packed public artifacts.
 
 Additional 0.1 parity coverage currently lives in tests and verification
 scripts rather than separate `cloud-push/` or `dsl-json-parity/` conformance
@@ -73,6 +82,12 @@ fixture directories:
 - 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.
+- The main Synapsor repo fixture
+  `tests/fixtures/synapsor_spec/protected-read-aggregate.contract.json`,
+  `SynapsorContractSpec.*`, control-plane tests, and
+  `scripts/verify_contract_roundtrip.sh` prove that Cloud/C++ validates,
+  normalizes, stores, and exports the same optional `protected_read` authority
+  without accepting SQL escape fields.
 
 ## Runner Usage
 
@@ -87,6 +102,7 @@ corepack pnpm --filter @synapsor-runner/mcp-server test
 corepack pnpm test:contract-conformance
 corepack pnpm test:aggregate-read
 corepack pnpm test:principal-scope
+corepack pnpm test:auto-boundary-explore:packed
 ```
 
 The spec package also validates every conformance contract: