@synapsor/runner 1.5.0 → 1.5.4

package/docs/dsl-reference.md

@@ -29,7 +29,7 @@ END
 
 | Clause | Meaning |
 | --- | --- |
-| `BIND name FROM source key [REQUIRED]` | Defines trusted context. Sources: `SESSION`, `ENV`/`ENVIRONMENT`, `CLOUD_SESSION`, `STATIC_DEV`, `HTTP_CLAIM`. Model tool arguments cannot set these bindings. |
+| `BIND name FROM source key [REQUIRED]` | Defines trusted context. Canonical sources: `SESSION`, `ENV`/`ENVIRONMENT`, `CLOUD_SESSION`, `STATIC_DEV`, `HTTP_CLAIM`. Model tool arguments cannot set these bindings. Runner rejects `SESSION`; use one of its implemented verified providers described below. |
 | `TENANT BINDING name` | Selects the binding used for tenant scope. Defaults to a binding named `tenant_id`. |
 | `PRINCIPAL BINDING name` | Selects the actor binding. Defaults to a binding named `principal`. |
 
@@ -65,16 +65,57 @@ END
 | `TENANT KEY column` | Required in DSL 0.1. Adds trusted tenant scope to every read/write. |
 | `PRINCIPAL SCOPE KEY column` | Optional tenant-additive row lock. Runner binds this fixed column to the context's required trusted `PRINCIPAL BINDING`; it is never a model argument. |
 | `CONFLICT GUARD column` | Captures the row-version value for exact guarded writeback. Prefer a monotonic version or native-precision timestamp. |
+| `CONFLICT GUARD WEAK ROW HASH ACKNOWLEDGED` | Explicitly accepts a weaker hash over the captured projection for a legacy, ordinary single-row source-DB UPDATE. It may miss concurrent changes outside that projection and is never equivalent to a version column. |
+
+An UPDATE proposal must choose one of those guard clauses. Omitting the clause
+is a compile error; the compiler never silently selects the weak form. The weak
+form is rejected for INSERT, DELETE, reversible writes, bounded sets, and
+Runner-ledger authority. `contract lint`, `contract explain`, `doctor`, and
+`tools preview` all identify it prominently.
+
+To migrate a legacy DSL file that omitted the guard, inspect the target schema
+and add an exact source column:
+
+```sql
+  CONFLICT GUARD version
+```
+
+Use a monotonic integer/version column when available, or a native-precision
+`updated_at` maintained by the database. If a legacy source has no usable
+version column and the capability is an ordinary single-row UPDATE using
+source-DB receipt authority, the explicit weak clause keeps the previous
+projection-hash behavior while recording the reduced assurance in review
+output. Do not use it as a production-equivalent substitute for a real version
+column.
 
 `PRINCIPAL SCOPE KEY` means `tenant_key = trusted tenant AND
 principal_scope_key = trusted principal`. It cannot replace tenant scope,
 default to all rows, or be overridden by an argument. The principal binding
-must be required and come from a trusted provider such as `ENVIRONMENT`,
-`HTTP_CLAIM`, `SESSION`, or `CLOUD_SESSION`. For networked multi-user serving,
-use signed HTTP claims. See the complete
+must be required and come from a trusted Runner provider: `ENVIRONMENT`,
+verified `HTTP_CLAIM`, verified `CLOUD_SESSION`, or explicit
+`STATIC_DEV` for development only. For networked multi-user serving, use
+signed HTTP claims. Canonical `SESSION` is implemented by C++/Cloud but is
+rejected by Runner; Runner never aliases it to environment variables. See the complete
 [`principal-row-scope.synapsor.sql`](../fixtures/dsl/principal-row-scope.synapsor.sql)
 example.
 
+### Migrating `FROM SESSION` for Runner
+
+Choose the provider that owns the verified identity at the Runner boundary:
+
+- local stdio or one trusted process: `FROM ENVIRONMENT`; export the named
+  values before starting Runner;
+- Streamable HTTP: `FROM HTTP_CLAIM`; configure signed JWT verification and
+  bind only verified claims;
+- Cloud embedding: `FROM CLOUD_SESSION`; use the verified Cloud session
+  supplied by the control plane; or
+- disposable development only: `FROM STATIC_DEV`.
+
+`synapsor-runner dsl validate` and `dsl compile` target Runner and fail with
+`SESSION_BINDING_UNSUPPORTED` before serving. The standalone DSL accepts the
+canonical syntax by default for other implementations; pass `--target runner`
+to request the same fail-closed Runner validation.
+
 ## Arguments and lookup
 
 ```sql

package/docs/effect-regression.md

@@ -103,6 +103,42 @@ synapsor-runner effect run \
 Dataset fixture paths are relative and cannot escape the dataset directory.
 Each result is named `<fixture_id>.result.json`.
 
+### Run an application-owned adapter
+
+For a real application harness, Runner can launch one provider-neutral command
+directly, without a shell:
+
+```bash
+synapsor-runner effect run \
+  --dataset ./effects/dataset.json \
+  --adapter node \
+  --adapter-arg ./app/effect-adapter.mjs \
+  --result-origin deterministic-application \
+  --format junit \
+  --out ./artifacts/effect-results.xml
+```
+
+Use `--result-origin external-model` when the adapter actually calls a model.
+The origin is included in text, JSON, and JUnit provenance so deterministic
+application results are not presented as model evidence.
+
+Runner starts the command with `shell: false`, a bounded argument list,
+timeout/output limits, and a minimal environment that omits ambient database
+URLs and tokens. It sets `SYNAPSOR_EFFECT_MODE=propose_only`,
+`SYNAPSOR_EFFECT_FIXTURE_PATH`, and
+`SYNAPSOR_EFFECT_SOURCE_DATABASE_CHANGED=false`. The command must emit exactly
+one canonical result JSON document to stdout.
+
+This is a process boundary, not a sandbox. Adopter-owned code can deliberately
+load its own credentials, so keep the adapter propose-only and point it at
+fixtures or an explicitly disposable source. Runner still rejects every result
+that reports source mutation.
+
+The repository's working example is
+[`examples/support-billing-agent/app/effect-adapter.mjs`](../examples/support-billing-agent/app/effect-adapter.mjs),
+and [`.github/workflows/effect-regression.yml`](https://github.com/Synapsor/Synapsor-Runner/blob/main/.github/workflows/effect-regression.yml)
+runs it and uploads JUnit output on relevant pull requests.
+
 ## Accept An Intentional Change
 
 Runner never updates a baseline during `run` or `compare`. After reviewing an
@@ -133,10 +169,11 @@ Commit the accepted fixture and review it like application code.
 ## Boundaries
 
 - This is not a general agent workflow engine.
-- This does not execute a provider command or application code.
+- Offline `--result`/`--results-dir` mode executes no provider command or
+  application code. `--adapter` explicitly executes the adopter-owned command
+  under the bounded process contract above.
 - This does not prove model quality outside the imported observations.
 - This complements [`contract test`](contract-testing.md); a contract can
   conform while an agent's proposed business effect still regresses.
 - Replay remains read-only. Creating an effect fixture does not replay or
   reapply the original write.
-

package/docs/fresh-developer-usability.md

@@ -0,0 +1,110 @@
+# Fresh-Developer Usability Protocol
+
+Use this protocol with five developers who have not previously used Synapsor.
+It is a launch gate, not an automated test. A maintainer may rehearse the
+protocol, but must not report a participant result unless that person actually
+completed the session.
+
+## Goal
+
+Measure whether a developer can connect an existing supported staging project,
+draft one disabled Safe Action with a coding agent, receive an exact Data PR,
+approve outside the agent, and find the guarded receipt without learning the
+canonical JSON or SQL-like DSL first.
+
+Measure product time separately from the initial package download. Start the
+product timer only after `synapsor-runner --version` succeeds.
+
+## Participant Setup
+
+Provide each participant with:
+
+- a fresh clone of their application or the support-plan-credit reference app;
+- Node 22.13 or newer;
+- a disposable Postgres staging database and least-privilege read/write roles;
+- exported database URLs and trusted tenant/principal values;
+- current stable Cursor, with no existing Synapsor configuration;
+- the README only. Do not give verbal product-architecture instruction.
+
+Never use production credentials or data. Record the OS, Node version, Cursor
+version, package-install method, database engine, and whether the package was
+already cached.
+
+## Tasks
+
+Ask the participant to complete these tasks without a maintainer taking control:
+
+1. Run the four-second synthetic proof and identify whether the model can call
+   `approve`, `apply`, `commit`, or raw SQL.
+2. Connect the staging project and confirm the trusted organization scope.
+3. Tell Cursor one business action to make safe and use the generated
+   `/synapsor-protect` path or exact fallback prompt.
+4. Find the disabled action file and explain why editing it does not activate a
+   tool.
+5. Open the Workbench effect preview and confirm the source row is unchanged.
+6. Explicitly activate the reviewed digest through the operator-controlled UI.
+7. Reconnect Cursor if instructed and create one proposal through the semantic
+   tool.
+8. Review the exact before/after Data PR, approve outside Cursor, and apply it.
+9. Locate the receipt/replay record and explain what happens on retry.
+10. Draft a second disabled action without changing the active tool surface.
+
+Do not rescue a participant until they have been blocked for two minutes. Record
+the exact screen, command, wording, or missing prerequisite that blocked them.
+
+## Measurements
+
+For each participant, record:
+
+| Measure | Target |
+| --- | --- |
+| Installed CLI to first own-data Data PR | under 5 minutes |
+| Installed CLI to first guarded receipt | under 8 minutes |
+| Second disabled action draft after setup | under 2 minutes |
+| Second action ready for explicit activation | under 5 minutes |
+| Handwritten canonical JSON or DSL | none on the happy path |
+| Extra CLI command after Cursor proposal call | none |
+| Unsafe authority exposed to Cursor | none |
+
+Also record every wrong turn, maintainer intervention, misunderstood trust
+boundary, and request for a model-provider key or Synapsor account.
+
+## Pass Criteria
+
+The launch gate passes only when all five participants:
+
+- complete the first Data PR without handwritten JSON or DSL;
+- correctly identify that activation, approval, and apply are outside the
+  model-facing MCP surface;
+- observe unchanged source data before approval;
+- produce one guarded receipt; and
+- expose only the intended semantic read/proposal tools in Cursor.
+
+At least four of five must meet every timing target. Any cross-tenant result,
+hidden-field exposure, pre-approval mutation, automatic activation, raw SQL
+tool, or model-visible commit authority is a release blocker regardless of
+timing.
+
+## Reporting Template
+
+Record one row per real participant:
+
+```text
+Participant:
+Date:
+Environment:
+Cold package download:
+Product timer start:
+First Data PR:
+First receipt:
+Second draft:
+Second activation-ready action:
+Interventions:
+Tool surface observed:
+Safety-boundary explanation:
+Outcome: pass | fail
+```
+
+Until five real sessions are recorded, report this gate as **owner verification
+pending**. Do not infer usability from unit tests, protocol tests, or a
+maintainer-run demo.

package/docs/getting-started-own-database.md

@@ -28,11 +28,11 @@ inspect your schema
 -> choose one table/view
 -> choose trusted scope and visible fields
 -> optionally choose proposal/writeback rules
--> generate synapsor.runner.json
+-> generate synapsor.runner.json + canonical synapsor.contract.json
 -> preview MCP tools exposed to the model
 -> run a local smoke check of the tool boundary
 -> optionally write .synapsor/smoke-input.json for one real row
--> print mcp serve and local UI commands
+-> open the secured localhost first-action workbench in an interactive terminal
 ```
 
 It does not print your database URL, put the URL in MCP client config, expose
@@ -43,6 +43,11 @@ credentials.
 `onboard db --from-env DATABASE_URL` is the same explicit path if you prefer the
 older command name in scripts.
 
+Interactive `start` opens the focused local workbench after config validation
+and an MCP boundary handshake. Use `--no-open` for CI or scripts. That handshake
+proves the reviewed tool surface; the workbench's **Test** step remains pending
+until a real scoped read is recorded in the local ledger.
+
 During the wizard, provide the optional sample object id if you know one safe
 row in the selected table. Runner writes `./.synapsor/smoke-input.json` with
 that id and prints the exact `smoke call` command. If you skip it, use
@@ -186,6 +191,95 @@ The wizard:
 - writes the generated config, `.env.example`, and MCP client snippets only
   after final confirmation.
 
+The generated action is explicit about its activation state. Read-only and
+shadow actions cannot commit. Review/writeback generation requires final
+confirmation (`--yes` in a noninteractive command) and still gives the model no
+approval or apply tool.
+
+### Draft another Safe Action with a coding agent
+
+After a reviewed read capability exists, describe one business action instead
+of hand-authoring a complete contract:
+
+```bash
+synapsor-runner start \
+  --action plan_credit \
+  --description "Propose one reviewed customer plan credit" \
+  --based-on support.inspect_customer
+```
+
+Runner writes `synapsor/actions/support.propose_plan_credit.ts` and scoped
+agent instructions. The file is an inert scaffold. It contains explicit
+authority questions for trusted scope, visible and kept-out fields, allowed
+effect, conflict guard, bounds, approval, and executor. Creating or editing it
+does not change the active contract or MCP tool list.
+
+Give the exact prompt printed by the command to Cursor or another coding
+agent. The agent may inspect project/schema evidence, complete the restricted
+TypeScript object, and run deterministic validation:
+
+```bash
+synapsor-runner action validate \
+  ./synapsor/actions/support.propose_plan_credit.ts
+```
+
+Runner statically parses rather than imports the file. A successful validation
+writes a digest-addressed **disabled draft**, a plain-language explanation,
+and exact static allow/deny/effect tests under `.synapsor/drafts/`. It cannot
+activate a tool.
+
+In the secured Workbench, run **Preview exact staging Data PR**. The preview
+may perform the reviewed scoped read and write proposal evidence to the local
+ledger, but it cannot mutate the source. Review the exact effect, type
+`ACTIVATE` plus the complete displayed digest, and confirm activation yourself.
+There is intentionally no CLI or MCP command a coding agent can use to
+activate the draft. If the host does not refresh `tools/list`, reconnect the
+MCP server after activation as the Workbench instructs.
+
+## 5. Add the reviewed tools to Cursor
+
+After setting trusted environment values, preview and install a project-scoped
+entry without hand-editing `.cursor/mcp.json`:
+
+```bash
+synapsor-runner mcp install cursor --project --dry-run \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+synapsor-runner mcp install cursor --project --yes \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+synapsor-runner mcp status cursor --project --check-launch
+```
+
+Runner merges rather than replaces existing MCP servers, creates a backup,
+records an integrity marker, and is idempotent. The entry uses an exact Runner
+version and contains no database URL, trusted tenant/principal value, approval,
+apply, or revert authority. Remove only the Runner-owned entry with:
+
+```bash
+synapsor-runner mcp uninstall cursor --project --yes
+```
+
+See the [host compatibility matrix](host-compatibility.md) for the precise
+Cursor evidence and MCP Apps limitation.
+
+## 6. Inspect local activation evidence
+
+Runner records bounded timing milestones locally. It does not transmit them:
+
+```bash
+synapsor-runner activation show \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+synapsor-runner activation export \
+  --out ./.synapsor/activation-report.json
+```
+
+Product activation time begins after package installation; initial npm
+resolution/download/cache time is measured separately when evaluating cold
+`npx` behavior. The report contains milestone timing/status only, not source
+rows, object IDs, tenant IDs, credentials, or project paths.
+
 For proposal modes, the current runner supports explicit field-update mappings such as:
 
 ```text
@@ -426,7 +520,7 @@ MCP client:
 ```bash
 export SYNAPSOR_TENANT_ID="acme"
 export SYNAPSOR_PRINCIPAL="local_operator"
-export SYNAPSOR_RUNNER_HTTP_TOKEN="dev-local-token"
+export SYNAPSOR_RUNNER_HTTP_TOKEN="$(node -e 'process.stdout.write(require("node:crypto").randomBytes(32).toString("base64url"))')"
 
 npx -y -p @synapsor/runner synapsor-runner up --serve \
   --config ./synapsor.runner.json \
@@ -449,9 +543,12 @@ npx -y -p @synapsor/runner synapsor-runner mcp serve-streamable-http \
 ```
 
 Streamable HTTP defaults to `127.0.0.1:8766` and requires bearer auth by
-default. Use private networking/TLS before exposing it beyond localhost. See
+default. A non-loopback listener refuses to start until direct TLS, an explicitly
+trusted TLS proxy, or authenticated emergency break glass is selected. Shared
+services use signed per-session identity rather than one endpoint token. See
 [HTTP MCP](http-mcp.md). If you want the smaller JSON-RPC bridge instead, use
-`synapsor-runner mcp serve-http`.
+`synapsor-runner mcp serve-http`; it is not suitable for claim-bound shared MCP
+sessions.
 
 The model-facing MCP server exposes semantic tools such as:
 

package/docs/guarded-crud-writeback.md

@@ -27,13 +27,22 @@ does not fit either direct boundary.
 
 | Operation | Required source guard | Direct-write behavior |
 | --- | --- | --- |
-| `UPDATE` | Primary key, trusted tenant, exact version/conflict column | Patches only allowlisted columns and affects exactly one row. In Runner-ledger mode, the version must advance in the same source transaction. |
+| `UPDATE` | Primary key, trusted tenant, and normally an exact version/conflict column | Patches only allowlisted columns and affects exactly one row. In Runner-ledger mode, the exact version must advance in the same source transaction. |
 | `INSERT` | Source `PRIMARY KEY` or `UNIQUE` constraint over the reviewed dedup identity | Runner injects tenant and proposal-derived identity values, inserts only allowlisted fields, and requires exactly one row. |
 | `DELETE` | Primary key, trusted tenant, exact version column | Deletes exactly one reviewed row. Hard delete requires human/operator approval and is refused when Runner detects write triggers or widening cascades. Prefer soft delete as guarded `UPDATE`. |
 
 Existing proposal capabilities with no `operation` field continue to mean
 single-row `UPDATE`.
 
+DSL authoring requires `CONFLICT GUARD <column>` for UPDATE and never silently
+chooses weak semantics. A narrow legacy single-row, non-reversible UPDATE using
+source-DB receipt authority may explicitly declare
+`CONFLICT GUARD WEAK ROW HASH ACKNOWLEDGED`. That mode hashes only the captured
+projection and may miss concurrent changes outside it. It is prominently
+reported by lint/explain/doctor/preview and is unavailable for Runner-ledger,
+DELETE, reversibility, or bounded sets. Treat it as a compatibility escape
+hatch, not equivalent protection.
+
 ## Receipt authority
 
 Receipt authority and source-table provisioning are separate decisions:

package/docs/host-compatibility.md

@@ -0,0 +1,59 @@
+# MCP Host Compatibility
+
+This matrix separates host evidence from protocol evidence. It was last
+reviewed on 2026-07-20. A working MCP SDK handshake is not presented as proof
+that a specific editor renders an extension or protects app-only controls.
+
+| Host/surface | Status | Evidence and boundary |
+| --- | --- | --- |
+| Cursor project `.cursor/mcp.json` lifecycle | Tested | Runner install/status/uninstall tests cover preview, merge, backup, idempotency, ownership, tamper refusal, paths with spaces, and exact-version `npx` wiring. Local Cursor version observed: 3.7.21 (`517f696d8ab6c53eb04fbfdaae705cd146bf3460`, x64). |
+| Cursor stdio Runner launch and `tools/list` | Protocol-tested | `mcp status cursor --project --check-launch` executes the generated command and checks the exact reviewed tools through the official MCP client transport. A final manual Cursor UI pass is still required for a release claim tied to that host version. |
+| Cursor MCP Apps inline proposal card | Unknown | Runner advertises the standard display-only resource metadata, but current stable Cursor rendering and app-only authority guarantees have not been reproduced. Use the secured localhost workbench or operator CLI. |
+| Cursor approval/apply/revert through MCP | Unsupported | Intentionally absent. Cursor may auto-run model-facing tools; commit authority therefore stays outside MCP regardless of host settings. |
+| Generic Add to Cursor deep link | Unsupported | Runner does not generate a link because no current documented generic server payload has been verified end to end. Project install is the supported path. |
+| Generic stdio MCP client | Protocol-tested | Official MCP SDK initialization, tool listing, calls, resources, and display-only Apps metadata are covered in the suite. |
+| Generic Streamable HTTP MCP client | Protocol-tested | Official MCP SDK sessions, signed context, secret rotation, JWKS, mTLS, aliases, and session isolation are covered. |
+| Claude Desktop | Protocol-tested | Packaged stdio configuration and MCP transport are tested; manual host UI behavior varies by version and remains a release checklist item. |
+| Claude Code | Configuration-tested and protocol-tested | Claude Code 2.1.216 accepted the secret-free stdio configuration through `mcp add-json`; the same command completed MCP `tools/list`. A manual model-driven proposal call remains a release gate. |
+| Codex | Configuration-tested and protocol-tested | Codex CLI 0.144.6 accepted the secret-free stdio configuration through `codex mcp add`; the same command completed MCP `tools/list`. A manual model-driven proposal call remains a release gate. |
+| VS Code | Protocol-tested | The checked `.vscode/mcp.json` shape is parsed and the same stdio command completes MCP `tools/list`; manual editor UI behavior is not claimed. |
+| OpenAI Agents SDK | Recipe-checked and protocol-tested | Packaged stdio/Streamable HTTP examples are syntax/safety checked and OpenAI-safe aliases are protocol-tested. The exact SDK agent call remains protocol-only until run with an owner-supplied API key. |
+| LangChain/LangGraph | Recipe-checked, protocol-only | The current `@langchain/mcp-adapters` recipe lists tools, rejects unsafe authority, and calls the proposal tool. The framework runtime has not been executed in this release environment. |
+| Google ADK | Recipe-checked, protocol-only | The current `McpToolset`/`StdioConnectionParams` recipe exposes only the two reviewed tools. The framework runtime has not been executed in this release environment. |
+| LlamaIndex | Recipe-checked, protocol-only | The current `BasicMCPClient` recipe lists tools and calls the proposal tool. The framework runtime has not been executed in this release environment. |
+
+## Cursor Project Setup
+
+Current Cursor documentation supports project MCP configuration in
+`.cursor/mcp.json`. Runner manages only its `synapsor` entry:
+
+```bash
+synapsor-runner mcp install cursor --project --dry-run
+synapsor-runner mcp install cursor --project --yes
+synapsor-runner mcp status cursor --project --check-launch
+```
+
+The generated entry contains command paths only. Database credentials and
+trusted tenant/principal values must come from the environment that launches
+Runner. Other Cursor MCP servers and settings are preserved.
+
+Primary references:
+
+- [Cursor MCP documentation](https://cursor.com/docs/context/mcp)
+- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
+- [MCP Apps specification](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx)
+
+All adjacent-host source links, runnable snippets, shared proposal input, and
+verification commands are in [Client And Framework Recipes](client-recipes.md).
+
+## Authority Fallback
+
+Hosts without a verified app-only human-control boundary receive the same
+structured/text proposal result and can open the secured loopback workbench.
+Approval, rejection, apply, compensation, policy activation, trusted identity,
+and credentials never enter model-visible `tools/list`. Runner does not infer
+host safety from a product name or user-agent string.
+
+Runner currently exposes tools, not MCP prompts or an elicitation-based
+approval flow. First-run setup and approval do not depend on optional host
+prompt/elicitation support.