@synapsor/runner 1.5.0 → 1.5.3

package/CHANGELOG.md

@@ -1,6 +1,96 @@
 # Changelog
 
-## 1.5.0 (prepared, not published)
+## 1.5.3 (prepared, not published)
+
+### Intent to Safe Action
+
+- Adds one code-first Safe Action Composer from a reviewed read boundary to a
+  restricted TypeScript draft, canonical contract, plain-language explanation,
+  and deterministic allow/deny/effect tests. Runner statically parses the file
+  and never imports or executes adopter code while deciding authority.
+- Keeps every generated action disabled until a human reviews a real staging
+  Data PR in the secured Workbench and explicitly activates the complete
+  digest. Editing, validating, or watching a draft cannot change active MCP
+  tools; proposals remain pinned to their active contract digest.
+- Adds current Cursor project/plugin packaging, `/synapsor-protect`, live Safe
+  Action diagnostics, owned install/uninstall, and an honest host matrix.
+  Activation, approval, apply, credentials, and trusted identity stay outside
+  the model-facing surface.
+- Extends MCP audit with evidence-labeled authority maps, explicitly consented
+  selected-server bypass checks, text/JSON/Markdown/SARIF output, fixtures, and
+  a non-mutating GitHub Actions workflow.
+- Adds a checked-in Safe Action CI workflow plus verified proposal-only recipes
+  for Claude Code, Codex, VS Code, OpenAI Agents, LangChain/LangGraph, Google
+  ADK, LlamaIndex, and generic MCP clients.
+- Reframes the README and website around one existing-application Data PR,
+  publishes an honest alternatives guide, and adds a deterministic 36-second
+  support-plan-credit cut backed by real PostgreSQL proposal, receipt, retry,
+  and stale-conflict evidence.
+- Prepares only `@synapsor/runner@1.5.3`; `@synapsor/spec@1.4.2`,
+  `@synapsor/dsl@1.4.3`, and the Cloud CLI remain unchanged.
+
+## 1.5.2 (prepared, not published)
+
+### First safe action in an existing application
+
+- Establishes one canonical path from an existing application and staging
+  Postgres/MySQL database to a reviewed semantic action, scoped evidence, exact
+  proposal/Data PR, external human review, guarded apply, receipt, and replay.
+  Own-data failures stop honestly and never fall back to synthetic data.
+- Generates a canonical contract and local Runner wiring from read-only schema
+  inspection while detecting Prisma, Drizzle, OpenAPI, known database
+  environment names, and existing Synapsor files without executing adopter
+  code. The happy path requires no hand-written JSON or DSL.
+- Adds a focused localhost workbench for Project, Data source, Trust scope,
+  Action, Agent, Test, and Review. Configuration validation alone no longer
+  marks Test complete; a scoped read must create query-audit evidence first.
+- Adds safe project-scoped Cursor install, status, and uninstall with preview,
+  merge, backup, ownership/integrity checks, exact-version launch, and
+  preservation of unrelated MCP entries. Approval, apply, revert, credentials,
+  and trusted identity remain outside the model-facing MCP surface.
+- Adds local-only activation reports for proof, own-data onboarding, Cursor,
+  first read, and first proposal. Product timing explicitly excludes initial
+  package download; separately reported cold `npx` timing is environment-
+  specific. No activation telemetry or business identifiers are transmitted.
+- Adds optional `@synapsor/runner/authoring` and
+  `@synapsor/runner/shadow` exports. TypeScript authoring emits the same
+  canonical public contract, while shadow progression and provider-neutral
+  effect regression remain non-activating and label deterministic versus
+  external-model evidence.
+- Connects MCP audit candidates directly to the secured workbench and keeps
+  audit prominent in the README and docs. Adds an explicit host-compatibility
+  matrix and a packaged support/billing first-action reference workflow.
+- Corrects the supported runtime floor to Node 22.13.0, where `node:sqlite` is
+  available without an experimental flag, and fails earlier runtimes before
+  loading the Runner bundle.
+- Prepares only `@synapsor/runner@1.5.2`; `@synapsor/spec@1.4.2`,
+  `@synapsor/dsl@1.4.3`, and the Cloud CLI remain unchanged.
+
+## 1.5.1 (prepared, not published)
+
+### Safe ownership for disposable try state
+
+- Stops `try` from recursively deleting a caller-provided `--state-dir`.
+  Custom paths are now unowned containers; Runner writes into a marked managed
+  child and removes only its known direct state files.
+- Rejects filesystem roots, home/cwd/repository paths and their ancestors,
+  parent traversal, symlinked path components, unmarked lookalike directories,
+  and managed files replaced by links. Unrelated caller files are preserved.
+- Adds an atomic per-state lease. Concurrent runs fail clearly, while a valid
+  lease left by a dead process can recover without broad cleanup.
+- Keeps `demo inspect --state-dir` aligned with the managed-child layout and
+  safely adopts only the known legacy default `.synapsor/try` file set.
+- Hardens explicit `--force` replacement for generated schema and MCP-audit
+  candidate directories against protected paths, symlinked ancestors, and
+  linked or invalid ownership markers.
+- Consistently identifies the embedded `try` source as synthetic.
+- Updates the packaged YAML parser to `2.8.3`, which includes the upstream
+  deeply nested collection denial-of-service fix.
+- Corrects the repository's stale publication wording for the live `1.5.0`
+  release. Only `@synapsor/runner` is staged at `1.5.1`; Spec, DSL, and Cloud
+  CLI versions remain unchanged.
+
+## 1.5.0 (2026-07-20)
 
 ### Complete guarded-action developer proof
 
@@ -31,9 +121,8 @@
 - Rewrites the README around the complete `try --prove` outcome, keeps MCP
   audit immediately second, names each isolation boundary precisely, and
   reconciles release documentation with the live npm registry.
-- Stages only `@synapsor/runner@1.5.0`; `@synapsor/spec@1.4.2`,
+- Published only `@synapsor/runner@1.5.0`; `@synapsor/spec@1.4.2`,
   `@synapsor/dsl@1.4.3`, and `@synapsor/cli@0.1.0-beta.1` remain unchanged.
-  Nothing is published by this change.
 
 ## 1.4.123 (2026-07-17)
 

package/README.md

@@ -4,23 +4,27 @@
 [![license: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
 [![ci](https://github.com/Synapsor/Synapsor-Runner/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Synapsor/Synapsor-Runner/actions/workflows/ci.yml?query=branch%3Amain)
 
-**Approve the exact business effect, not an opaque tool call.**
+**Let AI agents change real application data without giving the model SQL.**
 
-Synapsor Runner is an open-source MCP runtime for Postgres and MySQL. It
-gives agents reviewed business actions instead of `execute_sql`, saves risky
-changes as proposals, and keeps database credentials, approval, and writeback
-outside the model-facing surface.
+**MCP connects the agent. Synapsor controls the commit.**
 
-## Prove It In 60 Seconds
+Synapsor Runner is an open-source MCP runtime for Postgres and MySQL. It gives
+agents reviewed business actions, records proposed changes as exact Data PRs,
+and keeps credentials, activation, approval, and commit authority outside the
+model-facing surface.
 
-First, prove the boundary without a database, Docker, config, MCP client, LLM,
-or account:
+## Prove The Boundary In Four Seconds
+
+No database, Docker, config, MCP client, LLM, or account is required:
 
 ```bash
 npx -y @synapsor/runner try --prove
 ```
 
-The embedded source requests a $55 waiver and shows:
+The four-second product measurement begins after package resolution. A cold
+`npx` download is recorded separately because registry and network time vary.
+
+The embedded synthetic source requests a $55 waiver and proves:
 
 ```text
 Proposed effect: late_fee_cents: 5500 -> 0
@@ -31,10 +35,64 @@ Stale apply refused: yes
 ```
 
 Review happens outside the model-facing tools. The command stores inspectable
-state under `./.synapsor/try/` and does not test your database connection.
-`demo --quick` remains a noninteractive compatibility alias.
+state under `./.synapsor/try/`; it teaches the boundary and does not claim to
+test your database connection. `demo --quick` remains a noninteractive compatibility alias.
+
+## Protect One Action In Your Application
+
+Start with a staging database and a read-only credential. Runner inspects
+metadata, creates one reviewed read boundary, and opens the secured localhost
+Workbench:
+
+```bash
+npm install -g @synapsor/runner
+export DATABASE_URL="postgresql://runner_reader:REPLACE_ME@db.example.com:5432/app?sslmode=require"
+synapsor-runner start --from-env DATABASE_URL --schema public
+```
 
-Next, audit a typical raw-SQL MCP server:
+Describe one business action. This creates an inert TypeScript draft; it does
+not add a tool or change the active contract:
+
+```bash
+synapsor-runner start \
+  --action plan_credit \
+  --description "Propose one reviewed customer plan credit" \
+  --based-on support.inspect_customer
+```
+
+Add the reviewed tools to the current Cursor project:
+
+```bash
+synapsor-runner mcp install cursor --project \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+```
+
+In Cursor, use the Workbench's exact prompt. The checked-in project
+instructions require the coding agent to draft and validate the action while
+leaving effect review and activation to you. Once activated, a request such as
+"give CUS-3001 a $25 plan credit" can only create a semantic proposal:
+
+```text
+Data PR  wrp_...
+Action   support.propose_plan_credit on CUS-3001
+Effect   plan_credit_cents: 0 -> 2500
+Source unchanged before approval: Yes
+```
+
+Review the exact effect in the secured Workbench, select **Approve outside
+MCP**, then run the displayed guarded apply command from a trusted terminal.
+The agent has no approval or commit tool. Runner rechecks scope, policy, row
+version, bounds, and idempotency before returning a receipt; a retry cannot
+duplicate the mutation and a stale proposal conflicts.
+
+See the [own-database guide](docs/getting-started-own-database.md) for the full
+staging path and [Cursor plugin guide](docs/cursor-plugin.md) for
+`/synapsor-protect` and the plugin boundary.
+
+## Audit An Existing MCP Server
+
+Audit a typical raw-SQL MCP server without launching or calling one:
 
 ```bash
 npx -y @synapsor/runner audit --example dangerous-db-mcp
@@ -49,9 +107,10 @@ npx -y @synapsor/runner audit ./tools-list.json
 It flags raw SQL, arbitrary identifiers, model-controlled authority,
 model-facing approval/writeback, and missing conflict or idempotency signals.
 It does not call business tools. See [MCP Database Risk
-Review](docs/mcp-audit.md) for supported workflows and limits.
-
-Then [connect a staging database](#connect-a-staging-database).
+Review](docs/mcp-audit.md) for local manifests, selected-server checks, CI,
+SARIF, evidence labels, and limits. You may not need Runner: use the
+[alternatives guide](docs/alternatives.md) to compare direct read-only access,
+hand-built tools, and this reviewed boundary.
 
 ## Safety Model
 
@@ -104,73 +163,16 @@ credentials. See [Database scope] and the
 
 ## Connect A Staging Database
 
-Start with staging and a read-only credential. Keep database permissions,
-views, and RLS.
+The setup above stores environment-variable names, not connection strings, and
+never falls back to synthetic data if inspection fails. Keep staging, database
+permissions, restricted views, and RLS underneath Runner. Bind trusted tenant
+and principal values in the launching process, then review the exact field and
+tool surface before connecting Cursor.
 
-```bash
-npm install -g @synapsor/runner
-export DATABASE_URL="postgresql://runner_reader:REPLACE_ME@db.example.com:5432/app?sslmode=require"
-synapsor-runner start --from-env DATABASE_URL --schema public
-```
-
-The wizard inspects metadata, generates reviewed capabilities, previews MCP
-tools, and prints smoke/serve commands. It stores environment-variable names,
-not connection strings.
-
-[Generate disabled review candidates from Prisma, Drizzle, or
-OpenAPI.](docs/schema-api-candidates.md)
-
-The generated capability is a tenant-scoped read with an explicit column
-allowlist and required evidence. See the [own-database
-guide](docs/getting-started-own-database.md) for the full configuration.
-
-```json
-{
-  "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
-}
-```
-
-Set the trusted values in the process that launches Runner, then validate and
-preview the exact model-facing boundary before connecting an MCP client:
-
-```bash
-export SYNAPSOR_TENANT_ID="acme"
-export SYNAPSOR_PRINCIPAL="local-developer"
-synapsor-runner config validate --config ./synapsor.runner.json
-synapsor-runner tools preview --config ./synapsor.runner.json --store ./.synapsor/local.db
-synapsor-runner mcp serve --config ./synapsor.runner.json --store ./.synapsor/local.db
-```
-
-For proposal capabilities and writes, follow the
-[complete own-database guide](docs/getting-started-own-database.md). Reviewed
-single-row INSERT, UPDATE, and DELETE can use Runner's guarded direct
-writeback. Runner also supports tightly [bounded set
-writes](docs/bounded-set-writeback.md): fixed-predicate UPDATE/DELETE and
-exact-review batch INSERT, with human approval, a hard 100-row ceiling, atomic
-apply, and exact receipts. Free-form predicates, unbounded or cross-table work,
-and external effects go through an [app-owned
-executor](docs/writeback-executors.md) after approval.
-
-Direct writes can use [reviewed
-compensation](docs/reversible-change-sets.md). Receipts capture a
-bounded inverse; `synapsor-runner revert <proposal_id>` creates a separately
-approved proposal. This is not rollback, time travel, or app-owned
-compensation.
+The [complete own-database guide](docs/getting-started-own-database.md) covers
+validation, scoped reads, disabled Prisma/Drizzle/OpenAPI candidates, guarded
+single-row writes, and app-owned executors. Use the [host compatibility
+matrix](docs/host-compatibility.md) for accurately tested client behavior.
 
 ## Review And Prove Your Contract
 
@@ -202,18 +204,11 @@ trust boundaries, covered threats, non-goals, and required operator controls.
 - MCP proposal, evidence, and replay handles are references rather than bearer
   authority: resource reads re-check the owning tenant and principal against
   the current trusted session.
-- Same-tenant owner/assignee isolation uses a reviewed
-  [`PRINCIPAL SCOPE KEY`](docs/capability-authoring.md#same-tenant-principal-row-scope)
-  composed with mandatory tenant scope; `test:principal-scope` proves generic
-  cross-principal denial and evidence-handle isolation on Postgres and MySQL.
-- `test:live-apply`, `test:guarded-crud`, `test:bounded-set`, and
-  `test:reversible` run disposable PostgreSQL/MySQL scenarios. They prove no
-  pre-approval mutation, guarded single-row CRUD, idempotent retry,
-  fail-closed conflicts, bounded atomic sets, exact receipts, and reviewed
-  compensation.
-- The C++/Cloud round-trip verifier exports normalized contracts, validates
-  them with `@synapsor/spec`, and loads them in Runner. The shared contract and
-  verification commands are documented in [Conformance](docs/conformance.md).
+- `test:principal-scope`, `test:live-apply`, `test:guarded-crud`,
+  `test:bounded-set`, and `test:reversible` prove cross-principal denial,
+  no pre-approval mutation, guarded writes, idempotent retry, conflicts,
+  bounded atomic sets, receipts, and reviewed compensation on disposable
+  PostgreSQL/MySQL fixtures.
 
 Runner is a narrow agent/database safety boundary, not a replacement for
 least-privilege database access, host security, or application authorization.
@@ -224,12 +219,9 @@ See [Security Boundary](docs/security-boundary.md) and
 
 ## Operate The Approval Loop
 
-Policies combine per-proposal and daily ceilings; exceeding one routes to human
-review. Operators get batch apply, metrics, structured logs, and optional
-signed roles. Local SQLite is the default; bounded fleets can use verified HTTP
-claims, asymmetric JWT sessions, and a shared Postgres `runtime_store`.
-`smoke call` follows that store and never falls back to SQLite. Use `/healthz`
-for liveness and `/readyz` for dependency readiness. See
+Policies can combine per-proposal and aggregate ceilings; exceeding one routes
+to human review. Local SQLite is the default, while bounded fleets can use
+verified HTTP claims and a shared Postgres runtime store. See
 [Production](docs/production.md), [Runner Config](docs/runner-config-reference.md),
 and [Small Runner Fleets](docs/running-a-runner-fleet.md).
 
@@ -242,16 +234,11 @@ and [Small Runner Fleets](docs/running-a-runner-fleet.md).
 | `@synapsor/dsl` | SQL-like authoring that compiles contexts, capabilities, and workflow declarations into canonical contract JSON. |
 | `@synapsor/cli` | Synapsor Cloud administration, contract governance, human review, Runner connections, and shared audit records. |
 
-Runner executes locally. The spec is shared by Runner and Cloud/C++; the DSL
-is its reviewable source format. Start with [Capability
-Authoring](docs/capability-authoring.md). Use `.synapsor.sql` for generic SQL
-highlighting; legacy `.synapsor` files produce the same contract JSON.
-
-Use the [DSL Reference](docs/dsl-reference.md) for exact authoring grammar and
-the [Runner Config Reference](docs/runner-config-reference.md) for every wiring
-key, default, and path-resolution rule. The
-[Store Lifecycle guide](docs/store-lifecycle.md) explains ledger sensitivity,
-owner-only permissions, inspection commands, and retention.
+Runner, JSON, `.synapsor.sql`, and the optional TypeScript
+`@synapsor/runner/authoring` frontend all use the same canonical spec. The
+`@synapsor/runner/shadow` helper records app-owned outcomes without granting
+write authority. Start with [Capability Authoring](docs/capability-authoring.md)
+and the [Runner Config Reference](docs/runner-config-reference.md).
 
 ## OSS And Cloud
 

package/dist/authoring.d.ts

@@ -0,0 +1,23 @@
+import { type AgentContextSpec, type CapabilitySpec, type PolicySpec, type ResourceSpec, type SynapsorContract, type WorkflowSpec } from "@synapsor/spec";
+export type SynapsorContractDefinition = Omit<SynapsorContract, "spec_version" | "kind">;
+/** Preserve editor inference for a canonical resource definition. */
+export declare function defineResource<const T extends ResourceSpec>(resource: T): T;
+/** Preserve editor inference for trusted context bindings resolved outside model input. */
+export declare function defineAgentContext<const T extends AgentContextSpec>(context: T): T;
+/** Preserve editor inference for a canonical read, aggregate, proposal, or external capability. */
+export declare function defineCapability<const T extends CapabilitySpec>(capability: T): T;
+/** Preserve editor inference for a canonical workflow declaration. */
+export declare function defineWorkflow<const T extends WorkflowSpec>(workflow: T): T;
+/** Preserve editor inference for a canonical policy declaration. */
+export declare function definePolicy<const T extends PolicySpec>(policy: T): T;
+/**
+ * Build and validate the same language-neutral contract consumed by the JSON,
+ * SQL-like DSL, local Runner, and Cloud registry paths.
+ */
+export declare function defineContract<const T extends SynapsorContractDefinition>(definition: T): SynapsorContract & T;
+/** Validate and normalize a code-first definition into canonical contract JSON shape. */
+export declare function compileContract(definition: SynapsorContractDefinition | SynapsorContract): SynapsorContract;
+/** Serialize normalized canonical JSON for review, version control, or Runner loading. */
+export declare function contractJson(definition: SynapsorContractDefinition | SynapsorContract, indentation?: number): string;
+export type { AgentContextSpec, CapabilitySpec, PolicySpec, ResourceSpec, SynapsorContract, WorkflowSpec, } from "@synapsor/spec";
+//# sourceMappingURL=authoring.d.ts.map

package/dist/authoring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authoring.d.ts","sourceRoot":"","sources":["../src/authoring.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,YAAY,EAClB,MAAM,gBAAgB,CAAC;AAExB,MAAM,MAAM,0BAA0B,GAAG,IAAI,CAAC,gBAAgB,EAAE,cAAc,GAAG,MAAM,CAAC,CAAC;AAEzF,qEAAqE;AACrE,wBAAgB,cAAc,CAAC,KAAK,CAAC,CAAC,SAAS,YAAY,EAAE,QAAQ,EAAE,CAAC,GAAG,CAAC,CAE3E;AAED,2FAA2F;AAC3F,wBAAgB,kBAAkB,CAAC,KAAK,CAAC,CAAC,SAAS,gBAAgB,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,CAElF;AAED,mGAAmG;AACnG,wBAAgB,gBAAgB,CAAC,KAAK,CAAC,CAAC,SAAS,cAAc,EAAE,UAAU,EAAE,CAAC,GAAG,CAAC,CAEjF;AAED,sEAAsE;AACtE,wBAAgB,cAAc,CAAC,KAAK,CAAC,CAAC,SAAS,YAAY,EAAE,QAAQ,EAAE,CAAC,GAAG,CAAC,CAE3E;AAED,oEAAoE;AACpE,wBAAgB,YAAY,CAAC,KAAK,CAAC,CAAC,SAAS,UAAU,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAErE;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,CAAC,CAAC,SAAS,0BAA0B,EACvE,UAAU,EAAE,CAAC,GACZ,gBAAgB,GAAG,CAAC,CAQtB;AAED,yFAAyF;AACzF,wBAAgB,eAAe,CAAC,UAAU,EAAE,0BAA0B,GAAG,gBAAgB,GAAG,gBAAgB,CAM3G;AAED,0FAA0F;AAC1F,wBAAgB,YAAY,CAC1B,UAAU,EAAE,0BAA0B,GAAG,gBAAgB,EACzD,WAAW,SAAI,GACd,MAAM,CAKR;AAED,YAAY,EACV,gBAAgB,EAChB,cAAc,EACd,UAAU,EACV,YAAY,EACZ,gBAAgB,EAChB,YAAY,GACb,MAAM,gBAAgB,CAAC"}