@synapsor/runner 1.4.121 → 1.4.123

package/docs/README.md

@@ -142,6 +142,7 @@ no-database demo, wire your database, then read deeper concepts.
   topology, claim-bound sessions, pools, fleet rate limits, quorum, metrics,
   dead letters, backup/restore/retention, and kill/recovery evidence.
 - [Cloud Mode](cloud-mode.md): what stays local and what Cloud-linked mode adds.
+- [Synapsor Cloud CLI](cloud-cli.md): command, credential, entitlement, and Cloud-linked authority reference.
 - [OSS Runner Vs Synapsor Cloud](oss-vs-cloud.md): detailed product and
   operational boundary.
 - [Cloud Push](cloud-push.md): register a validated local contract in the

package/docs/capability-authoring.md

@@ -84,11 +84,14 @@ synapsor-runner contract bundle ./synapsor.contract.json --out ./synapsor-runner
 synapsor-runner cloud push ./synapsor.contract.json --dry-run
 synapsor-runner cloud push ./synapsor.contract.json \
   --api-url "$SYNAPSOR_CLOUD_BASE_URL" \
-  --token "$SYNAPSOR_CLOUD_TOKEN" \
   --workspace "$SYNAPSOR_PROJECT_ID" \
   --name billing-late-fee
 ```
 
+Set `SYNAPSOR_API_KEY` for scoped CI automation or
+`SYNAPSOR_CLOUD_ACCESS_TOKEN` for a signed-in human. Secrets are not accepted
+as command-line flags.
+
 Reference the generated contract from local runner wiring:
 
 ```json
@@ -118,6 +121,22 @@ synapsor-runner mcp serve --config ./synapsor.runner.json --store ./.synapsor/lo
 capabilities cannot accidentally lose descriptions, returns hints, or numeric
 patch bounds during review.
 
+After compilation, run the canonical contract through the surface review:
+
+```bash
+synapsor-runner contract lint ./synapsor.contract.json
+synapsor-runner contract lint ./synapsor.contract.json --strict
+```
+
+The default command keeps capability-surface findings advisory; `--strict` opts
+into warning-as-failure CI policy. Review capabilities using a simple fitness
+test: if the name is not a business operation an audit log would recognize, ask
+whether the model should receive it. Lint also surfaces generic query-like
+string arguments, more than eight capabilities on one target, and structurally
+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.
+
 ## DSL / JSON Capability Parity
 
 The DSL compiles to canonical `@synapsor/spec` JSON. It must not silently weaken
@@ -318,6 +337,45 @@ Bad:
 
 Runner rejects model-facing trust-scope arguments.
 
+### Same-Tenant Principal Row Scope
+
+Tenant scope separates organizations. When multiple authenticated users share
+one tenant but should see only rows assigned to them, add a second reviewed
+lock:
+
+```sql
+CREATE AGENT CONTEXT care_session
+  BIND hospital_id FROM HTTP_CLAIM hospital_id REQUIRED
+  BIND principal FROM HTTP_CLAIM sub REQUIRED
+  TENANT BINDING hospital_id
+  PRINCIPAL BINDING principal
+END
+
+CREATE CAPABILITY care.inspect_assigned_patient
+  USING CONTEXT care_session
+  SOURCE local_postgres
+  ON public.patients
+  PRIMARY KEY id
+  TENANT KEY hospital_id
+  PRINCIPAL SCOPE KEY assigned_to
+  LOOKUP patient_id BY id
+  ARG patient_id STRING REQUIRED MAX LENGTH 128
+  ALLOW READ id, hospital_id, display_name, care_status, updated_at
+  KEEP OUT assigned_to, diagnosis_notes
+  REQUIRE EVIDENCE
+  MAX ROWS 1
+END
+```
+
+Runner generates one parameterized predicate containing both locks. It also
+forces the scope column on reviewed inserts and preserves it through proposals,
+writeback jobs, receipts, replay, and compensation. A same-tenant row assigned
+to another principal has the same public not-found result as an absent or
+cross-tenant row. The scope column may remain kept out of model-visible data.
+Use a separately reviewed tenant-wide capability for supervisors; there is no
+runtime bypass flag. Database RLS and least-privilege roles remain recommended
+defense in depth.
+
 ## Direct SQL Writeback
 
 Use direct SQL writeback for reviewed guarded single-row INSERT, UPDATE, or

