@synapsor/runner 1.5.0 → 1.5.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (83) hide show
  1. package/CHANGELOG.md +134 -3
  2. package/README.md +108 -113
  3. package/dist/authoring.d.ts +23 -0
  4. package/dist/authoring.d.ts.map +1 -0
  5. package/dist/authoring.mjs +1318 -0
  6. package/dist/cli.d.ts.map +1 -1
  7. package/dist/cli.js +4 -5
  8. package/dist/local-ui.d.ts +14 -0
  9. package/dist/local-ui.d.ts.map +1 -1
  10. package/dist/runner.mjs +12334 -5256
  11. package/dist/runtime.mjs +817 -149
  12. package/dist/shadow.d.ts +36 -0
  13. package/dist/shadow.d.ts.map +1 -0
  14. package/dist/shadow.mjs +5362 -0
  15. package/docs/README.md +25 -2
  16. package/docs/alternatives.md +122 -0
  17. package/docs/capability-authoring.md +49 -1
  18. package/docs/client-recipes.md +218 -0
  19. package/docs/cloud-mode.md +18 -0
  20. package/docs/contract-testing.md +9 -7
  21. package/docs/cursor-plugin.md +78 -0
  22. package/docs/database-enforced-scope.md +8 -0
  23. package/docs/dsl-reference.md +45 -4
  24. package/docs/effect-regression.md +39 -2
  25. package/docs/fresh-developer-usability.md +110 -0
  26. package/docs/getting-started-own-database.md +102 -5
  27. package/docs/guarded-crud-writeback.md +10 -1
  28. package/docs/host-compatibility.md +59 -0
  29. package/docs/http-mcp.md +222 -207
  30. package/docs/limitations.md +9 -2
  31. package/docs/local-mode.md +11 -7
  32. package/docs/mcp-audit.md +166 -2
  33. package/docs/mcp-client-setup.md +28 -11
  34. package/docs/mcp-clients.md +43 -8
  35. package/docs/openai-agents-sdk.md +16 -2
  36. package/docs/oss-vs-cloud.md +3 -0
  37. package/docs/production.md +72 -7
  38. package/docs/release-notes.md +131 -4
  39. package/docs/runner-bundles.md +7 -2
  40. package/docs/runner-config-reference.md +96 -6
  41. package/docs/running-a-runner-fleet.md +42 -13
  42. package/docs/security-boundary.md +58 -8
  43. package/docs/shadow-studies.md +47 -4
  44. package/docs/store-lifecycle.md +93 -5
  45. package/docs/troubleshooting-first-run.md +46 -0
  46. package/examples/openai-agents-http/README.md +10 -4
  47. package/examples/openai-agents-http/agent.py +2 -2
  48. package/examples/runner-fleet/Dockerfile +7 -2
  49. package/examples/runner-fleet/README.md +11 -7
  50. package/examples/runner-fleet/docker-compose.yml +4 -4
  51. package/examples/runner-fleet/mint-dev-token.mjs +1 -1
  52. package/examples/runner-fleet/start-tls-runner.sh +21 -0
  53. package/examples/runner-fleet/synapsor.runner.json +27 -1
  54. package/examples/support-billing-agent/README.md +18 -0
  55. package/examples/support-billing-agent/app/README.md +6 -0
  56. package/examples/support-billing-agent/app/contract.ts +28 -0
  57. package/examples/support-billing-agent/app/effect-adapter.mjs +23 -0
  58. package/examples/support-billing-agent/app/record-shadow-outcomes.mjs +44 -0
  59. package/examples/support-billing-agent/scripts/run-evaluation.sh +6 -5
  60. package/examples/support-plan-credit/README.md +54 -3
  61. package/examples/support-plan-credit/mcp-client-examples/README.md +23 -0
  62. package/examples/support-plan-credit/mcp-client-examples/claude-code.sh +34 -0
  63. package/examples/support-plan-credit/mcp-client-examples/codex.config.toml +24 -0
  64. package/examples/support-plan-credit/mcp-client-examples/generic-stdio.mjs +35 -0
  65. package/examples/support-plan-credit/mcp-client-examples/generic-streamable-http.json +4 -1
  66. package/examples/support-plan-credit/mcp-client-examples/generic-streamable-http.mjs +31 -0
  67. package/examples/support-plan-credit/mcp-client-examples/google-adk.py +40 -0
  68. package/examples/support-plan-credit/mcp-client-examples/langchain.mjs +29 -0
  69. package/examples/support-plan-credit/mcp-client-examples/llamaindex.py +36 -0
  70. package/examples/support-plan-credit/mcp-client-examples/openai-agents-stdio.ts +1 -1
  71. package/examples/support-plan-credit/mcp-client-examples/openai-agents-streamable-http.ts +5 -1
  72. package/examples/support-plan-credit/mcp-client-examples/vscode.mcp.json +20 -0
  73. package/examples/support-plan-credit/synapsor/actions/support.propose_plan_credit.contract-tests.generated.json +221 -0
  74. package/examples/support-plan-credit/synapsor/actions/support.propose_plan_credit.ts +34 -0
  75. package/examples/support-plan-credit/synapsor.contract.json +0 -3
  76. package/fixtures/mcp-audit/README.md +14 -0
  77. package/fixtures/mcp-audit/cursor-bypass-config.json +38 -0
  78. package/fixtures/mcp-audit/dangerous-tools-list.json +33 -0
  79. package/fixtures/mcp-audit/reviewed-proposal-tools-list.json +60 -0
  80. package/package.json +18 -3
  81. package/schemas/mcp-audit-report.schema.json +100 -1
  82. package/schemas/synapsor.contract-tests.schema.json +1 -1
  83. package/schemas/synapsor.runner.schema.json +80 -0
package/CHANGELOG.md CHANGED
@@ -1,6 +1,138 @@
1
1
  # Changelog
2
2
 
3
- ## 1.5.0 (prepared, not published)
3
+ ## 1.5.4 (prepared, not published)
4
+
5
+ ### Networked MCP authentication hardening
6
+
7
+ - Defines explicit local-loopback, remote single-tenant, and shared multi-tenant
8
+ HTTP security profiles while preserving zero-configuration local stdio.
9
+ - Refuses non-loopback cleartext listeners before bind unless the operator
10
+ explicitly selects a trusted TLS proxy or authenticated break-glass posture.
11
+ Runner-owned TLS and optional mTLS remain supported.
12
+ - Hardens opaque endpoint tokens with environment-only provisioning, production
13
+ entropy checks, constant-time comparison, one bounded previous-token rotation
14
+ slot, and per-session credential pinning. Opaque tokens remain service access
15
+ credentials, not tenant or user identity.
16
+ - Requires verified signed identity for shared deployments. Runner validates
17
+ algorithm, signature, issuer, audience/resource, time, scope, tenant, and
18
+ principal on every request, including requests for existing MCP sessions.
19
+ - Adds RFC 9728 protected-resource metadata and standards-correct Bearer
20
+ challenges for external authorization servers. Runner remains a protected
21
+ resource and does not issue passwords, access tokens, or refresh tokens.
22
+ - Adds exact Origin and Host policy, bounded headers/bodies/connections/sessions,
23
+ TLS preflight, bounded public-only JWKS handling, and safe overload responses.
24
+ - Expands `doctor`, help, client generators, fleet examples, and deployment docs
25
+ so operators can distinguish TLS, Bearer presentation, opaque tokens, JWTs,
26
+ MCP session IDs, trusted context, database scope, and operator authority
27
+ without printing credential values.
28
+ - Adds read-only, no-ID-first `lifecycle` inspection across local SQLite and
29
+ shared PostgreSQL runtime stores. Latest, filtered business-object lookup, and
30
+ proposal/evidence/replay/job/intent/receipt/audit handles resolve one typed,
31
+ redacted proposal-to-receipt/replay timeline without creating jobs, leases,
32
+ source calls, or Cloud synchronization.
33
+ - Makes UPDATE conflict guarding exact by default in the SQL-like DSL.
34
+ Omitting `CONFLICT GUARD <column>` now fails. The explicit legacy
35
+ `CONFLICT GUARD WEAK ROW HASH ACKNOWLEDGED` form is limited to ordinary
36
+ single-row source-DB UPDATE and warns that projection hashing can miss outside
37
+ changes.
38
+ - Preserves canonical `SESSION` for implementations with a real typed session
39
+ boundary while making Runner fail closed with
40
+ `SESSION_BINDING_UNSUPPORTED`. Runner-targeted DSL validation, contract load,
41
+ lint/explain, and runtime no longer allow an environment fallback.
42
+ - Prepares `@synapsor/runner@1.5.4` and `@synapsor/dsl@1.4.4`;
43
+ `@synapsor/spec@1.4.2` and the Cloud CLI remain unchanged.
44
+
45
+ ## 1.5.3 (published 2026-07-21)
46
+
47
+ ### Intent to Safe Action
48
+
49
+ - Adds one code-first Safe Action Composer from a reviewed read boundary to a
50
+ restricted TypeScript draft, canonical contract, plain-language explanation,
51
+ and deterministic allow/deny/effect tests. Runner statically parses the file
52
+ and never imports or executes adopter code while deciding authority.
53
+ - Keeps every generated action disabled until a human reviews a real staging
54
+ Data PR in the secured Workbench and explicitly activates the complete
55
+ digest. Editing, validating, or watching a draft cannot change active MCP
56
+ tools; proposals remain pinned to their active contract digest.
57
+ - Adds current Cursor project/plugin packaging, `/synapsor-protect`, live Safe
58
+ Action diagnostics, owned install/uninstall, and an honest host matrix.
59
+ Activation, approval, apply, credentials, and trusted identity stay outside
60
+ the model-facing surface.
61
+ - Extends MCP audit with evidence-labeled authority maps, explicitly consented
62
+ selected-server bypass checks, text/JSON/Markdown/SARIF output, fixtures, and
63
+ a non-mutating GitHub Actions workflow.
64
+ - Adds a checked-in Safe Action CI workflow plus verified proposal-only recipes
65
+ for Claude Code, Codex, VS Code, OpenAI Agents, LangChain/LangGraph, Google
66
+ ADK, LlamaIndex, and generic MCP clients.
67
+ - Reframes the README and website around one existing-application Data PR,
68
+ publishes an honest alternatives guide, and adds a deterministic 36-second
69
+ support-plan-credit cut backed by real PostgreSQL proposal, receipt, retry,
70
+ and stale-conflict evidence.
71
+ - Published only `@synapsor/runner@1.5.3`; `@synapsor/spec@1.4.2`,
72
+ `@synapsor/dsl@1.4.3`, and the Cloud CLI remain unchanged.
73
+
74
+ ## 1.5.2 (prepared, not published)
75
+
76
+ ### First safe action in an existing application
77
+
78
+ - Establishes one canonical path from an existing application and staging
79
+ Postgres/MySQL database to a reviewed semantic action, scoped evidence, exact
80
+ proposal/Data PR, external human review, guarded apply, receipt, and replay.
81
+ Own-data failures stop honestly and never fall back to synthetic data.
82
+ - Generates a canonical contract and local Runner wiring from read-only schema
83
+ inspection while detecting Prisma, Drizzle, OpenAPI, known database
84
+ environment names, and existing Synapsor files without executing adopter
85
+ code. The happy path requires no hand-written JSON or DSL.
86
+ - Adds a focused localhost workbench for Project, Data source, Trust scope,
87
+ Action, Agent, Test, and Review. Configuration validation alone no longer
88
+ marks Test complete; a scoped read must create query-audit evidence first.
89
+ - Adds safe project-scoped Cursor install, status, and uninstall with preview,
90
+ merge, backup, ownership/integrity checks, exact-version launch, and
91
+ preservation of unrelated MCP entries. Approval, apply, revert, credentials,
92
+ and trusted identity remain outside the model-facing MCP surface.
93
+ - Adds local-only activation reports for proof, own-data onboarding, Cursor,
94
+ first read, and first proposal. Product timing explicitly excludes initial
95
+ package download; separately reported cold `npx` timing is environment-
96
+ specific. No activation telemetry or business identifiers are transmitted.
97
+ - Adds optional `@synapsor/runner/authoring` and
98
+ `@synapsor/runner/shadow` exports. TypeScript authoring emits the same
99
+ canonical public contract, while shadow progression and provider-neutral
100
+ effect regression remain non-activating and label deterministic versus
101
+ external-model evidence.
102
+ - Connects MCP audit candidates directly to the secured workbench and keeps
103
+ audit prominent in the README and docs. Adds an explicit host-compatibility
104
+ matrix and a packaged support/billing first-action reference workflow.
105
+ - Corrects the supported runtime floor to Node 22.13.0, where `node:sqlite` is
106
+ available without an experimental flag, and fails earlier runtimes before
107
+ loading the Runner bundle.
108
+ - Prepares only `@synapsor/runner@1.5.2`; `@synapsor/spec@1.4.2`,
109
+ `@synapsor/dsl@1.4.3`, and the Cloud CLI remain unchanged.
110
+
111
+ ## 1.5.1 (prepared, not published)
112
+
113
+ ### Safe ownership for disposable try state
114
+
115
+ - Stops `try` from recursively deleting a caller-provided `--state-dir`.
116
+ Custom paths are now unowned containers; Runner writes into a marked managed
117
+ child and removes only its known direct state files.
118
+ - Rejects filesystem roots, home/cwd/repository paths and their ancestors,
119
+ parent traversal, symlinked path components, unmarked lookalike directories,
120
+ and managed files replaced by links. Unrelated caller files are preserved.
121
+ - Adds an atomic per-state lease. Concurrent runs fail clearly, while a valid
122
+ lease left by a dead process can recover without broad cleanup.
123
+ - Keeps `demo inspect --state-dir` aligned with the managed-child layout and
124
+ safely adopts only the known legacy default `.synapsor/try` file set.
125
+ - Hardens explicit `--force` replacement for generated schema and MCP-audit
126
+ candidate directories against protected paths, symlinked ancestors, and
127
+ linked or invalid ownership markers.
128
+ - Consistently identifies the embedded `try` source as synthetic.
129
+ - Updates the packaged YAML parser to `2.8.3`, which includes the upstream
130
+ deeply nested collection denial-of-service fix.
131
+ - Corrects the repository's stale publication wording for the live `1.5.0`
132
+ release. Only `@synapsor/runner` is staged at `1.5.1`; Spec, DSL, and Cloud
133
+ CLI versions remain unchanged.
134
+
135
+ ## 1.5.0 (2026-07-20)
4
136
 
5
137
  ### Complete guarded-action developer proof
6
138
 
@@ -31,9 +163,8 @@
31
163
  - Rewrites the README around the complete `try --prove` outcome, keeps MCP
32
164
  audit immediately second, names each isolation boundary precisely, and
33
165
  reconciles release documentation with the live npm registry.
34
- - Stages only `@synapsor/runner@1.5.0`; `@synapsor/spec@1.4.2`,
166
+ - Published only `@synapsor/runner@1.5.0`; `@synapsor/spec@1.4.2`,
35
167
  `@synapsor/dsl@1.4.3`, and `@synapsor/cli@0.1.0-beta.1` remain unchanged.
36
- Nothing is published by this change.
37
168
 
38
169
  ## 1.4.123 (2026-07-17)
39
170
 
package/README.md CHANGED
@@ -4,23 +4,26 @@
4
4
  [![license: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
5
5
  [![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)
6
6
 
7
- **Approve the exact business effect, not an opaque tool call.**
7
+ **Let AI agents change real application data without giving the model SQL.**
8
8
 
9
- Synapsor Runner is an open-source MCP runtime for Postgres and MySQL. It
10
- gives agents reviewed business actions instead of `execute_sql`, saves risky
11
- changes as proposals, and keeps database credentials, approval, and writeback
12
- outside the model-facing surface.
9
+ **MCP connects the agent. Synapsor controls the commit.**
13
10
 
14
- ## Prove It In 60 Seconds
11
+ Synapsor Runner is an open-source MCP runtime for Postgres and MySQL. It gives
12
+ agents reviewed business actions, records proposed changes as exact Data PRs,
13
+ and keeps credentials, activation, approval, and commit authority outside the
14
+ model-facing surface.
15
15
 
16
- First, prove the boundary without a database, Docker, config, MCP client, LLM,
17
- or account:
16
+ ## Prove The Boundary In Four Seconds
17
+
18
+ No database, Docker, config, MCP client, LLM, or account is required:
18
19
 
19
20
  ```bash
20
21
  npx -y @synapsor/runner try --prove
21
22
  ```
22
23
 
23
- The embedded source requests a $55 waiver and shows:
24
+ Timing begins after package resolution; cold `npx` download time varies.
25
+
26
+ The embedded synthetic source requests a $55 waiver and proves:
24
27
 
25
28
  ```text
26
29
  Proposed effect: late_fee_cents: 5500 -> 0
@@ -30,11 +33,71 @@ Restart-safe retry: yes; duplicate mutations: 0
30
33
  Stale apply refused: yes
31
34
  ```
32
35
 
33
- Review happens outside the model-facing tools. The command stores inspectable
34
- state under `./.synapsor/try/` and does not test your database connection.
36
+ Review happens outside model-facing tools. State is stored under
37
+ `./.synapsor/try/`; this proves the boundary, not your database connection.
35
38
  `demo --quick` remains a noninteractive compatibility alias.
36
39
 
37
- Next, audit a typical raw-SQL MCP server:
40
+ ## Protect One Action In Your Application
41
+
42
+ Start with a staging database and a read-only credential. Runner inspects
43
+ metadata, creates one reviewed read boundary, and opens the secured localhost
44
+ Workbench:
45
+
46
+ ```bash
47
+ npm install -g @synapsor/runner
48
+ export DATABASE_URL="postgresql://runner_reader:REPLACE_ME@db.example.com:5432/app?sslmode=require"
49
+ synapsor-runner start --from-env DATABASE_URL --schema public
50
+ ```
51
+
52
+ Describe one business action. This creates an inert TypeScript draft; it does
53
+ not add a tool or change the active contract:
54
+
55
+ ```bash
56
+ synapsor-runner start \
57
+ --action plan_credit \
58
+ --description "Propose one reviewed customer plan credit" \
59
+ --based-on support.inspect_customer
60
+ ```
61
+
62
+ Add the reviewed tools to the current Cursor project:
63
+
64
+ ```bash
65
+ synapsor-runner mcp install cursor --project \
66
+ --config ./synapsor.runner.json \
67
+ --store ./.synapsor/local.db
68
+ ```
69
+
70
+ In Cursor, use the Workbench's exact prompt. The checked-in project
71
+ instructions require the coding agent to draft and validate the action while
72
+ leaving effect review and activation to you. Once activated, a request such as
73
+ "give CUS-3001 a $25 plan credit" can only create a semantic proposal:
74
+
75
+ ```text
76
+ Data PR wrp_...
77
+ Action support.propose_plan_credit on CUS-3001
78
+ Effect plan_credit_cents: 0 -> 2500
79
+ Source unchanged before approval: Yes
80
+ ```
81
+
82
+ Review the exact effect in the secured Workbench, select **Approve outside
83
+ MCP**, then run the displayed guarded apply command from a trusted terminal.
84
+ The agent has no approval or commit tool. Runner rechecks scope, policy, row
85
+ version, bounds, and idempotency before returning a receipt; a retry cannot
86
+ duplicate the mutation and a stale proposal conflicts.
87
+
88
+ Inspect the latest lifecycle without copying an id:
89
+
90
+ ```bash
91
+ synapsor-runner lifecycle --details --store ./.synapsor/local.db
92
+ ```
93
+
94
+ See the [own-database guide](docs/getting-started-own-database.md),
95
+ [Cursor plugin guide](docs/cursor-plugin.md), and
96
+ [store lifecycle guide](docs/store-lifecycle.md) for the complete paths.
97
+
98
+ ## Audit An Existing MCP Server
99
+
100
+ Audit a typical raw-SQL MCP server without launching or calling one:
38
101
 
39
102
  ```bash
40
103
  npx -y @synapsor/runner audit --example dangerous-db-mcp
@@ -49,9 +112,10 @@ npx -y @synapsor/runner audit ./tools-list.json
49
112
  It flags raw SQL, arbitrary identifiers, model-controlled authority,
50
113
  model-facing approval/writeback, and missing conflict or idempotency signals.
51
114
  It does not call business tools. See [MCP Database Risk
52
- Review](docs/mcp-audit.md) for supported workflows and limits.
53
-
54
- Then [connect a staging database](#connect-a-staging-database).
115
+ Review](docs/mcp-audit.md) for local manifests, selected-server checks, CI,
116
+ SARIF, evidence labels, and limits. You may not need Runner: use the
117
+ [alternatives guide](docs/alternatives.md) to compare direct read-only access,
118
+ hand-built tools, and this reviewed boundary.
55
119
 
56
120
  ## Safety Model
57
121
 
@@ -96,81 +160,26 @@ not make raw SQL or prompt-injection-prone clients safe.
96
160
  | `postgres_rls` | PostgreSQL also checks transaction-bound tenant/principal scope. Arbitrary trusted-context or credential control remains outside this guarantee. |
97
161
  | `tenant_bound` | Authenticated context selects a restricted per-tenant credential or process. |
98
162
 
99
- Stdio commonly trusts process environment; shared HTTP must use verified signed
100
- claims. Model arguments, query parameters, and arbitrary tenant headers are
101
- never trusted. MySQL has no native RLS; use restricted views or tenant
102
- credentials. See [Database scope] and the
163
+ Use stdio; no socket opens. HTTP requires authentication; non-loopback
164
+ listeners require TLS or an explicit trusted TLS proxy. Shared services require
165
+ signed claims. Model-controlled input and MCP session IDs never establish
166
+ identity. See [HTTP MCP].
167
+ MySQL has no native RLS; use restricted views or tenant credentials. See
168
+ [Database scope] and the
103
169
  [build-vs-adopt guide](docs/why-synapsor-vs-app-guardrails.md).
104
170
 
105
171
  ## Connect A Staging Database
106
172
 
107
- Start with staging and a read-only credential. Keep database permissions,
108
- views, and RLS.
173
+ The setup above stores environment-variable names, not connection strings, and
174
+ never falls back to synthetic data if inspection fails. Keep staging, database
175
+ permissions, restricted views, and RLS underneath Runner. Bind trusted tenant
176
+ and principal values in the launching process, then review the exact field and
177
+ tool surface before connecting Cursor.
109
178
 
110
- ```bash
111
- npm install -g @synapsor/runner
112
- export DATABASE_URL="postgresql://runner_reader:REPLACE_ME@db.example.com:5432/app?sslmode=require"
113
- synapsor-runner start --from-env DATABASE_URL --schema public
114
- ```
115
-
116
- The wizard inspects metadata, generates reviewed capabilities, previews MCP
117
- tools, and prints smoke/serve commands. It stores environment-variable names,
118
- not connection strings.
119
-
120
- [Generate disabled review candidates from Prisma, Drizzle, or
121
- OpenAPI.](docs/schema-api-candidates.md)
122
-
123
- The generated capability is a tenant-scoped read with an explicit column
124
- allowlist and required evidence. See the [own-database
125
- guide](docs/getting-started-own-database.md) for the full configuration.
126
-
127
- ```json
128
- {
129
- "name": "billing.inspect_invoice",
130
- "kind": "read",
131
- "source": "app_postgres",
132
- "target": {
133
- "schema": "public",
134
- "table": "invoices",
135
- "primary_key": "id",
136
- "tenant_key": "tenant_id"
137
- },
138
- "args": {
139
- "invoice_id": { "type": "string", "required": true, "max_length": 128 }
140
- },
141
- "lookup": { "id_from_arg": "invoice_id" },
142
- "visible_columns": ["id", "tenant_id", "status", "late_fee_cents", "updated_at"],
143
- "evidence": "required",
144
- "max_rows": 1
145
- }
146
- ```
147
-
148
- Set the trusted values in the process that launches Runner, then validate and
149
- preview the exact model-facing boundary before connecting an MCP client:
150
-
151
- ```bash
152
- export SYNAPSOR_TENANT_ID="acme"
153
- export SYNAPSOR_PRINCIPAL="local-developer"
154
- synapsor-runner config validate --config ./synapsor.runner.json
155
- synapsor-runner tools preview --config ./synapsor.runner.json --store ./.synapsor/local.db
156
- synapsor-runner mcp serve --config ./synapsor.runner.json --store ./.synapsor/local.db
157
- ```
158
-
159
- For proposal capabilities and writes, follow the
160
- [complete own-database guide](docs/getting-started-own-database.md). Reviewed
161
- single-row INSERT, UPDATE, and DELETE can use Runner's guarded direct
162
- writeback. Runner also supports tightly [bounded set
163
- writes](docs/bounded-set-writeback.md): fixed-predicate UPDATE/DELETE and
164
- exact-review batch INSERT, with human approval, a hard 100-row ceiling, atomic
165
- apply, and exact receipts. Free-form predicates, unbounded or cross-table work,
166
- and external effects go through an [app-owned
167
- executor](docs/writeback-executors.md) after approval.
168
-
169
- Direct writes can use [reviewed
170
- compensation](docs/reversible-change-sets.md). Receipts capture a
171
- bounded inverse; `synapsor-runner revert <proposal_id>` creates a separately
172
- approved proposal. This is not rollback, time travel, or app-owned
173
- compensation.
179
+ The [complete own-database guide](docs/getting-started-own-database.md) covers
180
+ validation, scoped reads, disabled Prisma/Drizzle/OpenAPI candidates, guarded
181
+ single-row writes, and app-owned executors. Use the [host compatibility
182
+ matrix](docs/host-compatibility.md) for accurately tested client behavior.
174
183
 
175
184
  ## Review And Prove Your Contract
176
185
 
@@ -202,18 +211,11 @@ trust boundaries, covered threats, non-goals, and required operator controls.
202
211
  - MCP proposal, evidence, and replay handles are references rather than bearer
203
212
  authority: resource reads re-check the owning tenant and principal against
204
213
  the current trusted session.
205
- - Same-tenant owner/assignee isolation uses a reviewed
206
- [`PRINCIPAL SCOPE KEY`](docs/capability-authoring.md#same-tenant-principal-row-scope)
207
- composed with mandatory tenant scope; `test:principal-scope` proves generic
208
- cross-principal denial and evidence-handle isolation on Postgres and MySQL.
209
- - `test:live-apply`, `test:guarded-crud`, `test:bounded-set`, and
210
- `test:reversible` run disposable PostgreSQL/MySQL scenarios. They prove no
211
- pre-approval mutation, guarded single-row CRUD, idempotent retry,
212
- fail-closed conflicts, bounded atomic sets, exact receipts, and reviewed
213
- compensation.
214
- - The C++/Cloud round-trip verifier exports normalized contracts, validates
215
- them with `@synapsor/spec`, and loads them in Runner. The shared contract and
216
- verification commands are documented in [Conformance](docs/conformance.md).
214
+ - `test:principal-scope`, `test:live-apply`, `test:guarded-crud`,
215
+ `test:bounded-set`, and `test:reversible` prove cross-principal denial,
216
+ no pre-approval mutation, guarded writes, idempotent retry, conflicts,
217
+ bounded atomic sets, receipts, and reviewed compensation on disposable
218
+ PostgreSQL/MySQL fixtures.
217
219
 
218
220
  Runner is a narrow agent/database safety boundary, not a replacement for
219
221
  least-privilege database access, host security, or application authorization.
@@ -221,15 +223,13 @@ See [Security Boundary](docs/security-boundary.md) and
221
223
  [Current Limitations](docs/limitations.md).
222
224
 
223
225
  [Database scope]: docs/database-enforced-scope.md
226
+ [HTTP MCP]: docs/http-mcp.md
224
227
 
225
228
  ## Operate The Approval Loop
226
229
 
227
- Policies combine per-proposal and daily ceilings; exceeding one routes to human
228
- review. Operators get batch apply, metrics, structured logs, and optional
229
- signed roles. Local SQLite is the default; bounded fleets can use verified HTTP
230
- claims, asymmetric JWT sessions, and a shared Postgres `runtime_store`.
231
- `smoke call` follows that store and never falls back to SQLite. Use `/healthz`
232
- for liveness and `/readyz` for dependency readiness. See
230
+ Policies can combine per-proposal and aggregate ceilings; exceeding one routes
231
+ to human review. Local SQLite is the default, while bounded fleets can use
232
+ verified HTTP claims and a shared Postgres runtime store. See
233
233
  [Production](docs/production.md), [Runner Config](docs/runner-config-reference.md),
234
234
  and [Small Runner Fleets](docs/running-a-runner-fleet.md).
235
235
 
@@ -242,16 +242,11 @@ and [Small Runner Fleets](docs/running-a-runner-fleet.md).
242
242
  | `@synapsor/dsl` | SQL-like authoring that compiles contexts, capabilities, and workflow declarations into canonical contract JSON. |
243
243
  | `@synapsor/cli` | Synapsor Cloud administration, contract governance, human review, Runner connections, and shared audit records. |
244
244
 
245
- Runner executes locally. The spec is shared by Runner and Cloud/C++; the DSL
246
- is its reviewable source format. Start with [Capability
247
- Authoring](docs/capability-authoring.md). Use `.synapsor.sql` for generic SQL
248
- highlighting; legacy `.synapsor` files produce the same contract JSON.
249
-
250
- Use the [DSL Reference](docs/dsl-reference.md) for exact authoring grammar and
251
- the [Runner Config Reference](docs/runner-config-reference.md) for every wiring
252
- key, default, and path-resolution rule. The
253
- [Store Lifecycle guide](docs/store-lifecycle.md) explains ledger sensitivity,
254
- owner-only permissions, inspection commands, and retention.
245
+ Runner, JSON, `.synapsor.sql`, and the optional TypeScript
246
+ `@synapsor/runner/authoring` frontend all use the same canonical spec. The
247
+ `@synapsor/runner/shadow` helper records app-owned outcomes without granting
248
+ write authority. Start with [Capability Authoring](docs/capability-authoring.md)
249
+ and the [Runner Config Reference](docs/runner-config-reference.md).
255
250
 
256
251
  ## OSS And Cloud
257
252
 
@@ -0,0 +1,23 @@
1
+ import { type AgentContextSpec, type CapabilitySpec, type PolicySpec, type ResourceSpec, type SynapsorContract, type WorkflowSpec } from "@synapsor/spec";
2
+ export type SynapsorContractDefinition = Omit<SynapsorContract, "spec_version" | "kind">;
3
+ /** Preserve editor inference for a canonical resource definition. */
4
+ export declare function defineResource<const T extends ResourceSpec>(resource: T): T;
5
+ /** Preserve editor inference for trusted context bindings resolved outside model input. */
6
+ export declare function defineAgentContext<const T extends AgentContextSpec>(context: T): T;
7
+ /** Preserve editor inference for a canonical read, aggregate, proposal, or external capability. */
8
+ export declare function defineCapability<const T extends CapabilitySpec>(capability: T): T;
9
+ /** Preserve editor inference for a canonical workflow declaration. */
10
+ export declare function defineWorkflow<const T extends WorkflowSpec>(workflow: T): T;
11
+ /** Preserve editor inference for a canonical policy declaration. */
12
+ export declare function definePolicy<const T extends PolicySpec>(policy: T): T;
13
+ /**
14
+ * Build and validate the same language-neutral contract consumed by the JSON,
15
+ * SQL-like DSL, local Runner, and Cloud registry paths.
16
+ */
17
+ export declare function defineContract<const T extends SynapsorContractDefinition>(definition: T): SynapsorContract & T;
18
+ /** Validate and normalize a code-first definition into canonical contract JSON shape. */
19
+ export declare function compileContract(definition: SynapsorContractDefinition | SynapsorContract): SynapsorContract;
20
+ /** Serialize normalized canonical JSON for review, version control, or Runner loading. */
21
+ export declare function contractJson(definition: SynapsorContractDefinition | SynapsorContract, indentation?: number): string;
22
+ export type { AgentContextSpec, CapabilitySpec, PolicySpec, ResourceSpec, SynapsorContract, WorkflowSpec, } from "@synapsor/spec";
23
+ //# sourceMappingURL=authoring.d.ts.map
@@ -0,0 +1 @@
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"}