@synapsor/runner 0.1.13 → 0.1.15

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 ## Unreleased
 
+### Editor-Friendly DSL Source Files
+
+- Prefers `.synapsor.sql` for DSL source files so editors can provide generic
+  SQL highlighting while keeping `.synapsor` backward compatible.
+- Keeps DSL semantics, Runner behavior, and generated canonical JSON unchanged.
+- Stages `@synapsor/dsl@0.1.5` and `@synapsor/runner@0.1.15`.
+
+### README Path Polish
+
+- Makes the audit, demo, and staging-database adoption sequence explicit for
+  readers scanning the first minute of the README.
+- Trims the inline JSON example to the reviewed capability entry and links the
+  generated storage, source, trusted-context, and timeout wiring to the full
+  own-database guide.
+- Stages `@synapsor/runner@0.1.14`; `@synapsor/spec` and `@synapsor/dsl` remain
+  unchanged for that release.
+
+## 0.1.13
+
 ### Front-Door Documentation
 
 - Rewrites the GitHub and npm READMEs around an audit-first 60-second proof,
@@ -15,6 +34,8 @@
 - Stages `@synapsor/runner@0.1.13`; `@synapsor/spec` and `@synapsor/dsl` remain
   unchanged.
 
+## 0.1.12
+
 ### Runner Version Invocation
 
 - Stages `@synapsor/runner@0.1.12` without changing or republishing

package/README.md

@@ -14,6 +14,10 @@ surface.
 
 ## Prove It In 60 Seconds
 
+The path is: **audit** your existing MCP risk, then **demo** the safety
+boundary, then **connect** a staging database. The first two commands finish in
+seconds and touch nothing but a local fixture file.
+
 First, inspect the risk in a typical raw-SQL database MCP server. This works
 even if you never adopt Runner:
 
@@ -77,48 +81,30 @@ creates trusted context, generates reviewed capabilities, previews the MCP tool
 surface, and prints the next smoke and serve commands. It stores environment
 variable names, not connection strings.
 
-A minimal generated read-only configuration looks like this:
+The interesting part of the generated configuration is the capability entry: a
+reviewed, tenant-scoped read with an explicit column allowlist and required
+evidence. The storage, source, and trusted-context wiring around it (including
+statement timeouts) is generated for you; the full file is in the
+[own-database guide](docs/getting-started-own-database.md).
 
 ```json
 {
-  "version": 1,
-  "mode": "read_only",
-  "result_format": 2,
-  "storage": { "sqlite_path": "./.synapsor/local.db" },
-  "sources": {
-    "app_postgres": {
-      "engine": "postgres",
-      "read_url_env": "DATABASE_URL",
-      "statement_timeout_ms": 3000
-    }
+  "name": "billing.inspect_invoice",
+  "kind": "read",
+  "source": "app_postgres",
+  "target": {
+    "schema": "public",
+    "table": "invoices",
+    "primary_key": "id",
+    "tenant_key": "tenant_id"
   },
-  "trusted_context": {
-    "provider": "environment",
-    "values": {
-      "tenant_id_env": "SYNAPSOR_TENANT_ID",
-      "principal_env": "SYNAPSOR_PRINCIPAL"
-    }
+  "args": {
+    "invoice_id": { "type": "string", "required": true, "max_length": 128 }
   },
-  "capabilities": [
-    {
-      "name": "billing.inspect_invoice",
-      "kind": "read",
-      "source": "app_postgres",
-      "target": {
-        "schema": "public",
-        "table": "invoices",
-        "primary_key": "id",
-        "tenant_key": "tenant_id"
-      },
-      "args": {
-        "invoice_id": { "type": "string", "required": true, "max_length": 128 }
-      },
-      "lookup": { "id_from_arg": "invoice_id" },
-      "visible_columns": ["id", "tenant_id", "status", "late_fee_cents", "updated_at"],
-      "evidence": "required",
-      "max_rows": 1
-    }
-  ]
+  "lookup": { "id_from_arg": "invoice_id" },
+  "visible_columns": ["id", "tenant_id", "status", "late_fee_cents", "updated_at"],
+  "evidence": "required",
+  "max_rows": 1
 }
 ```
 
@@ -170,7 +156,9 @@ See [Security Boundary](docs/security-boundary.md) and
 
 Runner executes locally. The spec is the portable contract shared by Runner
 and Cloud/C++. The DSL gives that contract a reviewable source format. Start
-with [Capability Authoring](docs/capability-authoring.md).
+with [Capability Authoring](docs/capability-authoring.md). Use `.synapsor.sql`
+for DSL source files when you want editors to provide generic SQL highlighting;
+legacy `.synapsor` files remain supported and produce the same contract JSON.
 
 ## OSS And Cloud
 

package/dist/runner.mjs

@@ -8439,7 +8439,7 @@ function stringOrDefault(value, fallback) {
 // apps/runner/package.json
 var package_default = {
   name: "@synapsor/runner",
-  version: "0.1.13",
+  version: "0.1.15",
   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",
@@ -8526,7 +8526,7 @@ var package_default = {
 // packages/dsl/package.json
 var package_default2 = {
   name: "@synapsor/dsl",
-  version: "0.1.4",
+  version: "0.1.5",
   description: "Preview SQL-like Synapsor authoring DSL compiler for canonical @synapsor/spec contracts.",
   license: "Apache-2.0",
   type: "module",
@@ -10139,7 +10139,7 @@ async function dslCommand(args) {
 }
 async function dslValidate(args) {
   const target2 = firstPositional(args);
-  if (!target2) throw new Error("dsl validate requires <contract.synapsor>");
+  if (!target2) throw new Error("dsl validate requires a DSL source file such as contract.synapsor.sql or contract.synapsor");
   const source = await fs3.readFile(target2, "utf8");
   const strict = args.includes("--strict");
   const result = validateAgentDsl(source);
@@ -10161,7 +10161,7 @@ async function dslValidate(args) {
 }
 async function dslCompile(args) {
   const target2 = firstPositional(args);
-  if (!target2) throw new Error("dsl compile requires <contract.synapsor>");
+  if (!target2) throw new Error("dsl compile requires a DSL source file such as contract.synapsor.sql or contract.synapsor");
   const source = await fs3.readFile(target2, "utf8");
   const strict = args.includes("--strict");
   const result = compileAgentDslWithWarnings(source);
@@ -16849,7 +16849,7 @@ Examples:
   ${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} dsl compile ./contract.synapsor.sql --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
@@ -16867,8 +16867,10 @@ 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
+  ${cmd} dsl validate ./contract.synapsor.sql [--json]
+  ${cmd} dsl compile ./contract.synapsor.sql --out ./synapsor.contract.json
+
+Both .synapsor.sql and legacy .synapsor source files are supported.
 
 Compile the preview SQL-like Synapsor authoring DSL into canonical
 @synapsor/spec JSON. Unsupported Cloud-only/generated clauses fail explicitly

package/docs/capability-authoring.md

@@ -5,9 +5,13 @@ source of truth for trusted context, resources, capabilities, evidence,
 proposal shape, and writeback intent.
 
 ```text
-contract.synapsor -> synapsor.contract.json -> synapsor.runner.json
+contract.synapsor.sql -> synapsor.contract.json -> synapsor.runner.json
 ```
 
+Use `.synapsor.sql` as the preferred DSL source extension because editors can
+provide generic SQL highlighting. Legacy `.synapsor` files remain supported;
+the suffix does not change DSL semantics or generated canonical JSON.
+
 Use `synapsor.runner.json` for local wiring: database env var names, SQLite
 store path, MCP transport settings, and local development flags. The model sees
 semantic capabilities such as `billing.inspect_invoice`, not raw SQL, table
@@ -69,7 +73,7 @@ END
 Compile and validate:
 
 ```bash
-synapsor-runner dsl compile ./contract.synapsor --out ./synapsor.contract.json --strict
+synapsor-runner dsl compile ./contract.synapsor.sql --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

package/docs/conformance.md

@@ -2,6 +2,11 @@
 
 Conformance fixtures prove behavior, not just JSON shape.
 
+The conformance artifacts are canonical JSON. When authoring a source contract
+for these checks, prefer `.synapsor.sql` for generic editor SQL highlighting;
+`.synapsor` remains backward compatible and the filename does not affect the
+compiled contract semantics.
+
 `@synapsor/spec` owns the fixtures under:
 
 ```text

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

@@ -138,10 +138,13 @@ synapsor-runner tools preview --config ./synapsor.runner.json --store ./.synapso
 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 --strict
+synapsor-runner dsl validate ./contract.synapsor.sql
+synapsor-runner dsl compile ./contract.synapsor.sql --out ./synapsor.contract.json --strict
 ```
 
+`.synapsor.sql` is the preferred editor-friendly source filename. Existing
+`.synapsor` files remain valid and compile to equivalent canonical JSON.
+
 ## Bundle For Local Runner
 
 Cloud/exported or hand-written contracts can become a local Runner bundle:

package/docs/release-notes.md

@@ -12,9 +12,17 @@ for the Synapsor Cloud CLI.
 
 ## Unreleased
 
-Prepared package version: `@synapsor/runner@0.1.12`. The already-published
-`@synapsor/spec@0.1.4` and `@synapsor/dsl@0.1.4` do not change and must not be
-republished for this release.
+### Editor-Friendly DSL Source Files
+
+- Prefers `.synapsor.sql` for DSL source files so editors can provide generic
+  SQL highlighting; `.synapsor` remains supported for compatibility.
+- The filename suffix does not change DSL semantics or generated canonical JSON.
+- Stages `@synapsor/dsl@0.1.5` and `@synapsor/runner@0.1.15`; `@synapsor/spec`
+  remains `0.1.4`.
+
+Prepared package versions: `@synapsor/dsl@0.1.5` and
+`@synapsor/runner@0.1.15`. The already-published `@synapsor/spec@0.1.4` does
+not change and must not be republished for this release.
 
 ### Runner Version Invocation
 

package/examples/support-plan-credit/README.md

@@ -27,7 +27,7 @@ When working from this source checkout, use `corepack pnpm runner` in place of
 Validate the authored boundary before starting Docker:
 
 ```bash
-synapsor-runner dsl compile examples/support-plan-credit/contract.synapsor \
+synapsor-runner dsl compile examples/support-plan-credit/contract.synapsor.sql \
   --out /tmp/support-plan-credit.contract.json \
   --strict
 synapsor-runner contract validate /tmp/support-plan-credit.contract.json
@@ -192,7 +192,7 @@ tool metadata and results. For Claude, Cursor, or generic MCP clients, omit
 
 ## How The Policy Is Governed
 
-The auto-approval policy lives in `contract.synapsor`:
+The auto-approval policy lives in `contract.synapsor.sql`:
 
 ```sql
 AUTO APPROVE WHEN plan_credit_cents <= 2500

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synapsor/runner",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "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",