@synapsor/runner 1.4.12 → 1.4.122

package/docs/contract-review.md

@@ -0,0 +1,57 @@
+# Review Contracts Before Serving Them
+
+Runner uses the same DSL parser and canonical Spec validator for compilation,
+editor diagnostics, explanation, and lint. These tools reduce authoring errors;
+they do not replace a human review of database permissions, visible fields,
+tenant binding, or business policy.
+
+## Explain The Boundary
+
+```bash
+synapsor-runner contract explain ./contract.synapsor.sql --format markdown
+synapsor-runner contract explain ./synapsor.contract.json --format json
+```
+
+The explanation lists trusted context bindings, model-facing arguments, fixed
+targets and selections, visible and kept-out fields, evidence requirements,
+proposal/writeback controls, approval, bounds, reversibility, and unresolved
+runtime dependencies. It is derived from normalized canonical contract JSON.
+It never reads environment values or prints database URLs, tokens, keys, or
+evidence rows.
+
+## Lint In CI
+
+```bash
+synapsor-runner contract lint ./contract.synapsor.sql --strict
+synapsor-runner contract lint ./synapsor.contract.json \
+  --config ./synapsor.runner.json --format sarif --out ./contract-lint.sarif
+```
+
+`--strict` is equivalent to `--fail-on warning`; the default fails on errors.
+Lint rule IDs, ordering, severity, and source ranges are deterministic. Rules
+cover objective review gaps such as missing descriptions/evidence, unbounded
+strings, unresolved wiring, irreversible operations, and policy/writeback
+contradictions. Lint does not claim to discover every sensitive column.
+
+Expected successful output ends with:
+
+```text
+Summary: 0 error / 0 warning / N info
+```
+
+## Language Server
+
+```bash
+synapsor-runner language-server --stdio
+```
+
+The stdio LSP supports `.synapsor.sql` and legacy `.synapsor` documents. It
+publishes parser/validator diagnostics and provides context-aware completion,
+hover, and formatting. Configure a generic LSP client to launch the command
+above with the workspace as its working directory. For VS Code, use any stdio
+language-client extension that can associate both filename patterns with that
+command. Generic SQL highlighting remains useful for `.synapsor.sql`; the LSP
+adds Synapsor-specific semantics.
+
+The server never suggests raw SQL, model-authored predicates, approval tools,
+or clauses that are illegal for the current capability kind.

package/docs/contract-testing.md

@@ -0,0 +1,76 @@
+# Test A Contract Boundary
+
+Adopter-owned contract tests exercise reviewed allow/deny behavior without an
+LLM. The public manifest schema is
+[`schemas/synapsor.contract-tests.schema.json`](../schemas/synapsor.contract-tests.schema.json).
+
+```bash
+synapsor-runner contract test \
+  --contract ./synapsor.contract.json \
+  --tests ./synapsor.contract-tests.json \
+  --config ./synapsor.runner.json
+```
+
+Static mode checks tool exposure, operator-only boundaries, argument limits,
+transition guards, bounded-set caps, and other assertions that do not require a
+database. Add `--live` to call the actual MCP runtime for scoped reads,
+proposals, evidence/replay redaction, and source-unchanged checks.
+
+```bash
+synapsor-runner contract test \
+  --contract ./synapsor.contract.json \
+  --tests ./synapsor.contract-tests.json \
+  --config ./synapsor.runner.json \
+  --live --format junit --out ./contract-tests.xml
+```
+
+Live mode accepts local/disposable PostgreSQL and MySQL targets. Runner refuses
+remote hosts by default; `--allow-remote` is an explicit operator override and
+does not grant implicit write permission. Use synthetic fixtures and a
+disposable database. Unknown assertions and unresolved required tests fail
+rather than being skipped.
+
+A successful run ends with a stable count such as:
+
+```text
+Summary: 6 passed / 0 failed / 6 total
+```
+
+Supported assertions cover valid scoped tools, cross-tenant denial,
+same-tenant cross-principal denial, kept-out
+fields, argument constraints, transition guards, set caps, unchanged source
+state before approval, and the absence of model-facing approval/writeback.
+Trusted tenant and principal values belong in test setup, not tool arguments.
+
+Use `cross_principal_deny` to prove both the allowed and denied sides of one
+row lock. The two contexts must use the same tenant and different principals:
+
+```json
+{
+  "id": "case-manager-b-cannot-read-a",
+  "kind": "cross_principal_deny",
+  "capability": "care.inspect_assigned_patient",
+  "args": { "patient_id": "PAT-1001" },
+  "trusted_context": {
+    "tenant_id": "hospital_a",
+    "principal": "case_manager_a",
+    "provenance": "http_claims"
+  },
+  "other_trusted_context": {
+    "tenant_id": "hospital_a",
+    "principal": "case_manager_b",
+    "provenance": "http_claims"
+  },
+  "expected_code": "NOT_FOUND_IN_TENANT"
+}
+```
+
+Live execution first proves the owner can read the row, then requires the other
+principal to receive the generic denial and `RESOURCE_NOT_FOUND` for the
+owner's evidence handle. Run the repository's Postgres/MySQL proof with
+`corepack pnpm test:principal-scope`.
+
+The flagship example includes a working manifest at
+[`examples/support-plan-credit/synapsor.contract-tests.json`](../examples/support-plan-credit/synapsor.contract-tests.json).
+Contract tests prove the declared cases, not every possible threat or database
+permission error.

package/docs/dsl-reference.md

@@ -47,6 +47,7 @@ CREATE CAPABILITY billing.inspect_invoice
   ON public.invoices
   PRIMARY KEY id
   TENANT KEY tenant_id
+  PRINCIPAL SCOPE KEY assigned_to
   CONFLICT GUARD updated_at
   ...
 END
@@ -62,8 +63,18 @@ END
 | `ON schema.table` | Required fixed target. Table/schema are never model inputs. |
 | `PRIMARY KEY column` | Fixed single-row target key. Defaults to `id` in DSL 0.1. Declare it explicitly. |
 | `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. |
 
+`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
+[`principal-row-scope.synapsor.sql`](../fixtures/dsl/principal-row-scope.synapsor.sql)
+example.
+
 ## Arguments and lookup
 
 ```sql
@@ -71,6 +82,7 @@ END
   ARG invoice_id STRING REQUIRED MAX LENGTH 128 DESCRIPTION 'Invoice id.'
   ARG amount_cents NUMBER REQUIRED MIN 1 MAX 2500 DESCRIPTION 'Amount in cents.'
   ARG confirmed BOOLEAN REQUIRED
+  ARG risk_level STRING ENUM('low', 'medium', 'high') REQUIRED
 ```
 
 Argument types are `STRING`/`TEXT`, `NUMBER`, and `BOOLEAN`/`BOOL`.
@@ -80,12 +92,41 @@ Argument types are `STRING`/`TEXT`, `NUMBER`, and `BOOLEAN`/`BOOL`.
 - `MIN n` and `MAX n` are numeric bounds for `NUMBER`.
 - `MAX LENGTH n` bounds `STRING`/`TEXT`. Legacy text `MAX n` remains accepted.
 - `LOOKUP arg BY column` binds one argument to the target row lookup.
+- `ENUM(value, ...)` restricts an argument to reviewed string, numeric, or
+  boolean values of the declared type. Enums contain 1 through 64 unique,
+  non-null values and preserve declared order.
 
 In spec 0.1, lookup is primary-key-only. The `BY` column must equal the declared
 `PRIMARY KEY`. A different column fails with `LOOKUP_COLUMN_UNSUPPORTED`; Runner
 never silently rewrites it. List/filter queries require a reviewed view or a
 different capability design.
 
+## Aggregate read
+
+An aggregate capability returns one scalar and no source rows:
+
+```sql
+CREATE CAPABILITY billing.overdue_balance_total
+  DESCRIPTION 'Return overdue balance for the trusted tenant.'
+  USING CONTEXT local_operator
+  SOURCE billing_postgres
+  ON public.invoices
+  PRIMARY KEY id
+  TENANT KEY tenant_id
+  AGGREGATE READ SUM balance_cents
+  SELECT WHERE status = 'overdue'
+  MIN GROUP SIZE 5
+  REQUIRE EVIDENCE
+END
+```
+
+Use `COUNT ROWS`, `COUNT NON NULL column`, `SUM column`, or `AVG column`.
+`SELECT WHERE` is the same contract-fixed equality AST used by reviewed set
+operations. `MIN GROUP SIZE` is mandatory and must be 2 through 1,000,000.
+Aggregate reads cannot declare model arguments, lookup, visible row fields,
+proposal clauses, joins, grouping, or arbitrary expressions. See [Bounded
+Aggregate Reads](aggregate-reads.md).
+
 ## Read surface and evidence
 
 ```sql
@@ -162,7 +203,7 @@ bounds, exact version guards, and human/operator approval:
 
 ```sql
   PROPOSE ACTION close_overdue UPDATE SET
