@synapsor/runner 1.4.123 → 1.5.3

package/CHANGELOG.md

@@ -1,6 +1,130 @@
 # Changelog
 
-## 1.4.123 (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
+
+- Adds `synapsor-runner try` as a no-account, no-database, no-Docker proof of
+  scoped evidence, an exact business-data proposal, external approval, guarded
+  commit, restart-safe retry, stale-state refusal, receipt, and non-mutating
+  replay. `try --prove` also verifies changed-intent collision rejection.
+- Adds explicit `application_scope`, `postgres_rls`, and `tenant_bound`
+  assurance modes. PostgreSQL hardened mode binds tenant/principal
+  transaction-locally, checks RLS and role prerequisites, and fails closed
+  rather than silently downgrading.
+- Productizes strict local shadow studies, authoritative human-outcome
+  comparison, deterministic readiness reports, and effect-level JSON/JUnit
+  regression fixtures without activating policy or mutating source data.
+- Adds a standard display-only MCP App proposal resource with exact effect,
+  evidence, scope, policy, and review-state presentation. Approval and apply
+  remain absent from MCP, with terminal and standalone local-UI fallbacks.
+- Extends static MCP risk audit into disabled review candidates, and adds
+  review-only Prisma, Drizzle, and OpenAPI generators that emit canonical
+  contracts without importing or executing adopter code.
+- Promotes `examples/support-billing-agent` as a disposable PostgreSQL/RLS
+  proof covering tenant and principal scope, kept-out fields, exact $55
+  proposal, approval/apply, idempotent retry, stale conflict, replay, strict
+  shadow, human comparison, and effect regression.
+- Keeps app-owned handler writers least-privileged when their receipt table is
+  pre-provisioned: the helper checks for the table before attempting DDL, and
+  the live source and packed examples verify transactional apply and retry.
+- 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.
+- 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.
+
+## 1.4.123 (2026-07-17)
 
 ### Advisory capability-surface fitness lint
 
@@ -13,10 +137,10 @@
 - Adds stable structured details and surface metrics to JSON/SARIF output, plus
   a concise text summary. No database connection, environment value, source
   row, or probabilistic classifier is involved.
-- Stages only `@synapsor/runner@1.4.123`; `@synapsor/spec@1.4.2`,
+- Published only `@synapsor/runner@1.4.123`; `@synapsor/spec@1.4.2`,
   `@synapsor/dsl@1.4.3`, and `@synapsor/cli@0.1.0-beta.1` are unchanged.
 
-## 1.4.122 (2026-07-16)
+## 1.4.122 (2026-07-17)
 
 ### Trusted principal row scope and Cloud-linked governance
 
@@ -42,7 +166,7 @@
 - Published `@synapsor/spec@1.4.2`, `@synapsor/dsl@1.4.3`, and
   `@synapsor/runner@1.4.122`.
 
-## 1.4.121 (prepared, not published)
+## 1.4.121 (2026-07-15)
 
 ### Contract trust surface and bounded-set parser correctness
 
@@ -78,10 +202,10 @@
 - Proves additive Spec/DSL/Runner/C++ aggregate and enum parity, shared Postgres
   recommendation durability, and transient PostgreSQL/MySQL timeout
   classification.
-- Stages `@synapsor/spec@1.4.1`, `@synapsor/dsl@1.4.2`, and
-  `@synapsor/runner@1.4.121`. Nothing is published by this change.
+- Published `@synapsor/spec@1.4.1`, `@synapsor/dsl@1.4.2`, and
+  `@synapsor/runner@1.4.121`.
 
-## 1.4.12 (prepared, not published)
+## 1.4.12 (2026-07-14)
 
 ### Runtime-store smoke-call consistency
 
@@ -97,10 +221,10 @@
 - Adds focused no-fallback coverage and a disposable two-process fleet proof
   covering ownership, approval/apply, one source receipt, replay, and safe
   ledger unavailability.
-- Stages only `@synapsor/runner@1.4.12`; `@synapsor/dsl` remains `1.4.1` and
-  `@synapsor/spec` remains `1.4.0`. Nothing is published by this change.
+- Published only `@synapsor/runner@1.4.12`; `@synapsor/dsl` remains `1.4.1`
+  and `@synapsor/spec` remains `1.4.0`.
 
-## 1.4.1 (prepared, not published)
+## 1.4.1 (2026-07-14)
 
 ### Canonical Bounded-Set Digest Verification
 
@@ -127,11 +251,11 @@
   structural authorization, explains where SQL authority lives, and documents
   the approval, receipt, replay, and compensation layer without claiming
   prompt-injection prevention or compliance certification.
-- Stages `@synapsor/runner@1.4.1` and `@synapsor/dsl@1.4.1`;
+- Published `@synapsor/runner@1.4.1` and `@synapsor/dsl@1.4.1`;
   `@synapsor/spec` remains `1.4.0` because the public contract schema did not
-  change. Nothing is published by this change.
+  change.
 
-## 1.4.0 (prepared, not published)
+## 1.4.0 (2026-07-14)
 
 ### Reviewed Reversible Change Sets
 
@@ -155,8 +279,8 @@
   conformance fixtures, owner-authorized resources, local UI/doctor/preview
   state, bounded metrics, crash-reconciliation tests, and the disposable
   `corepack pnpm test:reversible` gate.
-- Stages `@synapsor/spec@1.4.0`, `@synapsor/dsl@1.4.0`, and
-  `@synapsor/runner@1.4.0`. No npm package is published by this change.
+- Published `@synapsor/spec@1.4.0`, `@synapsor/dsl@1.4.0`, and
+  `@synapsor/runner@1.4.0`.
 
 ## 1.3.0 (prepared, not published)
 
@@ -233,7 +357,8 @@
   metadata so a leaked handle does not become bearer authority.
 - Adds shared-store and Streamable HTTP regressions proving owner access still
   works while cross-session resource reads fail closed.
-- Stages only `@synapsor/runner@1.1.1`; canonical Spec and DSL remain `1.1.0`.
+- Published only `@synapsor/runner@1.1.1`; canonical Spec and DSL remain
+  `1.1.0`.
 
 ## 1.1.0
 
@@ -257,8 +382,8 @@
 - Adds verified dead-letter list/show/requeue/discard, shared-ledger
   backup/digest/restore, archive-before-retention, and a repeatable two-Runner
   kill/recovery test over synthetic Postgres/MySQL.
-- Stages `@synapsor/spec@1.1.0`, `@synapsor/dsl@1.1.0`, and
-  `@synapsor/runner@1.1.0`. Nothing is published by this change.
+- Published `@synapsor/spec@1.1.0`, `@synapsor/dsl@1.1.0`, and
+  `@synapsor/runner@1.1.0`.
 
 ## 1.0.0
 
@@ -280,7 +405,7 @@
   and Streamable HTTP mTLS.
 - Declares the first semver contract for the documented CLI, schema, contract,
   MCP result, writeback, approval, metrics, and replay surfaces.
-- Stages `@synapsor/spec@1.0.0`, `@synapsor/dsl@1.0.0`, and
+- Published `@synapsor/spec@1.0.0`, `@synapsor/dsl@1.0.0`, and
   `@synapsor/runner@1.0.0`.
 
 ## 0.1.16

package/README.md

@@ -4,21 +4,95 @@
 [![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)
 
-Stop giving AI agents `execute_sql`. Give them reviewed business actions.
+**Let AI agents change real application data without giving the model SQL.**
 
-Synapsor Runner is an open-source, local-first MCP runtime for Postgres and
-MySQL. It exposes semantic tools such as `billing.inspect_invoice` and
-`billing.propose_late_fee_waiver`, saves risky changes as proposals, and keeps
-database credentials, approval, and writeback outside the model-facing tool
-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.
 
-Path: **audit** MCP risk, **demo** the boundary, then **connect** staging. The
-first two commands touch only a local fixture.
+## Prove The Boundary In Four Seconds
 
-First, inspect the risk in a typical raw-SQL database MCP server. This works
-even if you never adopt Runner:
+No database, Docker, config, MCP client, LLM, or account is required:
+
+```bash
+npx -y @synapsor/runner try --prove
+```
+
+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
+Source changed before approval: No
+Guarded commit: 1 row, receipt recorded
+Restart-safe retry: yes; duplicate mutations: 0
+Stale apply refused: yes
+```
+
+Review happens outside the model-facing tools. The command stores inspectable
+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
+```
+
+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
@@ -33,17 +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 see the proposal, approval boundary, evidence, and replay loop. It needs no
-database, Docker, config file, MCP client, or Synapsor account:
-
-```bash
-npx -y @synapsor/runner demo --quick
-```
-
-The quick demo creates a fixture ledger at `./.synapsor/quick-demo.db`. It
-teaches the boundary; it does not claim to test your database connection.
+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
 
@@ -75,100 +142,43 @@ approval, apply, or revert tools. A human or trusted operator approves outside
 MCP, then Runner performs a guarded write or routes the proposal to an
 app-owned executor.
 
-Contracts constrain tools, trusted context, visible and writable columns,
-bounds, transitions, and approvals. Proposals separate model intent from commit
-authority; evidence, query audit, receipts, and replay preserve the reviewed
-lifecycle. Runner does not make raw SQL tools, hosts, or
-prompt-injection-prone clients safe.
+Contracts fix trusted context, fields, bounds, transitions, and approvals;
+evidence, query audit, receipts, and replay preserve the lifecycle. Runner does
+not make raw SQL or prompt-injection-prone clients safe.
 
-## Why Not Just Use A Prompt And App Code?
+## Choose An Isolation Mode
 
-Prompts are not an authorization boundary. First ask who produces the SQL:
-
-- **The model produces SQL:** validation must understand arbitrary queries,
-  scope, and side effects. That is `execute_sql` behind a parser.
-- **Trusted app code produces fixed, parameterized SQL:** good. You have built
-  a semantic tool, and that may be enough for a small read-only application.
+| Mode | Boundary |
+| --- | --- |
+| Embedded `try` | Synthetic source; proves the lifecycle, not your database. |
+| `application_scope` | Shared role plus Runner predicates. A Runner bug or compromised process can cross scope; retain database controls. |
+| `postgres_rls` | PostgreSQL also checks transaction-bound tenant/principal scope. Arbitrary trusted-context or credential control remains outside this guarantee. |
+| `tenant_bound` | Authenticated context selects a restricted per-tenant credential or process. |
 
-Runner adds one reviewed contract for trusted scope, field controls, evidence,
-approval outside MCP, guarded writeback, receipts, replay, and compensation.
-Use your own code when you do not need that lifecycle. See the [build-vs-adopt
-guide](docs/why-synapsor-vs-app-guardrails.md).
+Stdio commonly trusts process environment; shared HTTP must use verified signed
+claims. Model arguments, query parameters, and arbitrary tenant headers are
+never trusted. MySQL has no native RLS; use restricted views or tenant
+credentials. See [Database scope] and the
+[build-vs-adopt guide](docs/why-synapsor-vs-app-guardrails.md).
 
 ## Connect A Staging Database
 
-Start with a staging or disposable database and a read-only credential. Keep
-database permissions, restricted views, and row-level security in place.
+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 guided command inspects metadata, asks you to choose one table or view,
-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.
-
-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
 
-Before serving a contract, use `contract explain` for a reviewer-readable
-boundary, `contract lint --strict` for deterministic surface-fitness CI checks,
-and `contract test` for adopter-owned allow/deny/redaction cases. The built-in language
-server supplies diagnostics, completion, hover, and formatting for
+Before serving, use `contract explain`, `contract lint --strict`, and `contract
+test` for reviewer-readable boundaries and allow/deny/redaction cases. The
+built-in language server supplies diagnostics, completion, hover, and formatting for
 `.synapsor.sql` and legacy `.synapsor` files. See [Contract
 Review](docs/contract-review.md) and [Contract
 Testing](docs/contract-testing.md).
@@ -194,32 +204,24 @@ 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.
 See [Security Boundary](docs/security-boundary.md) and
 [Current Limitations](docs/limitations.md).
 
+[Database scope]: docs/database-enforced-scope.md
+
 ## 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).
 
@@ -232,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
 
@@ -264,7 +261,7 @@ guide](https://github.com/Synapsor/Synapsor-Runner/blob/main/docs/cloud-cli.md).
 ## Next Steps
 
 - Follow the [step-by-step Synapsor Tutorial](https://github.com/sandeshtiwari/Synapsor-Tutorial).
-- Run the [`support-plan-credit` flagship example](examples/support-plan-credit).
+- Run the [`support-billing-agent` flagship example](examples/support-billing-agent).
 - Connect [Claude, Cursor, OpenAI Agents SDK, or another MCP client](docs/mcp-clients.md).
 - Author and [push a validated contract to Cloud](docs/cloud-push.md).
 - Browse the [task-first documentation index](docs/README.md).

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"}