package/docs/cloud-cli.md

@@ -0,0 +1,248 @@
+# Synapsor Cloud CLI
+
+Use `synapsor-runner` for the local MCP/database boundary. Use `synapsor` from
+`@synapsor/cli` for Cloud administration, shared review, and audit. Linking a
+Runner to Cloud is optional; local-only Runner mode requires no account.
+
+## Credential Boundaries
+
+| Credential | Used by | Purpose |
+|---|---|---|
+| Human session | `synapsor`, web UI | Administration and human decisions, subject to role, policy, recent auth, and entitlement |
+| Service API key | `synapsor` or `synapsor-runner cloud push` in CI | Explicit project scopes such as contract push or activity export |
+| Runner token | `synapsor-runner` Cloud protocol | Register, heartbeat, proposal/activity sync, leases, and terminal results |
+| Local MCP HTTP token | MCP client to local Runner | Local transport authentication only |
+
+Authentication, project role/scope authorization, and paid feature entitlement
+are independent checks. A valid key can remain authenticated after a billing
+change while paid operations return `payment_required` or
+`feature_not_entitled`. Neither API keys nor Runner tokens bypass plan state.
+
+Never put a Cloud secret, database URL, or local MCP token on a CLI argument.
+Use a masked environment variable or a mode-`0600` secret file.
+
+## Command Index
+
+```text
+auth          login, logout, whoami, profiles, use, configure-service
+status        selected profile, API, project, service health
+entitlements  effective hosted features, limits, and blocked reason
+billing       plan/payment lifecycle summary
+workspaces    list, use
+projects      list, show, use
+sources       list, show (safe metadata only)
+contracts     init, validate, format, inspect, diff, push, list, show,
+              history, pull, activate, rollback
+contexts      list, show, create, update, remove
+capabilities  list, show, create, update, remove, preview
+workflows     list, show, create, update, remove, validate
+api-keys      list, show, create, rotate, revoke
+runners       list, show, create, rotate-token, revoke-token,
+              bundle download, doctor
+proposals     list, show, decisions, approve, reject
+activity      search, show
+evidence      show
+receipts      show
+replay        show, verify
+exports       create, status, download
+```
+
+Run `synapsor --help` for the compact index. All local context/capability/
+workflow edits validate the complete canonical contract and use atomic file
+replacement with a backup. Complex definitions can be supplied with
+`--from-file`; the CLI does not invent unsafe defaults for proposal writeback.
+
+`synapsor <group> --help` lists that group's real commands, and
+`synapsor <group> <command> --help` shows the checked command syntax. The help
+tree and this index are covered together by the CLI test suite.
+
+## Human Login And Project Selection
+
+```bash
+npm install --global @synapsor/cli
+
+synapsor auth login --open
+synapsor auth whoami
+synapsor workspaces list
+synapsor projects list
+synapsor projects use <project-id>
+synapsor status
+synapsor entitlements show
+```
+
+`status` reports authentication, selected project, service health, plan,
+billing lifecycle, effective entitlement, grace deadline, and blocked reason.
+Authentication, project role or service-key scope authorization, and paid
+feature entitlement are separate checks. A valid credential does not bypass
+`payment_required`, `feature_not_entitled`, or `project_inactive`.
+
+## Author A Canonical Contract
+
+Contexts, capabilities, and workflows are reviewed parts of one immutable
+canonical contract, not mutable Cloud permission rows. Local edits are atomic,
+fully validated, and followed by a semantic safety diff.
+
+```bash
+synapsor contracts init ./synapsor.contract.json --name support-contract
+
+synapsor contexts create trusted_operator \
+  --contract ./synapsor.contract.json \
+  --from-file ./context.json
+
+synapsor capabilities create billing.inspect_invoice \
+  --contract ./synapsor.contract.json \
+  --from-file ./capability.json
+
+synapsor workflows create billing.invoice_review \
+  --contract ./synapsor.contract.json \
+  --from-file ./workflow.json
+
+synapsor contracts validate ./synapsor.contract.json
+synapsor contracts diff ./before.json ./synapsor.contract.json
+synapsor contracts push ./synapsor.contract.json --dry-run
+synapsor contracts push ./synapsor.contract.json
+```
+
+Push creates or reuses an immutable version. It does not silently rewrite an
+existing version. Activation and rollback are separate authorized mutations:
+
+```bash
+synapsor contracts history <contract-id>
+synapsor contracts activate <contract-id>/<version-id> --yes
+synapsor contracts rollback <contract-id>/<older-version-id> --yes
+```
+
+The Runner-centric equivalent remains supported:
+
+```bash
+synapsor-runner cloud push ./synapsor.contract.json
+```
+
+It uses the same canonical validation, digest, endpoint, idempotency, and error
+semantics as `synapsor contracts push`.
+
+## Create And Use A CI API Key
+
+Only an authorized human can create, rotate, or revoke keys. The secret is
+returned once and must be written to a protected file; it is never printed by
+normal or JSON output.
+
+```bash
+synapsor api-keys create \
+  --name contract-ci \
+  --scopes project:read,contracts:read,contracts:write \
+  --expires-at 2026-12-31 \
+  --secret-file ./.synapsor/contract-ci.key
+
+export SYNAPSOR_API_KEY="$(cat ./.synapsor/contract-ci.key)"
+synapsor auth configure-service \
+  --profile ci \
+  --api-url https://dev-api.synapsor.ai \
+  --project <project-id> \
+  --credential-env SYNAPSOR_API_KEY
+
+synapsor auth whoami --profile ci --json
+synapsor contracts push ./synapsor.contract.json --profile ci
+```
+
+`whoami` reports a service identity, key prefix/ID, scopes, project,
+expiration, and entitlement summary. It never turns the key into a human
+identity. Rotate and revoke through a human profile:
+
+```bash
+synapsor api-keys rotate <key-id> --secret-file ./.synapsor/contract-ci.next.key
+synapsor api-keys revoke <key-id> --yes
+```
+
+After revocation, requests using the old value fail; they do not fall back to a
+local profile or another credential.
+
+## Connect A Customer-Operated Runner
+
+Runner tokens are separate, source-scoped machine credentials. Create one and
+store its one-time value without printing it:
+
+```bash
+synapsor runners create \
+  --name support-runner \
+  --sources <cloud-source-id> \
+  --secret-file ./.synapsor/runner.token
+
+export SYNAPSOR_RUNNER_TOKEN="$(cat ./.synapsor/runner.token)"
+```
+
+When `--permissions` is omitted, Cloud applies the bounded Runner-protocol
+permission set. Use `--permissions <csv>` to narrow a token further; these
+permissions never authorize human, API-key, contract, or approval operations.
+
+The credential-free Runner bundle contains the reviewed connection metadata
+and sample configuration. Supply the Runner token separately:
+
+```bash
+synapsor runners bundle download <contract-id>/<version-id> \
+  --source <cloud-source-id> \
+  --out ./synapsor-runner-bundle.zip
+synapsor runners doctor <runner-id>
+```
+
+Runner tokens authenticate only registration, heartbeat, proposal/activity
+sync, leases, and terminal results. They are rejected by Cloud administration
+and human-decision routes. Source database URLs and write credentials stay in
+the Runner process environment and never enter the bundle, contract, Cloud
+CLI, or Cloud registry.
+
+## Review And Audit
+
+```bash
+synapsor proposals list --status pending
+synapsor proposals show <proposal-id>
+synapsor proposals approve <proposal-id> --reason "Reviewed evidence" --yes
+
+synapsor evidence show <proposal-id>
+synapsor receipts show <proposal-id>
+synapsor replay verify <proposal-id>
+synapsor activity search --lookup <business-id> --json
+```
+
+Proposal approval records Cloud governance state; it never changes the source
+database directly. A trusted Runner must receive an authorized lease and
+recheck the local proposal, exact contract digest, tenant and principal locks,
+allowlists, bounds, conflict/version guard, idempotency, and affected-row rule.
+Service API keys and Runner tokens cannot record human approval.
+
+## Cloud-Linked Runner Authority
+
+`governance.mode: cloud_linked` is explicit. Cloud is authoritative for active
+contract versions, human decisions, job leasing, and terminal governance state.
+The local/shared Runner store remains a durable operational spool and local
+evidence/replay ledger; Cloud and the CLI never open or upload its SQLite file.
+
+The initial evidence policy is `metadata_only`. Cloud receives bounded proposal
+diffs, safe identities/fingerprints, IDs, counts, and integrity hashes. Source
+rows, evidence payloads, SQL text/parameters, kept-out fields, credentials, and
+local replay payloads remain local.
+
+By default a Cloud-linked Runner durably queues proposals during a transient
+Cloud outage. Set `governance.queue_when_unavailable: false` to fail before the
+source read/proposal is created when authenticated Cloud readiness is not
+available. In both modes, no Cloud approval or writeback proceeds offline.
+
+Inspect and repair the local operational outbox with Runner, not the Cloud CLI:
+
+```bash
+synapsor-runner doctor --config ./synapsor.runner.json --store ./.synapsor/local.db
+synapsor-runner cloud outbox status --config ./synapsor.runner.json --store ./.synapsor/local.db
+synapsor-runner cloud outbox inspect latest --config ./synapsor.runner.json --store ./.synapsor/local.db
+synapsor-runner cloud outbox reconcile --yes --config ./synapsor.runner.json --store ./.synapsor/local.db
+```
+
+Dead-letter or hash-divergence state requires operator inspection. Runner never
+silently chooses a local copy over Cloud or creates a fake local human approval.
+
+## Pagination And JSON
+
+List/search commands accept `--limit`, `--cursor`, and bounded `--all`.
+`--max-items` can lower the aggregate bound; raising it beyond the safe default
+requires `--allow-large-result`. Use `--json` for scripts. Unknown or transient
+failures are not retried as mutations; shared client retries are limited to
+classified safe requests and honor server retry timing.

