@synapsor/runner 1.5.3 → 1.6.0

package/CHANGELOG.md

@@ -1,6 +1,86 @@
 # Changelog
 
-## 1.5.3 (prepared, not published)
+## 1.6.0 (prepared, not published)
+
+### Connect, Explore, Protect
+
+- Adds deterministic whole-schema Auto Boundary drafting from database
+  metadata, statically parsed Prisma/Drizzle schemas, OpenAPI documents, and
+  existing Synapsor definitions. It executes no adopter code, samples no source
+  rows before activation, uses no LLM, and emits only disabled public DSL,
+  canonical JSON, tests, review evidence, and a generation lock.
+- Adds a secured local Workbench review for trusted tenant/principal scope,
+  visible and kept-out fields, typed filters, aggregate-safe measures,
+  `count_distinct`, reviewed dimensions and time buckets, one-hop
+  relationships, cohort suppression, privacy/query budgets, and exact
+  role/grant/RLS posture. Activation binds every decision to one immutable
+  digest.
+- Adds authoring-only Scoped Explore through exactly `app.describe_data` and
+  `app.explore_data`. Row and PM-style aggregate plans contain no SQL or
+  arbitrary identifiers, run with verified read-only credentials and enforced
+  read-only transactions, and retain only normalized redacted audit metadata.
+- Adds a deliberately small aggregate grammar for counts, reviewed distinct
+  identifiers, sums/averages, categorical dimensions, day/week/month buckets,
+  bounded comparisons and top-N, optional proven many-to-one relationships,
+  cohort suppression, and durable extraction/differencing/rate budgets.
+- Adds Protect This Query. Workbench freezes a successful plan into public
+  `.synapsor.sql`, canonical `protected_read` authority, positive/deny/scope/
+  suppression/drift tests, and a disabled named capability. Human exact-digest
+  activation removes broad Explore while preserving the named production tool.
+- Adds lock-bound schema/role/grant/ownership/RLS/compiler/Spec drift checks.
+  Additive schema fields receive no authority; breaking generated-authority
+  drift fails closed until regeneration and review.
+- Preserves published 1.x contracts, exact legacy normalization/digests,
+  established CLI selectors and automation, active tools, TypeScript authoring,
+  manual/headless operation, guarded writes, Data PRs, app-owned executors, and
+  deployments without generation locks through packed compatibility fixtures.
+- Prepares `@synapsor/runner@1.6.0`, `@synapsor/dsl@1.5.0`, and
+  `@synapsor/spec@1.5.0`. Nothing is published, tagged, pushed, or released by
+  this change.
+
+## 1.5.4 (published 2026-07-22)
+
+### Networked MCP authentication hardening
+
+- Defines explicit local-loopback, remote single-tenant, and shared multi-tenant
+  HTTP security profiles while preserving zero-configuration local stdio.
+- Refuses non-loopback cleartext listeners before bind unless the operator
+  explicitly selects a trusted TLS proxy or authenticated break-glass posture.
+  Runner-owned TLS and optional mTLS remain supported.
+- Hardens opaque endpoint tokens with environment-only provisioning, production
+  entropy checks, constant-time comparison, one bounded previous-token rotation
+  slot, and per-session credential pinning. Opaque tokens remain service access
+  credentials, not tenant or user identity.
+- Requires verified signed identity for shared deployments. Runner validates
+  algorithm, signature, issuer, audience/resource, time, scope, tenant, and
+  principal on every request, including requests for existing MCP sessions.
+- Adds RFC 9728 protected-resource metadata and standards-correct Bearer
+  challenges for external authorization servers. Runner remains a protected
+  resource and does not issue passwords, access tokens, or refresh tokens.
+- Adds exact Origin and Host policy, bounded headers/bodies/connections/sessions,
+  TLS preflight, bounded public-only JWKS handling, and safe overload responses.
+- Expands `doctor`, help, client generators, fleet examples, and deployment docs
+  so operators can distinguish TLS, Bearer presentation, opaque tokens, JWTs,
+  MCP session IDs, trusted context, database scope, and operator authority
+  without printing credential values.
+- Adds read-only, no-ID-first `lifecycle` inspection across local SQLite and
+  shared PostgreSQL runtime stores. Latest, filtered business-object lookup, and
+  proposal/evidence/replay/job/intent/receipt/audit handles resolve one typed,
+  redacted proposal-to-receipt/replay timeline without creating jobs, leases,
+  source calls, or Cloud synchronization.
+- Makes UPDATE conflict guarding exact by default in the SQL-like DSL.
+  Omitting `CONFLICT GUARD <column>` now fails. The explicit legacy
+  `CONFLICT GUARD WEAK ROW HASH ACKNOWLEDGED` form is limited to ordinary
+  single-row source-DB UPDATE and warns that projection hashing can miss outside
+  changes.
+- Preserves canonical `SESSION` for implementations with a real typed session
+  boundary while making Runner fail closed with
+  `SESSION_BINDING_UNSUPPORTED`. Runner-targeted DSL validation, contract load,
+  lint/explain, and runtime no longer allow an environment fallback.
+- Published `@synapsor/runner@1.5.4` and `@synapsor/dsl@1.4.4`;
+  `@synapsor/spec@1.4.2` and the Cloud CLI remain unchanged.
+
+## 1.5.3 (published 2026-07-21)
 
 ### Intent to Safe Action
 
@@ -26,7 +106,7 @@
   publishes an honest alternatives guide, and adds a deterministic 36-second
   support-plan-credit cut backed by real PostgreSQL proposal, receipt, retry,
   and stale-conflict evidence.
-- Prepares only `@synapsor/runner@1.5.3`; `@synapsor/spec@1.4.2`,
+- Published only `@synapsor/runner@1.5.3`; `@synapsor/spec@1.4.2`,
   `@synapsor/dsl@1.4.3`, and the Cloud CLI remain unchanged.
 
 ## 1.5.2 (prepared, not published)

package/README.md

@@ -21,8 +21,7 @@ No database, Docker, config, MCP client, LLM, or account is required:
 npx -y @synapsor/runner try --prove
 ```
 
-The four-second product measurement begins after package resolution. A cold
-`npx` download is recorded separately because registry and network time vary.
+Timing begins after package resolution; cold `npx` download time varies.
 
 The embedded synthetic source requests a $55 waiver and proves:
 
@@ -34,116 +33,152 @@ Restart-safe retry: yes; duplicate mutations: 0
 Stale apply refused: yes
 ```
 
-Review happens outside the model-facing tools. The command stores inspectable
-state under `./.synapsor/try/`; it teaches the boundary and does not claim to
-test your database connection. `demo --quick` remains a noninteractive compatibility alias.
+Review happens outside model-facing tools. State is stored under
+`./.synapsor/try/`; this proves the boundary, not your database connection.
+`demo --quick` remains a noninteractive compatibility alias.
 
-## Protect One Action In Your Application
+## Audit An Existing MCP Server
+
+Audit a typical raw-SQL MCP server without launching or calling one:
+
+```bash
+npx -y @synapsor/runner audit --example dangerous-db-mcp
+```
+
+Audit your own tool manifest, remote `tools/list`, or stdio server:
+
+```bash
+npx -y @synapsor/runner audit ./tools-list.json
+```
+
+It flags raw SQL, arbitrary identifiers, model-controlled authority, and
+model-facing writeback without calling business tools. See [MCP Database Risk
+Review](docs/mcp-audit.md) and the [alternatives
+guide](docs/alternatives.md).
+
+## Connect Your Staging Application
 
-Start with a staging database and a read-only credential. Runner inspects
-metadata, creates one reviewed read boundary, and opens the secured localhost
-Workbench:
+Use a dedicated SELECT-only, non-owner staging credential. Runner combines the
+whole database schema with statically parsed Prisma, Drizzle, OpenAPI, and
+existing Synapsor definitions. It does not execute adopter code, sample source
+rows, or use an LLM:
 
 ```bash
 npm install -g @synapsor/runner
 export DATABASE_URL="postgresql://runner_reader:REPLACE_ME@db.example.com:5432/app?sslmode=require"
+export SYNAPSOR_TENANT_ID="acme"
+export SYNAPSOR_PRINCIPAL="developer-1"
 synapsor-runner start --from-env DATABASE_URL --schema public
 ```
 