-  SELECT WHERE status = 'overdue'
+  SELECT WHERE risk_level = 'high' AND case_status = 'active'
   MAX ROWS 10
   MAX TOTAL balance_cents BEFORE 50000
   ALLOW WRITE status
@@ -172,11 +213,14 @@ bounds, exact version guards, and human/operator approval:
   WRITEBACK DIRECT SQL
 ```
 
-`SELECT WHERE` accepts one or more literal equality terms joined by `AND`.
-Columns, operators, values, ordering, ranges, and raw SQL cannot come from a
-model argument. Runner reads `MAX ROWS + 1` and rejects overflow rather than
-truncating. `MAX TOTAL column BEFORE|AFTER|ABSOLUTE DELTA maximum` is a
-reviewer-visible aggregate value bound.
+`SELECT WHERE` accepts one through eight literal equality terms joined by
+`AND`. The separator is recognized only outside quoted literals, so
+`description = 'salt AND pepper'` remains one term. `OR`, parentheses,
+inequalities, ranges, trailing expressions, and free-form or model-authored
+predicates are rejected during compilation. Runner reads `MAX ROWS + 1` and
+rejects overflow rather than truncating. `MAX TOTAL column
+BEFORE|AFTER|ABSOLUTE DELTA maximum` is a reviewer-visible aggregate value
+bound.
 
 Batch INSERT takes a complete typed item array:
 

package/docs/graduated-trust.md

@@ -0,0 +1,64 @@
+# Graduated Trust Recommendations
+
+Graduated trust is an opt-in operator workflow that evaluates scoped ledger
+history and recommends a bounded policy threshold change. It is disabled by
+default. It never auto-approves itself, changes the active contract, pushes a
+contract, or activates a registry version.
+
+```json
+{
+  "graduated_trust": {
+    "enabled": true,
+    "kill_switch": false,
+    "criteria": [{
+      "capability": "support.propose_plan_credit",
+      "policy": "small_credit",
+      "field": "plan_credit_cents",
+      "minimum_human_reviews": 20,
+      "window_days": 30,
+      "maximum_rejection_rate": 0.05,
+      "maximum_conflict_rate": 0.01,
+      "maximum_failure_rate": 0.01,
+      "maximum_revert_rate": 0.01,
+      "maximum_threshold_increase": 500,
+      "absolute_ceiling": 5000
+    }]
+  }
+}
+```
+
+Evaluate human-reviewed outcomes for one trusted tenant/capability/policy:
+
+```bash
+synapsor-runner policy recommend --contract ./synapsor.contract.json \
+  --config ./synapsor.runner.json --tenant tenant_acme \
+  --capability support.propose_plan_credit --policy small_credit \
+  --store ./.synapsor/local.db
+```
+
+Eligible history produces `RECOMMENDATION_CREATED` and a pending `ptr_...`
+identifier. Disabled, insufficient, stale, or out-of-policy history returns a
+stable non-success code and creates no recommendation.
+
+Auto-approved outcomes do not count as independent human evidence. Missing or
+legacy provenance, mismatched contract digest/version, tampered approvals,
+cross-scope records, insufficient samples, or excessive rejection, conflict,
+failure, or revert rates fail closed. `kill_switch: true` disables evaluation
+even when `enabled` remains true.
+
+A recommendation remains operator-only. List it with `policy recommendations
+list`. Approval or rejection requires a cryptographically verified `signed_key`
+or `jwt_oidc` operator identity. Rejection is terminal. Approval permits only
+an explicit export of a separate reviewable contract artifact:
+
+```bash
+synapsor-runner policy recommendations export ptr_... --tenant tenant_acme \
+  --contract ./synapsor.contract.json \
+  --out ./synapsor.contract.recommended.json --actor policy-reviewer --yes \
+  --store ./.synapsor/local.db
+```
+
+Export rechecks the base contract digest, version, and current threshold. The
+artifact is not activated. Activation remains an explicit operator or Cloud
+registry action. Recommendation, decision, and export metadata remain in the
+local or shared Postgres runtime ledger and can appear in scoped reports.

package/docs/hosted-cloud-linked-verification.md

@@ -0,0 +1,97 @@
+# Hosted Cloud-Linked Verification
+
+This is the manual release gate for the complete OSS Runner and single-node
+Synapsor Cloud boundary. It is intentionally opt-in because it creates Cloud
+records and mutates a synthetic source row.
+
+The verifier installs packed or published Cloud CLI and Runner packages in a
+clean temporary directory and proves:
+
+- public protocol discovery;
+- packed CLI human `whoami`, secure one-time service-key output, and immediate
+  service-key revocation;
+- canonical contract push parity between `synapsor contracts push` and
+  `synapsor-runner cloud push` with one immutable version identity;
+- source-scoped Runner token creation, rotation, registration idempotency, and
+  heartbeat;
+- credential-free Runner bundle download;
+- scoped MCP read and cross-tenant denial;
+- proposal creation without a source write and automatic durable-outbox
+  delivery without a manual `cloud sync` command;
+- authenticated Cloud approval and guarded local writeback through the packed
+  Runner's public worker CLI;
+- two registered Runner processes competing for one exclusive job lease;
+- duplicate-claim idempotency, rejection, and stale-version conflict;
+- linked Cloud activity integrity and canonical export;
+- reviewed activation and rollback of a risk-increasing contract version; and
+- immediate Runner-token revocation across doctor, registration, claim, and
+  result submission.
+
+It never accepts production data. Use a disposable project and a synthetic
+Postgres or MySQL database that can be reset after the run.
+
+## Prerequisites
+
+Build the workspace and pack both packages before a pre-publish check:
+
+```bash
+corepack pnpm install
+corepack pnpm build
+corepack pnpm --filter @synapsor/runner pack --pack-destination /tmp
+corepack pnpm --filter @synapsor/cli pack --pack-destination /tmp
+```
+
+Prepare:
+
+- a disposable Cloud project and imported synthetic source;
+- an authenticated human session token obtained through the normal browser/
+  device login flow;
+- separate least-privilege read and write source URLs;
+- a canonical contract with one scoped read and one proposal capability; and
+- three independent proposal fixture rows: apply, reject, and stale-conflict.
+
+Read tokens and database URLs from a secret prompt or secret manager. Do not
+put them in Git, shell history, command-line arguments, or the Runner bundle.
+
+## Run
+
+Set the non-secret fixture identifiers and JSON assertions for your synthetic
+database. The exact required variables and their meanings are always available
+without credentials:
+
+```bash
+corepack pnpm verify:hosted-cloud-linked -- --help
+```
+
+Then opt in explicitly and run:
+
+```bash
+export SYNAPSOR_HOSTED_E2E=1
+export SYNAPSOR_E2E_DISPOSABLE_PROJECT=1
+export SYNAPSOR_CLOUD_BASE_URL="https://dev-api.synapsor.ai"
+export SYNAPSOR_RUNNER_PACKAGE_SPEC="/tmp/synapsor-runner-<version>.tgz"
+export SYNAPSOR_CLI_PACKAGE_SPEC="/tmp/synapsor-cli-<version>.tgz"
+
+corepack pnpm verify:hosted-cloud-linked
+```
+
+The command refuses to run unless both opt-in flags are present. HTTPS is
+required unless `SYNAPSOR_E2E_ALLOW_HTTP=1` is explicitly set for a local
+control-plane test. The generated Runner token is revoked in a `finally` block,
+and the temporary directory is removed unless
+`SYNAPSOR_E2E_KEEP_TEMP=1` is set for debugging.
+
+## Passing Result
+
+A pass prints only a boolean summary with all checks set to `true`. The
+`token_rotated`, `registration_idempotent`, `two_runner_exclusive_claim`,
+`registration_heartbeat`, `proposal_reviewed_metadata`,
+`two_runner_exclusive_claim`, `receipt_replay_linked`, `activity_exported`,
+`contract_governance`, and `revoked_operations_blocked` fields prove those
+additional boundaries explicitly. It does not print bearer tokens, database
+URLs, source rows, or kept-out values. Confirm the synthetic fixture is reset
+after the run before reusing the project.
+
+This gate is evidence for the existing single-node design-partner boundary. It
+does not establish multi-region availability, managed Runner hosting, SSO/SCIM,
+legal hold, formal compliance certification, or an enterprise SLA.

package/docs/limitations.md

@@ -49,6 +49,12 @@ enterprise SLA.
 - Static MCP database risk review.
 - Local indexed search for proposals, evidence bundles, query audit, writeback
   receipts, and proposal replay.
+- DSL enum arguments and fixed, tenant-scoped aggregate count/sum/avg tools
+  with mandatory minimum-group suppression and no source-row output.
+- Contract LSP, explanation, deterministic lint, adopter-owned contract tests,
+  and scoped tamper-evident JSON/Markdown/PDF ledger reports.
+- Off-by-default graduated-trust recommendations that require verified operator
+  review and explicit artifact export without activation.
 
 ## Runtime Contract
 
@@ -81,6 +87,10 @@ truth for the model-facing tools.
 - Prompt-injection prevention.
 - Unbounded/high-throughput or multi-region ledger scale.
 - Managed fleet, SLA, compliance certification, or production support guarantee.
+- Arbitrary aggregate expressions, joins, grouping, dynamic columns,
+  model-controlled aggregate predicates, or a statistical privacy guarantee.
+- Automatic policy widening or activation from graduated-trust metrics.
+- Immutable/WORM compliance storage from the local report exporter.
 
 ## Important External Database Semantics
 

package/docs/oss-vs-cloud.md

@@ -9,9 +9,12 @@ evidence and proposals, keeps approval outside MCP, applies or routes approved
 writeback, and records receipts and replay in the default local SQLite ledger
 or an opt-in shared Postgres runtime store.
 
-Cloud is the team control plane. It stores versioned contracts, produces
-downloadable Runner bundles, and provides shared activity, evidence, approval,
-and investigation surfaces for enabled design-partner deployments.
+Cloud is the team control plane. In the design-partner deployment it stores
+versioned contracts, issues source-scoped Runner identities, produces
+credential-free bundles, receives reviewed local proposals, records human
+decisions, leases approved jobs to compatible local Runners, and links safe
+activity/receipt/replay metadata. The database connection and enforcement
+runtime stay local.
 
 | Need | OSS Runner | Synapsor Cloud |
 | --- | --- | --- |
@@ -19,9 +22,9 @@ and investigation surfaces for enabled design-partner deployments.
 | Contract source | Local files reviewed in Git | Shared registry with immutable versions and digests |
 | Trusted context | Local environment/session bindings | Registered bindings plus deployment-specific Cloud session context |
 | Capabilities | Local semantic MCP tools | Registry, version history, and capability inspection |
-| Evidence and replay | Local SQLite ledger by default; optional shared Postgres runtime store | Shared activity and evidence surfaces where enabled |
-| Approval | Local CLI or localhost UI | Team approval surfaces where enabled |
-| Writeback | Guarded one-row CRUD, fixed/frozen bounded sets, or app-owned executor | Cloud-linked jobs with local execution; managed production orchestration is future work |
+| Evidence and replay | Local SQLite ledger by default; optional shared Postgres runtime store | Redacted shared chronology and references; full evidence payload stays local by default |
+| Approval | Local CLI or localhost UI | Human-authenticated shared approval inbox; unavailable to MCP/Runner tokens |
+| Writeback | Guarded one-row CRUD, fixed/frozen bounded sets, or app-owned executor | Durable approval/job/lease coordination; the local Runner rechecks and executes |
 | MCP risk audit | Static local audit | Organization-wide continuous audit is future work |
 | Identity | Local operator boundary | Workspace RBAC where configured; SAML and SCIM are future work |
 | Operations | Customer-operated single node or bounded small fleet | Managed fleet remains Cloud work; no enterprise SLA in the current beta |
@@ -45,6 +48,10 @@ environment-variable wiring, and MCP client templates.
 3. Keep contracts in Git and exercise proposal, approval, writeback, and replay.
 4. Push the validated contract when the team needs a shared registry and review
    surface.
+5. Create a source-scoped Runner token, download a bundle, and verify the
+   registration heartbeat.
+6. Sync one staging proposal, approve it in Cloud, and verify the local guarded
+   write plus linked receipt/replay chronology.
 
 See [Cloud Push](cloud-push.md), [Runner Bundles](runner-bundles.md), and
 [Cloud Mode](cloud-mode.md) for commands and deployment details. See

package/docs/release-notes.md

@@ -10,6 +10,71 @@ npx -y -p @synapsor/runner synapsor-runner demo --quick
 The OSS runner command is `synapsor-runner`. The `synapsor` command is reserved
 for the Synapsor Cloud CLI.
 
+## 1.4.122 (prepared, not published)
+
+### Trusted principal scope and Cloud-linked authority
+
+- Contracts may bind a reviewed target column to a required trusted principal
+  in addition to the existing tenant lock. Runner applies both predicates in
+  SQL and never accepts the principal value from model arguments.
+- Same-tenant rows owned by another principal and cross-principal evidence,
+  proposal, receipt, and replay handles return the same generic miss as absent
+  or cross-tenant resources.
+- PostgreSQL/MySQL live tests cover scoped read/propose/insert/update/delete,
+  aggregate and bounded-set operations, conflict/idempotency, compensation,
+  signed HTTP sessions, and generic denial behavior.
+- In explicit `cloud_linked` mode, Cloud is authoritative for governance while
+  the local/shared Runner store remains the durable operational spool. An
+  idempotent outbox synchronizes bounded proposal/activity/result metadata;
+  full evidence, source rows, SQL details, replay payloads, and credentials
+  remain local.
+- Cloud-linked approval and apply cannot fall back to local operator commands.
+  The trusted Runner still verifies the exact local contract, proposal hash,
+  tenant/principal guards, bounds, conflict checks, and receipt rules before
+  source mutation.
+- A separate `@synapsor/cli@0.1.0-beta.1` package manages Cloud contracts,
+  projects, scoped credentials, Runner connections, proposal decisions, and
+  audit records. Runner keeps the `synapsor-runner` binary and local boundary.
+
+Prepared package versions: `@synapsor/spec@1.4.2`,
+`@synapsor/dsl@1.4.3`, `@synapsor/runner@1.4.122`, and
+`@synapsor/cli@0.1.0-beta.1`.
+
+## 1.4.121 (prepared, not published)
+
+### Contract trust surface and bounded-set parser correctness
+
+- Fixes BUG-018, where a documented fixed predicate containing multiple
+  equality terms joined by `AND` could compile as one string-valued term and
+  then fail closed with no matching source rows.
+- The DSL compiler now consumes the complete clause, keeps `AND` inside quoted
+  strings, preserves ordered typed literals, and rejects malformed or
+  unsupported expressions before serving or proposal creation.
+- This does not add free-form SQL predicates: only fixed literal equality terms
+  joined by `AND` are supported. `OR`, parentheses, inequalities, ranges, and
+  model-authored predicates remain unsupported.
+- PostgreSQL and MySQL live verification proves all terms are applied together
+  within trusted tenant scope, source rows remain unchanged before approval,
+  and guarded apply, receipt/replay, retry, caps, and drift checks remain green.
+- Contract authors gain one parser-backed review path: stdio LSP diagnostics,
+  completion, hover, and formatting; plain-language explanation; deterministic
+  lint; and adopter-owned static/disposable contract tests.
+- Scoped object/principal reports export redacted JSON, Markdown, or PDF ledger
+  metadata with digest/signature verification. They are tamper-evident exports,
+  not a claim that local SQLite is immutable compliance storage.
+- DSL enum arguments compile to the canonical enum shape and are enforced by
+  every Runner transport. Canonical aggregate reads return one fixed
+  tenant-scoped COUNT/SUM/AVG scalar, suppress small groups, and persist no
+  member rows or identities in evidence/query audit.
+- Graduated trust remains disabled by default and operator-only. It can create
+  and export a verified, bounded policy recommendation artifact, but cannot
+  auto-approve, push, or activate it.
+- C++/Cloud validators and exporters preserve the new additive enum/aggregate
+  fields for canonical round-trip compatibility.
+
+Prepared package versions: `@synapsor/spec@1.4.1`,
+`@synapsor/dsl@1.4.2`, and `@synapsor/runner@1.4.121`.
+
 ## 1.4.12 (prepared, not published)
 
 ### Runtime-store smoke-call consistency

package/docs/rfcs/007-trusted-principal-row-scope.md

@@ -0,0 +1,75 @@
+# RFC 007: Trusted Principal Row Scope
+
+Status: accepted for implementation
+
+## Problem
+
+Runner already binds a trusted tenant and principal to a context, but the
+principal is currently identity/audit metadata rather than a database row
+predicate. Two users in one tenant can therefore share a tenant-scoped
+capability even when each should see only rows assigned to that user.
+
+## Canonical Shape
+
+Add one optional subject field:
+
+```json
+{
+  "tenant_key": "hospital_id",
+  "principal_scope_key": "assigned_to"
+}
+```
+
+The value for `principal_scope_key` always comes from the capability context's
+required `principal_binding`. The contract does not store a principal value and
+the model does not supply one.
+
+The DSL form is:
+
+```sql
+TENANT KEY hospital_id
+PRINCIPAL SCOPE KEY assigned_to
+```
+
+No second representation is introduced. Existing contracts without the field
+retain their current tenant-scoped semantics.
+
+## Invariant
+
+```text
+effective row authority = tenant predicate
+                          AND principal predicate
+                          AND reviewed fixed guards
+```
+
+Principal scope is invalid without tenant scope or without a required trusted
+principal binding. It cannot replace tenant scope, use a model argument, OR
+with another predicate, default to match-all, or be bypassed dynamically. A
+tenant-wide supervisor uses a separately reviewed capability without principal
+scope.
+
+## Enforcement
+
+The principal predicate is a bound SQL parameter in every applicable read,
+proposal, aggregate, bounded-set, CRUD, compensation, and apply-time query.
+INSERT forces the reviewed column from trusted context. Executor envelopes carry
+an immutable reviewed scope guard. The principal scope is included in proposal
+integrity and writeback authority.
+
+Cloud receives only the reviewed column/binding metadata and a stable safe
+fingerprint. The local proposal retains the trusted value needed for SQL. A
+Cloud job cannot substitute it; Runner verifies the job fingerprint, proposal
+hash, and contract digest before mutation.
+
+Evidence, proposal, receipt, activity, and replay lookups recheck tenant and
+principal authority. Opaque handles are not bearer credentials. A same-tenant
+cross-principal miss has the same public result as a cross-tenant or absent row,
+and the query performs no separate existence probe.
+
+## Compatibility And Release
+
+The field changes `@synapsor/spec`, `@synapsor/dsl`, and Runner behavior. It is
+covered by canonical normalization/digest tests, TypeScript/C++ round-trip
+fixtures, PostgreSQL/MySQL live tests, and packed-package tests. The next Runner
+release remains on the `1.4.x` line and targets `1.4.122` if unused; this RFC
+does not justify a `1.5.0` jump.

package/docs/runner-bundles.md

@@ -11,6 +11,7 @@ Every bundle contains:
 ```text
 synapsor.contract.json
 synapsor.runner.json
