@synapsor/runner 0.1.7 → 0.1.9

package/CHANGELOG.md

@@ -2,7 +2,51 @@
 
 ## Unreleased
 
-No unreleased changes yet.
+## 0.1.9
+
+### CLI Hygiene
+
+- Adds top-level `synapsor-runner --version`, `synapsor-runner -v`, and
+  `synapsor-runner version` output so published package checks do not look like
+  an unknown command.
+
+## 0.1.8
+
+### DSL / JSON Contract Parity
+
+- Adds portable spec fields for capability `returns_hint`, proposal
+  `numeric_bounds`, and proposal `transition_guards` so reviewed safety
+  metadata can live in canonical contracts instead of runner-private config.
+- Extends the DSL with `DESCRIPTION`, `RETURNS HINT`, arg descriptions,
+  numeric arg min/max, text `MAX LENGTH`, patch `BOUND`, and `TRANSITION`
+  clauses.
+- Adds DSL warnings and `--strict` mode so weak proposal contracts fail CI
+  instead of silently compiling.
+- Preserves compiled bounds through `contracts: []` into Runner propose-time
+  enforcement and accepts pure-contract configs with `capabilities: []`.
+- Adds `docs/dsl-json-parity.md` so developers can see which fields are
+  authored in DSL, validated in JSON, enforced by Runner, and accepted by
+  C++/Cloud.
+
+### Cloud Registry Push
+
+- Wires non-dry-run `synapsor-runner cloud push` to the Synapsor Cloud control
+  API. The CLI validates locally, posts normalized `@synapsor/spec` JSON, and
+  reports Cloud contract/version/digest details only after the server confirms
+  storage.
+- Keeps `--dry-run` network-free and updates error handling for invalid tokens,
+  missing workspace permissions, validation errors, conflicts, and network
+  failures without printing bearer tokens.
+- Documents the project-scoped Cloud registry path and backend runner-bundle
+  export foundation.
+
+### Release Verification
+
+- Adds `corepack pnpm test:live-apply` as the documented Docker-backed live
+  apply smoke. It aliases the existing MCP local examples proof and verifies
+  proposal diffs, approval outside MCP, guarded writeback, idempotent retry,
+  stale-row conflict, receipts, and replay against disposable Postgres/MySQL
+  databases.
 
 ## 0.1.7
 

package/README.md

@@ -235,6 +235,8 @@ CREATE AGENT CONTEXT local_operator
 END
 
 CREATE CAPABILITY billing.inspect_invoice
+  DESCRIPTION 'Inspect one invoice in the trusted tenant before proposing a waiver.'
+  RETURNS HINT 'Returns reviewed invoice fields plus evidence/query-audit handles.'
   USING CONTEXT local_operator
   SOURCE local_postgres
   ON public.invoices
@@ -242,13 +244,15 @@ CREATE CAPABILITY billing.inspect_invoice
   TENANT KEY tenant_id
   CONFLICT GUARD updated_at
   LOOKUP invoice_id BY id
-  ARG invoice_id STRING REQUIRED MAX 128
+  ARG invoice_id STRING REQUIRED MAX LENGTH 128 DESCRIPTION 'Invoice id such as INV-3001.'
   ALLOW READ id, tenant_id, status, late_fee_cents, updated_at
   REQUIRE EVIDENCE
   MAX ROWS 1
 END
 
 CREATE CAPABILITY billing.propose_late_fee_waiver
+  DESCRIPTION 'Propose waiving one invoice late fee after inspecting invoice and policy evidence.'
+  RETURNS HINT 'Returns a review-required proposal id, exact diff, evidence handle, and source_database_changed:false.'
   USING CONTEXT local_operator
   SOURCE local_postgres
   ON public.invoices
@@ -256,8 +260,8 @@ CREATE CAPABILITY billing.propose_late_fee_waiver
   TENANT KEY tenant_id
   CONFLICT GUARD updated_at
   LOOKUP invoice_id BY id
-  ARG invoice_id STRING REQUIRED MAX 128
-  ARG reason TEXT REQUIRED MAX 500
+  ARG invoice_id STRING REQUIRED MAX LENGTH 128 DESCRIPTION 'Invoice id such as INV-3001.'
+  ARG reason TEXT REQUIRED MAX LENGTH 500 DESCRIPTION 'Business reason for the proposed waiver.'
   ALLOW READ id, tenant_id, status, late_fee_cents, waiver_reason, updated_at
   REQUIRE EVIDENCE
   MAX ROWS 1
@@ -265,6 +269,7 @@ CREATE CAPABILITY billing.propose_late_fee_waiver
   ALLOW WRITE late_fee_cents, waiver_reason
   PATCH late_fee_cents = 0
   PATCH waiver_reason = ARG reason
+  BOUND late_fee_cents 0..10000
   APPROVAL ROLE billing_lead
   WRITEBACK DIRECT SQL
 END
@@ -273,20 +278,33 @@ END
 Compile, validate, and serve it:
 
 ```bash
-synapsor-runner dsl compile ./contract.synapsor --out ./synapsor.contract.json
+synapsor-runner dsl compile ./contract.synapsor --out ./synapsor.contract.json --strict
 synapsor-runner contract validate ./synapsor.contract.json
 synapsor-runner contract bundle ./synapsor.contract.json --out ./synapsor-runner-bundle
 synapsor-runner cloud push ./synapsor.contract.json --dry-run
+synapsor-runner cloud push ./synapsor.contract.json \
+  --api-url "$SYNAPSOR_CLOUD_BASE_URL" \
+  --token "$SYNAPSOR_CLOUD_TOKEN" \
+  --workspace "$SYNAPSOR_PROJECT_ID" \
+  --name billing-late-fee
 cd ./synapsor-runner-bundle
 cp .env.example .env  # fill in and export your read-only database values
 synapsor-runner mcp serve --config ./synapsor.runner.json --store ./.synapsor/local.db
 ```
 
+`--strict` treats DSL safety warnings as errors, so CI catches proposal
+capabilities that are missing descriptions, returns hints, or numeric patch
+bounds.
+
 The `contract bundle` step generates `synapsor.runner.json` (with env-var
 placeholders) inside the bundle directory, which is why `mcp serve` runs from
 there. The server keeps stdout clean for MCP protocol frames and prints its
 ready line on stderr.
 
+See [`docs/dsl-json-parity.md`](docs/dsl-json-parity.md) for the current
+field-by-field support matrix across JSON spec, DSL, runner enforcement,
+C++/Cloud compatibility, and Cloud push.
+
 Your `synapsor.runner.json` supplies local wiring: database env var names,
 SQLite store path, MCP transport settings, and local debug options. The
 contract supplies the portable meaning: contexts, capabilities, evidence,
@@ -406,6 +424,18 @@ and proves the proposal-first write path:
 npx -y -p @synapsor/runner synapsor-runner demo
 ```
 
+For contributor/release verification from a checkout, the live apply smoke uses
+disposable Postgres/MySQL containers and the official MCP stdio client transport:
+
+```bash
+corepack pnpm test:live-apply
+```
+
+It verifies semantic tool listing, proposal diffs, source rows unchanged before
+approval, guarded writeback, idempotent retry, stale-row conflict, receipts, and
+replay. See [`docs/local-mode.md`](docs/local-mode.md#local-mcp-smoke) for
+prerequisites and expected output.
+
 After the demo prints its generated config and store path, run the happy path it
 prints. The shape is:
 
@@ -1205,6 +1235,11 @@ Portable contracts can be checked locally before Cloud import:
 synapsor-runner contract validate ./synapsor.contract.json
 synapsor-runner contract bundle ./synapsor.contract.json --out ./synapsor-runner-bundle
 synapsor-runner cloud push ./synapsor.contract.json --dry-run
+synapsor-runner cloud push ./synapsor.contract.json \
+  --api-url "$SYNAPSOR_CLOUD_BASE_URL" \
+  --token "$SYNAPSOR_CLOUD_TOKEN" \
+  --workspace "$SYNAPSOR_PROJECT_ID" \
+  --name billing-late-fee
 ```
 
 ## Current Limitations

package/dist/cli.d.ts.map

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

package/dist/runner.mjs

@@ -890,6 +890,7 @@ function validateExecutorAuth(value, path4, strict, errors) {
 function validateCapabilities(value, sources, contexts, executors, mode, strict, errors, warnings, hasContracts = false) {
   if (mode === "cloud" && value === void 0) return;
   if (hasContracts && value === void 0) return;
+  if (hasContracts && Array.isArray(value) && value.length === 0) return;
   if (!Array.isArray(value) || value.length === 0) {
     errors.push({ path: "$.capabilities", code: "CAPABILITIES_REQUIRED", message: "At least one capability is required." });
     return;
@@ -2812,13 +2813,15 @@ var METADATA_KEYS = /* @__PURE__ */ new Set(["name", "description", "version", "
 var RESOURCE_KEYS = /* @__PURE__ */ new Set(["name", "engine", "schema", "table", "type", "primary_key", "tenant_key", "conflict_key", "single_tenant_dev"]);
 var CONTEXT_KEYS2 = /* @__PURE__ */ new Set(["name", "description", "bindings", "tenant_binding", "principal_binding"]);
 var BINDING_KEYS = /* @__PURE__ */ new Set(["name", "source", "key", "required"]);
-var CAPABILITY_KEYS2 = /* @__PURE__ */ new Set(["name", "description", "kind", "context", "source", "subject", "args", "lookup", "visible_fields", "kept_out_fields", "evidence", "max_rows", "proposal"]);
+var CAPABILITY_KEYS2 = /* @__PURE__ */ new Set(["name", "description", "returns_hint", "kind", "context", "source", "subject", "args", "lookup", "visible_fields", "kept_out_fields", "evidence", "max_rows", "proposal"]);
 var SUBJECT_KEYS = /* @__PURE__ */ new Set(["resource", "schema", "table", "primary_key", "tenant_key", "conflict_key", "single_tenant_dev"]);
 var ARG_KEYS2 = /* @__PURE__ */ new Set(["type", "description", "required", "max_length", "minimum", "maximum", "enum"]);
 var LOOKUP_KEYS2 = /* @__PURE__ */ new Set(["id_from_arg"]);
 var EVIDENCE_KEYS = /* @__PURE__ */ new Set(["required", "sources", "query_audit", "handle_prefix"]);
-var PROPOSAL_KEYS = /* @__PURE__ */ new Set(["action", "allowed_fields", "patch", "conflict_guard", "approval", "writeback"]);
+var PROPOSAL_KEYS = /* @__PURE__ */ new Set(["action", "allowed_fields", "patch", "numeric_bounds", "transition_guards", "conflict_guard", "approval", "writeback"]);
 var PATCH_KEYS = /* @__PURE__ */ new Set(["fixed", "from_arg"]);
+var NUMERIC_BOUND_KEYS2 = /* @__PURE__ */ new Set(["minimum", "maximum"]);
+var TRANSITION_GUARD_KEYS2 = /* @__PURE__ */ new Set(["from_column", "allowed"]);
 var CONFLICT_GUARD_KEYS2 = /* @__PURE__ */ new Set(["column", "weak_guard_ack"]);
 var APPROVAL_KEYS2 = /* @__PURE__ */ new Set(["mode", "required_role"]);
 var WRITEBACK_KEYS2 = /* @__PURE__ */ new Set(["mode", "executor", "idempotency_key"]);
@@ -2997,6 +3000,8 @@ function validateCapabilities2(value, contextNames, resourceNames, errors, warni
       errors.push({ path: `${path4}.name`, code: "INVALID_CAPABILITY_NAME", message: "capability name must be namespace.name." });
     else
       addUnique(names, capability.name, `${path4}.name`, "DUPLICATE_CAPABILITY_NAME", errors);
+    if (capability.returns_hint !== void 0 && !isNonEmptyString2(capability.returns_hint))
+      errors.push({ path: `${path4}.returns_hint`, code: "INVALID_RETURNS_HINT", message: "returns_hint must be a non-empty string." });
     if (!["read", "proposal", "external_action", "answer_with_evidence"].includes(String(capability.kind)))
       errors.push({ path: `${path4}.kind`, code: "INVALID_CAPABILITY_KIND", message: "kind must be read, proposal, external_action, or answer_with_evidence." });
     if (!isNonEmptyString2(capability.context) || !contextNames.has(capability.context))
@@ -3059,6 +3064,20 @@ function validateArgs2(value, path4, errors) {
     checkUnknownKeys2(arg, ARG_KEYS2, argPath, errors);
     if (!["string", "number", "boolean"].includes(String(arg.type)))
       errors.push({ path: `${argPath}.type`, code: "INVALID_ARG_TYPE", message: "arg type must be string, number, or boolean." });
+    if (arg.description !== void 0 && !isNonEmptyString2(arg.description))
+      errors.push({ path: `${argPath}.description`, code: "INVALID_ARG_DESCRIPTION", message: "arg description must be a non-empty string." });
+    if (arg.max_length !== void 0 && (!Number.isInteger(arg.max_length) || Number(arg.max_length) <= 0))
+      errors.push({ path: `${argPath}.max_length`, code: "INVALID_MAX_LENGTH", message: "max_length must be a positive integer." });
+    if ((arg.minimum !== void 0 || arg.maximum !== void 0) && arg.type !== "number")
+      errors.push({ path: argPath, code: "NUMERIC_BOUNDS_REQUIRE_NUMBER", message: "minimum/maximum can only be used with number args." });
+    if (arg.minimum !== void 0 && !isFiniteNumber2(arg.minimum))
+      errors.push({ path: `${argPath}.minimum`, code: "INVALID_MINIMUM", message: "minimum must be a finite number." });
+    if (arg.maximum !== void 0 && !isFiniteNumber2(arg.maximum))
+      errors.push({ path: `${argPath}.maximum`, code: "INVALID_MAXIMUM", message: "maximum must be a finite number." });
+    if (isFiniteNumber2(arg.minimum) && isFiniteNumber2(arg.maximum) && Number(arg.minimum) > Number(arg.maximum))
+      errors.push({ path: argPath, code: "INVALID_ARG_NUMERIC_RANGE", message: "minimum must be less than or equal to maximum." });
+    if (arg.enum !== void 0 && (!Array.isArray(arg.enum) || arg.enum.length === 0))
+      errors.push({ path: `${argPath}.enum`, code: "INVALID_ARG_ENUM", message: "enum must be a non-empty array when provided." });
   }
 }
 function validateLookup2(value, path4, args, errors) {
@@ -3109,6 +3128,8 @@ function validateProposalAction(value, path4, errors) {
         errors.push({ path: patchPath, code: "PATCH_BINDING_REQUIRED", message: "patch binding must include fixed or from_arg." });
     }
   }
+  validateNumericBounds2(value.numeric_bounds, value.patch, `${path4}.numeric_bounds`, errors);
+  validateTransitionGuards2(value.transition_guards, value.patch, `${path4}.transition_guards`, errors);
   if (value.conflict_guard !== void 0) {
     if (!isRecord3(value.conflict_guard))
       errors.push({ path: `${path4}.conflict_guard`, code: "CONFLICT_GUARD_NOT_OBJECT", message: "conflict_guard must be an object." });
@@ -3128,6 +3149,74 @@ function validateProposalAction(value, path4, errors) {
       errors.push({ path: `${path4}.writeback.mode`, code: "INVALID_WRITEBACK_MODE", message: "writeback.mode must be direct_sql, app_handler, cloud_worker, or none." });
   }
 }
+function validateNumericBounds2(value, patch, path4, errors) {
+  if (value === void 0)
+    return;
+  if (!isRecord3(value)) {
+    errors.push({ path: path4, code: "NUMERIC_BOUNDS_NOT_OBJECT", message: "numeric_bounds must map patch fields to numeric bounds." });
+    return;
+  }
+  const patchFields = isRecord3(patch) ? new Set(Object.keys(patch)) : /* @__PURE__ */ new Set();
+  for (const [field, bounds] of Object.entries(value)) {
+    const boundPath = `${path4}.${field}`;
+    if (!isSafeIdentifier2(field))
+      errors.push({ path: boundPath, code: "INVALID_NUMERIC_BOUND_FIELD", message: "numeric_bounds keys must be safe patch fields." });
+    if (!patchFields.has(field))
+      errors.push({ path: boundPath, code: "NUMERIC_BOUND_PATCH_FIELD_REQUIRED", message: "numeric_bounds can only constrain fields in proposal.patch." });
+    if (!isRecord3(bounds)) {
+      errors.push({ path: boundPath, code: "NUMERIC_BOUND_NOT_OBJECT", message: "numeric bound must be an object." });
+      continue;
+    }
+    checkUnknownKeys2(bounds, NUMERIC_BOUND_KEYS2, boundPath, errors);
+    const hasMinimum = bounds.minimum !== void 0;
+    const hasMaximum = bounds.maximum !== void 0;
+    if (!hasMinimum && !hasMaximum)
+      errors.push({ path: boundPath, code: "NUMERIC_BOUND_EMPTY", message: "numeric bound must define minimum, maximum, or both." });
+    if (hasMinimum && !isFiniteNumber2(bounds.minimum))
+      errors.push({ path: `${boundPath}.minimum`, code: "INVALID_MINIMUM", message: "minimum must be a finite number." });
+    if (hasMaximum && !isFiniteNumber2(bounds.maximum))
+      errors.push({ path: `${boundPath}.maximum`, code: "INVALID_MAXIMUM", message: "maximum must be a finite number." });
+    if (isFiniteNumber2(bounds.minimum) && isFiniteNumber2(bounds.maximum) && Number(bounds.minimum) > Number(bounds.maximum)) {
+      errors.push({ path: boundPath, code: "INVALID_NUMERIC_RANGE", message: "minimum must be less than or equal to maximum." });
+    }
+  }
+}
+function validateTransitionGuards2(value, patch, path4, errors) {
+  if (value === void 0)
+    return;
+  if (!isRecord3(value)) {
+    errors.push({ path: path4, code: "TRANSITION_GUARDS_NOT_OBJECT", message: "transition_guards must map patch fields to allowed state transitions." });
+    return;
+  }
+  const patchFields = isRecord3(patch) ? new Set(Object.keys(patch)) : /* @__PURE__ */ new Set();
+  for (const [field, guard] of Object.entries(value)) {
+    const guardPath = `${path4}.${field}`;
+    if (!isSafeIdentifier2(field))
+      errors.push({ path: guardPath, code: "INVALID_TRANSITION_GUARD_FIELD", message: "transition_guards keys must be safe patch fields." });
+    if (!patchFields.has(field))
+      errors.push({ path: guardPath, code: "TRANSITION_GUARD_PATCH_FIELD_REQUIRED", message: "transition_guards can only constrain fields in proposal.patch." });
+    if (!isRecord3(guard)) {
+      errors.push({ path: guardPath, code: "TRANSITION_GUARD_NOT_OBJECT", message: "transition guard must be an object." });
+      continue;
+    }
+    checkUnknownKeys2(guard, TRANSITION_GUARD_KEYS2, guardPath, errors);
+    if (guard.from_column !== void 0 && !isSafeIdentifier2(guard.from_column)) {
+      errors.push({ path: `${guardPath}.from_column`, code: "INVALID_TRANSITION_FROM_COLUMN", message: "from_column must be a safe identifier." });
+    }
+    if (!isRecord3(guard.allowed) || Object.keys(guard.allowed).length === 0) {
+      errors.push({ path: `${guardPath}.allowed`, code: "TRANSITION_ALLOWED_REQUIRED", message: "transition guard must define allowed transitions." });
+      continue;
+    }
+    for (const [from, toValues] of Object.entries(guard.allowed)) {
+      const allowedPath = `${guardPath}.allowed.${from}`;
+      if (!isNonEmptyString2(from))
+        errors.push({ path: allowedPath, code: "TRANSITION_FROM_REQUIRED", message: "transition source state must be a non-empty string." });
+      if (!Array.isArray(toValues) || toValues.length === 0 || toValues.some((item) => !isNonEmptyString2(item))) {
+        errors.push({ path: allowedPath, code: "TRANSITION_TO_VALUES_REQUIRED", message: "transition target states must be non-empty strings." });
+      }
+    }
+  }
+}
 function validateWorkflows(value, contextNames, capabilityNames, errors) {
   if (value === void 0)
     return;
@@ -3311,6 +3400,9 @@ function isQualifiedOrSafeName(value) {
 function isPositiveInteger2(value) {
   return Number.isInteger(value) && Number(value) > 0;
 }
+function isFiniteNumber2(value) {
+  return typeof value === "number" && Number.isFinite(value);
+}
 
 // packages/spec/dist/normalize.js
 function normalizeContract(input) {
@@ -3428,6 +3520,7 @@ function runtimeCapabilityFromSpec(capability, resources, config) {
     name: capability.name,
     kind: capability.kind === "proposal" ? "proposal" : "read",
     ...capability.description ? { description: capability.description } : {},
+    ...capability.returns_hint ? { returns_hint: capability.returns_hint } : {},
     source,
     context: capability.context,
     target: target2,
@@ -3440,6 +3533,8 @@ function runtimeCapabilityFromSpec(capability, resources, config) {
   if (capability.kind === "proposal" && capability.proposal) {
     runtime.patch = capability.proposal.patch;
     runtime.allowed_columns = capability.proposal.allowed_fields;
+    runtime.numeric_bounds = capability.proposal.numeric_bounds;
+    runtime.transition_guards = capability.proposal.transition_guards;
     runtime.conflict_guard = capability.proposal.conflict_guard;
     runtime.approval = capability.proposal.approval;
     runtime.writeback = {
@@ -6590,7 +6685,7 @@ function parseAgentDsl(source) {
   }
   return { contexts, capabilities, workflows };
 }
-function compileAgentDsl(source) {
+function compileAgentDslWithWarnings(source) {
   const ast = parseAgentDsl(source);
   const contexts = ast.contexts.map((context) => ({
     name: context.name,
@@ -6602,6 +6697,8 @@ function compileAgentDsl(source) {
     const spec = {
       name: capability.name,
       kind: capability.kind,
+      ...capability.description ? { description: capability.description } : {},
+      ...capability.returnsHint ? { returns_hint: capability.returnsHint } : {},
       context: capability.context,
       ...capability.source ? { source: capability.source } : {},
       subject: {
@@ -6611,7 +6708,7 @@ function compileAgentDsl(source) {
         ...capability.tenantKey ? { tenant_key: capability.tenantKey } : {},
         ...capability.conflictKey ? { conflict_key: capability.conflictKey } : {}
       },
-      args: capability.args,
+      args: specArgsFromDsl(capability.args),
       ...capability.lookup ? { lookup: { id_from_arg: capability.lookup.arg } } : {},
       visible_fields: capability.visibleFields,
       ...capability.keptOutFields.length ? { kept_out_fields: capability.keptOutFields } : {},
@@ -6623,6 +6720,8 @@ function compileAgentDsl(source) {
         action: capability.proposal.action,
         allowed_fields: capability.proposal.allowedFields,
         patch: capability.proposal.patch,
+        ...capability.proposal.numericBounds ? { numeric_bounds: capability.proposal.numericBounds } : {},
+        ...capability.proposal.transitionGuards ? { transition_guards: capability.proposal.transitionGuards } : {},
         conflict_guard: capability.conflictKey ? { column: capability.conflictKey } : { weak_guard_ack: true },
         approval: { mode: "human", required_role: capability.proposal.approvalRole ?? "local_reviewer" },
         writeback: {
@@ -6649,12 +6748,12 @@ function compileAgentDsl(source) {
     ...workflows.length ? { workflows } : {}
   };
   assertValidContract(contract);
-  return normalizeContract(contract);
+  return { contract: normalizeContract(contract), warnings: collectDslWarnings(ast) };
 }
 function validateAgentDsl(source) {
   try {
-    compileAgentDsl(source);
-    return { ok: true, errors: [], warnings: [] };
+    const result = compileAgentDslWithWarnings(source);
+    return { ok: true, errors: [], warnings: result.warnings };
   } catch (error) {
     if (error instanceof AgentDslError) {
       return {
@@ -6739,6 +6838,7 @@ function parseContextBlock(block) {
 function parseCapabilityBlock(block) {
   const capability = {
     name: block.name,
+    line: block.line,
     kind: "read",
     context: "",
     schema: "",
@@ -6749,6 +6849,16 @@ function parseCapabilityBlock(block) {
     keptOutFields: []
   };
   for (const item of block.body) {
+    const description = item.text.match(/^DESCRIPTION\s+'(.*)'$/i);
+    if (description) {
+      capability.description = description[1] ?? "";
+      continue;
+    }
+    const returnsHint = item.text.match(/^RETURNS\s+HINT\s+'(.*)'$/i);
+    if (returnsHint) {
+      capability.returnsHint = returnsHint[1] ?? "";
+      continue;
+    }
     const context = item.text.match(/^USING\s+CONTEXT\s+([A-Za-z_][A-Za-z0-9_.]*)$/i);
     if (context?.[1]) {
       capability.context = context[1];
@@ -6780,13 +6890,9 @@ function parseCapabilityBlock(block) {
       capability.conflictKey = conflict3[1];
       continue;
     }
-    const arg = item.text.match(/^ARG\s+([A-Za-z_][A-Za-z0-9_]*)\s+(STRING|TEXT|NUMBER|BOOLEAN|BOOL)(?:\s+REQUIRED)?(?:\s+MAX\s+(\d+))?$/i);
+    const arg = item.text.match(/^ARG\s+([A-Za-z_][A-Za-z0-9_]*)\s+(STRING|TEXT|NUMBER|BOOLEAN|BOOL)\b(.*)$/i);
     if (arg?.[1] && arg[2]) {
-      capability.args[arg[1]] = {
-        type: normalizeArgType(arg[2]),
-        ...item.text.match(/\sREQUIRED(?:\s|$)/i) ? { required: true } : {},
-        ...arg[3] ? { max_length: Number(arg[3]) } : {}
-      };
+      capability.args[arg[1]] = parseArgSpec(arg[1], arg[2], arg[3] ?? "", item.line);
       continue;
     }
     const lookup = item.text.match(/^LOOKUP\s+([A-Za-z_][A-Za-z0-9_]*)\s+BY\s+([A-Za-z_][A-Za-z0-9_]*)$/i);
@@ -6836,6 +6942,30 @@ function parseCapabilityBlock(block) {
         capability.proposal.allowedFields.push(patch[1]);
       continue;
     }
+    const bound = item.text.match(/^BOUND\s+([A-Za-z_][A-Za-z0-9_]*)\s+(-?\d+(?:\.\d+)?)?\s*\.\.\s*(-?\d+(?:\.\d+)?)?$/i);
+    if (bound?.[1]) {
+      ensureProposal(capability, item);
+      const minimum = bound[2] !== void 0 ? Number(bound[2]) : void 0;
+      const maximum = bound[3] !== void 0 ? Number(bound[3]) : void 0;
+      if (minimum === void 0 && maximum === void 0)
+        throw dslError(item.line, 1, "BOUND_RANGE_REQUIRED", "BOUND requires minimum, maximum, or both, such as 1..2500");
+      capability.proposal.numericBounds ??= {};
+      capability.proposal.numericBounds[bound[1]] = {
+        ...minimum !== void 0 ? { minimum } : {},
+        ...maximum !== void 0 ? { maximum } : {}
+      };
+      continue;
+    }
+    const transition = item.text.match(/^TRANSITION\s+([A-Za-z_][A-Za-z0-9_]*)(?:\s+FROM\s+([A-Za-z_][A-Za-z0-9_]*))?\s+ALLOW\s+(.+)$/i);
+    if (transition?.[1] && transition[3]) {
+      ensureProposal(capability, item);
+      capability.proposal.transitionGuards ??= {};
+      capability.proposal.transitionGuards[transition[1]] = {
+        ...transition[2] ? { from_column: transition[2] } : {},
+        allowed: parseTransitionAllowed(transition[3], item.line)
+      };
+      continue;
+    }
     const approval = item.text.match(/^APPROVAL\s+ROLE\s+([A-Za-z_][A-Za-z0-9_.-]*)$/i);
     if (approval?.[1]) {
       ensureProposal(capability, item);
@@ -6868,6 +6998,40 @@ function parseCapabilityBlock(block) {
     throw dslError(block.line, 1, "PROPOSAL_PATCH_REQUIRED", `${block.name} proposal requires at least one PATCH line`);
   return capability;
 }
+function specArgsFromDsl(args) {
+  return Object.fromEntries(Object.entries(args).map(([name, arg]) => {
+    const { line: _line, ...spec } = arg;
+    return [name, spec];
+  }));
+}
+function collectDslWarnings(ast) {
+  const warnings = [];
+  for (const capability of ast.capabilities) {
+    if (capability.kind !== "proposal" || !capability.proposal)
+      continue;
+    const line = capability.line ?? 1;
+    if (!capability.description) {
+      warnings.push({ line, column: 1, code: "DESCRIPTION_RECOMMENDED", message: `${capability.name} is a proposal capability without DESCRIPTION.` });
+    }
+    if (!capability.returnsHint) {
+      warnings.push({ line, column: 1, code: "RETURNS_HINT_RECOMMENDED", message: `${capability.name} is a proposal capability without RETURNS HINT.` });
+    }
+    for (const [column, binding] of Object.entries(capability.proposal.patch)) {
+      if (!binding.from_arg)
+        continue;
+      const arg = capability.args[binding.from_arg];
+      if (arg?.type === "number" && arg.minimum === void 0 && arg.maximum === void 0 && capability.proposal.numericBounds?.[column] === void 0) {
+        warnings.push({
+          line: arg.line ?? line,
+          column: 1,
+          code: "NUMERIC_PATCH_BOUND_RECOMMENDED",
+          message: `${capability.name} patches ${column} from numeric arg ${binding.from_arg} without ARG MIN/MAX or BOUND ${column}.`
+        });
+      }
+    }
+  }
+  return warnings;
+}
 function parseWorkflowBlock(block) {
   const workflow = { name: block.name, context: "", allowedCapabilities: [] };
   for (const item of block.body) {
@@ -6925,6 +7089,76 @@ function parsePatchBinding(raw) {
     return { fixed: quoted[1] ?? "" };
   return { fixed: trimmed };
 }
+function parseArgSpec(name, rawType, rawOptions, line) {
+  const type = normalizeArgType(rawType);
+  let rest = rawOptions.trim();
+  let description;
+  const descriptionMatch = rest.match(/\bDESCRIPTION\s+'([^']*)'/i);
+  if (descriptionMatch) {
+    description = descriptionMatch[1] ?? "";
+    rest = `${rest.slice(0, descriptionMatch.index)} ${rest.slice((descriptionMatch.index ?? 0) + descriptionMatch[0].length)}`.trim();
+  }
+  const required = /\bREQUIRED\b/i.test(rest);
+  rest = rest.replace(/\bREQUIRED\b/ig, " ").trim();
+  const maxLengthMatch = rest.match(/\bMAX\s+LENGTH\s+(\d+)\b/i);
+  const maxLength = maxLengthMatch?.[1] ? Number(maxLengthMatch[1]) : void 0;
+  if (maxLengthMatch)
+    rest = `${rest.slice(0, maxLengthMatch.index)} ${rest.slice((maxLengthMatch.index ?? 0) + maxLengthMatch[0].length)}`.trim();
+  const minMatch = rest.match(/\bMIN\s+(-?\d+(?:\.\d+)?)\b/i);
+  const minimum = minMatch?.[1] ? Number(minMatch[1]) : void 0;
+  if (minMatch)
+    rest = `${rest.slice(0, minMatch.index)} ${rest.slice((minMatch.index ?? 0) + minMatch[0].length)}`.trim();
+  const maxMatch = rest.match(/\bMAX\s+(-?\d+(?:\.\d+)?)\b/i);
+  const maximumOrLegacyLength = maxMatch?.[1] ? Number(maxMatch[1]) : void 0;
+  if (maxMatch)
+    rest = `${rest.slice(0, maxMatch.index)} ${rest.slice((maxMatch.index ?? 0) + maxMatch[0].length)}`.trim();
+  if (rest.trim().length > 0) {
+    throw dslError(line, 1, "ARG_OPTIONS_UNSUPPORTED", `unsupported ARG options for ${name}: ${rest.trim()}`);
+  }
+  if (type !== "number" && minimum !== void 0) {
+    throw dslError(line, 1, "ARG_MIN_REQUIRES_NUMBER", `ARG ${name} uses MIN, but MIN is only valid for NUMBER args`);
+  }
+  if (type === "boolean" && (maxLength !== void 0 || maximumOrLegacyLength !== void 0)) {
+    throw dslError(line, 1, "ARG_MAX_INVALID_FOR_BOOLEAN", `ARG ${name} cannot use MAX or MAX LENGTH because BOOLEAN has no numeric or length bound`);
+  }
+  if (type === "number" && maxLength !== void 0) {
+    throw dslError(line, 1, "ARG_MAX_LENGTH_REQUIRES_TEXT", `ARG ${name} uses MAX LENGTH, but MAX LENGTH is only valid for STRING/TEXT args`);
+  }
+  return {
+    type,
+    line,
+    ...required ? { required: true } : {},
+    ...description !== void 0 ? { description } : {},
+    ...type === "number" && minimum !== void 0 ? { minimum } : {},
+    ...type === "number" && maximumOrLegacyLength !== void 0 ? { maximum: maximumOrLegacyLength } : {},
+    ...type !== "number" && maxLength !== void 0 ? { max_length: maxLength } : {},
+    ...type !== "number" && maxLength === void 0 && maximumOrLegacyLength !== void 0 ? { max_length: maximumOrLegacyLength } : {}
+  };
+}
+function parseTransitionAllowed(raw, line) {
+  const allowed = {};
+  for (const item of raw.split(",").map((part) => part.trim()).filter(Boolean)) {
+    const match = item.match(/^(.+?)\s*->\s*(.+)$/);
+    if (!match?.[1] || !match[2]) {
+      throw dslError(line, 1, "TRANSITION_RULE_INVALID", `transition rule must use from -> to syntax: ${item}`);
+    }
+    const from = parseStateValue(match[1]);
+    const toValues = match[2].split("|").map(parseStateValue).filter(Boolean);
+    if (!from || toValues.length === 0) {
+      throw dslError(line, 1, "TRANSITION_RULE_INVALID", `transition rule must name non-empty states: ${item}`);
+    }
+    allowed[from] = toValues;
+  }
+  if (Object.keys(allowed).length === 0) {
+    throw dslError(line, 1, "TRANSITION_ALLOWED_REQUIRED", "TRANSITION requires at least one from -> to rule");
+  }
+  return allowed;
+}
+function parseStateValue(raw) {
+  const trimmed = raw.trim();
+  const quoted = trimmed.match(/^'(.*)'$/);
+  return (quoted?.[1] ?? trimmed).trim();
+}
 function normalizeBindingSource(source) {
   const normalized = source.toUpperCase();
   if (normalized === "ENV")
@@ -8145,6 +8379,11 @@ async function main(argv) {
     usage([]);
     return 0;
   }
+  if (command === "--version" || command === "-v" || command === "version") {
+    process2.stdout.write(`${await runnerPackageVersion()}
+`);
+    return 0;
+  }
   if (!isKnownTopLevelCommand(command)) {
     process2.stderr.write(`Unknown command: ${cliCommandName()} ${command}
 
@@ -9331,12 +9570,15 @@ async function dslValidate(args) {
   const target2 = firstPositional(args);
   if (!target2) throw new Error("dsl validate requires <contract.synapsor>");
   const source = await fs3.readFile(target2, "utf8");
+  const strict = args.includes("--strict");
   const result = validateAgentDsl(source);
   if (args.includes("--json")) {
     process2.stdout.write(`${JSON.stringify(result, null, 2)}
 `);
   } else if (result.ok) {
     process2.stdout.write(`dsl valid: ${target2}
+`);
+    for (const warning of result.warnings) process2.stdout.write(`warning ${warning.line}:${warning.column} ${warning.code}: ${warning.message}
 `);
   } else {
     process2.stdout.write(`dsl invalid: ${target2}
@@ -9344,13 +9586,22 @@ async function dslValidate(args) {
     for (const error of result.errors) process2.stdout.write(`error ${error.line}:${error.column} ${error.code}: ${error.message}
 `);
   }
-  return result.ok ? 0 : 1;
+  return result.ok && (!strict || result.warnings.length === 0) ? 0 : 1;
 }
 async function dslCompile(args) {
   const target2 = firstPositional(args);
   if (!target2) throw new Error("dsl compile requires <contract.synapsor>");
   const source = await fs3.readFile(target2, "utf8");
-  const contract = compileAgentDsl(source);
+  const strict = args.includes("--strict");
+  const result = compileAgentDslWithWarnings(source);
+  if (strict && result.warnings.length > 0) {
+    process2.stdout.write(`dsl warnings treated as errors: ${target2}
+`);
+    for (const warning of result.warnings) process2.stdout.write(`warning ${warning.line}:${warning.column} ${warning.code}: ${warning.message}
+`);
+    return 1;
+  }
+  const contract = result.contract;
   const output = outputArg(args);
   const text = `${JSON.stringify(contract, null, 2)}
 `;
@@ -9361,6 +9612,8 @@ async function dslCompile(args) {
   } else {
     process2.stdout.write(text);
   }
+  for (const warning of result.warnings) process2.stderr.write(`warning ${warning.line}:${warning.column} ${warning.code}: ${warning.message}
+`);
   return 0;
 }
 async function contractValidate(args) {
@@ -11291,19 +11544,33 @@ async function cloudPush(args) {
   if (!target2) throw new Error("cloud push requires <synapsor.contract.json>");
   const parsed = JSON.parse(await fs3.readFile(target2, "utf8"));
   const contract = normalizeContract(parsed);
+  const workspace = (optionalArg(args, "--workspace") ?? optionalArg(args, "--project") ?? process2.env.SYNAPSOR_WORKSPACE_ID ?? process2.env.SYNAPSOR_PROJECT_ID ?? "").trim();
+  const name = (optionalArg(args, "--name") ?? contract.metadata?.name ?? "").trim();
+  const description = (optionalArg(args, "--description") ?? contract.metadata?.description ?? "").trim();
+  const idempotencyKey = optionalArg(args, "--idempotency-key");
   const payload = {
     schema_version: "synapsor.cloud-contract-push.v0.1",
     contract,
     summary: contractSummary(contract),
-    workspace: optionalArg(args, "--workspace") ?? process2.env.SYNAPSOR_WORKSPACE_ID,
-    name: optionalArg(args, "--name") ?? contract.metadata?.name,
+    workspace,
+    name,
+    description,
+    source: "runner",
+    source_versions: {
+      "@synapsor/runner": process2.env.npm_package_version ?? "unknown"
+    },
+    activate: args.includes("--activate"),
+    idempotency_key: idempotencyKey,
     pushed_at: (/* @__PURE__ */ new Date()).toISOString()
   };
   const dryRun = args.includes("--dry-run");
-  if (args.includes("--json")) {
+  const json = args.includes("--json");
+  if (dryRun && json) {
     process2.stdout.write(`${JSON.stringify({ ok: dryRun, dry_run: dryRun, payload }, null, 2)}
 `);
-  } else {
+    return 0;
+  }
+  if (dryRun) {
     process2.stdout.write("Synapsor Cloud contract push preview\n");
     process2.stdout.write(`Contract: ${target2}
 `);
@@ -11317,17 +11584,48 @@ async function cloudPush(args) {
 `);
     process2.stdout.write(`Kept-out fields: ${payload.summary.kept_out_fields}
 `);
-  }
-  if (dryRun) {
-    if (!args.includes("--json")) process2.stdout.write("Dry run only. No Cloud upload attempted.\n");
+    process2.stdout.write("Dry run only. No Cloud upload attempted.\n");
     return 0;
   }
-  const apiUrl = optionalArg(args, "--api-url") ?? process2.env.SYNAPSOR_CLOUD_BASE_URL;
-  const token = optionalArg(args, "--token") ?? process2.env.SYNAPSOR_CLOUD_TOKEN ?? process2.env.SYNAPSOR_RUNNER_TOKEN;
+  const apiUrl = (optionalArg(args, "--api-url") ?? process2.env.SYNAPSOR_CLOUD_BASE_URL ?? "").trim();
+  const token = (optionalArg(args, "--token") ?? process2.env.SYNAPSOR_CLOUD_TOKEN ?? process2.env.SYNAPSOR_RUNNER_TOKEN ?? "").trim();
+  if (!workspace) {
+    throw new Error("cloud push upload requires --workspace <project_id> or SYNAPSOR_WORKSPACE_ID/SYNAPSOR_PROJECT_ID.");
+  }
   if (!apiUrl || !token) {
-    throw new Error("cloud push upload requires --dry-run, or real --api-url plus --token/SYNAPSOR_CLOUD_TOKEN after the Cloud registry endpoint is available.");
+    throw new Error("cloud push upload requires --api-url plus --token/SYNAPSOR_CLOUD_TOKEN. Use --dry-run for local validation without a network call.");
+  }
+  const response = await postCloudContractPush({
+    apiUrl,
+    token,
+    workspace,
+    payload,
+    idempotencyKey
+  });
+  if (json) {
+    process2.stdout.write(`${JSON.stringify(response, null, 2)}
+`);
+    return 0;
   }
-  throw new Error("cloud push upload is not wired to a Cloud registry endpoint yet. Use --dry-run for local validation; do not treat this as uploaded.");
+  const contractId = cloudStringField(response, "contract_id") || cloudStringField(response.contract, "contract_id");
+  const versionId = cloudStringField(response, "contract_version_id") || cloudStringField(response.version, "contract_version_id");
+  const digest = cloudStringField(response, "digest") || cloudStringField(response.version, "digest");
+  const status = cloudStringField(response, "status") || cloudStringField(response.version, "status") || "stored";
+  process2.stdout.write("Synapsor Cloud contract push complete\n");
+  process2.stdout.write(`Workspace: ${workspace}
+`);
+  if (contractId) process2.stdout.write(`Contract id: ${contractId}
+`);
+  if (versionId) process2.stdout.write(`Version id: ${versionId}
+`);
+  if (digest) process2.stdout.write(`Digest: ${digest}
+`);
+  process2.stdout.write(`Status: ${status}
+`);
+  const registryUrl = cloudStringField(response, "registry_url");
+  if (registryUrl) process2.stdout.write(`Registry: ${registryUrl}
+`);
+  return 0;
 }
 function contractSummary(contract) {
   return {
@@ -11338,6 +11636,81 @@ function contractSummary(contract) {
     kept_out_fields: contract.capabilities.reduce((count, capability) => count + (capability.kept_out_fields?.length ?? 0), 0)
   };
 }
+async function postCloudContractPush(input) {
+  let endpoint;
+  try {
+    endpoint = new URL(`/v1/control/projects/${encodeURIComponent(input.workspace)}/agent-contracts`, input.apiUrl.endsWith("/") ? input.apiUrl : `${input.apiUrl}/`);
+  } catch {
+    throw new Error("cloud push upload failed: --api-url/SYNAPSOR_CLOUD_BASE_URL is not a valid URL.");
+  }
+  const headers = {
+    accept: "application/json",
+    authorization: `Bearer ${input.token}`,
+    "content-type": "application/json",
+    "user-agent": "synapsor-runner-cloud-push"
+  };
+  if (input.idempotencyKey) headers["idempotency-key"] = input.idempotencyKey;
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 15e3);
+  let response;
+  try {
+    response = await fetch(endpoint, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(input.payload),
+      signal: controller.signal
+    });
+  } catch (error) {
+    const reason = error instanceof Error && (error.name === "AbortError" || error.name === "TimeoutError") ? "request timed out" : "network request failed";
+    throw new Error(`cloud push upload failed: ${reason}. Check --api-url/SYNAPSOR_CLOUD_BASE_URL and network connectivity.`);
+  } finally {
+    clearTimeout(timeout);
+  }
+  const text = await response.text();
+  const body = parseCloudResponseJson(text);
+  if (!response.ok || body.ok === false) {
+    throw new Error(cloudPushErrorMessage(response.status, body));
+  }
+  return body;
+}
+function parseCloudResponseJson(text) {
+  if (!text.trim()) return {};
+  try {
+    const parsed = JSON.parse(text);
+    return isRecord7(parsed) ? parsed : { value: parsed };
+  } catch {
+    return { raw: text.slice(0, 500) };
+  }
+}
+function cloudPushErrorMessage(status, body) {
+  const code = typeof body.error === "string" && body.error ? body.error : `http_${status}`;
+  const detail = cloudValidationDetail(body);
+  if (status === 401) return `cloud push upload failed: token is missing, invalid, or expired (${code}).`;
+  if (status === 403) return `cloud push upload failed: token does not have permission to write this workspace (${code}).`;
+  if (status === 404) return `cloud push upload failed: Cloud API URL or workspace was not found (${code}).`;
+  if (status === 409) return `cloud push upload failed: registry conflict (${code}).${detail}`;
+  if (status === 422) return `cloud push upload failed: Cloud rejected the contract (${code}).${detail}`;
+  if (status >= 500) return `cloud push upload failed: Cloud returned HTTP ${status} (${code}).`;
+  return `cloud push upload failed: Cloud returned HTTP ${status} (${code}).${detail}`;
+}
+function cloudValidationDetail(body) {
+  const errors = Array.isArray(body.errors) ? body.errors : [];
+  if (!errors.length) {
+    const message = typeof body.message === "string" ? body.message : "";
+    return message ? ` ${message}` : "";
+  }
+  const rendered = errors.slice(0, 3).map((issue) => {
+    if (!isRecord7(issue)) return String(issue);
+    const path4 = typeof issue.path === "string" ? issue.path : "$";
+    const code = typeof issue.code === "string" ? issue.code : "validation_error";
+    const message = typeof issue.message === "string" ? issue.message : "";
+    return `${path4} ${code}${message ? `: ${message}` : ""}`;
+  }).join("; ");
+  return ` ${rendered}`;
+}
+function cloudStringField(value, key) {
+  return isRecord7(value) && typeof value[key] === "string" ? value[key] : "";
+}
 async function cloudConnect(args) {
   const configPath = optionalArg(args, "--config") ?? process2.env.SYNAPSOR_MCP_CONFIG ?? "synapsor.cloud.json";
   const parsed = JSON.parse(await fs3.readFile(configPath, "utf8"));
@@ -14648,6 +15021,7 @@ function firstPositional(args) {
   const flagsWithValues = /* @__PURE__ */ new Set([
     "--allowed-columns",
     "--approval-role",
+    "--api-url",
     "--actor",
     "--action",
     "--auth-token-env",
@@ -14658,6 +15032,7 @@ function firstPositional(args) {
     "--conflict-column",
     "--cors-origin",
     "--database-url-env",
+    "--description",
     "--destination",
     "--engine",
     "--evidence",
@@ -14713,10 +15088,12 @@ function firstPositional(args) {
     "--tenant-env",
     "--tenant-key",
     "--timeout-ms",
+    "--token",
     "--to",
     "--transition-guard",
     "--url",
     "--visible-columns",
+    "--workspace",
     "--writeback-job",
     "--write-url-env"
   ]);
@@ -15733,6 +16110,16 @@ function cliCommandName() {
   if (process2.env.SYNAPSOR_RUNNER_COMMAND_NAME) return process2.env.SYNAPSOR_RUNNER_COMMAND_NAME;
   return "synapsor-runner";
 }
+async function runnerPackageVersion() {
+  if (process2.env.npm_package_version) return process2.env.npm_package_version;
+  const packageUrl = new URL("../package.json", import.meta.url);
+  try {
+    const parsed = JSON.parse(await fs3.readFile(packageUrl, "utf8"));
+    if (typeof parsed.version === "string" && parsed.version.trim()) return parsed.version.trim();
+  } catch {
+  }
+  return "unknown";
+}
 function usage(args = []) {
   const [command, subcommand] = args;
   const key = (command === "mcp" || command === "handler") && subcommand ? `${command} ${subcommand}` : command ?? "";

package/docs/capability-authoring.md

@@ -26,6 +26,8 @@ CREATE AGENT CONTEXT local_operator
 END
 
 CREATE CAPABILITY billing.inspect_invoice
+  DESCRIPTION 'Inspect one invoice in the trusted tenant before proposing a waiver.'
+  RETURNS HINT 'Returns reviewed invoice fields plus evidence/query-audit handles.'
   USING CONTEXT local_operator
   SOURCE local_postgres
   ON public.invoices
@@ -33,13 +35,15 @@ CREATE CAPABILITY billing.inspect_invoice
   TENANT KEY tenant_id
   CONFLICT GUARD updated_at
   LOOKUP invoice_id BY id
-  ARG invoice_id STRING REQUIRED MAX 128
+  ARG invoice_id STRING REQUIRED MAX LENGTH 128 DESCRIPTION 'Invoice id such as INV-3001.'
   ALLOW READ id, tenant_id, status, late_fee_cents, updated_at
   REQUIRE EVIDENCE
   MAX ROWS 1
 END
 
 CREATE CAPABILITY billing.propose_late_fee_waiver
+  DESCRIPTION 'Propose waiving one invoice late fee after inspecting invoice and policy evidence.'
+  RETURNS HINT 'Returns a review-required proposal id, exact diff, evidence handle, and source_database_changed:false.'
   USING CONTEXT local_operator
   SOURCE local_postgres
   ON public.invoices
@@ -47,8 +51,8 @@ CREATE CAPABILITY billing.propose_late_fee_waiver
   TENANT KEY tenant_id
   CONFLICT GUARD updated_at
   LOOKUP invoice_id BY id
-  ARG invoice_id STRING REQUIRED MAX 128
-  ARG reason TEXT REQUIRED MAX 500
+  ARG invoice_id STRING REQUIRED MAX LENGTH 128 DESCRIPTION 'Invoice id such as INV-3001.'
+  ARG reason TEXT REQUIRED MAX LENGTH 500 DESCRIPTION 'Business reason for the proposed waiver.'
   ALLOW READ id, tenant_id, status, late_fee_cents, waiver_reason, updated_at
   REQUIRE EVIDENCE
   MAX ROWS 1
@@ -56,6 +60,7 @@ CREATE CAPABILITY billing.propose_late_fee_waiver
   ALLOW WRITE late_fee_cents, waiver_reason
   PATCH late_fee_cents = 0
   PATCH waiver_reason = ARG reason
+  BOUND late_fee_cents 0..10000
   APPROVAL ROLE billing_lead
   WRITEBACK DIRECT SQL
 END
@@ -64,10 +69,15 @@ END
 Compile and validate:
 
 ```bash
-synapsor-runner dsl compile ./contract.synapsor --out ./synapsor.contract.json
+synapsor-runner dsl compile ./contract.synapsor --out ./synapsor.contract.json --strict
 synapsor-runner contract validate ./synapsor.contract.json
 synapsor-runner contract bundle ./synapsor.contract.json --out ./synapsor-runner-bundle
 synapsor-runner cloud push ./synapsor.contract.json --dry-run
+synapsor-runner cloud push ./synapsor.contract.json \
+  --api-url "$SYNAPSOR_CLOUD_BASE_URL" \
+  --token "$SYNAPSOR_CLOUD_TOKEN" \
+  --workspace "$SYNAPSOR_PROJECT_ID" \
+  --name billing-late-fee
 ```
 
 Reference the generated contract from local runner wiring:
@@ -95,6 +105,31 @@ synapsor-runner tools preview --config ./synapsor.runner.json --store ./.synapso
 synapsor-runner mcp serve --config ./synapsor.runner.json --store ./.synapsor/local.db
 ```
 
+`--strict` treats DSL safety warnings as errors. Use it in CI so proposal
+capabilities cannot accidentally lose descriptions, returns hints, or numeric
+patch bounds during review.
+
+## DSL / JSON Capability Parity
+
+The DSL compiles to canonical `@synapsor/spec` JSON. It must not silently weaken
+reviewed runner JSON capabilities. Current parity:
+
+| JSON field | DSL clause | Since | Notes |
+| --- | --- | --- | --- |
+| capability `description` | `DESCRIPTION '...'` | 0.1.8 | Recommended for every model-facing tool; strict mode warns when proposal capabilities omit it. |
+| capability `returns_hint` | `RETURNS HINT '...'` | 0.1.8 | Recommended for every model-facing tool; strict mode warns when proposal capabilities omit it. |
+| arg `description` | `ARG name TYPE ... DESCRIPTION '...'` | 0.1.8 | Used in MCP tool input schemas. |
+| arg `minimum` | `ARG amount NUMBER MIN 1` | 0.1.8 | NUMBER args only. |
+| arg `maximum` | `ARG amount NUMBER MAX 2500` | 0.1.8 | NUMBER args only. |
+| arg `max_length` | `ARG reason TEXT MAX LENGTH 500` | 0.1.8 | STRING/TEXT args only. Legacy `MAX 500` is still accepted for existing DSL files, but `MAX LENGTH` is the reviewed spelling. |
+| arg `enum` | Not expressible in DSL yet | 0.1 | Use embedded JSON or generated contract JSON when enum allowlists are required. |
+| proposal `numeric_bounds` | `BOUND column 1..2500`, `BOUND column ..2500`, or `BOUND column 1..` | 0.1.8 | Applies to patched numeric columns. Strict mode warns when a NUMBER arg is patched without arg min/max or a matching `BOUND`. |
+| proposal `transition_guards` | `TRANSITION status ALLOW pending -> approved\|rejected` or `TRANSITION status FROM current_status ALLOW open -> closed` | 0.1.8 | Values are state strings; use `|` for multiple target states. |
+| proposal `conflict_guard` | `CONFLICT GUARD updated_at` | 0.1 | If omitted, DSL emits an explicit weak-guard acknowledgement. Prefer a real row-version column. |
+| proposal `approval` | `APPROVAL ROLE billing_lead` | 0.1 | Local mode records the required role; enforcement is still outside the model-facing MCP tool. |
+| proposal `writeback` | `WRITEBACK DIRECT SQL`, `WRITEBACK APP HANDLER EXECUTOR name`, `WRITEBACK CLOUD WORKER`, `WRITEBACK NONE` | 0.1.7 | Handler URLs/tokens stay in `synapsor.runner.json`; contracts carry only the handler name. |
+| evidence options | `REQUIRE EVIDENCE` | 0.1 | Detailed evidence sources/handle prefixes are not expressible in DSL yet; use embedded JSON or generated contract JSON for those. |
+
 ## Direct Runner Config Path
 
 Directly embedding capabilities in `synapsor.runner.json` remains supported for

package/docs/conformance.md

@@ -26,6 +26,17 @@ The fixture set is intentionally small in 0.1. It covers the runner-supported
 semantic surface first: trusted context, scoped reads, evidence handles,
 proposal boundaries, kept-out fields, manual approval, and replay envelopes.
 
+Additional 0.1 parity coverage currently lives in tests and verification
+scripts rather than separate `cloud-push/` or `dsl-json-parity/` conformance
+fixture directories:
+
+- `docs/dsl-json-parity.md`, DSL/spec tests, and the
+  `numeric-bounds-transition` C++ export fixture cover richer DSL/JSON parity
+  fields such as `returns_hint`, numeric bounds, and transition guards.
+- The main Synapsor repo script `scripts/verify_contract_cloud_push.sh`
+  verifies real Cloud push, retrieval, idempotent versioning, unauthorized
+  rejection, and runner-bundle download against a live local control-plane.
+
 ## Runner Usage
 
 Runner tests load every conformance `contract.json` and verify that the MCP

package/docs/local-mode.md

@@ -351,6 +351,28 @@ It launches the official MCP stdio client transport against `synapsor-runner mcp
 The business state changed after the agent saw it, so Synapsor refused to commit.
 ```
 
+The same live writeback smoke has a clearer release-check alias:
+
+```bash
+corepack pnpm test:live-apply
+```
+
+Prerequisites:
+
+- Docker daemon running;
+- local ports `55433`, `55434`, and `53307` available;
+- no Synapsor Cloud account, API key, hosted workspace, or production database.
+
+Expected output:
+
+- disposable Postgres billing, Postgres support, and MySQL orders containers start;
+- MCP `tools/list` exposes reviewed semantic tools, not raw SQL;
+- proposal calls create exact before/after diffs while source rows remain unchanged;
+- local approval happens outside MCP;
+- guarded writeback applies approved jobs and records receipts/replay;
+- idempotent retry returns the existing receipt;
+- a stale-row write is blocked as a conflict.
+
 ## Optional MCP client configs
 
 After the Docker demo passes, developers who want to attach an MCP client can use the checked-in stdio config shapes in:

package/docs/migrating-to-synapsor-spec.md

@@ -139,7 +139,7 @@ You can also compile from the SQL-like authoring layer:
 
 ```bash
 synapsor-runner dsl validate ./contract.synapsor
-synapsor-runner dsl compile ./contract.synapsor --out ./synapsor.contract.json
+synapsor-runner dsl compile ./contract.synapsor --out ./synapsor.contract.json --strict
 ```
 
 ## Bundle For Local Runner

package/docs/release-notes.md

@@ -10,6 +10,45 @@ npx -y -p @synapsor/runner synapsor-runner demo --quick
 The OSS runner command is `synapsor-runner`. The `synapsor` command is reserved
 for the Synapsor Cloud CLI.
 
+## Unreleased
+
+## 0.1.9
+
+### CLI Hygiene
+
+- Adds top-level `synapsor-runner --version`, `synapsor-runner -v`, and
+  `synapsor-runner version` output.
+
+## 0.1.8
+
+### DSL / JSON Contract Parity
+
+- Adds portable spec fields for capability `returns_hint`, proposal
+  `numeric_bounds`, and proposal `transition_guards`.
+- Extends the DSL with `DESCRIPTION`, `RETURNS HINT`, arg descriptions,
+  numeric arg min/max, text `MAX LENGTH`, patch `BOUND`, and `TRANSITION`
+  clauses.
+- Adds DSL warnings and `--strict` mode so proposal capabilities cannot
+  silently lose reviewed safety metadata.
+- Preserves compiled bounds through `contracts: []` into Runner propose-time
+  enforcement and accepts pure-contract configs with `capabilities: []`.
+- Adds `docs/dsl-json-parity.md` as the field-by-field support matrix across
+  JSON spec, DSL, Runner, C++/Cloud, and Cloud push.
+
+### Cloud Registry Push
+
+- Wires non-dry-run `synapsor-runner cloud push` to the Cloud control API.
+- Keeps dry-run network-free and prints server-confirmed contract, version,
+  digest, and registry details for real uploads.
+- Adds clearer 401/403/404/409/422/network error messages without printing
+  bearer tokens.
+
+### Release Verification
+
+- Adds `corepack pnpm test:live-apply` as the documented Docker-backed live
+  apply smoke for disposable Postgres/MySQL MCP examples, guarded writeback,
+  idempotent retry, stale-row conflict, receipts, and replay.
+
 ## 0.1.5
 
 ### Contract Authoring Front Door

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synapsor/runner",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Stop giving AI agents execute_sql; expose reviewed Postgres/MySQL MCP actions with proposals, approval, writeback, and replay.",
   "license": "Apache-2.0",
   "type": "module",