-Describe one business action. This creates an inert TypeScript draft; it does
-not add a tool or change the active contract:
+A fresh project opens the secured localhost Workbench and emits disabled DSL,
+canonical JSON, tests, review evidence, and a generation lock. Review scope,
+fields, aggregate members, relationships, privacy budgets, profile, and exact
+role/RLS posture, then activate the exact digest. Existing tools stay unchanged.
+
+## Ask Your First Real Question In Cursor
+
+After activation, let Runner add only the local authoring entry to this Cursor
+project:
 
 ```bash
-synapsor-runner start \
-  --action plan_credit \
-  --description "Propose one reviewed customer plan credit" \
-  --based-on support.inspect_customer
+synapsor-runner mcp install cursor \
+  --project \
+  --authoring \
+  --project-root . \
+  --yes
 ```
 
-Add the reviewed tools to the current Cursor project:
+Cursor sees exactly two temporary tools:
 
-```bash
-synapsor-runner mcp install cursor --project \
-  --config ./synapsor.runner.json \
-  --store ./.synapsor/local.db
+```text
+app.describe_data
+app.explore_data
 ```
 
-In Cursor, use the Workbench's exact prompt. The checked-in project
-instructions require the coding agent to draft and validate the action while
-leaving effect review and activation to you. Once activated, a request such as
-"give CUS-3001 a $25 plan credit" can only create a semantic proposal:
+Ask a bounded question such as:
 
 ```text
-Data PR  wrp_...
-Action   support.propose_plan_credit on CUS-3001
-Effect   plan_credit_cents: 0 -> 2500
-Source unchanged before approval: Yes
+Which reviewed regions and reason categories contributed most to the increase
+in churned accounts by week?
 ```
 
-Review the exact effect in the secured Workbench, select **Approve outside
-MCP**, then run the displayed guarded apply command from a trusted terminal.
-The agent has no approval or commit tool. Runner rechecks scope, policy, row
-version, bounds, and idempotency before returning a receipt; a retry cannot
-duplicate the mutation and a stale proposal conflicts.
+Runner accepts a typed plan, not SQL. It validates every member against the
+activated digest, injects trusted scope, and runs a read-only transaction.
+Small cohorts are suppressed and durable budgets limit repeated differencing.
+This is descriptive analysis, not proof of causation.
 
-See the [own-database guide](docs/getting-started-own-database.md) for the full
-staging path and [Cursor plugin guide](docs/cursor-plugin.md) for
-`/synapsor-protect` and the plugin boundary.
+Scoped Explore is local authoring only. Missing/unknown/production profiles,
+write-capable or owner credentials, stale generation locks, remote/shared HTTP,
+and non-loopback runtimes never advertise these tools.
 
-## Audit An Existing MCP Server
+## Protect This Query
 
-Audit a typical raw-SQL MCP server without launching or calling one:
+Choose the useful result in Workbench. No opaque ID needs to be copied. Runner
+freezes the reviewed shape into public DSL, canonical JSON, and tests under
+`synapsor/protected/drafts/`. The named capability starts disabled and requires
+exact-digest human activation outside MCP.
+
+After activation, Scoped Explore is disabled. Update Cursor to the production
+config:
 
 ```bash
-npx -y @synapsor/runner audit --example dangerous-db-mcp
+synapsor-runner mcp install cursor \
+  --project \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --yes
 ```
 
-Audit your own tool manifest, remote `tools/list`, or stdio server:
+Production exposes the protected named capability, not `app.explore_data`.
+Read the complete [Auto Boundary, Scoped Explore, And Protect
+guide](docs/auto-boundary-and-scoped-explore.md).
+
+## Create An Exact Data PR
+
+For a write, describe one business action. This creates an inert TypeScript
+draft; it does not add a tool or change the active contract:
 
 ```bash
-npx -y @synapsor/runner audit ./tools-list.json
+synapsor-runner start \
+  --action plan_credit \
+  --description "Propose one reviewed customer plan credit" \
+  --based-on support.inspect_customer
 ```
 
-It flags raw SQL, arbitrary identifiers, model-controlled authority,
-model-facing approval/writeback, and missing conflict or idempotency signals.
-It does not call business tools. See [MCP Database Risk
-Review](docs/mcp-audit.md) for local manifests, selected-server checks, CI,
-SARIF, evidence labels, and limits. You may not need Runner: use the
-[alternatives guide](docs/alternatives.md) to compare direct read-only access,
-hand-built tools, and this reviewed boundary.
-
-## Safety Model
+Once a human activates that exact action digest, an agent request can create
+only a semantic proposal:
 
 ```text
-AI agent or MCP client
-        |
-        | reviewed semantic tool
-        v
-+--------------------------------+
-| Synapsor Runner MCP            |
-| trusted tenant/principal scope |
-| evidence + query audit         |
-| proposals, not direct writes   |
-+--------------------------------+
-        |
-        | scoped read / approved guarded writeback
-        v
-+--------------------------------+
-| Your Postgres or MySQL         |
-| source of truth                |
-+--------------------------------+
-
-Local SQLite ledger:
-evidence -> proposal -> approval -> receipt -> replay
+Data PR  wrp_...
+Action   support.propose_plan_credit on CUS-3001
+Effect   plan_credit_cents: 0 -> 2500
+Source unchanged before approval: Yes
+```
+
+Approve in Workbench outside MCP; a trusted operator or worker commits. Runner
+supports guarded single-row INSERT/UPDATE/DELETE, fixed-predicate bounded
+UPDATE/DELETE, and exact-review batch INSERT. Rich transactions and external
+effects use app-owned executors.
+
+Runner rechecks scope, policy, row version, bounds, idempotency, and affected
+rows before returning a receipt. A retry cannot duplicate the mutation and a
+stale proposal conflicts. Inspect the latest lifecycle without copying an ID:
+
+```bash
+synapsor-runner lifecycle --details --store ./.synapsor/local.db
 ```
 
-The model can inspect scoped data and propose an exact change. It cannot call
-approval, apply, or revert tools. A human or trusted operator approves outside
-MCP, then Runner performs a guarded write or routes the proposal to an
-app-owned executor.
+See the [own-database guide](docs/getting-started-own-database.md),
+[Cursor plugin guide](docs/cursor-plugin.md), and
+[store lifecycle guide](docs/store-lifecycle.md) for the complete paths.
+
+## Safety Model
 
-Contracts fix trusted context, fields, bounds, transitions, and approvals;
-evidence, query audit, receipts, and replay preserve the lifecycle. Runner does
+Contracts fix trusted context, fields, bounds, transitions, and approval.
+Model-facing tools can inspect scoped data and propose exact changes, but cannot
+approve, apply, or revert. A trusted operator/worker performs guarded writeback;
+the ledger links evidence, proposal, decision, receipt, and replay. Runner does
 not make raw SQL or prompt-injection-prone clients safe.
 
 ## Choose An Isolation Mode
@@ -155,60 +190,31 @@ not make raw SQL or prompt-injection-prone clients safe.
 | `postgres_rls` | PostgreSQL also checks transaction-bound tenant/principal scope. Arbitrary trusted-context or credential control remains outside this guarantee. |
 | `tenant_bound` | Authenticated context selects a restricted per-tenant credential or process. |
 
-Stdio commonly trusts process environment; shared HTTP must use verified signed
-claims. Model arguments, query parameters, and arbitrary tenant headers are
-never trusted. MySQL has no native RLS; use restricted views or tenant
-credentials. See [Database scope] and the
+Use stdio; no socket opens. HTTP requires authentication; non-loopback
+listeners require TLS or an explicit trusted TLS proxy. Shared services require
+signed claims. Model-controlled input and MCP session IDs never establish
+identity. See [HTTP MCP].
+MySQL has no native RLS; use restricted views or tenant credentials. See
+[Database scope] and the
 [build-vs-adopt guide](docs/why-synapsor-vs-app-guardrails.md).
 
-## Connect A Staging Database
-
-The setup above stores environment-variable names, not connection strings, and
-never falls back to synthetic data if inspection fails. Keep staging, database
-permissions, restricted views, and RLS underneath Runner. Bind trusted tenant
-and principal values in the launching process, then review the exact field and
-tool surface before connecting Cursor.
-
-The [complete own-database guide](docs/getting-started-own-database.md) covers
-validation, scoped reads, disabled Prisma/Drizzle/OpenAPI candidates, guarded
-single-row writes, and app-owned executors. Use the [host compatibility
-matrix](docs/host-compatibility.md) for accurately tested client behavior.
-
 ## Review And Prove Your Contract
 
-Before serving, use `contract explain`, `contract lint --strict`, and `contract
-test` for reviewer-readable boundaries and allow/deny/redaction cases. The
-built-in language server supplies diagnostics, completion, hover, and formatting for
-`.synapsor.sql` and legacy `.synapsor` files. See [Contract
-Review](docs/contract-review.md) and [Contract
-Testing](docs/contract-testing.md).
-
-Runner also supports reviewed [aggregate reads](docs/aggregate-reads.md),
-tenant-scoped tamper-evident [ledger reports](docs/compliance-reports.md), and
-opt-in [graduated-trust recommendations](docs/graduated-trust.md). Aggregate
-tools return one scalar and no source rows. Graduated trust is disabled by
-default, remains operator-only, and can export a reviewable artifact but never
-activate it.
+Use `contract explain`, `contract lint --strict`, and `contract test`; the
+language server handles `.synapsor.sql` and legacy `.synapsor`. See [Contract
+Review](docs/contract-review.md), [Contract Testing](docs/contract-testing.md),
+and the [own-database guide](docs/getting-started-own-database.md).
 
 ## Trust And Verification
 
 Start with the **[Threat Model](THREAT_MODEL.md)**. It defines protected assets,
 trust boundaries, covered threats, non-goals, and required operator controls.
 
-- [Conformance fixtures](docs/conformance.md) prove trusted context, scoped
-  reads, kept-out fields, proposal boundaries, approval, receipts, and replay
-  behavior rather than only validating JSON shape.
-- `contract test` lets adopters encode the same boundary checks for their own
-  synthetic fixtures; it never invokes an LLM and refuses remote live targets
-  by default.
-- MCP proposal, evidence, and replay handles are references rather than bearer
-  authority: resource reads re-check the owning tenant and principal against
-  the current trusted session.
-- `test:principal-scope`, `test:live-apply`, `test:guarded-crud`,
-  `test:bounded-set`, and `test:reversible` prove cross-principal denial,
-  no pre-approval mutation, guarded writes, idempotent retry, conflicts,
-  bounded atomic sets, receipts, and reviewed compensation on disposable
-  PostgreSQL/MySQL fixtures.
+[Conformance fixtures](docs/conformance.md) and `contract test` cover trusted
+scope, kept-out fields, proposals, approval, receipts, and replay. Resource
+handles re-check tenant/principal rather than acting as bearer authority. Live
+gates cover principal denial, no pre-approval mutation, idempotency, conflict,
+bounded sets, and compensation on disposable databases.
 
 Runner is a narrow agent/database safety boundary, not a replacement for
 least-privilege database access, host security, or application authorization.
@@ -216,6 +222,7 @@ See [Security Boundary](docs/security-boundary.md) and
 [Current Limitations](docs/limitations.md).
 
 [Database scope]: docs/database-enforced-scope.md
+[HTTP MCP]: docs/http-mcp.md
 
 ## Operate The Approval Loop
 
@@ -242,16 +249,10 @@ and the [Runner Config Reference](docs/runner-config-reference.md).
 
 ## OSS And Cloud
 
-Synapsor Runner works by itself for local, single-node, and bounded small-fleet
-deployments: your database remains the source of truth and Runner stores review
-artifacts in the default local SQLite ledger or an opt-in shared Postgres
-runtime store.
-Synapsor Cloud adds a shared contract registry, immutable versions,
-source-scoped Runner connections, downloadable bundles, a human approval
-inbox, durable leased writeback jobs, and a redacted shared activity/receipt
-chronology. Database credentials and guarded execution remain local. See [Cloud
-Mode](docs/cloud-mode.md) for the design-partner path and [OSS Runner vs
-Synapsor Cloud](docs/oss-vs-cloud.md) for the detailed boundary.
+Runner works alone with local SQLite or an opt-in shared Postgres ledger.
+Synapsor Cloud adds shared registry, approval, leased jobs, and redacted
+activity/receipt chronology; credentials and guarded execution stay local. See
+[Cloud Mode](docs/cloud-mode.md) and [OSS vs Cloud](docs/oss-vs-cloud.md).
 
 `synapsor-runner` owns the local MCP/database boundary. `synapsor` from
 `@synapsor/cli` manages Cloud review and audit. Both Cloud push commands use