@synapsor/runner 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -4,6 +4,23 @@
 
 No unreleased changes yet.
 
+## 0.1.7
+
+### Contract Writeback Resolution
+
+- Fixes contract-authored proposal capabilities loaded through `contracts: []`
+  so `apply` resolves the same reviewed capability catalog used by serve,
+  tools, propose, and doctor.
+- Rejects duplicate capability names across embedded runner config and
+  referenced contracts instead of silently shadowing a safety contract.
+- Preserves canonical contract writeback modes, including direct SQL,
+  app-owned handler, cloud-worker, and proposal-only/no-local-writeback
+  semantics.
+- Fails broken applyable writeback definitions at propose/doctor time before a
+  human approves a proposal.
+- Creates local store parent directories automatically and trims env-derived
+  URLs, tokens, and trusted context values before use.
+
 ## 0.1.5
 
 ### Contract Authoring Front Door

package/README.md

@@ -277,9 +277,16 @@ synapsor-runner dsl compile ./contract.synapsor --out ./synapsor.contract.json
 synapsor-runner contract validate ./synapsor.contract.json
 synapsor-runner contract bundle ./synapsor.contract.json --out ./synapsor-runner-bundle
 synapsor-runner cloud push ./synapsor.contract.json --dry-run
+cd ./synapsor-runner-bundle
+cp .env.example .env  # fill in and export your read-only database values
 synapsor-runner mcp serve --config ./synapsor.runner.json --store ./.synapsor/local.db
 ```
 
+The `contract bundle` step generates `synapsor.runner.json` (with env-var
+placeholders) inside the bundle directory, which is why `mcp serve` runs from
+there. The server keeps stdout clean for MCP protocol frames and prints its
+ready line on stderr.
+
 Your `synapsor.runner.json` supplies local wiring: database env var names,
 SQLite store path, MCP transport settings, and local debug options. The
 contract supplies the portable meaning: contexts, capabilities, evidence,

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAYA,OAAO,EAAqG,KAAK,WAAW,EAA2F,MAAM,6BAA6B,CAAC;AAoB3P,OAAO,EAA6G,KAAK,YAAY,EAAwB,MAAM,2BAA2B,CAAC;AAE/L,OAAO,EAOL,KAAK,gBAAgB,EAEtB,MAAM,mCAAmC,CAAC;AA6U3C,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAqD1D;AA+DD,KAAK,SAAS,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAE9E,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,GAAE;IACP,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,MAAM,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;CACvC,GACL,OAAO,CAAC,MAAM,CAAC,CA2TjB;AA8mED,wBAAsB,0BAA0B,CAAC,GAAG,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAM/H"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAYA,OAAO,EAAoN,KAAK,WAAW,EAA2F,MAAM,6BAA6B,CAAC;AAoB1W,OAAO,EAA6G,KAAK,YAAY,EAAwB,MAAM,2BAA2B,CAAC;AAE/L,OAAO,EAOL,KAAK,gBAAgB,EAEtB,MAAM,mCAAmC,CAAC;AA6U3C,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAqD1D;AA+DD,KAAK,SAAS,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAE9E,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,GAAE;IACP,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,MAAM,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;CACvC,GACL,OAAO,CAAC,MAAM,CAAC,CA2TjB;AAyrED,wBAAsB,0BAA0B,CAAC,GAAG,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAS/H"}

package/dist/runner.mjs

@@ -440,7 +440,7 @@ function normalizeRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
 }
 function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
 }
 
 // packages/config/src/index.ts
@@ -479,6 +479,7 @@ var CAPABILITY_KEYS = /* @__PURE__ */ new Set([
   "transition_guards",
   "conflict_guard",
   "approval",
+  "writeback",
   "single_tenant_dev_ack"
 ]);
 var TARGET_KEYS = /* @__PURE__ */ new Set(["schema", "table", "primary_key", "tenant_key", "single_tenant_dev"]);
@@ -489,6 +490,8 @@ var NUMERIC_BOUND_KEYS = /* @__PURE__ */ new Set(["minimum", "maximum"]);
 var TRANSITION_GUARD_KEYS = /* @__PURE__ */ new Set(["from_column", "allowed"]);
 var CONFLICT_GUARD_KEYS = /* @__PURE__ */ new Set(["column", "weak_guard_ack"]);
 var APPROVAL_KEYS = /* @__PURE__ */ new Set(["mode", "required_role"]);
+var WRITEBACK_KEYS = /* @__PURE__ */ new Set(["mode", "executor"]);
+var WRITEBACK_MODES = /* @__PURE__ */ new Set(["direct_sql", "app_handler", "cloud_worker", "none"]);
 var MODEL_CONTROLLED_TRUST_FIELDS = /* @__PURE__ */ new Set([
   "tenant_id",
   "tenantId",
@@ -653,9 +656,7 @@ function validateWritebackReadiness(sources, capabilities, mode, errors, warning
     const sourceName = isNonEmptyString(capability.source) ? capability.source : void 0;
     const source = sourceName ? sources[sourceName] : void 0;
     if (!sourceName || !isRecord(source)) return;
-    const executor = isNonEmptyString(capability.executor) ? capability.executor : "sql_update";
-    const directSql = executor === "sql_update";
-    if (!directSql) return;
+    if (capabilityWritebackMode(capability) !== "direct_sql") return;
     if (source.read_only === true) {
       errors.push({
         path: `$.capabilities[${index}].executor`,
@@ -673,6 +674,13 @@ function validateWritebackReadiness(sources, capabilities, mode, errors, warning
     }
   });
 }
+function capabilityWritebackMode(capability) {
+  if (isRecord(capability.writeback) && typeof capability.writeback.mode === "string" && WRITEBACK_MODES.has(capability.writeback.mode)) {
+    return capability.writeback.mode;
+  }
+  if (isNonEmptyString(capability.executor) && capability.executor !== "sql_update") return "app_handler";
+  return "direct_sql";
+}
 function validateCloud(value, mode, strict, errors) {
   if (mode !== "cloud") {
     if (value !== void 0) {
@@ -889,7 +897,21 @@ function validateCapabilities(value, sources, contexts, executors, mode, strict,
   const sourceNames = isRecord(sources) ? new Set(Object.keys(sources)) : /* @__PURE__ */ new Set();
   const contextNames = isRecord(contexts) ? new Set(Object.keys(contexts)) : /* @__PURE__ */ new Set();
   const executorNames = isRecord(executors) ? new Set(Object.keys(executors)) : /* @__PURE__ */ new Set();
+  const capabilityNames = /* @__PURE__ */ new Map();
   value.forEach((capability, index) => validateCapability(capability, index, sourceNames, contextNames, executorNames, strict, errors, warnings));
+  value.forEach((capability, index) => {
+    if (!isRecord(capability) || !isQualifiedName(capability.name)) return;
+    const previous = capabilityNames.get(capability.name);
+    if (previous !== void 0) {
+      errors.push({
+        path: `$.capabilities[${index}].name`,
+        code: "DUPLICATE_CAPABILITY_NAME",
+        message: `Capability ${capability.name} is already defined at $.capabilities[${previous}]. Capability names must be unique.`
+      });
+      return;
+    }
+    capabilityNames.set(capability.name, index);
+  });
 }
 function validateCapability(value, index, sourceNames, contextNames, executorNames, strict, errors, warnings) {
   const path4 = `$.capabilities[${index}]`;
@@ -923,6 +945,7 @@ function validateCapability(value, index, sourceNames, contextNames, executorNam
       errors.push({ path: `${path4}.executor`, code: "UNKNOWN_EXECUTOR", message: "Capability executor must be sql_update or reference a configured executor." });
     }
   }
+  validateCapabilityWriteback(value, path4, executorNames, strict, errors);
   validateTarget(value.target, `${path4}.target`, strict, errors, warnings);
   validateArgs(value.args, `${path4}.args`, strict, errors);
   validateLookup(value.lookup, `${path4}.lookup`, strict, errors);
@@ -932,6 +955,40 @@ function validateCapability(value, index, sourceNames, contextNames, executorNam
   }
   if (value.kind === "proposal") {
     validateProposalCapability(value, path4, strict, errors);
+  } else if (value.writeback !== void 0) {
+    errors.push({ path: `${path4}.writeback`, code: "WRITEBACK_ONLY_FOR_PROPOSAL", message: "writeback is only valid on proposal capabilities." });
+  }
+}
+function validateCapabilityWriteback(capability, path4, executorNames, strict, errors) {
+  if (capability.writeback === void 0) return;
+  if (!isRecord(capability.writeback)) {
+    errors.push({ path: `${path4}.writeback`, code: "WRITEBACK_NOT_OBJECT", message: "writeback must be an object." });
+    return;
+  }
+  if (strict) checkUnknownKeys(capability.writeback, WRITEBACK_KEYS, `${path4}.writeback`, errors);
+  if (!WRITEBACK_MODES.has(String(capability.writeback.mode))) {
+    errors.push({ path: `${path4}.writeback.mode`, code: "INVALID_WRITEBACK_MODE", message: "writeback.mode must be direct_sql, app_handler, cloud_worker, or none." });
+    return;
+  }
+  const mode = String(capability.writeback.mode);
+  const executor = isNonEmptyString(capability.writeback.executor) ? capability.writeback.executor : isNonEmptyString(capability.executor) ? capability.executor : void 0;
+  if (mode === "direct_sql") {
+    if (executor !== void 0 && executor !== "sql_update") {
+      errors.push({ path: `${path4}.writeback.executor`, code: "WRITEBACK_EXECUTOR_MISMATCH", message: "direct_sql writeback cannot name an app-owned executor." });
+    }
+    return;
+  }
+  if (mode === "none") {
+    if (executor !== void 0) {
+      errors.push({ path: `${path4}.writeback.executor`, code: "WRITEBACK_EXECUTOR_MISMATCH", message: "WRITEBACK NONE must not name an executor." });
+    }
+    return;
+  }
+  if (mode === "cloud_worker") return;
+  if (!executor || executor === "sql_update") {
+    errors.push({ path: `${path4}.writeback.executor`, code: "WRITEBACK_EXECUTOR_REQUIRED", message: "app_handler writeback must name a configured executor." });
+  } else if (!executorNames.has(executor)) {
+    errors.push({ path: `${path4}.writeback.executor`, code: "UNKNOWN_EXECUTOR", message: "app_handler writeback executor must reference a configured executor." });
   }
 }
 function validateTarget(value, path4, strict, errors, warnings) {
@@ -1250,6 +1307,8 @@ import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 
 // packages/proposal-store/src/index.ts
 import { DatabaseSync } from "node:sqlite";
+import { mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
 var ProposalStoreError = class extends Error {
   constructor(code, message) {
     super(message);
@@ -1263,6 +1322,9 @@ var ProposalStore = class {
   path;
   constructor(path4 = ":memory:") {
     this.path = path4;
+    if (path4 !== ":memory:") {
+      mkdirSync(dirname(resolve(path4)), { recursive: true });
+    }
     this.db = new DatabaseSync(path4);
     this.migrate();
   }
@@ -1952,6 +2014,10 @@ var ProposalStore = class {
     if (changeSet.writeback.mode !== "trusted_worker_required") {
       throw new ProposalStoreError("WRITEBACK_NOT_REQUIRED", `proposal ${proposalId} uses ${changeSet.writeback.mode}`);
     }
+    const writebackExecutor = changeSet.writeback.executor;
+    if (typeof writebackExecutor === "string" && writebackExecutor !== "sql_update" && writebackExecutor !== "trusted_worker_required") {
+      throw new ProposalStoreError("WRITEBACK_NOT_DIRECT_SQL", `proposal ${proposalId} uses app-owned or non-local writeback executor ${writebackExecutor}`);
+    }
     if (changeSet.source.kind !== "external_postgres" && changeSet.source.kind !== "external_mysql") {
       throw new ProposalStoreError("WRITEBACK_TARGET_NOT_EXTERNAL", `proposal ${proposalId} targets ${changeSet.source.kind}`);
     }
@@ -2755,7 +2821,7 @@ var PROPOSAL_KEYS = /* @__PURE__ */ new Set(["action", "allowed_fields", "patch"
 var PATCH_KEYS = /* @__PURE__ */ new Set(["fixed", "from_arg"]);
 var CONFLICT_GUARD_KEYS2 = /* @__PURE__ */ new Set(["column", "weak_guard_ack"]);
 var APPROVAL_KEYS2 = /* @__PURE__ */ new Set(["mode", "required_role"]);
-var WRITEBACK_KEYS = /* @__PURE__ */ new Set(["mode", "executor", "idempotency_key"]);
+var WRITEBACK_KEYS2 = /* @__PURE__ */ new Set(["mode", "executor", "idempotency_key"]);
 var WORKFLOW_KEYS = /* @__PURE__ */ new Set(["name", "description", "context", "allowed_capabilities", "required_evidence", "approval", "settlement", "replay"]);
 var POLICY_KEYS = /* @__PURE__ */ new Set(["name", "kind", "mode", "rules"]);
 var EVIDENCE_RECORD_KEYS = /* @__PURE__ */ new Set(["handle", "capability", "query_fingerprint", "items"]);
@@ -3057,7 +3123,7 @@ function validateProposalAction(value, path4, errors) {
   if (value.approval !== void 0)
     validateNestedObject(value.approval, APPROVAL_KEYS2, `${path4}.approval`, errors);
   if (value.writeback !== void 0) {
-    validateNestedObject(value.writeback, WRITEBACK_KEYS, `${path4}.writeback`, errors);
+    validateNestedObject(value.writeback, WRITEBACK_KEYS2, `${path4}.writeback`, errors);
     if (isRecord3(value.writeback) && !["direct_sql", "app_handler", "cloud_worker", "none"].includes(String(value.writeback.mode)))
       errors.push({ path: `${path4}.writeback.mode`, code: "INVALID_WRITEBACK_MODE", message: "writeback.mode must be direct_sql, app_handler, cloud_worker, or none." });
   }
@@ -3296,20 +3362,31 @@ function loadRuntimeConfigFromFile(configPath = process.env.SYNAPSOR_MCP_CONFIG
 }
 function resolveRuntimeConfig(config, baseDir = process.cwd()) {
   if (!Array.isArray(config.contracts) || config.contracts.length === 0) return config;
+  const seenCapabilities = /* @__PURE__ */ new Map();
+  for (const [index, capability] of (config.capabilities ?? []).entries()) {
+    rememberCapabilityName(seenCapabilities, capability.name, `embedded capabilities[${index}]`);
+  }
   const resolved = {
     ...config,
     contexts: { ...config.contexts ?? {} },
     capabilities: [...config.capabilities ?? []]
   };
-  for (const contractPath of config.contracts) {
+  for (const [contractIndex, contractPath] of config.contracts.entries()) {
     const fullPath = path.resolve(baseDir, contractPath);
     const contract = normalizeContract(JSON.parse(fs.readFileSync(fullPath, "utf8")));
-    mergeContractIntoRuntimeConfig(resolved, contract);
+    mergeContractIntoRuntimeConfig(resolved, contract, `contracts[${contractIndex}] ${contractPath}`, seenCapabilities);
   }
   delete resolved.contracts;
   return resolved;
 }
-function mergeContractIntoRuntimeConfig(config, contract) {
+function rememberCapabilityName(seen, name, origin) {
+  const previous = seen.get(name);
+  if (previous) {
+    throw new Error(`Duplicate capability ${name}: ${origin} conflicts with ${previous}. Capability names must be unique across embedded runner config and referenced contracts.`);
+  }
+  seen.set(name, origin);
+}
+function mergeContractIntoRuntimeConfig(config, contract, origin, seenCapabilities) {
   const resources = new Map((contract.resources ?? []).map((resource) => [resource.name, resource]));
   for (const context of contract.contexts) {
     if (!config.contexts) config.contexts = {};
@@ -3320,7 +3397,8 @@ function mergeContractIntoRuntimeConfig(config, contract) {
     if (context) config.trusted_context = runtimeContextFromSpec(context);
   }
   if (!config.capabilities) config.capabilities = [];
-  for (const capability of contract.capabilities) {
+  for (const [capabilityIndex, capability] of contract.capabilities.entries()) {
+    rememberCapabilityName(seenCapabilities, capability.name, `${origin} capabilities[${capabilityIndex}]`);
     config.capabilities.push(runtimeCapabilityFromSpec(capability, resources, config));
   }
 }
@@ -3364,7 +3442,11 @@ function runtimeCapabilityFromSpec(capability, resources, config) {
     runtime.allowed_columns = capability.proposal.allowed_fields;
     runtime.conflict_guard = capability.proposal.conflict_guard;
     runtime.approval = capability.proposal.approval;
-    if (capability.proposal.writeback?.mode && capability.proposal.writeback.mode !== "direct_sql" && capability.proposal.writeback.executor) {
+    runtime.writeback = {
+      mode: capability.proposal.writeback?.mode ?? "direct_sql",
+      ...capability.proposal.writeback?.executor ? { executor: capability.proposal.writeback.executor } : {}
+    };
+    if (capability.proposal.writeback?.executor) {
       runtime.executor = capability.proposal.writeback.executor;
     }
   }
@@ -3521,11 +3603,12 @@ async function serveStdio(options = {}) {
   const server = createSynapsorMcpServer(runtime, { toolNameStyle: options.toolNameStyle });
   const transport = new StdioServerTransport();
   await server.connect(transport);
-  await new Promise((resolve) => {
+  process.stderr.write("synapsor-runner MCP stdio server ready. Waiting for an MCP client on stdio; logs stay on stderr.\n");
+  await new Promise((resolve2) => {
     const previousOnClose = transport.onclose;
     const close = () => {
       runtime.close();
-      resolve();
+      resolve2();
     };
     transport.onclose = () => {
       previousOnClose?.();
@@ -3544,7 +3627,7 @@ async function startHttpMcpServer(options = {}) {
   if (devNoAuth && !isLoopbackHost(host)) {
     throw new McpRuntimeError("HTTP_DEV_NO_AUTH_UNSAFE_HOST", "--dev-no-auth is only allowed with localhost or 127.0.0.1.");
   }
-  const authToken = devNoAuth ? void 0 : env[authTokenEnv];
+  const authToken = devNoAuth ? void 0 : envValue(env, authTokenEnv);
   if (!devNoAuth && !authToken) {
     throw new McpRuntimeError("HTTP_AUTH_TOKEN_MISSING", `${authTokenEnv} is not set. HTTP MCP requires bearer auth by default.`);
   }
@@ -3568,11 +3651,11 @@ async function startHttpMcpServer(options = {}) {
     });
   });
   try {
-    await new Promise((resolve, reject) => {
+    await new Promise((resolve2, reject) => {
       server.once("error", reject);
       server.listen(port, host, () => {
         server.off("error", reject);
-        resolve();
+        resolve2();
       });
     });
   } catch (error) {
@@ -3610,7 +3693,7 @@ async function startStreamableHttpMcpServer(options = {}) {
   if (devNoAuth && !isLoopbackHost(host)) {
     throw new McpRuntimeError("HTTP_DEV_NO_AUTH_UNSAFE_HOST", "--dev-no-auth is only allowed with localhost or 127.0.0.1.");
   }
-  const authToken = devNoAuth ? void 0 : env[authTokenEnv];
+  const authToken = devNoAuth ? void 0 : envValue(env, authTokenEnv);
   if (!devNoAuth && !authToken) {
     throw new McpRuntimeError("HTTP_AUTH_TOKEN_MISSING", `${authTokenEnv} is not set. Streamable HTTP MCP requires bearer auth by default.`);
   }
@@ -3637,11 +3720,11 @@ async function startStreamableHttpMcpServer(options = {}) {
     });
   });
   try {
-    await new Promise((resolve, reject) => {
+    await new Promise((resolve2, reject) => {
       server.once("error", reject);
       server.listen(port, host, () => {
         server.off("error", reject);
-        resolve();
+        resolve2();
       });
     });
   } catch (error) {
@@ -3965,20 +4048,20 @@ function isLoopbackHost(host) {
   return host === "127.0.0.1" || host === "localhost" || host === "::1";
 }
 async function closeHttpServer(server, runtime) {
-  await new Promise((resolve, reject) => {
+  await new Promise((resolve2, reject) => {
     server.close((error) => {
       if (error) reject(error);
-      else resolve();
+      else resolve2();
     });
   }).finally(() => {
     runtime.close();
   });
 }
 async function closeStreamableHttpServer(server, sessions) {
-  await new Promise((resolve, reject) => {
+  await new Promise((resolve2, reject) => {
     server.close((error) => {
       if (error) reject(error);
-      else resolve();
+      else resolve2();
     });
   }).finally(() => closeStreamableSessions(sessions));
 }
@@ -4022,8 +4105,8 @@ function listedLocalCapabilities(config) {
 }
 function createCloudClient(config, env) {
   const cloud2 = requireCloudConfig(config);
-  const baseUrl = env[cloud2.base_url_env];
-  const runnerToken = env[cloud2.runner_token_env];
+  const baseUrl = envValue(env, cloud2.base_url_env);
+  const runnerToken = envValue(env, cloud2.runner_token_env);
   if (!baseUrl) throw new McpRuntimeError("CLOUD_BASE_URL_MISSING", `${cloud2.base_url_env} is not set.`);
   if (!runnerToken) throw new McpRuntimeError("CLOUD_RUNNER_TOKEN_MISSING", `${cloud2.runner_token_env} is not set.`);
   return new ControlPlaneClient({
@@ -4105,6 +4188,9 @@ async function callConfiguredTool(input) {
   if (capability.kind === "proposal" && input.config.mode === "read_only") {
     throw new McpRuntimeError("PROPOSALS_DISABLED", "This runner is in read_only mode; proposal tools are disabled.");
   }
+  if (capability.kind === "proposal" && input.config.mode === "review") {
+    assertProposalWritebackResolvable(input.config, capability);
+  }
   const source = input.config.sources?.[capability.source];
   if (!source) throw new McpRuntimeError("SOURCE_NOT_FOUND", `Unknown source: ${capability.source}`);
   const context = resolveTrustedContext(input.config, input.env, capability);
@@ -4274,7 +4360,7 @@ function resultEnvelopeFromLegacy(legacy, capability, canonicalName) {
     const targetType = typeof target2?.type === "string" ? target2.type : capability?.target.table ?? "object";
     const targetId = target2?.id !== void 0 ? String(target2.id) : "unknown";
     const executor = writebackExecutorName(legacy.writeback);
-    const writebackMode = executor && executor !== "sql_update" && executor !== "trusted_worker_required" ? "app_handler" : "direct_update";
+    const writebackMode = executor === "read_only" || executor === "none" ? "proposal_only" : executor && executor !== "sql_update" && executor !== "trusted_worker_required" ? "app_handler" : "direct_update";
     return {
       ok: true,
       summary: `Created proposal ${proposalId} for ${targetType} ${targetId}. Source database changed: no.`,
@@ -4329,6 +4415,44 @@ function writebackExecutorName(value) {
   if (!isRecord4(value)) return void 0;
   return typeof value.executor === "string" ? value.executor : typeof value.mode === "string" ? value.mode : void 0;
 }
+function capabilityWritebackMode2(capability) {
+  const mode = capability.writeback?.mode;
+  if (mode === "direct_sql" || mode === "app_handler" || mode === "cloud_worker" || mode === "none") return mode;
+  if (capability.executor && capability.executor !== "sql_update") return "app_handler";
+  return "direct_sql";
+}
+function capabilityWritebackExecutor(capability) {
+  return capability.writeback?.executor ?? capability.executor;
+}
+function assertProposalWritebackResolvable(config, capability) {
+  if (capability.kind !== "proposal") return;
+  const mode = capabilityWritebackMode2(capability);
+  if (mode === "none" || mode === "cloud_worker") return;
+  if (mode === "direct_sql") {
+    const source = config.sources?.[capability.source];
+    if (!source) {
+      throw new McpRuntimeError("WRITEBACK_UNRESOLVED", `capability ${capability.name} declares DIRECT SQL writeback but source ${capability.source} is not configured.`);
+    }
+    if (source.read_only === true) {
+      throw new McpRuntimeError("WRITEBACK_UNRESOLVED", `capability ${capability.name} declares DIRECT SQL writeback but source ${capability.source} is read-only.`);
+    }
+    if (!source.write_url_env) {
+      throw new McpRuntimeError("WRITEBACK_UNRESOLVED", `capability ${capability.name} declares DIRECT SQL writeback but source ${capability.source} has no write_url_env.`);
+    }
+    return;
+  }
+  const executorName = capabilityWritebackExecutor(capability);
+  if (!executorName || executorName === "sql_update") {
+    throw new McpRuntimeError("WRITEBACK_UNRESOLVED", `capability ${capability.name} declares HANDLER writeback but has no executor name.`);
+  }
+  const executor = config.executors?.[executorName];
+  if (!isRecord4(executor)) {
+    throw new McpRuntimeError("WRITEBACK_UNRESOLVED", `capability ${capability.name} declares HANDLER writeback but executor ${executorName} is not configured.`);
+  }
+  if (executor.type !== "http_handler" && executor.type !== "command_handler") {
+    throw new McpRuntimeError("WRITEBACK_UNRESOLVED", `capability ${capability.name} declares HANDLER writeback but executor ${executorName} is not an app-owned handler.`);
+  }
+}
 function evidenceHandle(bundleId) {
   return {
     bundle_id: bundleId,
@@ -4388,6 +4512,9 @@ function buildChangeSet(input) {
   enforcePatchGuards(input.capability, before, patch);
   const after = { ...before, ...patch };
   const guard = expectedVersionGuard(input.capability, before);
+  const writebackMode = capabilityWritebackMode2(input.capability);
+  const changeSetWritebackMode = writebackMode === "none" ? "read_only" : "trusted_worker_required";
+  const writebackExecutor = writebackMode === "none" ? "none" : writebackMode === "cloud_worker" ? "cloud_worker" : writebackMode === "direct_sql" ? "sql_update" : capabilityWritebackExecutor(input.capability);
   const proposalCore = {
     schema_version: protocolVersions.changeSet,
     proposal_id: stableId("wrp", {
@@ -4435,8 +4562,8 @@ function buildChangeSet(input) {
     },
     writeback: {
       status: "not_applied",
-      mode: "trusted_worker_required",
-      executor: input.capability.executor ?? "sql_update"
+      mode: changeSetWritebackMode,
+      executor: writebackExecutor
     },
     source_database_mutated: false,
     created_at: (/* @__PURE__ */ new Date()).toISOString()
@@ -4459,7 +4586,7 @@ async function readCurrentRow(input) {
   return readMysqlRow(input);
 }
 async function readPostgresRow(input) {
-  const connectionString = input.env[input.source.read_url_env];
+  const connectionString = envValue(input.env, input.source.read_url_env);
   if (!connectionString) throw new McpRuntimeError("SOURCE_CREDENTIAL_MISSING", `${input.source.read_url_env} is not set.`);
   const pool = new Pool({ connectionString });
   const client = await pool.connect();
@@ -4481,7 +4608,7 @@ async function readPostgresRow(input) {
   }
 }
 async function readMysqlRow(input) {
-  const uri = input.env[input.source.read_url_env];
+  const uri = envValue(input.env, input.source.read_url_env);
   if (!uri) throw new McpRuntimeError("SOURCE_CREDENTIAL_MISSING", `${input.source.read_url_env} is not set.`);
   const connection = await mysql.createConnection({ uri, dateStrings: true });
   try {
@@ -4536,8 +4663,8 @@ function resolveTrustedContext(config, env, capability) {
   if (provider === "environment") {
     const tenantEnv = String(values.tenant_id_env ?? "SYNAPSOR_TENANT_ID");
     const principalEnv = String(values.principal_env ?? "SYNAPSOR_PRINCIPAL");
-    const tenant = env[tenantEnv];
-    const principal = env[principalEnv];
+    const tenant = envValue(env, tenantEnv);
+    const principal = envValue(env, principalEnv);
     if (!tenant || !principal) throw new McpRuntimeError("TRUSTED_BINDING_MISSING", `${tenantEnv} and ${principalEnv} must be set.`);
     return { tenant_id: tenant, principal, provenance: "environment" };
   }
@@ -4550,8 +4677,19 @@ function resolveTrustedContext(config, env, capability) {
   throw new McpRuntimeError("TRUSTED_CONTEXT_UNSUPPORTED", `${provider} trusted context is not available in local stdio mode.`);
 }
 function valueFromEnvOrLiteral(envName, literal, env) {
-  if (typeof envName === "string" && env[envName]) return env[envName];
-  return typeof literal === "string" && literal.length > 0 ? literal : void 0;
+  if (typeof envName === "string") {
+    const value2 = envValue(env, envName);
+    if (value2) return value2;
+  }
+  if (typeof literal !== "string") return void 0;
+  const value = literal.trim();
+  return value.length > 0 ? value : void 0;
+}
+function envValue(env, name) {
+  const value = env[name];
+  if (value === void 0) return void 0;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
 }
 function validateToolArgs(capability, args) {
   for (const [name, spec] of Object.entries(capability.args)) {
@@ -6420,7 +6558,7 @@ async function startPolling(config, adapters2, signal) {
     } catch (error) {
       logger.error("runner loop failed", { error: error instanceof Error ? error.message : String(error) });
     }
-    await new Promise((resolve) => setTimeout(resolve, config.pollIntervalMs));
+    await new Promise((resolve2) => setTimeout(resolve2, config.pollIntervalMs));
   }
 }
 
@@ -6856,11 +6994,11 @@ async function startLocalUiServer(options = {}) {
       });
     }
   });
-  await new Promise((resolve, reject) => {
+  await new Promise((resolve2, reject) => {
     server.once("error", reject);
     server.listen(options.port ?? 0, host, () => {
       server.off("error", reject);
-      resolve();
+      resolve2();
     });
   });
   const address = server.address();
@@ -6873,10 +7011,10 @@ async function startLocalUiServer(options = {}) {
     port,
     token,
     csrfToken,
-    close: () => new Promise((resolve, reject) => {
+    close: () => new Promise((resolve2, reject) => {
       server.close((error) => {
         if (error) reject(error);
-        else resolve();
+        else resolve2();
       });
     })
   };
@@ -8719,7 +8857,7 @@ async function writeGeneratedSmokeInputFile(lookupArg, objectId, force) {
 `, force);
 }
 async function maybeRunGeneratedSmokeCall(input) {
-  const required = uniqueStrings([input.readUrlEnv, input.tenantEnv, input.principalEnv]).filter((envName) => !input.env[envName]);
+  const required = uniqueStrings([input.readUrlEnv, input.tenantEnv, input.principalEnv]).filter((envName) => !envValue2(input.env, envName));
   if (required.length > 0) {
     return [
       "Smoke call not run yet.",
@@ -9352,8 +9490,7 @@ function bundleReadme(contract) {
 }
 async function configValidate(args) {
   const configPath = optionalArg(args, "--config") ?? "synapsor.runner.json";
-  const parsed = JSON.parse(await fs3.readFile(configPath, "utf8"));
-  const result = validateRunnerCapabilityConfig(parsed);
+  const result = await validateConfigFile(configPath);
   if (args.includes("--json")) {
     process2.stdout.write(`${JSON.stringify(result, null, 2)}
 `);
@@ -9374,6 +9511,30 @@ async function configValidate(args) {
   }
   return result.ok ? 0 : 1;
 }
+async function validateConfigFile(configPath) {
+  const parsed = JSON.parse(await fs3.readFile(configPath, "utf8"));
+  const raw = validateRunnerCapabilityConfig(parsed);
+  if (!raw.ok) return raw;
+  try {
+    const resolved = resolveRuntimeConfig(parsed, path3.dirname(path3.resolve(configPath)));
+    const resolvedValidation = validateRunnerCapabilityConfig(resolved);
+    return {
+      ok: resolvedValidation.ok,
+      errors: resolvedValidation.errors,
+      warnings: [...raw.warnings, ...resolvedValidation.warnings]
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      errors: [{
+        path: "$.contracts",
+        code: "CONTRACT_RESOLUTION_FAILED",
+        message: error instanceof Error ? error.message : String(error)
+      }],
+      warnings: raw.warnings
+    };
+  }
+}
 async function configShow(args) {
   const configPath = optionalArg(args, "--config") ?? "synapsor.runner.json";
   const parsed = JSON.parse(await fs3.readFile(configPath, "utf8"));
@@ -9437,13 +9598,49 @@ function trustedContextsForDoctor(config) {
   return contexts;
 }
 function envPresenceCheck(envName, message) {
+  const value = envValue2(process2.env, envName);
   return {
     name: `env:${envName}`,
-    ok: Boolean(process2.env[envName]),
-    level: process2.env[envName] ? "pass" : "fail",
-    message: process2.env[envName] ? `${envName} is set.` : message
+    ok: Boolean(value),
+    level: value ? "pass" : "fail",
+    message: value ? `${envName} is set.` : message
   };
 }
+function proposalWritebackResolutionDoctorCheck(config, capability) {
+  const mode = capabilityWritebackMode2(capability);
+  if (mode === "none") {
+    return {
+      name: `capability:${capability.name}:writeback-resolution`,
+      ok: true,
+      level: "pass",
+      message: "Capability explicitly declares no local writeback; proposals are review records only."
+    };
+  }
+  if (mode === "cloud_worker") {
+    return {
+      name: `capability:${capability.name}:writeback-resolution`,
+      ok: true,
+      level: "pass",
+      message: "Capability declares cloud-worker writeback; local apply is intentionally unavailable."
+    };
+  }
+  try {
+    assertProposalWritebackResolvable(config, capability);
+    return {
+      name: `capability:${capability.name}:writeback-resolution`,
+      ok: true,
+      level: "pass",
+      message: mode === "direct_sql" ? "Direct SQL writeback definition resolves to a source and writer env var name." : `App-owned handler writeback resolves to executor ${capabilityWritebackExecutor(capability)}.`
+    };
+  } catch (error) {
+    return {
+      name: `capability:${capability.name}:writeback-resolution`,
+      ok: false,
+      level: "fail",
+      message: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
 async function httpHandlerReachabilityCheck(executorName, rawUrl, timeoutMs) {
   try {
     const url = new URL(rawUrl);
@@ -9493,7 +9690,7 @@ function safeReachabilityError(error) {
   return "connection failed";
 }
 async function inspectConfiguredSource(input) {
-  if (!process2.env[input.source.read_url_env]) return;
+  if (!envValue2(process2.env, input.source.read_url_env)) return;
   const capabilities = (input.config.capabilities ?? []).filter((capability) => capability.source === input.sourceName);
   const schemas = Array.from(new Set(capabilities.map((capability) => capability.target.schema)));
   for (const schema of schemas.length ? schemas : [void 0]) {
@@ -9836,15 +10033,15 @@ function firstRunConfigEnvChecks(config) {
       String(values.tenant_id_env ?? "SYNAPSOR_TENANT_ID"),
       String(values.principal_env ?? "SYNAPSOR_PRINCIPAL")
     ]) {
-      checks.push(process2.env[envName] ? pass(`env-${envName}`, `${envName} is set for ${contextName}.`, "Trusted tenant/principal values must come from the launcher, not the model.", "No action needed.") : warn(`env-${envName}`, `${envName} is not set for ${contextName}.`, "Trusted tenant/principal values must come from the launcher, not the model.", `Set ${envName}, or use the generated .env.example as a template.`));
+      checks.push(envValue2(process2.env, envName) ? pass(`env-${envName}`, `${envName} is set for ${contextName}.`, "Trusted tenant/principal values must come from the launcher, not the model.", "No action needed.") : warn(`env-${envName}`, `${envName} is not set for ${contextName}.`, "Trusted tenant/principal values must come from the launcher, not the model.", `Set ${envName}, or use the generated .env.example as a template.`));
     }
   }
   for (const [sourceName, source] of Object.entries(config.sources ?? {})) {
-    checks.push(process2.env[source.read_url_env] ? pass(`env-${source.read_url_env}`, `${source.read_url_env} is set for ${sourceName}.`, "Configured capabilities need a read credential env var to inspect/propose against your DB.", "No action needed.") : warn(`env-${source.read_url_env}`, `${source.read_url_env} is not set for ${sourceName}.`, "Configured capabilities need a read credential env var to inspect/propose against your DB.", `Set ${source.read_url_env} before running doctor, tools preview, or mcp serve against your own database.`));
+    checks.push(envValue2(process2.env, source.read_url_env) ? pass(`env-${source.read_url_env}`, `${source.read_url_env} is set for ${sourceName}.`, "Configured capabilities need a read credential env var to inspect/propose against your DB.", "No action needed.") : warn(`env-${source.read_url_env}`, `${source.read_url_env} is not set for ${sourceName}.`, "Configured capabilities need a read credential env var to inspect/propose against your DB.", `Set ${source.read_url_env} before running doctor, tools preview, or mcp serve against your own database.`));
     if (source.write_url_env) {
-      checks.push(process2.env[source.write_url_env] ? pass(`env-${source.write_url_env}`, `${source.write_url_env} is set for ${sourceName}.`, "Trusted writeback needs a separate writer credential outside the MCP client.", "No action needed.") : warn(`env-${source.write_url_env}`, `${source.write_url_env} is not set for ${sourceName}.`, "Trusted writeback needs a separate writer credential outside the MCP client.", `Set ${source.write_url_env} only when you are ready to apply an approved writeback job.`));
-      const readValue = process2.env[source.read_url_env];
-      const writeValue = process2.env[source.write_url_env];
+      checks.push(envValue2(process2.env, source.write_url_env) ? pass(`env-${source.write_url_env}`, `${source.write_url_env} is set for ${sourceName}.`, "Trusted writeback needs a separate writer credential outside the MCP client.", "No action needed.") : warn(`env-${source.write_url_env}`, `${source.write_url_env} is not set for ${sourceName}.`, "Trusted writeback needs a separate writer credential outside the MCP client.", `Set ${source.write_url_env} only when you are ready to apply an approved writeback job.`));
+      const readValue = envValue2(process2.env, source.read_url_env);
+      const writeValue = envValue2(process2.env, source.write_url_env);
       if (readValue && writeValue && readValue === writeValue) {
         checks.push(fail(`credential-split-${sourceName}`, `Read and write env vars resolve to the same credential for ${sourceName}.`, "Read/proposal authority and writeback authority must be separated.", "Use a read-only credential for MCP reads and a separate writer credential only for trusted apply."));
       }
@@ -9899,11 +10096,11 @@ function fail(name, checked, why, fix) {
   return { name, status: "fail", checked, why, fix };
 }
 async function isPortAvailable(port) {
-  return new Promise((resolve) => {
+  return new Promise((resolve2) => {
     const server = net.createServer();
-    server.once("error", () => resolve(false));
+    server.once("error", () => resolve2(false));
     server.listen(port, "127.0.0.1", () => {
-      server.close(() => resolve(true));
+      server.close(() => resolve2(true));
     });
   });
 }
@@ -9923,9 +10120,10 @@ async function localDoctor(args) {
   const allowSharedCredential = args.includes("--allow-shared-credential");
   const checkHandlers = args.includes("--check-handlers");
   const checkWriteback = args.includes("--check-writeback") || args.includes("--check-db");
-  const parsed = JSON.parse(await fs3.readFile(configPath, "utf8"));
+  const rawConfig = JSON.parse(await fs3.readFile(configPath, "utf8"));
+  let parsed = rawConfig;
   const checks = [];
-  const validation = validateRunnerCapabilityConfig(parsed);
+  const validation = await validateConfigFile(configPath);
   checks.push({
     name: "config-valid",
     ok: validation.ok,
@@ -9935,6 +10133,9 @@ async function localDoctor(args) {
   for (const warning of validation.warnings) {
     checks.push({ name: `config-warning:${warning.code}`, ok: true, level: "warn", message: warning.message });
   }
+  if (validation.ok) {
+    parsed = await readRuntimeConfig(configPath);
+  }
   const contextsToCheck = trustedContextsForDoctor(parsed);
   for (const [contextName, contextValues] of contextsToCheck) {
     const tenantEnv = String(contextValues.tenant_id_env ?? "SYNAPSOR_TENANT_ID");
@@ -9944,14 +10145,19 @@ async function localDoctor(args) {
     }
   }
   const sources = parsed.sources ?? {};
+  if (parsed.mode === "review") {
+    for (const capability of (parsed.capabilities ?? []).filter((item) => item.kind === "proposal")) {
+      checks.push(proposalWritebackResolutionDoctorCheck(parsed, capability));
+    }
+  }
   for (const [sourceName, source] of Object.entries(sources)) {
     checks.push(envPresenceCheck(source.read_url_env, `${source.read_url_env} is required for ${sourceName} reads.`));
     if (parsed.mode === "review") {
       if (sourceNeedsSqlWriteback(parsed, sourceName)) {
         if (source.write_url_env) {
           checks.push(envPresenceCheck(source.write_url_env, `${source.write_url_env} is required for trusted writeback in review mode.`));
-          const readValue = process2.env[source.read_url_env];
-          const writeValue = process2.env[source.write_url_env];
+          const readValue = envValue2(process2.env, source.read_url_env);
+          const writeValue = envValue2(process2.env, source.write_url_env);
           if (readValue && writeValue && readValue === writeValue) {
             checks.push({
               name: `source:${sourceName}:credential-separation`,
@@ -9965,7 +10171,7 @@ async function localDoctor(args) {
         } else {
           checks.push({ name: `source:${sourceName}:write-url-env`, ok: false, level: "fail", message: "SQL writeback proposal capabilities require write_url_env for trusted writeback." });
         }
-        const writeUrl = source.write_url_env ? process2.env[source.write_url_env] : void 0;
+        const writeUrl = source.write_url_env ? envValue2(process2.env, source.write_url_env) : void 0;
         if (checkWriteback && writeUrl) {
           checks.push(...await directSqlWritebackDoctorChecks(parsed, sourceName, source, writeUrl));
         } else if (checkWriteback) {
@@ -9993,7 +10199,7 @@ async function localDoctor(args) {
       const urlEnv = String(executor.url_env ?? "");
       if (urlEnv) {
         checks.push(envPresenceCheck(urlEnv, `${urlEnv} is required for http_handler executor ${executorName}.`));
-        const handlerUrl = process2.env[urlEnv];
+        const handlerUrl = envValue2(process2.env, urlEnv);
         if (checkHandlers && handlerUrl) {
           checks.push(await httpHandlerReachabilityCheck(executorName, handlerUrl, Number(executor.timeout_ms ?? 3e3)));
         } else if (!checkHandlers) {
@@ -10107,7 +10313,7 @@ async function directSqlWritebackDoctorChecks(config, sourceName, source, writeU
 function directSqlProposalCapabilities(config, sourceName) {
   return (config.capabilities ?? []).filter((capability) => {
     if (capability.kind !== "proposal" || capability.source !== sourceName) return false;
-    return (capability.executor ?? "sql_update") === "sql_update";
+    return capabilityWritebackMode2(capability) === "direct_sql";
   });
 }
 async function rollbackOnlyTargetProbe(engine, databaseUrl, capability) {
@@ -10298,7 +10504,7 @@ async function applyProposal(args, proposalId) {
   const storePath = optionalArg(args, "--store") ?? process2.env.SYNAPSOR_LOCAL_STORE ?? "./.synapsor/local.db";
   const dryRun = args.includes("--dry-run") || process2.env.SYNAPSOR_DRY_RUN === "true";
   const runnerId = optionalArg(args, "--runner") ?? process2.env.SYNAPSOR_RUNNER_ID ?? "local_runner";
-  const config = JSON.parse(await fs3.readFile(configPath, "utf8"));
+  const config = await readRuntimeConfig(configPath);
   const resolvedProposalId = await resolveProposalId(proposalId, storePath);
   const validation = validateRunnerCapabilityConfig(config);
   if (!validation.ok) {
@@ -10315,6 +10521,9 @@ async function applyProposal(args, proposalId) {
     const proposal = requireLocalProposal(store, resolvedProposalId);
     const capability = findProposalCapability(config, proposal);
     const executorName = proposalExecutorName(proposal, capability);
+    if (executorName === "none" || executorName === "cloud_worker") {
+      throw new Error(`proposal ${resolvedProposalId} is not locally applyable; capability ${capability.name} declares ${executorName === "none" ? "no local writeback" : "cloud-worker writeback"}.`);
+    }
     if (executorName === "sql_update") {
       const job = store.createWritebackJobFromProposal(resolvedProposalId, {
         project_id: optionalArg(args, "--project") ?? "local",
@@ -10372,16 +10581,19 @@ async function applySqlJob(job, configPath, storePath, dryRun, env = process2.en
   return result;
 }
 async function resolveSqlWriteDatabaseUrl(job, configPath, env) {
-  const config = JSON.parse(await fs3.readFile(configPath, "utf8"));
+  const config = await readRuntimeConfig(configPath);
   const source = config.sources?.[job.source_id];
   const writeUrlEnv = source?.write_url_env;
-  if (writeUrlEnv && env[writeUrlEnv]) return env[writeUrlEnv] ?? "";
-  return env.SYNAPSOR_DATABASE_URL || "";
+  if (writeUrlEnv) {
+    const value = envValue2(env, writeUrlEnv);
+    if (value) return value;
+  }
+  return envValue2(env, "SYNAPSOR_DATABASE_URL") || "";
 }
 function sourceNeedsSqlWriteback(config, sourceName) {
   return (config.capabilities ?? []).some((capability) => {
     if (capability.kind !== "proposal" || capability.source !== sourceName) return false;
-    return (capability.executor ?? "sql_update") === "sql_update";
+    return capabilityWritebackMode2(capability) === "direct_sql";
   });
 }
 function findProposalCapability(config, proposal) {
@@ -10400,8 +10612,12 @@ function findProposalCapability(config, proposal) {
   return capability;
 }
 function proposalExecutorName(proposal, capability) {
+  const mode = capabilityWritebackMode2(capability);
+  if (mode === "none") return "none";
+  if (mode === "cloud_worker") return "cloud_worker";
+  if (mode === "direct_sql") return "sql_update";
   const writeback2 = proposal.change_set.writeback;
-  return capability.executor ?? (typeof writeback2.executor === "string" ? writeback2.executor : void 0) ?? "sql_update";
+  return capabilityWritebackExecutor(capability) ?? (typeof writeback2.executor === "string" ? writeback2.executor : void 0) ?? "sql_update";
 }
 function executorConfig(config, executorName) {
   const raw = config.executors?.[executorName];
@@ -10426,7 +10642,7 @@ async function applyHttpHandlerProposal(input) {
     executor: input.executorName,
     request: prepared.request
   });
-  const url = input.env[input.executor.url_env];
+  const url = envValue2(input.env, input.executor.url_env);
   if (!url) throw new Error(`${input.executor.url_env} is not set`);
   const headers = {
     accept: "application/json",
@@ -10434,7 +10650,7 @@ async function applyHttpHandlerProposal(input) {
     "idempotency-key": prepared.request.idempotency_key
   };
   if (input.executor.auth) {
-    const token = input.env[input.executor.auth.token_env];
+    const token = envValue2(input.env, input.executor.auth.token_env);
     if (!token) throw new Error(`${input.executor.auth.token_env} is not set`);
     headers.authorization = `Bearer ${token}`;
   }
@@ -10449,7 +10665,7 @@ async function applyHttpHandlerProposal(input) {
   headers["x-synapsor-issued-at"] = issuedAt;
   headers["x-synapsor-proposal-id"] = prepared.proposal.proposal_id;
   if (input.executor.signing_secret_env) {
-    const signingSecret = input.env[input.executor.signing_secret_env];
+    const signingSecret = envValue2(input.env, input.executor.signing_secret_env);
     if (!signingSecret) throw new Error(`${input.executor.signing_secret_env} is not set`);
     headers["x-synapsor-signature"] = signHandlerRequestBody(requestBody, signingSecret);
   }
@@ -10487,7 +10703,7 @@ async function applyCommandHandlerProposal(input) {
     executor: input.executorName,
     request: prepared.request
   });
-  const commandText = input.env[input.executor.command_env];
+  const commandText = envValue2(input.env, input.executor.command_env);
   if (!commandText) throw new Error(`${input.executor.command_env} is not set`);
   const [command, ...commandArgs] = splitCommand(commandText);
   if (!command) throw new Error(`${input.executor.command_env} did not contain a command`);
@@ -10737,7 +10953,7 @@ function safeHandlerDetails(value) {
   return redactConfig(value);
 }
 async function runCommandHandler(command, args, request, timeoutMs) {
-  return new Promise((resolve) => {
+  return new Promise((resolve2) => {
     const child = spawn(command, args, { stdio: ["pipe", "pipe", "pipe"], env: process2.env });
     let stdout = "";
     let stderr = "";
@@ -10746,7 +10962,7 @@ async function runCommandHandler(command, args, request, timeoutMs) {
       if (settled) return;
       settled = true;
       clearTimeout(timeout);
-      resolve(body);
+      resolve2(body);
     };
     const timeout = setTimeout(() => {
       child.kill("SIGTERM");
@@ -10771,7 +10987,7 @@ async function runCommandHandler(command, args, request, timeoutMs) {
   });
 }
 async function verifyLocalWritebackAuthority(job, configPath, storePath) {
-  const config = JSON.parse(await fs3.readFile(configPath, "utf8"));
+  const config = await readRuntimeConfig(configPath);
   const validation = validateRunnerCapabilityConfig(config);
   if (!validation.ok) {
     throw new Error(`cannot apply writeback with invalid local config: ${validation.errors.map((error) => error.code).join(", ")}`);
@@ -10789,7 +11005,7 @@ async function verifyLocalWritebackAuthority(job, configPath, storePath) {
   if (Date.parse(String(job.lease_expires_at)) < Date.now()) {
     throw new Error("writeback job lease has expired");
   }
-  const proposalCapabilities = (config.capabilities ?? []).filter((capability) => capability.kind === "proposal" && capability.source === job.source_id);
+  const proposalCapabilities = (config.capabilities ?? []).filter((capability) => capability.kind === "proposal" && capability.source === job.source_id && capabilityWritebackMode2(capability) === "direct_sql");
   const matching = proposalCapabilities.find((capability) => capabilityMatchesJob(capability, job));
   if (!matching) {
     throw new Error("writeback job does not match any reviewed proposal capability in local config");
@@ -10978,7 +11194,7 @@ function formatReviewModeUp(input) {
   } else {
     lines.push(
       `  Streamable HTTP endpoint: http://${input.host}:${input.port}/mcp`,
-      `  Auth token env: ${input.authTokenEnv} (${process2.env[input.authTokenEnv] ? "set" : "missing"})`,
+      `  Auth token env: ${input.authTokenEnv} (${envValue2(process2.env, input.authTokenEnv) ? "set" : "missing"})`,
       input.serveRequested ? input.dryRun ? "  Status: dry run only; server not started." : "  Status: starting after this checklist." : `  Start command: ${cliCommandName()} up --serve --config ${input.configPath} --store ${input.storePath} --port ${input.port} --auth-token-env ${input.authTokenEnv} --alias-mode ${input.aliasMode}`
     );
   }
@@ -10997,12 +11213,19 @@ function formatUpWritebackLines(config) {
   const proposals2 = (config.capabilities ?? []).filter((capability) => capability.kind === "proposal");
   if (proposals2.length === 0) return ["  - no proposal capabilities; this config is read-only from Runner's perspective"];
   return proposals2.map((capability) => {
-    const executorName = capability.executor ?? "sql_update";
-    if (executorName === "sql_update") {
+    const mode = capabilityWritebackMode2(capability);
+    if (mode === "none") {
+      return `  - ${capability.name}: proposal-only; no local writeback`;
+    }
+    if (mode === "cloud_worker") {
+      return `  - ${capability.name}: cloud-worker writeback; local apply disabled`;
+    }
+    if (mode === "direct_sql") {
       const source = config.sources?.[capability.source];
       const envName = source?.write_url_env ?? "SYNAPSOR_DATABASE_URL";
-      return `  - ${capability.name}: direct guarded one-row UPDATE via ${envName} (${process2.env[envName] ? "set" : "missing"})`;
+      return `  - ${capability.name}: direct guarded one-row UPDATE via ${envName} (${envValue2(process2.env, envName) ? "set" : "missing"})`;
     }
+    const executorName = capabilityWritebackExecutor(capability) ?? "missing_executor";
     const executor = config.executors?.[executorName];
     return `  - ${capability.name}: app-owned ${String(executor?.type ?? "executor")} ${executorName}`;
   });
@@ -11017,14 +11240,14 @@ function formatUpHandlerLines(config) {
       const tokenEnv = typeof auth?.token_env === "string" ? auth.token_env : void 0;
       const signingSecretEnv = typeof executor.signing_secret_env === "string" ? executor.signing_secret_env : void 0;
       lines.push(`  - ${name}: http_handler`);
-      if (urlEnv) lines.push(`    url env: ${urlEnv} (${process2.env[urlEnv] ? "set" : "missing"})`);
-      if (tokenEnv) lines.push(`    bearer token env: ${tokenEnv} (${process2.env[tokenEnv] ? "set" : "missing"})`);
-      if (signingSecretEnv) lines.push(`    signing secret env: ${signingSecretEnv} (${process2.env[signingSecretEnv] ? "set" : "missing"})`);
+      if (urlEnv) lines.push(`    url env: ${urlEnv} (${envValue2(process2.env, urlEnv) ? "set" : "missing"})`);
+      if (tokenEnv) lines.push(`    bearer token env: ${tokenEnv} (${envValue2(process2.env, tokenEnv) ? "set" : "missing"})`);
+      if (signingSecretEnv) lines.push(`    signing secret env: ${signingSecretEnv} (${envValue2(process2.env, signingSecretEnv) ? "set" : "missing"})`);
       if (!signingSecretEnv) lines.push("    signing secret env: not configured (recommended unless loopback-only)");
     } else if (executor.type === "command_handler") {
       const commandEnv = typeof executor.command_env === "string" ? executor.command_env : "";
       lines.push(`  - ${name}: command_handler`);
-      if (commandEnv) lines.push(`    command env: ${commandEnv} (${process2.env[commandEnv] ? "set" : "missing"})`);
+      if (commandEnv) lines.push(`    command env: ${commandEnv} (${envValue2(process2.env, commandEnv) ? "set" : "missing"})`);
     }
   }
   return lines;
@@ -11125,8 +11348,8 @@ async function cloudConnect(args) {
   }
   const baseUrlEnv = parsed.cloud.base_url_env || "SYNAPSOR_CLOUD_BASE_URL";
   const tokenEnv = parsed.cloud.runner_token_env || "SYNAPSOR_RUNNER_TOKEN";
-  const baseUrl = process2.env[baseUrlEnv];
-  const runnerToken = process2.env[tokenEnv];
+  const baseUrl = envValue2(process2.env, baseUrlEnv);
+  const runnerToken = envValue2(process2.env, tokenEnv);
   const missing = [baseUrl ? "" : baseUrlEnv, runnerToken ? "" : tokenEnv].filter(Boolean);
   if (missing.length > 0) {
     process2.stdout.write(`missing environment variables: ${missing.join(", ")}
@@ -11302,7 +11525,7 @@ async function writebackDoctor(args) {
   let ok = true;
   for (const [sourceName, source] of sqlSources) {
     const writeEnv = source.write_url_env;
-    const writeUrl = writeEnv ? process2.env[writeEnv] : void 0;
+    const writeUrl = writeEnv ? envValue2(process2.env, writeEnv) : void 0;
     lines.push(`Source: ${sourceName}`);
     lines.push(`  engine: ${source.engine}`);
     lines.push(`  writer env: ${writeEnv ?? "(missing write_url_env)"}`);
@@ -11928,13 +12151,13 @@ async function mcpServeHttp(args) {
     throw error;
   }
   process2.stderr.write("Press Ctrl+C to stop.\n");
-  await new Promise((resolve) => {
+  await new Promise((resolve2) => {
     const stop = async () => {
       process2.off("SIGINT", stop);
       process2.off("SIGTERM", stop);
       await server.close();
       await releaseLease();
-      resolve();
+      resolve2();
     };
     process2.once("SIGINT", stop);
     process2.once("SIGTERM", stop);
@@ -11976,13 +12199,13 @@ async function mcpServeStreamableHttp(args) {
     throw error;
   }
   process2.stderr.write("Press Ctrl+C to stop.\n");
-  await new Promise((resolve) => {
+  await new Promise((resolve2) => {
     const stop = async () => {
       process2.off("SIGINT", stop);
       process2.off("SIGTERM", stop);
       await server.close();
       await releaseLease();
-      resolve();
+      resolve2();
     };
     process2.once("SIGINT", stop);
     process2.once("SIGTERM", stop);
@@ -12988,7 +13211,7 @@ function isRunnerConfigLike(value) {
 }
 async function fetchRemoteMcpTools(target2, args, timeoutMs) {
   const bearerEnv = optionalArg(args, "--bearer-env") ?? "SYNAPSOR_MCP_AUDIT_BEARER";
-  const bearer = process2.env[bearerEnv];
+  const bearer = envValue2(process2.env, bearerEnv);
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), timeoutMs);
   try {
@@ -13014,7 +13237,7 @@ async function fetchRemoteMcpTools(target2, args, timeoutMs) {
 async function fetchStdioMcpTools(commandText, timeoutMs) {
   const [command, ...commandArgs] = splitCommand(commandText);
   if (!command) throw new Error("mcp audit stdio target requires a command");
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve2, reject) => {
     const child = spawn(command, commandArgs, {
       env: process2.env,
       stdio: ["pipe", "pipe", "pipe"]
@@ -13052,7 +13275,7 @@ async function fetchStdioMcpTools(commandText, timeoutMs) {
         reject(new Error(`mcp audit stdio tools/list response not found${stderr ? `: ${stderr.slice(0, 240)}` : ""}`));
         return;
       }
-      resolve(response);
+      resolve2(response);
     });
     child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id: 1, method: "initialize", params: { protocolVersion: "2025-11-25", capabilities: {}, clientInfo: { name: "synapsor-mcp-audit", version: "0.1.0" } } })}
 `);
@@ -13151,12 +13374,12 @@ async function ui(args) {
     process2.stdout.write("Opening the local review UI in your browser when a desktop opener is available.\n");
   }
   process2.stdout.write("Approval and rejection actions require the per-run local session plus CSRF token. Press Ctrl+C to stop.\n");
-  await new Promise((resolve) => {
+  await new Promise((resolve2) => {
     const stop = async () => {
       process2.off("SIGINT", stop);
       process2.off("SIGTERM", stop);
       await server.close();
-      resolve();
+      resolve2();
     };
     process2.once("SIGINT", stop);
     process2.once("SIGTERM", stop);
@@ -13669,7 +13892,7 @@ async function eventsTail(args) {
   }
   const seen = /* @__PURE__ */ new Set();
   await printOnce(seen);
-  await new Promise((resolve) => {
+  await new Promise((resolve2) => {
     const timer = setInterval(() => {
       void printOnce(seen).catch((error) => {
         process2.stderr.write(`events tail error: ${safeErrorMessage(error)}
@@ -13680,7 +13903,7 @@ async function eventsTail(args) {
       clearInterval(timer);
       process2.off("SIGINT", stop);
       process2.off("SIGTERM", stop);
-      resolve();
+      resolve2();
     };
     process2.once("SIGINT", stop);
     process2.once("SIGTERM", stop);
@@ -13689,7 +13912,7 @@ async function eventsTail(args) {
 }
 async function eventsWebhook(args) {
   assertKnownOptions(args, eventWebhookAllowedOptions, "events webhook");
-  const url = optionalArg(args, "--url") ?? envValue(optionalArg(args, "--url-env"));
+  const url = optionalArg(args, "--url") ?? envValue2(optionalArg(args, "--url-env"));
   if (!url) throw new Error("events webhook requires --url <https://...> or --url-env <ENV>");
   const endpoint = new URL(url);
   if (!["http:", "https:"].includes(endpoint.protocol)) throw new Error("events webhook URL must use http or https");
@@ -13703,7 +13926,7 @@ async function eventsWebhook(args) {
   const sinceEventId = optionalPositiveIntegerArg(args, "--since-event-id");
   if (!Number.isFinite(intervalMs) || intervalMs < 250) throw new Error("--interval-ms must be at least 250");
   if (!Number.isFinite(timeoutMs) || timeoutMs < 250) throw new Error("--timeout-ms must be at least 250");
-  const token = envValue(optionalArg(args, "--auth-token-env"));
+  const token = envValue2(optionalArg(args, "--auth-token-env"));
   const filters = eventFiltersFromArgs(args);
   const seen = /* @__PURE__ */ new Set();
   const pushOnce = async () => {
@@ -13738,7 +13961,7 @@ async function eventsWebhook(args) {
 `);
   }
   if (!follow) return 0;
-  await new Promise((resolve) => {
+  await new Promise((resolve2) => {
     const timer = setInterval(() => {
       void pushOnce().catch((error) => {
         process2.stderr.write(`events webhook error: ${safeErrorMessage(error)}
@@ -13749,7 +13972,7 @@ async function eventsWebhook(args) {
       clearInterval(timer);
       process2.off("SIGINT", stop);
       process2.off("SIGTERM", stop);
-      resolve();
+      resolve2();
     };
     process2.once("SIGINT", stop);
     process2.once("SIGTERM", stop);
@@ -14123,9 +14346,19 @@ function optionalPositiveIntegerArg(args, flag) {
   if (!Number.isInteger(parsed) || parsed < 0) throw new Error(`${flag} must be a non-negative integer`);
   return parsed;
 }
-function envValue(name) {
-  if (!name) return void 0;
-  return process2.env[name];
+function envValue2(first, second) {
+  if (typeof first === "string" || first === void 0) {
+    if (!first) return void 0;
+    return trimmedEnvValue(process2.env, first);
+  }
+  if (!second) return void 0;
+  return trimmedEnvValue(first, second);
+}
+function trimmedEnvValue(env, name) {
+  const value = env[name];
+  if (value === void 0) return void 0;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
 }
 function linkedProposalFilter(args, store, options = {}) {
   const noLinkedProposal = "__synapsor_no_linked_proposal__";
@@ -14345,11 +14578,11 @@ async function waitForReferenceDemoDatabase() {
       stdio: "pipe"
     });
     if (result.status === 0) {
-      await new Promise((resolve) => setTimeout(resolve, 500));
+      await new Promise((resolve2) => setTimeout(resolve2, 500));
       return;
     }
     last = result.stderr || result.stdout || `exit ${result.status}`;
-    await new Promise((resolve) => setTimeout(resolve, 1e3));
+    await new Promise((resolve2) => setTimeout(resolve2, 1e3));
   }
   throw new Error(`demo database did not become ready: ${last}`);
 }

package/docs/capability-authoring.md

@@ -300,6 +300,34 @@ Use an app-owned executor when an approved proposal needs richer business work:
 creating a credit row, inserting an outbox event, updating multiple app tables,
 or calling your own service.
 
+In DSL, keep the reviewed business contract portable and name the executor:
+
+```sql
+CREATE CAPABILITY billing.propose_plan_credit
+  CONTEXT trusted_operator
+  SOURCE local_postgres
+  ON public.invoices
+  PRIMARY KEY id
+  TENANT KEY tenant_id
+  ARG invoice_id STRING REQUIRED
+  ARG amount_cents NUMBER REQUIRED
+  ARG reason STRING REQUIRED
+  LOOKUP invoice_id
+  VISIBLE id, tenant_id, customer_id, status, credit_requested_cents, credit_reason, updated_at
+  PROPOSE ACTION billing.grant_plan_credit
+  ALLOW WRITE credit_requested_cents, credit_reason
+  PATCH credit_requested_cents = ARG amount_cents
+  PATCH credit_reason = ARG reason
+  CONFLICT GUARD updated_at
+  APPROVAL ROLE billing_lead
+  WRITEBACK APP HANDLER EXECUTOR billing_handler
+END
+```
+
+`billing_handler` is contract content. Its URL, bearer-token env var, signing
+secret env var, and timeout stay in `synapsor.runner.json` so credentials never
+enter the portable contract:
+
 ```json
 "executors": {
   "billing_handler": {
@@ -316,7 +344,7 @@ or calling your own service.
 }
 ```
 
-Then reference it from a proposal capability:
+For legacy embedded JSON capabilities, reference the same executor directly:
 
 ```json
 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synapsor/runner",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "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",
@@ -52,11 +52,6 @@
   "engines": {
     "node": ">=22.5.0"
   },
-  "scripts": {
-    "build": "tsc -b && node ../../scripts/build-runner-package.mjs",
-    "prepack": "cd ../.. && corepack pnpm build:runner-package",
-    "test": "vitest run"
-  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.29.0",
     "mysql2": "^3.11.0",
@@ -77,5 +72,9 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b && node ../../scripts/build-runner-package.mjs",
+    "test": "vitest run"
   }
-}
+}