@synapsor/runner 1.4.0 → 1.4.12

package/docs/bounded-set-writeback.md

@@ -0,0 +1,298 @@
+# Bounded Set Writeback
+
+Synapsor Runner can apply a deliberately narrow class of reviewed
+multi-row database changes to PostgreSQL and MySQL:
+
+- fixed-predicate set `UPDATE`;
+- fixed-predicate set `DELETE`;
+- exact-review batch `INSERT`.
+
+This is not model-generated SQL and it is not a generic batch API. The model
+can ask to run a reviewed business action, but it cannot choose a table,
+column, operator, ordering, predicate, tenant, or unbounded set.
+
+## Safety invariant
+
+The worst action available to a prompt-injected model is to request one
+contract-authored rule, against the trusted tenant, up to the reviewer-authored
+row and value caps. Before approval, Runner freezes the exact ordered members.
+Apply later touches only those members in one transaction and records every
+identity and bounded digest.
+
+Every bounded set requires:
+
+1. a fixed typed selection for existing-row UPDATE/DELETE, or the complete
+   reviewed item array for batch INSERT;
+2. `MAX ROWS n`, where `1 <= n <= 100`;
+3. at least one aggregate `MAX TOTAL` bound;
+4. trusted tenant binding;
+5. exact version guards and integer advancement for set UPDATE;
+6. source-unique per-item identities for batch INSERT;
+7. human/operator approval outside MCP;
+8. one atomic source transaction and an exact affected-row count;
+9. source or Runner-ledger receipts with the documented crash semantics.
+
+A row cap is a rejection threshold, never `LIMIT n` truncation. Proposal reads
+fetch at most `n + 1`; finding the extra row rejects before proposal
+persistence. Aggregate overflow also rejects before persistence.
+
+## DSL examples
+
+Fixed set UPDATE:
+
+```sql
+PROPOSE ACTION close_overdue UPDATE SET
+SELECT WHERE status = 'overdue'
+MAX ROWS 10
+MAX TOTAL balance_cents BEFORE 50000
+ALLOW WRITE status
+PATCH status = 'closed'
+ADVANCE VERSION version USING INTEGER INCREMENT
+APPROVAL ROLE billing_reviewer
+WRITEBACK DIRECT SQL
+```
+
+The selection is a contract literal. It is not an argument and is never taken
+from the model. The first release supports equality terms joined by `AND`.
+
+Exact-review batch INSERT:
+
+```sql
+ARG items ROWS MAX 10 REQUIRED
+ITEM FIELD items.id STRING REQUIRED MAX LENGTH 128
+ITEM FIELD items.external_id STRING REQUIRED MAX LENGTH 128
+ITEM FIELD items.amount_cents NUMBER REQUIRED MIN 1 MAX 2500
+ITEM FIELD items.reason STRING REQUIRED MAX LENGTH 500
+
+PROPOSE ACTION create_credits INSERT SET
+BATCH ITEMS FROM ARG items
+MAX ROWS 10
+MAX TOTAL amount_cents AFTER 25000
+DEDUP KEY tenant_id = TRUSTED TENANT, id = ITEM id, external_id = ITEM external_id
+ALLOW WRITE amount_cents, reason
+PATCH amount_cents = ITEM amount_cents
+PATCH reason = ITEM reason
+APPROVAL ROLE billing_reviewer
+WRITEBACK DIRECT SQL
+```
+
+The reviewer sees every allowlisted candidate item before approval. The source
+must enforce the declared identity with a primary or unique constraint.
+
+Set DELETE uses `DELETE SET`, a fixed selection, `MAX ROWS`, `MAX TOTAL`, and
+an exact conflict guard. It has no patch. Runner rejects hard DELETE if it
+cannot prove trigger/FK visibility or detects write triggers or widening
+cascades. Prefer a set UPDATE of `deleted_at` or status when possible.
+
+## Worked contract-to-apply example
+
+This PostgreSQL example closes two overdue tickets. MySQL is supported with
+the same contract semantics; change the source engine and schema/database name
+to match the inspected MySQL object.
+
+Create the fixture with an administrator account, then give the Runner reader
+`SELECT` and its separate writer only `SELECT, UPDATE` on this table:
+
+```sql
+CREATE TABLE public.service_tickets (
+  id bigint PRIMARY KEY,
+  tenant_id text NOT NULL,
+  status text NOT NULL,
+  cost_cents integer NOT NULL,
+  version integer NOT NULL
+);
+
+INSERT INTO public.service_tickets
+  (id, tenant_id, status, cost_cents, version)
+VALUES
+  (3, 'acme', 'overdue', 8000, 1),
+  (4, 'acme', 'overdue', 15000, 1),
+  (99, 'globex', 'overdue', 49000, 1);
+```
+
+Save this as `tickets.synapsor.sql`:
+
+```sql
+CREATE AGENT CONTEXT local_operator
+  BIND tenant_id FROM ENVIRONMENT SYNAPSOR_TENANT_ID REQUIRED
+  BIND principal FROM ENVIRONMENT SYNAPSOR_PRINCIPAL REQUIRED
+  TENANT BINDING tenant_id
+  PRINCIPAL BINDING principal
+END
+
+CREATE CAPABILITY tickets.close_overdue
+  USING CONTEXT local_operator
+  SOURCE local_db
+  ON public.service_tickets
+  PRIMARY KEY id
+  TENANT KEY tenant_id
+  CONFLICT GUARD version
+  LOOKUP reason BY id
+  ARG reason STRING REQUIRED MAX LENGTH 100
+  ALLOW READ id, tenant_id, status, cost_cents, version
+  REQUIRE EVIDENCE
+  PROPOSE ACTION close_overdue UPDATE SET
+  SELECT WHERE status = 'overdue'
+  MAX ROWS 10
+  MAX TOTAL cost_cents BEFORE 50000
+  ALLOW WRITE status
+  PATCH status = 'closed'
+  ADVANCE VERSION version USING INTEGER INCREMENT
+  APPROVAL ROLE ops_manager
+  WRITEBACK DIRECT SQL
+END
+```
+
+Compile the contract and create `synapsor.runner.json`:
+
+```bash
+synapsor-runner dsl compile ./tickets.synapsor.sql \
+  --out ./synapsor.contract.json --strict
+synapsor-runner contract validate ./synapsor.contract.json
+```
+
+```json
+{
+  "version": 1,
+  "mode": "review",
+  "storage": { "sqlite_path": "./.synapsor/local.db" },
+  "sources": {
+    "local_db": {
+      "engine": "postgres",
+      "read_url_env": "SYNAPSOR_DATABASE_READ_URL",
+      "write_url_env": "SYNAPSOR_DATABASE_WRITE_URL",
+      "statement_timeout_ms": 3000,
+      "receipts": { "authority": "runner_ledger" }
+    }
+  },
+  "contracts": ["./synapsor.contract.json"]
+}
+```
+
+Load database URLs from your shell or secret manager. The config stores only
+environment-variable names. Trusted tenant/principal values are process-owned,
+not tool arguments:
+
+```bash
+export SYNAPSOR_TENANT_ID=acme
+export SYNAPSOR_PRINCIPAL=local_operator
+
+synapsor-runner config validate --config ./synapsor.runner.json
+synapsor-runner doctor --config ./synapsor.runner.json --check-writeback
+synapsor-runner propose tickets.close_overdue \
+  --json '{"reason":"reviewed overdue-ticket close"}' \
+  --config ./synapsor.runner.json --store ./.synapsor/local.db
+synapsor-runner proposals show latest --store ./.synapsor/local.db --details
+```
+
+At this point IDs `3` and `4` are frozen in the proposal, but both source rows
+are still `overdue` at version `1`; the `globex` row is outside trusted tenant
+scope. Approval and apply remain operator-side commands and are not MCP tools:
+
+```bash
+synapsor-runner proposals approve latest --actor ops_manager --yes \
+  --store ./.synapsor/local.db
+synapsor-runner apply latest --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+synapsor-runner receipts list --proposal <proposal_id> \
+  --store ./.synapsor/local.db
+synapsor-runner replay show --proposal <proposal_id> --details \
+  --store ./.synapsor/local.db
+```
+
+Exactly IDs `3` and `4` become `closed` at version `2` in one transaction.
+The receipt/replay list both safe primary-key identities and their bounded
+digests. ID `99` is unchanged.
+
+To test drift on a freshly seeded copy, create the proposal, then use a
+database-operator session to increment one frozen row's version before
+approval. `apply` returns `SET_DRIFT_CONFLICT`; the other frozen row remains
+unchanged because no partial set mutation is committed:
+
+```sql
+UPDATE public.service_tickets SET version = version + 1 WHERE id = 4;
+```
+
+The example uses `runner_ledger`, which creates no receipt table in the source
+database. For one local process, the local store is the authority; a fleet must
+use authoritative shared-Postgres `runtime_store`. `source_db` authority
+instead writes the mutation and receipt atomically in one source transaction
+and requires its fixed precreated or auto-migrated receipt table. See
+[Guarded CRUD receipt authority](guarded-crud-writeback.md).
+
+## Proposal and apply behavior
+
+Proposal creation stores:
+
+- the exact ordered primary keys and trusted tenant;
+- every exact expected version;
+- allowlisted before/after values or bounded digests;
+- reviewed row count and aggregate values;
+- a digest over the complete frozen set;
+- pending human/operator approval.
+
+Member and set digests use SHA-256 over JSON whose object keys are sorted
+recursively. Array order remains significant because it is the reviewed,
+deterministic primary-key order. JSON strings, finite numbers, booleans, and
+null retain their protocol representation; unsupported runtime objects and
+non-finite values are rejected rather than stringified implicitly. Runner
+1.4.1 also verifies the narrowly known deterministic raw-object order emitted
+by 1.4.0, reconstructed from the complete stored reviewed data, so unchanged
+1.4.0 proposals remain applyable without weakening the drift checks.
+
+Apply locks the frozen rows in deterministic primary-key order, rechecks every
+reviewed value/version, performs every member mutation in one transaction, and
+requires the affected count to equal the frozen count. One missing/stale row or
+one database error rolls back the whole set.
+
+Set `sources.<name>.statement_timeout_ms` to bound source waits. PostgreSQL
+uses transaction-local statement and lock timeouts. MySQL applies the value to
+read/preflight execution and rounds it up to whole seconds for InnoDB lock
+waits; MySQL does not offer the same general DML statement timeout as
+PostgreSQL.
+
+The protocol-v3 receipt and replay include every primary key plus the bounded
+before/after or tombstone digests. Kept-out fields are never added merely to
+support a set operation.
+
+## Receipt authority and ambiguity
+
+`source_db` authority commits the mutation and receipt in the same source
+transaction. It gives the strongest retry classification.
+
+`runner_ledger` authority creates no source receipt table, but no atomic
+transaction spans the source and Runner ledger. A process loss after source
+commit can therefore produce `reconciliation_required`. Runner does not retry
+or guess. The operator reconciliation path re-inspects only the frozen,
+allowlisted identities and records an immutable decision.
+
+## Explicit boundary
+
+Use an [app-owned executor](writeback-executors.md) for:
+
+- model-supplied or free-form predicates;
+- ranges, wildcards, ordering, subqueries, or dynamic identifiers;
+- more than 100 rows or any unbounded batch;
+- UPSERT/MERGE, DDL, stored procedures, or cross-table/database transactions;
+- external API calls, events, files, emails, payments, or other side effects;
+- a hard DELETE whose trigger/cascade effects cannot be proven bounded.
+
+Policy auto-approval is not supported for bounded sets. Every set proposal
+requires a verified human/operator decision.
+
+## Verification
+
+Run the disposable-engine gate:
+
+```bash
+corepack pnpm test:bounded-set
+```
+
+It verifies both PostgreSQL and MySQL: the exact DSL/contract path under both
+receipt authorities; cap+1 and aggregate rejection before persistence; exact
+UPDATE/DELETE; batch INSERT; idempotent retry; independent version, predicate,
+aggregate, writable-value, missing-member, and tenant drift; injected mid-set
+rollback; insert dedup/atomicity; delete trigger/cascade refusal; exact receipt
+members; Runner-ledger reconciliation; and 1/10/100-row bounds. See the
+[local benchmark note](benchmarks/bounded-set-local.md) and the normative
+[safety RFC](rfcs/005-bounded-set-writeback.md).

package/docs/capability-authoring.md

@@ -447,3 +447,9 @@ Commit authority stays outside the model:
 ```text
 human/operator approval -> guarded writeback or app-owned handler -> receipt/replay
 ```
+
+If your application already exposes fixed parameterized functions, that is a
+good foundation rather than an anti-pattern. Read [Why Synapsor Over Prompt And
+Application Guardrails](why-synapsor-vs-app-guardrails.md) to decide whether
+you also need Runner's shared contract, trusted context, evidence, approval,
+receipt, replay, and compensation lifecycle.

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

@@ -368,7 +368,14 @@ npx -y -p @synapsor/runner synapsor-runner smoke call --config ./synapsor.runner
 
 `smoke call` uses the same runtime as the MCP server. It records evidence and
 query audit for read tools, or creates a proposal for proposal tools, then
-prints the commands to inspect evidence/proposals/replay from the local store.
+prints the commands to inspect evidence/proposals/replay. With the default
+storage topology those records are in local SQLite. With
+`storage.shared_postgres.mode = "runtime_store"`, Runner `1.4.12` and later
+write them to the authoritative shared Postgres ledger and include `--config`
+in follow-up commands. The supplied `--store` path is compatibility plumbing
+for those CLI commands; it does not receive an orphan proposal copy. If the
+shared ledger is unavailable, `smoke call` fails safely and does not fall back
+to SQLite.
 
 The snippets contain the local command and args. They must not contain database
 URLs, passwords, approval tools, commit tools, or write credentials.

package/docs/production.md

@@ -340,6 +340,16 @@ from `url_env`, auto-runs the shared-ledger migration, and serializes runtime
 mutations with a transaction-scoped advisory lock. The MCP tools still expose no
 database URLs or write credentials to the model.
 
+`smoke call` uses the same runtime-store resolver as MCP serving. Its evidence,
+query audit, proposal, events, and replay records therefore land directly in
+the shared Postgres ledger and are immediately visible to another Runner using
+the same config. `--store` remains accepted so the printed follow-up CLI
+commands have a compatibility/bridge path, but that SQLite path is not an
+authoritative copy and normally is not created by the smoke call. Shared-ledger
+connection failure returns the safe availability error and a nonzero exit; it
+never causes a local fallback. This consistency fix is present in Runner
+`1.4.12` and later.
+
 `runtime_store` covers MCP serving, CLI approval/apply, and supervised worker
 runs. For CLI mutations, Runner restores the shared ledger into a temporary
 local store while holding the Postgres advisory lock, runs the existing local

package/docs/release-notes.md

@@ -10,6 +10,47 @@ npx -y -p @synapsor/runner synapsor-runner demo --quick
 The OSS runner command is `synapsor-runner`. The `synapsor` command is reserved
 for the Synapsor Cloud CLI.
 
+## 1.4.12 (prepared, not published)
+
+### Runtime-store smoke-call consistency
+
+- Fixes BUG-017, where `smoke call` could put proposal artifacts in the
+  requested local SQLite path even though the config selected authoritative
+  shared Postgres `runtime_store` mode.
+- Smoke calls now use the same runtime storage resolver as MCP tool calls. A
+  second Runner can immediately inspect the proposal, evidence, query audit,
+  events, and replay from the shared ledger.
+- Shared-ledger unavailability fails closed with a safe retryable error,
+  nonzero exit status, no credential leakage, and no local orphan proposal.
+- Local SQLite and mirror modes retain their existing behavior; no source row
+  changes before the normal external approval/apply path.
+
+Prepared package version: `@synapsor/runner@1.4.12`.
+`@synapsor/dsl` remains `1.4.1`; `@synapsor/spec` remains `1.4.0`.
+
+## 1.4.1 (prepared, not published)
+
+### Bounded-set digest compatibility patch
+
+- Contract-authored bounded-set proposals now use deterministic recursive
+  object-key ordering for member and set digest material.
+- Valid proposals created by `1.4.0` remain applyable; the compatibility path
+  accepts only the known deterministic `1.4.0` serializations reconstructed
+  from the complete stored reviewed data.
+- Genuine member, version, value, aggregate, membership, or tenant drift still
+  fails closed before source mutation on PostgreSQL and MySQL.
+- The Runner package now includes the linked bounded-set guide and validates
+  all shipped local Markdown links while packaging.
+- The DSL package description and README no longer label the current `1.4.x`
+  package as a `0.1 preview`. Canonical contract `spec_version: "0.1"` is
+  unchanged.
+- Adds an honest prompt-and-application-guardrails decision guide covering SQL
+  authority, hand-built semantic tools, structural enforcement, build-vs-adopt
+  fit, and regulated-data boundaries.
+
+Prepared package versions: `@synapsor/dsl@1.4.1` and
+`@synapsor/runner@1.4.1`. `@synapsor/spec` remains `1.4.0`.
+
 ## 1.4.0 (prepared, not published)
 
 ### Reviewed Reversible Change Sets

package/docs/result-envelope-v3.md

@@ -0,0 +1,43 @@
+# Result Envelope V3
+
+Protocol v3 is used only for bounded set direct writeback. Protocol v1 and v2
+remain accepted for legacy UPDATE and guarded single-row CRUD.
+
+The public artifacts are:
+
+- `synapsor.change-set.v3`;
+- `synapsor.writeback-job.v3`;
+- `synapsor.execution-receipt.v3`.
+
+Each v3 object names one operation: `set_update`, `set_delete`, or
+`batch_insert`. It carries the same frozen-set authority:
+
+```json
+{
+  "max_rows": 10,
+  "row_count": 2,
+  "aggregate_bounds": [
+    { "column": "balance_cents", "measure": "before", "maximum": 20000, "actual": 15000 }
+  ],
+  "members": [
+    {
+      "primary_key": { "column": "id", "value": "INV-1" },
+      "expected_version": { "column": "version", "value": 1 },
+      "before_digest": "sha256:...",
+      "after_digest": "sha256:..."
+    }
+  ],
+  "set_digest": "sha256:..."
+}
+```
+
+The complete protocol fixtures live in [`fixtures/protocol`](../fixtures/protocol)
+and the JSON Schemas live in [`schemas`](../schemas). The execution receipt
+reports every `target_identity` and matching `member_effect`, plus receipt
+authority, set digest, exact affected count, safe status/error, and receipt
+hash. An applied result is invalid unless its affected count and member-effect
+count match the frozen identity count.
+
+`runner_ledger` may return `reconciliation_required` with an intent ID when a
+cross-database crash window prevents proof of commit. That is a terminal
+operator state, not a retry instruction or an `already_applied` guess.

package/docs/security-boundary.md

@@ -20,6 +20,13 @@ trusted context, evidence handles, query audit, local inspection, and
 proposal-first writes. Proposal workflows add full replay across evidence,
 approval, writeback receipts, and events.
 
+Prompt instructions and application validation are separate layers. Prompts
+can guide behavior but cannot supply authorization. A fixed, parameterized
+application tool can be a sound boundary for a small system; Runner adds a
+portable reviewed contract and a consistent proposal, approval, receipt,
+replay, and compensation lifecycle. See [Why Synapsor Over Prompt And
+Application Guardrails](why-synapsor-vs-app-guardrails.md).
+
 The model-facing MCP server exposes reviewed semantic tools such as
 `billing.inspect_invoice` and `billing.propose_late_fee_waiver`.
 

package/docs/troubleshooting-first-run.md

@@ -12,6 +12,26 @@ Use JSON for automation:
 npx -y -p @synapsor/runner synapsor-runner doctor --first-run --json
 ```
 
+## Smoke Proposal Missing From Another Runner
+
+What happened:
+
+`smoke call` returned a proposal id, but `proposals list --config ...` on a
+second Runner cannot find it.
+
+Fix:
+
+1. Verify `synapsor-runner --version` is `1.4.12` or later.
+2. Confirm both commands use a config whose
+   `storage.shared_postgres.mode` is `runtime_store` and whose `url_env` and
+   `schema` identify the same ledger.
+3. Run `store shared-postgres status --url-env <ENV> --schema <SCHEMA>`.
+
+In `runtime_store` mode, `--store` is not the authoritative ledger. Runner does
+not fall back to that SQLite path when shared Postgres is unavailable. Versions
+before `1.4.12` could orphan smoke-call artifacts locally; recreate that test
+proposal after upgrading.
+
 ## Docker Missing
 
 What happened:

package/docs/why-synapsor-vs-app-guardrails.md

@@ -0,0 +1,169 @@
+# Why Synapsor Over Prompt And Application Guardrails
+
+You can build a safe database tool in application code. The important question
+is not whether the code is custom or packaged. It is where authority lives and
+which safety properties are enforced outside the model.
+
+Synapsor Runner is useful when a narrow application function is no longer the
+whole requirement. It adds a shared, reviewable contract and an operational
+record around model-facing reads and writes: trusted context, evidence, query
+audit, proposals, approval outside MCP, guarded writeback, idempotency
+receipts, replay, and opt-in reviewed compensation.
+
+It does not make prompts trustworthy, prevent prompt injection, replace
+database permissions, or make an application compliant by itself.
+
+## Prompt Instructions Are Not A Security Boundary
+
+A system prompt can improve normal model behavior. It cannot grant or remove
+database authority. **Prompt-only enforcement is not a security boundary.** A
+confused or prompt-injected model can ignore an instruction, so a rule such as
+"only access this tenant" must be enforced by trusted code, database policy,
+or both.
+
+This is a general agent-security issue, not a hypothetical specific to one
+vendor:
+
+- [OWASP LLM01: Prompt Injection](https://genai.owasp.org/llmrisk/llm01-prompt-injection/)
+  describes direct and indirect prompt injection and recommends constrained
+  model behavior plus human approval for high-risk actions.
+- [General Analysis published a controlled Supabase MCP
+  demonstration](https://generalanalysis.com/blog/supabase-mcp-blog) in which
+  untrusted support-ticket content influenced an agent with broad database
+  access and exposed integration-token data. The demonstration disabled
+  read-only mode and used a privileged `service_role`; it was a controlled
+  security test, not evidence that every Supabase MCP deployment is
+  vulnerable.
+- [Supabase's defense-in-depth
+  response](https://supabase.com/blog/defense-in-depth-mcp) likewise recommends
+  a protective layer, least privilege, and avoiding direct production access.
+
+The lesson is not that a prompt can never be useful. It is that prompt text
+must not be the control that protects tenant scope, hidden fields, approval,
+or commit authority.
+
+## First Ask: Who Produces The SQL?
+
+### The model produces SQL
+
+If the model emits arbitrary SQL and application code decides whether to run
+it, that validator must correctly understand the database grammar,
+subqueries, functions, views, permissions, row scope, side effects, and future
+schema changes. A blocklist or regular expression is not an authorization
+system. This remains the `execute_sql` problem with an extra parser in front
+of it.
+
+Prefer fixed, parameterized statements selected by trusted application code,
+restricted database roles, views, and row-level security. Do not make the
+model the query planner for privileged production access.
+
+### Your application produces SQL
+
+If application code selects a fixed parameterized statement and exposes a
+narrow function such as `billing.inspect_invoice`, you have already made the
+most important architectural move: a semantic business tool replaces raw SQL.
+For a small application, that may be enough.
+
+The next question is whether you also need a consistent review and operations
+layer. Without one, each function must separately implement and preserve:
+
+- trusted tenant and principal binding;
+- read and write field allowlists;
+- evidence and query-audit records;
+- exact proposed diffs before a write;
+- approval identity and quorum outside the model;
+- conflict, transition, numeric, row-count, and aggregate guards;
+- idempotent execution and receipts;
+- activity search and replay;
+- bounded, separately approved compensation where reversibility is possible.
+
+Synapsor centralizes those mechanics in a contract and runtime instead of
+requiring every tool handler to invent them independently.
+
+## What Runner Adds
+
+| Concern | Prompt or one-off handler | Synapsor Runner |
+| --- | --- | --- |
+| Model-facing authority | Depends on instructions and handler design | Only reviewed semantic capabilities are served |
+| Tenant/principal scope | Often passed as model arguments or scattered checks | Bound from trusted environment or authenticated session context |
+| Data exposure | Handler-specific projection | Contract-reviewed visible fields and kept-out fields |
+| Risky writes | Handler may write during the tool call | MCP creates a proposal; approval and apply stay outside MCP |
+| Concurrency | Must be designed per handler | Version/conflict guards and frozen-set drift checks fail closed |
+| Retry behavior | Must be designed per handler | Idempotency keys and source or Runner-ledger receipts |
+| Investigation | Application logs | Evidence handles, query audit, proposal events, receipts, activity, and replay |
+| Undo | Usually another bespoke endpoint | Opt-in reviewed compensation for supported direct writes |
+| Review surface | Prompt, code, and policies may diverge | Portable canonical contract plus SQL-like DSL |
+
+This is structural enforcement only for traffic that actually passes through
+Runner and its reviewed capabilities. An unrestricted credential, a second raw
+SQL MCP server, or a bypass path in the application remains outside the
+boundary.
+
+The local SQLite or shared Postgres ledger is durable through Runner's
+supported interfaces, but a trusted host or database administrator can alter
+local state. Use Synapsor Cloud or your own tamper-evident retention and access
+controls when organizational audit requirements demand a stronger shared
+record.
+
+## Build Or Adopt
+
+Your own code is probably enough when all of these are true:
+
+- the agent is read-only or has one or two fixed, low-risk functions;
+- the application already derives tenant scope from authenticated server
+  state;
+- database roles, views, and row-level security provide the required floor;
+- you do not need approval history, evidence, receipts, replay, or reviewed
+  compensation;
+- one team owns every tool and can test every change consistently.
+
+Consider Runner when one or more of these are true:
+
+- agents can propose writes to customer, billing, support, health, finance,
+  or other consequential data;
+- tenant or principal isolation must not depend on model-supplied arguments;
+- a human or operator must approve some changes outside the agent loop;
+- retries, stale writes, bounded sets, or partial failures need explicit
+  fail-closed behavior;
+- investigators need to answer what the agent read, requested, approved, and
+  changed;
+- capabilities are growing across teams, agents, databases, or MCP clients;
+- the safety boundary needs to be reviewed in source control as one portable
+  contract.
+
+This is not a claim that the mechanics are impossible to build. It is a choice
+between maintaining them independently in every integration and adopting a
+tested contract/runtime that makes the same controls visible and repeatable.
+
+## Regulated And High-Consequence Data
+
+Health, finance, and other regulated workloads make the distinction more
+important, but Runner does not confer HIPAA, PCI DSS, SOC 2, or any other
+compliance status. A real deployment still needs the appropriate legal and
+organizational controls, least-privilege roles, encryption, retention,
+monitoring, incident response, vendor agreements, and human access policy.
+
+Runner can contribute technical evidence for that program: tenant-bound
+capabilities, explicit field projections, proposal/approval separation,
+signed operator identity where configured, guarded writeback receipts, and
+replay. Validate those controls with your security and compliance owners
+before using production regulated data.
+
+## Evaluate It Against Your Existing Layer
+
+1. Run the static MCP risk review against your current tools:
+
+   ```bash
+   npx -y @synapsor/runner audit ./tools-list.json
+   ```
+
+2. List every rule currently enforced only by a prompt.
+3. Identify whether the model or trusted code chooses SQL, tenant scope,
+   columns, predicates, approval, and commit timing.
+4. Pick one consequential staging workflow and compare its current evidence,
+   retry, conflict, approval, receipt, and investigation behavior with the
+   [own-database Runner flow](getting-started-own-database.md).
+
+Keep your existing database permissions either way. Runner shapes the
+agent-facing interface; it does not replace the database's own authorization
+boundary.

package/examples/runner-fleet/seed/postgres.sql

@@ -64,6 +64,7 @@ INSERT INTO public.invoices (id, tenant_id, status, late_fee_cents, waiver_reaso
   ('INV-ACME', 'acme', 'overdue', 2500, NULL, '2026-07-12T12:00:00Z'),
   ('INV-GLOBEX', 'globex', 'overdue', 3100, NULL, '2026-07-12T12:00:00Z'),
   ('INV-RATECO', 'rateco', 'overdue', 900, NULL, '2026-07-12T12:00:00Z'),
+  ('INV-SMOKE-CALL', 'acme', 'overdue', 2100, NULL, '2026-07-12T12:00:00Z'),
   ('INV-BATCH-A', 'acme', 'overdue', 1100, NULL, '2026-07-12T12:00:00Z'),
   ('INV-BATCH-B', 'acme', 'overdue', 1300, NULL, '2026-07-12T12:00:00Z'),
   ('INV-QUORUM-RACE', 'acme', 'overdue', 1400, NULL, '2026-07-12T12:00:00Z'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synapsor/runner",
-  "version": "1.4.0",
+  "version": "1.4.12",
   "description": "Stop giving AI agents execute_sql; expose reviewed Postgres/MySQL MCP actions with proposals, approval, writeback, and replay.",
   "license": "Apache-2.0",
   "type": "module",
@@ -35,6 +35,7 @@
     "AGENTS.md",
     "CHANGELOG.md",
     "CONTRIBUTING.md",
+    "SECURITY.md",
     "LICENSE",
     "NOTICE",
     "THREAT_MODEL.md",