@synapsor/runner 1.5.3 → 1.5.4

package/dist/shadow.mjs

@@ -1908,6 +1908,11 @@ var ProposalStore = class {
     const rows = this.db.prepare(query.sql).all(...query.params);
     return rows.map((row) => rowToProposal(row)).filter((proposal) => proposal !== void 0);
   }
+  countProposals(filters = {}) {
+    const query = buildProposalCountQuery(filters);
+    const row = this.db.prepare(query.sql).get(...query.params);
+    return isRecord(row) ? Number(row.count ?? 0) : 0;
+  }
   listEvidenceBundles(filters = {}) {
     const query = buildEvidenceQuery(filters);
     const rows = this.db.prepare(query.sql).all(...query.params);
@@ -1934,6 +1939,19 @@ var ProposalStore = class {
     const proposalId = replayId.startsWith(prefix) ? replayId.slice(prefix.length) : replayId;
     return this.replay(proposalId);
   }
+  getStoredReplay(replayId) {
+    const row = this.db.prepare("SELECT * FROM replay_records WHERE replay_id = ?").get(replayId);
+    return rowToStoredReplay(row);
+  }
+  getStoredReplayForProposal(proposalId) {
+    const row = this.db.prepare(`
+      SELECT * FROM replay_records
+      WHERE proposal_id = ?
+      ORDER BY created_at DESC, replay_id DESC
+      LIMIT 1
+    `).get(proposalId);
+    return rowToStoredReplay(row);
+  }
   proposalIdForEvidence(evidenceBundleId) {
     const evidence = this.getEvidenceBundle(evidenceBundleId);
     if (evidence?.proposal_id) return evidence.proposal_id;
@@ -2236,6 +2254,19 @@ var ProposalStore = class {
     });
     return job;
   }
+  getWritebackJob(writebackJobId) {
+    return rowToWritebackJob(this.db.prepare("SELECT * FROM writeback_jobs WHERE writeback_job_id = ?").get(writebackJobId));
+  }
+  listWritebackJobs(options = {}) {
+    const clauses = [];
+    const values = [];
+    if (options.proposal_id) {
+      clauses.push("proposal_id = ?");
+      values.push(options.proposal_id);
+    }
+    const limit = Math.min(Math.max(options.limit ?? 100, 1), 1e3);
+    return this.db.prepare(`SELECT * FROM writeback_jobs${clauses.length ? ` WHERE ${clauses.join(" AND ")}` : ""} ORDER BY created_at ASC, writeback_job_id ASC LIMIT ?`).all(...values, limit).map(rowToWritebackJob).filter((job) => Boolean(job));
+  }
   claimWritebackIntent(jobInput, runnerId) {
     const job = parseWritebackJob(jobInput);
     const proposal = this.requireProposal(job.proposal_id);
@@ -4059,6 +4090,19 @@ function inWhere(column, values) {
   };
 }
 function buildProposalQuery(filters) {
+  const { clauses, params } = proposalQueryParts(filters);
+  const where = clauses.length ? ` WHERE ${clauses.join(" AND ")}` : "";
+  return {
+    sql: `SELECT * FROM proposals${where} ORDER BY created_at DESC, proposal_id DESC${filters.limit ? " LIMIT ?" : ""}`,
+    params: filters.limit ? [...params, filters.limit] : params
+  };
+}
+function buildProposalCountQuery(filters) {
+  const { clauses, params } = proposalQueryParts(filters);
+  const where = clauses.length ? ` WHERE ${clauses.join(" AND ")}` : "";
+  return { sql: `SELECT COUNT(*) AS count FROM proposals${where}`, params };
+}
+function proposalQueryParts(filters) {
   const clauses = [];
   const params = [];
   addEqual(clauses, params, "proposal_id", filters.proposal);
@@ -4070,7 +4114,7 @@ function buildProposalQuery(filters) {
   addEqual(clauses, params, "action", filters.capability ?? filters.action);
   addObjectFilter(clauses, params, "business_object", "source_table", "object_id", filters.objectType, filters.objectId);
   addTimeRange(clauses, params, "created_at", filters.from, filters.to);
-  return finishQuery("SELECT * FROM proposals", clauses, params, filters.limit);
+  return { clauses, params };
 }
 function buildEvidenceQuery(filters) {
   const clauses = [];
@@ -4652,6 +4696,62 @@ function rowToReceipt(row) {
     source_table: row.source_table == null ? void 0 : String(row.source_table)
   };
 }
+function rowToWritebackJob(row) {
+  if (!isRecord(row)) return void 0;
+  let payload;
+  try {
+    payload = JSON.parse(String(row.job_json));
+  } catch {
+    throw new ProposalStoreError("WRITEBACK_JOB_CORRUPT", `writeback job ${String(row.writeback_job_id)} payload is not valid JSON`);
+  }
+  if (!isRecord(payload)) {
+    throw new ProposalStoreError("WRITEBACK_JOB_CORRUPT", `writeback job ${String(row.writeback_job_id)} payload is not an object`);
+  }
+  const handler = payload.schema_version === "synapsor.handler-writeback.v1";
+  let normalizedJob;
+  if (!handler) {
+    try {
+      normalizedJob = parseWritebackJob(payload);
+    } catch {
+      throw new ProposalStoreError("WRITEBACK_JOB_CORRUPT", `writeback job ${String(row.writeback_job_id)} payload is not a supported writeback protocol`);
+    }
+  }
+  const payloadJobId = handler ? payload.writeback_job_id : normalizedJob?.job_id;
+  const payloadProposalId = handler ? payload.proposal_id : normalizedJob?.proposal_id;
+  const payloadProposalHash = handler ? payload.proposal_hash : normalizedJob?.approval_id;
+  if (payloadJobId !== String(row.writeback_job_id) || payloadProposalId !== String(row.proposal_id) || payloadProposalHash !== String(row.proposal_hash)) {
+    throw new ProposalStoreError("WRITEBACK_JOB_CORRUPT", `writeback job ${String(row.writeback_job_id)} index fields do not match its payload`);
+  }
+  return {
+    writeback_job_id: String(row.writeback_job_id),
+    proposal_id: String(row.proposal_id),
+    proposal_hash: String(row.proposal_hash),
+    status: String(row.status),
+    kind: handler ? "app_handler" : "direct_sql",
+    payload,
+    ...normalizedJob ? { normalized_job: normalizedJob } : {},
+    created_at: String(row.created_at),
+    updated_at: String(row.updated_at)
+  };
+}
+function rowToStoredReplay(row) {
+  if (!isRecord(row)) return void 0;
+  let payload;
+  try {
+    payload = JSON.parse(String(row.payload_json));
+  } catch {
+    throw new ProposalStoreError("REPLAY_RECORD_CORRUPT", `replay ${String(row.replay_id)} payload is not valid JSON`);
+  }
+  if (!isRecord(payload) || !isRecord(payload.proposal)) {
+    throw new ProposalStoreError("REPLAY_RECORD_CORRUPT", `replay ${String(row.replay_id)} payload is not a supported replay record`);
+  }
+  const replayId = String(row.replay_id);
+  const proposalId = String(row.proposal_id);
+  if (payload.replay_id !== replayId || payload.proposal.proposal_id !== proposalId || !Array.isArray(payload.approvals) || !Array.isArray(payload.events) || !Array.isArray(payload.receipts) || !Array.isArray(payload.query_audit) || !Array.isArray(payload.evidence) || typeof payload.generated_at !== "string") {
+    throw new ProposalStoreError("REPLAY_RECORD_CORRUPT", `replay ${replayId} index fields do not match its payload`);
+  }
+  return payload;
+}
 function rowToWritebackIntent(row) {
   if (!isRecord(row)) return void 0;
   const status = String(row.status);

package/docs/capability-authoring.md

@@ -196,7 +196,8 @@ reviewed runner JSON capabilities. Current parity:
 | arg `enum` | `ARG risk_level STRING ENUM('low', 'medium', 'high') REQUIRED` | 1.4.121 | Supports 1..64 same-type string, number, or boolean values; duplicates and mixed types fail compilation. |
 | proposal `numeric_bounds` | `BOUND column 1..2500`, `BOUND column ..2500`, or `BOUND column 1..` | 0.1.8 | Applies to patched numeric columns. Strict mode warns when a NUMBER arg is patched without arg min/max or a matching `BOUND`. |
 | proposal `transition_guards` | `TRANSITION status ALLOW pending -> approved\|rejected` or `TRANSITION status FROM current_status ALLOW open -> closed` | 0.1.8 | Values are state strings; use `|` for multiple target states. |
-| proposal `conflict_guard` | `CONFLICT GUARD updated_at` | 0.1 | If omitted, DSL emits an explicit weak-guard acknowledgement. Prefer a real row-version column. |
+| proposal `conflict_guard` | `CONFLICT GUARD updated_at` | 0.1 | Required for ordinary UPDATE authoring. It compiles to an exact version-column check. Omission fails instead of silently weakening concurrency protection. |
+| proposal weak `conflict_guard` | `CONFLICT GUARD WEAK ROW HASH ACKNOWLEDGED` | 1.4.4 | Explicit legacy escape hatch for an ordinary single-row source-DB UPDATE only. It hashes the captured projection and may miss concurrent changes outside that projection. It is rejected for DELETE, reversible writes, bounded sets, and Runner-ledger authority. |
 | proposal `approval` | `APPROVAL ROLE billing_lead` | 0.1 | Local mode records the required role; enforcement is still outside the model-facing MCP tool. |
 | proposal `approval.required_approvals` | `REQUIRE 2 APPROVALS` | 1.1 | Optional 1..10 distinct-reviewer quorum; defaults to 1. |
 | proposal `writeback` | `WRITEBACK DIRECT SQL`, `WRITEBACK APP HANDLER EXECUTOR name`, `WRITEBACK CLOUD WORKER`, `WRITEBACK NONE` | 0.1.7 | Handler URLs/tokens stay in `synapsor.runner.json`; contracts carry only the handler name. |
@@ -523,6 +524,8 @@ Canonical Synapsor names use dots, such as `billing.inspect_invoice`. Some
 clients require function-safe names. Use:
 
 ```bash
+export SYNAPSOR_RUNNER_HTTP_TOKEN="$(node -e 'process.stdout.write(require("node:crypto").randomBytes(32).toString("base64url"))')"
+
 synapsor-runner mcp serve-streamable-http \
   --config ./synapsor.runner.json \
   --store ./.synapsor/local.db \
@@ -533,6 +536,8 @@ synapsor-runner mcp serve-streamable-http \
 The model sees aliases such as `billing__inspect_invoice`. Runner includes the
 canonical name in tool metadata and descriptions so audit/replay still use the
 real capability name.
+This loopback token is opaque endpoint access, not tenant identity. See
+[HTTP MCP](http-mcp.md) before using a network listener.
 
 ## Why Not `execute_sql`
 

package/docs/cloud-mode.md

@@ -19,6 +19,24 @@ The local Runner still keeps database credentials in your environment. MCP
 client config snippets contain command paths and Runner arguments, not database
 URLs or write credentials.
 
+Keep Cloud and MCP credentials distinct:
+
+| Credential | Purpose | Issuer/provisioner | Never substitutes for |
+| --- | --- | --- | --- |
+| Cloud user session | Human control-panel/CLI identity and subscription/RBAC checks | Synapsor Cloud identity system | MCP tenant identity or database access |
+| Cloud service/API key | Contract push and scoped Cloud administration | Synapsor Cloud | MCP endpoint access |
+| Source-scoped Runner token | Runner registration, heartbeat, lease, activity, and result calls for one Cloud source | Synapsor Cloud Connect Runner flow | Model-facing MCP access or operator approval |
+| Opaque MCP endpoint token | Loopback or explicitly single-tenant HTTP endpoint access | Customer operator/secret manager | User/tenant identity |
+| Signed MCP access JWT | Shared HTTP client identity and verified tenant/principal claims | Customer identity provider/authorization server | Cloud subscription credential or DB role |
+| Operator credential | Activation, approval, apply, reconcile, dead-letter, and revert authority | Customer operator identity system | Model-facing MCP capability |
+| Database/handler credential | Local read or trusted post-approval effect | Customer secret manager/database/application | Cloud or MCP authentication |
+
+Cloud-linked mode does not require networked MCP: a desktop client can still
+launch the local Runner over stdio. If the local Runner exposes Streamable HTTP,
+the same [HTTP MCP](http-mcp.md) channel and identity profiles apply. Cloud API
+keys and source-scoped Runner tokens are never accepted as shortcuts for MCP
+session authentication.
+
 ## Trust Boundary
 
 ```text

package/docs/database-enforced-scope.md

@@ -11,6 +11,10 @@ from model arguments. Choose the database enforcement mode deliberately:
 
 These modes are defense in depth, not substitutes for least-privilege roles,
 restricted views, application authorization, or staging-first validation.
+HTTP endpoint authentication is another independent layer: it establishes who
+may call Runner and, for signed shared sessions, which trusted tenant/principal
+claims are bound. It does not turn `application_scope` into database-enforced
+isolation. See [HTTP MCP](http-mcp.md).
 
 ## Default: Application-Level Scope
 
@@ -49,6 +53,10 @@ with environment-bound capabilities.
 For shared production HTTP, prefer asymmetric JWT verification so Runner holds
 only public verification material. HS256 remains useful for local development
 and controlled deployments but gives Runner access to the signing secret.
+Also declare `http_security.deployment: shared`, an exact HTTPS
+audience/protected resource, a direct-TLS or trusted-proxy channel, and exact
+Host/Origin policy. A static endpoint token cannot supply shared tenant or
+principal identity.
 
 Run `doctor --json` or `tools preview --json` to inspect the effective
 per-source assurance mode and trusted-context binding. Server startup prints

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/getting-started-own-database.md

@@ -520,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 \
@@ -543,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: