@synapsor/runner 1.4.0 → 1.4.1

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 1.4.1 (prepared, not published)
+
+### Canonical Bounded-Set Digest Verification
+
+- Fixes contract-authored bounded-set proposals that could fail unchanged
+  apply with `SET_DIGEST_MISMATCH` after protocol parsing reordered aggregate
+  object fields.
+- Uses recursive canonical JSON key ordering for new member and set digests,
+  while narrowly accepting the deterministic raw representations emitted by
+  `1.4.0` so valid stored proposals remain applyable.
+- Keeps every frozen member, expected version, reviewed value, aggregate,
+  tenant guard, and atomic source check intact; malformed digests and genuine
+  source drift still fail closed.
+- Adds PostgreSQL/MySQL regression coverage for the exact DSL-to-contract path
+  under source-database and Runner-ledger receipt authority, plus independent
+  version, predicate, aggregate, writable-value, missing-member, and tenant
+  drift checks.
+- Ships the bounded-set guide and other linked public docs in the Runner
+  tarball, and fails package assembly when a shipped local Markdown link cannot
+  resolve.
+- Removes obsolete `0.1 preview` wording from the DSL package without changing
+  canonical Spec `spec_version: "0.1"`.
+- Adds a build-vs-adopt guide for teams already using prompts and custom
+  parameterized tools. It distinguishes behavioral instructions from
+  structural authorization, explains where SQL authority lives, and documents
+  the approval, receipt, replay, and compensation layer without claiming
+  prompt-injection prevention or compliance certification.
+- Stages `@synapsor/runner@1.4.1` and `@synapsor/dsl@1.4.1`;
+  `@synapsor/spec` remains `1.4.0` because the public contract schema did not
+  change. Nothing is published by this change.
+
 ## 1.4.0 (prepared, not published)
 
 ### Reviewed Reversible Change Sets

package/README.md

@@ -88,10 +88,26 @@ approve/reject prompt:
 - evidence, query audit, idempotency receipts, and replay preserve what was
   inspected, requested, approved, and applied.
 
-Runner supports bounded production deployments when its documented database,
-identity, ledger, backup, and operational controls are satisfied. It does not
-make arbitrary agent code, raw SQL tools, host infrastructure, or
-prompt-injection-prone clients safe by itself.
+Runner supports bounded deployments when its documented database, identity,
+ledger, backup, and operational controls are satisfied. It does not make raw
+SQL tools, host infrastructure, or prompt-injection-prone clients safe.
+
+## Why Not Just Use A Prompt And App Code?
+
+Prompt instructions can guide behavior, but prompt-only enforcement is not an
+authorization boundary. First ask who produces the SQL:
+
+- **The model produces SQL:** your validator must safely understand arbitrary
+  queries, scope, and side effects. That is `execute_sql` with an extra parser.
+- **Trusted app code produces fixed, parameterized SQL:** good. You have built
+  a semantic tool, and that may be enough for a small read-only application.
+
+Runner becomes useful when those tools also need one reviewed contract for
+trusted tenant scope, field controls, evidence, approval outside MCP, guarded
+and idempotent writeback, receipts, replay, and reviewed compensation. Use your
+own code when you do not need that lifecycle. Read the [full build-vs-adopt
+guide](docs/why-synapsor-vs-app-guardrails.md) for the decision table, public
+incident evidence, and regulated-data boundaries.
 
 ## Connect A Staging Database
 
@@ -109,11 +125,9 @@ creates trusted context, generates reviewed capabilities, previews the MCP tool
 surface, and prints the next smoke and serve commands. It stores environment
 variable names, not connection strings.
 
-The interesting part of the generated configuration is the capability entry: a
-reviewed, tenant-scoped read with an explicit column allowlist and required
-evidence. The storage, source, and trusted-context wiring around it (including
-statement timeouts) is generated for you; the full file is in the
-[own-database guide](docs/getting-started-own-database.md).
+The generated capability is a tenant-scoped read with an explicit column
+allowlist and required evidence. See the [own-database
+guide](docs/getting-started-own-database.md) for the full configuration.
 
 ```json
 {
@@ -174,19 +188,11 @@ trust boundaries, covered threats, non-goals, and required operator controls.
 - MCP proposal, evidence, and replay handles are references rather than bearer
   authority: resource reads re-check the owning tenant and principal against
   the current trusted session.
-- `corepack pnpm test:live-apply` runs disposable Postgres and MySQL scenarios.
-  It proves source rows stay unchanged before approval, guarded writeback
-  applies once, idempotent retry does not duplicate the effect, and a stale row
-  returns a conflict.
-- `corepack pnpm test:guarded-crud` proves native single-row INSERT, UPDATE,
-  and DELETE across both databases and all receipt modes, including the
-  zero-source-schema Runner-ledger path and fail-closed reconciliation.
-- `corepack pnpm test:bounded-set` proves proposal-time cap and aggregate
-  rejection, frozen-set drift checks, all-or-nothing set UPDATE/DELETE and
-  batch INSERT, delete-side-effect refusal, exact receipts, and 1/10/100-row
-  bounds on disposable PostgreSQL and MySQL.
-- `corepack pnpm test:reversible` proves approval, conflict guards, redaction,
-  receipts, and replay on PostgreSQL and MySQL.
+- `test:live-apply`, `test:guarded-crud`, `test:bounded-set`, and
+  `test:reversible` run disposable PostgreSQL/MySQL scenarios. They prove no
+  pre-approval mutation, guarded single-row CRUD, idempotent retry,
+  fail-closed conflicts, bounded atomic sets, exact receipts, and reviewed
+  compensation.
 - The C++/Cloud round-trip verifier exports normalized contracts, validates
   them with `@synapsor/spec`, and loads them in Runner. The shared contract and
   verification commands are documented in [Conformance](docs/conformance.md).
@@ -198,12 +204,9 @@ See [Security Boundary](docs/security-boundary.md) and
 
 ## Operate The Approval Loop
 
-Reviewed policies can combine a per-proposal threshold with daily count and
-total ceilings. Exceeding a ceiling routes that proposal to human review; it
-never auto-applies. Operators can apply the bounded approved queue independently
-with `apply --all-approved --yes`, inspect Prometheus counters with `metrics
-show`, and consume safe newline-delimited JSON outcome logs from stderr. Signed
-operator keys can enforce contract reviewer roles and separate apply roles.
+Reviewed policies combine per-proposal and daily ceilings; exceeding one routes
+the proposal to human review. Operators use `apply --all-approved --yes`,
+Prometheus metrics, structured logs, and optional signed reviewer/apply roles.
 Shared Postgres ledger mirror mode is available for bounded operator handoffs,
 and `storage.shared_postgres.mode = "runtime_store"` lets MCP serving use
 Postgres as the primary proposal/evidence/replay store with bounded CLI
@@ -230,11 +233,10 @@ dead-letter, and rolling-upgrade rules are in
 | `@synapsor/spec` | Canonical portable contracts for contexts, capabilities, workflows, evidence, proposals, receipts, and replay. |
 | `@synapsor/dsl` | SQL-like authoring that compiles contexts, capabilities, and workflow declarations into canonical contract JSON. |
 
-Runner executes locally. The spec is the portable contract shared by Runner
-and Cloud/C++. The DSL gives that contract a reviewable source format. Start
-with [Capability Authoring](docs/capability-authoring.md). Use `.synapsor.sql`
-for DSL source files when you want editors to provide generic SQL highlighting;
-legacy `.synapsor` files remain supported and produce the same contract JSON.
+Runner executes locally. The spec is shared by Runner and Cloud/C++; the DSL
+is its reviewable source format. Start with [Capability
+Authoring](docs/capability-authoring.md). Use `.synapsor.sql` for generic SQL
+highlighting; legacy `.synapsor` files produce the same contract JSON.
 
 Use the [DSL Reference](docs/dsl-reference.md) for exact authoring grammar and
 the [Runner Config Reference](docs/runner-config-reference.md) for every wiring

package/SECURITY.md

@@ -0,0 +1,11 @@
+# Security Policy
+
+Report security issues privately to security@synapsor.ai.
+
+Do not include production credentials, customer data, or full source rows in bug reports. Include runner version, job id, proposal id, source id, engine, safe error code, and redacted logs where possible.
+
+## Supported security scope
+
+The v0.1 runner protects the local writeback boundary for approved structured jobs. It does not make the hosted Synapsor control plane self-hosted, and it does not provide HA, compliance certification, or a general database proxy.
+
+See `docs/threat-model.md` for detailed trust boundaries, covered threats, non-goals, and release blockers.

package/dist/runner.mjs

@@ -3,7 +3,7 @@
 // apps/runner/src/cli.ts
 import fs5 from "node:fs/promises";
 import { spawn, spawnSync } from "node:child_process";
-import crypto8 from "node:crypto";
+import crypto9 from "node:crypto";
 import net from "node:net";
 import os from "node:os";
 import path5 from "node:path";
@@ -12,7 +12,42 @@ import readline from "node:readline/promises";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 // packages/protocol/src/index.ts
+import crypto2 from "node:crypto";
 import { z } from "zod";
+function canonicalJsonStringify(input) {
+  return JSON.stringify(canonicalJsonValue(input, /* @__PURE__ */ new Set()));
+}
+function canonicalJsonDigest(input) {
+  return `sha256:${crypto2.createHash("sha256").update(canonicalJsonStringify(input)).digest("hex")}`;
+}
+function canonicalJsonValue(input, ancestors) {
+  if (input === null || typeof input === "string" || typeof input === "boolean") return input;
+  if (typeof input === "number") {
+    if (!Number.isFinite(input)) throw new TypeError("canonical JSON accepts only finite numbers");
+    return Object.is(input, -0) ? 0 : input;
+  }
+  if (Array.isArray(input)) {
+    if (ancestors.has(input)) throw new TypeError("canonical JSON does not accept circular values");
+    ancestors.add(input);
+    const output2 = input.map((item) => canonicalJsonValue(item, ancestors));
+    ancestors.delete(input);
+    return output2;
+  }
+  if (typeof input !== "object" || input === void 0) throw new TypeError("canonical JSON accepts only JSON values");
+  const record = input;
+  const prototype = Object.getPrototypeOf(record);
+  if (prototype !== Object.prototype && prototype !== null) throw new TypeError("canonical JSON accepts only plain objects");
+  if (ancestors.has(record)) throw new TypeError("canonical JSON does not accept circular values");
+  ancestors.add(record);
+  const output = {};
+  for (const key of Object.keys(record).sort()) {
+    const value = record[key];
+    if (value === void 0) throw new TypeError("canonical JSON does not accept undefined values");
+    output[key] = canonicalJsonValue(value, ancestors);
+  }
+  ancestors.delete(record);
+  return output;
+}
 var scalar = z.union([z.string(), z.number(), z.boolean(), z.null()]);
 var scalarMap = z.record(scalar).refine((value) => Object.keys(value).length > 0, "object must not be empty");
 var boundedScalarRecord = z.record(scalar).refine((value) => Object.keys(value).length <= 256, "object exceeds 256 fields");
@@ -2755,7 +2790,7 @@ function isRecord(value) {
 }
 
 // packages/mcp-server/src/index.ts
-import crypto4 from "node:crypto";
+import crypto5 from "node:crypto";
 import fs2 from "node:fs";
 import { createServer } from "node:http";
 import { createServer as createHttpsServer } from "node:https";
@@ -2766,11 +2801,11 @@ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/
 import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 
 // packages/postgres/src/index.ts
-import crypto3 from "node:crypto";
+import crypto4 from "node:crypto";
 import { Pool, types as pgTypes } from "pg";
 
 // packages/worker-core/src/index.ts
-import crypto2 from "node:crypto";
+import crypto3 from "node:crypto";
 
 // packages/worker-core/src/mcp-audit.ts
 var MCP_AUDIT_DISCLAIMER = "This is a static risk review, not proof that an MCP server is secure.";
@@ -3308,21 +3343,21 @@ function assertFrozenSetJobIntegrity(job) {
       if (member.before[job.target.tenant_guard.column] !== job.target.tenant_guard.value) throw new Error("SET_TENANT_GUARD_MISMATCH");
       const expectedAfter = { ...member.before, ...job.patch, [job.version_advance.column]: member.expected_version.value + 1 };
       if (!recordsEqual(member.after, expectedAfter)) throw new Error("SET_AFTER_STATE_MISMATCH");
-      if (member.before_digest !== reconciliationDigest({ primary_key: member.primary_key.value, before: member.before })) throw new Error("SET_BEFORE_DIGEST_MISMATCH");
-      if (member.after_digest !== reconciliationDigest({ primary_key: member.primary_key.value, after: member.after })) throw new Error("SET_AFTER_DIGEST_MISMATCH");
+      if (!reviewedDigestMatches(member.before_digest, { primary_key: member.primary_key.value, before: member.before })) throw new Error("SET_BEFORE_DIGEST_MISMATCH");
+      if (!reviewedDigestMatches(member.after_digest, { primary_key: member.primary_key.value, after: member.after })) throw new Error("SET_AFTER_DIGEST_MISMATCH");
     } else if (job.operation === "set_delete") {
       if (!member.expected_version || member.before[member.expected_version.column] !== member.expected_version.value) throw new Error("SET_VERSION_GUARD_MISMATCH");
       if (member.before[job.target.tenant_guard.column] !== job.target.tenant_guard.value) throw new Error("SET_TENANT_GUARD_MISMATCH");
       if (Object.keys(member.after).length !== 0) throw new Error("SET_DELETE_PATCH_FORBIDDEN");
-      if (member.before_digest !== reconciliationDigest({ primary_key: member.primary_key.value, before: member.before })) throw new Error("SET_BEFORE_DIGEST_MISMATCH");
-      if (member.tombstone_digest !== reconciliationDigest({ primary_key: member.primary_key.value, expected_version: member.expected_version })) throw new Error("SET_TOMBSTONE_DIGEST_MISMATCH");
+      if (!reviewedDigestMatches(member.before_digest, { primary_key: member.primary_key.value, before: member.before })) throw new Error("SET_BEFORE_DIGEST_MISMATCH");
+      if (!reviewedDigestMatches(member.tombstone_digest, { primary_key: member.primary_key.value, expected_version: member.expected_version })) throw new Error("SET_TOMBSTONE_DIGEST_MISMATCH");
     } else {
       const components = member.deduplication?.components ?? [];
       const primary = components.find((component) => component.column === job.target.primary_key.column);
       const tenant = components.find((component) => component.column === job.target.tenant_guard.column);
       if (!primary || primary.value !== member.primary_key.value || !tenant || tenant.source !== "trusted_tenant" || tenant.value !== job.target.tenant_guard.value) throw new Error("BATCH_DEDUP_REQUIRED");
       if (member.after[job.target.primary_key.column] !== member.primary_key.value || member.after[job.target.tenant_guard.column] !== job.target.tenant_guard.value) throw new Error("BATCH_IDENTITY_MISMATCH");
-      if (member.after_digest !== reconciliationDigest({ primary_key: member.primary_key.value, after: member.after })) throw new Error("SET_AFTER_DIGEST_MISMATCH");
+      if (!reviewedDigestMatches(member.after_digest, { primary_key: member.primary_key.value, after: member.after })) throw new Error("SET_AFTER_DIGEST_MISMATCH");
     }
   }
   for (const bound of set.aggregate_bounds) {
@@ -3333,8 +3368,24 @@ function assertFrozenSetJobIntegrity(job) {
     }, 0);
     if (actual !== bound.actual || actual > bound.maximum) throw new Error("SET_AGGREGATE_BOUND_MISMATCH");
   }
-  const expectedSetDigest = reconciliationDigest({ operation: job.operation, members: set.members, aggregate_bounds: set.aggregate_bounds });
-  if (set.set_digest !== expectedSetDigest) throw new Error("SET_DIGEST_MISMATCH");
+  const setMaterial = { operation: job.operation, members: set.members, aggregate_bounds: set.aggregate_bounds };
+  const legacyContractMaterial = {
+    operation: job.operation,
+    members: set.members,
+    aggregate_bounds: set.aggregate_bounds.map((bound) => ({
+      column: bound.column,
+      maximum: bound.maximum,
+      measure: bound.measure,
+      actual: bound.actual
+    }))
+  };
+  if (!reviewedDigestMatches(set.set_digest, setMaterial, legacyContractMaterial)) throw new Error("SET_DIGEST_MISMATCH");
+}
+function reviewedDigestMatches(actual, current, legacyContract) {
+  if (!actual) return false;
+  const expected = /* @__PURE__ */ new Set([canonicalJsonDigest(current), reconciliationDigest(current)]);
+  if (legacyContract) expected.add(reconciliationDigest(legacyContract));
+  return expected.has(actual);
 }
 function recordValuesMatch(actual, expected, valuesEqual) {
   return Object.entries(expected).every(([column, value]) => valuesEqual(actual[column], value));
@@ -3352,7 +3403,7 @@ function asScalar(value) {
   return value == null || typeof value === "string" || typeof value === "number" || typeof value === "boolean" ? value : String(value);
 }
 function reconciliationDigest(value) {
-  return `sha256:${crypto2.createHash("sha256").update(JSON.stringify(value)).digest("hex")}`;
+  return `sha256:${crypto3.createHash("sha256").update(JSON.stringify(value)).digest("hex")}`;
 }
 function loadConfig(env = process.env) {
   const engine = (env.SYNAPSOR_ENGINE || "postgres").toLowerCase();
@@ -3606,7 +3657,7 @@ function scalar2(value) {
   return value == null || typeof value === "string" || typeof value === "number" || typeof value === "boolean" ? value : String(value);
 }
 function digest(value) {
-  return `sha256:${crypto3.createHash("sha256").update(JSON.stringify(value)).digest("hex")}`;
+  return `sha256:${crypto4.createHash("sha256").update(JSON.stringify(value)).digest("hex")}`;
 }
 function reconciliationProjection(job) {
   const columns = /* @__PURE__ */ new Set([job.target.primary_key.column, job.target.tenant_guard.column, ...job.allowed_columns]);
@@ -10897,7 +10948,7 @@ async function handleStreamableHttpMcpRequest(input) {
     }
     let session;
     const transport = new StreamableHTTPServerTransport({
-      sessionIdGenerator: () => crypto4.randomUUID(),
+      sessionIdGenerator: () => crypto5.randomUUID(),
       onsessioninitialized: (newSessionId) => {
         if (session) {
           session.sessionId = newSessionId;
@@ -11038,7 +11089,7 @@ function validBearerToken(header, expected) {
   const actual = header.slice("Bearer ".length);
   const actualBuffer = Buffer.from(actual);
   const expectedBuffer = Buffer.from(expected);
-  return actualBuffer.length === expectedBuffer.length && crypto4.timingSafeEqual(actualBuffer, expectedBuffer);
+  return actualBuffer.length === expectedBuffer.length && crypto5.timingSafeEqual(actualBuffer, expectedBuffer);
 }
 function resolveMetricsEndpointAccess(config, env, host) {
   if (config.metrics?.enabled !== true) return { enabled: false };
@@ -11178,7 +11229,7 @@ async function checkRunnerReadiness(config, env = process.env, timeoutMs = 3e3)
         const table = `${quotePostgresIdentifier(shared.schema ?? "synapsor_runner")}.ledger_entries`;
         await client.query(
           `INSERT INTO ${table} (entry_key, kind, payload_json) VALUES ($1, 'readiness_probe', '{}'::jsonb)`,
-          [`readiness:${crypto4.randomUUID()}`]
+          [`readiness:${crypto5.randomUUID()}`]
         );
         await client.query("ROLLBACK");
       } catch (error) {
@@ -11274,7 +11325,7 @@ function bearerToken(header) {
   return token || void 0;
 }
 function tokenFingerprint(token) {
-  return `sha256:${crypto4.createHash("sha256").update(token).digest("hex")}`;
+  return `sha256:${crypto5.createHash("sha256").update(token).digest("hex")}`;
 }
 function safeSessionClaim(value) {
   if (typeof value !== "string") return void 0;
@@ -11338,7 +11389,7 @@ function toolNameExposureMap(canonicalNames, style) {
   return exposedByCanonical;
 }
 function shortToolHash(value) {
-  return crypto4.createHash("sha256").update(value).digest("hex").slice(0, 8);
+  return crypto5.createHash("sha256").update(value).digest("hex").slice(0, 8);
 }
 function setCorsHeaders(response, corsOrigin) {
   if (corsOrigin) {
@@ -12339,7 +12390,7 @@ function buildBoundedSetChangeSet(input) {
       primary_key: { column: input.capability.target.primary_key, value: primary.value },
       before: {},
       after,
-      after_digest: hashJson({ primary_key: primary.value, after }),
+      after_digest: canonicalJsonDigest({ primary_key: primary.value, after }),
       deduplication
     };
   }) : input.currentRows.map((rawRow) => {
@@ -12354,8 +12405,8 @@ function buildBoundedSetChangeSet(input) {
         expected_version: expectedVersion,
         before,
         after: {},
-        before_digest: hashJson({ primary_key: primaryValue, before }),
-        tombstone_digest: hashJson({ primary_key: primaryValue, expected_version: expectedVersion })
+        before_digest: canonicalJsonDigest({ primary_key: primaryValue, before }),
+        tombstone_digest: canonicalJsonDigest({ primary_key: primaryValue, expected_version: expectedVersion })
       };
     }
     const after = { ...before, ...input.patch };
@@ -12369,15 +12420,20 @@ function buildBoundedSetChangeSet(input) {
       expected_version: expectedVersion,
       before,
       after,
-      before_digest: hashJson({ primary_key: primaryValue, before }),
-      after_digest: hashJson({ primary_key: primaryValue, after })
+      before_digest: canonicalJsonDigest({ primary_key: primaryValue, before }),
+      after_digest: canonicalJsonDigest({ primary_key: primaryValue, after })
     };
   });
   const members = rawMembers.sort((left, right) => JSON.stringify(left.primary_key.value).localeCompare(JSON.stringify(right.primary_key.value)));
   if (new Set(members.map((member) => JSON.stringify(member.primary_key.value))).size !== members.length) {
     throw new McpRuntimeError("SET_IDENTITY_NOT_UNIQUE", "Every frozen set member must have a unique primary-key identity.");
   }
-  const aggregateBounds = operation.aggregate_bounds.map((bound) => ({ ...bound, actual: aggregateValue(members, bound) }));
+  const aggregateBounds = operation.aggregate_bounds.map((bound) => ({
+    column: bound.column,
+    measure: bound.measure,
+    maximum: bound.maximum,
+    actual: aggregateValue(members, bound)
+  }));
   for (const bound of aggregateBounds) {
     if (bound.actual > bound.maximum) throw new McpRuntimeError("SET_AGGREGATE_BOUND_EXCEEDED", `${bound.measure} aggregate for ${bound.column} exceeds the reviewed maximum ${bound.maximum}.`);
   }
@@ -12386,7 +12442,7 @@ function buildBoundedSetChangeSet(input) {
     row_count: members.length,
     aggregate_bounds: aggregateBounds,
     members,
-    set_digest: hashJson({ operation: kind, members, aggregate_bounds: aggregateBounds })
+    set_digest: canonicalJsonDigest({ operation: kind, members, aggregate_bounds: aggregateBounds })
   };
   const approvalMode = input.capability.approval?.mode === "operator" ? "operator" : "human";
   const proposalCore = {
@@ -12512,7 +12568,7 @@ var RuntimeRateLimiter = class {
     if (this.sharedPool && this.sharedSchema) {
       await this.migration;
       const table = `${quotePostgresIdentifier(this.sharedSchema)}.rate_limit_buckets`;
-      const bucketKey = crypto4.createHash("sha256").update(`${context.tenant_id}\0${capability}`).digest("hex");
+      const bucketKey = crypto5.createHash("sha256").update(`${context.tenant_id}\0${capability}`).digest("hex");
       const result = await this.sharedPool.query(
         `INSERT INTO ${table} AS bucket (bucket_key, window_start, request_count, rejected_count)
          VALUES ($1, $2, 1, 0)
