@synapsor/runner 1.4.123 → 1.5.3

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,179 @@
+# 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`.
+
+### Run an application-owned adapter
+
+For a real application harness, Runner can launch one provider-neutral command
+directly, without a shell:
+
+```bash
+synapsor-runner effect run \
+  --dataset ./effects/dataset.json \
+  --adapter node \
+  --adapter-arg ./app/effect-adapter.mjs \
+  --result-origin deterministic-application \
+  --format junit \
+  --out ./artifacts/effect-results.xml
+```
+
+Use `--result-origin external-model` when the adapter actually calls a model.
+The origin is included in text, JSON, and JUnit provenance so deterministic
+application results are not presented as model evidence.
+
+Runner starts the command with `shell: false`, a bounded argument list,
+timeout/output limits, and a minimal environment that omits ambient database
+URLs and tokens. It sets `SYNAPSOR_EFFECT_MODE=propose_only`,
+`SYNAPSOR_EFFECT_FIXTURE_PATH`, and
+`SYNAPSOR_EFFECT_SOURCE_DATABASE_CHANGED=false`. The command must emit exactly
+one canonical result JSON document to stdout.
+
+This is a process boundary, not a sandbox. Adopter-owned code can deliberately
+load its own credentials, so keep the adapter propose-only and point it at
+fixtures or an explicitly disposable source. Runner still rejects every result
+that reports source mutation.
+
+The repository's working example is
+[`examples/support-billing-agent/app/effect-adapter.mjs`](../examples/support-billing-agent/app/effect-adapter.mjs),
+and [`.github/workflows/effect-regression.yml`](https://github.com/Synapsor/Synapsor-Runner/blob/main/.github/workflows/effect-regression.yml)
+runs it and uploads JUnit output on relevant pull requests.
+
+## 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.
+- Offline `--result`/`--results-dir` mode executes no provider command or
+  application code. `--adapter` explicitly executes the adopter-owned command
+  under the bounded process contract above.
+- 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/fresh-developer-usability.md

@@ -0,0 +1,110 @@
+# Fresh-Developer Usability Protocol
+
+Use this protocol with five developers who have not previously used Synapsor.
+It is a launch gate, not an automated test. A maintainer may rehearse the
+protocol, but must not report a participant result unless that person actually
+completed the session.
+
+## Goal
+
+Measure whether a developer can connect an existing supported staging project,
+draft one disabled Safe Action with a coding agent, receive an exact Data PR,
+approve outside the agent, and find the guarded receipt without learning the
+canonical JSON or SQL-like DSL first.
+
+Measure product time separately from the initial package download. Start the
+product timer only after `synapsor-runner --version` succeeds.
+
+## Participant Setup
+
+Provide each participant with:
+
+- a fresh clone of their application or the support-plan-credit reference app;
+- Node 22.13 or newer;
+- a disposable Postgres staging database and least-privilege read/write roles;
+- exported database URLs and trusted tenant/principal values;
+- current stable Cursor, with no existing Synapsor configuration;
+- the README only. Do not give verbal product-architecture instruction.
+
+Never use production credentials or data. Record the OS, Node version, Cursor
+version, package-install method, database engine, and whether the package was
+already cached.
+
+## Tasks
+
+Ask the participant to complete these tasks without a maintainer taking control:
+
+1. Run the four-second synthetic proof and identify whether the model can call
+   `approve`, `apply`, `commit`, or raw SQL.
+2. Connect the staging project and confirm the trusted organization scope.
+3. Tell Cursor one business action to make safe and use the generated
+   `/synapsor-protect` path or exact fallback prompt.
+4. Find the disabled action file and explain why editing it does not activate a
+   tool.
+5. Open the Workbench effect preview and confirm the source row is unchanged.
+6. Explicitly activate the reviewed digest through the operator-controlled UI.
+7. Reconnect Cursor if instructed and create one proposal through the semantic
+   tool.
+8. Review the exact before/after Data PR, approve outside Cursor, and apply it.
+9. Locate the receipt/replay record and explain what happens on retry.
+10. Draft a second disabled action without changing the active tool surface.
+
+Do not rescue a participant until they have been blocked for two minutes. Record
+the exact screen, command, wording, or missing prerequisite that blocked them.
+
+## Measurements
+
+For each participant, record:
+
+| Measure | Target |
+| --- | --- |
+| Installed CLI to first own-data Data PR | under 5 minutes |
+| Installed CLI to first guarded receipt | under 8 minutes |
+| Second disabled action draft after setup | under 2 minutes |
+| Second action ready for explicit activation | under 5 minutes |
+| Handwritten canonical JSON or DSL | none on the happy path |
+| Extra CLI command after Cursor proposal call | none |
+| Unsafe authority exposed to Cursor | none |
+
+Also record every wrong turn, maintainer intervention, misunderstood trust
+boundary, and request for a model-provider key or Synapsor account.
+
+## Pass Criteria
+
+The launch gate passes only when all five participants:
+
+- complete the first Data PR without handwritten JSON or DSL;
+- correctly identify that activation, approval, and apply are outside the
+  model-facing MCP surface;
+- observe unchanged source data before approval;
+- produce one guarded receipt; and
+- expose only the intended semantic read/proposal tools in Cursor.
+
+At least four of five must meet every timing target. Any cross-tenant result,
+hidden-field exposure, pre-approval mutation, automatic activation, raw SQL
+tool, or model-visible commit authority is a release blocker regardless of
+timing.
+
+## Reporting Template
+
+Record one row per real participant:
+
+```text
+Participant:
+Date:
+Environment:
+Cold package download:
+Product timer start:
+First Data PR:
+First receipt:
+Second draft:
+Second activation-ready action:
+Interventions:
+Tool surface observed:
+Safety-boundary explanation:
+Outcome: pass | fail
+```
+
+Until five real sessions are recorded, report this gate as **owner verification
+pending**. Do not infer usability from unit tests, protocol tests, or a
+maintainer-run demo.