@synapsor/runner 1.5.3 → 1.6.0

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:

package/docs/current-scope.md

@@ -2,40 +2,67 @@
 
 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;
+- 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;
+- 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.0`;
 - 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.0 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/database-enforced-scope.md

@@ -11,6 +11,10 @@ from model arguments. Choose the database enforcement mode deliberately:
 
 These modes are defense in depth, not substitutes for least-privilege roles,
 restricted views, application authorization, or staging-first validation.
+HTTP endpoint authentication is another independent layer: it establishes who
+may call Runner and, for signed shared sessions, which trusted tenant/principal
+claims are bound. It does not turn `application_scope` into database-enforced
+isolation. See [HTTP MCP](http-mcp.md).
 
 ## Default: Application-Level Scope
 
@@ -49,6 +53,10 @@ with environment-bound capabilities.
 For shared production HTTP, prefer asymmetric JWT verification so Runner holds
 only public verification material. HS256 remains useful for local development
 and controlled deployments but gives Runner access to the signing secret.
+Also declare `http_security.deployment: shared`, an exact HTTPS
+audience/protected resource, a direct-TLS or trusted-proxy channel, and exact
+Host/Origin policy. A static endpoint token cannot supply shared tenant or
+principal identity.
 
 Run `doctor --json` or `tools preview --json` to inspect the effective
 per-source assurance mode and trusted-context binding. Server startup prints

package/docs/dsl-reference.md

@@ -29,7 +29,7 @@ END
 
 | Clause | Meaning |
 | --- | --- |
-| `BIND name FROM source key [REQUIRED]` | Defines trusted context. Sources: `SESSION`, `ENV`/`ENVIRONMENT`, `CLOUD_SESSION`, `STATIC_DEV`, `HTTP_CLAIM`. Model tool arguments cannot set these bindings. |
+| `BIND name FROM source key [REQUIRED]` | Defines trusted context. Canonical sources: `SESSION`, `ENV`/`ENVIRONMENT`, `CLOUD_SESSION`, `STATIC_DEV`, `HTTP_CLAIM`. Model tool arguments cannot set these bindings. Runner rejects `SESSION`; use one of its implemented verified providers described below. |
 | `TENANT BINDING name` | Selects the binding used for tenant scope. Defaults to a binding named `tenant_id`. |
 | `PRINCIPAL BINDING name` | Selects the actor binding. Defaults to a binding named `principal`. |
 
@@ -65,16 +65,57 @@ END
 | `TENANT KEY column` | Required in DSL 0.1. Adds trusted tenant scope to every read/write. |
 | `PRINCIPAL SCOPE KEY column` | Optional tenant-additive row lock. Runner binds this fixed column to the context's required trusted `PRINCIPAL BINDING`; it is never a model argument. |
 | `CONFLICT GUARD column` | Captures the row-version value for exact guarded writeback. Prefer a monotonic version or native-precision timestamp. |
+| `CONFLICT GUARD WEAK ROW HASH ACKNOWLEDGED` | Explicitly accepts a weaker hash over the captured projection for a legacy, ordinary single-row source-DB UPDATE. It may miss concurrent changes outside that projection and is never equivalent to a version column. |
+
+An UPDATE proposal must choose one of those guard clauses. Omitting the clause
+is a compile error; the compiler never silently selects the weak form. The weak
+form is rejected for INSERT, DELETE, reversible writes, bounded sets, and
+Runner-ledger authority. `contract lint`, `contract explain`, `doctor`, and
+`tools preview` all identify it prominently.
+
+To migrate a legacy DSL file that omitted the guard, inspect the target schema
+and add an exact source column:
+
+```sql
+  CONFLICT GUARD version
+```
+
+Use a monotonic integer/version column when available, or a native-precision
+`updated_at` maintained by the database. If a legacy source has no usable
+version column and the capability is an ordinary single-row UPDATE using
+source-DB receipt authority, the explicit weak clause keeps the previous
+projection-hash behavior while recording the reduced assurance in review
+output. Do not use it as a production-equivalent substitute for a real version
+column.
 
 `PRINCIPAL SCOPE KEY` means `tenant_key = trusted tenant AND
 principal_scope_key = trusted principal`. It cannot replace tenant scope,
 default to all rows, or be overridden by an argument. The principal binding
-must be required and come from a trusted provider such as `ENVIRONMENT`,
-`HTTP_CLAIM`, `SESSION`, or `CLOUD_SESSION`. For networked multi-user serving,
-use signed HTTP claims. See the complete
+must be required and come from a trusted Runner provider: `ENVIRONMENT`,
+verified `HTTP_CLAIM`, verified `CLOUD_SESSION`, or explicit
+`STATIC_DEV` for development only. For networked multi-user serving, use
+signed HTTP claims. Canonical `SESSION` is implemented by C++/Cloud but is
+rejected by Runner; Runner never aliases it to environment variables. See the complete
 [`principal-row-scope.synapsor.sql`](../fixtures/dsl/principal-row-scope.synapsor.sql)
 example.
 
+### Migrating `FROM SESSION` for Runner
+
+Choose the provider that owns the verified identity at the Runner boundary:
+
+- local stdio or one trusted process: `FROM ENVIRONMENT`; export the named
+  values before starting Runner;
+- Streamable HTTP: `FROM HTTP_CLAIM`; configure signed JWT verification and
+  bind only verified claims;
+- Cloud embedding: `FROM CLOUD_SESSION`; use the verified Cloud session
+  supplied by the control plane; or
+- disposable development only: `FROM STATIC_DEV`.
+
+`synapsor-runner dsl validate` and `dsl compile` target Runner and fail with
+`SESSION_BINDING_UNSUPPORTED` before serving. The standalone DSL accepts the
+canonical syntax by default for other implementations; pass `--target runner`
+to request the same fail-closed Runner validation.
+
 ## Arguments and lookup
 
 ```sql
