@synapsor/runner 1.6.2 → 1.6.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.
- package/AGENTS.md +2 -2
- package/CHANGELOG.md +141 -2
- package/CONTRIBUTING.md +10 -3
- package/README.md +65 -83
- package/SECURITY.md +14 -2
- package/THREAT_MODEL.md +64 -4
- package/dist/authoring.mjs +151 -16
- package/dist/cli.d.ts +31 -3
- package/dist/cli.d.ts.map +1 -1
- package/dist/local-ui.d.ts +145 -1
- package/dist/local-ui.d.ts.map +1 -1
- package/dist/runner.mjs +37488 -19009
- package/dist/runtime.mjs +4056 -235
- package/dist/shadow.mjs +2423 -65
- package/docs/README.md +36 -2
- package/docs/agent-guided-setup.md +239 -0
- package/docs/aggregate-reads.md +14 -5
- package/docs/app-owned-executors.md +5 -6
- package/docs/approval-roles-and-operator-identity.md +353 -0
- package/docs/auto-boundary-and-scoped-explore.md +89 -11
- package/docs/capability-authoring.md +21 -2
- package/docs/client-recipes.md +1 -1
- package/docs/cloud-mode.md +7 -7
- package/docs/conformance.md +6 -3
- package/docs/current-scope.md +32 -2
- package/docs/cursor-plugin.md +3 -3
- package/docs/database-enforced-scope.md +6 -0
- package/docs/dsl-json-parity.md +75 -0
- package/docs/dsl-reference.md +22 -1
- package/docs/fresh-developer-usability.md +155 -80
- package/docs/getting-started-own-database.md +45 -44
- package/docs/guarded-crud-writeback.md +19 -0
- package/docs/guided-onboarding.md +399 -0
- package/docs/human-attention-notifications.md +367 -0
- package/docs/limitations.md +49 -13
- package/docs/local-mode.md +36 -22
- package/docs/mcp-audit.md +14 -14
- package/docs/mcp-client-setup.md +11 -14
- package/docs/mcp-clients.md +1 -1
- package/docs/migrating-to-synapsor-spec.md +42 -0
- package/docs/openai-agents-sdk.md +2 -2
- package/docs/production.md +39 -0
- package/docs/proposal-evidence-freshness.md +7 -7
- package/docs/recipes.md +6 -6
- package/docs/release-notes.md +144 -4
- package/docs/release-policy.md +20 -7
- package/docs/reversible-change-sets.md +1 -1
- package/docs/reviewed-database-views.md +132 -0
- package/docs/reviewed-relationships.md +245 -0
- package/docs/rfcs/006-reviewed-reversible-change-sets.md +1 -1
- package/docs/runner-bundles.md +7 -7
- package/docs/runner-config-reference.md +132 -0
- package/docs/running-a-runner-fleet.md +16 -1
- package/docs/schema-api-candidates.md +1 -1
- package/docs/security-boundary.md +54 -0
- package/docs/store-lifecycle.md +20 -1
- package/docs/supervised-automatic-apply.md +267 -0
- package/docs/troubleshooting-first-run.md +85 -10
- package/docs/use-your-own-database.md +6 -4
- package/docs/workbench-ask.md +279 -0
- package/docs/writeback-executors.md +7 -7
- package/examples/auto-boundary-churn/README.md +1 -1
- package/examples/community-solar-clean-room/README.md +7 -0
- package/examples/community-solar-clean-room/docker-compose.yml +16 -0
- package/examples/community-solar-clean-room/package.json +15 -0
- package/examples/community-solar-clean-room/prisma/schema.prisma +171 -0
- package/examples/community-solar-clean-room/seed/postgres.sql +571 -0
- package/examples/fitflow-guided-onboarding/README.md +43 -0
- package/examples/fitflow-guided-onboarding/app/page.tsx +8 -0
- package/examples/fitflow-guided-onboarding/docker-compose.yml +16 -0
- package/examples/fitflow-guided-onboarding/package.json +18 -0
- package/examples/fitflow-guided-onboarding/prisma/schema.prisma +98 -0
- package/examples/fitflow-guided-onboarding/seed/postgres.sql +401 -0
- package/examples/openai-agents-http/Makefile +1 -1
- package/examples/openai-agents-http/README.md +1 -1
- package/examples/openai-agents-stdio/Makefile +1 -1
- package/examples/openai-agents-stdio/README.md +2 -2
- package/examples/openai-agents-stdio/agent.py +1 -4
- package/examples/operator-oidc/issuer.mjs +188 -0
- package/examples/reference-support-billing-app/README.md +16 -16
- package/examples/retail-clean-room/README.md +7 -0
- package/examples/retail-clean-room/docker-compose.yml +16 -0
- package/examples/retail-clean-room/package.json +9 -0
- package/examples/retail-clean-room/prisma/schema.prisma +239 -0
- package/examples/retail-clean-room/seed/postgres.sql +781 -0
- package/examples/retail-clean-room/view-recipe/average-retained-revenue.synapsor.sql +21 -0
- package/examples/retail-clean-room/view-recipe/synapsor.runner.json +25 -0
- package/examples/support-plan-credit/README.md +6 -2
- package/examples/support-plan-credit/mcp-client-examples/claude-code.sh +1 -4
- package/examples/support-plan-credit/mcp-client-examples/claude-desktop.json +1 -4
- package/examples/support-plan-credit/mcp-client-examples/codex.config.toml +1 -4
- package/examples/support-plan-credit/mcp-client-examples/cursor-global.mcp.json +1 -4
- package/examples/support-plan-credit/mcp-client-examples/cursor-project.mcp.json +1 -4
- package/examples/support-plan-credit/mcp-client-examples/generic-stdio.json +1 -4
- package/examples/support-plan-credit/mcp-client-examples/generic-stdio.mjs +1 -1
- package/examples/support-plan-credit/mcp-client-examples/google-adk.py +1 -1
- package/examples/support-plan-credit/mcp-client-examples/langchain.mjs +1 -1
- package/examples/support-plan-credit/mcp-client-examples/llamaindex.py +1 -1
- package/examples/support-plan-credit/mcp-client-examples/openai-agents-stdio.ts +1 -1
- package/examples/support-plan-credit/mcp-client-examples/vscode.mcp.json +1 -4
- package/fixtures/compatibility/published-1.6.3/manifest.json +76 -0
- package/fixtures/compatibility/published-1.6.3/sources/packages/dsl/examples/aggregate-read.synapsor.sql +21 -0
- package/fixtures/compatibility/published-1.6.3/sources/packages/dsl/examples/billing-late-fee.synapsor.sql +56 -0
- package/fixtures/compatibility/published-1.6.3/sources/packages/dsl/examples/bounded-set-multi-term.synapsor.sql +30 -0
- package/fixtures/compatibility/published-1.6.3/sources/packages/dsl/examples/principal-row-scope.synapsor.sql +23 -0
- package/fixtures/compatibility/published-1.6.3/sources/packages/spec/fixtures/conformance/aggregate-read/contract.json +119 -0
- package/fixtures/compatibility/published-1.6.3/sources/packages/spec/fixtures/conformance/approval-quorum/contract.json +44 -0
- package/fixtures/compatibility/published-1.6.3/sources/packages/spec/fixtures/conformance/bounded-set-threats/contract.json +115 -0
- package/fixtures/compatibility/published-1.6.3/sources/packages/spec/fixtures/conformance/principal-row-scope/contract.json +78 -0
- package/fixtures/compatibility/published-1.6.3/sources/packages/spec/fixtures/conformance/proposal-capability/contract.json +101 -0
- package/fixtures/compatibility/published-1.6.3/sources/packages/spec/fixtures/conformance/reversible-change-sets/contract.json +98 -0
- package/fixtures/compatibility/published-1.6.3/sources/packages/spec/fixtures/valid/basic-read.contract.json +60 -0
- package/llms.txt +10 -5
- package/package.json +11 -3
- package/schemas/schema-candidate-review.schema.json +42 -0
- package/schemas/synapsor.runner.schema.json +227 -4
package/docs/mcp-audit.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# MCP database risk review
|
|
2
2
|
|
|
3
|
-
`npx -y
|
|
3
|
+
`npx -y @synapsor/runner audit <target>` performs a
|
|
4
4
|
static MCP database risk review over an exported tool manifest, a remote MCP
|
|
5
5
|
`tools/list` endpoint, or a stdio MCP server. The `mcp audit` subcommand is also
|
|
6
6
|
available for users who look for the command under the MCP namespace.
|
|
@@ -26,7 +26,7 @@ MCP annotations are treated as hints, not enforcement.
|
|
|
26
26
|
Built-in database MCP risk example:
|
|
27
27
|
|
|
28
28
|
```bash
|
|
29
|
-
npx -y
|
|
29
|
+
npx -y @synapsor/runner audit --example dangerous-db-mcp
|
|
30
30
|
```
|
|
31
31
|
|
|
32
32
|
This bundled example does not require a source checkout or local examples file.
|
|
@@ -37,7 +37,7 @@ table/column inputs, and model-controlled tenant/principal fields.
|
|
|
37
37
|
Human-readable output:
|
|
38
38
|
|
|
39
39
|
```bash
|
|
40
|
-
npx -y
|
|
40
|
+
npx -y @synapsor/runner audit ./tools-list.json
|
|
41
41
|
```
|
|
42
42
|
|
|
43
43
|
The default terminal report groups repeated findings into the three most
|
|
@@ -46,32 +46,32 @@ and one next action instead of repeating the same explanation for every tool.
|
|
|
46
46
|
Use the complete view when triaging every finding:
|
|
47
47
|
|
|
48
48
|
```bash
|
|
49
|
-
npx -y
|
|
49
|
+
npx -y @synapsor/runner audit ./tools-list.json --verbose
|
|
50
50
|
```
|
|
51
51
|
|
|
52
52
|
Remote `tools/list` endpoint with a bearer token kept in the environment:
|
|
53
53
|
|
|
54
54
|
```bash
|
|
55
55
|
SYNAPSOR_MCP_AUDIT_BEARER="..." \
|
|
56
|
-
npx -y
|
|
56
|
+
npx -y @synapsor/runner audit https://mcp.example.com --format json
|
|
57
57
|
```
|
|
58
58
|
|
|
59
59
|
Remote endpoint with a custom bearer-token environment variable:
|
|
60
60
|
|
|
61
61
|
```bash
|
|
62
|
-
npx -y
|
|
62
|
+
npx -y @synapsor/runner audit https://mcp.example.com --bearer-env MCP_AUDIT_TOKEN --format json
|
|
63
63
|
```
|
|
64
64
|
|
|
65
65
|
Stdio MCP server:
|
|
66
66
|
|
|
67
67
|
```bash
|
|
68
|
-
npx -y
|
|
68
|
+
npx -y @synapsor/runner audit 'stdio:node ./server.mjs' --timeout-ms 5000
|
|
69
69
|
```
|
|
70
70
|
|
|
71
71
|
JSON output:
|
|
72
72
|
|
|
73
73
|
```bash
|
|
74
|
-
npx -y
|
|
74
|
+
npx -y @synapsor/runner audit ./tools-list.json --format json
|
|
75
75
|
```
|
|
76
76
|
|
|
77
77
|
The JSON contract remains `synapsor.mcp-audit.v1`; its published schema is
|
|
@@ -80,19 +80,19 @@ The JSON contract remains `synapsor.mcp-audit.v1`; its published schema is
|
|
|
80
80
|
SARIF 2.1.0 output for code-scanning ingestion:
|
|
81
81
|
|
|
82
82
|
```bash
|
|
83
|
-
npx -y
|
|
83
|
+
npx -y @synapsor/runner audit ./tools-list.json --format sarif > mcp-audit.sarif
|
|
84
84
|
```
|
|
85
85
|
|
|
86
86
|
Markdown output for issues, PRs, or security review notes:
|
|
87
87
|
|
|
88
88
|
```bash
|
|
89
|
-
npx -y
|
|
89
|
+
npx -y @synapsor/runner audit --example dangerous-db-mcp --format markdown
|
|
90
90
|
```
|
|
91
91
|
|
|
92
92
|
Inspect a project-scoped Cursor configuration without launching anything:
|
|
93
93
|
|
|
94
94
|
```bash
|
|
95
|
-
npx -y
|
|
95
|
+
npx -y @synapsor/runner audit \
|
|
96
96
|
--mcp-config ./.cursor/mcp.json \
|
|
97
97
|
--format markdown
|
|
98
98
|
```
|
|
@@ -102,7 +102,7 @@ as `requires_operator_verification`. To query one reviewed stdio command, name
|
|
|
102
102
|
that exact server and give explicit consent:
|
|
103
103
|
|
|
104
104
|
```bash
|
|
105
|
-
npx -y
|
|
105
|
+
npx -y @synapsor/runner audit \
|
|
106
106
|
--mcp-config ./.cursor/mcp.json \
|
|
107
107
|
--live-server synapsor \
|
|
108
108
|
--yes \
|
|
@@ -132,7 +132,7 @@ Audit can create a separate review directory without editing or activating the
|
|
|
132
132
|
source configuration:
|
|
133
133
|
|
|
134
134
|
```bash
|
|
135
|
-
npx -y
|
|
135
|
+
npx -y @synapsor/runner audit generate \
|
|
136
136
|
./tools-list.json \
|
|
137
137
|
--output ./synapsor-audit-candidates
|
|
138
138
|
```
|
|
@@ -141,7 +141,7 @@ Open the same blocked candidate directly in the secured local review
|
|
|
141
141
|
workbench:
|
|
142
142
|
|
|
143
143
|
```bash
|
|
144
|
-
npx -y
|
|
144
|
+
npx -y @synapsor/runner audit generate \
|
|
145
145
|
./tools-list.json \
|
|
146
146
|
--output ./synapsor-audit-candidates \
|
|
147
147
|
--open-ui
|
package/docs/mcp-client-setup.md
CHANGED
|
@@ -57,7 +57,7 @@ provisions the same environment value to Runner and the authorized client:
|
|
|
57
57
|
```bash
|
|
58
58
|
export SYNAPSOR_RUNNER_HTTP_TOKEN="$(node -e 'process.stdout.write(require("node:crypto").randomBytes(32).toString("base64url"))')"
|
|
59
59
|
|
|
60
|
-
npx -y
|
|
60
|
+
npx -y @synapsor/runner mcp serve-streamable-http \
|
|
61
61
|
--config ./synapsor.runner.json \
|
|
62
62
|
--store ./.synapsor/local.db \
|
|
63
63
|
--auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
|
|
@@ -69,7 +69,7 @@ OpenAI-safe aliases while keeping canonical Synapsor capability names in MCP
|
|
|
69
69
|
metadata:
|
|
70
70
|
|
|
71
71
|
```bash
|
|
72
|
-
npx -y
|
|
72
|
+
npx -y @synapsor/runner mcp serve-streamable-http \
|
|
73
73
|
--config ./synapsor.runner.json \
|
|
74
74
|
--store ./.synapsor/local.db \
|
|
75
75
|
--auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN \
|
|
@@ -85,7 +85,7 @@ same time.
|
|
|
85
85
|
Preview the exact alias mapping before wiring a client:
|
|
86
86
|
|
|
87
87
|
```bash
|
|
88
|
-
npx -y
|
|
88
|
+
npx -y @synapsor/runner tools preview \
|
|
89
89
|
--config ./synapsor.runner.json \
|
|
90
90
|
--store ./.synapsor/local.db \
|
|
91
91
|
--alias-mode openai
|
|
@@ -101,7 +101,7 @@ with tenant/principal bound from verified claims. Details: [HTTP MCP](http-mcp.m
|
|
|
101
101
|
Print a snippet without modifying any client files:
|
|
102
102
|
|
|
103
103
|
```bash
|
|
104
|
-
npx -y
|
|
104
|
+
npx -y @synapsor/runner mcp config claude-desktop \
|
|
105
105
|
--config ./synapsor.runner.json \
|
|
106
106
|
--store ./.synapsor/local.db
|
|
107
107
|
```
|
|
@@ -121,7 +121,7 @@ For OpenAI Agents SDK, generate the Streamable HTTP start command and Python
|
|
|
121
121
|
snippet:
|
|
122
122
|
|
|
123
123
|
```bash
|
|
124
|
-
npx -y
|
|
124
|
+
npx -y @synapsor/runner mcp client-config \
|
|
125
125
|
--client openai-agents \
|
|
126
126
|
--config ./synapsor.runner.json \
|
|
127
127
|
--store ./.synapsor/local.db
|
|
@@ -130,13 +130,13 @@ npx -y -p @synapsor/runner synapsor-runner mcp client-config \
|
|
|
130
130
|
The older form is still supported:
|
|
131
131
|
|
|
132
132
|
```bash
|
|
133
|
-
npx -y
|
|
133
|
+
npx -y @synapsor/runner mcp configure --client claude-desktop --config ./synapsor.runner.json --store ./.synapsor/local.db
|
|
134
134
|
```
|
|
135
135
|
|
|
136
136
|
Write is opt-in and requires an explicit destination:
|
|
137
137
|
|
|
138
138
|
```bash
|
|
139
|
-
npx -y
|
|
139
|
+
npx -y @synapsor/runner mcp configure \
|
|
140
140
|
--client cursor \
|
|
141
141
|
--config ./synapsor.runner.json \
|
|
142
142
|
--store ./.synapsor/local.db \
|
|
@@ -162,7 +162,7 @@ standalone local UI or terminal for human review.
|
|
|
162
162
|
From the runner repository:
|
|
163
163
|
|
|
164
164
|
```bash
|
|
165
|
-
npx -y
|
|
165
|
+
npx -y @synapsor/runner mcp serve --config ./examples/mcp-postgres-billing/synapsor.runner.json --store ./.synapsor/local.db
|
|
166
166
|
```
|
|
167
167
|
|
|
168
168
|
For reproducible deployments, pin an exact stable version in package manifests
|
|
@@ -172,7 +172,7 @@ the current `latest` release.
|
|
|
172
172
|
For standard app/server HTTP MCP mode:
|
|
173
173
|
|
|
174
174
|
```bash
|
|
175
|
-
npx -y
|
|
175
|
+
npx -y @synapsor/runner mcp serve-streamable-http \
|
|
176
176
|
--config ./examples/mcp-postgres-billing/synapsor.runner.json \
|
|
177
177
|
--store ./.synapsor/local.db \
|
|
178
178
|
--auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
|
|
@@ -190,10 +190,7 @@ sessions, so do not use it for a shared identity deployment.
|
|
|
190
190
|
"synapsor-runner": {
|
|
191
191
|
"command": "npx",
|
|
192
192
|
"args": [
|
|
193
|
-
"-y",
|
|
194
|
-
"-p",
|
|
195
|
-
"@synapsor/runner",
|
|
196
|
-
"synapsor-runner",
|
|
193
|
+
"-y", "@synapsor/runner",
|
|
197
194
|
"mcp",
|
|
198
195
|
"serve",
|
|
199
196
|
"--config",
|
|
@@ -235,7 +232,7 @@ small tool-call test.
|
|
|
235
232
|
First confirm what Runner exposes:
|
|
236
233
|
|
|
237
234
|
```bash
|
|
238
|
-
npx -y
|
|
235
|
+
npx -y @synapsor/runner tools preview \
|
|
239
236
|
--config ./synapsor.runner.json \
|
|
240
237
|
--store ./.synapsor/local.db
|
|
241
238
|
```
|
package/docs/mcp-clients.md
CHANGED
|
@@ -39,7 +39,7 @@ Use stdio for Claude Desktop, Cursor, and other local MCP clients:
|
|
|
39
39
|
{
|
|
40
40
|
"command": "npx",
|
|
41
41
|
"args": [
|
|
42
|
-
"-y", "
|
|
42
|
+
"-y", "@synapsor/runner",
|
|
43
43
|
"mcp", "serve", "--config", "./synapsor.runner.json",
|
|
44
44
|
"--store", "./.synapsor/local.db"
|
|
45
45
|
]
|
|
@@ -148,6 +148,48 @@ The equivalent DSL is `REQUIRE 2 APPROVALS` after `APPROVAL ROLE
|
|
|
148
148
|
billing_lead`. Runner 1.0 does not understand this new optional semantic field;
|
|
149
149
|
use Runner/spec/DSL 1.1 together. Omitted fields preserve 1.0 behavior.
|
|
150
150
|
|
|
151
|
+
## 1.6 Generated Authority And Supervised Execution
|
|
152
|
+
|
|
153
|
+
Runner 1.6.4, Spec 1.7.0, and DSL 1.7.0 are additive. Existing hand-authored
|
|
154
|
+
DSL/JSON/config projects do not need Auto Boundary, Workbench, a generation
|
|
155
|
+
lock, schema rescanning, or supervised execution. Contracts that omit the new
|
|
156
|
+
fields retain their previous canonical normalization and digest.
|
|
157
|
+
|
|
158
|
+
Spec/DSL 1.7.0 add optional reviewed relationship-path fields and `LINK`
|
|
159
|
+
syntax. The legacy one-hop relationship form remains accepted and canonical;
|
|
160
|
+
an unchanged legacy contract retains its exact normalized bytes and digest.
|
|
161
|
+
|
|
162
|
+
Auto Boundary writes a generation lock only for authority it generated.
|
|
163
|
+
Drift enforcement applies only when `synapsor.runner.json` explicitly
|
|
164
|
+
references that lock under `generated_authority`; manually authored projects
|
|
165
|
+
continue to start without metadata inspection.
|
|
166
|
+
|
|
167
|
+
The optional proposal permission:
|
|
168
|
+
|
|
169
|
+
```json
|
|
170
|
+
{
|
|
171
|
+
"execution": {
|
|
172
|
+
"supervised_worker": "allowed"
|
|
173
|
+
}
|
|
174
|
+
}
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
compiles from:
|
|
178
|
+
|
|
179
|
+
```sql
|
|
180
|
+
ALLOW SUPERVISED WORKER APPLY
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
It applies nothing by itself. Automatic execution also requires a separate
|
|
184
|
+
deployment policy for the exact capability and active digest. Existing
|
|
185
|
+
`AUTO APPROVE` contracts continue to wait for manual apply, and no worker
|
|
186
|
+
starts because Runner was upgraded. See
|
|
187
|
+
[Operator-Supervised Automatic Apply](supervised-automatic-apply.md).
|
|
188
|
+
|
|
189
|
+
Human-attention events and external notification sinks require no contract
|
|
190
|
+
migration. Notifications are absent/disabled by default and emit no outbound
|
|
191
|
+
traffic until an operator configures and explicitly runs the dispatcher.
|
|
192
|
+
|
|
151
193
|
## Validate
|
|
152
194
|
|
|
153
195
|
```bash
|
|
@@ -10,7 +10,7 @@ surface.
|
|
|
10
10
|
```bash
|
|
11
11
|
export SYNAPSOR_RUNNER_HTTP_TOKEN="$(node -e 'process.stdout.write(require("node:crypto").randomBytes(32).toString("base64url"))')"
|
|
12
12
|
|
|
13
|
-
npx -y
|
|
13
|
+
npx -y @synapsor/runner mcp serve-streamable-http \
|
|
14
14
|
--config ./synapsor.runner.json \
|
|
15
15
|
--store ./.synapsor/local.db \
|
|
16
16
|
--auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN \
|
|
@@ -30,7 +30,7 @@ model and maps calls back to canonical Synapsor capability names such as
|
|
|
30
30
|
## Generate The Snippet
|
|
31
31
|
|
|
32
32
|
```bash
|
|
33
|
-
npx -y
|
|
33
|
+
npx -y @synapsor/runner mcp client-config \
|
|
34
34
|
--client openai-agents \
|
|
35
35
|
--config ./synapsor.runner.json \
|
|
36
36
|
--store ./.synapsor/local.db \
|
package/docs/production.md
CHANGED
|
@@ -400,6 +400,45 @@ every skipped item includes a safe reason. Re-running is idempotent through
|
|
|
400
400
|
durable receipts. Do not schedule batch apply for a policy that has no reviewed
|
|
401
401
|
aggregate limits.
|
|
402
402
|
|
|
403
|
+
For continuous execution, use the stricter default-off supervised mode rather
|
|
404
|
+
than scheduling broad batch apply. `AUTO APPROVE` by itself remains
|
|
405
|
+
manual-apply. A worker may consume approved work only when the active contract
|
|
406
|
+
contains `execution.supervised_worker = "allowed"` and
|
|
407
|
+
`supervised_worker.capabilities` independently names the exact same capability
|
|
408
|
+
and digest. Production additionally requires verified operator controls and a
|
|
409
|
+
live least-privilege writer-posture fingerprint.
|
|
410
|
+
|
|
411
|
+
```bash
|
|
412
|
+
synapsor-runner worker run --supervised --yes \
|
|
413
|
+
--worker-id billing_worker \
|
|
414
|
+
--config ./synapsor.runner.json
|
|
415
|
+
```
|
|
416
|
+
|
|
417
|
+
The worker accepts only eligible single-row direct INSERT/UPDATE shapes and
|
|
418
|
+
reuses the manual guarded-apply implementation. Before execution it repeats
|
|
419
|
+
approval, policy, limit, expiry, digest/lock, tenant/principal, target and
|
|
420
|
+
supporting-evidence freshness, conflict/deduplication, receipt, writer-posture,
|
|
421
|
+
and lease checks. Source or evidence drift produces zero mutation. DELETE,
|
|
422
|
+
reversible changes, set writes, and app-owned/external effects are not eligible
|
|
423
|
+
for this first automatic path. See [Operator-Supervised Automatic
|
|
424
|
+
Apply](supervised-automatic-apply.md).
|
|
425
|
+
|
|
426
|
+
Production operators can inspect the same queue and Human Attention Inbox in
|
|
427
|
+
the secured Workbench or CLI:
|
|
428
|
+
|
|
429
|
+
```bash
|
|
430
|
+
synapsor-runner worker status --config ./synapsor.runner.json
|
|
431
|
+
synapsor-runner attention show --config ./synapsor.runner.json
|
|
432
|
+
```
|
|
433
|
+
|
|
434
|
+
External delivery is disabled and quiet by default. When explicitly enabled,
|
|
435
|
+
one signed generic webhook can route timely review, UNKNOWN, reconciliation,
|
|
436
|
+
dead-letter, sustained-health, drift, posture, and critical-limit incidents.
|
|
437
|
+
Successful applies remain in the ledger/Workbench unless a sink opts into an
|
|
438
|
+
all-events route or digest. A webhook informs and cannot approve or mutate
|
|
439
|
+
Runner state. See [Human Attention And
|
|
440
|
+
Notifications](human-attention-notifications.md).
|
|
441
|
+
|
|
403
442
|
Runner writes newline-delimited JSON events to stderr for model-facing tool
|
|
404
443
|
rejections, operator decisions, and terminal writeback outcomes. These events
|
|
405
444
|
contain safe codes and identifiers, never tool arguments, row values, database
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Proposal And Evidence Freshness
|
|
2
2
|
|
|
3
|
-
Runner
|
|
3
|
+
Runner provides an optional fail-closed freshness gate for proposals whose
|
|
4
4
|
review depends on live source state.
|
|
5
5
|
|
|
6
6
|
This closes two different review gaps without changing the model-facing MCP
|
|
@@ -11,8 +11,8 @@ surface:
|
|
|
11
11
|
2. A proposal can declare reviewed supporting rows whose exact versions must
|
|
12
12
|
still match before approval and again at apply.
|
|
13
13
|
|
|
14
|
-
Target-row drift
|
|
15
|
-
|
|
14
|
+
Target-row drift is also blocked by the exact conflict guard at apply.
|
|
15
|
+
Freshness does not replace that protection. It adds an earlier review-time
|
|
16
16
|
check and extends the final transaction to declared same-source dependencies.
|
|
17
17
|
|
|
18
18
|
## What Freshness Does And Does Not Mean
|
|
@@ -36,10 +36,10 @@ new source read and create a new proposal with a new hash and review.
|
|
|
36
36
|
|
|
37
37
|
## Configuration
|
|
38
38
|
|
|
39
|
-
Freshness is a Runner deployment overlay in `synapsor.runner.json`.
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
39
|
+
Freshness is a Runner deployment overlay in `synapsor.runner.json`. It adds no
|
|
40
|
+
DSL clause and no canonical Spec field. Existing hand-authored DSL, canonical
|
|
41
|
+
JSON, contract digests, and `tools/list` output remain unchanged when this
|
|
42
|
+
optional section is absent.
|
|
43
43
|
|
|
44
44
|
```json
|
|
45
45
|
{
|
package/docs/recipes.md
CHANGED
|
@@ -9,20 +9,20 @@ tenant key, conflict column, and business limits.
|
|
|
9
9
|
List recipes:
|
|
10
10
|
|
|
11
11
|
```bash
|
|
12
|
-
npx -y
|
|
12
|
+
npx -y @synapsor/runner recipes list
|
|
13
13
|
```
|
|
14
14
|
|
|
15
15
|
Inspect one:
|
|
16
16
|
|
|
17
17
|
```bash
|
|
18
|
-
npx -y
|
|
18
|
+
npx -y @synapsor/runner recipes show billing.late_fee_waiver
|
|
19
19
|
```
|
|
20
20
|
|
|
21
21
|
Initialize a starter config:
|
|
22
22
|
|
|
23
23
|
```bash
|
|
24
|
-
npx -y
|
|
25
|
-
npx -y
|
|
24
|
+
npx -y @synapsor/runner recipes init billing.late_fee_waiver --output synapsor.runner.json
|
|
25
|
+
npx -y @synapsor/runner config validate --config synapsor.runner.json
|
|
26
26
|
```
|
|
27
27
|
|
|
28
28
|
Built-in recipes are JSON files under `recipes/`. They are starter data, not
|
|
@@ -31,8 +31,8 @@ domain, and initialize from your file:
|
|
|
31
31
|
|
|
32
32
|
```bash
|
|
33
33
|
cp recipes/billing.late_fee_waiver.json my-recipe.json
|
|
34
|
-
npx -y
|
|
35
|
-
npx -y
|
|
34
|
+
npx -y @synapsor/runner recipes show ./my-recipe.json
|
|
35
|
+
npx -y @synapsor/runner recipes init ./my-recipe.json --output synapsor.runner.json
|
|
36
36
|
```
|
|
37
37
|
|
|
38
38
|
Available recipes:
|
package/docs/release-notes.md
CHANGED
|
@@ -4,13 +4,153 @@ These notes track public Synapsor Runner behavior. Starting with `1.0.0`, the
|
|
|
4
4
|
documented production-loop compatibility line uses the untagged stable package:
|
|
5
5
|
|
|
6
6
|
```bash
|
|
7
|
-
npx -y
|
|
7
|
+
npx -y @synapsor/runner demo --quick
|
|
8
8
|
```
|
|
9
9
|
|
|
10
10
|
The OSS runner command is `synapsor-runner`. The `synapsor` command is reserved
|
|
11
11
|
for the Synapsor Cloud CLI.
|
|
12
12
|
|
|
13
|
-
## 1.6.
|
|
13
|
+
## 1.6.4 (prepared, not published)
|
|
14
|
+
|
|
15
|
+
### Review-correct onboarding and reviewed relationship paths
|
|
16
|
+
|
|
17
|
+
- Generated-boundary review now uses dependency-scoped invalidation and stale
|
|
18
|
+
revision checks. Editing one resource does not erase unrelated human
|
|
19
|
+
decisions, while stale browser state cannot overwrite a newer review.
|
|
20
|
+
- Workbench starts with a small useful resource pack, explains current agent
|
|
21
|
+
authority and source-change status in plain language, keeps advanced
|
|
22
|
+
permissions behind progressive disclosure, and preserves one recommended
|
|
23
|
+
next action. Project resume and nested config discovery retain existing work.
|
|
24
|
+
- A fresh `npx -y @synapsor/runner start` can accept the database URL through a
|
|
25
|
+
hidden terminal prompt, or load only a selected `DATABASE_URL` from an
|
|
26
|
+
explicitly confirmed local environment file. In the conservative local
|
|
27
|
+
development fast lane, at most two plain questions and one recorded
|
|
28
|
+
digest-bound human gesture lead to a real read without exporting the URL,
|
|
29
|
+
editing generated files, or weakening staging/production review.
|
|
30
|
+
- Deterministic classification is more conservative across unfamiliar domains.
|
|
31
|
+
Database, Prisma, Drizzle, OpenAPI, and existing Synapsor evidence can improve
|
|
32
|
+
names and structure but cannot grant authority or resolve ambiguous trusted
|
|
33
|
+
scope.
|
|
34
|
+
- Protected aggregate reads may contain up to three activated reviewed
|
|
35
|
+
relationship paths. Each path has one or two catalog-proven many-to-one
|
|
36
|
+
links with fan-out one. The model can select an activated path by name but
|
|
37
|
+
cannot provide a table, key, join type, or activation decision.
|
|
38
|
+
- A question needing an inactive proven path fails closed and stages that exact
|
|
39
|
+
path for operator review. Optional links require an explicit missing-row
|
|
40
|
+
choice because excluding versus retaining an unmatched counted row can change
|
|
41
|
+
totals. The reviewed choice and structural proof are digest-bound.
|
|
42
|
+
- Scope is enforced independently on every relation. Cohort suppression runs
|
|
43
|
+
after final grouping. One-to-many, many-to-many, ambiguous, stale, over-depth,
|
|
44
|
+
and model-improvised joins remain refused; complex formulas and relationship
|
|
45
|
+
graphs use reviewed database views.
|
|
46
|
+
- Packed Community Solar and Retail clean-room journeys and live
|
|
47
|
+
PostgreSQL/MySQL relationship gates cover unfamiliar-domain onboarding,
|
|
48
|
+
PM-style analysis, demand-driven review, nullable semantics, drift,
|
|
49
|
+
suppression, scope, and deliberate fan-out rejection.
|
|
50
|
+
- Workbench now offers an optional local **Ask with your model** client over the
|
|
51
|
+
exact active MCP/runtime tools. OpenAI, Anthropic, and custom
|
|
52
|
+
OpenAI-compatible adapters use explicit digest-bound direct-egress consent,
|
|
53
|
+
in-memory credentials/history, bounded tool loops, escaped provider prose,
|
|
54
|
+
and proposal-only writes. The no-model composer remains the default.
|
|
55
|
+
- Remote provider requests use fixed official origins or an operator-selected
|
|
56
|
+
HTTPS custom origin, refuse redirects, validate and pin DNS on every
|
|
57
|
+
connection, block private/special/metadata targets, redact errors, and
|
|
58
|
+
support Node 22's multi-address lookup contract. Plain HTTP remains
|
|
59
|
+
loopback-only.
|
|
60
|
+
- Both packed clean-room domains now pass the real Ask UI. The Retail journey
|
|
61
|
+
shows a kept-out-field refusal; Community Solar shows a source-unchanged
|
|
62
|
+
proposal. An owner-authorized live OpenAI `gpt-5-mini` acceptance run used
|
|
63
|
+
the same official-MCP path, matched its aggregate result, and passed exact-key
|
|
64
|
+
project/ledger/browser/output/evidence scans. Anthropic and generic
|
|
65
|
+
compatible claims are limited to the documented tested protocol matrix.
|
|
66
|
+
- Human-facing commands now use the shortest true form: direct `npx` for first
|
|
67
|
+
acquisition and `synapsor-runner <command>` after installation. The optional
|
|
68
|
+
unscoped `synapsor-runner` npm package contains no runtime or authority logic;
|
|
69
|
+
it delegates to the exact matching scoped Runner version. Existing explicit
|
|
70
|
+
package, pinned, CI, and machine-readable invocations remain compatible.
|
|
71
|
+
- Generated DSL previews use one local, escaped, copy-exact syntax highlighter
|
|
72
|
+
in light and dark themes with no CDN or unsafe HTML fallback. Activity and
|
|
73
|
+
human review details use the full Workbench width instead of a compressed
|
|
74
|
+
side column, including mobile layouts.
|
|
75
|
+
- Existing hand-authored and published `1.6.3` projects do not need the new
|
|
76
|
+
relationship fields, generation review, or Workbench. Legacy contracts keep
|
|
77
|
+
their exact normalized bytes/digests and existing tool lists remain
|
|
78
|
+
unchanged unless the feature is adopted.
|
|
79
|
+
|
|
80
|
+
Prepared package versions: `@synapsor/runner@1.6.4`,
|
|
81
|
+
`@synapsor/spec@1.7.0`, `@synapsor/dsl@1.7.0`, and the optional
|
|
82
|
+
`synapsor-runner@1.6.4` command alias.
|
|
83
|
+
No package is published by this change.
|
|
84
|
+
|
|
85
|
+
Publish Spec first, then DSL, then the scoped Runner, and finally its exact
|
|
86
|
+
version command alias. Force the final registry-only Runner dependency check
|
|
87
|
+
with
|
|
88
|
+
`VERIFY_PACKED_RUNNER_USE_LOCAL_SPEC=0 ./scripts/verify-packed-runner.sh` after
|
|
89
|
+
Spec 1.7.0 is visible on npm, and verify the alias only after
|
|
90
|
+
`@synapsor/runner@1.6.4` is visible.
|
|
91
|
+
|
|
92
|
+
## 1.6.3 (published 2026-07-24)
|
|
93
|
+
|
|
94
|
+
### Guided adoption without weaker authority
|
|
95
|
+
|
|
96
|
+
- A fresh interactive
|
|
97
|
+
`npx -y @synapsor/runner start --from-env DATABASE_URL` now drives one
|
|
98
|
+
resumable metadata-inspection, review-by-exception, exact-digest activation,
|
|
99
|
+
first safe read, and MCP setup journey. It requires no account, model key,
|
|
100
|
+
Cloud control plane, global install, or manual project files.
|
|
101
|
+
- Workbench explains the boundary before exposing advanced details, highlights
|
|
102
|
+
only unresolved security decisions, and keeps one primary next action visible.
|
|
103
|
+
Generated read, aggregate, protected, and write authorities remain disabled
|
|
104
|
+
until the human activates the exact reviewed digest.
|
|
105
|
+
- Project-aware `try call`, `try explore`, `try protect`, and guided action
|
|
106
|
+
paths remove repeated config/store flags and copied handles while preserving
|
|
107
|
+
the canonical DSL/Spec/runtime boundary and existing manual/headless paths.
|
|
108
|
+
- The packaged FitFlow journey proves a real named read, privacy-suppressed
|
|
109
|
+
PM-style aggregate, Protect This Query, proposal-only model call, bounded
|
|
110
|
+
approval policy, guarded source write, receipt/replay, compensation, and
|
|
111
|
+
equivalent authority across Workbench, CLI, Cursor, Claude, Codex, and
|
|
112
|
+
generic stdio setup.
|
|
113
|
+
- The packaged approval-role guide and simulated external OIDC/JWKS flow show
|
|
114
|
+
how `APPROVAL ROLE` maps to verified IdP claims and immutable decisions.
|
|
115
|
+
Reviewer and applier authority remain separate; invalid signatures, token
|
|
116
|
+
time/issuer/audience failures, missing or similar roles, key rotation errors,
|
|
117
|
+
proof tampering, and proof replay fail closed.
|
|
118
|
+
- Operator-supervised automatic apply is a new default-off execution axis.
|
|
119
|
+
Contract permission and an independent deployment allowlist must match one
|
|
120
|
+
exact active digest. Existing `AUTO APPROVE` behavior remains manual-apply;
|
|
121
|
+
eligible single-row INSERT/UPDATE work uses the same guarded apply after
|
|
122
|
+
current policy, limit, scope, target/supporting-evidence freshness,
|
|
123
|
+
writer-posture, receipt, and fenced-lease revalidation.
|
|
124
|
+
- The ledger and Workbench now project durable redacted human-attention events
|
|
125
|
+
for proposal, worker, boundary, schema, credential, policy, and sensitive
|
|
126
|
+
override states. External delivery is disabled and quiet by default. A
|
|
127
|
+
separate dispatcher supports coalescing, budgets, digests, JSONL development
|
|
128
|
+
output, and signed generic HTTPS webhooks that inform but never authorize.
|
|
129
|
+
- Replaying a failed notification requires a fresh verified signed-key or OIDC
|
|
130
|
+
operator decision bound to the exact delivery revision and a recorded
|
|
131
|
+
reason. It requeues only the redacted event. Packed tests prove competing
|
|
132
|
+
dispatcher deduplication, zero immediate success noise under the default
|
|
133
|
+
preset, metadata-endpoint SSRF refusal, and an unchanged source database
|
|
134
|
+
across notification replay.
|
|
135
|
+
- Workbench and CLI expose queue status, pause/drain, exact-digest
|
|
136
|
+
enable/disable/revoke, cancellation, dead-letter, UNKNOWN/reconciliation,
|
|
137
|
+
notification status/replay, and no-ID attention inspection outside MCP.
|
|
138
|
+
- Supported JSON failure paths emit one parseable result with a stable error
|
|
139
|
+
code, preserved-state and source-change status, one recovery action, and
|
|
140
|
+
redacted diagnostics on stderr.
|
|
141
|
+
- An explicit empty `capabilities` array is now valid zero-authority review
|
|
142
|
+
state. The optional canonical `execution.supervised_worker` permission and
|
|
143
|
+
public `ALLOW SUPERVISED WORKER APPLY` clause are additive. Spec and DSL
|
|
144
|
+
advance to `1.6.0` while preserving old contract normalization, digests, and
|
|
145
|
+
generated-lock support.
|
|
146
|
+
|
|
147
|
+
Published package versions: `@synapsor/runner@1.6.3`,
|
|
148
|
+
`@synapsor/spec@1.6.0`, and `@synapsor/dsl@1.6.0`.
|
|
149
|
+
|
|
150
|
+
The pre-release clean-install gate used the locally packed public Spec until
|
|
151
|
+
Spec 1.6.0 reached npm, then returned to the registry-only dependency proof.
|
|
152
|
+
|
|
153
|
+
## 1.6.2 (published 2026-07-23)
|
|
14
154
|
|
|
15
155
|
### Registry-installable packaging hotfix
|
|
16
156
|
|
|
@@ -25,7 +165,7 @@ for the Synapsor Cloud CLI.
|
|
|
25
165
|
therefore exercises the dependency-resolution path used by public `npx`.
|
|
26
166
|
- Runtime behavior is unchanged from the proposal/evidence freshness release.
|
|
27
167
|
|
|
28
|
-
|
|
168
|
+
Published package version: `@synapsor/runner@1.6.2`.
|
|
29
169
|
`@synapsor/spec@1.5.0` and `@synapsor/dsl@1.5.0` remain unchanged.
|
|
30
170
|
|
|
31
171
|
## 1.6.1 (published 2026-07-23; install-broken)
|
|
@@ -641,7 +781,7 @@ not change and must not be republished for this release.
|
|
|
641
781
|
### Public npm DX
|
|
642
782
|
|
|
643
783
|
- Prepares the spec-ready Runner package for the normal untagged npm path so
|
|
644
|
-
developers can use `npx -y
|
|
784
|
+
developers can use `npx -y @synapsor/runner ...` without
|
|
645
785
|
knowing about the temporary `next` release-candidate tag.
|
|
646
786
|
- Keeps the same contract/spec functionality as `0.1.2`; this is a release
|
|
647
787
|
hygiene patch for public install and README/package-page verification.
|
package/docs/release-policy.md
CHANGED
|
@@ -7,7 +7,7 @@ shared runtime-store deployment are part of the documented compatibility
|
|
|
7
7
|
surface. Use the stable package for normal installs:
|
|
8
8
|
|
|
9
9
|
```bash
|
|
10
|
-
npx -y
|
|
10
|
+
npx -y @synapsor/runner demo --quick
|
|
11
11
|
npm install -g @synapsor/runner
|
|
12
12
|
```
|
|
13
13
|
|
|
@@ -38,9 +38,10 @@ Alpha releases must keep the safety boundary intact:
|
|
|
38
38
|
- no generic model-generated INSERT/DELETE/UPSERT/DDL/multi-row SQL;
|
|
39
39
|
- proposal-first write path stays explicit.
|
|
40
40
|
|
|
41
|
-
## Stable Expectations
|
|
41
|
+
## Stable Release Expectations
|
|
42
42
|
|
|
43
|
-
|
|
43
|
+
Every stable release must preserve the safety boundary and should be tagged
|
|
44
|
+
only after:
|
|
44
45
|
|
|
45
46
|
- npm README commands match the published package;
|
|
46
47
|
- `synapsor-runner demo --quick` works from a clean directory;
|
|
@@ -62,7 +63,7 @@ A stable `0.1.0` release should only be tagged after:
|
|
|
62
63
|
- there are no known docs/code mismatches around transport, credentials,
|
|
63
64
|
receipt tables, or handler expectations.
|
|
64
65
|
|
|
65
|
-
## 1.0 Stability Gate
|
|
66
|
+
## Historical 1.0 Stability Gate
|
|
66
67
|
|
|
67
68
|
Do not tag `1.0.0` only because the package is useful. `1.0.0` is the public
|
|
68
69
|
semver contract for the Runner production approval loop, and it should be cut
|
|
@@ -89,7 +90,7 @@ versioning. Breaking changes require a new major version, except for security
|
|
|
89
90
|
fixes that close a vulnerability while preserving the safest possible
|
|
90
91
|
compatibility path.
|
|
91
92
|
|
|
92
|
-
## 1.1 Fleet Gate
|
|
93
|
+
## Historical 1.1 Fleet Gate
|
|
93
94
|
|
|
94
95
|
Do not publish `1.1.0` until all 1.0 gates remain green and the local synthetic
|
|
95
96
|
fleet verifier proves:
|
|
@@ -167,15 +168,27 @@ Before publishing any release:
|
|
|
167
168
|
./scripts/verify-release-gate.sh
|
|
168
169
|
```
|
|
169
170
|
|
|
171
|
+
For a coordinated Spec/DSL/Runner release, publish in dependency order:
|
|
172
|
+
|
|
173
|
+
1. `@synapsor/spec`;
|
|
174
|
+
2. `@synapsor/dsl`;
|
|
175
|
+
3. `@synapsor/runner`;
|
|
176
|
+
4. the optional `synapsor-runner` command alias, when prepared.
|
|
177
|
+
|
|
178
|
+
The alias must have the same version as the scoped Runner and depend on that
|
|
179
|
+
exact registry version. It contains no independent runtime or authority logic.
|
|
180
|
+
Run `corepack pnpm verify:packed-runner-alias` before publishing it, and do not
|
|
181
|
+
publish it until the matching scoped Runner is visible on npm.
|
|
182
|
+
|
|
170
183
|
After publishing an alpha prerelease:
|
|
171
184
|
|
|
172
185
|
```bash
|
|
173
|
-
VERIFY_PUBLISHED_ALPHA=1 ./scripts/verify-release-gate.sh
|
|
186
|
+
VERIFY_PUBLISHED_ALPHA=1 ./scripts/verify-release-gate.sh <prerelease-version>
|
|
174
187
|
```
|
|
175
188
|
|
|
176
189
|
After publishing/promoting stable `latest`, verify the stable channel from a
|
|
177
190
|
clean temporary directory:
|
|
178
191
|
|
|
179
192
|
```bash
|
|
180
|
-
./scripts/verify-published-stable.sh
|
|
193
|
+
./scripts/verify-published-stable.sh <stable-version>
|
|
181
194
|
```
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Reviewed Reversible Change Sets
|
|
2
2
|
|
|
3
|
-
Synapsor Runner
|
|
3
|
+
Synapsor Runner can capture a bounded inverse for an opt-in direct database
|
|
4
4
|
write. This is **reviewed compensation**, not rollback or database time travel.
|
|
5
5
|
|
|
6
6
|
The operator flow is deliberately two separate approval loops:
|