package/docs/cloud-mode.md

@@ -15,9 +15,35 @@ Cloud-linked mode is for teams that need a shared control plane:
 - receipt reporting;
 - retention and audit visibility.
 
-The local runner still keeps database credentials in your environment. MCP
-client config snippets should contain command paths and runner arguments, not
-database URLs or write credentials.
+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.
+
+## Trust Boundary
+
+```text
+agent / MCP client
+  -> local Runner semantic tools
+  -> local scoped read + evidence
+  -> local proposal (source unchanged)
+  -> reviewed diff + safe references synced to Cloud
+  -> signed-in human approves or rejects in Cloud
+  -> source-scoped leased job
+  -> local trusted worker rechecks contract + proposal + DB guards
+  -> local database write
+  -> redacted receipt/activity linkage returned to Cloud
+```
+
+Cloud receives the contract/version/digest, capability, trusted scope
+identifiers, reviewable allowlisted diff, safe evidence/query references,
+decision identity, lease state, and receipt/replay links. Database URLs,
+passwords, handler tokens, private keys, full source rows, and kept-out evidence
+payloads stay local.
+
+Maintainers must run the opt-in
+[hosted Cloud-linked verification](./hosted-cloud-linked-verification.md) with a
+packed Runner, disposable Cloud project, and synthetic source before claiming a
+release is Cloud-linked end to end.
 
 Push and retrieve the portable contract without moving database credentials
 into Cloud:
@@ -29,11 +55,67 @@ synapsor-runner cloud push ./synapsor.contract.json \
   --name support-plan-credit
 ```
 
+Use the current design-partner API base:
+
+```bash
+export SYNAPSOR_CLOUD_BASE_URL="https://dev-api.synapsor.ai"
+```
+
+Then create a source-scoped Runner token in **Contract registry -> Connect
+Runner**, download the selected version's bundle, and run:
+
+```bash
+cd ./<downloaded-runner-bundle>
+cp .env.example .env
+# Fill the placeholders in .env, including the one-time Runner token.
+set -a && . ./.env && set +a
+
+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
+```
+
+Run the trusted worker in a second operator-controlled terminal:
+
+```bash
+set -a && . ./.env && set +a
+npx -y -p @synapsor/runner synapsor-runner runner start --config ./synapsor.runner.json --store ./.synapsor/local.db
+```
+
+For deployment checks or an operator-controlled single claim cycle, use the
+same installed worker with `--once`; it exits after applying at most one
+Cloud-approved job and still rechecks the local contract, proposal, tenant,
+version, bounds, and idempotency guards:
+
+```bash
+npx -y -p @synapsor/runner synapsor-runner runner start --once --config ./synapsor.runner.json --store ./.synapsor/local.db
+```
+
+When a local proposal exists:
+
+```bash
+npx -y -p @synapsor/runner synapsor-runner cloud sync latest --config ./synapsor.cloud.json --store ./.synapsor/local.db
+```
+
 See [Cloud Push](cloud-push.md) and [Runner Bundles](runner-bundles.md).
 
-Cloud registry storage preserves approval policies but does not, by itself,
-mean hosted policy enforcement is enabled. Local Runner enforcement and hosted
-Cloud approval enforcement are separate runtime boundaries.
+Cloud approval changes proposal state and creates a claimable job; it does not
+touch the source database directly. If a lease expires, another compatible
+Runner may claim the job, but source and ledger idempotency prevent a duplicate
+effect. Stale row/set guards return a conflict. If the system cannot prove
+whether a source write committed, it records an indeterminate/reconciliation
+state instead of retrying blindly.
+
+Runner tokens are scoped to one project, explicit source IDs, and named
+operations. Rotate or revoke them from Connect Runner. Revocation blocks new
+registration, heartbeat, proposal, claim, lease, activity, and result calls.
+
+This is a single-node design-partner boundary, not managed Runner hosting,
+multi-region HA, SAML/SCIM, legal hold/WORM retention, or an enterprise SLA.
+Run the explicit hosted integration gate with synthetic staging data before
+depending on a deployment; registry push alone is not proof that registration,
+approval, leasing, and receipt synchronization are live.
 
 Run the local smoke for this mode with:
 

package/docs/cloud-push.md

@@ -17,8 +17,8 @@ Dry-run validates and normalizes locally. It performs no network request.
 ## Push
 
 ```bash
-export SYNAPSOR_CLOUD_BASE_URL="https://api.synapsor.ai"
-export SYNAPSOR_CLOUD_TOKEN="<workspace-scoped-token>"
+export SYNAPSOR_CLOUD_BASE_URL="https://dev-api.synapsor.ai"
+export SYNAPSOR_API_KEY="<contracts-write-service-key>"
 export SYNAPSOR_WORKSPACE_ID="<workspace-id>"
 
 synapsor-runner cloud push ./synapsor.contract.json \
@@ -29,7 +29,9 @@ The response includes the contract id, immutable version id, server-computed
 digest, summary counts, status, and registry path. Identical normalized content
 is idempotent; changed content creates the next version.
 
-Tokens are sent in the authorization header and are never part of the contract.
+Use `SYNAPSOR_API_KEY` for scoped CI automation or
+`SYNAPSOR_CLOUD_ACCESS_TOKEN` for an authenticated human session. Credentials
+are sent in the authorization header and are never part of the contract.
 Database URLs, passwords, private keys, and model-controlled tenant bindings
 are rejected by server-side validation.
 
@@ -42,6 +44,11 @@ permission (`403`), missing workspace/API paths (`404`), registry conflicts
 (`409`), server validation (`422`), and Cloud/network failures. Error output
 does not echo the bearer token.
 
+`dev-api.synapsor.ai` is the supported design-partner endpoint. Do not replace
+it with `api.synapsor.ai` unless Synapsor has separately announced and verified
+that hostname. Contract push uses a signed-in workspace/API credential;
+Runner registration and jobs use a separate source-scoped Runner token.
+
 ## Cloud To Local
 
 Open **Contract registry** in the workspace, choose a version, and download its
@@ -49,6 +56,16 @@ runner bundle. The ZIP contains the normalized contract, local runner wiring,
 placeholder environment file, README, and MCP client examples. It contains no
 live credentials or table rows.
 