@@ -13102,10 +13158,10 @@ function proposalAlreadyExists(existing) {
   );
 }
 function stableId(prefix, input) {
-  return `${prefix}_${crypto4.createHash("sha256").update(JSON.stringify(input)).digest("hex").slice(0, 20)}`;
+  return `${prefix}_${crypto5.createHash("sha256").update(JSON.stringify(input)).digest("hex").slice(0, 20)}`;
 }
 function hashJson(input) {
-  return `sha256:${crypto4.createHash("sha256").update(JSON.stringify(input)).digest("hex")}`;
+  return `sha256:${crypto5.createHash("sha256").update(JSON.stringify(input)).digest("hex")}`;
 }
 function isRecord5(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -13127,7 +13183,7 @@ function toolErrorPayload(error) {
 }
 
 // packages/mysql/src/index.ts
-import crypto5 from "node:crypto";
+import crypto6 from "node:crypto";
 import mysql2 from "mysql2/promise";
 var mysqlReceiptMigration = `CREATE TABLE IF NOT EXISTS synapsor_writeback_receipts (
   idempotency_key varchar(255) PRIMARY KEY,
@@ -13241,7 +13297,7 @@ function scalar4(value) {
   return value == null || typeof value === "string" || typeof value === "number" || typeof value === "boolean" ? value : String(value);
 }
 function digest2(value) {
-  return `sha256:${crypto5.createHash("sha256").update(JSON.stringify(value)).digest("hex")}`;
+  return `sha256:${crypto6.createHash("sha256").update(JSON.stringify(value)).digest("hex")}`;
 }
 function resultHash2(job, status, version) {
   return digest2({ job_id: job.job_id, status, version });
@@ -15621,7 +15677,7 @@ function parseList(value) {
 }
 function unsupported(item, blockKind) {
   if (/ROOT\s+EXTERNAL|JOIN\s+EXTERNAL|RETURN\s+ANSWER|AUTO\s+BRANCH|AUTO\s+MERGE/i.test(item.text)) {
-    throw dslError(item.line, 1, "UNSUPPORTED_PREVIEW_SYNTAX", `${blockKind} clause is not supported by @synapsor/dsl 0.1 preview: ${item.text}`);
+    throw dslError(item.line, 1, "UNSUPPORTED_PREVIEW_SYNTAX", `${blockKind} clause is not supported by the current @synapsor/dsl grammar: ${item.text}`);
   }
   throw dslError(item.line, 1, "UNSUPPORTED_DSL_CLAUSE", `unsupported ${blockKind} clause: ${item.text}`);
 }
@@ -15630,7 +15686,7 @@ function dslError(line, column, code, message2) {
 }
 
 // apps/runner/src/local-ui.ts
-import crypto6 from "node:crypto";
+import crypto7 from "node:crypto";
 import fs3 from "node:fs/promises";
 import { createServer as createServer2 } from "node:http";
 import path3 from "node:path";
@@ -15641,8 +15697,8 @@ async function startLocalUiServer(options = {}) {
   }
   const configPath = path3.resolve(options.configPath ?? "synapsor.runner.json");
   const storePath = path3.resolve(options.storePath ?? "./.synapsor/local.db");
-  const token = options.token ?? crypto6.randomBytes(24).toString("base64url");
-  const csrfToken = options.csrfToken ?? crypto6.randomBytes(24).toString("base64url");
+  const token = options.token ?? crypto7.randomBytes(24).toString("base64url");
+  const csrfToken = options.csrfToken ?? crypto7.randomBytes(24).toString("base64url");
   const storeAccess = options.storeAccess ?? localStoreAccess(storePath);
   const server = createServer2(async (request, response) => {
     try {
@@ -16606,7 +16662,7 @@ function stringOrDefault(value, fallback) {
 }
 
 // apps/runner/src/operator-identity.ts
-import crypto7 from "node:crypto";
+import crypto8 from "node:crypto";
 import fs4 from "node:fs/promises";
 import path4 from "node:path";
 async function resolveOperatorIdentity(input) {
@@ -16692,8 +16748,8 @@ async function resolveOperatorIdentity(input) {
   const decision = operatorDecision(input, subject);
   const canonical = stableJson(decision);
   const decisionHash = sha2562(canonical);
-  const signature = crypto7.sign("sha256", Buffer.from(canonical), privateKey).toString("base64url");
-  if (!crypto7.verify("sha256", Buffer.from(canonical), publicKey, Buffer.from(signature, "base64url"))) {
+  const signature = crypto8.sign("sha256", Buffer.from(canonical), privateKey).toString("base64url");
+  if (!crypto8.verify("sha256", Buffer.from(canonical), publicKey, Buffer.from(signature, "base64url"))) {
     throw new Error(`private key does not match the reviewed public key for operator ${subject}`);
   }
   const core = {
@@ -16717,7 +16773,7 @@ function verifyJwtOperatorProof(proof, attestationSecret) {
   const expected = hmacAttestation(unsigned, attestationSecret);
   const actualBuffer = Buffer.from(signature);
   const expectedBuffer = Buffer.from(expected);
-  if (actualBuffer.length !== expectedBuffer.length || !crypto7.timingSafeEqual(actualBuffer, expectedBuffer)) return false;
+  if (actualBuffer.length !== expectedBuffer.length || !crypto8.timingSafeEqual(actualBuffer, expectedBuffer)) return false;
   const core = { ...unsigned, signature };
   return proof.integrity_hash === sha2562(stableJson(core));
 }
@@ -16727,7 +16783,7 @@ function verifySignedOperatorProof(proof, publicKey) {
   if (proof.decision_hash !== sha2562(canonical)) return false;
   const { integrity_hash: _integrity, ...core } = proof;
   if (proof.integrity_hash !== sha2562(stableJson(core))) return false;
-  return crypto7.verify("sha256", Buffer.from(canonical), publicKey, Buffer.from(proof.signature, "base64url"));
+  return crypto8.verify("sha256", Buffer.from(canonical), publicKey, Buffer.from(proof.signature, "base64url"));
 }
 function operatorDecision(input, subject) {
   return {
@@ -16781,10 +16837,10 @@ function rolesFromClaim(value) {
   return [...new Set(roles)].sort();
 }
 function hmacAttestation(value, secret) {
-  return crypto7.createHmac("sha256", secret).update(stableJson(value)).digest("base64url");
+  return crypto8.createHmac("sha256", secret).update(stableJson(value)).digest("base64url");
 }
 function sha2562(value) {
-  return `sha256:${crypto7.createHash("sha256").update(value).digest("hex")}`;
+  return `sha256:${crypto8.createHash("sha256").update(value).digest("hex")}`;
 }
 function stableJson(value) {
   if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
@@ -16883,7 +16939,7 @@ function isRecord7(value) {
 // apps/runner/package.json
 var package_default = {
   name: "@synapsor/runner",
-  version: "1.4.0",
+  version: "1.4.1",
   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",
@@ -16918,6 +16974,7 @@ var package_default = {
     "AGENTS.md",
     "CHANGELOG.md",
     "CONTRIBUTING.md",
+    "SECURITY.md",
     "LICENSE",
     "NOTICE",
     "THREAT_MODEL.md",
@@ -16972,8 +17029,8 @@ var package_default = {
 // packages/dsl/package.json
 var package_default2 = {
   name: "@synapsor/dsl",
-  version: "1.4.0",
-  description: "Preview SQL-like Synapsor authoring DSL compiler for canonical @synapsor/spec contracts.",
+  version: "1.4.1",
+  description: "SQL-like Synapsor authoring frontend for canonical @synapsor/spec contracts.",
   license: "Apache-2.0",
   type: "module",
   main: "dist/index.js",
@@ -20374,8 +20431,8 @@ function trustedCliContext(config, capability, env) {
   return { tenant_id: tenant, principal };
 }
 function createCompensationProposal(input) {
-  const proposalId = `wrp_revert_${crypto8.randomBytes(10).toString("hex")}`;
-  const evidenceId = `ev_revert_${crypto8.randomBytes(10).toString("hex")}`;
+  const proposalId = `wrp_revert_${crypto9.randomBytes(10).toString("hex")}`;
+  const evidenceId = `ev_revert_${crypto9.randomBytes(10).toString("hex")}`;
   const createdAt = (/* @__PURE__ */ new Date()).toISOString();
   const one = input.inverse.members.length === 1 ? input.inverse.members[0] : void 0;
   const before = one ? one.expected_state : { row_count: input.inverse.members.length };
@@ -20845,7 +20902,7 @@ function executorConfig(config, executorName) {
   throw new Error(`executor ${executorName} has unsupported type`);
 }
 function signHandlerRequestBody(body, secret) {
-  return `sha256=${crypto8.createHmac("sha256", secret).update(body).digest("hex")}`;
+  return `sha256=${crypto9.createHmac("sha256", secret).update(body).digest("hex")}`;
 }
 async function applyHttpHandlerProposal(input) {
   const duplicate = duplicateHandlerReceipt(input.store, input.proposalId);
@@ -21050,7 +21107,7 @@ function buildHandlerReceipt(input) {
   };
 }
 function hashReceipt(input) {
-  return `sha256:${crypto8.createHash("sha256").update(JSON.stringify(input)).digest("hex")}`;
+  return `sha256:${crypto9.createHash("sha256").update(JSON.stringify(input)).digest("hex")}`;
 }
 function formatApplyResult(job, result, dryRun, storePath) {
   const status = writebackResultStatus(result);
@@ -22113,7 +22170,7 @@ function reconciliationReceipt(intent, observation, outcome, runnerId, reason) {
     };
     return {
       ...base2,
-      receipt_hash: `sha256:${crypto8.createHash("sha256").update(JSON.stringify(base2)).digest("hex")}`
+      receipt_hash: `sha256:${crypto9.createHash("sha256").update(JSON.stringify(base2)).digest("hex")}`
     };
   }
   if (job.protocol_version !== protocolVersions.normalizedWritebackJobV2) throw new Error("single-row reconciliation requires a writeback-job v2");
@@ -22140,7 +22197,7 @@ function reconciliationReceipt(intent, observation, outcome, runnerId, reason) {
   };
   return {
     ...base,
-    receipt_hash: `sha256:${crypto8.createHash("sha256").update(JSON.stringify(base)).digest("hex")}`
+    receipt_hash: `sha256:${crypto9.createHash("sha256").update(JSON.stringify(base)).digest("hex")}`
   };
 }
 function publicWritebackIntent(intent) {
@@ -25616,7 +25673,7 @@ no rows deleted
         await pool.query(`DELETE FROM ${qualified} WHERE entry_key = ANY($1::text[])`, [archivedEntries.map((entry) => entry.entry_key)]);
       }
       const retentionEntry = {
-        entry_key: `retention:${crypto8.randomUUID()}`,
+        entry_key: `retention:${crypto9.randomUUID()}`,
         kind: "retention_event",
         payload: {
           cutoff,
@@ -27647,7 +27704,7 @@ function toExecutionReceipt(job, result, dryRun) {
   const affectedRows2 = result.affected_rows ?? 0;
   const terminalStatus = result.status === "applied" && !dryRun && affectedRows2 === 0 ? "already_applied" : result.status;
   const previousVersion = job.conflict_guard.kind === "version_column" ? job.conflict_guard.expected_value : void 0;
-  const receiptHash = typeof result.result_hash === "string" && result.result_hash.startsWith("sha256:") ? result.result_hash : `sha256:${crypto8.createHash("sha256").update(JSON.stringify({
+  const receiptHash = typeof result.result_hash === "string" && result.result_hash.startsWith("sha256:") ? result.result_hash : `sha256:${crypto9.createHash("sha256").update(JSON.stringify({
     job_id: job.job_id,
     status: terminalStatus,
     affected_rows: affectedRows2,

package/docs/README.md

@@ -24,6 +24,10 @@ no-database demo, wire your database, then read deeper concepts.
 ## 02 Why Raw SQL Is Dangerous
 
 - [Security Boundary](security-boundary.md): what the model can and cannot see.
+- [Why Synapsor Over Prompt And Application
+  Guardrails](why-synapsor-vs-app-guardrails.md): where SQL authority lives,
+  what a hand-built semantic tool already gets right, and when the shared
+  contract, approval, receipt, and replay layer is worth adopting.
 - [MCP Audit](mcp-audit.md): static review for risky database MCP tools such as
   `execute_sql`, broad query tools, model-controlled tenant filters, or
   model-facing approval/commit tools.

package/docs/benchmarks/bounded-set-local.md

@@ -0,0 +1,27 @@
+# Bounded Set Local Measurements
+
+These measurements are test evidence, not throughput claims or capacity
+guidance. They record one run of `corepack pnpm test:bounded-set` on 2026-07-13
+using synthetic rows and disposable local Docker databases.
+
+Environment:
+
+- Linux laptop, Intel Core i7-13800H, 20 logical CPUs, 30 GiB RAM;
+- Node.js 22.22.2 and pnpm 10.14.0;
+- Docker 29.5.2;
+- PostgreSQL 16 and MySQL 8 containers;
+- source-database receipt authority with an administrator-precreated receipt
+  table;
+- one sequential set UPDATE per measurement, including connection setup,
+  source receipt, lock/preflight, transaction, and exact receipt generation.
+
+| Engine | 1 row | 10 rows | 100 rows |
+| --- | ---: | ---: | ---: |
+| PostgreSQL | 30.42 ms | 53.88 ms | 154.90 ms |
+| MySQL | 25.30 ms | 53.91 ms | 163.20 ms |
+
+These figures are not portable across hardware, network topology, source
+indexes, lock contention, triggers, database configuration, or receipt mode.
+The claim supported by this gate is only that execution stays bounded and the
+hard 100-row ceiling is exercised on both adapters. Operators must benchmark
+their own reviewed contracts and database topology.

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/release-notes.md

@@ -10,6 +10,29 @@ 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.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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synapsor/runner",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "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",