@synapsor/runner 1.4.123 → 1.5.3

package/examples/support-billing-agent/README.md

@@ -1,16 +1,20 @@
 # Support/Billing Agent Demo
 
-This is the flagship Synapsor Runner demo.
+This is the flagship Synapsor Runner demo. It uses a disposable PostgreSQL
+database with row-level security (RLS) so the database independently checks the
+same trusted tenant and principal scope as Runner.
 
 It uses a disposable Postgres support/billing app and shows the full loop:
 
 ```text
-agent inspects scoped evidence
+agent inspects ticket SUP-184 and invoice INV-3001
 -> agent creates a proposal
+-> reviewer sees the exact $55 late-fee waiver
 -> source database is unchanged
 -> human approves outside MCP
 -> guarded writeback applies exactly one row
 -> replay shows evidence, diff, approval, receipt, and conflict behavior
+-> strict shadow and effect checks compare behavior without enabling writes
 ```
 
 ## Run It
@@ -25,6 +29,8 @@ Expected end state:
 
 ```text
 Reference support/billing app smoke passed.
+Shadow comparison passed: 6 cases, 2 human outcomes, 1 exact agreement, 1 human rejection.
+Effect regression passed: the reviewed $55 waiver effect is unchanged.
 ```
 
 The model-facing tools are exactly:
@@ -41,10 +47,42 @@ The demo proves:
 - the model does not receive `execute_sql`, approval tools, commit/apply tools,
   database URLs, write credentials, arbitrary table names, arbitrary column
   names, or tenant authority;
+- the contract-visible result excludes `card_token`, `internal_risk_note`, and
+  their seeded secret-looking values;
+- trusted tenant and principal values are bound outside model arguments, and
+  PostgreSQL RLS denies both cross-tenant and same-tenant cross-principal rows;
+- `doctor --check-rls` verifies the live database policies before the demo;
 - proposals do not mutate the source database;
 - approved writeback uses tenant, primary-key, allowed-column,
   idempotency, and `updated_at` conflict guards;
-- replay contains the evidence and writeback receipt.
+- an identical retry returns the prior receipt without another mutation;
+- stale data fails closed with `VERSION_CONFLICT`;
+- replay contains the evidence, query audit, approval, writeback event, and
+  receipt;
+- strict Shadow Mode records a proposal but cannot approve or mutate it; and
+- the shadow report compares cases with authoritative human outcomes before the
+  effect fixture checks the expected business change.
+
+The app-owned integration files make those two evaluation paths reusable:
+
+- `app/contract.ts` is the code-first TypeScript form of the reviewed late-fee
+  action and compiles to the same canonical spec as JSON/DSL;
+- `app/record-shadow-outcomes.mjs` records authoritative app outcomes through
+  `@synapsor/runner/shadow` without approval or source mutation;
+- `app/effect-adapter.mjs` emits one deterministic, propose-only result through
+  the provider-neutral command adapter;
+- `.github/workflows/effect-regression.yml` runs the effect check and uploads
+  JUnit output for relevant pull requests.
+
+This repository result is deterministic application evidence, not an external
+model benchmark. Use `--result-origin external-model` only when your adapter
+actually invokes a model.
+
+RLS is defense in depth, not a claim that a fully compromised Runner process is
+contained. A process that can choose arbitrary trusted context or replace the
+database credential remains outside this guarantee. Production deployments
+must authenticate context upstream, keep the database roles least-privileged,
+and protect Runner's environment.
 
 ## Compare The Unsafe Shortcut
 
