@synapsor/runner 1.4.122 → 1.5.0

package/docs/README.md

@@ -28,9 +28,10 @@ no-database demo, wire your database, then read deeper concepts.
   Guardrails](why-synapsor-vs-app-guardrails.md): where SQL authority lives,
   what a hand-built semantic tool already gets right, and when the shared
   contract, approval, receipt, and replay layer is worth adopting.
-- [MCP Audit](mcp-audit.md): static review for risky database MCP tools such as
-  `execute_sql`, broad query tools, model-controlled tenant filters, or
-  model-facing approval/commit tools.
+- [MCP Audit](mcp-audit.md): concise static review for risky database MCP tools
+  such as `execute_sql`, broad query tools, model-controlled tenant filters, or
+  model-facing approval/commit tools, plus explicit generation of disabled
+  canonical review candidates.
 
 ## 03 Run The Demo
 
@@ -49,6 +50,9 @@ no-database demo, wire your database, then read deeper concepts.
   links to the canonical own-database guide.
 - [Doctor](doctor.md): redacted setup checks, handler probes, direct SQL
   writeback probes, and receipt-table guidance.
+- [Database-Enforced Scope](database-enforced-scope.md): application-level
+  scope, hardened PostgreSQL RLS, tenant-bound credentials/deployments, and
+  honest MySQL alternatives.
 - [Guarded Single-Row CRUD Writeback](guarded-crud-writeback.md): native
   INSERT/UPDATE/DELETE, receipt modes, crash semantics, privileges, and
   reconciliation.
@@ -60,6 +64,10 @@ no-database demo, wire your database, then read deeper concepts.
 
 ## 05 Generate Capabilities
 
+- [Reviewed Prisma, Drizzle, And OpenAPI
+  Candidates](schema-api-candidates.md): turn structural developer artifacts
+  into deterministic, disabled canonical review candidates without executing
+  adopter code or inferring authority.
 - [Capability Authoring](capability-authoring.md): define read/proposal
   capabilities, model-facing descriptions, result envelopes, trusted context,
   and writeback guards.
@@ -74,11 +82,17 @@ no-database demo, wire your database, then read deeper concepts.
   and deterministic lint/SARIF output.
 - [Contract Testing](contract-testing.md): adopter-owned static and disposable
   PostgreSQL/MySQL allow/deny/redaction assertions.
+- [Agent Effect Regression](effect-regression.md): provider-neutral,
+  propose-only fixtures that catch changed capability calls, business diffs,
+  policy outcomes, tenant handling, and hidden-field behavior.
 - [Bounded Aggregate Reads](aggregate-reads.md): fixed scalar count/sum/avg,
   tenant scope, suppression, and no-row evidence.
 
 ## 06 Serve MCP
 
+- [Inline Proposal Review With MCP Apps](mcp-apps.md): display-only proposal
+  cards where supported, exact protocol versions, tested compatibility, and
+  secure standalone review fallback.
 - [MCP Client Setup](mcp-client-setup.md): connect Claude, Cursor, VS Code, or
   another stdio MCP client.
 - [MCP Client Configs](mcp-clients.md): complete Claude, Cursor, OpenAI Agents,
@@ -96,6 +110,8 @@ no-database demo, wire your database, then read deeper concepts.
 
 - [Local Mode](local-mode.md): local store, proposals, approval, replay, and
   writeback flow.
+- [Shadow Studies](shadow-studies.md): compare what an agent would propose
+  with explicit authorized outcomes before granting write authority.
 - [Writeback Executors](writeback-executors.md): app-owned writeback handlers
   for approved proposals.
 - [App-Owned Executors](app-owned-executors.md): short entry point for rich

package/docs/capability-authoring.md

@@ -121,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
@@ -134,7 +150,7 @@ reviewed runner JSON capabilities. Current parity:
 | arg `minimum` | `ARG amount NUMBER MIN 1` | 0.1.8 | NUMBER args only. |
 | arg `maximum` | `ARG amount NUMBER MAX 2500` | 0.1.8 | NUMBER args only. |
 | arg `max_length` | `ARG reason TEXT MAX LENGTH 500` | 0.1.8 | STRING/TEXT args only. Legacy `MAX 500` is still accepted for existing DSL files, but `MAX LENGTH` is the reviewed spelling. |
-| arg `enum` | Not expressible in DSL yet | 0.1 | Use embedded JSON or generated contract JSON when enum allowlists are required. |
+| arg `enum` | `ARG risk_level STRING ENUM('low', 'medium', 'high') REQUIRED` | 1.4.121 | Supports 1..64 same-type string, number, or boolean values; duplicates and mixed types fail compilation. |
 | proposal `numeric_bounds` | `BOUND column 1..2500`, `BOUND column ..2500`, or `BOUND column 1..` | 0.1.8 | Applies to patched numeric columns. Strict mode warns when a NUMBER arg is patched without arg min/max or a matching `BOUND`. |
 | proposal `transition_guards` | `TRANSITION status ALLOW pending -> approved\|rejected` or `TRANSITION status FROM current_status ALLOW open -> closed` | 0.1.8 | Values are state strings; use `|` for multiple target states. |
 | proposal `conflict_guard` | `CONFLICT GUARD updated_at` | 0.1 | If omitted, DSL emits an explicit weak-guard acknowledgement. Prefer a real row-version column. |

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/database-enforced-scope.md

@@ -0,0 +1,273 @@
+# Database-Enforced Tenant And Principal Scope
+
+Runner always binds tenant and principal from trusted server-side context, not
+from model arguments. Choose the database enforcement mode deliberately:
+
+| Diagnostic mode | What enforces scope | Protects against | Does not protect against |
+| --- | --- | --- | --- |
+| `application_scope` | Runner's fixed, parameterized predicates with one least-privilege credential | A model trying to widen tenant or principal arguments | A defect in Runner's predicate construction |
+| `postgres_rls` | Runner predicates plus PostgreSQL row-level security | Omitted/wrong Runner predicates and pooled-session context leakage | A fully compromised process that can choose trusted settings while holding a broad credential |
+| `tenant_bound` | Runner predicates plus a credential or process that cannot access other tenants | Query mistakes and a process that never receives organization-wide database authority | Incorrect grants or isolation in the credential/deployment itself |
+
+These modes are defense in depth, not substitutes for least-privilege roles,
+restricted views, application authorization, or staging-first validation.
+
+## Default: Application-Level Scope
+
+Existing source configs remain compatible. An omitted `database_scope`, or:
+
+```json
+{
+  "database_scope": { "mode": "application" },
+  "credential_scope": { "mode": "shared" }
+}
+```
+
+means Runner adds reviewed tenant and optional principal predicates to every
+supported read and write using one environment-bound credential. This stops
+the model from selecting another tenant, because scope is not a tool argument.
+It is still application-level isolation: a defect in Runner's SQL construction
+could cross that boundary. Keep database permissions, restricted views, and
+RLS where available.
+
+## Trusted-Context Provenance
+
+The tenant value is part of the security boundary. Runner accepts it through
+these reviewed paths:
+
+| Deployment | Trusted-context source | Diagnostic binding |
+| --- | --- | --- |
+| Local stdio or one explicitly single-tenant process | Operator-controlled environment or local development binding | `process_bound` |
+| Shared Streamable HTTP | Verified signed JWT claims configured with `http_claims` and `session_auth` | `verified_http_session` |
+| Cloud embedding | A verified per-session binding supplied by the embedding control plane | `verified_external_session` |
+
+Runner does not treat a tool argument, query parameter, arbitrary MCP `_meta`
+value, `X-Tenant-*` header, or unverified forwarded header as tenant or
+principal authority. A shared HTTP catalog cannot mix claims-bound capabilities
+with environment-bound capabilities.
+
+For shared production HTTP, prefer asymmetric JWT verification so Runner holds
+only public verification material. HS256 remains useful for local development
+and controlled deployments but gives Runner access to the signing secret.
+
+Run `doctor --json` or `tools preview --json` to inspect the effective
+per-source assurance mode and trusted-context binding. Server startup prints
+the same non-secret summary. An `application_scope` source used with verified
+HTTP sessions is deliberately reported with a warning: authentication makes
+the tenant value trustworthy, but it does not add an independent database
+boundary.
+
+## PostgreSQL RLS Mode
+
+Add fixed setting names to a PostgreSQL source:
+
+```json
+{
+  "sources": {
+    "billing_postgres": {
+      "engine": "postgres",
+      "read_url_env": "BILLING_POSTGRES_READ_URL",
+      "write_url_env": "BILLING_POSTGRES_WRITE_URL",
+      "database_scope": {
+        "mode": "postgres_rls",
+        "tenant_setting": "synapsor.tenant_id",
+        "principal_setting": "synapsor.principal"
+      },
+      "credential_scope": { "mode": "shared" }
+    }
+  }
+}
+```
+
+For each scoped transaction, Runner binds both values with parameterized
+transaction-local `set_config(..., true)`. Reads, evidence, aggregates,
+bounded-set selection, guarded writes, reconciliation, compensation, and
+verification therefore use the same trusted context. Transaction-local values
+are cleared on commit or rollback and are not reused on the next pooled
+checkout.
+
+Runner refuses hardened serving or writeback when the role or target cannot be
+attested. Required properties include:
+
+- RLS and `FORCE ROW LEVEL SECURITY` are enabled;
+- the effective role is not a superuser, table owner, or `BYPASSRLS` role;
+- applicable policies are permissive only where the reviewed access requires
+  them;
+- every applicable operation policy references both configured settings;
+- `SELECT`/`DELETE` have a suitable `USING` expression;
+- `INSERT` has a suitable `WITH CHECK` expression;
+- `UPDATE` has both `USING` and `WITH CHECK`.
+
+### Example PostgreSQL policy
+
+Use a non-owner read role and a separate non-owner write role. Adapt names and
+grants to your schema:
+
+Runner does not silently create or widen these policies. Review and apply the
+SQL as a database owner, then run doctor using the steady-state non-owner role.
+
+```sql
+ALTER TABLE public.invoices ENABLE ROW LEVEL SECURITY;
+ALTER TABLE public.invoices FORCE ROW LEVEL SECURITY;
+
+CREATE POLICY invoices_reader_scope
+ON public.invoices
+FOR SELECT
+TO runner_reader
+USING (
+  tenant_id = current_setting('synapsor.tenant_id', true)
+  AND assigned_to = current_setting('synapsor.principal', true)
+);
+
+CREATE POLICY invoices_writer_select_scope
+ON public.invoices
+FOR SELECT
+TO runner_writer
+USING (
+  tenant_id = current_setting('synapsor.tenant_id', true)
+  AND assigned_to = current_setting('synapsor.principal', true)
+);
+
+CREATE POLICY invoices_writer_insert_scope
+ON public.invoices
+FOR INSERT
+TO runner_writer
+WITH CHECK (
+  tenant_id = current_setting('synapsor.tenant_id', true)
+  AND assigned_to = current_setting('synapsor.principal', true)
+);
+
+CREATE POLICY invoices_writer_update_scope
+ON public.invoices
+FOR UPDATE
+TO runner_writer
+USING (
+  tenant_id = current_setting('synapsor.tenant_id', true)
+  AND assigned_to = current_setting('synapsor.principal', true)
+)
+WITH CHECK (
+  tenant_id = current_setting('synapsor.tenant_id', true)
+  AND assigned_to = current_setting('synapsor.principal', true)
+);
+
+CREATE POLICY invoices_writer_delete_scope
+ON public.invoices
+FOR DELETE
+TO runner_writer
+USING (
+  tenant_id = current_setting('synapsor.tenant_id', true)
+  AND assigned_to = current_setting('synapsor.principal', true)
+);
+```
+
+Grant only the operations and columns needed by the reviewed capabilities.
+Policy expressions are not a replacement for grants.
+
+Run the normal metadata checks before serving:
+
+```bash
+synapsor-runner doctor --config ./synapsor.runner.json
+```
+
+On a disposable or explicitly approved live target, also prove that a known
+row disappears under a different tenant and under a different principal:
+
+```bash
+synapsor-runner doctor --config ./synapsor.runner.json --check-rls
+```
+
+`--check-rls` reads only through the configured read role. It does not mutate
+the source. Startup and per-connection checks still fail closed when the
+required role or policy properties are absent.
+
+PostgreSQL RLS catches a missing application predicate. It does not make a
+fully compromised Runner process safe if that process can choose arbitrary
+trusted setting values while holding a credential that spans tenants. Use a
+tenant-bound credential or isolated deployment for that threat model.
+
+## Tenant-Bound Credentials
+
+Contracts contain a resolver identifier, never a connection string:
+
+```json
+{
+  "credential_scope": {
+    "mode": "tenant_resolver",
+    "resolver": "production_tenant_credentials"
+  }
+}
+```
+
+An embedding application supplies the matching resolver:
+
+```ts
+import {
+  startRunnerStreamableHttp,
+  type TenantCredentialResolver
+} from "@synapsor/runner/runtime";
+
+const credentialResolver: TenantCredentialResolver = {
+  id: "production_tenant_credentials",
+  async resolve({ source_name, access, tenant_id, principal }) {
+    const lease = await credentialBroker.issue({
+      source: source_name,
+      access,
+      tenant: tenant_id,
+      principal
+    });
+
+    return {
+      connection_url: lease.connectionUrl,
+      credential_id: lease.id,
+      expires_at: lease.expiresAt
+    };
+  }
+};
+
+await startRunnerStreamableHttp({
+  configPath: "./synapsor.runner.json",
+  credentialResolver
+});
+```
+
+The resolver receives only verified trusted context. Runner partitions pools
+by source, access type, tenant, principal, and credential identity; an expired
+or rotated lease is closed before reuse. Resolution failures are fail-closed,
+and connection URLs are not logged or stored in contracts.
+
+The stock CLI does not load arbitrary executable resolver modules. For direct
+CLI operation, run one Runner process per tenant with a tenant-bound credential
+in the normal `read_url_env`/`write_url_env` variables and keep
+`credential_scope.mode` as `shared`. This gives the process no cross-tenant
+credential to misuse.
+
+## MySQL
+
+MySQL does not provide a native equivalent to PostgreSQL RLS. Runner therefore
+does not label session variables or application predicates as independent
+database enforcement.
+
+Use one or more of:
+
+- tenant-bound read/write credentials;
+- restricted tenant-aware views or stored procedures owned and reviewed by
+  your application;
+- separate schemas or databases;
+- one isolated Runner deployment per tenant.
+
+Runner's trusted-context predicates still narrow model behavior, but a shared
+MySQL credential remains application-level scope unless the database grants,
+views, or deployment physically prevent cross-tenant access.
+
+## Verification
+
+The repository's disposable PostgreSQL proof covers:
+
+```bash
+corepack pnpm test:database-scope
+```
+
+It verifies an intentionally unscoped query is still denied by RLS, correct
+tenant/principal access succeeds, cross-scope access fails, `WITH CHECK`
+prevents row moves, pooled scope does not leak, guarded writeback and
+compensation remain scoped, and unsafe roles/policies fail doctor.

package/docs/dependency-license-inventory.md

@@ -10,11 +10,15 @@ Summary from the current dependency set:
 
 | License | Package entries |
 | --- | ---: |
-| MIT | 149 |
+| MIT | 200 |
 | Apache-2.0 | 4 |
 | BSD-3-Clause | 3 |
 | BSD-2-Clause | 1 |
-| ISC | 11 |
+| ISC | 15 |
+| `(BSD-3-Clause OR GPL-2.0)` | 1 |
+| `(MIT AND Zlib)` | 1 |
+| `0BSD` | 1 |
+| `(MIT OR CC0-1.0)` | 1 |
 
 Apache-2.0 dependency entries reported by pnpm:
 

package/docs/doctor.md

@@ -20,6 +20,23 @@ The default check validates:
 - MCP tool boundary, including absence of raw SQL and commit tools;
 - local store stats.
 
+For a source configured with `database_scope.mode = "postgres_rls"`, doctor
+also verifies RLS/FORCE status, effective-role bypass risk, applicable
+operation policies, `USING`/`WITH CHECK`, and both configured trusted-setting
+names. Hardened mode fails rather than silently falling back to
+application-only predicates.
+
+On a disposable or explicitly approved live target, add:
+
+```bash
+synapsor-runner doctor --config synapsor.runner.json --check-rls
+```
+
+This performs a read-only cross-tenant and cross-principal canary and checks
+that transaction-local values do not survive the pooled transaction. See
+[Database-Enforced Tenant And Principal
+Scope](database-enforced-scope.md).
+
 ## App-Owned Handler Checks
 
 For `http_handler` executors, add `--check-handlers`:

