@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.
Files changed (116) hide show
  1. package/AGENTS.md +2 -2
  2. package/CHANGELOG.md +141 -2
  3. package/CONTRIBUTING.md +10 -3
  4. package/README.md +65 -83
  5. package/SECURITY.md +14 -2
  6. package/THREAT_MODEL.md +64 -4
  7. package/dist/authoring.mjs +151 -16
  8. package/dist/cli.d.ts +31 -3
  9. package/dist/cli.d.ts.map +1 -1
  10. package/dist/local-ui.d.ts +145 -1
  11. package/dist/local-ui.d.ts.map +1 -1
  12. package/dist/runner.mjs +37488 -19009
  13. package/dist/runtime.mjs +4056 -235
  14. package/dist/shadow.mjs +2423 -65
  15. package/docs/README.md +36 -2
  16. package/docs/agent-guided-setup.md +239 -0
  17. package/docs/aggregate-reads.md +14 -5
  18. package/docs/app-owned-executors.md +5 -6
  19. package/docs/approval-roles-and-operator-identity.md +353 -0
  20. package/docs/auto-boundary-and-scoped-explore.md +89 -11
  21. package/docs/capability-authoring.md +21 -2
  22. package/docs/client-recipes.md +1 -1
  23. package/docs/cloud-mode.md +7 -7
  24. package/docs/conformance.md +6 -3
  25. package/docs/current-scope.md +32 -2
  26. package/docs/cursor-plugin.md +3 -3
  27. package/docs/database-enforced-scope.md +6 -0
  28. package/docs/dsl-json-parity.md +75 -0
  29. package/docs/dsl-reference.md +22 -1
  30. package/docs/fresh-developer-usability.md +155 -80
  31. package/docs/getting-started-own-database.md +45 -44
  32. package/docs/guarded-crud-writeback.md +19 -0
  33. package/docs/guided-onboarding.md +399 -0
  34. package/docs/human-attention-notifications.md +367 -0
  35. package/docs/limitations.md +49 -13
  36. package/docs/local-mode.md +36 -22
  37. package/docs/mcp-audit.md +14 -14
  38. package/docs/mcp-client-setup.md +11 -14
  39. package/docs/mcp-clients.md +1 -1
  40. package/docs/migrating-to-synapsor-spec.md +42 -0
  41. package/docs/openai-agents-sdk.md +2 -2
  42. package/docs/production.md +39 -0
  43. package/docs/proposal-evidence-freshness.md +7 -7
  44. package/docs/recipes.md +6 -6
  45. package/docs/release-notes.md +144 -4
  46. package/docs/release-policy.md +20 -7
  47. package/docs/reversible-change-sets.md +1 -1
  48. package/docs/reviewed-database-views.md +132 -0
  49. package/docs/reviewed-relationships.md +245 -0
  50. package/docs/rfcs/006-reviewed-reversible-change-sets.md +1 -1
  51. package/docs/runner-bundles.md +7 -7
  52. package/docs/runner-config-reference.md +132 -0
  53. package/docs/running-a-runner-fleet.md +16 -1
  54. package/docs/schema-api-candidates.md +1 -1
  55. package/docs/security-boundary.md +54 -0
  56. package/docs/store-lifecycle.md +20 -1
  57. package/docs/supervised-automatic-apply.md +267 -0
  58. package/docs/troubleshooting-first-run.md +85 -10
  59. package/docs/use-your-own-database.md +6 -4
  60. package/docs/workbench-ask.md +279 -0
  61. package/docs/writeback-executors.md +7 -7
  62. package/examples/auto-boundary-churn/README.md +1 -1
  63. package/examples/community-solar-clean-room/README.md +7 -0
  64. package/examples/community-solar-clean-room/docker-compose.yml +16 -0
  65. package/examples/community-solar-clean-room/package.json +15 -0
  66. package/examples/community-solar-clean-room/prisma/schema.prisma +171 -0
  67. package/examples/community-solar-clean-room/seed/postgres.sql +571 -0
  68. package/examples/fitflow-guided-onboarding/README.md +43 -0
  69. package/examples/fitflow-guided-onboarding/app/page.tsx +8 -0
  70. package/examples/fitflow-guided-onboarding/docker-compose.yml +16 -0
  71. package/examples/fitflow-guided-onboarding/package.json +18 -0
  72. package/examples/fitflow-guided-onboarding/prisma/schema.prisma +98 -0
  73. package/examples/fitflow-guided-onboarding/seed/postgres.sql +401 -0
  74. package/examples/openai-agents-http/Makefile +1 -1
  75. package/examples/openai-agents-http/README.md +1 -1
  76. package/examples/openai-agents-stdio/Makefile +1 -1
  77. package/examples/openai-agents-stdio/README.md +2 -2
  78. package/examples/openai-agents-stdio/agent.py +1 -4
  79. package/examples/operator-oidc/issuer.mjs +188 -0
  80. package/examples/reference-support-billing-app/README.md +16 -16
  81. package/examples/retail-clean-room/README.md +7 -0
  82. package/examples/retail-clean-room/docker-compose.yml +16 -0
  83. package/examples/retail-clean-room/package.json +9 -0
  84. package/examples/retail-clean-room/prisma/schema.prisma +239 -0
  85. package/examples/retail-clean-room/seed/postgres.sql +781 -0
  86. package/examples/retail-clean-room/view-recipe/average-retained-revenue.synapsor.sql +21 -0
  87. package/examples/retail-clean-room/view-recipe/synapsor.runner.json +25 -0
  88. package/examples/support-plan-credit/README.md +6 -2
  89. package/examples/support-plan-credit/mcp-client-examples/claude-code.sh +1 -4
  90. package/examples/support-plan-credit/mcp-client-examples/claude-desktop.json +1 -4
  91. package/examples/support-plan-credit/mcp-client-examples/codex.config.toml +1 -4
  92. package/examples/support-plan-credit/mcp-client-examples/cursor-global.mcp.json +1 -4
  93. package/examples/support-plan-credit/mcp-client-examples/cursor-project.mcp.json +1 -4
  94. package/examples/support-plan-credit/mcp-client-examples/generic-stdio.json +1 -4
  95. package/examples/support-plan-credit/mcp-client-examples/generic-stdio.mjs +1 -1
  96. package/examples/support-plan-credit/mcp-client-examples/google-adk.py +1 -1
  97. package/examples/support-plan-credit/mcp-client-examples/langchain.mjs +1 -1
  98. package/examples/support-plan-credit/mcp-client-examples/llamaindex.py +1 -1
  99. package/examples/support-plan-credit/mcp-client-examples/openai-agents-stdio.ts +1 -1
  100. package/examples/support-plan-credit/mcp-client-examples/vscode.mcp.json +1 -4
  101. package/fixtures/compatibility/published-1.6.3/manifest.json +76 -0
  102. package/fixtures/compatibility/published-1.6.3/sources/packages/dsl/examples/aggregate-read.synapsor.sql +21 -0
  103. package/fixtures/compatibility/published-1.6.3/sources/packages/dsl/examples/billing-late-fee.synapsor.sql +56 -0
  104. package/fixtures/compatibility/published-1.6.3/sources/packages/dsl/examples/bounded-set-multi-term.synapsor.sql +30 -0
  105. package/fixtures/compatibility/published-1.6.3/sources/packages/dsl/examples/principal-row-scope.synapsor.sql +23 -0
  106. package/fixtures/compatibility/published-1.6.3/sources/packages/spec/fixtures/conformance/aggregate-read/contract.json +119 -0
  107. package/fixtures/compatibility/published-1.6.3/sources/packages/spec/fixtures/conformance/approval-quorum/contract.json +44 -0
  108. package/fixtures/compatibility/published-1.6.3/sources/packages/spec/fixtures/conformance/bounded-set-threats/contract.json +115 -0
  109. package/fixtures/compatibility/published-1.6.3/sources/packages/spec/fixtures/conformance/principal-row-scope/contract.json +78 -0
  110. package/fixtures/compatibility/published-1.6.3/sources/packages/spec/fixtures/conformance/proposal-capability/contract.json +101 -0
  111. package/fixtures/compatibility/published-1.6.3/sources/packages/spec/fixtures/conformance/reversible-change-sets/contract.json +98 -0
  112. package/fixtures/compatibility/published-1.6.3/sources/packages/spec/fixtures/valid/basic-read.contract.json +60 -0
  113. package/llms.txt +10 -5
  114. package/package.json +11 -3
  115. package/schemas/schema-candidate-review.schema.json +42 -0
  116. 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 -p @synapsor/runner synapsor-runner audit <target>` performs a
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 -p @synapsor/runner synapsor-runner audit --example dangerous-db-mcp
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 -p @synapsor/runner synapsor-runner audit ./tools-list.json
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 -p @synapsor/runner synapsor-runner audit ./tools-list.json --verbose
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 -p @synapsor/runner synapsor-runner audit https://mcp.example.com --format json
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 -p @synapsor/runner synapsor-runner audit https://mcp.example.com --bearer-env MCP_AUDIT_TOKEN --format json
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 -p @synapsor/runner synapsor-runner audit 'stdio:node ./server.mjs' --timeout-ms 5000
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 -p @synapsor/runner synapsor-runner audit ./tools-list.json --format json
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 -p @synapsor/runner synapsor-runner audit ./tools-list.json --format sarif > mcp-audit.sarif
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 -p @synapsor/runner synapsor-runner audit --example dangerous-db-mcp --format markdown
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 -p @synapsor/runner synapsor-runner audit \
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 -p @synapsor/runner synapsor-runner audit \
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 -p @synapsor/runner synapsor-runner audit generate \
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 -p @synapsor/runner synapsor-runner audit generate \
144
+ npx -y @synapsor/runner audit generate \
145
145
  ./tools-list.json \
146
146
  --output ./synapsor-audit-candidates \
147
147
  --open-ui
@@ -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 -p @synapsor/runner synapsor-runner mcp serve-streamable-http \
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 -p @synapsor/runner synapsor-runner mcp serve-streamable-http \
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 -p @synapsor/runner synapsor-runner tools preview \
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 -p @synapsor/runner synapsor-runner mcp config claude-desktop \
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 -p @synapsor/runner synapsor-runner mcp client-config \
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 -p @synapsor/runner synapsor-runner mcp configure --client claude-desktop --config ./synapsor.runner.json --store ./.synapsor/local.db
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 -p @synapsor/runner synapsor-runner mcp configure \
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 -p @synapsor/runner synapsor-runner mcp serve --config ./examples/mcp-postgres-billing/synapsor.runner.json --store ./.synapsor/local.db
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 -p @synapsor/runner synapsor-runner mcp serve-streamable-http \
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 -p @synapsor/runner synapsor-runner tools preview \
235
+ npx -y @synapsor/runner tools preview \
239
236
  --config ./synapsor.runner.json \
240
237
  --store ./.synapsor/local.db
241
238
  ```
@@ -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", "-p", "@synapsor/runner", "synapsor-runner",
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 -p @synapsor/runner synapsor-runner mcp serve-streamable-http \
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 -p @synapsor/runner synapsor-runner mcp client-config \
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 \
@@ -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 1.6.1 adds an optional fail-closed freshness gate for proposals whose
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 was already blocked by the exact conflict guard at apply.
15
- Version 1.6.1 does not replace that protection. It adds an earlier review-time
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`. Version
40
- 1.6.1 adds no DSL clause and no canonical Spec field. Existing hand-authored
41
- DSL, canonical JSON, contract digests, and `tools/list` output remain unchanged
42
- when this optional section is absent.
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 -p @synapsor/runner synapsor-runner recipes list
12
+ npx -y @synapsor/runner recipes list
13
13
  ```
14
14
 
15
15
  Inspect one:
16
16
 
17
17
  ```bash
18
- npx -y -p @synapsor/runner synapsor-runner recipes show billing.late_fee_waiver
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 -p @synapsor/runner synapsor-runner recipes init billing.late_fee_waiver --output synapsor.runner.json
25
- npx -y -p @synapsor/runner synapsor-runner config validate --config synapsor.runner.json
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 -p @synapsor/runner synapsor-runner recipes show ./my-recipe.json
35
- npx -y -p @synapsor/runner synapsor-runner recipes init ./my-recipe.json --output synapsor.runner.json
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:
@@ -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 -p @synapsor/runner synapsor-runner demo --quick
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.2 (prepared, not published)
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
- Prepared package version: `@synapsor/runner@1.6.2`.
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 -p @synapsor/runner synapsor-runner ...` without
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.
@@ -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 -p @synapsor/runner synapsor-runner demo --quick
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
- A stable `0.1.0` release should only be tagged after:
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 0.1.0-alpha.17
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 0.1.0
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 1.4 can capture a bounded inverse for an opt-in direct database
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: