@synapsor/runner 1.5.3 → 1.6.0

package/dist/shadow.mjs

@@ -1908,6 +1908,11 @@ var ProposalStore = class {
     const rows = this.db.prepare(query.sql).all(...query.params);
     return rows.map((row) => rowToProposal(row)).filter((proposal) => proposal !== void 0);
   }
+  countProposals(filters = {}) {
+    const query = buildProposalCountQuery(filters);
+    const row = this.db.prepare(query.sql).get(...query.params);
+    return isRecord(row) ? Number(row.count ?? 0) : 0;
+  }
   listEvidenceBundles(filters = {}) {
     const query = buildEvidenceQuery(filters);
     const rows = this.db.prepare(query.sql).all(...query.params);
@@ -1934,6 +1939,19 @@ var ProposalStore = class {
     const proposalId = replayId.startsWith(prefix) ? replayId.slice(prefix.length) : replayId;
     return this.replay(proposalId);
   }
+  getStoredReplay(replayId) {
+    const row = this.db.prepare("SELECT * FROM replay_records WHERE replay_id = ?").get(replayId);
+    return rowToStoredReplay(row);
+  }
+  getStoredReplayForProposal(proposalId) {
+    const row = this.db.prepare(`
+      SELECT * FROM replay_records
+      WHERE proposal_id = ?
+      ORDER BY created_at DESC, replay_id DESC
+      LIMIT 1
+    `).get(proposalId);
+    return rowToStoredReplay(row);
+  }
   proposalIdForEvidence(evidenceBundleId) {
     const evidence = this.getEvidenceBundle(evidenceBundleId);
     if (evidence?.proposal_id) return evidence.proposal_id;
@@ -2236,6 +2254,19 @@ var ProposalStore = class {
     });
     return job;
   }
+  getWritebackJob(writebackJobId) {
+    return rowToWritebackJob(this.db.prepare("SELECT * FROM writeback_jobs WHERE writeback_job_id = ?").get(writebackJobId));
+  }
+  listWritebackJobs(options = {}) {
+    const clauses = [];
+    const values = [];
+    if (options.proposal_id) {
+      clauses.push("proposal_id = ?");
+      values.push(options.proposal_id);
+    }
+    const limit = Math.min(Math.max(options.limit ?? 100, 1), 1e3);
+    return this.db.prepare(`SELECT * FROM writeback_jobs${clauses.length ? ` WHERE ${clauses.join(" AND ")}` : ""} ORDER BY created_at ASC, writeback_job_id ASC LIMIT ?`).all(...values, limit).map(rowToWritebackJob).filter((job) => Boolean(job));
+  }
   claimWritebackIntent(jobInput, runnerId) {
     const job = parseWritebackJob(jobInput);
     const proposal = this.requireProposal(job.proposal_id);
@@ -4059,6 +4090,19 @@ function inWhere(column, values) {
   };
 }
 function buildProposalQuery(filters) {
+  const { clauses, params } = proposalQueryParts(filters);
+  const where = clauses.length ? ` WHERE ${clauses.join(" AND ")}` : "";
+  return {
+    sql: `SELECT * FROM proposals${where} ORDER BY created_at DESC, proposal_id DESC${filters.limit ? " LIMIT ?" : ""}`,
+    params: filters.limit ? [...params, filters.limit] : params
+  };
+}
+function buildProposalCountQuery(filters) {
+  const { clauses, params } = proposalQueryParts(filters);
+  const where = clauses.length ? ` WHERE ${clauses.join(" AND ")}` : "";
+  return { sql: `SELECT COUNT(*) AS count FROM proposals${where}`, params };
+}
+function proposalQueryParts(filters) {
   const clauses = [];
   const params = [];
   addEqual(clauses, params, "proposal_id", filters.proposal);
@@ -4070,7 +4114,7 @@ function buildProposalQuery(filters) {
   addEqual(clauses, params, "action", filters.capability ?? filters.action);
   addObjectFilter(clauses, params, "business_object", "source_table", "object_id", filters.objectType, filters.objectId);
   addTimeRange(clauses, params, "created_at", filters.from, filters.to);
-  return finishQuery("SELECT * FROM proposals", clauses, params, filters.limit);
+  return { clauses, params };
 }
 function buildEvidenceQuery(filters) {
   const clauses = [];
@@ -4652,6 +4696,62 @@ function rowToReceipt(row) {
     source_table: row.source_table == null ? void 0 : String(row.source_table)
   };
 }
+function rowToWritebackJob(row) {
+  if (!isRecord(row)) return void 0;
+  let payload;
+  try {
+    payload = JSON.parse(String(row.job_json));
+  } catch {
+    throw new ProposalStoreError("WRITEBACK_JOB_CORRUPT", `writeback job ${String(row.writeback_job_id)} payload is not valid JSON`);
+  }
+  if (!isRecord(payload)) {
+    throw new ProposalStoreError("WRITEBACK_JOB_CORRUPT", `writeback job ${String(row.writeback_job_id)} payload is not an object`);
+  }
+  const handler = payload.schema_version === "synapsor.handler-writeback.v1";
+  let normalizedJob;
+  if (!handler) {
+    try {
+      normalizedJob = parseWritebackJob(payload);
+    } catch {
+      throw new ProposalStoreError("WRITEBACK_JOB_CORRUPT", `writeback job ${String(row.writeback_job_id)} payload is not a supported writeback protocol`);
+    }
+  }
+  const payloadJobId = handler ? payload.writeback_job_id : normalizedJob?.job_id;
+  const payloadProposalId = handler ? payload.proposal_id : normalizedJob?.proposal_id;
+  const payloadProposalHash = handler ? payload.proposal_hash : normalizedJob?.approval_id;
+  if (payloadJobId !== String(row.writeback_job_id) || payloadProposalId !== String(row.proposal_id) || payloadProposalHash !== String(row.proposal_hash)) {
+    throw new ProposalStoreError("WRITEBACK_JOB_CORRUPT", `writeback job ${String(row.writeback_job_id)} index fields do not match its payload`);
+  }
+  return {
+    writeback_job_id: String(row.writeback_job_id),
+    proposal_id: String(row.proposal_id),
+    proposal_hash: String(row.proposal_hash),
+    status: String(row.status),
+    kind: handler ? "app_handler" : "direct_sql",
+    payload,
+    ...normalizedJob ? { normalized_job: normalizedJob } : {},
+    created_at: String(row.created_at),
+    updated_at: String(row.updated_at)
+  };
+}
+function rowToStoredReplay(row) {
+  if (!isRecord(row)) return void 0;
+  let payload;
+  try {
+    payload = JSON.parse(String(row.payload_json));
+  } catch {
+    throw new ProposalStoreError("REPLAY_RECORD_CORRUPT", `replay ${String(row.replay_id)} payload is not valid JSON`);
+  }
+  if (!isRecord(payload) || !isRecord(payload.proposal)) {
+    throw new ProposalStoreError("REPLAY_RECORD_CORRUPT", `replay ${String(row.replay_id)} payload is not a supported replay record`);
+  }
+  const replayId = String(row.replay_id);
+  const proposalId = String(row.proposal_id);
+  if (payload.replay_id !== replayId || payload.proposal.proposal_id !== proposalId || !Array.isArray(payload.approvals) || !Array.isArray(payload.events) || !Array.isArray(payload.receipts) || !Array.isArray(payload.query_audit) || !Array.isArray(payload.evidence) || typeof payload.generated_at !== "string") {
+    throw new ProposalStoreError("REPLAY_RECORD_CORRUPT", `replay ${replayId} index fields do not match its payload`);
+  }
+  return payload;
+}
 function rowToWritebackIntent(row) {
   if (!isRecord(row)) return void 0;
   const status = String(row.status);

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/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
@@ -196,12 +225,14 @@ reviewed runner JSON capabilities. Current parity:
 | arg `enum` | `ARG risk_level STRING ENUM('low', 'medium', 'high') REQUIRED` | 1.4.121 | Supports 1..64 same-type string, number, or boolean values; duplicates and mixed types fail compilation. |
 | proposal `numeric_bounds` | `BOUND column 1..2500`, `BOUND column ..2500`, or `BOUND column 1..` | 0.1.8 | Applies to patched numeric columns. Strict mode warns when a NUMBER arg is patched without arg min/max or a matching `BOUND`. |
 | proposal `transition_guards` | `TRANSITION status ALLOW pending -> approved\|rejected` or `TRANSITION status FROM current_status ALLOW open -> closed` | 0.1.8 | Values are state strings; use `|` for multiple target states. |
-| proposal `conflict_guard` | `CONFLICT GUARD updated_at` | 0.1 | If omitted, DSL emits an explicit weak-guard acknowledgement. Prefer a real row-version column. |
+| proposal `conflict_guard` | `CONFLICT GUARD updated_at` | 0.1 | Required for ordinary UPDATE authoring. It compiles to an exact version-column check. Omission fails instead of silently weakening concurrency protection. |
+| proposal weak `conflict_guard` | `CONFLICT GUARD WEAK ROW HASH ACKNOWLEDGED` | 1.4.4 | Explicit legacy escape hatch for an ordinary single-row source-DB UPDATE only. It hashes the captured projection and may miss concurrent changes outside that projection. It is rejected for DELETE, reversible writes, bounded sets, and Runner-ledger authority. |
 | proposal `approval` | `APPROVAL ROLE billing_lead` | 0.1 | Local mode records the required role; enforcement is still outside the model-facing MCP tool. |
 | proposal `approval.required_approvals` | `REQUIRE 2 APPROVALS` | 1.1 | Optional 1..10 distinct-reviewer quorum; defaults to 1. |
 | 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
 
@@ -523,6 +554,8 @@ Canonical Synapsor names use dots, such as `billing.inspect_invoice`. Some
 clients require function-safe names. Use:
 
 ```bash
+export SYNAPSOR_RUNNER_HTTP_TOKEN="$(node -e 'process.stdout.write(require("node:crypto").randomBytes(32).toString("base64url"))')"
+
 synapsor-runner mcp serve-streamable-http \
   --config ./synapsor.runner.json \
   --store ./.synapsor/local.db \
@@ -533,6 +566,8 @@ synapsor-runner mcp serve-streamable-http \
 The model sees aliases such as `billing__inspect_invoice`. Runner includes the
 canonical name in tool metadata and descriptions so audit/replay still use the
 real capability name.
+This loopback token is opaque endpoint access, not tenant identity. See
+[HTTP MCP](http-mcp.md) before using a network listener.
 
 ## Why Not `execute_sql`
 

package/docs/cloud-mode.md

@@ -19,6 +19,24 @@ The local Runner still keeps database credentials in your environment. MCP
 client config snippets contain command paths and Runner arguments, not database
 URLs or write credentials.
 
+Keep Cloud and MCP credentials distinct:
+
+| Credential | Purpose | Issuer/provisioner | Never substitutes for |
+| --- | --- | --- | --- |
+| Cloud user session | Human control-panel/CLI identity and subscription/RBAC checks | Synapsor Cloud identity system | MCP tenant identity or database access |
+| Cloud service/API key | Contract push and scoped Cloud administration | Synapsor Cloud | MCP endpoint access |
+| Source-scoped Runner token | Runner registration, heartbeat, lease, activity, and result calls for one Cloud source | Synapsor Cloud Connect Runner flow | Model-facing MCP access or operator approval |
+| Opaque MCP endpoint token | Loopback or explicitly single-tenant HTTP endpoint access | Customer operator/secret manager | User/tenant identity |
+| Signed MCP access JWT | Shared HTTP client identity and verified tenant/principal claims | Customer identity provider/authorization server | Cloud subscription credential or DB role |
+| Operator credential | Activation, approval, apply, reconcile, dead-letter, and revert authority | Customer operator identity system | Model-facing MCP capability |
+| Database/handler credential | Local read or trusted post-approval effect | Customer secret manager/database/application | Cloud or MCP authentication |
+
+Cloud-linked mode does not require networked MCP: a desktop client can still
+launch the local Runner over stdio. If the local Runner exposes Streamable HTTP,
+the same [HTTP MCP](http-mcp.md) channel and identity profiles apply. Cloud API
+keys and source-scoped Runner tokens are never accepted as shortcuts for MCP
+session authentication.
+
 ## Trust Boundary
 
 ```text