@synapsor/runner 1.4.12 → 1.4.122

package/docs/README.md

@@ -70,6 +70,12 @@ no-database demo, wire your database, then read deeper concepts.
 - [Recipes](recipes.md): starter business-capability templates.
 - [JSON Schema](../schemas/synapsor.runner.schema.json): editor validation for
   `synapsor.runner.json`.
+- [Contract Review](contract-review.md): LSP setup, plain-language explanation,
+  and deterministic lint/SARIF output.
+- [Contract Testing](contract-testing.md): adopter-owned static and disposable
+  PostgreSQL/MySQL allow/deny/redaction assertions.
+- [Bounded Aggregate Reads](aggregate-reads.md): fixed scalar count/sum/avg,
+  tenant scope, suppression, and no-row evidence.
 
 ## 06 Serve MCP
 
@@ -113,6 +119,10 @@ no-database demo, wire your database, then read deeper concepts.
   and lifecycle inspection.
 - `examples/mysql-refund-agent/`: MySQL order/refund review example using the
   same proposal, approval, guarded writeback, and replay loop.
+- [Scoped Ledger Reports](compliance-reports.md): object/principal JSON,
+  Markdown, and PDF exports with digest/signature verification.
+- [Graduated Trust](graduated-trust.md): off-by-default operator
+  recommendations that never auto-activate a policy.
 
 ## 09 App-Owned Handlers
 
@@ -132,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/aggregate-reads.md

@@ -0,0 +1,49 @@
+# Bounded Aggregate Reads
+
+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.
+
+```sql
+CREATE CAPABILITY billing.overdue_balance_total
+  DESCRIPTION 'Return the reviewed overdue balance total 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
+```
+
+Compile the packaged example with:
+
+```bash
+synapsor-runner dsl compile ./fixtures/dsl/aggregate-read.synapsor.sql \
+  --out ./synapsor.contract.json --strict
+```
+
+A permitted call returns one aggregate scalar; an undersized group returns a
+stable suppressed result. Neither result contains source rows or member IDs.
+
+Supported operations are `COUNT ROWS`, `COUNT NON NULL column`, `SUM column`,
+and `AVG column`. The source, table/view, tenant key, function, column, optional
+equality selection, and minimum group size are contract-authored. The first
+release permits no model arguments, dynamic columns, joins, grouping, arbitrary
+expressions, or model-controlled predicates.
+
+When fewer records match than `MIN GROUP SIZE`, the stable result is suppressed
+and contains no aggregate value or member identity. Allowed results contain one
+scalar plus evidence/query-audit handles. Evidence records the contract digest,
+trusted scope reference, reviewed operation, fixed predicate summary, and
+suppression state; it never stores member rows or IDs.
+
+PostgreSQL and MySQL execution is parameterized and uses the configured
+statement timeout. A dependency outage or statement timeout returns a safe,
+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.

package/docs/bounded-set-writeback.md

@@ -129,20 +129,25 @@ CREATE CAPABILITY tickets.close_overdue
   CONFLICT GUARD version
   LOOKUP reason BY id
   ARG reason STRING REQUIRED MAX LENGTH 100
-  ALLOW READ id, tenant_id, status, cost_cents, version
+  ALLOW READ id, tenant_id, risk_level, case_status, cost_cents, version
   REQUIRE EVIDENCE
   PROPOSE ACTION close_overdue UPDATE SET
-  SELECT WHERE status = 'overdue'
+  SELECT WHERE risk_level = 'high' AND case_status = 'active'
   MAX ROWS 10
   MAX TOTAL cost_cents BEFORE 50000
-  ALLOW WRITE status
-  PATCH status = 'closed'
+  ALLOW WRITE case_status
+  PATCH case_status = 'closed'
   ADVANCE VERSION version USING INTEGER INCREMENT
   APPROVAL ROLE ops_manager
   WRITEBACK DIRECT SQL
 END
 ```
 
+Each `SELECT WHERE` term is a reviewer-fixed literal equality, and every term
+must match. Up to eight terms may be joined by `AND`; quoted `AND` text remains
+part of the value. `OR`, parentheses, inequalities, ranges, and free-form or
+model-authored predicates are not supported.
+
 Compile the contract and create `synapsor.runner.json`:
 
 ```bash

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
@@ -318,6 +321,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/compliance-reports.md

@@ -0,0 +1,42 @@
+# Export Scoped Ledger Reports
+
+Runner can export a deterministic chronology for one business object or one
+principal inside an explicit tenant scope:
+
+```bash
+synapsor-runner report --object invoice:INV-3001 --tenant tenant_acme \
+  --store ./.synapsor/local.db --format markdown --out ./invoice-report.md
+
+synapsor-runner report --principal support.operator --tenant tenant_acme \
+  --store ./.synapsor/local.db --format pdf --out ./operator-report.pdf
+```
+
+Runner prints the output path and canonical `sha256:...` integrity digest. A
+successful verification prints `PASS`, `REPORT_DIGEST_VERIFIED`, or
+`REPORT_SIGNATURE_VERIFIED` when a public key is supplied.
+
+For `storage.shared_postgres.mode = "runtime_store"`, include `--config
+./synapsor.runner.json`; Runner reads through a bounded local bridge to the same
+shared ledger.
+
+Reports include scoped proposal, query-audit, approval/rejection, writeback,
+receipt, replay, compensation, and graduated-trust decision metadata when those
+records exist. Evidence rows are never exported. Kept-out values, credentials,
+keys, raw driver errors, and database URLs are excluded.
+
+JSON, Markdown, and PDF reports carry a canonical manifest digest. Optional
+operator signing binds the export to the existing key model:
+
+```bash
+synapsor-runner report --object invoice:INV-3001 --tenant tenant_acme \
+  --store ./.synapsor/local.db --format json --out ./invoice-report.json \
+  --signing-key ./operator-private.pem --key-id review-key-1
+
+synapsor-runner report verify ./invoice-report.json \
+  --public-key ./operator-public.pem
+```
+
+Verification detects content, ordering, digest, and signature tampering. A
+verified export is tamper-evident; it does not make local SQLite immutable,
+append-only compliance storage. Protect report files and signing keys with the
+same care as the ledger.

package/docs/conformance.md

@@ -28,9 +28,11 @@ Current fixture groups:
 - `manual-approval`
 - `auto-approval`
 - `aggregate-policy-limits`
+- `aggregate-read`
 - `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,
@@ -42,11 +44,21 @@ selection, count/value caps, frozen-version drift checks, atomic rollback,
 exact receipts, hard-delete side-effect refusal, and human approval. Adapter
 tests and `corepack pnpm test:bounded-set` complete the live PostgreSQL/MySQL
 matrix.
+The aggregate-read fixture proves a reviewer-fixed scalar operation, trusted
+tenant scope, fixed equality selection, minimum-group suppression, and an
+evidence/query-audit surface containing no member rows or identities. The live
+`corepack pnpm test:aggregate-read` gate runs COUNT/SUM/AVG, suppression,
+timeout, and dependency classification against disposable PostgreSQL and
+MySQL.
 The reversible-change-set fixture proves that undo is a new reviewed
 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
@@ -72,6 +84,9 @@ Run:
 
 ```bash
 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: