@synapsor/runner 1.5.0 → 1.5.4

package/docs/release-notes.md

@@ -10,7 +10,134 @@ npx -y -p @synapsor/runner synapsor-runner demo --quick
 The OSS runner command is `synapsor-runner`. The `synapsor` command is reserved
 for the Synapsor Cloud CLI.
 
-## 1.5.0 (prepared, not published)
+## 1.5.4 (prepared, not published)
+
+### Networked MCP authentication hardening
+
+- Local stdio still opens no network listener and needs no HTTP credential.
+  Loopback HTTP remains authenticated by default with an operator-provisioned
+  opaque token.
+- Remote HTTP now refuses to bind over an undeclared cleartext channel. Operators
+  must use Runner-owned TLS, explicitly declare a trusted TLS proxy, or select an
+  authenticated and prominently diagnosed break-glass posture.
+- Opaque endpoint tokens are constrained to local or explicit single-tenant use.
+  Remote use requires adequate entropy; one active and one previous env-provided
+  value support bounded rotation without logging either value.
+- Shared deployments require signed per-session identity and `http_claims`
+  trusted context. Runner revalidates issuer, audience/resource, time, scope,
+  tenant, principal, signature, and algorithm on every request and rejects token
+  or identity swaps inside an MCP session.
+- RFC 9728 protected-resource metadata and Bearer challenges let compatible MCP
+  clients discover the configured external authorization server. Runner verifies
+  access tokens but does not implement user login or token issuance.
+- TLS/mTLS preflight, public-only bounded JWKS handling, exact Origin/Host checks,
+  request/session bounds, doctor diagnostics, client recipes, and fleet examples
+  now share one documented deployment ladder.
+- `lifecycle`, `lifecycle show`, and `lifecycle show latest` now inspect the
+  newest complete proposal lifecycle without an id. Filters and known
+  proposal/evidence/replay/job/intent/receipt/audit handles resolve a stable,
+  read-only `synapsor.lifecycle-view.v1` domain document across local SQLite
+  and shared PostgreSQL runtime stores.
+- DSL UPDATE authoring now requires an exact `CONFLICT GUARD <column>` instead
+  of silently choosing projection hashing. A reviewer-visible weak compatibility
+  clause remains only for ordinary single-row source-DB UPDATE and is rejected
+  for the stronger operation modes.
+- Runner rejects canonical `FROM SESSION` with
+  `SESSION_BINDING_UNSUPPORTED` rather than treating its key as a process
+  environment variable. Explicit ENVIRONMENT, verified HTTP_CLAIM, verified
+  CLOUD_SESSION, and STATIC_DEV behavior remains distinct.
+
+Prepared package versions: `@synapsor/runner@1.5.4` and
+`@synapsor/dsl@1.4.4`. `@synapsor/spec@1.4.2` and the Cloud CLI are
+unchanged. Nothing has been published by this repository change.
+
+## 1.5.3 (published 2026-07-21)
+
+### Intent to Safe Action
+
+- `start --action <name> --description <intent>` creates one inert TypeScript
+  Safe Action scaffold from an existing reviewed read boundary. Project-scoped
+  instructions let a coding agent complete and validate only the draft.
+- `action validate` statically parses the restricted object and emits a
+  digest-addressed disabled canonical draft, explanation, and deterministic
+  allow/deny/effect tests. It does not import adopter code, activate the action,
+  or alter the active MCP tool catalog.
+- The secured Workbench runs one real source-unchanged staging Data PR before
+  activation and requires `ACTIVATE` plus the complete digest. Cloud-linked
+  projects use governed Cloud activation. Existing proposals remain bound to
+  the exact active contract digest they were created under.
+- The package includes a current-format Cursor plugin with
+  `/synapsor-protect`, diagnostics, deterministic package verification, and
+  project-safe MCP wiring. Cursor host claims remain evidence-labeled; a stable
+  UI pass and Marketplace submission are owner gates.
+- MCP audit now renders a model-authority map and opt-in bypass evidence as
+  text, JSON, Markdown, or SARIF. A checked-in GitHub Actions workflow and Safe
+  Action team CI are deterministic and non-mutating.
+- Proposal-only integration recipes cover Claude Code, Codex, VS Code, OpenAI
+  Agents, LangChain/LangGraph, Google ADK, LlamaIndex, and generic MCP clients.
+- The first two README screens, public website, article, discovery routes, and
+  36-second evidence-backed demo now lead with the own-project Data PR path.
+
+Published package version: `@synapsor/runner@1.5.3`. Spec, DSL, and Cloud CLI
+packages were unchanged.
+
+## 1.5.2 (prepared, not published)
+
+### First safe action in an existing application
+
+- `start --from-env DATABASE_URL` and
+  `try --prove --from-env DATABASE_URL` now converge on one own-data
+  onboarding path. It inspects a staging database read-only, asks the developer
+  to choose trusted scope and one reviewed action, emits canonical files, and
+  never substitutes synthetic data after an own-data failure.
+- The localhost workbench presents Project, Data source, Trust scope, Action,
+  Agent, Test, and Review plus an exact proposal Data PR. Test is complete only
+  after a scoped tool call records query audit, not after config validation.
+- Project-scoped Cursor install/status/uninstall previews and owns only its MCP
+  entry, preserves other entries, and launches the exact Runner version.
+  Approval, apply, revert, credentials, and trusted identity stay outside MCP.
+- Local activation reports measure proof, onboarding, Cursor, first read, and
+  first proposal without telemetry or business identifiers. Product time
+  excludes initial package download; cold `npx` time is reported separately
+  as an observed environment-specific measurement.
+- Optional TypeScript authoring emits the same canonical Spec contract. Shadow
+  trust progression and provider-neutral effect regression remain
+  non-activating and preserve deterministic/external-model provenance.
+- MCP audit candidates can open directly in the secured workbench, and the
+  release includes the host-compatibility matrix and support/billing reference
+  workflow.
+- The package now requires Node 22.13.0 or newer, the first Node 22 release
+  where Runner's `node:sqlite` dependency is available without an experimental
+  runtime flag. Older Node versions fail immediately with an actionable error.
+
+Prepared package version: `@synapsor/runner@1.5.2`. Spec, DSL, and Cloud CLI
+packages are unchanged. Nothing has been published by this repository change.
+
+## 1.5.1 (prepared, not published)
+
+### Safe disposable state ownership
+
+- `try --state-dir` no longer treats the supplied directory as disposable.
+  The supplied path is a caller-owned container and Runner uses a marked
+  managed child beneath it.
+- Cleanup removes only known direct try-state files. Unrelated files remain in
+  place, and roots, home/cwd/repository paths, traversal, symlink escapes,
+  unmarked lookalikes, and linked managed files fail closed.
+- An atomic state lease prevents concurrent runs from corrupting each other and
+  permits recovery from a valid lease whose process is no longer alive.
+- `demo inspect --state-dir` resolves the same managed child. The default
+  `.synapsor/try` path safely adopts only the recognized legacy file layout.
+- Explicit `--force` replacement of generated schema and MCP-audit candidate
+  directories now rejects protected paths, symlinked ancestors, and linked or
+  invalid ownership markers.
+- The embedded `try` data source is consistently identified as synthetic.
+- The packaged YAML parser is updated to `2.8.3` to include the upstream fix
+  for deeply nested collection denial of service.
+
+Prepared package version: `@synapsor/runner@1.5.1`. Spec, DSL, and Cloud CLI
+packages are unchanged. Nothing has been published by this repository change.
+
+## 1.5.0 (published 2026-07-20)
 
 ### Complete guarded-action developer proof
 
@@ -45,8 +172,8 @@ for the Synapsor Cloud CLI.
   immediately second, and distinguishes application scope, PostgreSQL RLS, and
   tenant-bound isolation without overstating any of them.
 
-Prepared package version: `@synapsor/runner@1.5.0`. Spec, DSL, and Cloud CLI
-packages are unchanged. Nothing has been published by this repository change.
+Published package version: `@synapsor/runner@1.5.0`. Spec, DSL, and Cloud CLI
+packages were unchanged.
 
 ## 1.4.123 (2026-07-17)
 
@@ -744,7 +871,7 @@ not change and must not be republished for this release.
   CDC, managed runner fleets, compliance exports, production SLA, or C++ DBMS
   internals.
 - The local store is single-node SQLite for local/dev/staging usage.
-- Node >= 22.5.0 is required because the local ledger uses Node's
+- Node >= 22.13.0 is required because the local ledger uses Node's unflagged
   `node:sqlite` runtime. Use a supported Node runtime or the Docker-backed
   source demo path.
 

package/docs/runner-bundles.md

@@ -67,8 +67,13 @@ npx -y -p @synapsor/runner synapsor-runner cloud sync latest \
 
 For the OpenAI Agents SDK, use the included TypeScript examples. Their stdio
 command enables `--alias-mode openai`; the Streamable HTTP example includes the
-matching server command. Claude, Cursor, and generic templates use canonical
-dotted capability names.
+matching server command and reads its Bearer credential from
+`SYNAPSOR_RUNNER_HTTP_TOKEN`. The generic HTTP template uses the same environment
+reference. Neither file embeds a credential value. An operator generates and
+provisions the opaque token to the Runner process and authorized client; use a
+signed identity-provider token instead for shared multi-user deployments. See
+[HTTP MCP](http-mcp.md). Claude, Cursor, and generic stdio templates use
+canonical dotted capability names and need no HTTP credential.
 
 Approval and writeback remain outside the model-facing MCP tool surface. Use
 `proposals`, `apply`, `receipts`, and `replay` from a trusted operator shell.

package/docs/runner-config-reference.md

@@ -36,6 +36,7 @@ Unknown keys fail when `strict` is true (the default).
 | `approvals` | No | Local approval overrides. |
 | `operator_identity` | No | Verified operator identity and apply-role wiring for approve/reject/apply. |
 | `session_auth` | HTTP claims | HS256 development or asymmetric RS256/ES256 session-token verification. |
+| `http_security` | Networked HTTP | Deployment profile, protected channel, endpoint-token env names, OAuth protected-resource metadata, exact Origin/Host policy, and request/session bounds. |
 | `rate_limits` | No | Operational fixed-window limits; fleet-wide only with shared `runtime_store`. |
 | `metrics` | No | Separately authorized scrapeable HTTP metrics. Disabled by default. |
 | `graduated_trust` | No | Off-by-default, operator-only policy recommendation criteria and kill switch. |
@@ -212,8 +213,16 @@ Providers are `environment`, `static_dev`, `http_claims`, and `cloud_session`.
 Capabilities may reference a context by name. The model never receives tenant
 or principal as an overridable argument.
 
-For multi-tenant Streamable HTTP services, use `http_claims` plus signed
-session auth:
+The language-neutral canonical contract can preserve a `session` binding for
+implementations such as C++/Cloud that own a typed session boundary. Runner has
+no generic web-session provider and rejects it with
+`SESSION_BINDING_UNSUPPORTED`; it never treats the key as an environment
+variable. Use `environment` for local stdio, verified `http_claims` for shared
+Streamable HTTP, or verified `cloud_session` for Cloud embedding.
+
+For controlled loopback development, `http_claims` can use an HS256 session
+token. Runner holds the symmetric signing/verification secret in this mode, so
+it is not the recommended shared production profile:
 
 ```json
 {
@@ -229,7 +238,7 @@ session auth:
     "secret_env": "SYNAPSOR_SESSION_JWT_SECRET",
     "previous_secret_env": "SYNAPSOR_PREVIOUS_SESSION_JWT_SECRET",
     "issuer": "https://identity.example",
-    "audience": "synapsor-runner"
+    "audience": "https://runner.example/mcp"
   }
 }
 ```
@@ -239,16 +248,24 @@ the active secret first, then the previous secret. Existing MCP sessions remain
 bound to the exact token fingerprint, so clients cannot swap tenant/principal
 identity inside an initialized session.
 
-For networked deployments prefer asymmetric public-key verification:
+For a shared networked deployment, use asymmetric public-key verification and
+declare the protected resource and channel explicitly:
 
 ```json
 {
+  "trusted_context": {
+    "provider": "http_claims",
+    "values": {
+      "tenant_id_key": "tenant_id",
+      "principal_key": "sub"
+    }
+  },
   "session_auth": {
     "provider": "jwt_asymmetric",
-    "algorithms": ["RS256"],
+    "algorithms": ["RS256", "ES256"],
     "jwks_url_env": "SYNAPSOR_SESSION_JWKS_URL",
     "issuer": "https://identity.example",
-    "audience": "synapsor-runner",
+    "audience": "https://runner.example/mcp",
     "tenant_claim": "tenant_id",
     "principal_claim": "sub",
     "clock_skew_seconds": 30,
@@ -256,6 +273,19 @@ For networked deployments prefer asymmetric public-key verification:
     "jwks_cooldown_seconds": 30,
     "fetch_timeout_ms": 3000,
     "max_response_bytes": 1048576
+  },
+  "http_security": {
+    "deployment": "shared",
+    "channel": "trusted_tls_proxy",
+    "oauth_resource": {
+      "resource": "https://runner.example/mcp",
+      "authorization_servers": ["https://identity.example"],
+      "scopes_supported": ["synapsor:mcp"],
+      "required_scopes": ["synapsor:mcp"],
+      "resource_name": "Synapsor Runner"
+    },
+    "allowed_origins": ["https://agent-console.example"],
+    "allowed_hosts": ["runner.example"]
   }
 }
 ```
@@ -268,6 +298,66 @@ rejected. Every effective named context in an `http_claims` server must bind
 tenant and principal from claims; environment/static contradictions fail with
 `TRUSTED_CONTEXT_PROVIDER_CONFLICT` before serving.
 
+`session_auth` verifies identity; it does not issue access tokens. The external
+identity provider identified by `issuer` issues a short-lived token whose
+audience is the exact protected-resource URL. Runner fetches only public JWKS
+material and validates the configured claims on every request. Required OAuth
+scopes are declared under `http_security.oauth_resource`.
+
+## HTTP security
+
+`http_security` is Runner deployment wiring, not part of a portable contract:
+
+```json
+{
+  "http_security": {
+    "deployment": "single_tenant",
+    "channel": "trusted_tls_proxy",
+    "static_token": {
+      "active_env": "SYNAPSOR_RUNNER_HTTP_TOKEN",
+      "previous_env": "SYNAPSOR_RUNNER_HTTP_TOKEN_PREVIOUS"
+    },
+    "allowed_origins": ["https://agent-console.example"],
+    "allowed_hosts": ["runner.internal.example"],
+    "limits": {
+      "max_request_bytes": 65536,
+      "max_header_bytes": 8192,
+      "max_sessions": 500,
+      "session_idle_timeout_seconds": 300,
+      "request_timeout_ms": 15000,
+      "headers_timeout_ms": 5000,
+      "keep_alive_timeout_ms": 5000,
+      "max_connections": 1000
+    }
+  }
+}
+```
+
+- `deployment` is `loopback`, `single_tenant`, or `shared`. Shared requires
+  verified signed `http_claims`, exact issuer/audience, and RFC 9728
+  `oauth_resource` metadata.
+- `channel` is `direct_tls`, `trusted_tls_proxy`, or the explicitly unsafe
+  `insecure_http_break_glass`. A non-loopback listener without one refuses to
+  bind. Break glass remains authenticated.
+- `static_token` names one active and optionally one previous environment
+  variable. It is opaque service access for loopback/single-tenant use, not
+  tenant identity. Values never belong in config.
+- `oauth_resource.resource` is the exact HTTPS MCP endpoint and must equal
+  `session_auth.audience`. `authorization_servers` names external issuers;
+  Runner does not implement login or token refresh.
+- `allowed_origins` contains exact browser origins; an omitted browser Origin
+  remains valid for native clients. Wildcards are forbidden.
+- `allowed_hosts` contains exact direct/public Host authorities. Forwarded Host
+  and forwarded identity headers are not trusted automatically.
+- `limits` bounds bodies, headers, concurrent sessions/connections, idle
+  sessions, and HTTP timing. Defaults are documented in [HTTP MCP](http-mcp.md).
+
+Runner-owned TLS certificate, key, and optional client-CA PEM values are passed
+by environment references on the serve command (`--tls-cert-env`,
+`--tls-key-env`, `--tls-ca-env`, `--require-client-cert`). Private TLS material
+does not go in this JSON file. A trusted-proxy channel assumes firewall/private
+network controls prevent clients from bypassing that proxy.
+
 ## Contracts and embedded capabilities
 
 ```json

package/docs/running-a-runner-fleet.md

@@ -1,6 +1,6 @@
 # Running A Small Runner Fleet
 
-Synapsor Runner 1.1 supports a bounded small-fleet deployment. It does not
+Synapsor Runner supports a bounded small-fleet deployment. It does not
 turn the OSS package into Synapsor Cloud and it does not promise an unbounded,
 multi-region, or SLA-backed control plane.
 
@@ -32,7 +32,7 @@ model-facing approval/apply tools as blockers. Audit is a static review, not a
 security proof; follow it with `tools preview`, `doctor`, and the live fleet
 verification.
 
-## What 1.1 Guarantees
+## What The Bounded Fleet Guarantees
 
 With `storage.shared_postgres.mode = "runtime_store"`:
 
@@ -116,7 +116,7 @@ Use asymmetric verification for a networked fleet:
     "algorithms": ["RS256"],
     "jwks_url_env": "SYNAPSOR_SESSION_JWKS_URL",
     "issuer": "https://identity.example",
-    "audience": "synapsor-runner",
+    "audience": "https://runner.example/mcp",
     "tenant_claim": "tenant_id",
     "principal_claim": "sub",
     "clock_skew_seconds": 30,
@@ -124,10 +124,28 @@ Use asymmetric verification for a networked fleet:
     "jwks_cooldown_seconds": 30,
     "fetch_timeout_ms": 3000,
     "max_response_bytes": 1048576
+  },
+  "http_security": {
+    "deployment": "shared",
+    "channel": "trusted_tls_proxy",
+    "oauth_resource": {
+      "resource": "https://runner.example/mcp",
+      "authorization_servers": ["https://identity.example"],
+      "scopes_supported": ["synapsor:mcp"],
+      "required_scopes": ["synapsor:mcp"]
+    },
+    "allowed_hosts": ["runner.example"],
+    "allowed_origins": ["https://agent-console.example"]
   }
 }
 ```
 