@@ -127,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.
+Read [Auto Boundary, Scoped Explore, And
+Protect](auto-boundary-and-scoped-explore.md) for the complete command and
+security reference.
 
-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.
+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:
 
-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.
+```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 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.
+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.
@@ -520,7 +524,7 @@ MCP client:
 ```bash
 export SYNAPSOR_TENANT_ID="acme"
 export SYNAPSOR_PRINCIPAL="local_operator"
-export SYNAPSOR_RUNNER_HTTP_TOKEN="dev-local-token"
+export SYNAPSOR_RUNNER_HTTP_TOKEN="$(node -e 'process.stdout.write(require("node:crypto").randomBytes(32).toString("base64url"))')"
 
 npx -y -p @synapsor/runner synapsor-runner up --serve \
   --config ./synapsor.runner.json \
@@ -543,9 +547,12 @@ npx -y -p @synapsor/runner synapsor-runner mcp serve-streamable-http \
 ```
 
 Streamable HTTP defaults to `127.0.0.1:8766` and requires bearer auth by
-default. Use private networking/TLS before exposing it beyond localhost. See
+default. A non-loopback listener refuses to start until direct TLS, an explicitly
+trusted TLS proxy, or authenticated emergency break glass is selected. Shared
+services use signed per-session identity rather than one endpoint token. See
 [HTTP MCP](http-mcp.md). If you want the smaller JSON-RPC bridge instead, use
-`synapsor-runner mcp serve-http`.
+`synapsor-runner mcp serve-http`; it is not suitable for claim-bound shared MCP
+sessions.
 
 The model-facing MCP server exposes semantic tools such as:
 

package/docs/guarded-crud-writeback.md

@@ -27,13 +27,22 @@ does not fit either direct boundary.
 
 | Operation | Required source guard | Direct-write behavior |
 | --- | --- | --- |
-| `UPDATE` | Primary key, trusted tenant, exact version/conflict column | Patches only allowlisted columns and affects exactly one row. In Runner-ledger mode, the version must advance in the same source transaction. |
+| `UPDATE` | Primary key, trusted tenant, and normally an exact version/conflict column | Patches only allowlisted columns and affects exactly one row. In Runner-ledger mode, the exact version must advance in the same source transaction. |
 | `INSERT` | Source `PRIMARY KEY` or `UNIQUE` constraint over the reviewed dedup identity | Runner injects tenant and proposal-derived identity values, inserts only allowlisted fields, and requires exactly one row. |
 | `DELETE` | Primary key, trusted tenant, exact version column | Deletes exactly one reviewed row. Hard delete requires human/operator approval and is refused when Runner detects write triggers or widening cascades. Prefer soft delete as guarded `UPDATE`. |
 
 Existing proposal capabilities with no `operation` field continue to mean
 single-row `UPDATE`.
 
+DSL authoring requires `CONFLICT GUARD <column>` for UPDATE and never silently
+chooses weak semantics. A narrow legacy single-row, non-reversible UPDATE using
+source-DB receipt authority may explicitly declare
+`CONFLICT GUARD WEAK ROW HASH ACKNOWLEDGED`. That mode hashes only the captured
+projection and may miss concurrent changes outside it. It is prominently
+reported by lint/explain/doctor/preview and is unavailable for Runner-ledger,
+DELETE, reversibility, or bounded sets. Treat it as a compatibility escape
+hatch, not equivalent protection.
+
 ## Receipt authority
 
 Receipt authority and source-table provisioning are separate decisions: