@synapsor/runner 0.1.4 → 0.1.5

package/CHANGELOG.md

@@ -4,6 +4,24 @@
 
 No unreleased changes yet.
 
+## 0.1.5
+
+### Contract Authoring Front Door
+
+- Introduces `@synapsor/spec` and `@synapsor/dsl` in the main Runner README so
+  developers can find the canonical contract and SQL-like authoring layers from
+  the repo and npm package front door.
+- Adds a copy-pasteable `CREATE AGENT CONTEXT` / `CREATE CAPABILITY` authoring
+  flow that compiles to `synapsor.contract.json`, validates, bundles, dry-run
+  pushes to Cloud, and serves through Runner local wiring.
+- Refreshes capability authoring docs to lead with the contract/DSL path while
+  preserving direct `synapsor.runner.json` embedded capability authoring for
+  local experiments and compatibility.
+- Clarifies that workflow declarations are supported in contracts/DSL, while
+  Runner 0.1 does not execute full Synapsor Cloud workflow DAGs, auto-merge,
+  settlement policies, or native branching.
+- Updates the repository map to include `packages/spec` and `packages/dsl`.
+
 ## 0.1.4
 
 ### Public Repository Metadata

package/README.md

@@ -203,6 +203,88 @@ You install only `@synapsor/runner`. There is no separate handler package to
 install. A handler is your app's endpoint or script for rich approved writes;
 Runner includes templates and examples to help you build one.
 
+## Packages
+
+| Package | What it is |
+| --- | --- |
+| `@synapsor/runner` | The local runtime: CLI, MCP server, local store, evidence, proposals, approval, writeback, replay, and audit tools. |
+| `@synapsor/spec` | The canonical portable contract package for contexts, resources, capabilities, workflows, evidence, proposals, receipts, and replay. |
+| `@synapsor/dsl` | A SQL-like authoring layer that compiles `CREATE AGENT CONTEXT`, `CREATE CAPABILITY`, and `CREATE AGENT WORKFLOW` into `@synapsor/spec` JSON. |
+
+Use the runner when you want something to execute locally. Use the spec when
+you want a portable contract that Runner, Cloud, and the C++ engine can agree
+on. Use the DSL when you want to author that contract in a reviewable,
+database-style format.
+
+## Author Your Contract
+
+For new capabilities, prefer the portable contract path:
+
+```text
+contract.synapsor -> synapsor.contract.json -> synapsor.runner.json
+```
+
+Example DSL:
+
+```sql
+CREATE AGENT CONTEXT local_operator
+  BIND tenant_id FROM ENVIRONMENT SYNAPSOR_TENANT_ID REQUIRED
+  BIND principal FROM ENVIRONMENT SYNAPSOR_PRINCIPAL REQUIRED
+  TENANT BINDING tenant_id
+  PRINCIPAL BINDING principal
+END
+
+CREATE CAPABILITY billing.inspect_invoice
+  USING CONTEXT local_operator
+  SOURCE local_postgres
+  ON public.invoices
+  PRIMARY KEY id
+  TENANT KEY tenant_id
+  CONFLICT GUARD updated_at
+  LOOKUP invoice_id BY id
+  ARG invoice_id STRING REQUIRED MAX 128
+  ALLOW READ id, tenant_id, status, late_fee_cents, updated_at
+  REQUIRE EVIDENCE
+  MAX ROWS 1
+END
+
+CREATE CAPABILITY billing.propose_late_fee_waiver
+  USING CONTEXT local_operator
+  SOURCE local_postgres
+  ON public.invoices
+  PRIMARY KEY id
+  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
+  ALLOW READ id, tenant_id, status, late_fee_cents, waiver_reason, updated_at
+  REQUIRE EVIDENCE
+  MAX ROWS 1
+  PROPOSE ACTION waive_late_fee
+  ALLOW WRITE late_fee_cents, waiver_reason
+  PATCH late_fee_cents = 0
+  PATCH waiver_reason = ARG reason
+  APPROVAL ROLE billing_lead
+  WRITEBACK DIRECT SQL
+END
+```
+
+Compile, validate, and serve it:
+
+```bash
+synapsor-runner dsl compile ./contract.synapsor --out ./synapsor.contract.json
+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 mcp serve --config ./synapsor.runner.json --store ./.synapsor/local.db
+```
+
+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,
+proposal shape, and writeback intent.
+
 ## Who Does What
 
 You write the config: sources, trusted context, capabilities, visible fields,
@@ -1110,6 +1192,14 @@ The runner is useful by itself for local/staging safety. Synapsor Cloud is for
 teams, production governance, central audit, managed runners, enterprise
 controls, and proprietary Synapsor platform features.
 
+Portable contracts can be checked locally before Cloud import:
+
+```bash
+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
+```
+
 ## Current Limitations
 
 Supported in the current alpha:
@@ -1137,13 +1227,17 @@ Not supported:
 - stored procedures;
 - physical branching of external Postgres/MySQL;
 - full Synapsor workflow DAG execution;
-- `CREATE AGENT WORKFLOW`;
 - Synapsor SQL generation;
 - auto-merge or settlement-policy semantics;
 - model-callable approval or commit tools;
 - general prompt-injection prevention;
 - production SLA or compliance certification.
 
+Contract and DSL authoring can declare workflows and allowed capabilities with
+`CREATE AGENT WORKFLOW`. Runner 0.1 validates, bundles, and surfaces those
+contracts, but it does not execute full Synapsor Cloud workflow DAGs,
+auto-merge, settlement policies, or native branching.
+
 Complete limits: [docs/limitations.md](docs/limitations.md).
 
 Security boundary: [docs/security-boundary.md](docs/security-boundary.md).
@@ -1227,6 +1321,8 @@ After a manual stable publish/promotion, verify `latest`:
 ## Repository Map
 
 - `apps/runner`: CLI entrypoint and local UI.
+- `packages/spec`: canonical portable contract schemas, normalization, CLI, and conformance fixtures.
+- `packages/dsl`: SQL-like contract authoring for contexts, capabilities, and workflow declarations.
 - `packages/mcp-server`: stdio/HTTP MCP server and configured tool runtime.
 - `packages/schema-inspector`: Postgres/MySQL metadata inspection and config generation.
 - `packages/proposal-store`: local SQLite evidence/proposal/replay store.

package/docs/capability-authoring.md

@@ -1,8 +1,107 @@
 # Capability Authoring
 
-Use `synapsor.runner.json` to define the database actions an MCP client can see.
-The model sees semantic capabilities such as `billing.inspect_invoice`, not raw
-SQL, table names, write credentials, approval tools, or commit tools.
+For new work, author portable contracts first. The contract is the reviewable
+source of truth for trusted context, resources, capabilities, evidence,
+proposal shape, and writeback intent.
+
+```text
+contract.synapsor -> synapsor.contract.json -> synapsor.runner.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
+names, write credentials, approval tools, or commit tools.
+
+## Contract/DSL Path
+
+Write a small DSL contract:
+
+```sql
+CREATE AGENT CONTEXT local_operator
+  BIND tenant_id FROM ENVIRONMENT SYNAPSOR_TENANT_ID REQUIRED
+  BIND principal FROM ENVIRONMENT SYNAPSOR_PRINCIPAL REQUIRED
+  TENANT BINDING tenant_id
+  PRINCIPAL BINDING principal
+END
+
+CREATE CAPABILITY billing.inspect_invoice
+  USING CONTEXT local_operator
+  SOURCE local_postgres
+  ON public.invoices
+  PRIMARY KEY id
+  TENANT KEY tenant_id
+  CONFLICT GUARD updated_at
+  LOOKUP invoice_id BY id
+  ARG invoice_id STRING REQUIRED MAX 128
+  ALLOW READ id, tenant_id, status, late_fee_cents, updated_at
+  REQUIRE EVIDENCE
+  MAX ROWS 1
+END
+
+CREATE CAPABILITY billing.propose_late_fee_waiver
+  USING CONTEXT local_operator
+  SOURCE local_postgres
+  ON public.invoices
+  PRIMARY KEY id
+  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
+  ALLOW READ id, tenant_id, status, late_fee_cents, waiver_reason, updated_at
+  REQUIRE EVIDENCE
+  MAX ROWS 1
+  PROPOSE ACTION waive_late_fee
+  ALLOW WRITE late_fee_cents, waiver_reason
+  PATCH late_fee_cents = 0
+  PATCH waiver_reason = ARG reason
+  APPROVAL ROLE billing_lead
+  WRITEBACK DIRECT SQL
+END
+```
+
+Compile and validate:
+
+```bash
+synapsor-runner dsl compile ./contract.synapsor --out ./synapsor.contract.json
+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
+```
+
+Reference the generated contract from local runner wiring:
+
+```json
+{
+  "version": 1,
+  "mode": "review",
+  "contracts": ["./synapsor.contract.json"],
+  "storage": { "sqlite_path": "./.synapsor/local.db" },
+  "sources": {
+    "app_postgres": {
+      "engine": "postgres",
+      "read_url_env": "DATABASE_URL",
+      "write_url_env": "SYNAPSOR_DATABASE_WRITE_URL"
+    }
+  }
+}
+```
+
+Then preview or serve the MCP tools:
+
+```bash
+synapsor-runner tools preview --config ./synapsor.runner.json --store ./.synapsor/local.db
+synapsor-runner mcp serve --config ./synapsor.runner.json --store ./.synapsor/local.db
+```
+
+## Direct Runner Config Path
+
+Directly embedding capabilities in `synapsor.runner.json` remains supported for
+local experiments, generated configs, migration, and compatibility with earlier
+Runner versions. Prefer contracts when you want definitions that can be
+validated, bundled, reviewed in Git, dry-run pushed to Cloud, or shared with
+Cloud/C++ import/export fixtures.
 
 For editor validation, use the JSON Schema:
 
@@ -10,7 +109,7 @@ For editor validation, use the JSON Schema:
 schemas/synapsor.runner.schema.json
 ```
 
-## Minimal Shape
+## Minimal Runner Config Shape
 
 ```json
 {

package/docs/release-notes.md

@@ -10,6 +10,24 @@ 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.
 
+## 0.1.5
+
+### Contract Authoring Front Door
+
+- Introduces `@synapsor/spec` and `@synapsor/dsl` in the main Runner README so
+  developers can find the canonical contract and SQL-like authoring layers from
+  the repo and npm package front door.
+- Adds a copy-pasteable `CREATE AGENT CONTEXT` / `CREATE CAPABILITY` authoring
+  flow that compiles to `synapsor.contract.json`, validates, bundles, dry-run
+  pushes to Cloud, and serves through Runner local wiring.
+- Refreshes capability authoring docs to lead with the contract/DSL path while
+  preserving direct `synapsor.runner.json` embedded capability authoring for
+  local experiments and compatibility.
+- Clarifies that workflow declarations are supported in contracts/DSL, while
+  Runner 0.1 does not execute full Synapsor Cloud workflow DAGs, auto-merge,
+  settlement policies, or native branching.
+- Updates the repository map to include `packages/spec` and `packages/dsl`.
+
 ## 0.1.4
 
 ### Public Repository Metadata

package/package.json

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