@@ -61,8 +99,13 @@ fixture; it shows the path an MCP client should not expose to the model:
 execute_sql("UPDATE invoices SET late_fee_cents = 0 ...")
 ```
 
-Use `make demo` for the real proposal, approval, writeback, idempotent retry,
-stale-row conflict, and replay proof.
+Use `make demo` for the live RLS, proposal, approval, writeback, idempotent
+retry, stale-row conflict, replay, strict-shadow, human-outcome, and effect
+proofs. Run only the deterministic comparison pass with:
+
+```bash
+make evaluate
+```
 
 ## What This Wraps
 
@@ -77,7 +120,16 @@ Relevant files:
 - `db/seed.sql`
 - `synapsor.runner.json`
 - `scripts/run-demo.sh`
+- `scripts/run-evaluation.sh`
 - `app/README.md`
+- `app/contract.ts`
+- `app/record-shadow-outcomes.mjs`
+- `app/effect-adapter.mjs`
+- `shadow-study/cases.jsonl` and `shadow-study/outcomes.jsonl`: deterministic
+  true-shadow reference data for agent-versus-authoritative-outcome reports.
+
+See [Shadow Studies](../../docs/shadow-studies.md) for the import and report
+commands. The reference cases do not mutate this demo database.
 
 ## Stop And Clean Up
 

package/examples/support-billing-agent/app/README.md

@@ -11,3 +11,9 @@ writeback with tenant, primary-key, allowed-column, idempotency, and
 For richer app actions, such as inserting a credit ledger row and emitting an
 event, use the app-owned handler examples in `../app-owned-writeback/` and
 `../mcp-postgres-billing-app-handler/`.
+
+`contract.ts` demonstrates the optional typed authoring frontend without
+changing the canonical contract. `record-shadow-outcomes.mjs` is the normal-app
+bridge for authoritative human outcomes. `effect-adapter.mjs` is a deterministic
+propose-only CI adapter; it receives a bounded fixture path and emits one
+canonical result. Neither helper approves, applies, or mutates the source.

package/examples/support-billing-agent/app/contract.ts

@@ -0,0 +1,28 @@
+import { defineCapability } from "@synapsor/runner/authoring";
+
+export const waiveLateFee = defineCapability({
+  name: "billing.propose_late_fee_waiver",
+  kind: "proposal",
+  context: "local_operator",
+  source: "app_postgres",
+  subject: { resource: "billing.invoice", primary_key: "id", tenant_key: "tenant_id" },
+  args: {
+    invoice_id: { type: "string", required: true, max_length: 128 },
+    reason: { type: "string", required: true, max_length: 500 },
+  },
+  lookup: { id_from_arg: "invoice_id" },
+  visible_fields: ["id", "tenant_id", "late_fee_cents", "waiver_reason", "updated_at"],
+  kept_out_fields: ["card_token", "internal_risk_note"],
+  evidence: { required: true, query_audit: true },
+  max_rows: 1,
+  proposal: {
+    action: "waive_late_fee",
+    operation: { kind: "update" },
+    allowed_fields: ["late_fee_cents", "waiver_reason"],
+    patch: { late_fee_cents: { fixed: 0 }, waiver_reason: { from_arg: "reason" } },
+    numeric_bounds: { late_fee_cents: { minimum: 0, maximum: 10000 } },
+    conflict_guard: { column: "updated_at" },
+    approval: { mode: "human", required_role: "billing_lead" },
+    writeback: { mode: "direct_sql" },
+  },
+});

package/examples/support-billing-agent/app/effect-adapter.mjs

@@ -0,0 +1,23 @@
+import fs from "node:fs";
+
+if (process.env.SYNAPSOR_EFFECT_MODE !== "propose_only") {
+  throw new Error("reference effect adapter requires SYNAPSOR_EFFECT_MODE=propose_only");
+}
+if (process.env.DATABASE_URL || process.env.SYNAPSOR_DATABASE_WRITE_URL) {
+  throw new Error("reference effect adapter must not receive database credentials");
+}
+const fixturePath = process.env.SYNAPSOR_EFFECT_FIXTURE_PATH;
+if (!fixturePath) throw new Error("SYNAPSOR_EFFECT_FIXTURE_PATH is required");
+const fixture = JSON.parse(fs.readFileSync(fixturePath, "utf8"));
+const expected = fixture.expected;
+
+process.stdout.write(`${JSON.stringify({
+  schema_version: "synapsor.effect-result.v1",
+  fixture_id: fixture.fixture_id,
+  capability_calls: expected.capability_calls.map((name) => ({ name })),
+  trusted_context: expected.trusted_context,
+  proposal: expected.proposal,
+  observed_fields: Object.keys(expected.proposal.diff ?? {}).sort(),
+  evidence: { mode: "fixture", new_source_reads: false },
+  source_database_changed: false,
+})}\n`);

package/examples/support-billing-agent/app/record-shadow-outcomes.mjs

@@ -0,0 +1,44 @@
+import { createShadowOutcomeRecorder } from "@synapsor/runner/shadow";
+
+const [storePath, studyId] = process.argv.slice(2);
+if (!storePath || !studyId) {
+  throw new Error("usage: node record-shadow-outcomes.mjs <store-path> <study-id>");
+}
+
+const recorder = createShadowOutcomeRecorder({
+  storePath,
+  studyId,
+  actor: "support_reference_app",
+  source: "support-app-audit",
+});
+try {
+  recorder.record({
+    requestId: "req-waiver-exact",
+    tenantId: "acme",
+    businessObject: "invoice",
+    objectId: "INV-3001",
+    disposition: "applied",
+    actualEffect: {
+      before: { late_fee_cents: 5500, waiver_reason: null },
+      after: { late_fee_cents: 0, waiver_reason: "courtesy waiver" },
+      patch: { late_fee_cents: 0, waiver_reason: "courtesy waiver" },
+    },
+    occurredAt: "2026-07-19T11:00:00.000Z",
+    reference: "ticket:SUP-184",
+    reason: "customer qualified",
+  });
+  recorder.record({
+    requestId: "req-waiver-rejected",
+    tenantId: "acme",
+    businessObject: "invoice",
+    objectId: "INV-REJECTED",
+    disposition: "rejected_no_action",
+    occurredAt: "2026-07-19T11:01:00.000Z",
+    reference: "ticket:SUP-REJECTED",
+    reason: "customer already received a courtesy waiver",
+  });
+} finally {
+  recorder.close();
+}
+
+process.stdout.write("Recorded 2 authoritative outcomes through @synapsor/runner/shadow.\n");

package/examples/support-billing-agent/db/schema.sql

@@ -8,6 +8,7 @@ CREATE TABLE IF NOT EXISTS public.tenants (
 CREATE TABLE IF NOT EXISTS public.customers (
   id text PRIMARY KEY,
   tenant_id text NOT NULL REFERENCES public.tenants(id),
+  assigned_to text NOT NULL,
   name text NOT NULL,
   email text,
   plan text NOT NULL,
@@ -20,6 +21,7 @@ CREATE TABLE IF NOT EXISTS public.customers (
 CREATE TABLE IF NOT EXISTS public.support_tickets (
   id text PRIMARY KEY,
   tenant_id text NOT NULL REFERENCES public.tenants(id),
+  assigned_to text NOT NULL,
   customer_id text NOT NULL REFERENCES public.customers(id),
   subject text NOT NULL,
   status text NOT NULL,
@@ -30,11 +32,14 @@ CREATE TABLE IF NOT EXISTS public.support_tickets (
 CREATE TABLE IF NOT EXISTS public.invoices (
   id text PRIMARY KEY,
   tenant_id text NOT NULL REFERENCES public.tenants(id),
+  assigned_to text NOT NULL,
   customer_id text NOT NULL REFERENCES public.customers(id),
   status text NOT NULL,
   balance_cents integer NOT NULL,
   late_fee_cents integer NOT NULL,
   waiver_reason text,
+  card_token text,
+  internal_risk_note text,
   updated_at timestamptz NOT NULL DEFAULT now()
 );
 
@@ -93,9 +98,91 @@ $$;
 
 GRANT CONNECT ON DATABASE synapsor_support_billing_agent TO synapsor_reader, synapsor_writer;
 GRANT USAGE ON SCHEMA public TO synapsor_reader, synapsor_writer;
-GRANT SELECT ON public.tenants, public.customers, public.support_tickets, public.invoices, public.credits, public.agent_actions, public.orders TO synapsor_reader, synapsor_writer;
+GRANT SELECT ON public.tenants, public.credits, public.agent_actions, public.orders TO synapsor_reader, synapsor_writer;
+GRANT SELECT (id, tenant_id, assigned_to, name, plan, plan_credit_cents, credit_reason, created_at, updated_at)
+  ON public.customers TO synapsor_reader, synapsor_writer;
+GRANT SELECT (id, tenant_id, assigned_to, customer_id, subject, status, resolution_note, updated_at)
+  ON public.support_tickets TO synapsor_reader, synapsor_writer;
+GRANT SELECT (id, tenant_id, assigned_to, customer_id, status, balance_cents, late_fee_cents, waiver_reason, updated_at)
+  ON public.invoices TO synapsor_reader, synapsor_writer;
 GRANT SELECT, INSERT, UPDATE ON public.synapsor_writeback_receipts TO synapsor_writer;
 GRANT UPDATE (plan_credit_cents, credit_reason, updated_at) ON public.customers TO synapsor_writer;
 GRANT UPDATE (status, resolution_note, updated_at) ON public.support_tickets TO synapsor_writer;
 GRANT UPDATE (late_fee_cents, waiver_reason, updated_at) ON public.invoices TO synapsor_writer;
 GRANT UPDATE (status, status_change_reason, updated_at) ON public.orders TO synapsor_writer;
+
+ALTER TABLE public.customers ENABLE ROW LEVEL SECURITY;
+ALTER TABLE public.customers FORCE ROW LEVEL SECURITY;
+ALTER TABLE public.support_tickets ENABLE ROW LEVEL SECURITY;
+ALTER TABLE public.support_tickets FORCE ROW LEVEL SECURITY;
+ALTER TABLE public.invoices ENABLE ROW LEVEL SECURITY;
+ALTER TABLE public.invoices FORCE ROW LEVEL SECURITY;
+
+CREATE POLICY customers_reader_scope ON public.customers
+  FOR SELECT TO synapsor_reader
+  USING (
+    tenant_id = current_setting('synapsor.tenant_id', true)
+    AND assigned_to = current_setting('synapsor.principal', true)
+  );
+CREATE POLICY customers_writer_select_scope ON public.customers
+  FOR SELECT TO synapsor_writer
+  USING (
+    tenant_id = current_setting('synapsor.tenant_id', true)
+    AND assigned_to = current_setting('synapsor.principal', true)
+  );
+CREATE POLICY customers_writer_update_scope ON public.customers
+  FOR UPDATE TO synapsor_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 support_tickets_reader_scope ON public.support_tickets
+  FOR SELECT TO synapsor_reader
+  USING (
+    tenant_id = current_setting('synapsor.tenant_id', true)
+    AND assigned_to = current_setting('synapsor.principal', true)
+  );
+CREATE POLICY support_tickets_writer_select_scope ON public.support_tickets
+  FOR SELECT TO synapsor_writer
+  USING (
+    tenant_id = current_setting('synapsor.tenant_id', true)
+    AND assigned_to = current_setting('synapsor.principal', true)
+  );
+CREATE POLICY support_tickets_writer_update_scope ON public.support_tickets
+  FOR UPDATE TO synapsor_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_reader_scope ON public.invoices
+  FOR SELECT TO synapsor_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 synapsor_writer
+  USING (
+    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 synapsor_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)
+  );

package/examples/support-billing-agent/db/seed.sql

@@ -4,26 +4,26 @@ VALUES
   ('otherco', 'OtherCo Labs', '2026-06-20T10:00:00Z', '2026-06-20T10:00:00Z')
 ON CONFLICT (id) DO UPDATE SET name = EXCLUDED.name, updated_at = EXCLUDED.updated_at;
 
-INSERT INTO public.customers (id, tenant_id, name, email, plan, plan_credit_cents, credit_reason, created_at, updated_at)
+INSERT INTO public.customers (id, tenant_id, assigned_to, name, email, plan, plan_credit_cents, credit_reason, created_at, updated_at)
 VALUES
-  ('cust_acme_1', 'acme', 'Acme Robotics', 'ops@example.invalid', 'enterprise', 0, NULL, '2026-06-20T10:00:00Z', '2026-06-20T10:00:00Z'),
-  ('cust_acme_2', 'acme', 'Acme Field Ops', 'field@example.invalid', 'builder', 0, NULL, '2026-06-20T10:00:00Z', '2026-06-20T10:00:00Z'),
-  ('cust_other_1', 'otherco', 'OtherCo Labs', 'ops@otherco.invalid', 'builder', 0, NULL, '2026-06-20T10:00:00Z', '2026-06-20T10:00:00Z')
-ON CONFLICT (id) DO UPDATE SET tenant_id = EXCLUDED.tenant_id, name = EXCLUDED.name, email = EXCLUDED.email, plan = EXCLUDED.plan, plan_credit_cents = EXCLUDED.plan_credit_cents, credit_reason = EXCLUDED.credit_reason, updated_at = EXCLUDED.updated_at;
+  ('cust_acme_1', 'acme', 'reference_operator', 'Acme Robotics', 'ops@example.invalid', 'enterprise', 0, NULL, '2026-06-20T10:00:00Z', '2026-06-20T10:00:00Z'),
+  ('cust_acme_2', 'acme', 'another_operator', 'Acme Field Ops', 'field@example.invalid', 'builder', 0, NULL, '2026-06-20T10:00:00Z', '2026-06-20T10:00:00Z'),
+  ('cust_other_1', 'otherco', 'reference_operator', 'OtherCo Labs', 'ops@otherco.invalid', 'builder', 0, NULL, '2026-06-20T10:00:00Z', '2026-06-20T10:00:00Z')
+ON CONFLICT (id) DO UPDATE SET tenant_id = EXCLUDED.tenant_id, assigned_to = EXCLUDED.assigned_to, name = EXCLUDED.name, email = EXCLUDED.email, plan = EXCLUDED.plan, plan_credit_cents = EXCLUDED.plan_credit_cents, credit_reason = EXCLUDED.credit_reason, updated_at = EXCLUDED.updated_at;
 
-INSERT INTO public.support_tickets (id, tenant_id, customer_id, subject, status, resolution_note, updated_at)
+INSERT INTO public.support_tickets (id, tenant_id, assigned_to, customer_id, subject, status, resolution_note, updated_at)
 VALUES
-  ('T-1042', 'acme', 'cust_acme_1', 'Late fee waiver request for INV-3001', 'open', NULL, '2026-06-20T12:00:00Z'),
-  ('T-1043', 'acme', 'cust_acme_2', 'Duplicate card charge question', 'open', NULL, '2026-06-20T12:05:00Z'),
-  ('T-9001', 'otherco', 'cust_other_1', 'OtherCo private billing ticket', 'open', NULL, '2026-06-20T12:00:00Z')
-ON CONFLICT (id) DO UPDATE SET tenant_id = EXCLUDED.tenant_id, customer_id = EXCLUDED.customer_id, subject = EXCLUDED.subject, status = EXCLUDED.status, resolution_note = EXCLUDED.resolution_note, updated_at = EXCLUDED.updated_at;
+  ('SUP-184', 'acme', 'reference_operator', 'cust_acme_1', 'Late fee waiver request for INV-3001', 'open', NULL, '2026-06-20T12:00:00Z'),
+  ('SUP-185', 'acme', 'another_operator', 'cust_acme_2', 'Duplicate card charge question', 'open', NULL, '2026-06-20T12:05:00Z'),
+  ('SUP-9001', 'otherco', 'reference_operator', 'cust_other_1', 'OtherCo private billing ticket', 'open', NULL, '2026-06-20T12:00:00Z')
+ON CONFLICT (id) DO UPDATE SET tenant_id = EXCLUDED.tenant_id, assigned_to = EXCLUDED.assigned_to, customer_id = EXCLUDED.customer_id, subject = EXCLUDED.subject, status = EXCLUDED.status, resolution_note = EXCLUDED.resolution_note, updated_at = EXCLUDED.updated_at;
 
-INSERT INTO public.invoices (id, tenant_id, customer_id, status, balance_cents, late_fee_cents, waiver_reason, updated_at)
+INSERT INTO public.invoices (id, tenant_id, assigned_to, customer_id, status, balance_cents, late_fee_cents, waiver_reason, card_token, internal_risk_note, updated_at)
 VALUES
-  ('INV-3001', 'acme', 'cust_acme_1', 'overdue', 25500, 5500, NULL, '2026-06-20T14:31:08Z'),
-  ('INV-3002', 'acme', 'cust_acme_2', 'paid', 0, 0, NULL, '2026-06-20T14:40:00Z'),
-  ('INV-9001', 'otherco', 'cust_other_1', 'overdue', 25500, 5500, NULL, '2026-06-20T14:31:08Z')
-ON CONFLICT (id) DO UPDATE SET tenant_id = EXCLUDED.tenant_id, customer_id = EXCLUDED.customer_id, status = EXCLUDED.status, balance_cents = EXCLUDED.balance_cents, late_fee_cents = EXCLUDED.late_fee_cents, waiver_reason = EXCLUDED.waiver_reason, updated_at = EXCLUDED.updated_at;
+  ('INV-3001', 'acme', 'reference_operator', 'cust_acme_1', 'overdue', 25500, 5500, NULL, 'tok_acme_must_stay_hidden', 'manual risk note must stay hidden', '2026-06-20T14:31:08Z'),
+  ('INV-3002', 'acme', 'another_operator', 'cust_acme_2', 'paid', 0, 0, NULL, 'tok_acme_other_principal', 'another principal note', '2026-06-20T14:40:00Z'),
+  ('INV-9001', 'otherco', 'reference_operator', 'cust_other_1', 'overdue', 25500, 5500, NULL, 'tok_other_tenant', 'other tenant note', '2026-06-20T14:31:08Z')
+ON CONFLICT (id) DO UPDATE SET tenant_id = EXCLUDED.tenant_id, assigned_to = EXCLUDED.assigned_to, customer_id = EXCLUDED.customer_id, status = EXCLUDED.status, balance_cents = EXCLUDED.balance_cents, late_fee_cents = EXCLUDED.late_fee_cents, waiver_reason = EXCLUDED.waiver_reason, card_token = EXCLUDED.card_token, internal_risk_note = EXCLUDED.internal_risk_note, updated_at = EXCLUDED.updated_at;
 
 INSERT INTO public.credits (id, tenant_id, customer_id, invoice_id, amount_cents, reason, status, created_at, updated_at)
 VALUES

package/examples/support-billing-agent/scripts/run-demo.sh

@@ -12,4 +12,8 @@ SYNAPSOR_REFERENCE_DB="synapsor_support_billing_agent" \
 SYNAPSOR_REFERENCE_PORT="55436" \
 SYNAPSOR_REFERENCE_EXPECTED_TOOLS="support.inspect_ticket,support.propose_plan_credit,billing.inspect_invoice,billing.propose_late_fee_waiver" \
 SYNAPSOR_REFERENCE_EXACT_TOOLS="1" \
+SYNAPSOR_REFERENCE_TICKET_ID="SUP-184" \
+SYNAPSOR_REFERENCE_REQUIRE_PRINCIPAL_SCOPE="1" \
+SYNAPSOR_REFERENCE_REQUIRE_RLS="1" \
+SYNAPSOR_REFERENCE_SHADOW_PROOF="1" \
 node scripts/smoke-reference-support-billing-app.mjs

package/examples/support-billing-agent/scripts/run-evaluation.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
+cd "$ROOT_DIR"
+
+OUTPUT_DIR="$ROOT_DIR/tmp/support-billing-agent/evaluation"
+STORE_PATH="$OUTPUT_DIR/shadow.db"
+REPORT_PATH="$OUTPUT_DIR/shadow-report.json"
+EFFECT_PATH="$OUTPUT_DIR/effect-report.json"
+
+rm -rf "$OUTPUT_DIR"
+mkdir -p "$OUTPUT_DIR"
+
+corepack pnpm runner shadow study create \
+  --id sst_support_reference \
+  --name "Support reference study" \
+  --capability billing.propose_late_fee_waiver \
+  --store "$STORE_PATH" >/dev/null
+
+corepack pnpm runner shadow case import \
+  --study sst_support_reference \
+  --input "$ROOT_DIR/examples/support-billing-agent/shadow-study/cases.jsonl" \
+  --store "$STORE_PATH" >/dev/null
+
+corepack pnpm build:runner-package >/dev/null
+node "$ROOT_DIR/examples/support-billing-agent/app/record-shadow-outcomes.mjs" \
+  "$STORE_PATH" sst_support_reference >/dev/null
+
+corepack pnpm runner shadow report \
+  --study sst_support_reference \
+  --store "$STORE_PATH" \
+  --output "$REPORT_PATH" >/dev/null
+
+node --input-type=module - "$REPORT_PATH" <<'NODE'
+import fs from "node:fs";
+const report = JSON.parse(fs.readFileSync(process.argv[2], "utf8"));
+const expected = {
+  total_tasks_observed: 6,
+  tasks_with_authoritative_outcomes: 2,
+  comparable_tasks: 1,
+  exact_agreements: 1,
+  human_rejections_no_action: 1,
+  policy_denials: 1,
+  stale_conflicts: 1,
+  unmatched_cases: 1,
+  invalid_or_unsafe_scope_attempts: 1,
+};
+for (const [key, value] of Object.entries(expected)) {
+  if (report[key] !== value) throw new Error(`shadow report ${key}=${report[key]}, expected ${value}`);
+}
+NODE
+
+corepack pnpm runner effect run \
+  --dataset "$ROOT_DIR/fixtures/effects/dataset.json" \
+  --adapter node \
+  --adapter-arg "$ROOT_DIR/examples/support-billing-agent/app/effect-adapter.mjs" \
+  --result-origin deterministic-application \
+  --format json \
+  --out "$EFFECT_PATH" >/dev/null
+
+printf '%s\n' "Shadow comparison passed: 6 cases, 2 human outcomes, 1 exact agreement, 1 human rejection."
+printf '%s\n' "Effect regression passed: the reviewed \$55 waiver effect is unchanged."

package/examples/support-billing-agent/shadow-study/cases.jsonl

@@ -0,0 +1,6 @@
+{"request_id":"req-waiver-exact","tenant_id":"acme","principal":"support-agent-shadow","capability":"billing.propose_late_fee_waiver","business_object":"invoice","object_id":"INV-3001","agent_result":"proposed","proposed_effect":{"before":{"late_fee_cents":5500,"waiver_reason":null},"after":{"late_fee_cents":0,"waiver_reason":"courtesy waiver"},"patch":{"late_fee_cents":0,"waiver_reason":"courtesy waiver"}},"decision_reason":"customer qualifies for one courtesy waiver","risk_score":20,"amount_value":5500,"created_at":"2026-07-19T10:00:00.000Z"}
+{"request_id":"req-waiver-rejected","tenant_id":"acme","principal":"support-agent-shadow","capability":"billing.propose_late_fee_waiver","business_object":"invoice","object_id":"INV-REJECTED","agent_result":"proposed","proposed_effect":{"before":{"late_fee_cents":5500,"waiver_reason":null},"after":{"late_fee_cents":0,"waiver_reason":"courtesy waiver"},"patch":{"late_fee_cents":0,"waiver_reason":"courtesy waiver"}},"decision_reason":"agent found apparent eligibility","risk_score":45,"amount_value":5500,"created_at":"2026-07-19T10:01:00.000Z"}
+{"request_id":"req-waiver-policy","tenant_id":"acme","principal":"support-agent-shadow","capability":"billing.propose_late_fee_waiver","business_object":"invoice","object_id":"INV-EXCESSIVE","agent_result":"policy_denied","decision_reason":"amount above reviewed bound","risk_score":70,"amount_value":25000,"created_at":"2026-07-19T10:02:00.000Z"}
+{"request_id":"req-waiver-stale","tenant_id":"acme","principal":"support-agent-shadow","capability":"billing.propose_late_fee_waiver","business_object":"invoice","object_id":"INV-STALE","agent_result":"stale_conflict","decision_reason":"source version moved before proposal could be normalized","risk_score":60,"amount_value":5500,"created_at":"2026-07-19T10:03:00.000Z"}
+{"request_id":"req-waiver-forgery","tenant_id":"acme","principal":"support-agent-shadow","capability":"billing.propose_late_fee_waiver","business_object":"invoice","object_id":"INV-OTHER-TENANT","agent_result":"invalid_unsafe_scope_attempt","decision_reason":"model-supplied tenant override rejected","risk_score":100,"created_at":"2026-07-19T10:04:00.000Z"}
+{"request_id":"req-waiver-unmatched","tenant_id":"acme","principal":"support-agent-shadow","capability":"billing.propose_late_fee_waiver","business_object":"invoice","object_id":"INV-UNMATCHED","agent_result":"proposed","proposed_effect":{"before":{"late_fee_cents":5500,"waiver_reason":null},"after":{"late_fee_cents":0,"waiver_reason":"courtesy waiver"},"patch":{"late_fee_cents":0,"waiver_reason":"courtesy waiver"}},"decision_reason":"awaiting authoritative outcome","risk_score":30,"amount_value":5500,"created_at":"2026-07-19T10:05:00.000Z"}

package/examples/support-billing-agent/shadow-study/outcomes.jsonl

@@ -0,0 +1,2 @@
+{"request_id":"req-waiver-exact","tenant_id":"acme","business_object":"invoice","object_id":"INV-3001","actor":"support_lead_1","disposition":"applied","actual_effect":{"before":{"late_fee_cents":5500,"waiver_reason":null},"after":{"late_fee_cents":0,"waiver_reason":"courtesy waiver"},"patch":{"late_fee_cents":0,"waiver_reason":"courtesy waiver"}},"occurred_at":"2026-07-19T11:00:00.000Z","source":"support-system-audit","reference":"ticket:SUP-184","reason":"customer qualified"}
+{"request_id":"req-waiver-rejected","tenant_id":"acme","business_object":"invoice","object_id":"INV-REJECTED","actor":"support_lead_2","disposition":"rejected_no_action","occurred_at":"2026-07-19T11:01:00.000Z","source":"support-system-audit","reference":"ticket:SUP-REJECTED","reason":"customer already received a courtesy waiver"}

package/examples/support-billing-agent/synapsor.runner.json

@@ -9,7 +9,15 @@
       "engine": "postgres",
       "read_url_env": "REFERENCE_POSTGRES_READ_URL",
       "write_url_env": "REFERENCE_POSTGRES_WRITE_URL",
-      "statement_timeout_ms": 3000
+      "statement_timeout_ms": 3000,
+      "database_scope": {
+        "mode": "postgres_rls",
+        "tenant_setting": "synapsor.tenant_id",
+        "principal_setting": "synapsor.principal"
+      },
+      "credential_scope": {
+        "mode": "shared"
+      }
     }
   },
   "trusted_context": {
@@ -38,7 +46,8 @@
         "schema": "public",
         "table": "support_tickets",
         "primary_key": "id",
-        "tenant_key": "tenant_id"
+        "tenant_key": "tenant_id",
+        "principal_scope_key": "assigned_to"
       },
       "args": {
         "ticket_id": {
@@ -71,7 +80,8 @@
         "schema": "public",
         "table": "customers",
         "primary_key": "id",
-        "tenant_key": "tenant_id"
+        "tenant_key": "tenant_id",
+        "principal_scope_key": "assigned_to"
       },
       "args": {
         "customer_id": {
@@ -140,7 +150,8 @@
         "schema": "public",
         "table": "invoices",
         "primary_key": "id",
-        "tenant_key": "tenant_id"
+        "tenant_key": "tenant_id",
+        "principal_scope_key": "assigned_to"
       },
       "args": {
         "invoice_id": {
@@ -174,7 +185,8 @@
         "schema": "public",
         "table": "invoices",
         "primary_key": "id",
-        "tenant_key": "tenant_id"
+        "tenant_key": "tenant_id",
+        "principal_scope_key": "assigned_to"
       },
       "args": {
         "invoice_id": {

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

@@ -15,7 +15,7 @@ policy-tier demonstration.
 ## Prerequisites
 
 - Docker
-- Node 22.5+
+- Node 22.13+
 - Port `55438` available
 
 Install the stable CLI once for the commands below:
@@ -50,6 +50,42 @@ network connection or connecting to a database. From a source checkout,
 `corepack pnpm verify:adoption` runs this boundary check plus the no-database
 quick demo and MCP config validation.
 
+## Clone And Validate The Same Safe Action
+
+The checked-in code-first action is
+[`synapsor/actions/support.propose_plan_credit.ts`](synapsor/actions/support.propose_plan_credit.ts).
+It is a reviewable frontend for the same canonical JSON contract, not another
+runtime format. Editing it cannot change active tools.
+
+After cloning the repository and installing dependencies, another developer can
+run the deterministic team gate without a database or Cloud account:
+
+```bash
+corepack pnpm install --frozen-lockfile
+corepack pnpm verify:safe-action-team
+```
+
+The verifier copies this example to a disposable directory, compiles the action
+only as a disabled draft, compares the regenerated boundary tests with the
+checked-in file, proves the config and active contract are unchanged, and emits
+text, JSON, and JUnit reports under `tmp/safe-action-team-ci/`. Its static gate
+covers the exact proposal effect, trusted scope, evidence requirement, approval
+policy, operator separation, kept-out fields, argument bounds, and conflict
+guard. It performs no approval, activation, source read, or source mutation.
+
+The same gate runs in
+[`safe-action-ci.yml`](https://github.com/Synapsor/Synapsor-Runner/blob/main/.github/workflows/safe-action-ci.yml).
+CI adds a disposable PostgreSQL service and runs the generated allowed-effect,
+cross-tenant-denial, and source-unchanged assertions. It uses an amount above
+the auto-approval threshold, performs no approval or apply, and requires source
+rows and source receipt state to remain equivalent before and after the live
+suite.
+For a real staging preview, each developer supplies their own
+`PLAN_CREDIT_POSTGRES_READ_URL`, `PLAN_CREDIT_POSTGRES_WRITE_URL`,
+`SYNAPSOR_TENANT_ID`, and `SYNAPSOR_PRINCIPAL` outside Git, then follows the
+Quick Start below. Cursor receives the same proposal-only tools; activation,
+approval, and apply remain outside the agent.
+
 ## Quick Start
 
 ```bash
@@ -199,9 +235,19 @@ shape without guessing which state should change.
 Copy the matching template from [`mcp-client-examples/`](mcp-client-examples/):
 
 - Claude Desktop: `claude-desktop.json`
+- Claude Code: `claude-code.sh`
+- Codex: `codex.config.toml`
 - Cursor project/global: `cursor-project.mcp.json`, `cursor-global.mcp.json`
+- VS Code: `vscode.mcp.json`
 - OpenAI Agents SDK: stdio and Streamable HTTP TypeScript examples
-- generic MCP: stdio and Streamable HTTP JSON examples
+- LangChain/LangGraph: `langchain.mjs`
+- Google ADK: `google-adk.py`
+- LlamaIndex: `llamaindex.py`
+- generic MCP: stdio and Streamable HTTP JSON and JavaScript examples
+
+See [Client And Framework Recipes](../../docs/client-recipes.md) for current
+official references, exact proposal input, evidence labels, and the mechanical
+verification gate.
 
 For Streamable HTTP, run:
 

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

@@ -0,0 +1,23 @@
+# Support Plan Credit MCP Recipes
+
+These files connect different MCP hosts and frameworks to the same reviewed
+Runner tools:
+
+- `support.inspect_customer`
+- `support.propose_plan_credit`
+
+Every proposal example uses:
+
+```json
+{
+  "customer_id": "CUS-3001",
+  "credit_cents": 2500,
+  "reason": "SLA outage ticket SUP-481"
+}
+```
+
+The expected call result has `source_database_changed: false`. Human review,
+approval, and apply stay outside every model-facing recipe.
+
+See [Client And Framework Recipes](../../../docs/client-recipes.md) for setup,
+evidence labels, official references, and verification commands.