@synapsor/runner 0.1.1 → 0.1.2

package/dist/runner.mjs

@@ -444,7 +444,7 @@ function sleep(ms) {
 }
 
 // packages/config/src/index.ts
-var TOP_LEVEL_KEYS = /* @__PURE__ */ new Set(["version", "mode", "storage", "sources", "trusted_context", "contexts", "executors", "capabilities", "cloud", "strict", "result_format"]);
+var TOP_LEVEL_KEYS = /* @__PURE__ */ new Set(["version", "mode", "storage", "sources", "trusted_context", "contexts", "executors", "capabilities", "contracts", "cloud", "strict", "result_format"]);
 var STORAGE_KEYS = /* @__PURE__ */ new Set(["sqlite_path"]);
 var CLOUD_KEYS = /* @__PURE__ */ new Set(["base_url_env", "runner_token_env", "runner_id", "runner_version", "project_id", "adapter_id", "source_id", "engines", "capabilities", "session"]);
 var SOURCE_KEYS = /* @__PURE__ */ new Set([
@@ -559,16 +559,33 @@ function validateRunnerCapabilityConfig(input) {
     errors.push({ path: "$.mode", code: "INVALID_MODE", message: "mode must be read_only, shadow, review, or cloud." });
   }
   validateStorage(input.storage, strict, errors);
+  const hasContracts = validateContracts(input.contracts, errors);
   validateCloud(input.cloud, input.mode, strict, errors);
   validateSources(input.sources, input.mode, strict, errors, warnings);
   validateContexts(input.contexts, strict, errors, warnings);
-  validateTrustedContext(input.trusted_context, input.contexts, input.capabilities, input.mode, strict, errors, warnings);
+  validateTrustedContext(input.trusted_context, input.contexts, input.capabilities, input.mode, strict, errors, warnings, hasContracts);
   validateExecutors(input.executors, input.mode, strict, errors);
-  validateCapabilities(input.capabilities, input.sources, input.contexts, input.executors, input.mode, strict, errors, warnings);
+  validateCapabilities(input.capabilities, input.sources, input.contexts, input.executors, input.mode, strict, errors, warnings, hasContracts);
   validateWritebackReadiness(input.sources, input.capabilities, input.mode, errors, warnings);
   scanForForbiddenFields(input, "$", errors);
   return { ok: errors.length === 0, errors, warnings };
 }
+function validateContracts(value, errors) {
+  if (value === void 0) return false;
+  if (!Array.isArray(value) || value.length === 0) {
+    errors.push({ path: "$.contracts", code: "INVALID_CONTRACT_REFERENCES", message: "contracts must be a non-empty array of contract file paths." });
+    return false;
+  }
+  value.forEach((contractPath, index) => {
+    if (!isNonEmptyString(contractPath)) {
+      errors.push({ path: `$.contracts[${index}]`, code: "INVALID_CONTRACT_REFERENCE", message: "contract references must be non-empty file paths." });
+    }
+    if (typeof contractPath === "string" && /(postgres(?:ql)?:\/\/|mysql:\/\/|password|secret|token)/i.test(contractPath)) {
+      errors.push({ path: `$.contracts[${index}]`, code: "CONTRACT_REFERENCE_LOOKS_SECRET", message: "contracts must reference local contract files, not URLs or secrets." });
+    }
+  });
+  return errors.every((error) => !error.path.startsWith("$.contracts"));
+}
 function assertValidRunnerCapabilityConfig(input) {
   const result = validateRunnerCapabilityConfig(input);
   if (!result.ok) {
@@ -765,8 +782,9 @@ function validateContexts(value, strict, errors, warnings) {
     validateContextObject(context, path4, strict, errors, warnings);
   }
 }
-function validateTrustedContext(value, contexts, capabilities, mode, strict, errors, warnings) {
+function validateTrustedContext(value, contexts, capabilities, mode, strict, errors, warnings, hasContracts = false) {
   if (value === void 0) {
+    if (hasContracts) return;
     if (mode === "cloud") return;
     const allCapabilitiesHaveContext = Array.isArray(capabilities) && capabilities.length > 0 && capabilities.every((capability) => isRecord(capability) && isNonEmptyString(capability.context));
     if (isRecord(contexts) && allCapabilitiesHaveContext) return;
@@ -861,8 +879,9 @@ function validateExecutorAuth(value, path4, strict, errors) {
     errors.push({ path: `${path4}.token_env`, code: "EXECUTOR_TOKEN_ENV_REQUIRED", message: "bearer_env auth requires token_env." });
   }
 }
-function validateCapabilities(value, sources, contexts, executors, mode, strict, errors, warnings) {
+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 (!Array.isArray(value) || value.length === 0) {
     errors.push({ path: "$.capabilities", code: "CAPABILITIES_REQUIRED", message: "At least one capability is required." });
     return;
@@ -2693,6 +2712,557 @@ function isRecord2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+// packages/spec/dist/version.js
+var SPEC_VERSION = "0.1";
+
+// packages/spec/dist/errors.js
+var SynapsorSpecValidationError = class extends Error {
+  issues;
+  constructor(issues) {
+    super(`Invalid Synapsor contract:
+${issues.map((issue) => `${issue.path} ${issue.code}: ${issue.message}`).join("\n")}`);
+    this.issues = issues;
+    this.name = "SynapsorSpecValidationError";
+  }
+};
+
+// packages/spec/dist/validate.js
+var TOP_LEVEL_KEYS2 = /* @__PURE__ */ new Set([
+  "spec_version",
+  "kind",
+  "metadata",
+  "resources",
+  "contexts",
+  "capabilities",
+  "workflows",
+  "policies",
+  "evidence",
+  "proposals",
+  "receipts",
+  "replay",
+  "external_actions"
+]);
+var METADATA_KEYS = /* @__PURE__ */ new Set(["name", "description", "version", "tags"]);
+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 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 PATCH_KEYS = /* @__PURE__ */ new Set(["fixed", "from_arg"]);
+var CONFLICT_GUARD_KEYS2 = /* @__PURE__ */ new Set(["column", "weak_guard_ack"]);
+var APPROVAL_KEYS2 = /* @__PURE__ */ new Set(["mode", "required_role"]);
+var WRITEBACK_KEYS = /* @__PURE__ */ new Set(["mode", "executor", "idempotency_key"]);
+var 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"]);
+var PROPOSAL_RECORD_KEYS = /* @__PURE__ */ new Set(["id", "capability", "subject", "status", "diff", "evidence_handle"]);
+var RECEIPT_KEYS = /* @__PURE__ */ new Set(["id", "proposal_id", "status", "idempotency_key", "source_database_mutated", "rows_affected"]);
+var REPLAY_KEYS = /* @__PURE__ */ new Set(["id", "proposal_id", "run_id", "events"]);
+var EXTERNAL_ACTION_KEYS = /* @__PURE__ */ new Set(["id", "action", "handler", "idempotency_key", "receipt"]);
+var TRUSTED_ARG_NAMES = /* @__PURE__ */ new Set([
+  "tenant_id",
+  "tenantId",
+  "principal",
+  "principal_id",
+  "principalId",
+  "schema",
+  "table",
+  "column",
+  "columns",
+  "database_url",
+  "write_url",
+  "read_url",
+  "expected_version",
+  "row_version"
+]);
+function validateContract(input) {
+  const errors = [];
+  const warnings = [];
+  if (!isRecord3(input)) {
+    return {
+      ok: false,
+      errors: [{ path: "$", code: "CONTRACT_NOT_OBJECT", message: "Contract must be a JSON object." }],
+      warnings
+    };
+  }
+  checkUnknownKeys2(input, TOP_LEVEL_KEYS2, "$", errors);
+  if (input.spec_version !== SPEC_VERSION) {
+    errors.push({ path: "$.spec_version", code: "UNSUPPORTED_SPEC_VERSION", message: `spec_version must be ${SPEC_VERSION}.` });
+  }
+  if (input.kind !== "SynapsorContract") {
+    errors.push({ path: "$.kind", code: "INVALID_KIND", message: "kind must be SynapsorContract." });
+  }
+  validateMetadata(input.metadata, "$.metadata", errors);
+  const resourceNames = validateResources(input.resources, errors, warnings);
+  const contextNames = validateContexts2(input.contexts, errors, warnings);
+  const capabilityNames = validateCapabilities2(input.capabilities, contextNames, resourceNames, errors, warnings);
+  validateWorkflows(input.workflows, contextNames, capabilityNames, errors);
+  validatePolicies(input.policies, errors);
+  validateEvidenceRecords(input.evidence, errors);
+  validateProposalRecords(input.proposals, capabilityNames, errors);
+  validateReceiptRecords(input.receipts, errors);
+  validateReplay(input.replay, errors);
+  validateExternalActions(input.external_actions, errors);
+  scanForInlineSecrets(input, "$", errors);
+  return { ok: errors.length === 0, errors, warnings };
+}
+function assertValidContract(input) {
+  const result = validateContract(input);
+  if (!result.ok)
+    throw new SynapsorSpecValidationError(result.errors);
+}
+function validateMetadata(value, path4, errors) {
+  if (value === void 0)
+    return;
+  if (!isRecord3(value)) {
+    errors.push({ path: path4, code: "METADATA_NOT_OBJECT", message: "metadata must be an object." });
+    return;
+  }
+  checkUnknownKeys2(value, METADATA_KEYS, path4, errors);
+  if (value.name !== void 0 && !isNonEmptyString2(value.name))
+    errors.push({ path: `${path4}.name`, code: "INVALID_METADATA_NAME", message: "metadata.name must be a non-empty string." });
+  if (value.tags !== void 0 && (!Array.isArray(value.tags) || value.tags.some((tag) => !isNonEmptyString2(tag)))) {
+    errors.push({ path: `${path4}.tags`, code: "INVALID_METADATA_TAGS", message: "metadata.tags must be an array of non-empty strings." });
+  }
+}
+function validateResources(value, errors, warnings) {
+  const names = /* @__PURE__ */ new Set();
+  if (value === void 0)
+    return names;
+  if (!Array.isArray(value)) {
+    errors.push({ path: "$.resources", code: "RESOURCES_NOT_ARRAY", message: "resources must be an array." });
+    return names;
+  }
+  value.forEach((resource, index) => {
+    const path4 = `$.resources[${index}]`;
+    if (!isRecord3(resource)) {
+      errors.push({ path: path4, code: "RESOURCE_NOT_OBJECT", message: "resource must be an object." });
+      return;
+    }
+    checkUnknownKeys2(resource, RESOURCE_KEYS, path4, errors);
+    if (!isQualifiedOrSafeName(resource.name))
+      errors.push({ path: `${path4}.name`, code: "INVALID_RESOURCE_NAME", message: "resource name must be a safe identifier or qualified name." });
+    else
+      addUnique(names, resource.name, `${path4}.name`, "DUPLICATE_RESOURCE_NAME", errors);
+    if (!["postgres", "mysql", "synapsor"].includes(String(resource.engine)))
+      errors.push({ path: `${path4}.engine`, code: "INVALID_RESOURCE_ENGINE", message: "engine must be postgres, mysql, or synapsor." });
+    for (const key of ["schema", "table", "primary_key"]) {
+      if (!isSafeIdentifier2(resource[key]))
+        errors.push({ path: `${path4}.${key}`, code: "INVALID_RESOURCE_IDENTIFIER", message: `${key} must be a fixed safe identifier.` });
+    }
+    if (resource.tenant_key !== void 0 && !isSafeIdentifier2(resource.tenant_key))
+      errors.push({ path: `${path4}.tenant_key`, code: "INVALID_TENANT_KEY", message: "tenant_key must be a fixed safe identifier." });
+    if (!isSafeIdentifier2(resource.tenant_key) && resource.single_tenant_dev !== true) {
+      errors.push({ path: `${path4}.tenant_key`, code: "TENANT_KEY_REQUIRED", message: "tenant_key is required unless single_tenant_dev is explicitly true." });
+    }
+    if (resource.single_tenant_dev === true)
+      warnings.push({ path: `${path4}.single_tenant_dev`, code: "SINGLE_TENANT_DEV", message: "single_tenant_dev is only for local demos and must not be used for shared tenant data." });
+    if (resource.conflict_key !== void 0 && !isSafeIdentifier2(resource.conflict_key))
+      errors.push({ path: `${path4}.conflict_key`, code: "INVALID_CONFLICT_KEY", message: "conflict_key must be a fixed safe identifier." });
+  });
+  return names;
+}
+function validateContexts2(value, errors, warnings) {
+  const names = /* @__PURE__ */ new Set();
+  if (!Array.isArray(value) || value.length === 0) {
+    errors.push({ path: "$.contexts", code: "CONTEXTS_REQUIRED", message: "At least one context is required." });
+    return names;
+  }
+  value.forEach((context, index) => {
+    const path4 = `$.contexts[${index}]`;
+    if (!isRecord3(context)) {
+      errors.push({ path: path4, code: "CONTEXT_NOT_OBJECT", message: "context must be an object." });
+      return;
+    }
+    checkUnknownKeys2(context, CONTEXT_KEYS2, path4, errors);
+    if (!isQualifiedOrSafeName(context.name))
+      errors.push({ path: `${path4}.name`, code: "INVALID_CONTEXT_NAME", message: "context name must be a safe identifier or qualified name." });
+    else
+      addUnique(names, context.name, `${path4}.name`, "DUPLICATE_CONTEXT_NAME", errors);
+    if (!Array.isArray(context.bindings) || context.bindings.length === 0) {
+      errors.push({ path: `${path4}.bindings`, code: "BINDINGS_REQUIRED", message: "context.bindings must contain trusted/session bindings." });
+      return;
+    }
+    const bindingNames = /* @__PURE__ */ new Set();
+    context.bindings.forEach((binding, bindingIndex) => {
+      const bindingPath = `${path4}.bindings[${bindingIndex}]`;
+      if (!isRecord3(binding)) {
+        errors.push({ path: bindingPath, code: "BINDING_NOT_OBJECT", message: "binding must be an object." });
+        return;
+      }
+      checkUnknownKeys2(binding, BINDING_KEYS, bindingPath, errors);
+      if (!isSafeIdentifier2(binding.name))
+        errors.push({ path: `${bindingPath}.name`, code: "INVALID_BINDING_NAME", message: "binding name must be a safe identifier." });
+      else
+        addUnique(bindingNames, binding.name, `${bindingPath}.name`, "DUPLICATE_BINDING_NAME", errors);
+      if (!["session", "environment", "cloud_session", "static_dev", "http_claim"].includes(String(binding.source)))
+        errors.push({ path: `${bindingPath}.source`, code: "INVALID_BINDING_SOURCE", message: "binding source must be session, environment, cloud_session, static_dev, or http_claim." });
+      if (!isNonEmptyString2(binding.key))
+        errors.push({ path: `${bindingPath}.key`, code: "INVALID_BINDING_KEY", message: "binding key must be a non-empty string." });
+      if (binding.source === "static_dev")
+        warnings.push({ path: `${bindingPath}.source`, code: "STATIC_DEV_BINDING", message: "static_dev bindings are for local demos only." });
+    });
+    for (const key of ["tenant_binding", "principal_binding"]) {
+      if (context[key] !== void 0 && (!isSafeIdentifier2(context[key]) || !bindingNames.has(String(context[key])))) {
+        errors.push({ path: `${path4}.${key}`, code: "UNKNOWN_CONTEXT_BINDING", message: `${key} must reference a binding name.` });
+      }
+    }
+  });
+  return names;
+}
+function validateCapabilities2(value, contextNames, resourceNames, errors, warnings) {
+  const names = /* @__PURE__ */ new Set();
+  if (!Array.isArray(value) || value.length === 0) {
+    errors.push({ path: "$.capabilities", code: "CAPABILITIES_REQUIRED", message: "At least one capability is required." });
+    return names;
+  }
+  value.forEach((capability, index) => {
+    const path4 = `$.capabilities[${index}]`;
+    if (!isRecord3(capability)) {
+      errors.push({ path: path4, code: "CAPABILITY_NOT_OBJECT", message: "capability must be an object." });
+      return;
+    }
+    checkUnknownKeys2(capability, CAPABILITY_KEYS2, path4, errors);
+    if (!isQualifiedName2(capability.name))
+      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 (!["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))
+      errors.push({ path: `${path4}.context`, code: "UNKNOWN_CONTEXT", message: "capability.context must reference a declared context." });
+    validateSubject(capability.subject, `${path4}.subject`, resourceNames, errors, warnings);
+    validateArgs2(capability.args, `${path4}.args`, errors);
+    if (capability.lookup !== void 0)
+      validateLookup2(capability.lookup, `${path4}.lookup`, capability.args, errors);
+    validateFieldList(capability.visible_fields, `${path4}.visible_fields`, "VISIBLE_FIELDS_REQUIRED", errors);
+    if (capability.kept_out_fields !== void 0)
+      validateFieldList(capability.kept_out_fields, `${path4}.kept_out_fields`, "INVALID_KEPT_OUT_FIELDS", errors, true);
+    validateKeptOutExclusion(capability.visible_fields, capability.kept_out_fields, path4, errors);
+    if (capability.evidence !== void 0)
+      validateEvidenceRequirement(capability.evidence, `${path4}.evidence`, errors);
+    if (capability.max_rows !== void 0 && !isPositiveInteger2(capability.max_rows))
+      errors.push({ path: `${path4}.max_rows`, code: "INVALID_MAX_ROWS", message: "max_rows must be a positive integer." });
+    if (capability.kind === "proposal")
+      validateProposalAction(capability.proposal, `${path4}.proposal`, errors);
+    if (capability.kind !== "proposal" && capability.proposal !== void 0)
+      errors.push({ path: `${path4}.proposal`, code: "PROPOSAL_ONLY_FOR_PROPOSAL_KIND", message: "proposal is only valid for proposal capabilities." });
+  });
+  return names;
+}
+function validateSubject(value, path4, resourceNames, errors, warnings) {
+  if (!isRecord3(value)) {
+    errors.push({ path: path4, code: "SUBJECT_REQUIRED", message: "subject must be an object." });
+    return;
+  }
+  checkUnknownKeys2(value, SUBJECT_KEYS, path4, errors);
+  if (value.resource !== void 0 && (!isQualifiedOrSafeName(value.resource) || resourceNames.size > 0 && !resourceNames.has(String(value.resource)))) {
+    errors.push({ path: `${path4}.resource`, code: "UNKNOWN_RESOURCE", message: "subject.resource must reference a declared resource." });
+  }
+  if (value.resource === void 0) {
+    for (const key of ["schema", "table", "primary_key"]) {
+      if (!isSafeIdentifier2(value[key]))
+        errors.push({ path: `${path4}.${key}`, code: "INVALID_SUBJECT_IDENTIFIER", message: `${key} must be provided as a fixed safe identifier when resource is omitted.` });
+    }
+    if (!isSafeIdentifier2(value.tenant_key) && value.single_tenant_dev !== true) {
+      errors.push({ path: `${path4}.tenant_key`, code: "TENANT_KEY_REQUIRED", message: "tenant_key is required unless single_tenant_dev is explicitly true." });
+    }
+  }
+  if (value.single_tenant_dev === true)
+    warnings.push({ path: `${path4}.single_tenant_dev`, code: "SINGLE_TENANT_DEV", message: "single_tenant_dev is only for local demos and must not be used for shared tenant data." });
+}
+function validateArgs2(value, path4, errors) {
+  if (!isRecord3(value) || Object.keys(value).length === 0) {
+    errors.push({ path: path4, code: "ARGS_REQUIRED", message: "args must define at least one model-facing business argument." });
+    return;
+  }
+  for (const [name, arg] of Object.entries(value)) {
+    const argPath = `${path4}.${name}`;
+    if (!isSafeIdentifier2(name))
+      errors.push({ path: argPath, code: "INVALID_ARG_NAME", message: "arg names must be safe identifiers." });
+    if (TRUSTED_ARG_NAMES.has(name))
+      errors.push({ path: argPath, code: "MODEL_CONTROLLED_TRUST_ARG", message: "model-facing args cannot include trust scope, dynamic identifiers, or version authority." });
+    if (!isRecord3(arg)) {
+      errors.push({ path: argPath, code: "ARG_NOT_OBJECT", message: "arg definition must be an object." });
+      continue;
+    }
+    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." });
+  }
+}
+function validateLookup2(value, path4, args, errors) {
+  if (!isRecord3(value)) {
+    errors.push({ path: path4, code: "LOOKUP_NOT_OBJECT", message: "lookup must be an object." });
+    return;
+  }
+  checkUnknownKeys2(value, LOOKUP_KEYS2, path4, errors);
+  if (!isSafeIdentifier2(value.id_from_arg) || !isRecord3(args) || !Object.prototype.hasOwnProperty.call(args, String(value.id_from_arg))) {
+    errors.push({ path: `${path4}.id_from_arg`, code: "UNKNOWN_LOOKUP_ARG", message: "lookup.id_from_arg must reference a model-facing arg." });
+  }
+}
+function validateEvidenceRequirement(value, path4, errors) {
+  if (!isRecord3(value)) {
+    errors.push({ path: path4, code: "EVIDENCE_NOT_OBJECT", message: "evidence must be an object." });
+    return;
+  }
+  checkUnknownKeys2(value, EVIDENCE_KEYS, path4, errors);
+  if (typeof value.required !== "boolean")
+    errors.push({ path: `${path4}.required`, code: "INVALID_EVIDENCE_REQUIRED", message: "evidence.required must be boolean." });
+  if (value.sources !== void 0 && (!Array.isArray(value.sources) || value.sources.some((source) => !isNonEmptyString2(source))))
+    errors.push({ path: `${path4}.sources`, code: "INVALID_EVIDENCE_SOURCES", message: "evidence.sources must be non-empty strings." });
+}
+function validateProposalAction(value, path4, errors) {
+  if (!isRecord3(value)) {
+    errors.push({ path: path4, code: "PROPOSAL_REQUIRED", message: "proposal capabilities must define proposal action semantics." });
+    return;
+  }
+  checkUnknownKeys2(value, PROPOSAL_KEYS, path4, errors);
+  if (!isQualifiedOrSafeName(value.action))
+    errors.push({ path: `${path4}.action`, code: "INVALID_PROPOSAL_ACTION", message: "proposal.action must be a safe action name." });
+  validateFieldList(value.allowed_fields, `${path4}.allowed_fields`, "ALLOWED_FIELDS_REQUIRED", errors);
+  if (!isRecord3(value.patch) || Object.keys(value.patch).length === 0) {
+    errors.push({ path: `${path4}.patch`, code: "PATCH_REQUIRED", message: "proposal.patch must map allowed fields to fixed or arg values." });
+  } else {
+    for (const [field, patch] of Object.entries(value.patch)) {
+      const patchPath = `${path4}.patch.${field}`;
+      if (!isSafeIdentifier2(field))
+        errors.push({ path: patchPath, code: "INVALID_PATCH_FIELD", message: "patch field must be a safe identifier." });
+      if (Array.isArray(value.allowed_fields) && !value.allowed_fields.includes(field))
+        errors.push({ path: patchPath, code: "PATCH_FIELD_NOT_ALLOWED", message: "patch field must be listed in allowed_fields." });
+      if (!isRecord3(patch)) {
+        errors.push({ path: patchPath, code: "PATCH_BINDING_NOT_OBJECT", message: "patch binding must be an object." });
+        continue;
+      }
+      checkUnknownKeys2(patch, PATCH_KEYS, patchPath, errors);
+      if (patch.fixed === void 0 && !isSafeIdentifier2(patch.from_arg))
+        errors.push({ path: patchPath, code: "PATCH_BINDING_REQUIRED", message: "patch binding must include fixed or from_arg." });
+    }
+  }
+  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." });
+    else {
+      checkUnknownKeys2(value.conflict_guard, CONFLICT_GUARD_KEYS2, `${path4}.conflict_guard`, errors);
+      if (value.conflict_guard.column !== void 0 && !isSafeIdentifier2(value.conflict_guard.column))
+        errors.push({ path: `${path4}.conflict_guard.column`, code: "INVALID_CONFLICT_COLUMN", message: "conflict_guard.column must be a safe identifier." });
+      if (value.conflict_guard.column === void 0 && value.conflict_guard.weak_guard_ack !== true)
+        errors.push({ path: `${path4}.conflict_guard`, code: "CONFLICT_GUARD_REQUIRED", message: "proposal needs conflict_guard.column unless weak_guard_ack is explicit." });
+    }
+  }
+  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);
+    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 validateWorkflows(value, contextNames, capabilityNames, errors) {
+  if (value === void 0)
+    return;
+  if (!Array.isArray(value)) {
+    errors.push({ path: "$.workflows", code: "WORKFLOWS_NOT_ARRAY", message: "workflows must be an array." });
+    return;
+  }
+  const names = /* @__PURE__ */ new Set();
+  value.forEach((workflow, index) => {
+    const path4 = `$.workflows[${index}]`;
+    if (!isRecord3(workflow)) {
+      errors.push({ path: path4, code: "WORKFLOW_NOT_OBJECT", message: "workflow must be an object." });
+      return;
+    }
+    checkUnknownKeys2(workflow, WORKFLOW_KEYS, path4, errors);
+    if (!isQualifiedName2(workflow.name))
+      errors.push({ path: `${path4}.name`, code: "INVALID_WORKFLOW_NAME", message: "workflow name must be namespace.name." });
+    else
+      addUnique(names, workflow.name, `${path4}.name`, "DUPLICATE_WORKFLOW_NAME", errors);
+    if (!isNonEmptyString2(workflow.context) || !contextNames.has(workflow.context))
+      errors.push({ path: `${path4}.context`, code: "UNKNOWN_CONTEXT", message: "workflow.context must reference a declared context." });
+    if (!Array.isArray(workflow.allowed_capabilities) || workflow.allowed_capabilities.length === 0) {
+      errors.push({ path: `${path4}.allowed_capabilities`, code: "WORKFLOW_CAPABILITIES_REQUIRED", message: "workflow.allowed_capabilities must list allowed capabilities." });
+    } else {
+      workflow.allowed_capabilities.forEach((name, allowedIndex) => {
+        if (!isNonEmptyString2(name) || !capabilityNames.has(name))
+          errors.push({ path: `${path4}.allowed_capabilities[${allowedIndex}]`, code: "UNKNOWN_CAPABILITY", message: "workflow allowed capability must reference a declared capability." });
+      });
+    }
+  });
+}
+function validatePolicies(value, errors) {
+  if (value === void 0)
+    return;
+  validateArrayRecords(value, "$.policies", POLICY_KEYS, "POLICY", errors);
+}
+function validateEvidenceRecords(value, errors) {
+  if (value === void 0)
+    return;
+  validateArrayRecords(value, "$.evidence", EVIDENCE_RECORD_KEYS, "EVIDENCE", errors);
+}
+function validateProposalRecords(value, capabilityNames, errors) {
+  if (value === void 0)
+    return;
+  if (!Array.isArray(value)) {
+    errors.push({ path: "$.proposals", code: "PROPOSALS_NOT_ARRAY", message: "proposals must be an array." });
+    return;
+  }
+  value.forEach((proposal, index) => {
+    const path4 = `$.proposals[${index}]`;
+    if (!isRecord3(proposal)) {
+      errors.push({ path: path4, code: "PROPOSAL_NOT_OBJECT", message: "proposal must be an object." });
+      return;
+    }
+    checkUnknownKeys2(proposal, PROPOSAL_RECORD_KEYS, path4, errors);
+    if (!isNonEmptyString2(proposal.id))
+      errors.push({ path: `${path4}.id`, code: "INVALID_PROPOSAL_ID", message: "proposal.id must be non-empty." });
+    if (!isNonEmptyString2(proposal.capability) || capabilityNames.size > 0 && !capabilityNames.has(String(proposal.capability)))
+      errors.push({ path: `${path4}.capability`, code: "UNKNOWN_CAPABILITY", message: "proposal.capability must reference a declared capability." });
+  });
+}
+function validateReceiptRecords(value, errors) {
+  if (value === void 0)
+    return;
+  validateArrayRecords(value, "$.receipts", RECEIPT_KEYS, "RECEIPT", errors);
+}
+function validateReplay(value, errors) {
+  if (value === void 0)
+    return;
+  if (!Array.isArray(value)) {
+    errors.push({ path: "$.replay", code: "REPLAY_NOT_ARRAY", message: "replay must be an array." });
+    return;
+  }
+  value.forEach((record, index) => {
+    const path4 = `$.replay[${index}]`;
+    if (!isRecord3(record)) {
+      errors.push({ path: path4, code: "REPLAY_RECORD_NOT_OBJECT", message: "replay record must be an object." });
+      return;
+    }
+    checkUnknownKeys2(record, REPLAY_KEYS, path4, errors);
+    if (!isNonEmptyString2(record.id))
+      errors.push({ path: `${path4}.id`, code: "INVALID_REPLAY_ID", message: "replay id must be non-empty." });
+    if (!Array.isArray(record.events))
+      errors.push({ path: `${path4}.events`, code: "REPLAY_EVENTS_REQUIRED", message: "replay.events must be an array." });
+  });
+}
+function validateExternalActions(value, errors) {
+  if (value === void 0)
+    return;
+  validateArrayRecords(value, "$.external_actions", EXTERNAL_ACTION_KEYS, "EXTERNAL_ACTION", errors);
+}
+function validateArrayRecords(value, path4, keys, label, errors) {
+  if (!Array.isArray(value)) {
+    errors.push({ path: path4, code: `${label}_NOT_ARRAY`, message: `${path4} must be an array.` });
+    return;
+  }
+  value.forEach((record, index) => {
+    const itemPath = `${path4}[${index}]`;
+    if (!isRecord3(record)) {
+      errors.push({ path: itemPath, code: `${label}_NOT_OBJECT`, message: `${label.toLowerCase()} entry must be an object.` });
+      return;
+    }
+    checkUnknownKeys2(record, keys, itemPath, errors);
+  });
+}
+function validateFieldList(value, path4, code, errors, allowEmpty = false) {
+  if (!Array.isArray(value) || !allowEmpty && value.length === 0) {
+    errors.push({ path: path4, code, message: "field list must be a non-empty array of safe identifiers." });
+    return;
+  }
+  const seen = /* @__PURE__ */ new Set();
+  value.forEach((field, index) => {
+    if (!isSafeIdentifier2(field))
+      errors.push({ path: `${path4}[${index}]`, code: "INVALID_FIELD_IDENTIFIER", message: "field names must be fixed safe identifiers." });
+    else
+      addUnique(seen, field, `${path4}[${index}]`, "DUPLICATE_FIELD", errors);
+  });
+}
+function validateKeptOutExclusion(visible, keptOut, path4, errors) {
+  if (!Array.isArray(visible) || !Array.isArray(keptOut))
+    return;
+  const visibleSet = new Set(visible);
+  for (const field of keptOut) {
+    if (visibleSet.has(field))
+      errors.push({ path: `${path4}.kept_out_fields`, code: "KEPT_OUT_FIELD_VISIBLE", message: `kept-out field must not also be visible: ${String(field)}` });
+  }
+}
+function validateNestedObject(value, keys, path4, errors) {
+  if (!isRecord3(value)) {
+    errors.push({ path: path4, code: "NESTED_VALUE_NOT_OBJECT", message: "nested value must be an object." });
+    return;
+  }
+  checkUnknownKeys2(value, keys, path4, errors);
+}
+function scanForInlineSecrets(value, path4, errors) {
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => scanForInlineSecrets(item, `${path4}[${index}]`, errors));
+    return;
+  }
+  if (!isRecord3(value))
+    return;
+  for (const [key, child] of Object.entries(value)) {
+    const childPath = `${path4}.${key}`;
+    if (/database_url|read_url|write_url|connection_string|password|secret|token/i.test(key) && typeof child === "string" && /(postgres(?:ql)?:\/\/|mysql:\/\/|Bearer\s+|[A-Za-z0-9+/=]{24,})/i.test(child)) {
+      errors.push({ path: childPath, code: "INLINE_SECRET_OR_URL", message: "Contracts must not contain database URLs, passwords, bearer tokens, or secrets. Put runtime wiring in runner config/env vars." });
+    }
+    scanForInlineSecrets(child, childPath, errors);
+  }
+}
+function checkUnknownKeys2(value, allowed, path4, errors) {
+  for (const key of Object.keys(value)) {
+    if (allowed.has(key) || isExtensionKey(key))
+      continue;
+    errors.push({ path: `${path4}.${key}`, code: "UNKNOWN_CORE_FIELD", message: `Unknown core field ${key}. Use x-cloud-*, x-runner-*, or x-experimental-* for extensions.` });
+  }
+}
+function addUnique(seen, name, path4, code, errors) {
+  const value = String(name);
+  if (seen.has(value))
+    errors.push({ path: path4, code, message: `Duplicate name: ${value}` });
+  seen.add(value);
+}
+function isExtensionKey(key) {
+  return /^x-(cloud|runner|experimental)-[A-Za-z0-9_.-]+$/.test(key);
+}
+function isRecord3(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function isNonEmptyString2(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+function isSafeIdentifier2(value) {
+  return typeof value === "string" && /^[A-Za-z_][A-Za-z0-9_]*$/.test(value);
+}
+function isQualifiedName2(value) {
+  return typeof value === "string" && /^[A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*$/.test(value);
+}
+function isQualifiedOrSafeName(value) {
+  return isSafeIdentifier2(value) || isQualifiedName2(value);
+}
+function isPositiveInteger2(value) {
+  return Number.isInteger(value) && Number(value) > 0;
+}
+
+// packages/spec/dist/normalize.js
+function normalizeContract(input) {
+  assertValidContract(input);
+  return sortJson(input);
+}
+function sortJson(value) {
+  if (Array.isArray(value))
+    return value.map(sortJson);
+  if (!value || typeof value !== "object")
+    return value;
+  const entries = Object.entries(value).sort(([left], [right]) => left.localeCompare(right));
+  const output = {};
+  for (const [key, child] of entries)
+    output[key] = sortJson(child);
+  return output;
+}
+
 // packages/mcp-server/src/index.ts
 import mysql from "mysql2/promise";
 import { Pool } from "pg";
@@ -2720,10 +3290,94 @@ var McpRuntimeError = class extends Error {
 function loadRuntimeConfigFromFile(configPath = process.env.SYNAPSOR_MCP_CONFIG || "synapsor.runner.json") {
   const resolved = path.resolve(configPath);
   const parsed = JSON.parse(fs.readFileSync(resolved, "utf8"));
-  assertValidRunnerCapabilityConfig(parsed);
-  return parsed;
+  const config = resolveRuntimeConfig(parsed, path.dirname(resolved));
+  assertValidRunnerCapabilityConfig(config);
+  return config;
+}
+function resolveRuntimeConfig(config, baseDir = process.cwd()) {
+  if (!Array.isArray(config.contracts) || config.contracts.length === 0) return config;
+  const resolved = {
+    ...config,
+    contexts: { ...config.contexts ?? {} },
+    capabilities: [...config.capabilities ?? []]
+  };
+  for (const contractPath of config.contracts) {
+    const fullPath = path.resolve(baseDir, contractPath);
+    const contract = normalizeContract(JSON.parse(fs.readFileSync(fullPath, "utf8")));
+    mergeContractIntoRuntimeConfig(resolved, contract);
+  }
+  delete resolved.contracts;
+  return resolved;
+}
+function mergeContractIntoRuntimeConfig(config, contract) {
+  const resources = new Map((contract.resources ?? []).map((resource) => [resource.name, resource]));
+  for (const context of contract.contexts) {
+    if (!config.contexts) config.contexts = {};
+    config.contexts[context.name] ??= runtimeContextFromSpec(context);
+  }
+  if (!config.trusted_context && contract.contexts.length === 1) {
+    const [context] = contract.contexts;
+    if (context) config.trusted_context = runtimeContextFromSpec(context);
+  }
+  if (!config.capabilities) config.capabilities = [];
+  for (const capability of contract.capabilities) {
+    config.capabilities.push(runtimeCapabilityFromSpec(capability, resources, config));
+  }
+}
+function runtimeContextFromSpec(context) {
+  const tenantBinding = context.bindings.find((binding) => binding.name === context.tenant_binding) ?? context.bindings.find((binding) => binding.name === "tenant_id");
+  const principalBinding = context.bindings.find((binding) => binding.name === context.principal_binding) ?? context.bindings.find((binding) => binding.name === "principal");
+  const provider = context.bindings.some((binding) => binding.source === "environment") ? "environment" : context.bindings.some((binding) => binding.source === "cloud_session") ? "cloud_session" : context.bindings.some((binding) => binding.source === "http_claim") ? "http_claims" : context.bindings.some((binding) => binding.source === "static_dev") ? "static_dev" : "environment";
+  return {
+    provider,
+    values: {
+      ...tenantBinding ? { tenant_id_env: tenantBinding.key, tenant_id_key: tenantBinding.key } : {},
+      ...principalBinding ? { principal_env: principalBinding.key, principal_key: principalBinding.key } : {}
+    }
+  };
+}
+function runtimeCapabilityFromSpec(capability, resources, config) {
+  const subjectResource = capability.subject.resource ? resources.get(capability.subject.resource) : void 0;
+  const source = resolveCapabilitySource(capability, config);
+  const target2 = {
+    schema: subjectResource?.schema ?? capability.subject.schema ?? "",
+    table: subjectResource?.table ?? capability.subject.table ?? "",
+    primary_key: subjectResource?.primary_key ?? capability.subject.primary_key ?? "",
+    tenant_key: subjectResource?.tenant_key ?? capability.subject.tenant_key,
+    single_tenant_dev: subjectResource?.single_tenant_dev ?? capability.subject.single_tenant_dev
+  };
+  const runtime = {
+    name: capability.name,
+    kind: capability.kind === "proposal" ? "proposal" : "read",
+    ...capability.description ? { description: capability.description } : {},
+    source,
+    context: capability.context,
+    target: target2,
+    args: capability.args,
+    lookup: capability.lookup ?? { id_from_arg: Object.keys(capability.args)[0] ?? "id" },
+    visible_columns: capability.visible_fields,
+    evidence: capability.evidence?.required === false ? "optional" : "required",
+    ...capability.max_rows ? { max_rows: capability.max_rows } : {}
+  };
+  if (capability.kind === "proposal" && capability.proposal) {
+    runtime.patch = capability.proposal.patch;
+    runtime.allowed_columns = capability.proposal.allowed_fields;
+    runtime.conflict_guard = capability.proposal.conflict_guard;
+    runtime.approval = capability.proposal.approval;
+    if (capability.proposal.writeback?.mode && capability.proposal.writeback.mode !== "direct_sql" && capability.proposal.writeback.executor) {
+      runtime.executor = capability.proposal.writeback.executor;
+    }
+  }
+  return runtime;
+}
+function resolveCapabilitySource(capability, config) {
+  if (capability.source) return capability.source;
+  const sourceNames = Object.keys(config.sources ?? {});
+  if (sourceNames.length === 1 && sourceNames[0]) return sourceNames[0];
+  throw new Error(`contract capability ${capability.name} must set source when runner config has ${sourceNames.length} sources`);
 }
 function createMcpRuntime(config, options = {}) {
+  config = resolveRuntimeConfig(config);
   assertValidRunnerCapabilityConfig(config);
   const env = options.env ?? process.env;
   const storePath = options.storePath ?? config.storage?.sqlite_path ?? "./.synapsor/local.db";
@@ -3126,7 +3780,7 @@ async function handleHttpMcpRequest(input) {
     }
     const body = await readRequestBody(request);
     const payload = JSON.parse(body);
-    if (!isRecord3(payload)) {
+    if (!isRecord4(payload)) {
       writeJson(response, 400, jsonRpcError(null, -32600, "JSON-RPC request must be an object."));
       return;
     }
@@ -3136,7 +3790,7 @@ async function handleHttpMcpRequest(input) {
       writeJson(response, 400, jsonRpcError(id, -32600, "JSON-RPC method is required."));
       return;
     }
-    const result = await handleHttpJsonRpcMethod(runtime, method, isRecord3(payload.params) ? payload.params : {});
+    const result = await handleHttpJsonRpcMethod(runtime, method, isRecord4(payload.params) ? payload.params : {});
     writeJson(response, 200, {
       jsonrpc: "2.0",
       id,
@@ -3156,7 +3810,7 @@ async function handleHttpJsonRpcMethod(runtime, method, params) {
   if (method === "tools/call") {
     const name = typeof params.name === "string" ? params.name : void 0;
     if (!name) throw new McpRuntimeError("HTTP_TOOL_NAME_REQUIRED", "tools/call requires params.name.");
-    const args = isRecord3(params.arguments) ? params.arguments : isRecord3(params.args) ? params.args : {};
+    const args = isRecord4(params.arguments) ? params.arguments : isRecord4(params.args) ? params.args : {};
     return await toolCallResult(runtime, name, args);
   }
   if (method === "resources/read") {
@@ -3201,10 +3855,10 @@ function containsInitializeRequest(payload) {
 }
 function requestIdFromPayload(payload) {
   if (Array.isArray(payload)) {
-    const request = payload.find((message) => isRecord3(message) && "id" in message);
-    return isRecord3(request) ? request.id ?? null : null;
+    const request = payload.find((message) => isRecord4(message) && "id" in message);
+    return isRecord4(request) ? request.id ?? null : null;
   }
-  return isRecord3(payload) ? payload.id ?? null : null;
+  return isRecord4(payload) ? payload.id ?? null : null;
 }
 function openaiToolNameAlias(canonicalName) {
   const sanitized = canonicalName.replace(/[^A-Za-z0-9_-]+/g, "__").replace(/_{3,}/g, "__").replace(/^_+|_+$/g, "");
@@ -3297,7 +3951,7 @@ function sanitizeHttpError(error, authToken) {
 function sanitizeHttpPayload(value, authToken) {
   if (typeof value === "string") return sanitizeHttpString(value, authToken);
   if (Array.isArray(value)) return value.map((item) => sanitizeHttpPayload(item, authToken));
-  if (isRecord3(value)) {
+  if (isRecord4(value)) {
     return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, sanitizeHttpPayload(item, authToken)]));
   }
   return value;
@@ -3423,11 +4077,11 @@ function toolDescriptionWithCanonical(description, canonicalName, exposedName) {
 ${description}`;
 }
 function zodInputShapeFromJsonSchema(schema) {
-  const properties = isRecord3(schema.properties) ? schema.properties : {};
+  const properties = isRecord4(schema.properties) ? schema.properties : {};
   const required = Array.isArray(schema.required) ? new Set(schema.required.map(String)) : /* @__PURE__ */ new Set();
   const shape = {};
   for (const [name, rawProperty] of Object.entries(properties)) {
-    const property = isRecord3(rawProperty) ? rawProperty : {};
+    const property = isRecord4(rawProperty) ? rawProperty : {};
     let valueSchema;
     if (property.type === "number" || property.type === "integer") valueSchema = z2.number();
     else if (property.type === "boolean") valueSchema = z2.boolean();
@@ -3613,8 +4267,8 @@ function resultEnvelopeFromLegacy(legacy, capability, canonicalName) {
   const kind = capability?.kind ?? (typeof legacy.proposal_id === "string" ? "proposal" : "read");
   const evidenceBundleId = typeof legacy.evidence_bundle_id === "string" ? legacy.evidence_bundle_id : void 0;
   const sourceChanged = Boolean(legacy.source_database_changed ?? legacy.source_database_mutated ?? false);
-  const context = isRecord3(legacy.trusted_context) ? legacy.trusted_context : void 0;
-  const target2 = isRecord3(legacy.target) ? legacy.target : void 0;
+  const context = isRecord4(legacy.trusted_context) ? legacy.trusted_context : void 0;
+  const target2 = isRecord4(legacy.target) ? legacy.target : void 0;
   if (kind === "proposal") {
     const proposalId = typeof legacy.proposal_id === "string" ? legacy.proposal_id : "wrp_unknown";
     const targetType = typeof target2?.type === "string" ? target2.type : capability?.target.table ?? "object";
@@ -3631,7 +4285,7 @@ function resultEnvelopeFromLegacy(legacy, capability, canonicalName) {
         id: proposalId,
         state: typeof legacy.status === "string" ? legacy.status : "review_required",
         target: `${targetType}:${targetId}`,
-        diff: isRecord3(legacy.diff) ? legacy.diff : {},
+        diff: isRecord4(legacy.diff) ? legacy.diff : {},
         approval_required: legacy.approval_required !== false,
         writeback: {
           mode: writebackMode,
@@ -3650,7 +4304,7 @@ function resultEnvelopeFromLegacy(legacy, capability, canonicalName) {
       }
     };
   }
-  const businessObject = isRecord3(legacy.business_object) ? legacy.business_object : void 0;
+  const businessObject = isRecord4(legacy.business_object) ? legacy.business_object : void 0;
   const objectType = typeof businessObject?.type === "string" ? businessObject.type : capability?.target.table ?? "record";
   const objectId = businessObject?.id !== void 0 ? String(businessObject.id) : String(legacy.action ?? action);
   return {
@@ -3658,7 +4312,7 @@ function resultEnvelopeFromLegacy(legacy, capability, canonicalName) {
     summary: `Read ${objectType} ${objectId} through ${action}. Source database changed: no.`,
     action,
     kind: "read",
-    data: isRecord3(legacy.data) ? legacy.data : {},
+    data: isRecord4(legacy.data) ? legacy.data : {},
     proposal: null,
     error: null,
     evidence: evidenceBundleId ? evidenceHandle(evidenceBundleId) : null,
@@ -3672,7 +4326,7 @@ function resultEnvelopeFromLegacy(legacy, capability, canonicalName) {
   };
 }
 function writebackExecutorName(value) {
-  if (!isRecord3(value)) return void 0;
+  if (!isRecord4(value)) return void 0;
   return typeof value.executor === "string" ? value.executor : typeof value.mode === "string" ? value.mode : void 0;
 }
 function evidenceHandle(bundleId) {
@@ -4086,7 +4740,7 @@ function stableId(prefix, input) {
 function hashJson(input) {
   return `sha256:${crypto.createHash("sha256").update(JSON.stringify(input)).digest("hex")}`;
 }
-function isRecord3(value) {
+function isRecord4(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function toolErrorPayload(error) {
@@ -4159,14 +4813,41 @@ function validateMysqlPatch(job) {
 function resultHash(job, status, version) {
   return `sha256:${crypto2.createHash("sha256").update(JSON.stringify({ job_id: job.job_id, status, version })).digest("hex")}`;
 }
+function normalizeVersionValue(value) {
+  if (value instanceof Date) return normalizeVersionValue(value.toISOString());
+  const text = String(value ?? "").trim();
+  const timestamp = text.match(/^(\d{4}-\d{2}-\d{2})[T ](\d{2}:\d{2}:\d{2})(?:\.(\d{1,9}))?(Z|[+-]\d{2}(?::?\d{2})?)?$/i);
+  if (timestamp) {
+    const fraction = (timestamp[3] ?? "").padEnd(6, "0").slice(0, 6);
+    const offset = timestamp[4];
+    if (offset && offset.toUpperCase() !== "Z") {
+      const dateParts = timestamp[1].split("-");
+      const timeParts = timestamp[2].split(":");
+      const year = Number(dateParts[0]);
+      const month = Number(dateParts[1]);
+      const day = Number(dateParts[2]);
+      const hour = Number(timeParts[0]);
+      const minute = Number(timeParts[1]);
+      const second = Number(timeParts[2]);
+      const utc = new Date(Date.UTC(year, month - 1, day, hour, minute, second) - offsetMinutes(offset) * 6e4);
+      return `${utc.getUTCFullYear()}-${pad2(utc.getUTCMonth() + 1)}-${pad2(utc.getUTCDate())} ${pad2(utc.getUTCHours())}:${pad2(utc.getUTCMinutes())}:${pad2(utc.getUTCSeconds())}.${fraction}`;
+    }
+    return `${timestamp[1]} ${timestamp[2]}.${fraction}`;
+  }
+  return text;
+}
+function offsetMinutes(offset) {
+  const sign = offset.startsWith("-") ? -1 : 1;
+  const compact = offset.slice(1).replace(":", "");
+  const hours = Number(compact.slice(0, 2));
+  const minutes = Number(compact.slice(2, 4) || "0");
+  return sign * (hours * 60 + minutes);
+}
+function pad2(value) {
+  return String(value).padStart(2, "0");
+}
 function versionValuesMatch(actual, expected) {
-  const normalizeTimestamp = (value) => String(value ?? "").replace("T", " ").replace(/\.\d{3}Z$/, "").replace(/Z$/, "").slice(0, 19);
-  const actualNormalized = normalizeTimestamp(actual);
-  const expectedNormalized = normalizeTimestamp(expected);
-  if (actualNormalized && expectedNormalized && actualNormalized === expectedNormalized) {
-    return true;
-  }
-  return String(actual) === String(expected);
+  return normalizeVersionValue(actual) === normalizeVersionValue(expected);
 }
 async function applyMysqlJob(job, config) {
   if (config.dryRun) {
@@ -4176,15 +4857,22 @@ async function applyMysqlJob(job, config) {
   if (!config.databaseUrl) return failed(job, config, "DATABASE_UNAVAILABLE");
   const connection = await mysql2.createConnection({ uri: config.databaseUrl, dateStrings: true });
   try {
-    await connection.beginTransaction();
+    return await applyMysqlJobWithConnection(job, config, connection);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "TRANSACTION_FAILED";
+    return failed(job, config, message.includes("MULTI_ROW") ? "MULTI_ROW_WRITE_BLOCKED" : message.includes("VERSION") ? "VERSION_CONFLICT" : "TRANSACTION_FAILED");
+  } finally {
+    await connection.end();
+  }
+}
+async function applyMysqlJobWithConnection(job, config, connection) {
+  await connection.beginTransaction();
+  try {
     await connection.query(mysqlReceiptMigration);
-    const [receiptRows] = await connection.query(
-      "SELECT status, result_hash FROM synapsor_writeback_receipts WHERE idempotency_key = ? FOR UPDATE",
-      [job.idempotency_key]
-    );
-    if (receiptRows[0]?.status === "applied") {
+    const existing = await claimReceipt(connection, job, config);
+    if (existing) {
       await connection.commit();
-      return { protocol_version: "1.0", job_id: job.job_id, runner_id: config.runnerId, status: "applied", affected_rows: 0, result_hash: receiptRows[0].result_hash, completed_at: (/* @__PURE__ */ new Date()).toISOString() };
+      return existing;
     }
     const [rows] = await connection.query(
       `SELECT * FROM ${quoteMysqlIdentifier(job.target.schema)}.${quoteMysqlIdentifier(job.target.table)}
@@ -4194,14 +4882,16 @@ FOR UPDATE`,
       [job.target.primary_key.value, job.target.tenant_guard.value]
     );
     if (!rows[0]) {
-      await recordReceipt(connection, job, "conflict", resultHash(job, "ROW_NOT_FOUND"));
+      const hash2 = resultHash(job, "ROW_NOT_FOUND");
+      await recordReceipt(connection, job, "conflict", hash2);
       await connection.commit();
-      return conflict(job, config, "ROW_NOT_FOUND");
+      return conflict(job, config, "ROW_NOT_FOUND", hash2);
     }
     if (job.conflict_guard.kind === "version_column" && !versionValuesMatch(rows[0][job.conflict_guard.column], job.conflict_guard.expected_value)) {
-      await recordReceipt(connection, job, "conflict", resultHash(job, "VERSION_CONFLICT", rows[0][job.conflict_guard.column]));
+      const hash2 = resultHash(job, "VERSION_CONFLICT", rows[0][job.conflict_guard.column]);
+      await recordReceipt(connection, job, "conflict", hash2);
       await connection.commit();
-      return conflict(job, config, "VERSION_CONFLICT");
+      return conflict(job, config, "VERSION_CONFLICT", hash2);
     }
     const update = buildMysqlUpdate(job);
     const [result] = await connection.query(update.sql, update.values);
@@ -4212,22 +4902,44 @@ FOR UPDATE`,
     return { protocol_version: "1.0", job_id: job.job_id, runner_id: config.runnerId, status: "applied", affected_rows: 1, result_hash: hash, completed_at: (/* @__PURE__ */ new Date()).toISOString() };
   } catch (error) {
     await connection.rollback().catch(() => void 0);
-    const message = error instanceof Error ? error.message : "TRANSACTION_FAILED";
-    return failed(job, config, message.includes("MULTI_ROW") ? "MULTI_ROW_WRITE_BLOCKED" : message.includes("VERSION") ? "VERSION_CONFLICT" : "TRANSACTION_FAILED");
-  } finally {
-    await connection.end();
+    throw error;
   }
 }
+async function claimReceipt(connection, job, config) {
+  const [claim] = await connection.query(
+    `INSERT IGNORE INTO synapsor_writeback_receipts (idempotency_key, job_id, proposal_id, status, result_hash)
+VALUES (?, ?, ?, 'in_progress', NULL)`,
+    [job.idempotency_key, job.job_id, job.proposal_id]
+  );
+  if (claim.affectedRows === 1) return void 0;
+  const [receiptRows] = await connection.query(
+    "SELECT status, result_hash FROM synapsor_writeback_receipts WHERE idempotency_key = ? FOR UPDATE",
+    [job.idempotency_key]
+  );
+  const row = receiptRows[0];
+  if (!row) return failed(job, config, "IDEMPOTENCY_RECEIPT_UNAVAILABLE");
+  return resultFromExistingReceipt(job, config, row.status, row.result_hash);
+}
+function resultFromExistingReceipt(job, config, status, hash) {
+  const result_hash = typeof hash === "string" && hash ? hash : resultHash(job, "idempotent");
+  if (status === "applied" || status === "already_applied") {
+    return { protocol_version: "1.0", job_id: job.job_id, runner_id: config.runnerId, status: "already_applied", affected_rows: 0, result_hash, completed_at: (/* @__PURE__ */ new Date()).toISOString() };
+  }
+  if (status === "conflict") return conflict(job, config, "IDEMPOTENT_CONFLICT", result_hash);
+  if (status === "failed") return failed(job, config, "IDEMPOTENT_FAILED");
+  return failed(job, config, "IDEMPOTENCY_RECEIPT_IN_PROGRESS");
+}
 async function recordReceipt(connection, job, status, hash) {
-  await connection.query(
-    `INSERT INTO synapsor_writeback_receipts (idempotency_key, job_id, proposal_id, status, result_hash, completed_at)
-VALUES (?, ?, ?, ?, ?, CURRENT_TIMESTAMP)
-ON DUPLICATE KEY UPDATE status = VALUES(status), result_hash = VALUES(result_hash), completed_at = VALUES(completed_at)`,
-    [job.idempotency_key, job.job_id, job.proposal_id, status, hash]
+  const [result] = await connection.query(
+    `UPDATE synapsor_writeback_receipts
+SET status = ?, result_hash = ?, completed_at = CURRENT_TIMESTAMP
+WHERE idempotency_key = ?`,
+    [status, hash, job.idempotency_key]
   );
+  if (result.affectedRows !== 1) throw new Error("IDEMPOTENCY_RECEIPT_UNAVAILABLE");
 }
-function conflict(job, config, code) {
-  return { protocol_version: "1.0", job_id: job.job_id, runner_id: config.runnerId, status: "conflict", affected_rows: 0, error_code: code, completed_at: (/* @__PURE__ */ new Date()).toISOString() };
+function conflict(job, config, code, result_hash) {
+  return { protocol_version: "1.0", job_id: job.job_id, runner_id: config.runnerId, status: "conflict", affected_rows: 0, error_code: code, result_hash, completed_at: (/* @__PURE__ */ new Date()).toISOString() };
 }
 function failed(job, config, code) {
   return { protocol_version: "1.0", job_id: job.job_id, runner_id: config.runnerId, status: "failed", error_code: code, completed_at: (/* @__PURE__ */ new Date()).toISOString() };
@@ -4331,19 +5043,41 @@ function validatePostgresPatch(job) {
 function resultHash2(job, status, version) {
   return `sha256:${crypto3.createHash("sha256").update(JSON.stringify({ job_id: job.job_id, status, version })).digest("hex")}`;
 }
+function normalizeVersionValue2(value) {
+  if (value instanceof Date) return normalizeVersionValue2(value.toISOString());
+  const text = String(value ?? "").trim();
+  const timestamp = text.match(/^(\d{4}-\d{2}-\d{2})[T ](\d{2}:\d{2}:\d{2})(?:\.(\d{1,9}))?(Z|[+-]\d{2}(?::?\d{2})?)?$/i);
+  if (timestamp) {
+    const fraction = (timestamp[3] ?? "").padEnd(6, "0").slice(0, 6);
+    const offset = timestamp[4];
+    if (offset && offset.toUpperCase() !== "Z") {
+      const dateParts = timestamp[1].split("-");
+      const timeParts = timestamp[2].split(":");
+      const year = Number(dateParts[0]);
+      const month = Number(dateParts[1]);
+      const day = Number(dateParts[2]);
+      const hour = Number(timeParts[0]);
+      const minute = Number(timeParts[1]);
+      const second = Number(timeParts[2]);
+      const utc = new Date(Date.UTC(year, month - 1, day, hour, minute, second) - offsetMinutes2(offset) * 6e4);
+      return `${utc.getUTCFullYear()}-${pad22(utc.getUTCMonth() + 1)}-${pad22(utc.getUTCDate())} ${pad22(utc.getUTCHours())}:${pad22(utc.getUTCMinutes())}:${pad22(utc.getUTCSeconds())}.${fraction}`;
+    }
+    return `${timestamp[1]} ${timestamp[2]}.${fraction}`;
+  }
+  return text;
+}
+function offsetMinutes2(offset) {
+  const sign = offset.startsWith("-") ? -1 : 1;
+  const compact = offset.slice(1).replace(":", "");
+  const hours = Number(compact.slice(0, 2));
+  const minutes = Number(compact.slice(2, 4) || "0");
+  return sign * (hours * 60 + minutes);
+}
+function pad22(value) {
+  return String(value).padStart(2, "0");
+}
 function versionValuesMatch2(actual, expected) {
-  if (actual instanceof Date) {
-    const expectedDate = new Date(String(expected));
-    return !Number.isNaN(expectedDate.getTime()) && actual.getTime() === expectedDate.getTime();
-  }
-  if (typeof actual === "string" && typeof expected === "string") {
-    const actualDate = new Date(actual);
-    const expectedDate = new Date(expected);
-    if (!Number.isNaN(actualDate.getTime()) && !Number.isNaN(expectedDate.getTime())) {
-      return actualDate.getTime() === expectedDate.getTime();
-    }
-  }
-  return String(actual) === String(expected);
+  return normalizeVersionValue2(actual) === normalizeVersionValue2(expected);
 }
 async function withTransaction(client, fn) {
   await client.query("BEGIN");
@@ -4375,55 +5109,7 @@ async function applyPostgresJob(job, config) {
   const pool = new Pool2({ connectionString: config.databaseUrl });
   const client = await pool.connect();
   try {
-    return await withTransaction(client, async () => {
-      await client.query(postgresReceiptMigration);
-      const receipt = await client.query(
-        "SELECT status, result_hash FROM synapsor_writeback_receipts WHERE idempotency_key = $1 FOR UPDATE",
-        [job.idempotency_key]
-      );
-      if (receipt.rowCount && receipt.rows[0]?.status === "applied") {
-        return {
-          protocol_version: "1.0",
-          job_id: job.job_id,
-          runner_id: config.runnerId,
-          status: "applied",
-          affected_rows: 0,
-          result_hash: receipt.rows[0]?.result_hash || resultHash2(job, "idempotent"),
-          completed_at: (/* @__PURE__ */ new Date()).toISOString()
-        };
-      }
-      const row = await client.query(
-        `SELECT * FROM ${quotePostgresIdentifier(job.target.schema)}.${quotePostgresIdentifier(job.target.table)}
-WHERE ${quotePostgresIdentifier(job.target.primary_key.column)} = $1
-  AND ${quotePostgresIdentifier(job.target.tenant_guard.column)} = $2
-FOR UPDATE`,
-        [job.target.primary_key.value, job.target.tenant_guard.value]
-      );
-      if (!row.rowCount) {
-        await recordReceipt2(client, job, "conflict", resultHash2(job, "ROW_NOT_FOUND"));
-        return conflict2(job, config, "ROW_NOT_FOUND");
-      }
-      if (job.conflict_guard.kind === "version_column" && !versionValuesMatch2(row.rows[0]?.[job.conflict_guard.column], job.conflict_guard.expected_value)) {
-        await recordReceipt2(client, job, "conflict", resultHash2(job, "VERSION_CONFLICT", row.rows[0]?.[job.conflict_guard.column]));
-        return conflict2(job, config, "VERSION_CONFLICT");
-      }
-      const update = buildPostgresUpdate(job);
-      const applied = await client.query(update.sql, update.values);
-      if (applied.rowCount !== 1) {
-        throw new Error(applied.rowCount === 0 ? "VERSION_CONFLICT" : "MULTI_ROW_WRITE_BLOCKED");
-      }
-      const hash = resultHash2(job, "applied", job.conflict_guard.kind === "version_column" ? job.conflict_guard.expected_value : void 0);
-      await recordReceipt2(client, job, "applied", hash);
-      return {
-        protocol_version: "1.0",
-        job_id: job.job_id,
-        runner_id: config.runnerId,
-        status: "applied",
-        affected_rows: 1,
-        result_hash: hash,
-        completed_at: (/* @__PURE__ */ new Date()).toISOString()
-      };
-    });
+    return await applyPostgresJobWithClient(job, config, client);
   } catch (error) {
     const message = error instanceof Error ? error.message : "TRANSACTION_FAILED";
     return failed2(job, config, message.includes("MULTI_ROW") ? "MULTI_ROW_WRITE_BLOCKED" : message.includes("VERSION") ? "VERSION_CONFLICT" : "TRANSACTION_FAILED");
@@ -4432,17 +5118,93 @@ FOR UPDATE`,
     await pool.end();
   }
 }
+async function applyPostgresJobWithClient(job, config, client) {
+  return await withTransaction(client, async () => {
+    await client.query(postgresReceiptMigration);
+    const existing = await claimReceipt2(client, job, config);
+    if (existing) return existing;
+    const conflictProjection = job.conflict_guard.kind === "version_column" ? `, ${quotePostgresIdentifier(job.conflict_guard.column)}::text AS "__synapsor_conflict_value"` : "";
+    const row = await client.query(
+      `SELECT *${conflictProjection} FROM ${quotePostgresIdentifier(job.target.schema)}.${quotePostgresIdentifier(job.target.table)}
+WHERE ${quotePostgresIdentifier(job.target.primary_key.column)} = $1
+  AND ${quotePostgresIdentifier(job.target.tenant_guard.column)} = $2
+FOR UPDATE`,
+      [job.target.primary_key.value, job.target.tenant_guard.value]
+    );
+    if (!row.rowCount) {
+      const hash2 = resultHash2(job, "ROW_NOT_FOUND");
+      await recordReceipt2(client, job, "conflict", hash2);
+      return conflict2(job, config, "ROW_NOT_FOUND", hash2);
+    }
+    const currentVersion = row.rows[0]?.__synapsor_conflict_value ?? row.rows[0]?.[job.conflict_guard.kind === "version_column" ? job.conflict_guard.column : ""];
+    if (job.conflict_guard.kind === "version_column" && !versionValuesMatch2(currentVersion, job.conflict_guard.expected_value)) {
+      const hash2 = resultHash2(job, "VERSION_CONFLICT", currentVersion);
+      await recordReceipt2(client, job, "conflict", hash2);
+      return conflict2(job, config, "VERSION_CONFLICT", hash2);
+    }
+    const update = buildPostgresUpdate(job);
+    const applied = await client.query(update.sql, update.values);
+    if (applied.rowCount !== 1) {
+      throw new Error(applied.rowCount === 0 ? "VERSION_CONFLICT" : "MULTI_ROW_WRITE_BLOCKED");
+    }
+    const hash = resultHash2(job, "applied", job.conflict_guard.kind === "version_column" ? job.conflict_guard.expected_value : void 0);
+    await recordReceipt2(client, job, "applied", hash);
+    return {
+      protocol_version: "1.0",
+      job_id: job.job_id,
+      runner_id: config.runnerId,
+      status: "applied",
+      affected_rows: 1,
+      result_hash: hash,
+      completed_at: (/* @__PURE__ */ new Date()).toISOString()
+    };
+  });
+}
+async function claimReceipt2(client, job, config) {
+  const claimed = await client.query(
+    `INSERT INTO synapsor_writeback_receipts (idempotency_key, job_id, proposal_id, status, result_hash)
+VALUES ($1, $2, $3, 'in_progress', NULL)
+ON CONFLICT (idempotency_key) DO NOTHING
+RETURNING status, result_hash`,
+    [job.idempotency_key, job.job_id, job.proposal_id]
+  );
+  if (claimed.rowCount === 1) return void 0;
+  const receipt = await client.query(
+    "SELECT status, result_hash FROM synapsor_writeback_receipts WHERE idempotency_key = $1 FOR UPDATE",
+    [job.idempotency_key]
+  );
+  const row = receipt.rows[0];
+  if (!row) return failed2(job, config, "IDEMPOTENCY_RECEIPT_UNAVAILABLE");
+  return resultFromExistingReceipt2(job, config, row.status, row.result_hash);
+}
+function resultFromExistingReceipt2(job, config, status, hash) {
+  const result_hash = typeof hash === "string" && hash ? hash : resultHash2(job, "idempotent");
+  if (status === "applied" || status === "already_applied") {
+    return {
+      protocol_version: "1.0",
+      job_id: job.job_id,
+      runner_id: config.runnerId,
+      status: "already_applied",
+      affected_rows: 0,
+      result_hash,
+      completed_at: (/* @__PURE__ */ new Date()).toISOString()
+    };
+  }
+  if (status === "conflict") return conflict2(job, config, "IDEMPOTENT_CONFLICT", result_hash);
+  if (status === "failed") return failed2(job, config, "IDEMPOTENT_FAILED");
+  return failed2(job, config, "IDEMPOTENCY_RECEIPT_IN_PROGRESS");
+}
 async function recordReceipt2(client, job, status, hash) {
-  await client.query(
-    `INSERT INTO synapsor_writeback_receipts (idempotency_key, job_id, proposal_id, status, result_hash, completed_at)
-VALUES ($1, $2, $3, $4, $5, now())
-ON CONFLICT (idempotency_key)
-DO UPDATE SET status = EXCLUDED.status, result_hash = EXCLUDED.result_hash, completed_at = EXCLUDED.completed_at`,
-    [job.idempotency_key, job.job_id, job.proposal_id, status, hash]
+  const result = await client.query(
+    `UPDATE synapsor_writeback_receipts
+SET status = $2, result_hash = $3, completed_at = now()
+WHERE idempotency_key = $1`,
+    [job.idempotency_key, status, hash]
   );
+  if (result.rowCount !== 1) throw new Error("IDEMPOTENCY_RECEIPT_UNAVAILABLE");
 }
-function conflict2(job, config, code) {
-  return { protocol_version: "1.0", job_id: job.job_id, runner_id: config.runnerId, status: "conflict", affected_rows: 0, error_code: code, completed_at: (/* @__PURE__ */ new Date()).toISOString() };
+function conflict2(job, config, code, result_hash) {
+  return { protocol_version: "1.0", job_id: job.job_id, runner_id: config.runnerId, status: "conflict", affected_rows: 0, error_code: code, result_hash, completed_at: (/* @__PURE__ */ new Date()).toISOString() };
 }
 function failed2(job, config, code) {
   return { protocol_version: "1.0", job_id: job.job_id, runner_id: config.runnerId, status: "failed", error_code: code, completed_at: (/* @__PURE__ */ new Date()).toISOString() };
@@ -5432,13 +6194,13 @@ function collectTools(input) {
   const tools2 = [];
   const seen = /* @__PURE__ */ new Set();
   function addTool(value, path4) {
-    if (!isRecord4(value)) return;
+    if (!isRecord5(value)) return;
     const name = optionalString(value.name) ?? optionalString(value.tool_name) ?? optionalString(value.toolName);
     if (!name) return;
     const description = optionalString(value.description) ?? optionalString(value.title) ?? optionalString(value.summary) ?? "";
     const inputSchema = value.inputSchema ?? value.input_schema ?? value.parameters ?? value.schema ?? value.args_schema;
     const outputSchema = value.outputSchema ?? value.output_schema ?? value.resultSchema ?? value.result_schema ?? value.output;
-    const annotations = isRecord4(value.annotations) ? value.annotations : {};
+    const annotations = isRecord5(value.annotations) ? value.annotations : {};
     const key = `${path4}:${name}`;
     if (seen.has(key)) return;
     seen.add(key);
@@ -5447,14 +6209,14 @@ function collectTools(input) {
   function visit(value, path4, depth) {
     if (depth > 8) return;
     if (Array.isArray(value)) {
-      if (value.every((item) => isRecord4(item) && typeof item.name === "string")) {
+      if (value.every((item) => isRecord5(item) && typeof item.name === "string")) {
         value.forEach((item, index) => addTool(item, `${path4}[${index}]`));
       } else {
         value.forEach((item, index) => visit(item, `${path4}[${index}]`, depth + 1));
       }
       return;
     }
-    if (!isRecord4(value)) return;
+    if (!isRecord5(value)) return;
     addTool(value, path4);
     for (const [key, child] of Object.entries(value)) {
       if (key === "tools" && Array.isArray(child)) {
@@ -5472,9 +6234,9 @@ function collectTools(input) {
 function collectSchemaPropertyNames(schema) {
   const names = /* @__PURE__ */ new Set();
   function visit(value, depth) {
-    if (depth > 10 || !isRecord4(value)) return;
+    if (depth > 10 || !isRecord5(value)) return;
     const properties = value.properties;
-    if (isRecord4(properties)) {
+    if (isRecord5(properties)) {
       for (const [name, propertySchema] of Object.entries(properties)) {
         names.add(name);
         visit(propertySchema, depth + 1);
@@ -5548,7 +6310,7 @@ function normalizeToken(value) {
 function optionalString(value) {
   return typeof value === "string" ? value : void 0;
 }
-function isRecord4(value) {
+function isRecord5(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function safeStringify(value) {
@@ -5662,6 +6424,414 @@ async function startPolling(config, adapters2, signal) {
   }
 }
 
+// packages/dsl/dist/index.js
+var AgentDslError = class extends Error {
+  line;
+  column;
+  code;
+  constructor(line, column, code, message) {
+    super(`${line}:${column} ${code}: ${message}`);
+    this.line = line;
+    this.column = column;
+    this.code = code;
+    this.name = "AgentDslError";
+  }
+};
+function parseAgentDsl(source) {
+  const blocks = parseBlocks(source);
+  const contexts = [];
+  const capabilities = [];
+  const workflows = [];
+  for (const block of blocks) {
+    if (block.kind === "context")
+      contexts.push(parseContextBlock(block));
+    if (block.kind === "capability")
+      capabilities.push(parseCapabilityBlock(block));
+    if (block.kind === "workflow")
+      workflows.push(parseWorkflowBlock(block));
+  }
+  return { contexts, capabilities, workflows };
+}
+function compileAgentDsl(source) {
+  const ast = parseAgentDsl(source);
+  const contexts = ast.contexts.map((context) => ({
+    name: context.name,
+    bindings: context.bindings,
+    ...context.tenantBinding ? { tenant_binding: context.tenantBinding } : {},
+    ...context.principalBinding ? { principal_binding: context.principalBinding } : {}
+  }));
+  const capabilities = ast.capabilities.map((capability) => {
+    const spec = {
+      name: capability.name,
+      kind: capability.kind,
+      context: capability.context,
+      ...capability.source ? { source: capability.source } : {},
+      subject: {
+        schema: capability.schema,
+        table: capability.table,
+        primary_key: capability.primaryKey,
+        ...capability.tenantKey ? { tenant_key: capability.tenantKey } : {},
+        ...capability.conflictKey ? { conflict_key: capability.conflictKey } : {}
+      },
+      args: capability.args,
+      ...capability.lookup ? { lookup: { id_from_arg: capability.lookup.arg } } : {},
+      visible_fields: capability.visibleFields,
+      ...capability.keptOutFields.length ? { kept_out_fields: capability.keptOutFields } : {},
+      ...capability.evidenceRequired !== void 0 ? { evidence: { required: capability.evidenceRequired, query_audit: true } } : {},
+      ...capability.maxRows ? { max_rows: capability.maxRows } : {}
+    };
+    if (capability.kind === "proposal" && capability.proposal) {
+      spec.proposal = {
+        action: capability.proposal.action,
+        allowed_fields: capability.proposal.allowedFields,
+        patch: capability.proposal.patch,
+        conflict_guard: capability.conflictKey ? { column: capability.conflictKey } : { weak_guard_ack: true },
+        approval: { mode: "human", required_role: capability.proposal.approvalRole ?? "local_reviewer" },
+        writeback: {
+          mode: capability.proposal.writebackMode ?? "direct_sql",
+          ...capability.proposal.executor ? { executor: capability.proposal.executor } : {}
+        }
+      };
+    }
+    return spec;
+  });
+  const workflows = ast.workflows.map((workflow) => ({
+    name: workflow.name,
+    context: workflow.context,
+    allowed_capabilities: workflow.allowedCapabilities,
+    ...workflow.requiredEvidence !== void 0 ? { required_evidence: workflow.requiredEvidence } : {},
+    ...workflow.approvalRole ? { approval: { required: true, role: workflow.approvalRole } } : {},
+    ...workflow.checkpoint ? { replay: { checkpoint: workflow.checkpoint } } : {}
+  }));
+  const contract = {
+    spec_version: "0.1",
+    kind: "SynapsorContract",
+    contexts,
+    capabilities,
+    ...workflows.length ? { workflows } : {}
+  };
+  assertValidContract(contract);
+  return normalizeContract(contract);
+}
+function validateAgentDsl(source) {
+  try {
+    compileAgentDsl(source);
+    return { ok: true, errors: [], warnings: [] };
+  } catch (error) {
+    if (error instanceof AgentDslError) {
+      return {
+        ok: false,
+        errors: [{ line: error.line, column: error.column, code: error.code, message: error.message.replace(/^\d+:\d+ [A-Z_]+: /, "") }],
+        warnings: []
+      };
+    }
+    return {
+      ok: false,
+      errors: [{ line: 1, column: 1, code: "DSL_VALIDATION_FAILED", message: error instanceof Error ? error.message : String(error) }],
+      warnings: []
+    };
+  }
+}
+function parseBlocks(source) {
+  const lines = source.split(/\r?\n/);
+  const blocks = [];
+  let current;
+  lines.forEach((rawLine, index) => {
+    const lineNumber = index + 1;
+    const stripped = rawLine.replace(/--.*$/, "").trim();
+    if (!stripped)
+      return;
+    const contextMatch = stripped.match(/^CREATE\s+AGENT\s+CONTEXT\s+([A-Za-z_][A-Za-z0-9_.]*)$/i);
+    const capabilityMatch = stripped.match(/^CREATE\s+(?:AGENT\s+)?CAPABILITY\s+([A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*)$/i);
+    const workflowMatch = stripped.match(/^CREATE\s+AGENT\s+WORKFLOW\s+([A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*)$/i);
+    if (contextMatch || capabilityMatch || workflowMatch) {
+      if (current)
+        throw dslError(lineNumber, 1, "BLOCK_NOT_CLOSED", "previous CREATE block must end with END before starting another block");
+      if (contextMatch?.[1])
+        current = { kind: "context", name: contextMatch[1], line: lineNumber, body: [] };
+      else if (capabilityMatch?.[1])
+        current = { kind: "capability", name: capabilityMatch[1], line: lineNumber, body: [] };
+      else if (workflowMatch?.[1])
+        current = { kind: "workflow", name: workflowMatch[1], line: lineNumber, body: [] };
+      return;
+    }
+    if (/^END;?$/i.test(stripped)) {
+      if (!current)
+        throw dslError(lineNumber, 1, "END_WITHOUT_BLOCK", "END appeared without an open CREATE block");
+      blocks.push(current);
+      current = void 0;
+      return;
+    }
+    if (!current)
+      throw dslError(lineNumber, 1, "EXPECTED_CREATE", "expected CREATE AGENT CONTEXT, CREATE CAPABILITY, or CREATE AGENT WORKFLOW");
+    current.body.push({ text: stripped.replace(/;$/, ""), line: lineNumber });
+  });
+  if (current)
+    throw dslError(current.line, 1, "BLOCK_NOT_CLOSED", `${current.name} must end with END`);
+  return blocks;
+}
+function parseContextBlock(block) {
+  const context = { name: block.name, bindings: [] };
+  for (const item of block.body) {
+    const bind = item.text.match(/^BIND\s+([A-Za-z_][A-Za-z0-9_]*)\s+FROM\s+(SESSION|ENV|ENVIRONMENT|CLOUD_SESSION|STATIC_DEV|HTTP_CLAIM)\s+([A-Za-z0-9_.-]+)(?:\s+REQUIRED)?$/i);
+    if (bind?.[1] && bind[2] && bind[3]) {
+      const name = bind[1];
+      const source = normalizeBindingSource(bind[2]);
+      context.bindings.push({ name, source, key: bind[3], ...item.text.match(/\sREQUIRED$/i) ? { required: true } : {} });
+      continue;
+    }
+    const tenant = item.text.match(/^TENANT\s+BINDING\s+([A-Za-z_][A-Za-z0-9_]*)$/i);
+    if (tenant?.[1]) {
+      context.tenantBinding = tenant[1];
+      continue;
+    }
+    const principal = item.text.match(/^PRINCIPAL\s+BINDING\s+([A-Za-z_][A-Za-z0-9_]*)$/i);
+    if (principal?.[1]) {
+      context.principalBinding = principal[1];
+      continue;
+    }
+    unsupported(item, "context");
+  }
+  if (context.bindings.length === 0)
+    throw dslError(block.line, 1, "CONTEXT_BINDINGS_REQUIRED", "CREATE AGENT CONTEXT requires at least one BIND line");
+  context.tenantBinding ??= context.bindings.find((binding) => binding.name === "tenant_id")?.name;
+  context.principalBinding ??= context.bindings.find((binding) => binding.name === "principal")?.name;
+  return context;
+}
+function parseCapabilityBlock(block) {
+  const capability = {
+    name: block.name,
+    kind: "read",
+    context: "",
+    schema: "",
+    table: "",
+    primaryKey: "id",
+    args: {},
+    visibleFields: [],
+    keptOutFields: []
+  };
+  for (const item of block.body) {
+    const context = item.text.match(/^USING\s+CONTEXT\s+([A-Za-z_][A-Za-z0-9_.]*)$/i);
+    if (context?.[1]) {
+      capability.context = context[1];
+      continue;
+    }
+    const source = item.text.match(/^SOURCE\s+([A-Za-z_][A-Za-z0-9_.-]*)$/i);
+    if (source?.[1]) {
+      capability.source = source[1];
+      continue;
+    }
+    const on = item.text.match(/^ON\s+([A-Za-z_][A-Za-z0-9_]*)\.([A-Za-z_][A-Za-z0-9_]*)$/i);
+    if (on?.[1] && on[2]) {
+      capability.schema = on[1];
+      capability.table = on[2];
+      continue;
+    }
+    const primary = item.text.match(/^PRIMARY\s+KEY\s+([A-Za-z_][A-Za-z0-9_]*)$/i);
+    if (primary?.[1]) {
+      capability.primaryKey = primary[1];
+      continue;
+    }
+    const tenant = item.text.match(/^TENANT\s+KEY\s+([A-Za-z_][A-Za-z0-9_]*)$/i);
+    if (tenant?.[1]) {
+      capability.tenantKey = tenant[1];
+      continue;
+    }
+    const conflict3 = item.text.match(/^CONFLICT\s+GUARD\s+([A-Za-z_][A-Za-z0-9_]*)$/i);
+    if (conflict3?.[1]) {
+      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);
+    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]) } : {}
+      };
+      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);
+    if (lookup?.[1] && lookup[2]) {
+      capability.lookup = { arg: lookup[1], column: lookup[2] };
+      capability.primaryKey = lookup[2];
+      if (!capability.args[lookup[1]])
+        capability.args[lookup[1]] = { type: "string", required: true, max_length: 128 };
+      continue;
+    }
+    const read = item.text.match(/^ALLOW\s+READ\s+(.+)$/i);
+    if (read?.[1]) {
+      capability.visibleFields = parseList(read[1]);
+      continue;
+    }
+    const keptOut = item.text.match(/^KEEP\s+OUT\s+(.+)$/i);
+    if (keptOut?.[1]) {
+      capability.keptOutFields = parseList(keptOut[1]);
+      continue;
+    }
+    if (/^REQUIRE\s+EVIDENCE$/i.test(item.text)) {
+      capability.evidenceRequired = true;
+      continue;
+    }
+    const maxRows = item.text.match(/^MAX\s+ROWS\s+(\d+)$/i);
+    if (maxRows?.[1]) {
+      capability.maxRows = Number(maxRows[1]);
+      continue;
+    }
+    const propose2 = item.text.match(/^PROPOSE\s+ACTION\s+([A-Za-z_][A-Za-z0-9_.]*)$/i);
+    if (propose2?.[1]) {
+      capability.kind = "proposal";
+      capability.proposal = { action: propose2[1], allowedFields: [], patch: {} };
+      continue;
+    }
+    const allowWrite = item.text.match(/^ALLOW\s+WRITE\s+(.+)$/i);
+    if (allowWrite?.[1]) {
+      ensureProposal(capability, item);
+      capability.proposal.allowedFields = parseList(allowWrite[1]);
+      continue;
+    }
+    const patch = item.text.match(/^PATCH\s+([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.+)$/i);
+    if (patch?.[1] && patch[2]) {
+      ensureProposal(capability, item);
+      capability.proposal.patch[patch[1]] = parsePatchBinding(patch[2]);
+      if (!capability.proposal.allowedFields.includes(patch[1]))
+        capability.proposal.allowedFields.push(patch[1]);
+      continue;
+    }
+    const approval = item.text.match(/^APPROVAL\s+ROLE\s+([A-Za-z_][A-Za-z0-9_.-]*)$/i);
+    if (approval?.[1]) {
+      ensureProposal(capability, item);
+      capability.proposal.approvalRole = approval[1];
+      continue;
+    }
+    const writeback2 = item.text.match(/^WRITEBACK\s+(DIRECT\s+SQL|APP\s+HANDLER|CLOUD\s+WORKER|NONE)(?:\s+EXECUTOR\s+([A-Za-z_][A-Za-z0-9_.-]*))?$/i);
+    if (writeback2?.[1]) {
+      ensureProposal(capability, item);
+      capability.proposal.writebackMode = normalizeWritebackMode(writeback2[1]);
+      if (writeback2[2])
+        capability.proposal.executor = writeback2[2];
+      continue;
+    }
+    unsupported(item, "capability");
+  }
+  if (!capability.context)
+    throw dslError(block.line, 1, "CAPABILITY_CONTEXT_REQUIRED", `${block.name} requires USING CONTEXT`);
+  if (!capability.schema || !capability.table)
+    throw dslError(block.line, 1, "CAPABILITY_SUBJECT_REQUIRED", `${block.name} requires ON schema.table`);
+  if (!capability.tenantKey)
+    throw dslError(block.line, 1, "CAPABILITY_TENANT_REQUIRED", `${block.name} requires TENANT KEY for 0.1 DSL`);
+  if (capability.visibleFields.length === 0)
+    throw dslError(block.line, 1, "CAPABILITY_VISIBLE_FIELDS_REQUIRED", `${block.name} requires ALLOW READ`);
+  if (Object.keys(capability.args).length === 0 && capability.lookup)
+    capability.args[capability.lookup.arg] = { type: "string", required: true, max_length: 128 };
+  if (Object.keys(capability.args).length === 0)
+    throw dslError(block.line, 1, "CAPABILITY_ARGS_REQUIRED", `${block.name} requires ARG or LOOKUP`);
+  if (capability.kind === "proposal" && (!capability.proposal || Object.keys(capability.proposal.patch).length === 0))
+    throw dslError(block.line, 1, "PROPOSAL_PATCH_REQUIRED", `${block.name} proposal requires at least one PATCH line`);
+  return capability;
+}
+function parseWorkflowBlock(block) {
+  const workflow = { name: block.name, context: "", allowedCapabilities: [] };
+  for (const item of block.body) {
+    const context = item.text.match(/^USING\s+CONTEXT\s+([A-Za-z_][A-Za-z0-9_.]*)$/i);
+    if (context?.[1]) {
+      workflow.context = context[1];
+      continue;
+    }
+    const capability = item.text.match(/^ALLOW\s+CAPABILITY\s+([A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*)$/i);
+    if (capability?.[1]) {
+      workflow.allowedCapabilities.push(capability[1]);
+      continue;
+    }
+    if (/^REQUIRE\s+EVIDENCE$/i.test(item.text)) {
+      workflow.requiredEvidence = true;
+      continue;
+    }
+    const approval = item.text.match(/^APPROVAL\s+REQUIRED\s+ROLE\s+([A-Za-z_][A-Za-z0-9_.-]*)$/i);
+    if (approval?.[1]) {
+      workflow.approvalRole = approval[1];
+      continue;
+    }
+    const checkpoint = item.text.match(/^CHECKPOINT\s+(NONE|EVERY\s+STEP|PROPOSAL\s+ONLY)$/i);
+    if (checkpoint?.[1]) {
+      workflow.checkpoint = checkpoint[1].toLowerCase().replace(/\s+/g, "_");
+      continue;
+    }
+    unsupported(item, "workflow");
+  }
+  if (!workflow.context)
+    throw dslError(block.line, 1, "WORKFLOW_CONTEXT_REQUIRED", `${block.name} requires USING CONTEXT`);
+  if (workflow.allowedCapabilities.length === 0)
+    throw dslError(block.line, 1, "WORKFLOW_CAPABILITIES_REQUIRED", `${block.name} requires ALLOW CAPABILITY`);
+  return workflow;
+}
+function ensureProposal(capability, item) {
+  if (!capability.proposal)
+    throw dslError(item.line, 1, "PROPOSAL_ACTION_REQUIRED", "proposal clauses require PROPOSE ACTION first");
+}
+function parsePatchBinding(raw) {
+  const trimmed = raw.trim();
+  const arg = trimmed.match(/^ARG\s+([A-Za-z_][A-Za-z0-9_]*)$/i);
+  if (arg?.[1])
+    return { from_arg: arg[1] };
+  if (/^NULL$/i.test(trimmed))
+    return { fixed: null };
+  if (/^TRUE$/i.test(trimmed))
+    return { fixed: true };
+  if (/^FALSE$/i.test(trimmed))
+    return { fixed: false };
+  if (/^-?\d+(?:\.\d+)?$/.test(trimmed))
+    return { fixed: Number(trimmed) };
+  const quoted = trimmed.match(/^'(.*)'$/);
+  if (quoted)
+    return { fixed: quoted[1] ?? "" };
+  return { fixed: trimmed };
+}
+function normalizeBindingSource(source) {
+  const normalized = source.toUpperCase();
+  if (normalized === "ENV")
+    return "environment";
+  if (normalized === "ENVIRONMENT")
+    return "environment";
+  if (normalized === "SESSION")
+    return "session";
+  if (normalized === "CLOUD_SESSION")
+    return "cloud_session";
+  if (normalized === "STATIC_DEV")
+    return "static_dev";
+  return "http_claim";
+}
+function normalizeArgType(type) {
+  const normalized = type.toUpperCase();
+  if (normalized === "NUMBER")
+    return "number";
+  if (normalized === "BOOLEAN" || normalized === "BOOL")
+    return "boolean";
+  return "string";
+}
+function normalizeWritebackMode(mode) {
+  const normalized = mode.toUpperCase().replace(/\s+/g, "_");
+  if (normalized === "DIRECT_SQL")
+    return "direct_sql";
+  if (normalized === "APP_HANDLER")
+    return "app_handler";
+  if (normalized === "CLOUD_WORKER")
+    return "cloud_worker";
+  return "none";
+}
+function parseList(value) {
+  return value.split(",").map((item) => item.trim()).filter(Boolean);
+}
+function unsupported(item, blockKind) {
+  if (/ROOT\s+EXTERNAL|JOIN\s+EXTERNAL|RETURN\s+ANSWER|AUTO\s+BRANCH|AUTO\s+MERGE/i.test(item.text)) {
+    throw dslError(item.line, 1, "UNSUPPORTED_PREVIEW_SYNTAX", `${blockKind} clause is not supported by @synapsor/dsl 0.1 preview: ${item.text}`);
+  }
+  throw dslError(item.line, 1, "UNSUPPORTED_DSL_CLAUSE", `unsupported ${blockKind} clause: ${item.text}`);
+}
+function dslError(line, column, code, message) {
+  return new AgentDslError(line, column, code, message);
+}
+
 // apps/runner/src/local-ui.ts
 import crypto4 from "node:crypto";
 import fs2 from "node:fs/promises";
@@ -5814,7 +6984,7 @@ async function handleRequest(input) {
 async function readRunnerConfig(configPath) {
   const raw = await fs2.readFile(configPath, "utf8");
   const parsed = JSON.parse(raw);
-  if (!isRecord5(parsed)) throw new Error("runner config must be a JSON object");
+  if (!isRecord6(parsed)) throw new Error("runner config must be a JSON object");
   return parsed;
 }
 function buildSummary(config, configPath, storePath) {
@@ -5983,7 +7153,7 @@ async function readJsonBody(request) {
   }
   if (chunks.length === 0) return {};
   const parsed = JSON.parse(Buffer.concat(chunks).toString("utf8"));
-  if (!isRecord5(parsed)) throw new Error("request body must be a JSON object");
+  if (!isRecord6(parsed)) throw new Error("request body must be a JSON object");
   return parsed;
 }
 function hasValidCsrf(request, csrfToken) {
@@ -6489,7 +7659,7 @@ init().catch((error) => {
 }
 function redactSecrets(value, key = "") {
   if (Array.isArray(value)) return value.map((item) => redactSecrets(item));
-  if (isRecord5(value)) {
+  if (isRecord6(value)) {
     return Object.fromEntries(Object.entries(value).map(([entryKey, entryValue]) => [entryKey, redactSecrets(entryValue, entryKey)]));
   }
   if (typeof value === "string") {
@@ -6506,11 +7676,11 @@ function escapeScriptString(value) {
 function isLocalHost(host) {
   return host === "127.0.0.1" || host === "localhost" || host === "::1";
 }
-function isRecord5(value) {
+function isRecord6(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function asRecord(value) {
-  return isRecord5(value) ? value : {};
+  return isRecord6(value) ? value : {};
 }
 function stringOrDefault(value, fallback) {
   return typeof value === "string" && value.trim() ? value.trim() : fallback;
@@ -6856,6 +8026,8 @@ ${cliCommandName()} --help
   if (command === "init") return init(rest);
   if (command === "inspect") return inspect(rest);
   if (command === "config") return configCommand(rest);
+  if (command === "contract") return contractCommand(rest);
+  if (command === "dsl") return dslCommand(rest);
   if (command === "doctor") return doctor(rest);
   if (command === "validate") return validate(rest);
   if (command === "apply") return apply(rest);
@@ -7333,7 +8505,7 @@ function isScriptedOnboardingArgs(args) {
   return args.includes("--yes") || args.includes("--non-interactive") || args.includes("--dry-run") || Boolean(optionalArg(args, "--answers")) || Boolean(optionalArg(args, "--inspection-json")) || Boolean(optionalArg(args, "--table"));
 }
 function answersToSelectionSpec(raw) {
-  if (!isRecord6(raw)) throw new Error("--answers file must contain a JSON object");
+  if (!isRecord7(raw)) throw new Error("--answers file must contain a JSON object");
   const mode = stringValue(raw.mode) ?? "review";
   if (!["read_only", "shadow", "review"].includes(mode)) throw new Error("answers.mode must be read_only, shadow, or review");
   const engine = stringValue(raw.engine) ?? "postgres";
@@ -8002,6 +9174,182 @@ async function configCommand(args) {
   usage();
   return 2;
 }
+async function contractCommand(args) {
+  const [subcommand, ...rest] = args;
+  if (subcommand === "validate") return contractValidate(rest);
+  if (subcommand === "normalize") return contractNormalize(rest);
+  if (subcommand === "bundle") return contractBundle(rest);
+  usage(["contract"]);
+  return 2;
+}
+async function dslCommand(args) {
+  const [subcommand, ...rest] = args;
+  if (subcommand === "validate") return dslValidate(rest);
+  if (subcommand === "compile") return dslCompile(rest);
+  usage(["dsl"]);
+  return 2;
+}
+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 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}
+`);
+  } else {
+    process2.stdout.write(`dsl invalid: ${target2}
+`);
+    for (const error of result.errors) process2.stdout.write(`error ${error.line}:${error.column} ${error.code}: ${error.message}
+`);
+  }
+  return result.ok ? 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 output = outputArg(args);
+  const text = `${JSON.stringify(contract, null, 2)}
+`;
+  if (output) {
+    await fs3.writeFile(output, text, "utf8");
+    process2.stdout.write(`wrote contract: ${output}
+`);
+  } else {
+    process2.stdout.write(text);
+  }
+  return 0;
+}
+async function contractValidate(args) {
+  const target2 = firstPositional(args);
+  if (!target2) throw new Error("contract validate requires <synapsor.contract.json>");
+  const parsed = JSON.parse(await fs3.readFile(target2, "utf8"));
+  const result = validateContract(parsed);
+  if (args.includes("--json")) {
+    process2.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+  } else if (result.ok) {
+    process2.stdout.write(`contract valid: ${target2}
+`);
+    for (const warning of result.warnings) process2.stdout.write(`warning ${warning.path} ${warning.code}: ${warning.message}
+`);
+  } else {
+    process2.stdout.write(`contract invalid: ${target2}
+`);
+    for (const error of result.errors) process2.stdout.write(`error ${error.path} ${error.code}: ${error.message}
+`);
+  }
+  return result.ok ? 0 : 1;
+}
+async function contractNormalize(args) {
+  const target2 = firstPositional(args);
+  if (!target2) throw new Error("contract normalize requires <synapsor.contract.json>");
+  const parsed = JSON.parse(await fs3.readFile(target2, "utf8"));
+  const normalized = normalizeContract(parsed);
+  const output = outputArg(args);
+  const text = `${JSON.stringify(normalized, null, 2)}
+`;
+  if (output) {
+    await fs3.writeFile(output, text, "utf8");
+    process2.stdout.write(`wrote normalized contract: ${output}
+`);
+  } else {
+    process2.stdout.write(text);
+  }
+  return 0;
+}
+async function contractBundle(args) {
+  const target2 = firstPositional(args);
+  if (!target2) throw new Error("contract bundle requires <synapsor.contract.json>");
+  const outDir = outputArg(args) ?? "synapsor-runner-bundle";
+  const parsed = JSON.parse(await fs3.readFile(target2, "utf8"));
+  const contract = normalizeContract(parsed);
+  const firstCapability = contract.capabilities[0];
+  const firstSource = firstCapability?.source ?? "local_postgres";
+  const engine = inferContractBundleEngine(contract);
+  const readUrlEnv = engine === "mysql" ? "SYNAPSOR_DATABASE_READ_URL" : "SYNAPSOR_DATABASE_READ_URL";
+  const runnerConfig = {
+    version: 1,
+    mode: contract.capabilities.some((capability) => capability.kind === "proposal") ? "review" : "read_only",
+    result_format: 2,
+    storage: { sqlite_path: "./.synapsor/local.db" },
+    contracts: ["./synapsor.contract.json"],
+    sources: {
+      [firstSource]: {
+        engine,
+        read_url_env: readUrlEnv,
+        statement_timeout_ms: 3e3
+      }
+    }
+  };
+  await fs3.mkdir(outDir, { recursive: true });
+  await fs3.mkdir(path3.join(outDir, "mcp-client-examples"), { recursive: true });
+  await fs3.writeFile(path3.join(outDir, "synapsor.contract.json"), `${JSON.stringify(contract, null, 2)}
+`, "utf8");
+  await fs3.writeFile(path3.join(outDir, "synapsor.runner.json"), `${JSON.stringify(runnerConfig, null, 2)}
+`, "utf8");
+  await fs3.writeFile(path3.join(outDir, ".env.example"), bundleEnvExample(contract, readUrlEnv, engine), "utf8");
+  await fs3.writeFile(path3.join(outDir, "README.md"), bundleReadme(contract), "utf8");
+  await fs3.writeFile(path3.join(outDir, "mcp-client-examples", "generic-stdio.json"), `${JSON.stringify({
+    command: cliCommandName(),
+    args: ["mcp", "serve", "--config", "./synapsor.runner.json", "--store", "./.synapsor/local.db"]
+  }, null, 2)}
+`, "utf8");
+  process2.stdout.write(`created runner bundle: ${outDir}
+`);
+  process2.stdout.write("No database URLs, write credentials, tokens, or customer rows were included.\n");
+  return 0;
+}
+function inferContractBundleEngine(contract) {
+  const engine = contract.resources?.find((resource) => resource.engine === "postgres" || resource.engine === "mysql")?.engine;
+  return engine === "mysql" ? "mysql" : "postgres";
+}
+function bundleEnvExample(contract, readUrlEnv, engine) {
+  const context = contract.contexts[0];
+  const tenantBinding = context?.bindings.find((binding) => binding.name === context.tenant_binding) ?? context?.bindings.find((binding) => binding.name === "tenant_id");
+  const principalBinding = context?.bindings.find((binding) => binding.name === context.principal_binding) ?? context?.bindings.find((binding) => binding.name === "principal");
+  return [
+    "# Synapsor Runner bundle environment.",
+    "# Fill these locally. Do not commit real values.",
+    `# Set ${readUrlEnv} to your read-only ${engine === "mysql" ? "MySQL" : "Postgres"} URL.`,
+    `${readUrlEnv}=`,
+    `${tenantBinding?.key ?? "SYNAPSOR_TENANT_ID"}=acme`,
+    `${principalBinding?.key ?? "SYNAPSOR_PRINCIPAL"}=local_operator`,
+    ""
+  ].join("\n");
+}
+function bundleReadme(contract) {
+  const contractName = contract.metadata?.name ?? "Synapsor contract";
+  return [
+    `# ${contractName} Runner Bundle`,
+    "",
+    "This bundle lets you run a Cloud/exported Synapsor contract locally with Synapsor Runner.",
+    "",
+    "It includes:",
+    "",
+    "- `synapsor.contract.json`: canonical Synapsor contract;",
+    "- `synapsor.runner.json`: local runtime wiring with env-var placeholders;",
+    "- `.env.example`: placeholder runtime values only;",
+    "- `mcp-client-examples/`: client snippets with command paths only.",
+    "",
+    "It does not include database passwords, write credentials, bearer tokens, or table rows.",
+    "",
+    "## Run Locally",
+    "",
+    "```bash",
+    "cp .env.example .env",
+    "# edit .env, then export the values in your shell",
+    `${cliCommandName()} contract validate ./synapsor.contract.json`,
+    `${cliCommandName()} mcp serve --config ./synapsor.runner.json --store ./.synapsor/local.db`,
+    "```",
+    ""
+  ].join("\n");
+}
 async function configValidate(args) {
   const configPath = optionalArg(args, "--config") ?? "synapsor.runner.json";
   const parsed = JSON.parse(await fs3.readFile(configPath, "utf8"));
@@ -8334,7 +9682,7 @@ function looksLikeRecipePath(value) {
   return value.endsWith(".json") || value.includes("/") || value.includes("\\") || value.startsWith(".");
 }
 function normalizeRecipe(value, source) {
-  if (!isRecord6(value)) throw new Error(`recipe ${source} must be a JSON object`);
+  if (!isRecord7(value)) throw new Error(`recipe ${source} must be a JSON object`);
   const recipe = {
     id: requiredString(value, "id", source),
     title: requiredString(value, "title", source),
@@ -8369,7 +9717,7 @@ function requiredStringArray(value, key, source) {
 }
 function requiredRecord(value, key, source) {
   const item = value[key];
-  if (!isRecord6(item)) throw new Error(`recipe ${source} requires object ${key}`);
+  if (!isRecord7(item)) throw new Error(`recipe ${source} requires object ${key}`);
   return item;
 }
 async function doctor(args = []) {
@@ -8640,7 +9988,7 @@ async function localDoctor(args) {
     await inspectConfiguredSource({ config: parsed, sourceName, source, checks });
   }
   for (const [executorName, executor] of Object.entries(parsed.executors ?? {})) {
-    if (!isRecord6(executor)) continue;
+    if (!isRecord7(executor)) continue;
     if (executor.type === "http_handler") {
       const urlEnv = String(executor.url_env ?? "");
       if (urlEnv) {
@@ -8657,7 +10005,7 @@ async function localDoctor(args) {
           });
         }
       }
-      const auth = isRecord6(executor.auth) ? executor.auth : void 0;
+      const auth = isRecord7(executor.auth) ? executor.auth : void 0;
       const tokenEnv = typeof auth?.token_env === "string" ? auth.token_env : void 0;
       if (tokenEnv) checks.push(envPresenceCheck(tokenEnv, `${tokenEnv} is required for http_handler executor ${executorName} bearer auth.`));
       const signingSecretEnv = typeof executor.signing_secret_env === "string" ? executor.signing_secret_env : void 0;
@@ -8874,6 +10222,28 @@ async function localDoctorStoreStats(storePath) {
   }
 }
 async function validate(args) {
+  const target2 = firstPositional(args);
+  if (target2) {
+    const parsed = JSON.parse(await fs3.readFile(target2, "utf8"));
+    if (isSynapsorContractLike(parsed)) {
+      const result = validateContract(parsed);
+      if (args.includes("--json")) {
+        process2.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+      } else if (result.ok) {
+        process2.stdout.write(`contract valid: ${target2}
+`);
+        for (const warning of result.warnings) process2.stdout.write(`warning ${warning.path} ${warning.code}: ${warning.message}
+`);
+      } else {
+        process2.stdout.write(`contract invalid: ${target2}
+`);
+        for (const error of result.errors) process2.stdout.write(`error ${error.path} ${error.code}: ${error.message}
+`);
+      }
+      return result.ok ? 0 : 1;
+    }
+  }
   const job = await readJob(args);
   parseWritebackJob(job);
   process2.stdout.write("job valid\n");
@@ -9035,7 +10405,7 @@ function proposalExecutorName(proposal, capability) {
 }
 function executorConfig(config, executorName) {
   const raw = config.executors?.[executorName];
-  if (!isRecord6(raw)) throw new Error(`executor ${executorName} is not configured`);
+  if (!isRecord7(raw)) throw new Error(`executor ${executorName} is not configured`);
   if (raw.type === "http_handler") return raw;
   if (raw.type === "command_handler") return raw;
   if (raw.type === "sql_update") return { type: "sql_update" };
@@ -9193,7 +10563,7 @@ function alreadyAppliedReceipt(receipt, runnerId) {
   };
 }
 function handlerReceiptFromBody(input) {
-  const body = isRecord6(input.body) ? input.body : {};
+  const body = isRecord7(input.body) ? input.body : {};
   const rawStatus = String(body.status ?? "failed");
   const status = handlerReceiptStatuses.has(rawStatus) ? rawStatus : "failed";
   const rowsAffected = Number.isInteger(body.rows_affected) && Number(body.rows_affected) >= 0 ? Number(body.rows_affected) : status === "applied" && !input.dryRun ? 1 : 0;
@@ -9640,10 +11010,10 @@ function formatUpWritebackLines(config) {
 function formatUpHandlerLines(config) {
   const lines = [];
   for (const [name, executor] of Object.entries(config.executors ?? {})) {
-    if (!isRecord6(executor)) continue;
+    if (!isRecord7(executor)) continue;
     if (executor.type === "http_handler") {
       const urlEnv = typeof executor.url_env === "string" ? executor.url_env : "";
-      const auth = isRecord6(executor.auth) ? executor.auth : void 0;
+      const auth = isRecord7(executor.auth) ? executor.auth : void 0;
       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`);
@@ -9689,9 +11059,62 @@ async function runnerCommand(args) {
 async function cloud(args) {
   const [subcommand, ...rest] = args;
   if (subcommand === "connect") return cloudConnect(rest);
+  if (subcommand === "push") return cloudPush(rest);
   usage();
   return 2;
 }
+async function cloudPush(args) {
+  const target2 = firstPositional(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 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,
+    pushed_at: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  const dryRun = args.includes("--dry-run");
+  if (args.includes("--json")) {
+    process2.stdout.write(`${JSON.stringify({ ok: dryRun, dry_run: dryRun, payload }, null, 2)}
+`);
+  } else {
+    process2.stdout.write("Synapsor Cloud contract push preview\n");
+    process2.stdout.write(`Contract: ${target2}
+`);
+    process2.stdout.write(`Contexts: ${payload.summary.contexts}
+`);
+    process2.stdout.write(`Capabilities: ${payload.summary.capabilities}
+`);
+    process2.stdout.write(`Workflows: ${payload.summary.workflows}
+`);
+    process2.stdout.write(`Proposal capabilities: ${payload.summary.proposal_capabilities}
+`);
+    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");
+    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;
+  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 is not wired to a Cloud registry endpoint yet. Use --dry-run for local validation; do not treat this as uploaded.");
+}
+function contractSummary(contract) {
+  return {
+    contexts: contract.contexts.length,
+    capabilities: contract.capabilities.length,
+    workflows: contract.workflows?.length ?? 0,
+    proposal_capabilities: contract.capabilities.filter((capability) => capability.kind === "proposal").length,
+    kept_out_fields: contract.capabilities.reduce((count, capability) => count + (capability.kept_out_fields?.length ?? 0), 0)
+  };
+}
 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"));
@@ -10733,12 +12156,12 @@ async function proposalInput(args, capability) {
   if (selected > 1) throw new Error("propose accepts only one of --sample, --input, or --json");
   if (jsonInput) {
     const parsed = JSON.parse(jsonInput);
-    if (!isRecord6(parsed)) throw new Error("propose --json must be a JSON object");
+    if (!isRecord7(parsed)) throw new Error("propose --json must be a JSON object");
     return parsed;
   }
   if (inputPath) {
     const parsed = JSON.parse(await fs3.readFile(inputPath, "utf8"));
-    if (!isRecord6(parsed)) throw new Error("propose --input must point to a JSON object");
+    if (!isRecord7(parsed)) throw new Error("propose --input must point to a JSON object");
     return parsed;
   }
   if (sample) return sampleInputForCapability(capability);
@@ -11042,7 +12465,7 @@ The MCP server needs a reviewed config before it can expose semantic tools.
 Fix:
 Run ${cliCommandName()} onboard db --from-env DATABASE_URL, or pass --config <path>.`);
   }
-  const parsed = JSON.parse(await fs3.readFile(configPath, "utf8"));
+  const parsed = await readRuntimeConfig(configPath);
   const runtime = createMcpRuntime(parsed, { storePath });
   try {
     const tools2 = runtime.listTools();
@@ -11131,12 +12554,12 @@ async function smokeInputFromArgs(args, capability) {
   if (selected > 1) throw new Error("smoke call accepts only one of --sample, --input, or --json");
   if (jsonInput) {
     const parsed = JSON.parse(jsonInput);
-    if (!isRecord6(parsed)) throw new Error("smoke call --json must be a JSON object");
+    if (!isRecord7(parsed)) throw new Error("smoke call --json must be a JSON object");
     return parsed;
   }
   if (inputPath) {
     const parsed = JSON.parse(await fs3.readFile(inputPath, "utf8"));
-    if (!isRecord6(parsed)) throw new Error("smoke call --input must point to a JSON object");
+    if (!isRecord7(parsed)) throw new Error("smoke call --input must point to a JSON object");
     return parsed;
   }
   if (sample && capability) return sampleInputForCapability(capability);
@@ -11211,13 +12634,13 @@ async function writeMcpClientSnippet(destination, client, snippet, yes) {
 function mergeMcpClientSnippet(client, existing, snippet) {
   if (client === "generic" || client === "generic-stdio") return snippet;
   if (client === "claude-desktop" || client === "cursor") {
-    const existingServers = isRecord6(existing.mcpServers) ? existing.mcpServers : {};
-    const snippetServers = isRecord6(snippet.mcpServers) ? snippet.mcpServers : {};
+    const existingServers = isRecord7(existing.mcpServers) ? existing.mcpServers : {};
+    const snippetServers = isRecord7(snippet.mcpServers) ? snippet.mcpServers : {};
     return { ...existing, mcpServers: { ...existingServers, ...snippetServers } };
   }
   if (client === "vscode") {
-    const existingServers = isRecord6(existing.servers) ? existing.servers : {};
-    const snippetServers = isRecord6(snippet.servers) ? snippet.servers : {};
+    const existingServers = isRecord7(existing.servers) ? existing.servers : {};
+    const snippetServers = isRecord7(snippet.servers) ? snippet.servers : {};
     return { ...existing, servers: { ...existingServers, ...snippetServers } };
   }
   throw new Error(`unsupported MCP client: ${client}`);
@@ -11315,7 +12738,7 @@ async function recipesInit(args) {
   process2.stdout.write("Review the generated table and column names against your staging database before serving MCP tools.\n");
   return 0;
 }
-function isRecord6(value) {
+function isRecord7(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 async function benchmark(args) {
@@ -11561,7 +12984,7 @@ function builtInMcpAuditExample(example) {
   throw new Error(`unknown audit example: ${example}. Available examples: dangerous-db-mcp`);
 }
 function isRunnerConfigLike(value) {
-  return isRecord6(value) && value.version === 1 && Array.isArray(value.capabilities);
+  return isRecord7(value) && value.version === 1 && Array.isArray(value.capabilities);
 }
 async function fetchRemoteMcpTools(target2, args, timeoutMs) {
   const bearerEnv = optionalArg(args, "--bearer-env") ?? "SYNAPSOR_MCP_AUDIT_BEARER";
@@ -11770,7 +13193,7 @@ async function shadowRecordHumanAction(args) {
   const patchPath = optionalArg(args, "--patch");
   if (!patchPath) throw new Error("shadow record-human-action requires --patch <human-action.json>");
   const patch = JSON.parse(await fs3.readFile(patchPath, "utf8"));
-  if (!isRecord6(patch)) throw new Error("shadow human-action patch must be a JSON object");
+  if (!isRecord7(patch)) throw new Error("shadow human-action patch must be a JSON object");
   const store = await openLocalStore(args);
   try {
     const action = store.recordShadowHumanAction(proposalId, {
@@ -12842,8 +14265,10 @@ function missingLocalStoreError(storePath) {
   ].join("\n"));
 }
 async function readRuntimeConfig(configPath) {
-  const parsed = JSON.parse(await fs3.readFile(configPath, "utf8"));
-  return parsed;
+  return loadRuntimeConfigFromFile(configPath);
+}
+function isSynapsorContractLike(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value) && (value.kind === "SynapsorContract" || value.spec_version === "0.1");
 }
 function envWithDemoDefaults(config, configPath) {
   if (!isReferenceDemoConfig(config, configPath)) return process2.env;
@@ -13282,16 +14707,16 @@ function formatEvidenceDetail(evidence2) {
 `;
 }
 function formatEvidenceItem(item, index) {
-  const payload = isRecord6(item.item) ? item.item : item;
-  const visibleRow = isRecord6(payload.visible_row) ? payload.visible_row : payload;
+  const payload = isRecord7(item.item) ? item.item : item;
+  const visibleRow = isRecord7(payload.visible_row) ? payload.visible_row : payload;
   const title = stringField(payload, "kind") ?? "item";
-  const primaryKey = isRecord6(payload.primary_key) ? payload.primary_key : void 0;
+  const primaryKey = isRecord7(payload.primary_key) ? payload.primary_key : void 0;
   const heading = primaryKey ? `* ${title} ${formatScalar(primaryKey.value)}` : `* ${title} ${index}`;
   const rows = Object.entries(visibleRow).filter(([key]) => !["kind", "source_id", "table", "primary_key", "tenant"].includes(key)).flatMap(([key, value]) => formatEvidenceFieldLines(key, value)).slice(0, 12);
   return [heading, ...rows.length ? rows : ["  (no scalar preview fields)"]];
 }
 function formatEvidenceFieldLines(key, value) {
-  if (isRecord6(value)) {
+  if (isRecord7(value)) {
     const nested = Object.entries(value).filter(([, nestedValue]) => nestedValue === null || ["string", "number", "boolean"].includes(typeof nestedValue)).slice(0, 6).map(([nestedKey, nestedValue]) => `  ${key}.${nestedKey}: ${formatScalar(nestedValue)}`);
     return nested.length ? nested : [`  ${key}: [object]`];
   }
@@ -13353,7 +14778,7 @@ function formatQueryAuditFirstLook(row, storeSuffix) {
   ].join("\n");
 }
 function formatQueryAuditDetail(row) {
-  const payload = isRecord6(row.payload) ? row.payload : {};
+  const payload = isRecord7(row.payload) ? row.payload : {};
   return [
     `Query audit: ${row.audit_id}`,
     `Created at: ${row.created_at}`,
@@ -13504,7 +14929,7 @@ function formatReplayMarkdown(replay2) {
   const approvalEvents = replay2.events.filter((event) => /approved|rejected|canceled/i.test(event.kind));
   const evidenceLines = replay2.evidence.length > 0 ? replay2.evidence.flatMap((evidence2) => {
     const record = evidence2;
-    const payload = isRecord6(record.payload) ? record.payload : {};
+    const payload = isRecord7(record.payload) ? record.payload : {};
     const sourceId = stringField(payload, "source_id") ?? proposal.source_id;
     const table = stringField(payload, "target") ?? `${proposal.source_schema}.${proposal.source_table}`;
     const queryFingerprint = stringField(payload, "query_fingerprint") ?? proposal.change_set.evidence.query_fingerprint;
@@ -13820,7 +15245,7 @@ function formatMcpAuditMarkdown(report) {
 `;
 }
 function stringField(record, key) {
-  if (!isRecord6(record)) return void 0;
+  if (!isRecord7(record)) return void 0;
   const value = record[key];
   if (typeof value === "string") return value;
   if (typeof value === "number") return String(value);
@@ -14039,6 +15464,8 @@ function isKnownTopLevelCommand(command) {
     "init",
     "inspect",
     "config",
+    "contract",
+    "dsl",
     "doctor",
     "validate",
     "apply",
@@ -14091,6 +15518,9 @@ Commands:
   up           Bring up local review mode guidance/server
   init         Generate a Synapsor capability contract
   mcp          Serve safe semantic tools over MCP
+  contract     Validate and normalize canonical Synapsor contract files
+  dsl          Compile SQL-like Synapsor authoring DSL to contract JSON
+  cloud        Register runner metadata or dry-run contract push to Cloud
   onboard      One-command own-database setup
   smoke        Test generated tool calls before wiring an MCP client
   tools        List model-facing MCP tools and aliases
@@ -14116,12 +15546,40 @@ Examples:
   ${cmd} onboard db --from-env DATABASE_URL
   ${cmd} inspect --from-env DATABASE_URL
   ${cmd} init --wizard --from-env DATABASE_URL
+  ${cmd} contract validate ./synapsor.contract.json
+  ${cmd} contract normalize ./synapsor.contract.json --out ./synapsor.contract.normalized.json
+  ${cmd} dsl compile ./contract.synapsor --out ./synapsor.contract.json
+  ${cmd} cloud push ./synapsor.contract.json --dry-run
   ${cmd} smoke call --config ./synapsor.runner.json --store ./.synapsor/local.db
   ${cmd} tools list --aliases --config ./synapsor.runner.json --store ./.synapsor/local.db
   ${cmd} handler template node-fastify --output ./synapsor-writeback-handler.mjs
   ${cmd} mcp serve --config ./synapsor.runner.json --store ./.synapsor/local.db
   ${cmd} propose billing.propose_late_fee_waiver --sample
   ${cmd} audit ./synapsor.runner.json
+`,
+    contract: `Usage:
+  ${cmd} contract validate ./synapsor.contract.json [--json]
+  ${cmd} contract normalize ./synapsor.contract.json [--out ./synapsor.contract.normalized.json]
+
+Validate or normalize canonical Synapsor contract files. Contracts describe
+contexts, capabilities, workflows, evidence, proposal, receipt, and replay
+semantics. Local database URLs, ports, and store paths stay in runner config.
+`,
+    dsl: `Usage:
+  ${cmd} dsl validate ./contract.synapsor [--json]
+  ${cmd} dsl compile ./contract.synapsor --out ./synapsor.contract.json
+
+Compile the preview SQL-like Synapsor authoring DSL into canonical
+@synapsor/spec JSON. Unsupported Cloud-only/generated clauses fail explicitly
+instead of being ignored.
+`,
+    cloud: `Usage:
+  ${cmd} cloud connect --config ./synapsor.cloud.json
+  ${cmd} cloud push ./synapsor.contract.json --dry-run [--workspace <id>] [--name <registry-name>]
+
+cloud push validates and normalizes the contract locally, then prints the
+payload summary. Upload is intentionally not reported as successful until a
+real Cloud registry endpoint is wired.
 `,
     up: `Usage:
   ${cmd} up --config ./synapsor.runner.json --store ./.synapsor/local.db [--transport stdio|streamable-http]