@synapsor/runner 1.4.123 → 1.5.3

package/docs/release-policy.md

@@ -11,8 +11,12 @@ npx -y -p @synapsor/runner synapsor-runner demo --quick
 npm install -g @synapsor/runner
 ```
 
-Use `@alpha` or an exact prerelease only when intentionally testing the moving
-preview channel.
+Use an exact prerelease or a named preview tag only when intentionally testing
+preview behavior. Check the tags that currently exist before documenting one:
+
+```bash
+npm dist-tag ls @synapsor/runner
+```
 
 ## Alpha Expectations
 
@@ -128,9 +132,9 @@ internals. Local store migrations may happen inside `1.x` and later minor
 versions, but documented CLI inspection commands should remain the supported way
 to read the store.
 
-Alpha users should pin an exact alpha version in package.json, CI, and MCP
-client snippets. Use `@alpha` only when intentionally testing the moving
-preview channel.
+Prerelease users should pin an exact version in package.json, CI, and MCP
+client snippets. Do not assume an `alpha`, `beta`, or `next` tag exists; inspect
+the registry tags first.
 
 ## Result Envelope Migration
 

package/docs/runner-config-reference.md

@@ -114,6 +114,14 @@ not print database URLs or create the schema.
       "write_url_env": "BILLING_POSTGRES_WRITE_URL",
       "read_only": false,
       "statement_timeout_ms": 3000,
+      "database_scope": {
+        "mode": "postgres_rls",
+        "tenant_setting": "synapsor.tenant_id",
+        "principal_setting": "synapsor.principal"
+      },
+      "credential_scope": {
+        "mode": "shared"
+      },
       "receipts": {
         "authority": "source_db",
         "provisioning": "precreated",
@@ -138,6 +146,23 @@ adapter-specific reviewed SSL options when used.
 
 A contract's `SOURCE billing_postgres` must exactly match a `sources` key.
 
+`database_scope.mode` defaults to `application`: Runner enforces trusted
+tenant/principal predicates with the configured database credential.
+`postgres_rls` is PostgreSQL-only and requires fixed, distinct
+`tenant_setting` and `principal_setting` names. Runner binds them
+transaction-locally and refuses serving/writeback when RLS, FORCE, role, or
+operation-policy prerequisites cannot be attested.
+
+`credential_scope.mode` defaults to `shared`. `tenant_resolver` names a
+programmatic `TenantCredentialResolver`; credentials remain outside the
+contract/config and pools are partitioned by trusted scope and credential
+identity. The stock CLI does not load executable resolver modules, so CLI-only
+deployments should run one tenant-bound process/credential per tenant.
+
+See [Database-Enforced Tenant And Principal
+Scope](database-enforced-scope.md) for the guarantee matrix, PostgreSQL policy
+example, resolver interface, doctor canary, and MySQL alternatives.
+
 Long-running servers reuse native driver pools. Optional `pool` keys are
 `max_connections` (default 10), `connection_timeout_ms` (3000),
 `idle_timeout_ms` (30000), `queue_timeout_ms` (5000), and `queue_limit`

package/docs/schema-api-candidates.md

@@ -0,0 +1,68 @@
+# Reviewed Candidates From Prisma, Drizzle, And OpenAPI
+
+Use these generators after schema or API inspection when you want a review
+starting point without granting authority:
+
+```bash
+synapsor-runner init from-prisma ./prisma/schema.prisma \
+  --output ./synapsor-prisma-candidates
+
+synapsor-runner init from-drizzle ./src/schema.ts \
+  --output ./synapsor-drizzle-candidates
+
+synapsor-runner init from-openapi ./openapi.yaml \
+  --output ./synapsor-openapi-candidates
+```
+
+Each command writes a separate deterministic directory containing:
+
+- `synapsor.candidate.contract.json`: canonical `@synapsor/spec` candidates;
+- `synapsor.candidate.runner.json`: source-less strict Shadow configuration;
+- `synapsor.candidate.contract-tests.json`: deny, redaction, and operator
+  boundary test candidates;
+- `generation-review.json`: stable machine-readable review findings;
+- `REVIEW.md`: the human review checklist;
+- `.synapsor-schema-candidates.json`: Runner's ownership marker.
+
+No candidate is active. Proposal writeback is `none`, no database source is
+configured, and tenant/principal authority remains a visible placeholder.
+Generation never edits the input or an active Runner configuration.
+
+## What Is And Is Not Inferred
+
+The generators can suggest structural facts and likely review targets:
+
+- objects, fields, table mappings, primary keys, and version-like fields;
+- potential tenant/principal fields based on names;
+- potentially sensitive and kept-out fields;
+- possible read and proposal capability names;
+- operations that need business logic or an app-owned handler.
+
+They do not decide which tenant or principal is authoritative, which fields are
+safe to expose, which writes are valid, business bounds, approval policy, or
+auto-approval. A field-name heuristic is not data classification.
+
+Review `generation-review.json` and `REVIEW.md`, replace every
+`review_required_*` placeholder, run the generated tests and a
+[Shadow study](shadow-studies.md), then deliberately copy reviewed definitions
+into an active contract through code review.
+
+## Input Safety
+
+Input is bounded to 2 MiB, 50 objects, 128 fields per object, and 200 generated
+capabilities. Deep or oversized structures fail closed.
+
+- Prisma uses Runner's bounded lexer/parser. Datasource URLs, defaults, enum
+  values, generators, and plugins are not copied or run.
+- Drizzle is untrusted executable TypeScript. Runner parses a documented static
+  `pgTable`/`mysqlTable` object-literal subset with the TypeScript AST. It never
+  imports, transpiles, type-checks, executes, or resolves the application.
+  Dynamic table names fail; unsupported dynamic columns are called out for
+  review.
+- OpenAPI 3 JSON/YAML is parsed locally. Network/external references are
+  rejected. Server URLs, examples, defaults, enum values, callbacks, webhooks,
+  and credentials are not copied.
+
+Existing output is never replaced unless `--force` points to a directory with
+Runner's matching ownership marker. Hand-edited directories are refused even
+with `--force`.

package/docs/security-boundary.md

@@ -36,6 +36,7 @@ The model does not receive:
 - a generic `execute_sql` tool;
 - arbitrary table, schema, or column names;
 - database URLs or credentials;
+- contract activation tools;
 - approval tools;
 - commit/writeback tools;
 - trusted tenant or principal authority as ordinary model arguments.
@@ -50,6 +51,16 @@ 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.
 
+With a shared credential, these checks are application-level enforcement and
+depend on Runner's fixed predicate implementation. Optional PostgreSQL RLS mode
+adds an independent database check for omitted predicates and pooled-context
+leakage. Tenant-bound credentials or isolated deployments provide the stronger
+boundary when a Runner process must not hold organization-wide authority.
+PostgreSQL RLS does not protect against a fully compromised process that can
+choose arbitrary trusted settings, and MySQL has no native RLS equivalent. See
+[Database-Enforced Tenant And Principal
+Scope](database-enforced-scope.md).
+
 A capability may declare `principal_scope_key` (DSL: `PRINCIPAL SCOPE KEY`) to
 narrow rows inside a tenant. Runner then adds both fixed, parameterized guards:
 
@@ -74,6 +85,18 @@ explicit host-level administrative boundary.
 Proposal tools read the current row through the read credential, store evidence
 and an exact before/after diff, and leave the source database unchanged.
 
+Code-first Safe Actions do not create authority when a file is edited. Runner
+parses the restricted TypeScript object without importing or executing it,
+compiles it into a digest-addressed disabled canonical draft, and keeps the
+active contract pointer unchanged. Activation is available only in the
+session-token/CSRF-protected localhost Workbench after a matching real staging
+proposal proves `source_database_changed:false`; the operator must confirm the
+complete digest. A proposal remains pinned to the active contract digest it was
+created under, so later activation cannot reinterpret an old approval. Cloud-
+linked projects route activation through Cloud governance instead of the local
+control. No model-facing MCP tool can validate-and-activate, approve, apply, or
+revert.
+
 The local proposal store rejects obvious credential material before persistence:
 database URLs, bearer tokens, Synapsor runner tokens, private-key blocks, and
 secret-like fields such as password, token, API key, private key, cookie,
@@ -135,11 +158,13 @@ database identifiers such as `../private`, `id/../../tenant_id`, or
 `status; DROP TABLE tickets` before adapter execution. Local CLI file paths
 remain explicit user-provided paths; they are not model-facing authority.
 
-Local review can happen through the CLI or `synapsor-runner ui`. The UI is a localhost
-review surface with a per-run session token and CSRF protection for
-approve/reject actions. It does not expose raw SQL, database URLs, write
-credentials, approval tools, commit tools, or controls that widen reviewed
-tables/columns.
+Local review can happen through the CLI or `synapsor-runner ui`. The UI is a
+localhost review surface with a per-run session token and CSRF protection for
+approve/reject and Safe Action draft controls. Activation additionally requires
+a matching source-unchanged preview plus the complete digest. These operator
+controls are not MCP tools. The UI does not expose raw SQL, database URLs, or
+write credentials, and it does not let a model widen reviewed tables, columns,
+scope, policy, or executor authority.
 
 Contract lint and tests are review aids rather than a proof of complete
 security. Capability breadth can still drift as narrow tools accumulate;

package/docs/shadow-studies.md

@@ -0,0 +1,241 @@
+# Shadow Studies
+
+Use a shadow study before granting an agent write authority. Runner serves the
+reviewed proposal capability and records what the agent would have proposed,
+but the proposal cannot be approved, queued, or applied.
+
+A study compares two explicit records:
+
+```text
+agent result or proposed effect
+versus
+authoritative outcome recorded by your application or operator
+```
+
+Runner does not infer a human rejection from an unchanged database row. A case
+without an authoritative outcome remains visibly unmatched.
+
+## Safety Boundary
+
+Set the Runner configuration to:
+
+```json
+{
+  "version": 1,
+  "mode": "shadow"
+}
+```
+
+The proposal store enforces the shadow boundary below the CLI and local UI:
+
+- a shadow proposal cannot be approved;
+- it cannot become a writeback job or worker item;
+- it cannot invoke direct database writeback or an app-owned handler;
+- no flag bypasses these checks;
+- a report suggestion is inactive and never edits or activates a contract.
+
+Shadow data remains in the configured local Runner store. Case and outcome
+imports reject obvious credentials, bearer tokens, database URLs, and
+secret-like fields.
+
+## Start A Study
+
+Create a study before serving the shadow capability. An empty capability list
+means all shadow capabilities; repeat `--capability` or use comma-separated
+names to narrow it.
+
+```bash
+synapsor-runner shadow study create \
+  --id sst_support_pilot \
+  --name "Support waiver pilot" \
+  --capability billing.propose_late_fee_waiver \
+  --store ./.synapsor/local.db
+
+synapsor-runner mcp serve \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+```
+
+New matching shadow proposals are attached automatically. To attach proposals
+that already exist, or to repair correlation after an interrupted process:
+
+```bash
+synapsor-runner shadow study sync sst_support_pilot \
+  --store ./.synapsor/local.db
+```
+
+## Record Non-Proposal Results
+
+A study also needs tasks where the agent was unable or not allowed to propose.
+Import one JSON object with `case record`, or a JSON array/JSONL file with
+`case import`.
+
+```json
+{
+  "request_id": "req-policy-42",
+  "tenant_id": "acme",
+  "principal": "support-agent-shadow",
+  "capability": "billing.propose_late_fee_waiver",
+  "business_object": "invoice",
+  "object_id": "INV-3042",
+  "agent_result": "policy_denied",
+  "decision_reason": "amount above reviewed bound",
+  "risk_score": 35
+}
+```
+
+Allowed `agent_result` values are:
+
+- `proposed`
+- `policy_denied`
+- `unable_to_propose`
+- `stale_conflict`
+- `invalid_unsafe_scope_attempt`
+
+For `proposed`, include normalized `before`, `after`, and `patch` objects under
+`proposed_effect`.
+
+```bash
+synapsor-runner shadow case import \
+  --study sst_support_pilot \
+  --input ./cases.jsonl \
+  --store ./.synapsor/local.db
+```
+
+Imports are limited to 2 MiB and 10,000 records per command.
+
+## Record Authoritative Outcomes
+
+Export actual outcomes from your application audit log or have a trusted
+operator create them. Each outcome must match an existing case by study,
+request, trusted tenant, business object, and object ID. A supplied proposal ID
+must match too.
+
+```json
+{
+  "request_id": "request_123",
+  "proposal_id": "wrp_123",
+  "tenant_id": "acme",
+  "business_object": "invoice",
+  "object_id": "INV-3001",
+  "actor": "support_lead_1",
+  "disposition": "applied",
+  "actual_effect": {
+    "before": { "late_fee_cents": 5500 },
+    "after": { "late_fee_cents": 0 },
+    "patch": { "late_fee_cents": 0 }
+  },
+  "occurred_at": "2026-07-19T12:00:00.000Z",
+  "source": "support-system-audit",
+  "reference": "ticket:SUP-184",
+  "reason": "customer qualified"
+}
+```
+
+Allowed dispositions are `applied`, `rejected_no_action`, and
+`stale_conflict`. An applied outcome requires an exact normalized effect.
+
+```bash
+synapsor-runner shadow outcome import \
+  --study sst_support_pilot \
+  --input ./outcomes.jsonl \
+  --store ./.synapsor/local.db
+```
+
+For the normal application path, record the trusted outcome directly instead
+of assembling JSONL. `@synapsor/runner/shadow` writes through the same scope,
+effect-shape, and secret checks as the import command:
+
+```js
+import { createShadowOutcomeRecorder } from "@synapsor/runner/shadow";
+
+const recorder = createShadowOutcomeRecorder({
+  storePath: "./.synapsor/local.db",
+  studyId: "sst_support_pilot",
+  actor: "support_application",
+  source: "support-audit-log",
+});
+
+try {
+  recorder.record({
+    requestId: "request_123",
+    tenantId: "acme",
+    businessObject: "invoice",
+    objectId: "INV-3001",
+    disposition: "applied",
+    actualEffect: {
+      before: { late_fee_cents: 5500 },
+      after: { late_fee_cents: 0 },
+      patch: { late_fee_cents: 0 },
+    },
+  });
+} finally {
+  recorder.close();
+}
+```
+
+The application owns the truth of this outcome. The helper does not read or
+mutate the source database and cannot approve a shadow proposal.
+
+## Review The Report
+
+```bash
+synapsor-runner shadow report \
+  --study sst_support_pilot \
+  --output ./shadow-report.json \
+  --store ./.synapsor/local.db
+
+synapsor-runner ui \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+```
+
+The stable JSON report preserves total and comparable denominators and
+classifies exact, partial, disagreement, human rejection/no action, policy
+denial, unable-to-propose, stale/conflict, unmatched, and unsafe-scope cases.
+It also includes amount distributions, capability/reason breakdowns, and
+risk-ranked disagreements.
+
+The report also shows the explicit trust progression:
+
+```text
+Observe -> Compare -> Manual review -> Suggested bounded policy
+```
+
+It reports an insufficient sample size until the minimum comparable evidence
+exists. A suggested policy remains an inactive review artifact; the report
+never widens or activates the contract.
+
+Close a completed study:
+
+```bash
+synapsor-runner shadow study close sst_support_pilot \
+  --store ./.synapsor/local.db
+```
+
+## Deterministic Reference Data
+
+The packaged `examples/support-billing-agent/shadow-study/` directory contains
+six synthetic cases and two authoritative outcomes. It covers an exact $55
+waiver, human rejection, policy denial, stale state, tenant forgery, and an
+unmatched task.
+
+```bash
+synapsor-runner shadow study create \
+  --id sst_support_reference \
+  --name "Support reference study" \
+  --capability billing.propose_late_fee_waiver \
+  --store ./.synapsor/shadow-reference.db
+
+synapsor-runner shadow case import \
+  --study sst_support_reference \
+  --input ./examples/support-billing-agent/shadow-study/cases.jsonl \
+  --store ./.synapsor/shadow-reference.db
+
+node ./examples/support-billing-agent/app/record-shadow-outcomes.mjs \
+  ./.synapsor/shadow-reference.db sst_support_reference
+
+synapsor-runner shadow report \
+  --study sst_support_reference \
+  --store ./.synapsor/shadow-reference.db
+```

package/docs/troubleshooting-first-run.md

@@ -12,6 +12,52 @@ Use JSON for automation:
 npx -y -p @synapsor/runner synapsor-runner doctor --first-run --json
 ```
 
+## Safe Action Draft Does Not Appear As A Tool
+
+This is expected before activation. `start --action`, agent edits, `action
+validate`, and `action watch` can create or refresh only a disabled draft. They
+must not alter the active model-facing tools.
+
+Check status without exposing credentials:
+
+```bash
+synapsor-runner action status --json
+synapsor-runner tools preview \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+```
+
+Open the secured Workbench, run the real source-unchanged staging Data PR
+preview, review the complete digest, and activate it there. There is
+intentionally no activation CLI command to hand to a coding agent.
+
+## Activated Tool Does Not Appear In Cursor
+
+Some MCP hosts do not refresh `tools/list` for a running stdio session. First
+confirm that Runner's active tool surface changed:
+
+```bash
+synapsor-runner action status --json
+synapsor-runner mcp status cursor --project --check-launch
+```
+
+Then reconnect or restart the project MCP server as directed by the Workbench.
+Do not work around a stale host session by adding approval, apply, activation,
+credentials, tenant values, or raw SQL to the Cursor configuration.
+
+## Safe Action Validation Reports Review Placeholders
+
+The composer fails closed while any `__REVIEW_*__` authority placeholder or
+dynamic TypeScript expression remains. Review the reported field and source,
+then make the authority explicit in the restricted `defineCapability({...})`
+object. Runner will not infer trusted tenant/principal bindings, hidden fields,
+write columns, bounds, conflict guards, approval, or executor authority from
+application code.
+
+Use the generated explanation and test manifest after validation. Do not edit
+digest-addressed files under `.synapsor/drafts/` or `.synapsor/active/`; edit
+the TypeScript source and validate again.
+
 ## Smoke Proposal Missing From Another Runner
 
 What happened:

package/examples/mcp-postgres-billing-app-handler/app-handler.mjs

@@ -119,5 +119,13 @@ function writeJson(response, statusCode, body) {
 }
 
 async function loadHandlerHelper() {
-  return await import(new URL("./synapsor-handler.mjs", import.meta.url));
+  const bundledHelper = new URL("./synapsor-handler.mjs", import.meta.url);
+  try {
+    return await import(bundledHelper);
+  } catch (error) {
+    if (error?.code !== "ERR_MODULE_NOT_FOUND" || error?.url !== bundledHelper.href) {
+      throw error;
+    }
+    return await import(new URL("../../packages/handler/dist/index.js", import.meta.url));
+  }
 }

package/examples/mcp-postgres-billing-app-handler/schema.sql

@@ -50,6 +50,16 @@ CREATE TABLE IF NOT EXISTS public.synapsor_writeback_receipts (
   completed_at timestamptz
 );
 
+CREATE TABLE IF NOT EXISTS public.synapsor_handler_receipts (
+  idempotency_key text PRIMARY KEY,
+  proposal_id text NOT NULL,
+  action text NOT NULL,
+  status text NOT NULL,
+  receipt_json jsonb NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  completed_at timestamptz
+);
+
 DO $$
 BEGIN
   IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'synapsor_reader') THEN
@@ -65,5 +75,6 @@ GRANT CONNECT ON DATABASE synapsor_billing_app_handler TO synapsor_reader, synap
 GRANT USAGE ON SCHEMA public TO synapsor_reader, synapsor_writer;
 GRANT SELECT ON public.tenants, public.customers, public.invoices, public.account_credits TO synapsor_reader, synapsor_writer;
 GRANT SELECT, INSERT, UPDATE ON public.synapsor_writeback_receipts TO synapsor_writer;
+GRANT SELECT, INSERT, UPDATE ON public.synapsor_handler_receipts TO synapsor_writer;
 GRANT UPDATE (late_fee_cents, waiver_reason, credit_requested_cents, credit_reason, credited_cents, updated_at) ON public.invoices TO synapsor_writer;
 GRANT INSERT ON public.account_credits TO synapsor_writer;

package/examples/mcp-postgres-billing-app-handler/synapsor-handler.mjs

@@ -168,6 +168,9 @@ class PostgresWritebackHandlerTransaction {
         this.receiptTable = receiptTable;
     }
     async ensureReceiptTable() {
+        const existing = await this.client.query("SELECT to_regclass($1) AS receipt_table", [this.receiptTableName()]);
+        if (existing.rows[0]?.receipt_table)
+            return;
         await this.client.query(`
       CREATE TABLE IF NOT EXISTS ${this.receiptTableName()} (
         idempotency_key text PRIMARY KEY,

package/examples/raw-sql-vs-synapsor/Makefile

@@ -4,8 +4,8 @@ demo:
 	@printf '%s\n' "Unsafe shortcut:"
 	@printf '%s\n' '  agent -> execute_sql("UPDATE invoices SET late_fee_cents = 0 ...")'
 	@printf '%s\n' ""
-	@printf '%s\n' "Synapsor quick proof:"
-	npx -y @synapsor/runner demo --quick --no-interactive
+	@printf '%s\n' "Synapsor guarded-action proof:"
+	npx -y @synapsor/runner try --prove --yes --no-open
 	@printf '%s\n' ""
 	@printf '%s\n' "Risk audit example:"
 	npx -y @synapsor/runner audit --example dangerous-db-mcp --format markdown

package/examples/raw-sql-vs-synapsor/README.md

@@ -13,10 +13,12 @@ Expected output includes:
 
 ```text
 execute_sql
-Synapsor quick demo complete.
-proposal created
-source DB changed: no
-approval required outside MCP
+late_fee_cents: 5500 -> 0
+Source changed:
+  No
+Guarded commit complete.
+restart-safe retry: yes
+stale apply refused: yes
 ```
 
 The raw-SQL shortcut is:

package/examples/support-billing-agent/Makefile

@@ -1,7 +1,11 @@
-.PHONY: demo unsafe clean
+.PHONY: demo unsafe evaluate clean
 
 demo:
 	cd ../.. && examples/support-billing-agent/scripts/run-demo.sh
+	cd ../.. && examples/support-billing-agent/scripts/run-evaluation.sh
+
+evaluate:
+	cd ../.. && examples/support-billing-agent/scripts/run-evaluation.sh
 
 unsafe:
 	@printf '%s\n' "Unsafe raw-SQL shortcut this demo avoids:"