@synapsor/runner 0.1.6 → 0.1.8

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

package/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,36 @@ 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
+
+### 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.6",
+  "version": "0.1.8",
   "description": "Stop giving AI agents execute_sql; expose reviewed Postgres/MySQL MCP actions with proposals, approval, writeback, and replay.",
   "license": "Apache-2.0",
   "type": "module",
@@ -52,11 +52,6 @@
   "engines": {
     "node": ">=22.5.0"
   },
-  "scripts": {
-    "build": "tsc -b && node ../../scripts/build-runner-package.mjs",
-    "prepack": "cd ../.. && corepack pnpm build:runner-package",
-    "test": "vitest run"
-  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.29.0",
     "mysql2": "^3.11.0",
@@ -77,5 +72,9 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b && node ../../scripts/build-runner-package.mjs",
+    "test": "vitest run"
   }
-}
+}