+Choose the Cloud source when downloading because each bundle is source-bound:
+
+```bash
+synapsor runners bundle download <contract-id>/<version-id> \
+  --source <cloud-source-id> \
+  --out ./synapsor-runner-bundle.zip
+```
+
 Cloud currently preserves approval policy definitions in the contract and
-bundle. Hosted approval-policy enforcement remains a separate Cloud feature;
-do not infer it from registry storage alone.
+bundle. Cloud approval is a human-authenticated decision and is not exposed to
+the Runner token or MCP. The local Runner remains responsible for rechecking
+the exact contract digest, proposal hash, tenant, target, allowed fields,
+conflict/version guard, bounds, and one-write/idempotency rules before applying.

package/docs/conformance.md

@@ -32,6 +32,7 @@ Current fixture groups:
 - `numeric-bounds`
 - `bounded-set-threats`
 - `reversible-change-sets`
+- `principal-row-scope`
 
 The fixture set is intentionally small in 0.1. It covers the runner-supported
 semantic surface first: trusted context, scoped reads, evidence handles,
@@ -54,6 +55,10 @@ compensation proposal, not rollback: apply-time receipts capture only
 allowlisted inverse data, compensation uses fresh guards and exact members,
 ambiguous outcomes fail closed pending reconciliation, and hard delete reports
 a specific best-effort-unavailable reason.
+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.
 
 Additional 0.1 parity coverage currently lives in tests and verification
 scripts rather than separate `cloud-push/` or `dsl-json-parity/` conformance
@@ -81,6 +86,7 @@ Run:
 corepack pnpm --filter @synapsor-runner/mcp-server test
 corepack pnpm test:contract-conformance
 corepack pnpm test:aggregate-read
+corepack pnpm test:principal-scope
 ```
 
 The spec package also validates every conformance contract:

package/docs/contract-review.md

@@ -33,9 +33,42 @@ 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.
 
+### Review Capability-Surface Fitness
+
+Runner structurally limits capability **depth**: contracts cannot turn a model
+argument into raw SQL or a free-form predicate, and trusted tenant/principal
+scope is never model input. A separate review concern is capability **breadth**:
+many individually narrow tools can accumulate until the total model-facing
+surface is difficult to understand.
+
+Use this fitness test during review:
+
+> If a capability cannot be described as a named business operation an audit
+> log would recognize, it probably should not be exposed yet.
+
+`contract lint` reports these deterministic advisory warnings:
+
+| Code | Review signal |
+| --- | --- |
+| `SURFACE_GENERIC_ARGUMENT` | An un-enumerated string argument is literally named `filter`, `query`, `where`, `predicate`, or `sql`. Runner still does not interpolate it into SQL. |
+| `SURFACE_TARGET_DENSITY` | More than eight capabilities target the same normalized source and object. Eight is a review threshold, not a runtime limit. |
+| `SURFACE_OPERATION_NAMING` | A capability name does not match the conservative named-business-operation heuristic. |
+| `SURFACE_NEAR_DUPLICATE` | Two capabilities have the same target, kind, reviewed fields, targeting, write/approval shape, and identical or directionally loosened arguments. |
+
+The default command exits successfully when these advisories are the only
+findings. `--strict` (or `--fail-on warning`) deliberately lets a team turn all
+warnings into a CI policy gate without changing canonical contract validity.
+Text, JSON, and SARIF use the same stable finding set and deterministic order.
+
+Passing these checks does not prove that a surface is safe or well designed.
+Review which operations each agent actually needs; use narrower contracts or
+Runner/client deployments instead of exposing every organization capability to
+every model.
+
 Expected successful output ends with:
 
 ```text
+Surface: N model-facing capabilities across M targets; 0 target(s) above the advisory density threshold of 8
 Summary: 0 error / 0 warning / N info
 ```
 

package/docs/contract-testing.md

@@ -36,11 +36,40 @@ A successful run ends with a stable count such as:
 Summary: 6 passed / 0 failed / 6 total
 ```
 
-Supported assertions cover valid scoped tools, cross-tenant denial, kept-out
+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

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