+synapsor.cloud.json
 .env.example
 README.md
 mcp-client-examples/
@@ -43,9 +44,27 @@ set -a && . ./.env && set +a
 npx -y -p @synapsor/runner synapsor-runner contract validate ./synapsor.contract.json
 npx -y -p @synapsor/runner synapsor-runner config validate --config ./synapsor.runner.json
 npx -y -p @synapsor/runner synapsor-runner tools preview --config ./synapsor.runner.json --store ./.synapsor/local.db
+npx -y -p @synapsor/runner synapsor-runner cloud connect --config ./synapsor.cloud.json
 npx -y -p @synapsor/runner synapsor-runner mcp serve --config ./synapsor.runner.json --store ./.synapsor/local.db
 ```
 
+For proposal contracts, run the trusted worker in a separate
+operator-controlled terminal:
+
+```bash
+set -a && . ./.env && set +a
+npx -y -p @synapsor/runner synapsor-runner start --config ./synapsor.runner.json --store ./.synapsor/local.db
+```
+
+After an MCP tool creates a local proposal, sync its reviewed diff and safe
+references to Cloud:
+
+```bash
+npx -y -p @synapsor/runner synapsor-runner cloud sync latest \
+  --config ./synapsor.cloud.json \
+  --store ./.synapsor/local.db
+```
+
 For the OpenAI Agents SDK, use the included TypeScript examples. Their stdio
 command enables `--alias-mode openai`; the Streamable HTTP example includes the
 matching server command. Claude, Cursor, and generic templates use canonical
@@ -57,3 +76,8 @@ Approval and writeback remain outside the model-facing MCP tool surface. Use
 The bundle's `.env.example` contains names and placeholders only. Fill it for a
 local or staging source, source it into the shell or process that launches your
 MCP client, and keep the resulting `.env` out of source control.
+
+The Cloud `source_id` scopes the Runner token and job queue. The contract's
+source alias selects the local database adapter. They are intentionally
+different identifiers. Cloud jobs never contain a database URL or handler
+secret.