package/docs/effect-regression.md

@@ -0,0 +1,142 @@
+# Agent Effect Regression
+
+Contract tests answer whether a reviewed capability boundary is still valid.
+Effect regression answers a different question:
+
+> Did a model, prompt, policy, capability, or application change alter the
+> business effect the agent proposes?
+
+Runner effect evaluation is provider-neutral and offline. Runner snapshots
+existing replay evidence into a versioned fixture, then compares a result
+exported by your agent harness. It does not invoke a model, query a source
+database, approve a proposal, or apply a write.
+
+## Create A Baseline
+
+Start from an existing replay, proposal, or shadow-study case:
+
+```bash
+synapsor-runner effect fixture create \
+  --from-replay replay_wrp_... \
+  --request "Waive the late fee on invoice INV-3001" \
+  --contract ./synapsor.contract.json \
+  --capability-call billing.inspect_invoice \
+  --capability-call billing.propose_late_fee_waiver \
+  --store ./.synapsor/local.db \
+  --out ./effects/late-fee.json
+```
+
+Use `--from-proposal wrp_...` or `--from-shadow-case shc_...` for the other
+sources. The contract is required so Runner records its version and the
+reviewed kept-out fields. Every `--capability-call` must exist in that
+contract.
+
+The fixture contains:
+
+- the business request;
+- trusted tenant and principal context from the stored proposal;
+- bounded evidence and query-fingerprint snapshots already in the ledger;
+- the permitted capability calls;
+- expected target, business diff, policy result, conflict code, and outcome;
+- the contract version and fields that must remain hidden;
+- a digest that catches unreviewed fixture edits.
+
+It contains no database URL, provider credential, or live source connection.
+The secret and hidden-field checks fail closed while creating or loading it.
+
+## Import A Provider-Neutral Result
+
+Create a template:
+
+```bash
+synapsor-runner effect result init \
+  --fixture ./effects/late-fee.json \
+  --out ./effects/late-fee.result.json
+```
+
+Have your agent test harness populate this JSON after a propose-only run. The
+format records:
+
+- capability names and model-controlled arguments;
+- trusted context supplied by the application outside those arguments;
+- target, proposed diff, policy, conflict, and outcome category;
+- fields observed by the harness;
+- whether the harness made any new source read;
+- whether the source database changed.
+
+The adapter may use any model provider or application framework. Runner imports
+the result; it does not require a proprietary LLM API.
+
+The evaluation harness must disable apply/writeback. A result reporting a
+source mutation always fails. A new source read also fails by default. Pass
+`--allow-live-read` only when the test environment is explicitly disposable;
+that flag never permits a write.
+
+## Compare In CI
+
+```bash
+synapsor-runner effect run \
+  --fixture ./effects/late-fee.json \
+  --result ./effects/late-fee.result.json
+```
+
+`effect compare` is an alias. Both return a nonzero status when any reviewed
+effect changes. Reports cover:
+
+- capability calls and capability-surface expansion;
+- trusted-context drift or model arguments selecting tenant/principal;
+- target-object and business-diff changes;
+- policy, conflict, outcome-category, and contract-version changes;
+- kept-out field exposure;
+- source mutation or an unapproved new read.
+
+Use `--format json` or `--format junit` for CI:
+
+```bash
+synapsor-runner effect run \
+  --dataset ./effects/dataset.json \
+  --results-dir ./effects/results \
+  --format junit \
+  --out ./artifacts/effect-results.xml
+```
+
+Dataset fixture paths are relative and cannot escape the dataset directory.
+Each result is named `<fixture_id>.result.json`.
+
+## Accept An Intentional Change
+
+Runner never updates a baseline during `run` or `compare`. After reviewing an
+intentional business change, accept it explicitly:
+
+```bash
+synapsor-runner effect accept \
+  --fixture ./effects/late-fee.json \
+  --result ./effects/late-fee.result.json \
+  --actor release-engineer@example.com \
+  --reason "Reviewed billing policy v2" \
+  --in-place \
+  --yes
+```
+
+Use `--out ./effects/late-fee.v2.json` instead of `--in-place` to preserve the
+old fixture. Acceptance appends actor, reason, timestamp, and before/after
+baseline digests. It cannot waive:
+
+- a mismatched fixture identity;
+- source mutation;
+- a new source read;
+- trusted-context drift or model-controlled tenant/principal;
+- hidden-field exposure.
+
+Commit the accepted fixture and review it like application code.
+
+## Boundaries
+
+- This is not a general agent workflow engine.
+- This does not execute a provider command or application code.
+- This does not prove model quality outside the imported observations.
+- This complements [`contract test`](contract-testing.md); a contract can
+  conform while an agent's proposed business effect still regresses.
+- Replay remains read-only. Creating an effect fixture does not replay or
+  reapply the original write.
+

package/docs/getting-started-own-database.md

@@ -66,6 +66,13 @@ export DATABASE_URL="<postgres-or-mysql-read-url>"
 
 Use a read-only credential for inspection and model-facing read/proposal tools.
 
+The generated compatibility setup uses application-level trusted-scope
+predicates. Before production-like multi-tenant use, choose and document one of
+the modes in [Database-Enforced Tenant And Principal
+Scope](database-enforced-scope.md): shared application scope, PostgreSQL RLS
+plus Runner checks, or tenant-bound credentials/deployments. MySQL has no
+native RLS equivalent.
+
 ### TLS notes for AWS RDS and other managed databases
 
 If you see an error like:

package/docs/local-mode.md

@@ -30,9 +30,9 @@ Current local-mode foundation:
 - local approved proposal to `synapsor.writeback-job.v1` job generation;
 - guarded Postgres/MySQL writeback adapters for approved structured jobs.
 
-Still pending:
+Runtime requirement:
 
-The alpha package requires Node >= 22.5.0 because the local evidence/replay
+The stable package requires Node >= 22.5.0 because the local evidence/replay
 ledger uses Node's `node:sqlite` runtime. The published package declares that
 engine requirement and the CLI exits early with a clear message on older Node
 versions. The Docker-backed demo remains the recommended path when you do not
@@ -184,7 +184,11 @@ npx -y -p @synapsor/runner synapsor-runner proposals reject wrp_123 \
 
 Approval records the approver against the exact proposal hash/version. The proposal patch is immutable after creation.
 
-Shadow-mode proposals are inspectable through `proposals show` and `replay show`, but `proposals approve` and `proposals writeback-job` reject them. Shadow mode never mutates Postgres/MySQL.
+Shadow-mode proposals are inspectable through `proposals show` and `replay
+show`, but `proposals approve` and `proposals writeback-job` reject them.
+Shadow mode never mutates Postgres/MySQL or invokes an app-owned handler. To
+compare agent behavior with explicit application/operator outcomes across a
+pilot, use [Shadow Studies](shadow-studies.md).
 
 ## Browser review UI