@synapsor/runner 0.1.6 → 0.1.8

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) {
@@ -882,6 +890,7 @@ function validateExecutorAuth(value, path4, strict, errors) {
 function validateCapabilities(value, sources, contexts, executors, mode, strict, errors, warnings, hasContracts = false) {
   if (mode === "cloud" && value === void 0) return;
   if (hasContracts && value === void 0) return;
+  if (hasContracts && Array.isArray(value) && value.length === 0) return;
   if (!Array.isArray(value) || value.length === 0) {
     errors.push({ path: "$.capabilities", code: "CAPABILITIES_REQUIRED", message: "At least one capability is required." });
     return;
@@ -889,7 +898,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 +946,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 +956,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 +1308,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 +1323,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 +2015,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}`);
     }
@@ -2746,16 +2813,18 @@ var METADATA_KEYS = /* @__PURE__ */ new Set(["name", "description", "version", "
 var RESOURCE_KEYS = /* @__PURE__ */ new Set(["name", "engine", "schema", "table", "type", "primary_key", "tenant_key", "conflict_key", "single_tenant_dev"]);
 var CONTEXT_KEYS2 = /* @__PURE__ */ new Set(["name", "description", "bindings", "tenant_binding", "principal_binding"]);
 var BINDING_KEYS = /* @__PURE__ */ new Set(["name", "source", "key", "required"]);
-var CAPABILITY_KEYS2 = /* @__PURE__ */ new Set(["name", "description", "kind", "context", "source", "subject", "args", "lookup", "visible_fields", "kept_out_fields", "evidence", "max_rows", "proposal"]);
+var CAPABILITY_KEYS2 = /* @__PURE__ */ new Set(["name", "description", "returns_hint", "kind", "context", "source", "subject", "args", "lookup", "visible_fields", "kept_out_fields", "evidence", "max_rows", "proposal"]);
 var SUBJECT_KEYS = /* @__PURE__ */ new Set(["resource", "schema", "table", "primary_key", "tenant_key", "conflict_key", "single_tenant_dev"]);
 var ARG_KEYS2 = /* @__PURE__ */ new Set(["type", "description", "required", "max_length", "minimum", "maximum", "enum"]);
 var LOOKUP_KEYS2 = /* @__PURE__ */ new Set(["id_from_arg"]);
 var EVIDENCE_KEYS = /* @__PURE__ */ new Set(["required", "sources", "query_audit", "handle_prefix"]);
-var PROPOSAL_KEYS = /* @__PURE__ */ new Set(["action", "allowed_fields", "patch", "conflict_guard", "approval", "writeback"]);
+var PROPOSAL_KEYS = /* @__PURE__ */ new Set(["action", "allowed_fields", "patch", "numeric_bounds", "transition_guards", "conflict_guard", "approval", "writeback"]);
 var PATCH_KEYS = /* @__PURE__ */ new Set(["fixed", "from_arg"]);
+var NUMERIC_BOUND_KEYS2 = /* @__PURE__ */ new Set(["minimum", "maximum"]);
+var TRANSITION_GUARD_KEYS2 = /* @__PURE__ */ new Set(["from_column", "allowed"]);
 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"]);
@@ -2931,6 +3000,8 @@ function validateCapabilities2(value, contextNames, resourceNames, errors, warni
       errors.push({ path: `${path4}.name`, code: "INVALID_CAPABILITY_NAME", message: "capability name must be namespace.name." });
     else
       addUnique(names, capability.name, `${path4}.name`, "DUPLICATE_CAPABILITY_NAME", errors);
+    if (capability.returns_hint !== void 0 && !isNonEmptyString2(capability.returns_hint))
+      errors.push({ path: `${path4}.returns_hint`, code: "INVALID_RETURNS_HINT", message: "returns_hint must be a non-empty string." });
     if (!["read", "proposal", "external_action", "answer_with_evidence"].includes(String(capability.kind)))
       errors.push({ path: `${path4}.kind`, code: "INVALID_CAPABILITY_KIND", message: "kind must be read, proposal, external_action, or answer_with_evidence." });
     if (!isNonEmptyString2(capability.context) || !contextNames.has(capability.context))
@@ -2993,6 +3064,20 @@ function validateArgs2(value, path4, errors) {
     checkUnknownKeys2(arg, ARG_KEYS2, argPath, errors);
     if (!["string", "number", "boolean"].includes(String(arg.type)))
       errors.push({ path: `${argPath}.type`, code: "INVALID_ARG_TYPE", message: "arg type must be string, number, or boolean." });
+    if (arg.description !== void 0 && !isNonEmptyString2(arg.description))
+      errors.push({ path: `${argPath}.description`, code: "INVALID_ARG_DESCRIPTION", message: "arg description must be a non-empty string." });
+    if (arg.max_length !== void 0 && (!Number.isInteger(arg.max_length) || Number(arg.max_length) <= 0))
+      errors.push({ path: `${argPath}.max_length`, code: "INVALID_MAX_LENGTH", message: "max_length must be a positive integer." });
+    if ((arg.minimum !== void 0 || arg.maximum !== void 0) && arg.type !== "number")
+      errors.push({ path: argPath, code: "NUMERIC_BOUNDS_REQUIRE_NUMBER", message: "minimum/maximum can only be used with number args." });
+    if (arg.minimum !== void 0 && !isFiniteNumber2(arg.minimum))
+      errors.push({ path: `${argPath}.minimum`, code: "INVALID_MINIMUM", message: "minimum must be a finite number." });
+    if (arg.maximum !== void 0 && !isFiniteNumber2(arg.maximum))
+      errors.push({ path: `${argPath}.maximum`, code: "INVALID_MAXIMUM", message: "maximum must be a finite number." });
+    if (isFiniteNumber2(arg.minimum) && isFiniteNumber2(arg.maximum) && Number(arg.minimum) > Number(arg.maximum))
+      errors.push({ path: argPath, code: "INVALID_ARG_NUMERIC_RANGE", message: "minimum must be less than or equal to maximum." });
+    if (arg.enum !== void 0 && (!Array.isArray(arg.enum) || arg.enum.length === 0))
+      errors.push({ path: `${argPath}.enum`, code: "INVALID_ARG_ENUM", message: "enum must be a non-empty array when provided." });
   }
 }
 function validateLookup2(value, path4, args, errors) {
@@ -3043,6 +3128,8 @@ function validateProposalAction(value, path4, errors) {
         errors.push({ path: patchPath, code: "PATCH_BINDING_REQUIRED", message: "patch binding must include fixed or from_arg." });
     }
   }
+  validateNumericBounds2(value.numeric_bounds, value.patch, `${path4}.numeric_bounds`, errors);
+  validateTransitionGuards2(value.transition_guards, value.patch, `${path4}.transition_guards`, errors);
   if (value.conflict_guard !== void 0) {
     if (!isRecord3(value.conflict_guard))
       errors.push({ path: `${path4}.conflict_guard`, code: "CONFLICT_GUARD_NOT_OBJECT", message: "conflict_guard must be an object." });
@@ -3057,11 +3144,79 @@ 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." });
   }
 }
+function validateNumericBounds2(value, patch, path4, errors) {
+  if (value === void 0)
+    return;
+  if (!isRecord3(value)) {
+    errors.push({ path: path4, code: "NUMERIC_BOUNDS_NOT_OBJECT", message: "numeric_bounds must map patch fields to numeric bounds." });
+    return;
+  }
+  const patchFields = isRecord3(patch) ? new Set(Object.keys(patch)) : /* @__PURE__ */ new Set();
+  for (const [field, bounds] of Object.entries(value)) {
+    const boundPath = `${path4}.${field}`;
+    if (!isSafeIdentifier2(field))
+      errors.push({ path: boundPath, code: "INVALID_NUMERIC_BOUND_FIELD", message: "numeric_bounds keys must be safe patch fields." });
+    if (!patchFields.has(field))
+      errors.push({ path: boundPath, code: "NUMERIC_BOUND_PATCH_FIELD_REQUIRED", message: "numeric_bounds can only constrain fields in proposal.patch." });
+    if (!isRecord3(bounds)) {
+      errors.push({ path: boundPath, code: "NUMERIC_BOUND_NOT_OBJECT", message: "numeric bound must be an object." });
+      continue;
+    }
+    checkUnknownKeys2(bounds, NUMERIC_BOUND_KEYS2, boundPath, errors);
+    const hasMinimum = bounds.minimum !== void 0;
+    const hasMaximum = bounds.maximum !== void 0;
+    if (!hasMinimum && !hasMaximum)
+      errors.push({ path: boundPath, code: "NUMERIC_BOUND_EMPTY", message: "numeric bound must define minimum, maximum, or both." });
+    if (hasMinimum && !isFiniteNumber2(bounds.minimum))
+      errors.push({ path: `${boundPath}.minimum`, code: "INVALID_MINIMUM", message: "minimum must be a finite number." });
+    if (hasMaximum && !isFiniteNumber2(bounds.maximum))
+      errors.push({ path: `${boundPath}.maximum`, code: "INVALID_MAXIMUM", message: "maximum must be a finite number." });
+    if (isFiniteNumber2(bounds.minimum) && isFiniteNumber2(bounds.maximum) && Number(bounds.minimum) > Number(bounds.maximum)) {
+      errors.push({ path: boundPath, code: "INVALID_NUMERIC_RANGE", message: "minimum must be less than or equal to maximum." });
+    }
+  }
+}
+function validateTransitionGuards2(value, patch, path4, errors) {
+  if (value === void 0)
+    return;
+  if (!isRecord3(value)) {
+    errors.push({ path: path4, code: "TRANSITION_GUARDS_NOT_OBJECT", message: "transition_guards must map patch fields to allowed state transitions." });
+    return;
+  }
+  const patchFields = isRecord3(patch) ? new Set(Object.keys(patch)) : /* @__PURE__ */ new Set();
+  for (const [field, guard] of Object.entries(value)) {
+    const guardPath = `${path4}.${field}`;
+    if (!isSafeIdentifier2(field))
+      errors.push({ path: guardPath, code: "INVALID_TRANSITION_GUARD_FIELD", message: "transition_guards keys must be safe patch fields." });
+    if (!patchFields.has(field))
+      errors.push({ path: guardPath, code: "TRANSITION_GUARD_PATCH_FIELD_REQUIRED", message: "transition_guards can only constrain fields in proposal.patch." });
+    if (!isRecord3(guard)) {
+      errors.push({ path: guardPath, code: "TRANSITION_GUARD_NOT_OBJECT", message: "transition guard must be an object." });
+      continue;
+    }
+    checkUnknownKeys2(guard, TRANSITION_GUARD_KEYS2, guardPath, errors);
+    if (guard.from_column !== void 0 && !isSafeIdentifier2(guard.from_column)) {
+      errors.push({ path: `${guardPath}.from_column`, code: "INVALID_TRANSITION_FROM_COLUMN", message: "from_column must be a safe identifier." });
+    }
+    if (!isRecord3(guard.allowed) || Object.keys(guard.allowed).length === 0) {
+      errors.push({ path: `${guardPath}.allowed`, code: "TRANSITION_ALLOWED_REQUIRED", message: "transition guard must define allowed transitions." });
+      continue;
+    }
+    for (const [from, toValues] of Object.entries(guard.allowed)) {
+      const allowedPath = `${guardPath}.allowed.${from}`;
+      if (!isNonEmptyString2(from))
+        errors.push({ path: allowedPath, code: "TRANSITION_FROM_REQUIRED", message: "transition source state must be a non-empty string." });
+      if (!Array.isArray(toValues) || toValues.length === 0 || toValues.some((item) => !isNonEmptyString2(item))) {
+        errors.push({ path: allowedPath, code: "TRANSITION_TO_VALUES_REQUIRED", message: "transition target states must be non-empty strings." });
+      }
+    }
+  }
+}
 function validateWorkflows(value, contextNames, capabilityNames, errors) {
   if (value === void 0)
     return;
@@ -3245,6 +3400,9 @@ function isQualifiedOrSafeName(value) {
 function isPositiveInteger2(value) {
   return Number.isInteger(value) && Number(value) > 0;
 }
+function isFiniteNumber2(value) {
+  return typeof value === "number" && Number.isFinite(value);
+}
 
 // packages/spec/dist/normalize.js
 function normalizeContract(input) {
@@ -3296,20 +3454,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 +3489,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));
   }
 }
@@ -3350,6 +3520,7 @@ function runtimeCapabilityFromSpec(capability, resources, config) {
     name: capability.name,
     kind: capability.kind === "proposal" ? "proposal" : "read",
     ...capability.description ? { description: capability.description } : {},
+    ...capability.returns_hint ? { returns_hint: capability.returns_hint } : {},
     source,
     context: capability.context,
     target: target2,
@@ -3362,9 +3533,15 @@ function runtimeCapabilityFromSpec(capability, resources, config) {
   if (capability.kind === "proposal" && capability.proposal) {
     runtime.patch = capability.proposal.patch;
     runtime.allowed_columns = capability.proposal.allowed_fields;
+    runtime.numeric_bounds = capability.proposal.numeric_bounds;
+    runtime.transition_guards = capability.proposal.transition_guards;
     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;
     }
   }
@@ -3522,11 +3699,11 @@ async function serveStdio(options = {}) {
   const transport = new StdioServerTransport();
   await server.connect(transport);
   process.stderr.write("synapsor-runner MCP stdio server ready. Waiting for an MCP client on stdio; logs stay on stderr.\n");
-  await new Promise((resolve) => {
+  await new Promise((resolve2) => {
     const previousOnClose = transport.onclose;
     const close = () => {
       runtime.close();
-      resolve();
+      resolve2();
     };
     transport.onclose = () => {
       previousOnClose?.();
@@ -3545,7 +3722,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.`);
   }
@@ -3569,11 +3746,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) {
@@ -3611,7 +3788,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.`);
   }
@@ -3638,11 +3815,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) {
@@ -3966,20 +4143,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));
 }
@@ -4023,8 +4200,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({
@@ -4106,6 +4283,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);
@@ -4275,7 +4455,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.`,
@@ -4330,6 +4510,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,
@@ -4389,6 +4607,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", {
@@ -4436,8 +4657,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()
@@ -4460,7 +4681,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();
@@ -4482,7 +4703,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 {
@@ -4537,8 +4758,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" };
   }
@@ -4551,8 +4772,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)) {
@@ -6421,7 +6653,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));
   }
 }
 
@@ -6453,7 +6685,7 @@ function parseAgentDsl(source) {
   }
   return { contexts, capabilities, workflows };
 }
-function compileAgentDsl(source) {
+function compileAgentDslWithWarnings(source) {
   const ast = parseAgentDsl(source);
   const contexts = ast.contexts.map((context) => ({
     name: context.name,
@@ -6465,6 +6697,8 @@ function compileAgentDsl(source) {
     const spec = {
       name: capability.name,
       kind: capability.kind,
+      ...capability.description ? { description: capability.description } : {},
+      ...capability.returnsHint ? { returns_hint: capability.returnsHint } : {},
       context: capability.context,
       ...capability.source ? { source: capability.source } : {},
       subject: {
@@ -6474,7 +6708,7 @@ function compileAgentDsl(source) {
         ...capability.tenantKey ? { tenant_key: capability.tenantKey } : {},
         ...capability.conflictKey ? { conflict_key: capability.conflictKey } : {}
       },
-      args: capability.args,
+      args: specArgsFromDsl(capability.args),
       ...capability.lookup ? { lookup: { id_from_arg: capability.lookup.arg } } : {},
       visible_fields: capability.visibleFields,
       ...capability.keptOutFields.length ? { kept_out_fields: capability.keptOutFields } : {},
@@ -6486,6 +6720,8 @@ function compileAgentDsl(source) {
         action: capability.proposal.action,
         allowed_fields: capability.proposal.allowedFields,
         patch: capability.proposal.patch,
+        ...capability.proposal.numericBounds ? { numeric_bounds: capability.proposal.numericBounds } : {},
+        ...capability.proposal.transitionGuards ? { transition_guards: capability.proposal.transitionGuards } : {},
         conflict_guard: capability.conflictKey ? { column: capability.conflictKey } : { weak_guard_ack: true },
         approval: { mode: "human", required_role: capability.proposal.approvalRole ?? "local_reviewer" },
         writeback: {
@@ -6512,12 +6748,12 @@ function compileAgentDsl(source) {
     ...workflows.length ? { workflows } : {}
   };
   assertValidContract(contract);
-  return normalizeContract(contract);
+  return { contract: normalizeContract(contract), warnings: collectDslWarnings(ast) };
 }
 function validateAgentDsl(source) {
   try {
-    compileAgentDsl(source);
-    return { ok: true, errors: [], warnings: [] };
+    const result = compileAgentDslWithWarnings(source);
+    return { ok: true, errors: [], warnings: result.warnings };
   } catch (error) {
     if (error instanceof AgentDslError) {
       return {
@@ -6602,6 +6838,7 @@ function parseContextBlock(block) {
 function parseCapabilityBlock(block) {
   const capability = {
     name: block.name,
+    line: block.line,
     kind: "read",
     context: "",
     schema: "",
@@ -6612,6 +6849,16 @@ function parseCapabilityBlock(block) {
     keptOutFields: []
   };
   for (const item of block.body) {
+    const description = item.text.match(/^DESCRIPTION\s+'(.*)'$/i);
+    if (description) {
+      capability.description = description[1] ?? "";
+      continue;
+    }
+    const returnsHint = item.text.match(/^RETURNS\s+HINT\s+'(.*)'$/i);
+    if (returnsHint) {
+      capability.returnsHint = returnsHint[1] ?? "";
+      continue;
+    }
     const context = item.text.match(/^USING\s+CONTEXT\s+([A-Za-z_][A-Za-z0-9_.]*)$/i);
     if (context?.[1]) {
       capability.context = context[1];
@@ -6643,13 +6890,9 @@ function parseCapabilityBlock(block) {
       capability.conflictKey = conflict3[1];
       continue;
     }
-    const arg = item.text.match(/^ARG\s+([A-Za-z_][A-Za-z0-9_]*)\s+(STRING|TEXT|NUMBER|BOOLEAN|BOOL)(?:\s+REQUIRED)?(?:\s+MAX\s+(\d+))?$/i);
+    const arg = item.text.match(/^ARG\s+([A-Za-z_][A-Za-z0-9_]*)\s+(STRING|TEXT|NUMBER|BOOLEAN|BOOL)\b(.*)$/i);
     if (arg?.[1] && arg[2]) {
-      capability.args[arg[1]] = {
-        type: normalizeArgType(arg[2]),
-        ...item.text.match(/\sREQUIRED(?:\s|$)/i) ? { required: true } : {},
-        ...arg[3] ? { max_length: Number(arg[3]) } : {}
-      };
+      capability.args[arg[1]] = parseArgSpec(arg[1], arg[2], arg[3] ?? "", item.line);
       continue;
     }
     const lookup = item.text.match(/^LOOKUP\s+([A-Za-z_][A-Za-z0-9_]*)\s+BY\s+([A-Za-z_][A-Za-z0-9_]*)$/i);
@@ -6699,6 +6942,30 @@ function parseCapabilityBlock(block) {
         capability.proposal.allowedFields.push(patch[1]);
       continue;
     }
+    const bound = item.text.match(/^BOUND\s+([A-Za-z_][A-Za-z0-9_]*)\s+(-?\d+(?:\.\d+)?)?\s*\.\.\s*(-?\d+(?:\.\d+)?)?$/i);
+    if (bound?.[1]) {
+      ensureProposal(capability, item);
+      const minimum = bound[2] !== void 0 ? Number(bound[2]) : void 0;
+      const maximum = bound[3] !== void 0 ? Number(bound[3]) : void 0;
+      if (minimum === void 0 && maximum === void 0)
+        throw dslError(item.line, 1, "BOUND_RANGE_REQUIRED", "BOUND requires minimum, maximum, or both, such as 1..2500");
+      capability.proposal.numericBounds ??= {};
+      capability.proposal.numericBounds[bound[1]] = {
+        ...minimum !== void 0 ? { minimum } : {},
+        ...maximum !== void 0 ? { maximum } : {}
+      };
+      continue;
+    }
+    const transition = item.text.match(/^TRANSITION\s+([A-Za-z_][A-Za-z0-9_]*)(?:\s+FROM\s+([A-Za-z_][A-Za-z0-9_]*))?\s+ALLOW\s+(.+)$/i);
+    if (transition?.[1] && transition[3]) {
+      ensureProposal(capability, item);
+      capability.proposal.transitionGuards ??= {};
+      capability.proposal.transitionGuards[transition[1]] = {
+        ...transition[2] ? { from_column: transition[2] } : {},
+        allowed: parseTransitionAllowed(transition[3], item.line)
+      };
+      continue;
+    }
     const approval = item.text.match(/^APPROVAL\s+ROLE\s+([A-Za-z_][A-Za-z0-9_.-]*)$/i);
     if (approval?.[1]) {
       ensureProposal(capability, item);
@@ -6731,6 +6998,40 @@ function parseCapabilityBlock(block) {
     throw dslError(block.line, 1, "PROPOSAL_PATCH_REQUIRED", `${block.name} proposal requires at least one PATCH line`);
   return capability;
 }
+function specArgsFromDsl(args) {
+  return Object.fromEntries(Object.entries(args).map(([name, arg]) => {
+    const { line: _line, ...spec } = arg;
+    return [name, spec];
+  }));
+}
+function collectDslWarnings(ast) {
+  const warnings = [];
+  for (const capability of ast.capabilities) {
+    if (capability.kind !== "proposal" || !capability.proposal)
+      continue;
+    const line = capability.line ?? 1;
+    if (!capability.description) {
+      warnings.push({ line, column: 1, code: "DESCRIPTION_RECOMMENDED", message: `${capability.name} is a proposal capability without DESCRIPTION.` });
+    }
+    if (!capability.returnsHint) {
+      warnings.push({ line, column: 1, code: "RETURNS_HINT_RECOMMENDED", message: `${capability.name} is a proposal capability without RETURNS HINT.` });
+    }
+    for (const [column, binding] of Object.entries(capability.proposal.patch)) {
+      if (!binding.from_arg)
+        continue;
+      const arg = capability.args[binding.from_arg];
+      if (arg?.type === "number" && arg.minimum === void 0 && arg.maximum === void 0 && capability.proposal.numericBounds?.[column] === void 0) {
+        warnings.push({
+          line: arg.line ?? line,
+          column: 1,
+          code: "NUMERIC_PATCH_BOUND_RECOMMENDED",
+          message: `${capability.name} patches ${column} from numeric arg ${binding.from_arg} without ARG MIN/MAX or BOUND ${column}.`
+        });
+      }
+    }
+  }
+  return warnings;
+}
 function parseWorkflowBlock(block) {
   const workflow = { name: block.name, context: "", allowedCapabilities: [] };
   for (const item of block.body) {
@@ -6788,6 +7089,76 @@ function parsePatchBinding(raw) {
     return { fixed: quoted[1] ?? "" };
   return { fixed: trimmed };
 }
+function parseArgSpec(name, rawType, rawOptions, line) {
+  const type = normalizeArgType(rawType);
+  let rest = rawOptions.trim();
+  let description;
+  const descriptionMatch = rest.match(/\bDESCRIPTION\s+'([^']*)'/i);
+  if (descriptionMatch) {
+    description = descriptionMatch[1] ?? "";
+    rest = `${rest.slice(0, descriptionMatch.index)} ${rest.slice((descriptionMatch.index ?? 0) + descriptionMatch[0].length)}`.trim();
+  }
+  const required = /\bREQUIRED\b/i.test(rest);
+  rest = rest.replace(/\bREQUIRED\b/ig, " ").trim();
+  const maxLengthMatch = rest.match(/\bMAX\s+LENGTH\s+(\d+)\b/i);
+  const maxLength = maxLengthMatch?.[1] ? Number(maxLengthMatch[1]) : void 0;
+  if (maxLengthMatch)
+    rest = `${rest.slice(0, maxLengthMatch.index)} ${rest.slice((maxLengthMatch.index ?? 0) + maxLengthMatch[0].length)}`.trim();
+  const minMatch = rest.match(/\bMIN\s+(-?\d+(?:\.\d+)?)\b/i);
+  const minimum = minMatch?.[1] ? Number(minMatch[1]) : void 0;
+  if (minMatch)
+    rest = `${rest.slice(0, minMatch.index)} ${rest.slice((minMatch.index ?? 0) + minMatch[0].length)}`.trim();
+  const maxMatch = rest.match(/\bMAX\s+(-?\d+(?:\.\d+)?)\b/i);
+  const maximumOrLegacyLength = maxMatch?.[1] ? Number(maxMatch[1]) : void 0;
+  if (maxMatch)
+    rest = `${rest.slice(0, maxMatch.index)} ${rest.slice((maxMatch.index ?? 0) + maxMatch[0].length)}`.trim();
+  if (rest.trim().length > 0) {
+    throw dslError(line, 1, "ARG_OPTIONS_UNSUPPORTED", `unsupported ARG options for ${name}: ${rest.trim()}`);
+  }
+  if (type !== "number" && minimum !== void 0) {
+    throw dslError(line, 1, "ARG_MIN_REQUIRES_NUMBER", `ARG ${name} uses MIN, but MIN is only valid for NUMBER args`);
+  }
+  if (type === "boolean" && (maxLength !== void 0 || maximumOrLegacyLength !== void 0)) {
+    throw dslError(line, 1, "ARG_MAX_INVALID_FOR_BOOLEAN", `ARG ${name} cannot use MAX or MAX LENGTH because BOOLEAN has no numeric or length bound`);
+  }
+  if (type === "number" && maxLength !== void 0) {
+    throw dslError(line, 1, "ARG_MAX_LENGTH_REQUIRES_TEXT", `ARG ${name} uses MAX LENGTH, but MAX LENGTH is only valid for STRING/TEXT args`);
+  }
+  return {
+    type,
+    line,
+    ...required ? { required: true } : {},
+    ...description !== void 0 ? { description } : {},
+    ...type === "number" && minimum !== void 0 ? { minimum } : {},
+    ...type === "number" && maximumOrLegacyLength !== void 0 ? { maximum: maximumOrLegacyLength } : {},
+    ...type !== "number" && maxLength !== void 0 ? { max_length: maxLength } : {},
+    ...type !== "number" && maxLength === void 0 && maximumOrLegacyLength !== void 0 ? { max_length: maximumOrLegacyLength } : {}
+  };
+}
+function parseTransitionAllowed(raw, line) {
+  const allowed = {};
+  for (const item of raw.split(",").map((part) => part.trim()).filter(Boolean)) {
+    const match = item.match(/^(.+?)\s*->\s*(.+)$/);
+    if (!match?.[1] || !match[2]) {
+      throw dslError(line, 1, "TRANSITION_RULE_INVALID", `transition rule must use from -> to syntax: ${item}`);
+    }
+    const from = parseStateValue(match[1]);
+    const toValues = match[2].split("|").map(parseStateValue).filter(Boolean);
+    if (!from || toValues.length === 0) {
+      throw dslError(line, 1, "TRANSITION_RULE_INVALID", `transition rule must name non-empty states: ${item}`);
+    }
+    allowed[from] = toValues;
+  }
+  if (Object.keys(allowed).length === 0) {
+    throw dslError(line, 1, "TRANSITION_ALLOWED_REQUIRED", "TRANSITION requires at least one from -> to rule");
+  }
+  return allowed;
+}
+function parseStateValue(raw) {
+  const trimmed = raw.trim();
+  const quoted = trimmed.match(/^'(.*)'$/);
+  return (quoted?.[1] ?? trimmed).trim();
+}
 function normalizeBindingSource(source) {
   const normalized = source.toUpperCase();
   if (normalized === "ENV")
@@ -6857,11 +7228,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();
@@ -6874,10 +7245,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();
       });
     })
   };
@@ -8720,7 +9091,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.",
@@ -9194,12 +9565,15 @@ async function dslValidate(args) {
   const target2 = firstPositional(args);
   if (!target2) throw new Error("dsl validate requires <contract.synapsor>");
   const source = await fs3.readFile(target2, "utf8");
+  const strict = args.includes("--strict");
   const result = validateAgentDsl(source);
   if (args.includes("--json")) {
     process2.stdout.write(`${JSON.stringify(result, null, 2)}
 `);
   } else if (result.ok) {
     process2.stdout.write(`dsl valid: ${target2}
+`);
+    for (const warning of result.warnings) process2.stdout.write(`warning ${warning.line}:${warning.column} ${warning.code}: ${warning.message}
 `);
   } else {
     process2.stdout.write(`dsl invalid: ${target2}
@@ -9207,13 +9581,22 @@ async function dslValidate(args) {
     for (const error of result.errors) process2.stdout.write(`error ${error.line}:${error.column} ${error.code}: ${error.message}
 `);
   }
-  return result.ok ? 0 : 1;
+  return result.ok && (!strict || result.warnings.length === 0) ? 0 : 1;
 }
 async function dslCompile(args) {
   const target2 = firstPositional(args);
   if (!target2) throw new Error("dsl compile requires <contract.synapsor>");
   const source = await fs3.readFile(target2, "utf8");
-  const contract = compileAgentDsl(source);
+  const strict = args.includes("--strict");
+  const result = compileAgentDslWithWarnings(source);
+  if (strict && result.warnings.length > 0) {
+    process2.stdout.write(`dsl warnings treated as errors: ${target2}
+`);
+    for (const warning of result.warnings) process2.stdout.write(`warning ${warning.line}:${warning.column} ${warning.code}: ${warning.message}
+`);
+    return 1;
+  }
+  const contract = result.contract;
   const output = outputArg(args);
   const text = `${JSON.stringify(contract, null, 2)}
 `;
@@ -9224,6 +9607,8 @@ async function dslCompile(args) {
   } else {
     process2.stdout.write(text);
   }
+  for (const warning of result.warnings) process2.stderr.write(`warning ${warning.line}:${warning.column} ${warning.code}: ${warning.message}
+`);
   return 0;
 }
 async function contractValidate(args) {
@@ -9353,8 +9738,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)}
 `);
@@ -9375,6 +9759,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"));
@@ -9438,13 +9846,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);
@@ -9494,7 +9938,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]) {
@@ -9837,15 +10281,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."));
       }
@@ -9900,11 +10344,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));
     });
   });
 }
@@ -9924,9 +10368,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,
@@ -9936,6 +10381,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");
@@ -9945,14 +10393,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`,
@@ -9966,7 +10419,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) {
@@ -9994,7 +10447,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) {
@@ -10108,7 +10561,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) {
@@ -10299,7 +10752,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) {
@@ -10316,6 +10769,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",
@@ -10373,16 +10829,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) {
@@ -10401,8 +10860,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];
@@ -10427,7 +10890,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",
@@ -10435,7 +10898,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}`;
   }
@@ -10450,7 +10913,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);
   }
@@ -10488,7 +10951,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`);
@@ -10738,7 +11201,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 = "";
@@ -10747,7 +11210,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");
@@ -10772,7 +11235,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(", ")}`);
@@ -10790,7 +11253,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");
@@ -10979,7 +11442,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}`
     );
   }
@@ -10998,12 +11461,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}`;
   });
@@ -11018,14 +11488,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;
@@ -11069,19 +11539,33 @@ async function cloudPush(args) {
   if (!target2) throw new Error("cloud push requires <synapsor.contract.json>");
   const parsed = JSON.parse(await fs3.readFile(target2, "utf8"));
   const contract = normalizeContract(parsed);
+  const workspace = (optionalArg(args, "--workspace") ?? optionalArg(args, "--project") ?? process2.env.SYNAPSOR_WORKSPACE_ID ?? process2.env.SYNAPSOR_PROJECT_ID ?? "").trim();
+  const name = (optionalArg(args, "--name") ?? contract.metadata?.name ?? "").trim();
+  const description = (optionalArg(args, "--description") ?? contract.metadata?.description ?? "").trim();
+  const idempotencyKey = optionalArg(args, "--idempotency-key");
   const payload = {
     schema_version: "synapsor.cloud-contract-push.v0.1",
     contract,
     summary: contractSummary(contract),
-    workspace: optionalArg(args, "--workspace") ?? process2.env.SYNAPSOR_WORKSPACE_ID,
-    name: optionalArg(args, "--name") ?? contract.metadata?.name,
+    workspace,
+    name,
+    description,
+    source: "runner",
+    source_versions: {
+      "@synapsor/runner": process2.env.npm_package_version ?? "unknown"
+    },
+    activate: args.includes("--activate"),
+    idempotency_key: idempotencyKey,
     pushed_at: (/* @__PURE__ */ new Date()).toISOString()
   };
   const dryRun = args.includes("--dry-run");
-  if (args.includes("--json")) {
+  const json = args.includes("--json");
+  if (dryRun && json) {
     process2.stdout.write(`${JSON.stringify({ ok: dryRun, dry_run: dryRun, payload }, null, 2)}
 `);
-  } else {
+    return 0;
+  }
+  if (dryRun) {
     process2.stdout.write("Synapsor Cloud contract push preview\n");
     process2.stdout.write(`Contract: ${target2}
 `);
@@ -11095,17 +11579,48 @@ async function cloudPush(args) {
 `);
     process2.stdout.write(`Kept-out fields: ${payload.summary.kept_out_fields}
 `);
-  }
-  if (dryRun) {
-    if (!args.includes("--json")) process2.stdout.write("Dry run only. No Cloud upload attempted.\n");
+    process2.stdout.write("Dry run only. No Cloud upload attempted.\n");
     return 0;
   }
-  const apiUrl = optionalArg(args, "--api-url") ?? process2.env.SYNAPSOR_CLOUD_BASE_URL;
-  const token = optionalArg(args, "--token") ?? process2.env.SYNAPSOR_CLOUD_TOKEN ?? process2.env.SYNAPSOR_RUNNER_TOKEN;
+  const apiUrl = (optionalArg(args, "--api-url") ?? process2.env.SYNAPSOR_CLOUD_BASE_URL ?? "").trim();
+  const token = (optionalArg(args, "--token") ?? process2.env.SYNAPSOR_CLOUD_TOKEN ?? process2.env.SYNAPSOR_RUNNER_TOKEN ?? "").trim();
+  if (!workspace) {
+    throw new Error("cloud push upload requires --workspace <project_id> or SYNAPSOR_WORKSPACE_ID/SYNAPSOR_PROJECT_ID.");
+  }
   if (!apiUrl || !token) {
-    throw new Error("cloud push upload requires --dry-run, or real --api-url plus --token/SYNAPSOR_CLOUD_TOKEN after the Cloud registry endpoint is available.");
+    throw new Error("cloud push upload requires --api-url plus --token/SYNAPSOR_CLOUD_TOKEN. Use --dry-run for local validation without a network call.");
+  }
+  const response = await postCloudContractPush({
+    apiUrl,
+    token,
+    workspace,
+    payload,
+    idempotencyKey
+  });
+  if (json) {
+    process2.stdout.write(`${JSON.stringify(response, null, 2)}
+`);
+    return 0;
   }
-  throw new Error("cloud push upload is not wired to a Cloud registry endpoint yet. Use --dry-run for local validation; do not treat this as uploaded.");
+  const contractId = cloudStringField(response, "contract_id") || cloudStringField(response.contract, "contract_id");
+  const versionId = cloudStringField(response, "contract_version_id") || cloudStringField(response.version, "contract_version_id");
+  const digest = cloudStringField(response, "digest") || cloudStringField(response.version, "digest");
+  const status = cloudStringField(response, "status") || cloudStringField(response.version, "status") || "stored";
+  process2.stdout.write("Synapsor Cloud contract push complete\n");
+  process2.stdout.write(`Workspace: ${workspace}
+`);
+  if (contractId) process2.stdout.write(`Contract id: ${contractId}
+`);
+  if (versionId) process2.stdout.write(`Version id: ${versionId}
+`);
+  if (digest) process2.stdout.write(`Digest: ${digest}
+`);
+  process2.stdout.write(`Status: ${status}
+`);
+  const registryUrl = cloudStringField(response, "registry_url");
+  if (registryUrl) process2.stdout.write(`Registry: ${registryUrl}
+`);
+  return 0;
 }
 function contractSummary(contract) {
   return {
@@ -11116,6 +11631,81 @@ function contractSummary(contract) {
     kept_out_fields: contract.capabilities.reduce((count, capability) => count + (capability.kept_out_fields?.length ?? 0), 0)
   };
 }
+async function postCloudContractPush(input) {
+  let endpoint;
+  try {
+    endpoint = new URL(`/v1/control/projects/${encodeURIComponent(input.workspace)}/agent-contracts`, input.apiUrl.endsWith("/") ? input.apiUrl : `${input.apiUrl}/`);
+  } catch {
+    throw new Error("cloud push upload failed: --api-url/SYNAPSOR_CLOUD_BASE_URL is not a valid URL.");
+  }
+  const headers = {
+    accept: "application/json",
+    authorization: `Bearer ${input.token}`,
+    "content-type": "application/json",
+    "user-agent": "synapsor-runner-cloud-push"
+  };
+  if (input.idempotencyKey) headers["idempotency-key"] = input.idempotencyKey;
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 15e3);
+  let response;
+  try {
+    response = await fetch(endpoint, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(input.payload),
+      signal: controller.signal
+    });
+  } catch (error) {
+    const reason = error instanceof Error && (error.name === "AbortError" || error.name === "TimeoutError") ? "request timed out" : "network request failed";
+    throw new Error(`cloud push upload failed: ${reason}. Check --api-url/SYNAPSOR_CLOUD_BASE_URL and network connectivity.`);
+  } finally {
+    clearTimeout(timeout);
+  }
+  const text = await response.text();
+  const body = parseCloudResponseJson(text);
+  if (!response.ok || body.ok === false) {
+    throw new Error(cloudPushErrorMessage(response.status, body));
+  }
+  return body;
+}
+function parseCloudResponseJson(text) {
+  if (!text.trim()) return {};
+  try {
+    const parsed = JSON.parse(text);
+    return isRecord7(parsed) ? parsed : { value: parsed };
+  } catch {
+    return { raw: text.slice(0, 500) };
+  }
+}
+function cloudPushErrorMessage(status, body) {
+  const code = typeof body.error === "string" && body.error ? body.error : `http_${status}`;
+  const detail = cloudValidationDetail(body);
+  if (status === 401) return `cloud push upload failed: token is missing, invalid, or expired (${code}).`;
+  if (status === 403) return `cloud push upload failed: token does not have permission to write this workspace (${code}).`;
+  if (status === 404) return `cloud push upload failed: Cloud API URL or workspace was not found (${code}).`;
+  if (status === 409) return `cloud push upload failed: registry conflict (${code}).${detail}`;
+  if (status === 422) return `cloud push upload failed: Cloud rejected the contract (${code}).${detail}`;
+  if (status >= 500) return `cloud push upload failed: Cloud returned HTTP ${status} (${code}).`;
+  return `cloud push upload failed: Cloud returned HTTP ${status} (${code}).${detail}`;
+}
+function cloudValidationDetail(body) {
+  const errors = Array.isArray(body.errors) ? body.errors : [];
+  if (!errors.length) {
+    const message = typeof body.message === "string" ? body.message : "";
+    return message ? ` ${message}` : "";
+  }
+  const rendered = errors.slice(0, 3).map((issue) => {
+    if (!isRecord7(issue)) return String(issue);
+    const path4 = typeof issue.path === "string" ? issue.path : "$";
+    const code = typeof issue.code === "string" ? issue.code : "validation_error";
+    const message = typeof issue.message === "string" ? issue.message : "";
+    return `${path4} ${code}${message ? `: ${message}` : ""}`;
+  }).join("; ");
+  return ` ${rendered}`;
+}
+function cloudStringField(value, key) {
+  return isRecord7(value) && typeof value[key] === "string" ? value[key] : "";
+}
 async function cloudConnect(args) {
   const configPath = optionalArg(args, "--config") ?? process2.env.SYNAPSOR_MCP_CONFIG ?? "synapsor.cloud.json";
   const parsed = JSON.parse(await fs3.readFile(configPath, "utf8"));
@@ -11126,8 +11716,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(", ")}
@@ -11303,7 +11893,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)"}`);
@@ -11929,13 +12519,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);
@@ -11977,13 +12567,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);
@@ -12989,7 +13579,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 {
@@ -13015,7 +13605,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"]
@@ -13053,7 +13643,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" } } })}
 `);
@@ -13152,12 +13742,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);
@@ -13670,7 +14260,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)}
@@ -13681,7 +14271,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);
@@ -13690,7 +14280,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");
@@ -13704,7 +14294,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 () => {
@@ -13739,7 +14329,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)}
@@ -13750,7 +14340,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);
@@ -14124,9 +14714,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__";
@@ -14346,11 +14946,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}`);
 }
@@ -14416,6 +15016,7 @@ function firstPositional(args) {
   const flagsWithValues = /* @__PURE__ */ new Set([
     "--allowed-columns",
     "--approval-role",
+    "--api-url",
     "--actor",
     "--action",
     "--auth-token-env",
@@ -14426,6 +15027,7 @@ function firstPositional(args) {
     "--conflict-column",
     "--cors-origin",
     "--database-url-env",
+    "--description",
     "--destination",
     "--engine",
     "--evidence",
@@ -14481,10 +15083,12 @@ function firstPositional(args) {
     "--tenant-env",
     "--tenant-key",
     "--timeout-ms",
+    "--token",
     "--to",
     "--transition-guard",
     "--url",
     "--visible-columns",
+    "--workspace",
     "--writeback-job",
     "--write-url-env"
   ]);