@synapsor/runner 1.4.121 → 1.4.123

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/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,54 @@ 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.123 (prepared, not published)
+
+### Advisory capability-surface fitness lint
+
+- `contract lint` now reports high-signal breadth-drift advisories for generic
+  query/predicate-style string arguments, capability density above eight on one
+  target, operation names that do not read as business actions, and structural
+  near-duplicates with identical or loosened arguments.
+- Findings are deterministic across declaration order and share stable codes in
+  text, JSON, and SARIF. JSON/SARIF include reviewer-safe metrics and structural
+  differences without reading a database or environment values.
+- Advisory-only lint still exits successfully by default. Teams may opt into a
+  CI policy gate with `--strict` or `--fail-on warning`; canonical validity and
+  runtime enforcement are unchanged.
+
+Prepared package version: `@synapsor/runner@1.4.123`. Spec, DSL, and Cloud CLI
+packages are unchanged.
+
+## 1.4.122 (2026-07-16)
+
+### 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

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.

package/docs/running-a-runner-fleet.md

@@ -132,6 +132,14 @@ Every served capability context must bind tenant and principal from
 `HTTP_CLAIM`. Runner rejects an environment-bound contract mixed into this
 server with `TRUSTED_CONTEXT_PROVIDER_CONFLICT` before tools are served.
 
+For same-tenant per-user rows, declare `PRINCIPAL SCOPE KEY assigned_to` (or
+the corresponding canonical `principal_scope_key`) on the capability. The
+signed `sub` claim then becomes a bound SQL predicate composed with the signed
+tenant claim. Session token fingerprint pinning prevents swapping identities
+within an MCP session. `tools preview` displays both locks, and
+`corepack pnpm test:principal-scope` proves two concurrent principals cannot
+read each other's rows or evidence handles on Postgres and MySQL.
+
 Use an HTTPS JWKS URL from an allowlisted identity system. Runner rejects
 redirects, oversized responses, unknown algorithms, `none`, missing/unknown
 `kid`, bad issuer/audience, expired/not-yet-valid tokens, and private JWK

package/docs/security-boundary.md

@@ -50,6 +50,20 @@ Trusted context comes from local configuration, environment bindings, or Cloud
 session context in Cloud mode. Tenant, principal, and authorization scope must
 not be accepted from the model as authority.
 
+A capability may declare `principal_scope_key` (DSL: `PRINCIPAL SCOPE KEY`) to
+narrow rows inside a tenant. Runner then adds both fixed, parameterized guards:
+
+```text
+tenant_key = verified tenant AND principal_scope_key = verified principal
+```
+
+This applies to single-row reads and writes, aggregates, bounded sets, inserts,
+deletes, executor envelopes, and reviewed compensation. Missing principal
+context fails closed. A principal lock never replaces tenant scope and has no
+dynamic supervisor bypass. Use a separately reviewed tenant-wide capability
+for broader roles. RLS and restricted database roles remain valuable defense in
+depth; the contract does not replace them.
+
 Proposal, evidence, and replay handles are references, not bearer credentials.
 Before returning a local MCP resource, Runner resolves the resource's owning
 capability context again and requires both tenant and principal to match the
@@ -76,7 +90,7 @@ outside the model-facing MCP server and verifies:
 - local approval state;
 - proposal and job digests;
 - target schema/table;
-- primary-key and tenant guards;
+- primary-key, tenant, and declared principal-row guards;
 - allowed mutable columns;
 - conflict/version guard;
 - idempotency key;
@@ -128,7 +142,10 @@ credentials, approval tools, commit tools, or controls that widen reviewed
 tables/columns.
 
 Contract lint and tests are review aids rather than a proof of complete
-security. Scoped report exports omit evidence rows and kept-out values and are
+security. Capability breadth can still drift as narrow tools accumulate;
+surface-fitness lint makes high-signal generic, dense, poorly named, and
+near-duplicate surfaces visible for review but does not enforce good design.
+Scoped report exports omit evidence rows and kept-out values and are
 tamper-evident when their digest/signature verifies; local SQLite is not an
 immutable compliance service. Graduated-trust evaluation is operator-only,
 disabled by default, and can recommend/export a separate artifact but cannot

package/examples/runner-fleet/seed/mysql.sql

@@ -4,6 +4,7 @@ CREATE TABLE invoices (
   status varchar(64) NOT NULL,
   late_fee_cents integer NOT NULL,
   waiver_reason varchar(500),
+  assigned_to varchar(128) NOT NULL DEFAULT 'case_manager_a',
   updated_at datetime(6) NOT NULL
 );
 
@@ -41,7 +42,10 @@ INSERT INTO guard_crud_items (id, tenant_id, request_id, value_cents, version) V
 ALTER TABLE guard_crud_items AUTO_INCREMENT = 2001;
 
 INSERT INTO invoices (id, tenant_id, status, late_fee_cents, waiver_reason, updated_at) VALUES
-  ('MYSQL-ACME', 'acme', 'overdue', 700, NULL, '2026-07-12 12:00:00.000000');
+  ('MYSQL-ACME', 'acme', 'overdue', 700, NULL, '2026-07-12 12:00:00.000000'),
+  ('MYSQL-PRINCIPAL-A', 'hospital_a', 'principal_fixture', 100, NULL, '2026-07-12 12:00:00.000000'),
+  ('MYSQL-PRINCIPAL-B', 'hospital_a', 'principal_fixture', 200, NULL, '2026-07-12 12:00:00.000000');
+UPDATE invoices SET assigned_to = 'case_manager_b' WHERE id = 'MYSQL-PRINCIPAL-B';
 
 CREATE VIEW slow_invoices AS
 SELECT invoices.*, SLEEP(0.35) AS synthetic_delay

package/examples/runner-fleet/seed/postgres.sql

@@ -4,6 +4,7 @@ CREATE TABLE public.invoices (
   status text NOT NULL,
   late_fee_cents integer NOT NULL,
   waiver_reason text,
+  assigned_to text NOT NULL DEFAULT 'case_manager_a',
   updated_at timestamptz NOT NULL
 );
 
@@ -73,7 +74,10 @@ INSERT INTO public.invoices (id, tenant_id, status, late_fee_cents, waiver_reaso
   ('INV-DEAD-DISCARD', 'acme', 'overdue', 1750, NULL, '2026-07-12T12:00:00Z'),
   ('INV-KILL-BEFORE', 'acme', 'overdue', 1200, NULL, '2026-07-12T12:00:00Z'),
   ('INV-KILL-DURING', 'acme', 'overdue', 1500, NULL, '2026-07-12T12:00:00Z'),
-  ('INV-KILL-AFTER', 'acme', 'overdue', 1800, NULL, '2026-07-12T12:00:00Z');
+  ('INV-KILL-AFTER', 'acme', 'overdue', 1800, NULL, '2026-07-12T12:00:00Z'),
+  ('INV-PRINCIPAL-A', 'hospital_a', 'principal_fixture', 100, NULL, '2026-07-12T12:00:00Z'),
+  ('INV-PRINCIPAL-B', 'hospital_a', 'principal_fixture', 200, NULL, '2026-07-12T12:00:00Z');
+UPDATE public.invoices SET assigned_to = 'case_manager_b' WHERE id = 'INV-PRINCIPAL-B';
 
 CREATE FUNCTION public.synthetic_pool_delay() RETURNS integer
 LANGUAGE plpgsql VOLATILE AS $$

package/examples/support-plan-credit/README.md

@@ -272,10 +272,12 @@ Real push uses your Cloud env vars:
 
 ```bash
 export SYNAPSOR_CLOUD_BASE_URL="https://api.synapsor.ai"
-export SYNAPSOR_CLOUD_TOKEN="<workspace-scoped-token>"
-export SYNAPSOR_WORKSPACE_ID="<workspace_id>"
+export SYNAPSOR_API_KEY="<contracts-write-service-key>"
+export SYNAPSOR_PROJECT_ID="<project_id>"
+export SYNAPSOR_SOURCE_ID="<cloud_source_id>"
 
 synapsor-runner cloud push examples/support-plan-credit/synapsor.contract.json \
+  --workspace "$SYNAPSOR_PROJECT_ID" \
   --name support-plan-credit
 ```
 
@@ -283,11 +285,11 @@ After push, Cloud can return the registered version and a runner bundle with
 placeholder env names:
 
 ```bash
-curl -H "Authorization: Bearer $SYNAPSOR_CLOUD_TOKEN" \
-  "$SYNAPSOR_CLOUD_BASE_URL/v1/control/projects/$SYNAPSOR_WORKSPACE_ID/agent-contracts/<contract_id>/versions/<version_id>"
+curl -H "Authorization: Bearer $SYNAPSOR_API_KEY" \
+  "$SYNAPSOR_CLOUD_BASE_URL/v1/control/projects/$SYNAPSOR_PROJECT_ID/agent-contracts/<contract_id>/versions/<version_id>"
 
-curl -H "Authorization: Bearer $SYNAPSOR_CLOUD_TOKEN" \
-  "$SYNAPSOR_CLOUD_BASE_URL/v1/control/projects/$SYNAPSOR_WORKSPACE_ID/agent-contracts/<contract_id>/versions/<version_id>/runner-bundle?download=1" \
+curl -H "Authorization: Bearer $SYNAPSOR_API_KEY" \
+  "$SYNAPSOR_CLOUD_BASE_URL/v1/control/projects/$SYNAPSOR_PROJECT_ID/agent-contracts/<contract_id>/versions/<version_id>/runner-bundle?download=1&source_id=$SYNAPSOR_SOURCE_ID" \
   -o support-plan-credit-runner-bundle.zip
 ```
 

package/fixtures/contracts/capability-surface-fitness.contract.json

@@ -0,0 +1,190 @@
+{
+  "spec_version": "0.1",
+  "kind": "SynapsorContract",
+  "metadata": {
+    "name": "capability surface fitness fixture",
+    "description": "Exercises advisory capability-breadth review without changing contract validity.",
+    "version": "1.0.0"
+  },
+  "resources": [
+    {
+      "name": "billing_invoices",
+      "engine": "postgres",
+      "schema": "public",
+      "table": "invoices",
+      "type": "table",
+      "primary_key": "id",
+      "tenant_key": "tenant_id",
+      "conflict_key": "updated_at"
+    }
+  ],
+  "contexts": [
+    {
+      "name": "billing_operator",
+      "bindings": [
+        {
+          "name": "tenant_id",
+          "source": "environment",
+          "key": "SYNAPSOR_TENANT_ID",
+          "required": true
+        }
+      ],
+      "tenant_binding": "tenant_id"
+    }
+  ],
+  "capabilities": [
+    {
+      "name": "billing.execute",
+      "description": "Look up one reviewed invoice reference.",
+      "returns_hint": "One allowlisted invoice row.",
+      "kind": "read",
+      "context": "billing_operator",
+      "source": "local_postgres",
+      "subject": { "resource": "billing_invoices" },
+      "args": {
+        "filter": { "type": "string", "required": true, "max_length": 128 }
+      },
+      "lookup": { "id_from_arg": "filter" },
+      "visible_fields": ["id", "tenant_id", "status"],
+      "kept_out_fields": ["card_token", "internal_note"],
+      "evidence": { "required": true, "query_audit": true },
+      "max_rows": 1
+    },
+    {
+      "name": "billing.inspect_invoice_primary",
+      "description": "Inspect one primary invoice.",
+      "returns_hint": "One allowlisted invoice row.",
+      "kind": "read",
+      "context": "billing_operator",
+      "source": "local_postgres",
+      "subject": { "resource": "billing_invoices" },
+      "args": {
+        "invoice_id": { "type": "string", "required": true, "max_length": 128 }
+      },
+      "lookup": { "id_from_arg": "invoice_id" },
+      "visible_fields": ["id", "tenant_id", "status"],
+      "kept_out_fields": ["card_token", "internal_note"],
+      "evidence": { "required": true, "query_audit": true },
+      "max_rows": 1
+    },
+    {
+      "name": "billing.inspect_invoice_copy",
+      "description": "Inspect the same reviewed invoice shape for duplicate detection.",
+      "returns_hint": "One allowlisted invoice row.",
+      "kind": "read",
+      "context": "billing_operator",
+      "source": "local_postgres",
+      "subject": { "resource": "billing_invoices" },
+      "args": {
+        "invoice_id": { "type": "string", "required": true, "max_length": 128 }
+      },
+      "lookup": { "id_from_arg": "invoice_id" },
+      "visible_fields": ["id", "tenant_id", "status"],
+      "kept_out_fields": ["card_token", "internal_note"],
+      "evidence": { "required": true, "query_audit": true },
+      "max_rows": 1
+    },
+    {
+      "name": "billing.inspect_invoice_secondary",
+      "description": "Inspect one secondary invoice.",
+      "returns_hint": "One allowlisted invoice row.",
+      "kind": "read",
+      "context": "billing_operator",
+      "source": "local_postgres",
+      "subject": { "resource": "billing_invoices" },
+      "args": {
+        "secondary_invoice_id": { "type": "string", "required": true, "max_length": 128 }
+      },
+      "lookup": { "id_from_arg": "secondary_invoice_id" },
+      "visible_fields": ["id", "tenant_id", "status"],
+      "kept_out_fields": ["card_token", "internal_note"],
+      "evidence": { "required": true, "query_audit": true },
+      "max_rows": 1
+    },
+    {
+      "name": "billing.inspect_invoice_archived",
+      "description": "Inspect one archived invoice.",
+      "returns_hint": "One allowlisted invoice row.",
+      "kind": "read",
+      "context": "billing_operator",
+      "source": "local_postgres",
+      "subject": { "resource": "billing_invoices" },
+      "args": {
+        "archived_invoice_id": { "type": "string", "required": true, "max_length": 128 }
+      },
+      "lookup": { "id_from_arg": "archived_invoice_id" },
+      "visible_fields": ["id", "tenant_id", "status"],
+      "kept_out_fields": ["card_token", "internal_note"],
+      "evidence": { "required": true, "query_audit": true },
+      "max_rows": 1
+    },
+    {
+      "name": "billing.inspect_invoice_disputed",
+      "description": "Inspect one disputed invoice.",
+      "returns_hint": "One allowlisted invoice row.",
+      "kind": "read",
+      "context": "billing_operator",
+      "source": "local_postgres",
+      "subject": { "resource": "billing_invoices" },
+      "args": {
+        "disputed_invoice_id": { "type": "string", "required": true, "max_length": 128 }
+      },
+      "lookup": { "id_from_arg": "disputed_invoice_id" },
+      "visible_fields": ["id", "tenant_id", "status"],
+      "kept_out_fields": ["card_token", "internal_note"],
+      "evidence": { "required": true, "query_audit": true },
+      "max_rows": 1
+    },
+    {
+      "name": "billing.inspect_invoice_overdue",
+      "description": "Inspect one overdue invoice.",
+      "returns_hint": "One allowlisted invoice row.",
+      "kind": "read",
+      "context": "billing_operator",
+      "source": "local_postgres",
+      "subject": { "resource": "billing_invoices" },
+      "args": {
+        "overdue_invoice_id": { "type": "string", "required": true, "max_length": 128 }
+      },
+      "lookup": { "id_from_arg": "overdue_invoice_id" },
+      "visible_fields": ["id", "tenant_id", "status"],
+      "kept_out_fields": ["card_token", "internal_note"],
+      "evidence": { "required": true, "query_audit": true },
+      "max_rows": 1
+    },
+    {
+      "name": "billing.inspect_invoice_paid",
+      "description": "Inspect one paid invoice.",
+      "returns_hint": "One allowlisted invoice row.",
+      "kind": "read",
+      "context": "billing_operator",
+      "source": "local_postgres",
+      "subject": { "resource": "billing_invoices" },
+      "args": {
+        "paid_invoice_id": { "type": "string", "required": true, "max_length": 128 }
+      },
+      "lookup": { "id_from_arg": "paid_invoice_id" },
+      "visible_fields": ["id", "tenant_id", "status"],
+      "kept_out_fields": ["card_token", "internal_note"],
+      "evidence": { "required": true, "query_audit": true },
+      "max_rows": 1
+    },
+    {
+      "name": "billing.inspect_invoice_voided",
+      "description": "Inspect one voided invoice.",
+      "returns_hint": "One allowlisted invoice row.",
+      "kind": "read",
+      "context": "billing_operator",
+      "source": "local_postgres",
+      "subject": { "resource": "billing_invoices" },
+      "args": {
+        "voided_invoice_id": { "type": "string", "required": true, "max_length": 128 }
+      },
+      "lookup": { "id_from_arg": "voided_invoice_id" },
+      "visible_fields": ["id", "tenant_id", "status"],
+      "kept_out_fields": ["card_token", "internal_note"],
+      "evidence": { "required": true, "query_audit": true },
+      "max_rows": 1
+    }
+  ]
+}

package/fixtures/dsl/principal-row-scope.synapsor.sql

@@ -0,0 +1,23 @@
+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
+  DESCRIPTION 'Inspect one patient assigned to the authenticated case manager within the trusted hospital.'
+  RETURNS HINT 'Returns reviewed patient fields and evidence only when both tenant and assignee locks match.'
+  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 DESCRIPTION 'Reviewed patient identifier.'
+  ALLOW READ id, hospital_id, display_name, care_status, updated_at
+  KEEP OUT assigned_to, diagnosis_notes, insurance_member_id
+  REQUIRE EVIDENCE
+  MAX ROWS 1
+END