+The external identity provider issues the short-lived client JWT for resource
+`https://runner.example/mcp`; Runner only verifies it. The load balancer must
+terminate TLS and prevent direct access to the private Runner listeners. If
+Runner owns TLS instead, use protected certificate/key env references and set
+`channel` to `direct_tls`.
+
 Every served capability context must bind tenant and principal from
 `HTTP_CLAIM`. Runner rejects an environment-bound contract mixed into this
 server with `TRUSTED_CONTEXT_PROVIDER_CONFLICT` before tools are served.
@@ -147,6 +165,12 @@ material. Unknown `kid` triggers at most one controlled refresh. For offline
 deployments, configure one public PEM through `public_key_env` or
 `public_key_path`; never place a private key in Runner config.
 
+Runner publishes RFC 9728 protected-resource metadata at the path derived from
+the public resource and returns scope-aware Bearer challenges. The identity
+provider, not Runner, owns user login, client registration, token issuance, and
+refresh. An MCP session ID is only protocol state; every request is
+reauthenticated and remains pinned to the initialized credential identity.
+
 ## Ledger And Source Pools
 
 ```json
@@ -329,12 +353,13 @@ configured handler timeout. A hard kill is recoverable through leases and
 source-side idempotency receipts, but should remain an incident signal.
 
 Rotate JWKS keys by publishing the new `kid`, waiting at least the configured
-cache lifetime, switching issuers, then retiring the old key. Rotate metrics,
-handler, database, and ledger credentials independently through their named
-environment variables.
+cache lifetime while issuers sign with the new key, then retiring the old key.
+Do not casually change the issuer or protected-resource audience during a key
+rotation. Rotate TLS/mTLS, metrics, handler, database, and ledger credentials
+independently through their named environment variables.
 
-Only homogeneous Runner 1.1 instances are verified by `test:fleet`. Mixed
-1.0/1.1 operation is not claimed. For rolling upgrades:
+Only homogeneous Runner instances at the release under test are verified by
+`test:fleet`. Mixed-version operation is not claimed. For rolling upgrades:
 
 1. back up and verify the ledger;
 2. run schema/config validation with the target version;
@@ -351,8 +376,12 @@ roll back the full fleet. Never mix versions merely because both are `1.x`.
 
 ## TLS Boundary
 
-Terminate public TLS or mTLS at a trusted load balancer, or configure Runner's
-tested TLS/mTLS options directly. Keep Runner-to-database TLS verification on,
-use private networking where possible, restrict `/metrics`, and never forward
-untrusted identity headers as claims. The bearer JWT itself, not a proxy-added
-tenant header, is the session authority.
+Terminate public TLS or mTLS at a trusted load balancer and declare
+`channel: trusted_tls_proxy`, or configure Runner's tested TLS/mTLS options
+directly. A proxy declaration is a security assertion: firewall the private
+listener so clients cannot bypass the proxy, protect the private hop, and
+preserve an allowed Host. Keep Runner-to-database TLS verification on, use
+private networking where possible, and restrict `/metrics` separately. The
+verified Bearer JWT itself, not a proxy-added tenant/principal header, is the
+session authority. See [HTTP MCP](http-mcp.md) for channel flags, limits, and
+doctor checks.

package/docs/security-boundary.md

@@ -36,19 +36,55 @@ The model does not receive:
 - a generic `execute_sql` tool;
 - arbitrary table, schema, or column names;
 - database URLs or credentials;
+- contract activation tools;
 - approval tools;
 - commit/writeback tools;
+- MCP endpoint tokens, JWTs, refresh tokens, client secrets, or TLS keys;
 - trusted tenant or principal authority as ordinary model arguments.
 
+## Network transport and identity
+
+Local stdio is the preferred one-client path. The MCP client launches Runner and
+communicates over the child process's standard input/output, so Runner opens no
+network listener and HTTP authentication does not apply.
+
+A listening HTTP endpoint has no inherent client identity. Runner therefore
+requires Bearer authentication by default. On loopback or an explicitly
+single-tenant service, Bearer may carry one high-entropy opaque endpoint token;
+that token only answers "may this service call the endpoint?" and is not a user
+or tenant identity. Shared services require signed per-session JWTs, preferably
+RS256/ES256 from an external identity provider, with exact issuer,
+audience/resource, time, scope, tenant, and principal validation on every
+request. An MCP session ID only routes protocol state and never authenticates a
+caller.
+
+Non-loopback HTTP refuses to bind unless Runner owns TLS, an explicitly trusted
+TLS proxy protects the public and private hops, or an authenticated emergency
+cleartext break-glass mode is selected. TLS protects the channel; mTLS also
+authenticates a workload certificate but does not replace per-user/tenant claims
+in a shared service. Exact Origin and Host policy, request/session limits, and
+credential-pinned MCP sessions narrow browser, DNS-rebinding, exhaustion, and
+session-swap attacks.
+
+These controls remain independent: transport authentication permits endpoint
+access; verified session claims provide tenant/principal context; the contract
+authorizes semantic capabilities; database roles/RLS constrain the connection;
+operator identity authorizes activation, approval, apply, reconcile, and
+revert. See [HTTP MCP](http-mcp.md).
+
 Reviewed aggregate tools expose one scalar only. Their function, column,
 tenant key, optional equality selection, and minimum-group threshold are fixed
 in the contract; the model receives no predicate arguments or member rows.
 Suppression reduces single-record inference but does not replace statistical
 privacy review. See [Bounded Aggregate Reads](aggregate-reads.md).
 
-Trusted context comes from local configuration, environment bindings, or Cloud
-session context in Cloud mode. Tenant, principal, and authorization scope must
-not be accepted from the model as authority.
+Trusted context comes from operator-controlled process bindings for local or
+explicitly single-tenant use, verified signed HTTP claims for a shared service,
+or verified Cloud session context in Cloud mode. Tenant, principal, and
+authorization scope must not be accepted from the model as authority.
+Canonical `SESSION` content is rejected by Runner with
+`SESSION_BINDING_UNSUPPORTED`; Runner never aliases it to environment values,
+arbitrary headers, MCP metadata, or model arguments.
 
 With a shared credential, these checks are application-level enforcement and
 depend on Runner's fixed predicate implementation. Optional PostgreSQL RLS mode
@@ -84,6 +120,18 @@ explicit host-level administrative boundary.
 Proposal tools read the current row through the read credential, store evidence
 and an exact before/after diff, and leave the source database unchanged.
 
+Code-first Safe Actions do not create authority when a file is edited. Runner
+parses the restricted TypeScript object without importing or executing it,
+compiles it into a digest-addressed disabled canonical draft, and keeps the
+active contract pointer unchanged. Activation is available only in the
+session-token/CSRF-protected localhost Workbench after a matching real staging
+proposal proves `source_database_changed:false`; the operator must confirm the
+complete digest. A proposal remains pinned to the active contract digest it was
+created under, so later activation cannot reinterpret an old approval. Cloud-
+linked projects route activation through Cloud governance instead of the local
+control. No model-facing MCP tool can validate-and-activate, approve, apply, or
+revert.
+
 The local proposal store rejects obvious credential material before persistence:
 database URLs, bearer tokens, Synapsor runner tokens, private-key blocks, and
 secret-like fields such as password, token, API key, private key, cookie,
@@ -145,11 +193,13 @@ database identifiers such as `../private`, `id/../../tenant_id`, or
 `status; DROP TABLE tickets` before adapter execution. Local CLI file paths
 remain explicit user-provided paths; they are not model-facing authority.
 
-Local review can happen through the CLI or `synapsor-runner ui`. The UI is a localhost
-review surface with a per-run session token and CSRF protection for
-approve/reject actions. It does not expose raw SQL, database URLs, write
-credentials, approval tools, commit tools, or controls that widen reviewed
-tables/columns.
+Local review can happen through the CLI or `synapsor-runner ui`. The UI is a
+localhost review surface with a per-run session token and CSRF protection for
+approve/reject and Safe Action draft controls. Activation additionally requires
+a matching source-unchanged preview plus the complete digest. These operator
+controls are not MCP tools. The UI does not expose raw SQL, database URLs, or
+write credentials, and it does not let a model widen reviewed tables, columns,
+scope, policy, or executor authority.
 
 Contract lint and tests are review aids rather than a proof of complete
 security. Capability breadth can still drift as narrow tools accumulate;

package/docs/shadow-studies.md

@@ -142,6 +142,41 @@ synapsor-runner shadow outcome import \
   --store ./.synapsor/local.db
 ```
 
+For the normal application path, record the trusted outcome directly instead
+of assembling JSONL. `@synapsor/runner/shadow` writes through the same scope,
+effect-shape, and secret checks as the import command:
+
+```js
+import { createShadowOutcomeRecorder } from "@synapsor/runner/shadow";
+
+const recorder = createShadowOutcomeRecorder({
+  storePath: "./.synapsor/local.db",
+  studyId: "sst_support_pilot",
+  actor: "support_application",
+  source: "support-audit-log",
+});
+
+try {
+  recorder.record({
+    requestId: "request_123",
+    tenantId: "acme",
+    businessObject: "invoice",
+    objectId: "INV-3001",
+    disposition: "applied",
+    actualEffect: {
+      before: { late_fee_cents: 5500 },
+      after: { late_fee_cents: 0 },
+      patch: { late_fee_cents: 0 },
+    },
+  });
+} finally {
+  recorder.close();
+}
+```
+
+The application owns the truth of this outcome. The helper does not read or
+mutate the source database and cannot approve a shadow proposal.
+
 ## Review The Report
 
 ```bash
@@ -161,6 +196,16 @@ denial, unable-to-propose, stale/conflict, unmatched, and unsafe-scope cases.
 It also includes amount distributions, capability/reason breakdowns, and
 risk-ranked disagreements.
 
+The report also shows the explicit trust progression:
+
+```text
+Observe -> Compare -> Manual review -> Suggested bounded policy
+```
+
+It reports an insufficient sample size until the minimum comparable evidence
+exists. A suggested policy remains an inactive review artifact; the report
+never widens or activates the contract.
+
 Close a completed study:
 
 ```bash
@@ -187,10 +232,8 @@ synapsor-runner shadow case import \
   --input ./examples/support-billing-agent/shadow-study/cases.jsonl \
   --store ./.synapsor/shadow-reference.db
 
-synapsor-runner shadow outcome import \
-  --study sst_support_reference \
-  --input ./examples/support-billing-agent/shadow-study/outcomes.jsonl \
-  --store ./.synapsor/shadow-reference.db
+node ./examples/support-billing-agent/app/record-shadow-outcomes.mjs \
+  ./.synapsor/shadow-reference.db sst_support_reference
 
 synapsor-runner shadow report \
   --study sst_support_reference \