LM Studio gateway backend: palw-gateway crate (sessions/receipts/settlement/search), plugin rev5, launchers + search sidecar, ModelGenesisManifest (mirrors misaka-proof-of-llm 749aabb)

docs/evidence/qi35-lmstudio-palw-receipt.md

@@ -1,9 +1,23 @@
 # Huihui Qwen3.6 PALW receipt model in LM Studio
 
 This integration exposes the repository's patched canonical-INTEGER runtime to
-LM Studio through a loopback OpenAI-compatible endpoint. LM Studio's stock
-llama.cpp runtime is not used for inference: the custom GGUF requires the PALW
-runtime patches, and `qi35_model` remains the receipt issuer.
+LM Studio through a loopback endpoint. LM Studio's stock llama.cpp runtime is
+not used for inference: the custom GGUF requires the PALW runtime patches, and
+`qi35_model` remains the receipt issuer.
+
+Since plugin revision 5 there are two selectable backends (`Backend` in the
+plugin config):
+
+- **`palw-gateway` (default, 127.0.0.1:12346)** — the stateful successor. The
+  chat turn that answers the screen IS the PALW A-execution: persistent
+  sessions with id-stable prefix caching, per-turn engine receipts + runtime
+  ROOTS, privacy/mint mode fixed per message BEFORE sending, live web search
+  through the same sidecar stack, and the settlement pipeline (background
+  worker → replica → certified) whose status streams back into the chat. See
+  "Gateway backend" below.
+- **`legacy` (127.0.0.1:12345)** — the stateless `qi35_lmstudio_server.py`,
+  kept as the reference implementation. Each turn re-prefills the whole
+  transcript.
 
 ## Installed LM Studio generator
 
@@ -16,19 +30,114 @@ after changing the TypeScript adapter with:
 
 ## Start
 
-Start the endpoint before opening a chat in LM Studio:
+Since plugin revision 4 there is nothing to start manually: on each chat the
+generator health-checks the selected backend's `/healthz` and, when the
+endpoint is down, spawns that backend's launcher itself — detached, so the
+engine server outlives both the chat and LM Studio and is reused by later
+sessions. Revision 5 selects the launcher by the `Backend` config:
+`docs/evidence/qi35_lmstudio_gateway.sh` (gateway, port 12346) or
+`docs/evidence/qi35_lmstudio_server.sh` (legacy, port 12345). Launch progress
+streams into the same `receipt対象外` status block the backends use; launcher
+output goes to `~/.config/misaka-palw/lmstudio-server.log` (override:
+`QI35_LMSTUDIO_SERVER_LOG`). Concurrent chats share a single startup attempt,
+and the plugin decides gateway-vs-legacy behavior by what actually answers
+`/healthz` (the gateway reports `engine_resident`), not by config alone.
+
+Plugin config: `Backend` (gateway/legacy), `PALW mode` (see below),
+`Auto-start PALW engine server` (off restores manual-only behavior), and
+`QI35 workspace` pointing at the repository root (default
+`/Users/wata/Downloads/qwen-8.0`; env `QI35_WORKSPACE` wins). Receipt
+semantics are unchanged on both paths: `qi35_model` behind the loopback bridge
+remains the only issuer, and the spawned launcher is byte-identical to the
+manual path.
+
+Manual start remains supported (the plugin detects the healthy endpoint and
+spawns nothing):
 
 ```sh
 cd /Users/wata/Downloads/qwen-8.0
-./docs/evidence/qi35_lmstudio_server.sh
+./docs/evidence/qi35_lmstudio_gateway.sh   # gateway backend (default)
+./docs/evidence/qi35_lmstudio_server.sh    # legacy backend (web search)
 ```
 
-The launcher binds only to `127.0.0.1:12345`, checks the audit key, starts the
-local SearXNG stack when needed, and enables canonical Metal offload. In LM
-Studio, select the installed generator and its only model:
+Stop a detached backend with `pkill -f palw-gateway` /
+`pkill -f qi35_lmstudio_server.py`.
+
+Both launchers bind loopback only, require the audit key, enable canonical
+Metal offload, and start the SearXNG stack when search is enabled
+(`QI35_SEARCH_AUTO=off` skips it). In LM Studio, select the installed
+generator and its only model:
 
 `Huihui-Qwen3.6-35B-A3B PALW receipt`
 
+## Gateway backend (plugin revision 5)
+
+One execution answers the screen AND is the PALW A-run — the design rule that
+makes local-first economics work (no second inference for the receipt). Per
+turn the plugin POSTs the LM Studio transcript to the gateway's
+`/v1/lmstudio/turn`; the gateway resolves it onto its session store BY CONTENT
+(`<think>`/status blocks stripped before comparison):
+
+- matched prefix + same tail → `continued` on the existing branch — the
+  compiled prompt begins with the stored ids and the engine's prefix cache
+  hits (live: `cache_hit 206/223`, turn latency 23.1 s → 8.7 s);
+- edit/regenerate in LM Studio → sibling branch under the last matching turn
+  (append-only history, exactly like the native session API);
+- unknown transcript → new conversation, foreign history imported as
+  `mint_ineligible` turns (`stop_reason=imported`, ids re-encoded from text —
+  the one id-unstable step; every later turn is id-stable again).
+
+`PALW mode` maps to the turn's privacy mode, fixed before sending (§16 of the
+product architecture: deciding after generation invites grinding):
+`PALW Mint` / `Verified, No Mint` enter the settlement pipeline,
+`Local Only` never leaves the device. The `lmstudio_resolve` stream frame
+reports the PREVIOUS turn's settlement state (that is how certification
+results reach the chat without blocking it), and after the answer completes
+the plugin polls `GET /v1/turns/{id}` briefly
+(`QI35_SETTLEMENT_POLL_MS`, default 6 s) — settlement continues in the
+background either way. LM Studio's automatic "2-5 word title" request is
+detected and routed over the stateless `/v1/chat/completions` path so it
+neither creates a session turn nor mints a receipt.
+
+Live web search runs on the gateway path through
+`docs/evidence/qi35_search_sidecar.py` (`--search-cmd`, wired by the
+launcher): the ENTIRE legacy stack — smart/`/search` routing, SSRF-guarded
+page fetch, canonical `live_search_bundle_v1`, typed failure bundles — reused
+as a stdin/stdout subprocess, fail-open to a searchless turn only on
+sidecar-level errors. The rendered evidence joins the turn's user block
+(`user + "\n\n" + evidence`, the legacy `build_prompt_text` convention), so
+the receipt's `prompt_commitment` covers `bundle_sha256=` transitively — no
+receipt schema change. The bundle is persisted on the turn (schema v4
+`search_bundle_json`), streamed to the plugin as a `search_status` frame, and
+exported as the third sidecar `.search.json` (bundle + `receipt_binding`).
+The B replica replays the committed prompt ids — A's snapshot, never a
+re-search — so search turns settle exactly like plain turns.
+
+Gateway receipts are the same engine `RCPT` v0 objects, persisted on the turn
+row AND written as sidecars (`--receipt-dir`, default
+`docs/evidence/lmstudio-receipts/`, files 0600):
+`turn-<turn_id>-<output_commitment16>.receipt.json` plus a
+`qi35-gateway-opening/v1` `.opening.json` carrying the exact prompt/output
+ids, tokenizer digest, runtime roots and context meta. Offline verification =
+`qi35_chat.verify_receipt` (MAC) + recomputing both commitments from the
+opening's ids; verified live on 2026-07-31 for all four E2E turns, alongside
+the full loop `chat turn → receipt → A-commit → self-replica re-execution on
+the real 35B → route/kv/state roots matched → certified → certified_head
+advanced`, with `verified_no_mint` and `local_only` behaving per spec. A
+live `/search` turn additionally proved the binding chain offline: MAC +
+both commitments recomputed, `bundle_sha256=a7f79b9b…` found inside the
+committed 1340-token prompt, `.search.json` `receipt_binding` and the
+opening's `context_meta.search` matching — then settled `certified` through
+the same replica pipeline.
+
+Not on the gateway path yet (stated honestly): model-emitted tool calls, and
+everything consensus-side (`--palw-loopback` certifies plumbing, not
+economics — point `QI35_PALW_COORDINATOR` at a node bridge for the real
+counterparty). Verifier note: `palw-verify-search` replays LEGACY openings
+(`external_input` form); gateway search turns verify today via the opening's
+ids + `.search.json` as above, and extending the Rust verifier to the
+`qi35-gateway-opening/v1` shape is follow-up work.
+
 ## Receipt and search semantics
 
 - Search routing is automatic in `smart` mode. `/search <question>` forces it.

docs/evidence/qi35_lmstudio_gateway.sh

@@ -0,0 +1,89 @@
+#!/bin/zsh
+# Launch palw-gateway as the LM Studio backend (the stateful successor of
+# qi35_lmstudio_server.py): persistent sessions with id-stable prefix caching,
+# per-turn engine receipts + runtime ROOTS, the PALW settlement pipeline
+# (loopback coordinator by default; point QI35_PALW_COORDINATOR at a node-side
+# bridge to replace it), and GPT-style live search via the sidecar
+# (qi35_search_sidecar.py reusing the legacy stack; QI35_SEARCH_AUTO=off
+# disables it).
+set -e
+
+SP="$(cd "$(dirname "$0")" && pwd)"
+WS="${QI35_WORKSPACE:-$(cd "$SP/../.." && pwd)}"
+export QI35_MODEL="${QI35_MODEL:-$WS/models/Qwen3.6-abliterated-35b-Claude-4.7/Qwen3.6-abliterated-35b-Claude-4.7-Q4_K_M.gguf}"
+export QI35_TABLES="${QI35_TABLES:-$SP/qi35_tables.bin}"
+export QI35_ENGINE="${QI35_ENGINE:-$SP/qi35_model}"
+export QI35_TOKENIZER="${QI35_TOKENIZER:-$WS/models/Qwen3.6-35B-A3B-Claude-4.7-base-meta/tokenizer.json}"
+export QI35_AUDIT_KEY="${QI35_AUDIT_KEY:-$HOME/.config/misaka-palw/audit-keys/local-audit.key}"
+export QI35_RECEIPT_DIR="${QI35_RECEIPT_DIR:-$SP/lmstudio-receipts}"
+QI35_GATEWAY_STATE="${QI35_GATEWAY_STATE:-$HOME/.config/misaka-palw/lmstudio-gateway}"
+QI35_GATEWAY_PORT="${QI35_GATEWAY_PORT:-12346}"
+QI35_MAX_NEW="${QI35_MAX_NEW:-2048}"
+QI35_MAX_CONTEXT="${QI35_MAX_CONTEXT:-8192}"
+QI35_THREADS="${QI35_THREADS:-8}"
+QI35_LMSTUDIO_API_KEY="${QI35_LMSTUDIO_API_KEY:-palw-local}"
+export QI35_SEARCH_AUTO="${QI35_SEARCH_AUTO:-smart}"
+export QI35_SEARCH_BACKEND="${QI35_SEARCH_BACKEND:-searxng}"
+export QI35_SEARXNG_URL="${QI35_SEARXNG_URL:-http://127.0.0.1:8080}"
+export QI35_SEARCH_LANGUAGE="${QI35_SEARCH_LANGUAGE:-ja-JP}"
+export QI35_SEARCH_FETCH_PAGES="${QI35_SEARCH_FETCH_PAGES:-2}"
+QI35_SYSTEM="${QI35_SYSTEM:-You are a thoughtful and accurate assistant. The local date is $(date +%F). Write entirely in the user's language, including reasoning. For each non-trivial request, output exactly one concise <think>...</think> analysis, always close it, then give the direct answer with useful explanation, examples, and cautions. Do not invent current facts; say so when you would need a live source.}"
+
+if [[ ! -f "$QI35_AUDIT_KEY" ]]; then
+  print -u2 "qi35_lmstudio_gateway: audit key not found: $QI35_AUDIT_KEY"
+  exit 1
+fi
+
+# SearXNG stack for the search sidecar — same fail-closed block as the legacy
+# launcher, but only when search is enabled and uses the searxng backend.
+if [[ "$QI35_SEARCH_AUTO" != "off" && "$QI35_SEARCH_BACKEND" == "searxng" ]]; then
+  if ! curl -fsS --max-time 2 "$QI35_SEARXNG_URL/healthz" >/dev/null 2>&1; then
+    command -v colima >/dev/null 2>&1 || { print -u2 "Colima is required for search (QI35_SEARCH_AUTO=off to disable)"; exit 1; }
+    colima status >/dev/null 2>&1 || colima start --cpu 2 --memory 3 --vm-type vz
+    command -v docker-compose >/dev/null 2>&1 || { print -u2 "docker-compose is required for search"; exit 1; }
+    docker-compose --project-directory "$WS/infra/searxng" -f "$WS/infra/searxng/compose.yaml" up -d
+    for _ in {1..30}; do
+      curl -fsS --max-time 2 "$QI35_SEARXNG_URL/healthz" >/dev/null 2>&1 && break
+      sleep 1
+    done
+  fi
+  curl -fsS --max-time 2 "$QI35_SEARXNG_URL/healthz" >/dev/null
+fi
+
+GW_BIN="${QI35_GATEWAY_BIN:-$WS/palw-gateway/target/release/palw-gateway}"
+if [[ ! -x "$GW_BIN" ]]; then
+  command -v cargo >/dev/null 2>&1 || { print -u2 "palw-gateway binary missing and cargo unavailable: $GW_BIN"; exit 1; }
+  print -u2 "qi35_lmstudio_gateway: building palw-gateway (release)…"
+  (cd "$WS/palw-gateway" && cargo build --release)
+fi
+
+mkdir -p "$QI35_GATEWAY_STATE"
+chmod 700 "$QI35_GATEWAY_STATE"
+
+# The worker's counterparty: a node-side bridge when given, else the in-process
+# loopback coordinator (dev harness — certifies plumbing, not consensus).
+palw_args=(--palw-loopback)
+if [[ -n "${QI35_PALW_COORDINATOR:-}" ]]; then
+  palw_args=(--palw-coordinator "$QI35_PALW_COORDINATOR")
+  [[ -n "${QI35_PALW_COORDINATOR_TOKEN:-}" ]] && palw_args+=(--palw-coordinator-token "$QI35_PALW_COORDINATOR_TOKEN")
+fi
+[[ "${QI35_METAL:-v3}" == "0" ]] && palw_args+=(--no-metal)
+[[ "$QI35_SEARCH_AUTO" != "off" ]] && palw_args+=(--search-cmd "$SP/qi35_search_sidecar.py")
+
+exec "$GW_BIN" \
+  --gguf "$QI35_MODEL" \
+  --tables "$QI35_TABLES" \
+  --tokenizer "$QI35_TOKENIZER" \
+  --engine "$QI35_ENGINE" \
+  --listen "127.0.0.1:$QI35_GATEWAY_PORT" \
+  --db "$QI35_GATEWAY_STATE/sessions.sqlite3" \
+  --artifacts-dir "$QI35_GATEWAY_STATE/artifacts" \
+  --workspace "$QI35_GATEWAY_STATE/workspace" \
+  --threads "$QI35_THREADS" \
+  --max-new "$QI35_MAX_NEW" \
+  --max-context "$QI35_MAX_CONTEXT" \
+  --system-prompt "$QI35_SYSTEM" \
+  --auth-token "$QI35_LMSTUDIO_API_KEY" \
+  --audit-key-file "$QI35_AUDIT_KEY" \
+  --receipt-dir "$QI35_RECEIPT_DIR" \
+  "${palw_args[@]}"

docs/evidence/qi35_lmstudio_install.sh

@@ -12,5 +12,6 @@ command -v npm >/dev/null 2>&1 || { print -u2 "npm is required"; exit 1; }
 (cd "$PLUGIN" && npm install && "$LMS" dev --install -y)
 
 print "Installed misakachain/palw-receipt-adapter in LM Studio."
-print "Start the PALW endpoint with:"
-print "  $SP/qi35_lmstudio_server.sh"
+print "Backends auto-start from the plugin; manual start:"
+print "  $SP/qi35_lmstudio_gateway.sh   # gateway (sessions + settlement, default)"
+print "  $SP/qi35_lmstudio_server.sh    # legacy (reference)"

docs/evidence/qi35_search_sidecar.py

@@ -0,0 +1,95 @@
+#!/usr/bin/env python3
+"""Search sidecar for palw-gateway: one JSON request on stdin, one JSON reply on stdout.
+
+The gateway is Rust; the whole GPT-style search stack (routing, SSRF-guarded page
+fetch, canonical live_search_bundle_v1) already exists in qi35_web_search.py. This
+CLI re-exposes exactly the legacy qi35_chat.prepare_search() behavior — including
+"failures are typed into a bundle, not thrown away" — without importing qi35_chat
+(which requires the model/tokenizer environment). stdlib only.
+
+stdin : {"query": str, "previous_user_query": str|null}
+stdout: {"searched": false, "query": q}                                — routed away
+        {"searched": true,  "query": q, "evidence_text": str,
+         "effective_compression": "off"|"quality_gated_v1",
+         "bundle": {...}, "bundle_sha256": str, "summary_lines": [str]} — searched
+        {"searched": false, "query": q, "error": str}                  — sidecar-level failure (fail-open to a searchless turn)
+"""
+
+import json
+import os
+import sys
+import unicodedata
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from qi35_web_search import (  # noqa: E402
+    SearchError,
+    prompt_context_with_meta,
+    route_search_query,
+    search,
+    search_failure_bundle,
+    should_search,
+)
+
+SEARCH_MODE = os.environ.get("QI35_SEARCH_AUTO", "smart")
+
+
+def summary_lines(bundle):
+    outcome = bundle.get("outcome", {"status": "ok"})
+    digest = bundle.get("bundle_sha256", "")[:16]
+    if outcome.get("status") != "ok":
+        return [f"検索失敗を証跡化 {bundle.get('provider', '?')} sha256={digest}…: {outcome.get('message', '')}"]
+    lines = [f"検索 {bundle.get('provider', '?')} sha256={digest}… hits={len(bundle.get('results', []))}"]
+    for result in bundle.get("results", []):
+        lines.append(f"[{result['rank']}] {result['title']} — {result['url']}")
+    return lines
+
+
+def run(request):
+    raw_query = unicodedata.normalize("NFC", request.get("query", ""))
+    explicit = raw_query.startswith("/search ")
+    query = raw_query[len("/search "):].strip() if explicit else raw_query
+    if explicit and not query:
+        raise SearchError("検索語を入力してください")
+    if not explicit and not should_search(query, SEARCH_MODE):
+        return {"searched": False, "query": query}
+    previous = request.get("previous_user_query") or None
+    search_query, routing_reason, require_exact = route_search_query(query, previous)
+    try:
+        bundle = search(
+            search_query,
+            original_query=query,
+            routing_reason=routing_reason,
+            require_exact=require_exact,
+        )
+    except SearchError as error:
+        bundle = search_failure_bundle(
+            search_query,
+            error,
+            original_query=query,
+            routing_reason=routing_reason,
+        )
+    evidence_text, effective_mode = prompt_context_with_meta(bundle)
+    return {
+        "searched": True,
+        "query": query,
+        "evidence_text": evidence_text,
+        "effective_compression": effective_mode,
+        "bundle": bundle,
+        "bundle_sha256": bundle["bundle_sha256"],
+        "summary_lines": summary_lines(bundle),
+    }
+
+
+def main():
+    request = json.load(sys.stdin)
+    try:
+        reply = run(request)
+    except Exception as error:  # sidecar-level failure: the turn continues searchless
+        reply = {"searched": False, "query": request.get("query", ""), "error": str(error)}
+    json.dump(reply, sys.stdout, ensure_ascii=False)
+    sys.stdout.write("\n")
+
+
+if __name__ == "__main__":
+    main()

docs/model-genesis-candidate.md

@@ -43,3 +43,84 @@ d. Freeze tokenizer + runtime + quantization in the manifest; register the manif
    context in the LOCKED signature-domain table; sign with both parties' keys.
 
 Steps a–b are executable by one operator today; c is external by definition; d is blocked on c.
+
+## Prerequisites (in-repo) — status 2026-07-27
+
+The flip path above was not executable, for a reason that had nothing to do with the external
+gates: **the object the two parties are supposed to compare did not exist.** `ModelGenesisManifest`
+had zero hits across both repositories, so two operators could each run a conversion and still have
+nothing comparable at the end. That is now closed; the external items are untouched.
+
+### Built
+
+| Prerequisite | Where | What it gives |
+|---|---|---|
+| `ModelGenesisManifest` type, canonical encoding, keyed-BLAKE2b-512 hash | `runtime-palw/src/model_genesis.rs` | The comparable artifact of ADR-0047 §1. Backend-independent and weights-derived only; big-endian integers, `u64`-length-framed variable fields (prefix-free ⇒ injective). Hash domain `misaka-palw-v1/model-genesis`, distinct from `palw-k1/file` and every `misaka-palw-v3/*` receipt domain. |
+| Field-level diff | `ModelGenesisManifest::first_mismatch` | ADR-0047's acceptance test is a hash comparison, which tells a failing operator nothing. This names the differing field. |
+| Mechanical backend-independence check | `ModelGenesisManifest::validate` | Rejects a conversion procedure naming a backend/host token (`metal`, `cuda`, `gpu`, `ngl`, `thread`, `arm64`, …), absolute or `..`-bearing paths (which carry an operator's home directory into the digest), non-ASCII text, and mutable revision pins (a branch name is not reproducible). |
+| Honest readiness assessment | `model_genesis::assess_genesis` | Reproduces the four disqualifiers below as data. `eligible` can never be `true` — `ManifestUnsigned` is unconditional — and a unit test asserts that no input produces a genesis. Two stacks owned by one operator are reported as `TwoPartyForm::Weak`, per ADR-0047 §1. |
+| Deterministic conversion + manifest tool | `scripts/model_genesis_manifest.py` (`selftest` / `convert` / `manifest` / `verify`) | The identical procedure both operators run. Fixed conversion environment (`LC_ALL=C`, `TZ=UTC`, `PYTHONHASHSEED=0`, `SOURCE_DATE_EPOCH=0`) and a required `--model-name`, because the converter otherwise derives `general.name` from the local directory name — a per-operator difference that would break the match for no weights-related reason. |
+| Rust↔Python parity | golden vector `b747790722bdf626…f756d9b3`, pinned in both implementations | If the two encoders drifted, a cross-operator mismatch would be unattributable (weights, or tool?). `selftest` and `scripts/tests/test_model_genesis_manifest.py` bind them. |
+
+Fail-closed behaviour is not aspirational — it is the current state of this checkout. Against the
+real tree, `convert` and `manifest` both refuse:
+
+```
+$ python3 scripts/model_genesis_manifest.py manifest --weights-dir models/Qwen3.6-35B-A3B-Claude-4.7-base-meta …
+model-genesis: --weights-dir … contains metadata only — no *.safetensors/*.bin weight shards were
+found. Download the full checkpoint; a manifest must never be built from absent weights.
+```
+
+`models/Qwen3.6-35B-A3B-Claude-4.7-base-meta/` holds the seven pinned metadata files and no weight
+shards, and `llama-quantize` is not among the built targets in `config/runtime-pins.sh`
+(`PALW_BUILD_TARGETS`). Both are named explicitly by the tool rather than worked around.
+
+### The signature-domain row that would be required (BLOCKED on a human unlock decision)
+
+Disqualifier (3) cannot be closed by writing code. The ML-DSA-87 signature-context table
+`MisakaLLM-palw-shared/consensus/core/src/signature_domains.rs` was **LOCKED on 2026-07-25** and is
+guarded by a golden test that duplicates every row. Adding a signing object is an explicit human
+decision, so `runtime-palw/src/model_genesis.rs` contains **no signing function at all**. The exact
+row that would be needed:
+
+```rust
+SignatureDomain {
+    object: "PALW model genesis manifest",
+    context: crate::palw::PALW_MODEL_GENESIS_V1_MLDSA87_CONTEXT, // b"misaka-palw-v1/model-genesis/mldsa87"
+    defined_in: "misaka_palw::model_genesis::ModelGenesisManifest::manifest_hash",
+},
+```
+
+Three test sites change in the same commit, by design:
+
+1. `signature_domain_table_is_locked` — a new golden line (the lock's review surface).
+2. `palw_naming_divergence_is_pinned_not_forgotten` — asserts exactly 15 PALW rows and that every
+   PALW row outside a named allow-list contains no `/`. A slash-convention row must be added to
+   that allow-list, i.e. the naming convention is decided explicitly rather than inherited.
+3. `signature_domains_are_prefix_free` — already satisfied: the proposed context is distinct from
+   and not a prefix of `misaka-palw-v3/receipt/mldsa87` or `misaka-palw-v3/jobspec/mldsa87`
+   (checked by `model_genesis::tests::proposed_context_is_distinct_and_prefix_free`).
+
+The context constant is recorded in this repo as
+`PALW_MODEL_GENESIS_V1_MLDSA87_CONTEXT_UNREGISTERED` — named so that using it before the unlock is
+not a typo one can make silently. Signature *contexts* and keyed-*hash* domains are separate
+namespaces (see the `signature_domains.rs` module note), so the hash domain above did not require
+the table and does not pre-empt the decision.
+
+### Unchanged: what is still external
+
+Disqualifiers (1), (2) and (4) are all still open, and none of them moved:
+
+- **(1) provenance** — the pins in `config/runtime-pins.sh` still terminate at
+  `huihui-ai/Huihui-Qwen3.6-35B-A3B-Claude-4.7-Opus-abliterated`, a **third-party abliterated
+  derivative**, not official Alibaba weights. The manifest records this as a claim *inside* the
+  hashed encoding (`ProvenanceTier::ThirdPartyDerivative`), so one party cannot quietly record
+  "official" while the other records "derivative", and the tool prints `NOT a genesis candidate`
+  when that tier is used. Tooling makes the derivative reproducible; it cannot make it official.
+- **(2) two-party reproduction** — no run has happened. Requires the official weights of (1), a
+  working RTX box, and preferably an organisationally independent second operator.
+- **(4) compute-set** — receipts still bind the integer-canonical 0.5B calibration set; out of
+  ADR-0047's scope, tracked on the Receipt v3 / compute-set track.
+
+`runtime-palw/src/mint.rs` `model.official_genesis` (`MainnetBlocker::ExternalModelGenesis`) is
+therefore still unmet, and the mint test asserting that gate is never `met()` still holds.

docs/security-model.md

@@ -59,6 +59,21 @@ R32は`In progress`だがCUDA Receiptは発行不可である。
 host OS、driver、GPU firmware まで敵対的とみなす場合は、TEE attestation または ZK/VC を追加
 しなければならない。この v1 はその主張を行わない。
 
+### Consensus 側の三本柱(node ADR-0045 D2 の反映)
+
+node 側 consensus が担う正しさの柱は次の三つで、役割は重複しない。本 crate の Receipt/audit
+機構は第 1 の柱への入力であり、支払いの最終性・遡及の扱いは第 3 の柱の規律に従う。
+
+| 柱 | 検出するもの | 効果 | 時点 |
+|---|---|---|---|
+| Audit rounds | 標本化された leaf の再検証不一致 | certificate 拒否(事前)/ FraudEvidence(事後) | batch lifecycle 内 |
+| PCPB | ticket と provider の束縛偽装(委譲・横流し) | ticket 無効 = mint 不能(事前) | mint 時 |
+| Fraud + slash | 事後に発覚した不正(withhold、虚偽 receipt) | Revoked(**非遡及**)+ bond slash(遡及的担保) | いつでも |
+
+Revoked の非遡及は node 側 SS-04 で確定済み(coinbase 済み provider 支払いは UTXO model 上
+巻き戻せない;事後抑止は bond slash が担う)。単一 self-reported Receipt が独立証明でないという
+本書の宣言を consensus 側も正とし、参照は双方向に固定される(node `docs/adr/0045`)。
+
 ## Threat controls
 
 | Threat | Primary controls | Fail condition |
@@ -81,7 +96,7 @@ host OS、driver、GPU firmware まで敵対的とみなす場合は、TEE attes
 | External double settlement | stable payment command、signed terminal confirmation、single durable terminal | command/distribution/pair/amount/epoch不一致、逆terminal、conflicting replay |
 | Canary false slash | scheduler-signed precommit、atomic receipt acceptance、fault-party timeout attribution | precommit/request/assignment/window不一致、opening未到達、scheduler opening timeout |
 | Bond funding/slash replay | signed funding event、typed primary proof、conservation reconciliation、appeal state | event/offense/canonical payload conflict、account/assignment/evidence不一致 |
-| Dependency/MSRV drift | exact crypto pins、lockfile、Rust 1.81 all-target CI | lock変更、MSRV manifest parse失敗、lint/test failure |
+| Dependency/MSRV drift | exact crypto pins、lockfile、Rust 1.85 all-target CI | lock変更、MSRV manifest parse失敗、lint/test failure |
 | Premature Work Ticket | opaque maturity basis、required bond release links、WorkTicketV2、atomic one-shot issue | raw claim、epoch前倒し、bond link不足、grant不一致、source再消費 |
 
 ## Cryptographic rules

infra/lmstudio/palw-receipt-adapter/manifest.json

@@ -3,5 +3,5 @@
   "runner": "node",
   "owner": "misakachain",
   "name": "palw-receipt-adapter",
-  "revision": 3
+  "revision": 5
 }

infra/lmstudio/palw-receipt-adapter/src/config.ts

@@ -6,7 +6,7 @@ export const configSchematics = createConfigSchematics()
     "select",
     {
       displayName: "PALW receipt model",
-      subtitle: "Canonical-integer Huihui Qwen3.6 with automatic live search",
+      subtitle: "Canonical-integer Huihui Qwen3.6 (integer engine issues the receipt)",
       options: [
         {
           value: "huihui-ai/Huihui-Qwen3.6-35B-A3B-Claude-4.7-Opus-abliterated-PALW-receipt",
@@ -16,4 +16,52 @@ export const configSchematics = createConfigSchematics()
     },
     "huihui-ai/Huihui-Qwen3.6-35B-A3B-Claude-4.7-Opus-abliterated-PALW-receipt",
   )
+  .field(
+    "privacyMode",
+    "select",
+    {
+      displayName: "PALW mode",
+      subtitle:
+        "Fixed per message BEFORE sending (deciding after generation invites grinding). Gateway backend only; the legacy server ignores it.",
+      options: [
+        { value: "palw_mint", displayName: "PALW Mint — replica + settlement, reward candidate" },
+        { value: "verified_no_mint", displayName: "Verified, No Mint — replica match only" },
+        { value: "local_only", displayName: "Local Only — never leaves this device" },
+      ],
+    },
+    "palw_mint",
+  )
+  .field(
+    "serverFlavor",
+    "select",
+    {
+      displayName: "Backend",
+      subtitle:
+        "Gateway (12346): persistent sessions, prefix-cache fast turns, settlement status, receipt sidecars. Legacy (12345): stateless server with live web search.",
+      options: [
+        { value: "gateway", displayName: "palw-gateway (sessions + settlement)" },
+        { value: "legacy", displayName: "legacy qi35_lmstudio_server.py (web search)" },
+      ],
+    },
+    "gateway",
+  )
+  .field(
+    "autoStartServer",
+    "boolean",
+    {
+      displayName: "Auto-start PALW engine server",
+      subtitle:
+        "Spawn the selected backend's launcher from docs/evidence when its port is down (log: ~/.config/misaka-palw/lmstudio-server.log)",
+    },
+    true,
+  )
+  .field(
+    "workspacePath",
+    "string",
+    {
+      displayName: "QI35 workspace",
+      subtitle: "Repository root containing docs/evidence launchers (QI35_WORKSPACE overrides)",
+    },
+    "/Users/wata/Downloads/qwen-8.0",
+  )
   .build();

infra/lmstudio/palw-receipt-adapter/src/gateway.ts

@@ -0,0 +1,212 @@
+// palw-gateway client: the stateful LM Studio path. One POST to /v1/lmstudio/turn
+// streams GenerationEventV1 frames (prefixed by a lmstudio_resolve frame); the turn's
+// settlement status is then readable at GET /v1/turns/{id}. The receipt issuer is
+// unchanged — qi35_model behind the gateway — this file only moves bytes.
+
+export interface ResolveFrame {
+  resolution: string;
+  conversation_id: string;
+  parent_turn_id: string | null;
+  matched_pairs: number;
+  imported_turns: number;
+  parent: null | {
+    turn_id: string;
+    verification_status: string;
+    privacy_mode: string;
+    receipt_present: boolean;
+  };
+  certified_head: string | null;
+}
+
+export interface TurnStreamCallbacks {
+  onResolve: (frame: ResolveFrame) => void;
+  onSearchStatus: (lines: string[], bundleSha256: string) => void;
+  onStarted: (info: { job_id: string; turn_id: string; prompt_tokens: number }) => void;
+  onContextBudget: (droppedTurns: number) => void;
+  onDelta: (utf8: string) => void;
+  onCompleted: (info: {
+    stop_reason: string;
+    output_tokens: number;
+    cache_hit_tokens: number;
+    elapsed_ms: number;
+  }) => void;
+}
+
+export interface TurnInfo {
+  turn_id: string;
+  verification_status: string;
+  privacy_mode: string;
+  stop_reason: string | null;
+  certified_head: string | null;
+  receipt: {
+    present: boolean;
+    schema?: string;
+    output_commitment?: string;
+    prompt_commitment?: string;
+    signer_key_id?: string;
+    eos_reached?: boolean;
+  };
+  search?: {
+    present: boolean;
+    bundle_sha256?: string;
+    provider?: string;
+  };
+}
+
+export class GatewayError extends Error {}
+
+interface ChatMessage {
+  role: string;
+  content: string;
+}
+
+function baseOrigin(baseUrl: string): string {
+  return baseUrl.replace(/\/v1\/?$/, "");
+}
+
+function authHeaders(apiKey: string): Record<string, string> {
+  return { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}` };
+}
+
+// Detect which backend answers /healthz: the gateway reports {ok, engine_resident},
+// the legacy python server reports {status:"ok", model}. Unreachable → null.
+export async function detectFlavor(baseUrl: string): Promise<"gateway" | "legacy" | null> {
+  try {
+    const response = await fetch(`${baseOrigin(baseUrl)}/healthz`, {
+      signal: AbortSignal.timeout(1_500),
+    });
+    if (!response.ok) return null;
+    const body: unknown = await response.json();
+    if (typeof body === "object" && body !== null && "engine_resident" in body) return "gateway";
+    return "legacy";
+  } catch {
+    return null;
+  }
+}
+
+/// Stream one turn through POST /v1/lmstudio/turn. Resolves when the stream finishes
+/// ([DONE] or EOF); throws GatewayError on HTTP errors or a `failed` frame. Abort by
+/// firing `signal` — the gateway marks the turn user-cancelled via /v1/jobs/{id}/cancel,
+/// which the caller is responsible for invoking (it needs the job id from onStarted).
+export async function streamTurn(
+  baseUrl: string,
+  apiKey: string,
+  messages: ChatMessage[],
+  privacyMode: string,
+  callbacks: TurnStreamCallbacks,
+  signal: AbortSignal,
+): Promise<void> {
+  const response = await fetch(`${baseUrl.replace(/\/$/, "")}/lmstudio/turn`, {
+    method: "POST",
+    headers: authHeaders(apiKey),
+    body: JSON.stringify({ messages, privacy_mode: privacyMode }),
+    signal,
+  });
+  if (!response.ok || response.body === null) {
+    const text = await response.text().catch(() => "");
+    throw new GatewayError(`gateway ${response.status}: ${text.slice(0, 300)}`);
+  }
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  const handleFrame = (payload: string) => {
+    if (payload === "[DONE]") return;
+    let event: Record<string, unknown>;
+    try {
+      event = JSON.parse(payload) as Record<string, unknown>;
+    } catch {
+      return;
+    }
+    switch (event.type) {
+      case "lmstudio_resolve":
+        callbacks.onResolve(event as unknown as ResolveFrame);
+        break;
+      case "search_status":
+        callbacks.onSearchStatus(
+          Array.isArray(event.lines) ? (event.lines as string[]) : [],
+          typeof event.bundle_sha256 === "string" ? event.bundle_sha256 : "",
+        );
+        break;
+      case "started":
+        callbacks.onStarted(event as unknown as { job_id: string; turn_id: string; prompt_tokens: number });
+        break;
+      case "context_budget":
+        callbacks.onContextBudget(Number(event.dropped_turns ?? 0));
+        break;
+      case "token":
+        if (typeof event.utf8_delta === "string" && event.utf8_delta.length > 0) {
+          callbacks.onDelta(event.utf8_delta);
+        }
+        break;
+      case "completed":
+        callbacks.onCompleted(
+          event as unknown as { stop_reason: string; output_tokens: number; cache_hit_tokens: number; elapsed_ms: number },
+        );
+        break;
+      case "failed":
+        throw new GatewayError(String(event.message ?? "generation failed"));
+      default:
+        break;
+    }
+  };
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    buffer += decoder.decode(value, { stream: true });
+    let split;
+    while ((split = buffer.indexOf("\n\n")) >= 0) {
+      const frame = buffer.slice(0, split);
+      buffer = buffer.slice(split + 2);
+      for (const line of frame.split("\n")) {
+        if (line.startsWith("data: ")) handleFrame(line.slice("data: ".length));
+      }
+    }
+  }
+}
+
+export async function cancelJob(baseUrl: string, apiKey: string, jobId: string): Promise<void> {
+  await fetch(`${baseUrl.replace(/\/$/, "")}/jobs/${jobId}/cancel`, {
+    method: "POST",
+    headers: authHeaders(apiKey),
+    signal: AbortSignal.timeout(3_000),
+  }).catch(() => {});
+}
+
+export async function fetchTurnInfo(baseUrl: string, apiKey: string, turnId: string): Promise<TurnInfo | null> {
+  try {
+    const response = await fetch(`${baseUrl.replace(/\/$/, "")}/turns/${turnId}`, {
+      headers: authHeaders(apiKey),
+      signal: AbortSignal.timeout(3_000),
+    });
+    if (!response.ok) return null;
+    return (await response.json()) as TurnInfo;
+  } catch {
+    return null;
+  }
+}
+
+const SETTLED = new Set(["replica_matched", "certified", "matured", "mismatch", "mint_ineligible"]);
+
+/// Poll the turn's settlement for up to `budgetMs`, returning the last info seen. The
+/// pipeline continues in the gateway regardless — this only decides how much the current
+/// chat message can already show.
+export async function pollSettlement(
+  baseUrl: string,
+  apiKey: string,
+  turnId: string,
+  budgetMs: number,
+  isAborted: () => boolean,
+): Promise<TurnInfo | null> {
+  const deadline = Date.now() + budgetMs;
+  let last: TurnInfo | null = null;
+  for (;;) {
+    if (isAborted()) return last;
+    const info = await fetchTurnInfo(baseUrl, apiKey, turnId);
+    if (info !== null) {
+      last = info;
+      if (SETTLED.has(info.verification_status)) return info;
+    }
+    if (Date.now() >= deadline) return last;
+    await new Promise((resolve) => setTimeout(resolve, 1_000));
+  }
+}

infra/lmstudio/palw-receipt-adapter/src/generator.ts

@@ -2,12 +2,27 @@ import { type Chat, type GeneratorController, type InferParsedConfig } from "@lm
 import OpenAI from "openai";
 import { type ChatCompletionMessageParam } from "openai/resources/index";
 import { configSchematics } from "./config";
+import { cancelJob, detectFlavor, fetchTurnInfo, pollSettlement, streamTurn, GatewayError } from "./gateway";
+import { AbortedError, ensureServer, type ServerFlavor } from "./server";
 
-const BASE_URL = process.env.QI35_LMSTUDIO_BASE_URL ?? "http://127.0.0.1:12345/v1";
+// Per-backend default endpoints; QI35_LMSTUDIO_BASE_URL overrides both.
+const DEFAULT_URLS: Record<ServerFlavor, string> = {
+  gateway: "http://127.0.0.1:12346/v1",
+  legacy: "http://127.0.0.1:12345/v1",
+};
 const API_KEY = process.env.QI35_LMSTUDIO_API_KEY ?? "palw-local";
-// The PALW server now streams its own live status block (receipt対象外) covering search,
-// engine load, and prefill progress, so no static placeholder is emitted here. Both the
-// legacy placeholder and the live status block are stripped from history before resend.
+// How long the finished turn may wait for its replica verdict before deferring the
+// answer to the next message's resolve frame. The replica is a real 35B re-execution;
+// with the warm prefix cache it often lands within seconds, but never stall the chat.
+const SETTLEMENT_POLL_MS = Number(process.env.QI35_SETTLEMENT_POLL_MS ?? 6_000);
+
+function resolveBaseUrl(flavor: ServerFlavor): string {
+  return process.env.QI35_LMSTUDIO_BASE_URL ?? DEFAULT_URLS[flavor];
+}
+
+// The PALW backends stream their own live status blocks (receipt対象外) covering engine
+// start, prefill, resolve and settlement. All of them — and the legacy placeholder — are
+// stripped from history before resend so runtime decoration never re-enters a prompt.
 function withoutRuntimeStatus(content: string) {
   return content.replace(/<think>\s*PALW (?:runtime )?status \(receipt対象外\)[\s\S]*?<\/think>\s*/gi, "");
 }
@@ -24,17 +39,205 @@ function toMessages(history: Chat): ChatCompletionMessageParam[] {
   return messages;
 }
 
+// LM Studio's automatic chat-title request ("…come up with a 2-5 word title…") arrives
+// through the same generator. Detect it and answer over the STATELESS OpenAI path so it
+// neither creates a session turn nor mints a receipt — a title is not a conversation.
+function isTitleRequest(text: string): boolean {
+  return /\b\d+(?:\s*-\s*\d+)?\s*word title\b/i.test(text) || /\btitle for this conversation\b/i.test(text);
+}
+
+// One receipt対象外 status block: opens lazily on the first line, closes idempotently.
+// Everything runtime-flavored goes through here so one history-strip regex covers it all.
+class StatusBlock {
+  private opened = false;
+
+  public constructor(
+    private readonly parser: ReasoningStreamParser,
+    private readonly isAborted: () => boolean,
+  ) {}
+
+  public line(text: string) {
+    if (this.isAborted()) return;
+    if (!this.opened) {
+      this.opened = true;
+      this.parser.push("<think>PALW status (receipt対象外):\n");
+    }
+    this.parser.push(text + "\n");
+  }
+
+  public close() {
+    if (this.opened) {
+      this.opened = false;
+      this.parser.push("</think>\n");
+    }
+  }
+}
+
 export async function generate(ctl: GeneratorController, history: Chat) {
   const config: InferParsedConfig<typeof configSchematics> = ctl.getPluginConfig(configSchematics);
-  const client = new OpenAI({ apiKey: API_KEY, baseURL: BASE_URL, timeout: 30 * 60 * 1000 });
-  const stream = await client.chat.completions.create({
-    model: config.get("model"),
-    messages: toMessages(history),
-    stream: true,
+  let aborted = false;
+  ctl.onAborted(() => {
+    aborted = true;
+  });
+  const parser = new ReasoningStreamParser(ctl);
+  const status = new StatusBlock(parser, () => aborted);
+  const flavor = config.get("serverFlavor") as ServerFlavor;
+  const baseUrl = resolveBaseUrl(flavor);
+
+  if (config.get("autoStartServer")) {
+    try {
+      await ensureServer({
+        workspace: process.env.QI35_WORKSPACE ?? config.get("workspacePath").trim(),
+        baseUrl,
+        flavor,
+        emitStatus: (line) => status.line(line),
+        isAborted: () => aborted,
+      });
+    } catch (error) {
+      if (error instanceof AbortedError || aborted) return;
+      status.line(error instanceof Error ? error.message : String(error));
+      status.close();
+      parser.finish();
+      throw error;
+    }
+  }
+  if (aborted) return;
+
+  // Trust what actually answers the port over the configured flavor: an overridden
+  // BASE_URL may point either backend at either port.
+  const actual = (await detectFlavor(baseUrl)) ?? flavor;
+  const messages = toMessages(history);
+
+  if (actual === "legacy") {
+    status.close();
+    await openAiCompletion(ctl, parser, config.get("model"), baseUrl, messages, () => aborted);
+    return;
+  }
+
+  const trailingUser = [...messages].reverse().find((m) => m.role === "user");
+  const trailingText = typeof trailingUser?.content === "string" ? trailingUser.content : "";
+  if (isTitleRequest(trailingText)) {
+    status.close();
+    await openAiCompletion(ctl, parser, config.get("model"), baseUrl, messages, () => aborted);
+    return;
+  }
+
+  // ---- gateway path: one execution answers the screen AND becomes the PALW A-run ----
+  const privacyMode = config.get("privacyMode");
+  let jobId: string | null = null;
+  let turnId: string | null = null;
+  let promptTokens = 0;
+  let completed: { stop_reason: string; output_tokens: number; cache_hit_tokens: number; elapsed_ms: number } | null =
+    null;
+  const controller = new AbortController();
+  ctl.onAborted(() => {
+    controller.abort();
+    if (jobId !== null) void cancelJob(baseUrl, API_KEY, jobId);
   });
 
+  try {
+    await streamTurn(
+      baseUrl,
+      API_KEY,
+      messages as { role: string; content: string }[],
+      privacyMode,
+      {
+        onResolve: (frame) => {
+          const label =
+            frame.resolution === "continued"
+              ? `既存セッション継続 (一致 ${frame.matched_pairs} turn)`
+              : frame.resolution === "branched"
+                ? `分岐 (edit/regenerate、一致 ${frame.matched_pairs} turn)`
+                : frame.resolution === "imported"
+                  ? `新規セッション (過去 ${frame.imported_turns} turn を import)`
+                  : "新規セッション";
+          status.line(`会話復元: ${label} [${privacyMode}]`);
+          if (frame.parent !== null) {
+            const receipt = frame.parent.receipt_present ? " receipt有" : "";
+            status.line(`前turnのPALW検証: ${frame.parent.verification_status}${receipt}`);
+          }
+        },
+        onSearchStatus: (lines) => {
+          for (const line of lines) status.line(line);
+        },
+        onStarted: (info) => {
+          jobId = info.job_id;
+          turnId = info.turn_id;
+          promptTokens = info.prompt_tokens;
+          status.line(`prompt ${info.prompt_tokens} tokens — 生成開始`);
+        },
+        onContextBudget: (dropped) => status.line(`context予算: 古い ${dropped} turn を除外`),
+        onDelta: (utf8) => {
+          status.close();
+          parser.push(utf8);
+        },
+        onCompleted: (info) => {
+          completed = info;
+        },
+      },
+      controller.signal,
+    );
+  } catch (error) {
+    if (aborted) return;
+    const message = error instanceof GatewayError ? error.message : String(error);
+    status.line(message);
+    status.close();
+    parser.finish();
+    throw error;
+  }
+  if (aborted) return;
+
+  // Post-answer settlement block (receipt対象外): the answer clock is done, this shows
+  // how far the settlement clock got within its small budget. The pipeline continues in
+  // the gateway either way and the NEXT message's resolve frame reports the final state.
+  if (turnId !== null && completed !== null) {
+    const done: { stop_reason: string; output_tokens: number; cache_hit_tokens: number; elapsed_ms: number } = completed;
+    const wantsSettlement = privacyMode !== "local_only";
+    const info = wantsSettlement
+      ? await pollSettlement(baseUrl, API_KEY, turnId, SETTLEMENT_POLL_MS, () => aborted)
+      : await fetchTurnInfo(baseUrl, API_KEY, turnId);
+    const seconds = (done.elapsed_ms / 1000).toFixed(1);
+    status.line(
+      `生成完了: ${done.stop_reason} ${done.output_tokens} tok / cache_hit ${done.cache_hit_tokens}/${promptTokens} / ${seconds}s`,
+    );
+    if (info !== null) {
+      const pending = !["replica_matched", "certified", "matured", "mismatch", "mint_ineligible", "local_complete"].includes(
+        info.verification_status,
+      );
+      const suffix =
+        wantsSettlement && (pending || info.verification_status === "replica_pending")
+          ? "(バックグラウンド継続中 — 次メッセージで反映)"
+          : "";
+      status.line(`PALW検証: ${info.verification_status}${suffix}`);
+      if (info.receipt.present) {
+        const commitment = (info.receipt.output_commitment ?? "").slice(0, 16);
+        status.line(`receipt: ${info.receipt.schema ?? "?"} output_commitment=${commitment}…`);
+      }
+      if (info.search?.present) {
+        status.line(`検索bundle: sha256=${(info.search.bundle_sha256 ?? "").slice(0, 16)}… (${info.search.provider ?? "?"})`);
+      }
+    }
+    status.close();
+  }
+  parser.finish();
+}
+
+// Stateless OpenAI-compatible path: the legacy server, and gateway-side title requests.
+async function openAiCompletion(
+  ctl: GeneratorController,
+  parser: ReasoningStreamParser,
+  model: string,
+  baseUrl: string,
+  messages: ChatCompletionMessageParam[],
+  isAborted: () => boolean,
+) {
+  const client = new OpenAI({ apiKey: API_KEY, baseURL: baseUrl, timeout: 30 * 60 * 1000 });
+  const stream = await client.chat.completions.create({ model, messages, stream: true });
+  if (isAborted()) {
+    stream.controller.abort();
+    return;
+  }
   ctl.onAborted(() => stream.controller.abort());
-  const parser = new ReasoningStreamParser(ctl);
   for await (const chunk of stream) {
     const delta = chunk.choices[0]?.delta?.content;
     if (delta) parser.push(delta);

infra/lmstudio/palw-receipt-adapter/src/server.ts

@@ -9,7 +9,12 @@ import * as path from "path";
 export const SERVER_LOG =
   process.env.QI35_LMSTUDIO_SERVER_LOG ??
   path.join(homedir(), ".config", "misaka-palw", "lmstudio-server.log");
-const LAUNCHER_REL = path.join("docs", "evidence", "qi35_lmstudio_server.sh");
+/// Launchers per backend flavor, both under docs/evidence in the workspace.
+export const LAUNCHERS = {
+  gateway: path.join("docs", "evidence", "qi35_lmstudio_gateway.sh"),
+  legacy: path.join("docs", "evidence", "qi35_lmstudio_server.sh"),
+} as const;
+export type ServerFlavor = keyof typeof LAUNCHERS;
 const HEALTH_TIMEOUT_MS = 1_500;
 const POLL_INTERVAL_MS = 1_000;
 // Cold start may include `colima start` plus the SearXNG compose stack.
@@ -22,6 +27,7 @@ const PROGRESS_EVERY_MS = 5_000;
 export interface EnsureServerOptions {
   workspace: string;
   baseUrl: string;
+  flavor: ServerFlavor;
   emitStatus: (line: string) => void;
   isAborted: () => boolean;
 }
@@ -74,8 +80,8 @@ interface LauncherExit {
   message?: string;
 }
 
-function spawnLauncher(workspace: string, exitState: LauncherExit): void {
-  const launcher = path.join(workspace, LAUNCHER_REL);
+function spawnLauncher(workspace: string, flavor: ServerFlavor, exitState: LauncherExit): void {
+  const launcher = path.join(workspace, LAUNCHERS[flavor]);
   if (!existsSync(launcher)) {
     throw new ServerStartError(`launcher not found: ${launcher} (workspace 設定を確認)`);
   }
@@ -113,11 +119,12 @@ function spawnLauncher(workspace: string, exitState: LauncherExit): void {
 async function startAndWait(
   workspace: string,
   baseUrl: string,
+  flavor: ServerFlavor,
   emitStatus: (line: string) => void,
 ): Promise<void> {
-  emitStatus(`エンジンサーバ自動起動中 (${LAUNCHER_REL})…`);
+  emitStatus(`エンジンサーバ自動起動中 (${LAUNCHERS[flavor]})…`);
   const exitState: LauncherExit = { at: 0, code: null };
-  spawnLauncher(workspace, exitState);
+  spawnLauncher(workspace, flavor, exitState);
 
   const startedAt = Date.now();
   let lastProgressAt = 0;
@@ -157,7 +164,7 @@ let inflight: Promise<void> | null = null;
 export async function ensureServer(options: EnsureServerOptions): Promise<void> {
   if (await healthy(options.baseUrl)) return;
   if (inflight === null) {
-    const attempt = startAndWait(options.workspace, options.baseUrl, options.emitStatus).finally(
+    const attempt = startAndWait(options.workspace, options.baseUrl, options.flavor, options.emitStatus).finally(
       () => {
         inflight = null;
       },

palw-gateway/Cargo.lock

@@ -0,0 +1,879 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "ahash"
+version = "0.8.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5a15f179cd60c4584b8a8c596927aadc462e27f2ca70c04e0071964a73ba7a75"
+dependencies = [
+ "cfg-if",
+ "getrandom",
+ "once_cell",
+ "serde",
+ "version_check",
+ "zerocopy",
+]
+
+[[package]]
+name = "aho-corasick"
+version = "1.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ddd31a130427c27518df266943a5308ed92d4b226cc639f5a8f1002816174301"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "ascii"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d92bec98840b8f03a5ff5413de5293bfcd8bf96467cf5452609f939ec6f5de16"
+
+[[package]]
+name = "base64"
+version = "0.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9e1b586273c5702936fe7b7d6896644d8be71e6314cfe09d3167c95f712589e8"
+
+[[package]]
+name = "bitflags"
+version = "2.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b588b76d00fde79687d7646a9b5bdf3cc0f655e0bbd080335a95d7e96f3587da"
+
+[[package]]
+name = "blake2"
+version = "0.10.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "46502ad458c9a52b69d4d4d32775c788b7a1b85e8bc9d482d92250fc0e3f8efe"
+dependencies = [
+ "digest",
+]
+
+[[package]]
+name = "block-buffer"
+version = "0.10.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3078c7629b62d3f0439517fa394996acacc5cbc91c5a20d8c658e77abd503a71"
+dependencies = [
+ "generic-array",
+]
+
+[[package]]
+name = "castaway"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dec551ab6e7578819132c713a93c022a05d60159dc86e7a7050223577484c55a"
+dependencies = [
+ "rustversion",
+]
+
+[[package]]
+name = "cc"
+version = "1.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5add81bb678e6cb321aff7fa0dc7689ad82b112dbc032cea19f91d6b8e3582b9"
+dependencies = [
+ "find-msvc-tools",
+ "shlex",
+]
+
+[[package]]
+name = "cfg-if"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
+
+[[package]]
+name = "chunked_transfer"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6e4de3bc4ea267985becf712dc6d9eed8b04c953b3fcfb339ebc87acd9804901"
+
+[[package]]
+name = "compact_str"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9dfdd1c2274d9aa354115b09dc9a901d6c5576818cdf70d14cae2bdb47df00ab"
+dependencies = [
+ "castaway",
+ "cfg-if",
+ "itoa",
+ "rustversion",
+ "ryu",
+ "serde",
+ "static_assertions",
+]
+
+[[package]]
+name = "crossbeam-deque"
+version = "0.8.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5181e0de7b61eb03a81e347d6dd8797bae9da5146707b51077e2d71a54ec0ceb"
+dependencies = [
+ "crossbeam-epoch",
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "crossbeam-epoch"
+version = "0.9.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2d6914041f254d6e9176c01941b21115dcfb7089e55135a35411081bd106ef3f"
+dependencies = [
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "crossbeam-utils"
+version = "0.8.22"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "61803da095bee82a81bb1a452ecc25d3b2f1416d1897eb86430c6159ef717c17"
+
+[[package]]
+name = "crypto-common"
+version = "0.1.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "78c8292055d1c1df0cce5d180393dc8cce0abec0a7102adb6c7b1eef6016d60a"
+dependencies = [
+ "generic-array",
+ "typenum",
+]
+
+[[package]]
+name = "darling"
+version = "0.20.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fc7f46116c46ff9ab3eb1597a45688b6715c6e628b5c133e288e709a29bcb4ee"
+dependencies = [
+ "darling_core",
+ "darling_macro",
+]
+
+[[package]]
+name = "darling_core"
+version = "0.20.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0d00b9596d185e565c2207a0b01f8bd1a135483d02d9b7b0a54b11da8d53412e"
+dependencies = [
+ "fnv",
+ "ident_case",
+ "proc-macro2",
+ "quote",
+ "strsim",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "darling_macro"
+version = "0.20.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fc34b93ccb385b40dc71c6fceac4b2ad23662c7eeb248cf10d529b7e055b6ead"
+dependencies = [
+ "darling_core",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "dary_heap"
+version = "0.3.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8b1e3a325bc115f096c8b77bbf027a7c2592230e70be2d985be950d3d5e60ebe"
+dependencies = [
+ "serde",
+]
+
+[[package]]
+name = "derive_builder"
+version = "0.20.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "507dfb09ea8b7fa618fcf76e953f4f5e192547945816d5358edffe39f6f94947"
+dependencies = [
+ "derive_builder_macro",
+]
+
+[[package]]
+name = "derive_builder_core"
+version = "0.20.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2d5bcf7b024d6835cfb3d473887cd966994907effbe9227e8c8219824d06c4e8"
+dependencies = [
+ "darling",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "derive_builder_macro"
+version = "0.20.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ab63b0e2bf4d5928aff72e83a7dace85d7bba5fe12dcc3c5a572d78caffd3f3c"
+dependencies = [
+ "derive_builder_core",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "digest"
+version = "0.10.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292"
+dependencies = [
+ "block-buffer",
+ "crypto-common",
+ "subtle",
+]
+
+[[package]]
+name = "either"
+version = "1.17.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9e5e8f6c15a24b9a3ee5efec809ccd006d3b30e8b3bb63c39af737c7f87daa1d"
+
+[[package]]
+name = "esaxx-rs"
+version = "0.1.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d817e038c30374a4bcb22f94d0a8a0e216958d4c3dcde369b1439fec4bdda6e6"
+
+[[package]]
+name = "fallible-iterator"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2acce4a10f12dc2fb14a218589d4f1f62ef011b2d0cc4b3cb1bba8e94da14649"
+
+[[package]]
+name = "fallible-streaming-iterator"
+version = "0.1.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7360491ce676a36bf9bb3c56c1aa791658183a54d2744120f27285738d90465a"
+
+[[package]]
+name = "find-msvc-tools"
+version = "0.1.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5baebc0774151f905a1a2cc41989300b1e6fbb29aff0ceffa1064fdd3088d582"
+
+[[package]]
+name = "fnv"
+version = "1.0.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f9eec918d3f24069decb9af1554cad7c880e2da24a9afd88aca000531ab82c1"
+
+[[package]]
+name = "generic-array"
+version = "0.14.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85649ca51fd72272d7821adaf274ad91c288277713d9c18820d8499a7ff69e9a"
+dependencies = [
+ "typenum",
+ "version_check",
+]
+
+[[package]]
+name = "getrandom"
+version = "0.3.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "899def5c37c4fd7b2664648c28120ecec138e4d395b459e5ca34f9cce2dd77fd"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "r-efi",
+ "wasip2",
+]
+
+[[package]]
+name = "hashbrown"
+version = "0.14.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e5274423e17b7c9fc20b6e7e208532f9b19825d82dfd615708b70edd83df41f1"
+dependencies = [
+ "ahash",
+]
+
+[[package]]
+name = "hashlink"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6ba4ff7128dee98c7dc9794b6a411377e1404dba1c97deb8d1a55297bd25d8af"
+dependencies = [
+ "hashbrown",
+]
+
+[[package]]
+name = "httpdate"
+version = "1.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "df3b46402a9d5adb4c86a0cf463f42e19994e3ee891101b1841f30a545cb49a9"
+
+[[package]]
+name = "ident_case"
+version = "1.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b9e0384b61958566e926dc50660321d12159025e767c18e043daf26b70104c39"
+
+[[package]]
+name = "itertools"
+version = "0.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2b192c782037fadd9cfa75548310488aabdbf3d2da73885b31bd0abd03351285"
+dependencies = [
+ "either",
+]
+
+[[package]]
+name = "itoa"
+version = "1.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
+
+[[package]]
+name = "libc"
+version = "0.2.189"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
+
+[[package]]
+name = "libsqlite3-sys"
+version = "0.28.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0c10584274047cb335c23d3e61bcef8e323adae7c5c8c760540f73610177fc3f"
+dependencies = [
+ "cc",
+ "pkg-config",
+ "vcpkg",
+]
+
+[[package]]
+name = "log"
+version = "0.4.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
+
+[[package]]
+name = "macro_rules_attribute"
+version = "0.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b3ae8f6d608c795738406608304d30a2dfbdc8e58e44f7ba43236da5208ded3c"
+dependencies = [
+ "macro_rules_attribute-proc_macro",
+ "pastey",
+]
+
+[[package]]
+name = "macro_rules_attribute-proc_macro"
+version = "0.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fc04a4c58212d57930a24bf47d3fa87485264a3a054e9c10e042eb373573ad3c"
+
+[[package]]
+name = "memchr"
+version = "2.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
+
+[[package]]
+name = "minimal-lexical"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "68354c5c6bd36d73ff3feceb05efa59b6acb7626617f4962be322a825e61f79a"
+
+[[package]]
+name = "monostate"
+version = "0.1.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3341a273f6c9d5bef1908f17b7267bbab0e95c9bf69a0d4dcf8e9e1b2c76ef67"
+dependencies = [
+ "monostate-impl",
+ "serde",
+ "serde_core",
+]
+
+[[package]]
+name = "monostate-impl"
+version = "0.1.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e4db6d5580af57bf992f59068d4ea26fd518574ff48d7639b255a36f9de6e7e9"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "nom"
+version = "7.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d273983c5a657a70a3e8f2a01329822f3b8c8172b73826411a55751e404a0a4a"
+dependencies = [
+ "memchr",
+ "minimal-lexical",
+]
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "onig"
+version = "6.5.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0cc3cbf698f9438986c11a880c90a6d04b9de27575afd28bbf45b154b6c709e2"
+dependencies = [
+ "bitflags",
+ "libc",
+ "once_cell",
+ "onig_sys",
+]
+
+[[package]]
+name = "onig_sys"
+version = "69.9.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e68317604e77e53b85896388e1a803c1d21b74c899ec9e5e1112db90735edd7"
+dependencies = [
+ "cc",
+ "pkg-config",
+]
+
+[[package]]
+name = "palw-gateway"
+version = "0.1.0"
+dependencies = [
+ "blake2",
+ "rusqlite",
+ "serde",
+ "serde_json",
+ "tiny_http",
+ "tokenizers",
+]
+
+[[package]]
+name = "paste"
+version = "1.0.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "57c0d7b74b563b49d38dae00a0c37d4d6de9b432382b2892f0574ddcae73fd0a"
+
+[[package]]
+name = "pastey"
+version = "0.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2ee67f1008b1ba2321834326597b8e186293b049a023cdef258527550b9935b4"
+
+[[package]]
+name = "pkg-config"
+version = "0.3.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "19f132c84eca552bf34cab8ec81f1c1dcc229b811638f9d283dceabe58c5569e"
+
+[[package]]
+name = "ppv-lite86"
+version = "0.2.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85eae3c4ed2f50dcfe72643da4befc30deadb458a9b590d720cde2f2b1e97da9"
+dependencies = [
+ "zerocopy",
+]
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "r-efi"
+version = "5.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "69cdb34c158ceb288df11e18b4bd39de994f6657d83847bdffdbd7f346754b0f"
+
+[[package]]
+name = "rand"
+version = "0.9.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b9ef1d0d795eb7d84685bca4f72f3649f064e6641543d3a8c415898726a57b41"
+dependencies = [
+ "rand_chacha",
+ "rand_core",
+]
+
+[[package]]
+name = "rand_chacha"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d3022b5f1df60f26e1ffddd6c66e8aa15de382ae63b3a0c1bfc0e4d3e3f325cb"
+dependencies = [
+ "ppv-lite86",
+ "rand_core",
+]
+
+[[package]]
+name = "rand_core"
+version = "0.9.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "76afc826de14238e6e8c374ddcc1fa19e374fd8dd986b0d2af0d02377261d83c"
+dependencies = [
+ "getrandom",
+]
+
+[[package]]
+name = "rayon"
+version = "1.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fb39b166781f92d482534ef4b4b1b2568f42613b53e5b6c160e24cfbfa30926d"
+dependencies = [
+ "either",
+ "rayon-core",
+]
+
+[[package]]
+name = "rayon-cond"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2964d0cf57a3e7a06e8183d14a8b527195c706b7983549cd5462d5aa3747438f"
+dependencies = [
+ "either",
+ "itertools",
+ "rayon",
+]
+
+[[package]]
+name = "rayon-core"
+version = "1.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "22e18b0f0062d30d4230b2e85ff77fdfe4326feb054b9783a3460d8435c8ab91"
+dependencies = [
+ "crossbeam-deque",
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "regex"
+version = "1.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f020237b6c8eed93db2e2cb53c00c60a8e1bc73da7d073199a1180401450218d"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-automata",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-automata"
+version = "0.4.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fcfdb36bda0c880c5931cdc7a2bcdc8ba4556847b9d912bca70bc94708711ad"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-syntax"
+version = "0.8.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
+
+[[package]]
+name = "rusqlite"
+version = "0.31.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b838eba278d213a8beaf485bd313fd580ca4505a00d5871caeb1457c55322cae"
+dependencies = [
+ "bitflags",
+ "fallible-iterator",
+ "fallible-streaming-iterator",
+ "hashlink",
+ "libsqlite3-sys",
+ "smallvec",
+]
+
+[[package]]
+name = "rustversion"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f"
+
+[[package]]
+name = "ryu"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9774ba4a74de5f7b1c1451ed6cd5285a32eddb5cccb8cc655a4e50009e06477f"
+
+[[package]]
+name = "serde"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba"
+dependencies = [
+ "serde_core",
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_core"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48"
+dependencies = [
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_derive"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.3",
+]
+
+[[package]]
+name = "serde_json"
+version = "1.0.151"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c841b55ecdae098c80dcae9cf767f6f8a0c2cdb3416bbef72181df4d0fe73f14"
+dependencies = [
+ "itoa",
+ "memchr",
+ "serde",
+ "serde_core",
+ "zmij",
+]
+
+[[package]]
+name = "shlex"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba"
+
+[[package]]
+name = "smallvec"
+version = "1.15.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8ed6a63f02c8539c91a8685a86f4099661ba3da017932f6ebbea6de3f0fa7c90"
+
+[[package]]
+name = "spm_precompiled"
+version = "0.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5851699c4033c63636f7ea4cf7b7c1f1bf06d0cc03cfb42e711de5a5c46cf326"
+dependencies = [
+ "base64",
+ "nom",
+ "serde",
+ "unicode-segmentation",
+]
+
+[[package]]
+name = "static_assertions"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a2eb9349b6444b326872e140eb1cf5e7c522154d69e7a0ffb0fb81c06b37543f"
+
+[[package]]
+name = "strsim"
+version = "0.11.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f"
+
+[[package]]
+name = "subtle"
+version = "2.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "13c2bddecc57b384dee18652358fb23172facb8a2c51ccc10d74c157bdea3292"
+
+[[package]]
+name = "syn"
+version = "2.0.119"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "syn"
+version = "3.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "53e9bae58849f64dfa4f5d5ae372c8341f7305f82a3868709269343628b659a3"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "thiserror"
+version = "2.0.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09a43598840e33d5b0331f38c5e30d13bb11c11210a4b58f0d9b18a5a5eefcd9"
+dependencies = [
+ "thiserror-impl",
+]
+
+[[package]]
+name = "thiserror-impl"
+version = "2.0.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "43cbfe0cf76104d42a574802844187e84a305e531ed54455f11fbde0f10541cd"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.3",
+]
+
+[[package]]
+name = "tiny_http"
+version = "0.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "389915df6413a2e74fb181895f933386023c71110878cd0825588928e64cdc82"
+dependencies = [
+ "ascii",
+ "chunked_transfer",
+ "httpdate",
+ "log",
+]
+
+[[package]]
+name = "tokenizers"
+version = "0.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a620b996116a59e184c2fa2dfd8251ea34a36d0a514758c6f966386bd2e03476"
+dependencies = [
+ "ahash",
+ "aho-corasick",
+ "compact_str",
+ "dary_heap",
+ "derive_builder",
+ "esaxx-rs",
+ "getrandom",
+ "itertools",
+ "log",
+ "macro_rules_attribute",
+ "monostate",
+ "onig",
+ "paste",
+ "rand",
+ "rayon",
+ "rayon-cond",
+ "regex",
+ "regex-syntax",
+ "serde",
+ "serde_json",
+ "spm_precompiled",
+ "thiserror",
+ "unicode-normalization-alignments",
+ "unicode-segmentation",
+ "unicode_categories",
+]
+
+[[package]]
+name = "typenum"
+version = "1.20.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6f5e870be6c3b371b77fe0ee0bafb859fa4964b4404c27de1d380043c4dda20"
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "unicode-normalization-alignments"
+version = "0.1.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "43f613e4fa046e69818dd287fdc4bc78175ff20331479dab6e1b0f98d57062de"
+dependencies = [
+ "smallvec",
+]
+
+[[package]]
+name = "unicode-segmentation"
+version = "1.13.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c6f5d3c3b1bf09027a88a6bc961fc00497d651009560b5463668dc81b0fa87a8"
+
+[[package]]
+name = "unicode_categories"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "39ec24b3121d976906ece63c9daad25b85969647682eee313cb5779fdd69e14e"
+
+[[package]]
+name = "vcpkg"
+version = "0.2.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "accd4ea62f7bb7a82fe23066fb0957d48ef677f6eeb8215f372f52e48bb32426"
+
+[[package]]
+name = "version_check"
+version = "0.9.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
+
+[[package]]
+name = "wasip2"
+version = "1.0.4+wasi-0.2.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b67efb37e106e55ce722a510d6b5f9c17f083e5fc79afc2badeb12cc313d9487"
+dependencies = [
+ "wit-bindgen",
+]
+
+[[package]]
+name = "wit-bindgen"
+version = "0.57.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ebf944e87a7c253233ad6766e082e3cd714b5d03812acc24c318f549614536e"
+
+[[package]]
+name = "zerocopy"
+version = "0.8.55"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b5a105cd7b140f6eeec8acff2ea38135d3cab283ada58540f629fe51e46696eb"
+dependencies = [
+ "zerocopy-derive",
+]
+
+[[package]]
+name = "zerocopy-derive"
+version = "0.8.55"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0fe976fb70c78cd64cccfe3a6fc142244e8a77b70959b30faf9d0ac37ee228eb"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "zmij"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"

palw-gateway/Cargo.toml

@@ -0,0 +1,30 @@
+[package]
+name = "palw-gateway"
+version = "0.1.0"
+edition = "2021"
+# Matches runtime-palw's honest floor (see its Cargo.toml note).
+rust-version = "1.85"
+description = "PALW Desktop UX Phase 0 — resident streaming inference gateway + conversation session layer"
+license = "Apache-2.0"
+
+[workspace]
+
+[[bin]]
+name = "palw-gateway"
+path = "src/main.rs"
+
+[dependencies]
+# HTTP with hand-rolled SSE: tiny_http is synchronous, dependency-light, and lets one
+# thread own one response stream — exactly the shape a token stream needs. No async runtime.
+tiny_http = "0.12"
+# The session layer database. Bundled, like runtime-palw's state_store.
+rusqlite = { version = "0.31", features = ["bundled"] }
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+# The HF tokenizer (reads the pinned tokenizer.json). The repo has NO Rust encoder today —
+# the Explore survey confirmed decode-only — so this is a required new dependency.
+tokenizers = { version = "0.21", default-features = false, features = ["onig"] }
+blake2 = "0.10"
+
+[profile.release]
+opt-level = 2

palw-gateway/README.md

@@ -0,0 +1,223 @@
+# palw-gateway — PALW Desktop UX Phase 0 + Phase 1 + Phase 2 worker + LM Studio bridge
+
+The resident streaming inference gateway + Conversation Session Layer (Phase 0), plus the
+Phase-1 product layers of `docs/palw-desktop-product-architecture.md`: Context Compiler v1,
+project workspace, long-term memory, content-addressed artifacts with version chains, the
+three-mode tool runtime with sandbox, the five-priority resource scheduler, and the
+settlement-clock writer (verification transitions / mismatch cascade / certified head).
+Replaces the session-less, globally-locked `docs/evidence/qi35_lmstudio_server.py`; reuses
+the `qi35_model --serve` integer engine untouched (forward pass + KV snapshot + speculative
+decode — the survey's "reuse core, rewrite serving loop" verdict).
+
+## What it adds (none of which existed in the repo)
+
+- **Conversation Session Layer** (`store.rs`): turns, branches, dual heads
+  (`local_head`/`certified_head`), `TurnVerificationStatus` + `TurnPrivacyMode` columns
+  from day one so UX Phase 2 (PALW settlement) writes existing columns, never migrates.
+  SQLite hardened with the `runtime-palw/state_store.rs` pattern (own `application_id`,
+  WAL, `synchronous=FULL`, foreign keys).
+- **Token-id-stable history** (`context.rs`): the fix for the live bug the survey found —
+  the old stack rebuilt each prompt by `decode(gen)`→retokenize, which is NOT id-stable,
+  so the engine's longest-prefix cache missed on every multi-turn exchange. Here history
+  is assembled by concatenating STORED ids across ChatML fragment boundaries (each starts
+  with a special token the BPE never merges across), so turn N+1's prompt literally begins
+  with turn N's ids and the cache HITS. Verified live: turn 2 reported
+  `cache_hit_tokens=83` of a 101-token prompt (~1.9 s vs turn 1's 12.7 s).
+- **Display/model separation**: `display_text` (UI) and `prompt_ids`/`output_ids` (model)
+  are different columns, so receipt/search footers can never leak into the next prompt
+  (the other live bug the survey found).
+- **`GenerationEventV1` SSE** (`events.rs`, `http.rs`): the design doc's frozen wire type.
+  Two clocks kept separate — answer latency (streamed tokens) vs settlement latency
+  (`TurnVerificationStatus`, owned by the Phase-2 supervisor).
+- **Cancel = v1 semantics**: partial answer kept, turn marked `MintIneligible`
+  (B cannot reproduce the user's stop instant).
+
+## Phase 1 (this build)
+
+- **Context Compiler v1** (`context.rs`): system region = base prompt + project
+  instructions (§10) + memory snapshot (§12), stable-first for cacheability; attachments
+  and executed tool results render into the TURN's user block (like pasted text), so
+  attaching a file to turn N never invalidates turns 1..N-1's prefix. Deterministic
+  keyword chunk selection (`keyword-chunks-v1`) bounds each attachment; what was included
+  (memory snapshot root, memory ids, chunk selections, policies, dropped turns) lands in
+  `context_meta_json` on the turn — the future receipt commitment surface. The exact
+  rendered block is persisted (`user_block_text`) so later compiles reproduce identical
+  ids; legacy v1 rows fold back to the raw user text, byte-identical.
+- **Artifact store** (`artifact.rs` + schema): content-addressed blobs (blake2b-256,
+  temp+fsync+rename), verified reads, version chains with DERIVED version numbers (§8/§9),
+  parser policy `utf8-text-v1` (the only v1 parser; recorded per artifact).
+- **Tool runtime + sandbox** (`tools.rs`, §6/§17): `DeterministicReplay` (exact-i128
+  calculator) and `SnapshotReadOnly` (read_file/list_dir) execute immediately and are
+  snapshotted as artifacts; `ExactlyOnceSideEffect` (write_file/run_command) is stored as
+  a PROPOSAL and only runs through approve → the store's atomic `approved→executing`
+  claim, so a side effect can never fire twice. Sandbox: canonicalize-then-scope-check
+  paths (symlink escape refused), workspace-relative writes only, ABSOLUTE-path command
+  allowlist (no PATH lookup), cleared child env, wall-clock timeout, output caps. Honest
+  v1 limit: no kernel-level network isolation for spawned commands — the allowlist is the
+  network policy.
+- **Resource scheduler** (`scheduler.rs`, §14): five-priority queue in front of the
+  engine (foreground chat overtakes any queued background work; FIFO within a class), no
+  mid-generation preemption (engine has no stop channel — worst case = one background
+  generation), decode-rate EMA, and the SLA admission probe the Phase-2 replica worker
+  must call BEFORE accepting an assignment (refusing beats no-showing).
+- **Settlement-clock writer** (`store.rs`, §4): legal-transition machine
+  (`local_complete → replica_pending → replica_matched → [audit_pending →] certified →
+  matured`, mismatch reachable from the replica/audit states), LocalOnly turns barred from
+  the replica pipeline, mismatch cascades `MintIneligible` to every descendant (local
+  conversation survives; the reward dependency chain does not), `certified_head` = deepest
+  turn whose whole prefix is certified — out-of-order certifications do not advance it
+  past a gap.
+- **Schema v2 migration**: additive, in-place, v1 databases keep serving byte-identical
+  history.
+- **Streaming termination fix** (latent Phase-0 bug): SSE bodies are now
+  `Transfer-Encoding: chunked` with a terminating zero-chunk. tiny_http's `into_writer`
+  never closes the socket on drop (it parks the connection for keep-alive), so the old
+  bare-framed stream left generic clients (curl, fetch, EventSource) hanging for EOF after
+  `[DONE]`; the plugin never noticed because it aborts the connection itself. The zero-chunk
+  ends the response on the wire and the connection stays legitimately reusable.
+
+## Phase 2: background worker (§15)
+
+`worker.rs` is a STATELESS RECONCILER — no durable worker state, the session store is the
+single source of truth, and every cycle recomputes the work:
+
+1. **A-commits**: turns `local_complete` ∧ privacy ∈ {verified_no_mint, palw_mint} →
+   `submit_job` (idempotent by job id) → `replica_pending`. Crash between submit and the
+   store write heals on the next cycle's re-submit; §15's restart recovery is structural,
+   not a feature.
+2. **Verdicts**: turns in the pipeline → `fetch_verdicts` → legal transitions only
+   (`steps_to` walks intermediate states, e.g. a `certified` verdict against a
+   `replica_pending` turn applies matched→certified; stale verdicts are ignored).
+3. **B replicas**: `fetch_assignments` → §14 admission probe FIRST (refuse ⇒ decline with
+   reason — refusing beats no-showing) → §5-v1 Full Context replay on the engine at
+   `ReplicaJob` priority → result root.
+
+The coordinator is a TRAIT (`coordinator.rs`) with two implementations, because the real
+counterparty — the MISAKA node's PALW surface — is not finished:
+
+- **`LoopbackCoordinator`** (enable with `--palw-loopback`): a complete in-process
+  coordinator (submit → assign → result → matched → certified; mismatch; deadline
+  requeue; decline requeue), also SERVED over HTTP at `/v1/palw/loopback/*` so a second
+  gateway instance can run a genuine two-instance A/B loop against it. It is a dev
+  harness, NOT consensus: no beacons, bonds, DA retention, or rewards, and its verdicts
+  certify plumbing, not economics. Single-instance self-replica (default on) shares the
+  engine and its prefix cache — it validates the pipeline, never replica independence.
+  `Matured` is chain state (coinbase maturity) and is never synthesized here.
+- **`HttpCoordinator`** (`--palw-coordinator <base-url>`): client half of the same JSON
+  protocol — point it at another gateway's loopback, or at the node-side bridge once the
+  protocol features land there. Plain HTTP/1.1, `Connection: close`, no TLS: a
+  localhost/LAN dev transport that the production node binding replaces.
+
+### PALW coordinator protocol (JSON, v1)
+
+```
+POST {base}/jobs              {job_id, provider_id, prompt_ids, max_new, output_root,
+                               receipt_json?, runtime_roots?: {route, kv, state}}
+                              → {accepted:true}          (idempotent by job_id)
+POST {base}/verdicts          {job_ids:[…]}
+                              → {verdicts:[{job_id, verdict: replica_matched|certified|mismatch}]}
+                                (pending jobs are absent; matched is reported exactly once,
+                                 then promotes to certified)
+GET  {base}/assignments?provider_id=X
+                              → {assignments:[{job_id, prompt_ids, max_new, deadline_unix_ms}]}
+                                (claimed on fetch; deadline lapse or decline requeues)
+POST {base}/assignments/{job_id}/decline   {provider_id, reason}   → {declined:true}
+POST {base}/replica-results   {job_id, provider_id, output_root, runtime_roots?}
+                              → {recorded:true}
+                                (output_root = blake2b-256 over little-endian u32 output ids)
+```
+
+`runtime_roots` are the engine's per-generation execution commitments (`ROOTS route= kv=
+state=`, emitted under `QI35_SERVE_ROOTS`, which the engine host always sets): the MoE
+routing-trace root, the KV-cache root, and the recurrent-state root. When a submitter
+commits them, an honest replica must reproduce them — the match then covers execution
+STRUCTURE, not just output ids. The loopback matches leniently when the submitter omitted
+them; the node-side bridge (below) refuses rootless submissions outright.
+
+**The node-side server of this protocol is `misaka-palw-bridge`** (MisakaLLM workspace,
+`mil/bridge`): durable hash-chained journal, submitter ≠ replica enforced with no
+opt-out, and the match decided by the node's real eight-field
+`ReplicaMatchKey`/`run_replica_k2` (ADR-0039 §7.5) built over these roots. Point
+`--palw-coordinator http://host:26621/palw/v1` at it. A permanent protocol rejection
+(HTTP 400, e.g. a rootless pre-v3 turn against the class-strict bridge) marks the turn
+`mint_ineligible` instead of retrying forever.
+
+Verified end-to-end on real hardware: a `palw_mint` chat turn answered by the 35B engine
+in 11.2 s (model load included), then in the background: A-commit → self-assigned replica
+re-executed on the engine → roots matched → `certified` → `certified_head` advanced —
+answer clock and settlement clock visibly separate. Cross-process: two instances over
+real HTTP, with the replica root computed independently (Python blake2b) matching the
+Rust root, drove `replica_pending → replica_matched → certified` on the A side.
+
+## Endpoints
+
+- `GET /healthz`, `GET /v1/models` — supervisor probes (the LM Studio plugin's
+  `ensureServer()` polls `/healthz` unchanged; `engine_resident` in the body is also how the
+  plugin distinguishes this gateway from the legacy python server).
+- `POST /v1/chat/completions` — OpenAI-compatible SSE, STATELESS (client owns transcript).
+- `POST /v1/lmstudio/turn` — the LM Studio bridge (`lmstudio.rs`): body
+  `{messages, privacy_mode?}`; the client-owned transcript is resolved onto the session store
+  BY CONTENT (normalized text match, `<think>`/status blocks stripped) —
+  `continued` on the active branch (prefix cache hits), `branched` sibling on edit/regenerate,
+  or a new conversation with foreign history imported as `mint_ineligible` turns — then the
+  turn runs the NATIVE pipeline (id-stable prompt, receipt, ROOTS, settlement). The
+  `GenerationEventV1` stream is prefixed with one `lmstudio_resolve` frame that carries the
+  resolution and the parent turn's current settlement state.
+- `GET /v1/turns/{id}` — settlement status + receipt summary + runtime roots (the plugin's
+  post-answer poll target); `GET /v1/turns/{id}/receipt` — the engine receipt JSON verbatim.
+- `--receipt-dir <dir>`: every turn with a receipt also writes
+  `turn-<turn_id>-<oc16>.receipt.json` + `.opening.json` sidecars (0600; opening =
+  `qi35-gateway-opening/v1` with exact prompt/output ids + tokenizer digest + roots), the file
+  form offline verifiers consume — plus `.search.json` (bundle + `receipt_binding`) when the
+  turn searched.
+- `--search-cmd <program>`: GPT-style live search on the bridge path via a stdin/stdout JSON
+  sidecar (`docs/evidence/qi35_search_sidecar.py` reuses the whole legacy stack — routing,
+  SSRF-guarded page fetch, canonical `live_search_bundle_v1`, typed failure bundles).
+  Fail-open: sidecar-level errors degrade to a searchless turn. The rendered evidence joins
+  the TURN's user block (`user + "\n\n" + evidence`), so `prompt_commitment` covers the
+  bundle digest transitively (no receipt schema change); the bundle persists on the turn
+  (schema v4 `turns.search_bundle_json`) and streams to the client as a `search_status`
+  frame. B replicas replay A's committed ids — the snapshot, never a re-search.
+- `POST /v1/sessions` (`title`, `project_id`?), `GET /v1/sessions`,
+  `GET /v1/sessions/{id}/history` — session mgmt.
+- `POST /v1/sessions/{id}/messages` — the NATIVE turn endpoint (id-stable prompt compile,
+  `GenerationEventV1` stream). `parent_turn_id` ≠ head → branch/edit/regenerate. Body also
+  takes `privacy_mode`, `artifact_ids` (attachments), `tool_call_ids` (executed calls).
+- `POST /v1/sessions/{id}/head` — move `local_head` (branch switching).
+- `POST /v1/jobs/{job}/cancel` — cancel an in-flight generation.
+- `POST/GET /v1/projects`, `POST /v1/projects/{id}/instructions` — workspace layer.
+- `POST/GET /v1/memory`, `POST /v1/memory/{id}/delete` — long-term memory (soft delete;
+  namespace = `global` or a project id; both compile into the system region).
+- `POST /v1/artifacts?name=&project_id=&parent_artifact_id=` (raw body),
+  `GET /v1/artifacts`, `GET /v1/artifacts/{id}` (verified bytes),
+  `GET /v1/artifacts/{id}/meta` (meta + lineage + children).
+- `GET /v1/tools`, `POST /v1/tools/execute`, `POST /v1/tools/calls/{id}/approve|deny`,
+  `GET /v1/tools/calls/{id}` — the three-mode tool surface.
+- `GET /v1/scheduler/status`, `POST /v1/scheduler/admission` — §14 observability + SLA
+  admission probe.
+- `POST /v1/turns/{id}/verification` — settlement-clock transitions (manual/supervisor
+  writes; returns cascade + new certified head). The background worker drives the same
+  store machinery internally.
+- `GET /v1/palw/status` — worker counters + loopback job counts.
+- `/v1/palw/loopback/*` — the coordinator protocol above (404 unless `--palw-loopback`).
+
+## Not in this build (stated honestly)
+
+- Embedding-based RAG (§11's full form) — attachment retrieval is deterministic keyword
+  chunking; an embedding index is a separate subsystem.
+- Model-EMITTED tool calls / agent loops (§7, Phase 3) — tools are client-invoked; wiring
+  tool schemas into the canonical ChatML template changes the Compute Set prompt format
+  and belongs with the consensus-side template freeze.
+- The consensus half of settlement: beacons, provider bonds, DA retention, auditor
+  lottery, rewards/maturity, and the node RPC binding. The worker's coordinator trait is
+  the seam where the node-side bridge plugs in; the loopback coordinator stands in for it
+  and proves nothing about economics or replica independence.
+- Kernel-level sandbox isolation (network namespaces, rlimits) for `run_command`.
+
+## Run
+
+```
+palw-gateway --gguf <gguf> --tables docs/evidence/qi35_tables.bin \
+  --tokenizer models/.../tokenizer.json --engine docs/evidence/qi35_model \
+  --listen 127.0.0.1:12346 --db sessions.sqlite3
+```

palw-gateway/src/artifact.rs

@@ -0,0 +1,139 @@
+//! Content-addressed artifact blob store (design doc §8) — bytes on disk, addressed by
+//! blake2b-256 of the content, metadata in the session store.
+//!
+//! Properties the doc requires and this layout provides:
+//! * **Content-addressed**: the same bytes stored twice are one file; the hash IS the address,
+//!   so a stored artifact can always be re-verified against its own name.
+//! * **Crash-safe writes** (§18): write to a temp file in the same directory, fsync, rename —
+//!   a torn write can leave garbage temp files, never a wrong blob under a valid hash.
+//! * **Parser canonicalization** (§8 正準化): v1 ships exactly one parser policy,
+//!   `utf8-text-v1` — the parsed content of a text artifact is its bytes verbatim, so
+//!   `parsed_content_root == content_hash`. PDF/DOCX/OCR parsers are future policies; the field
+//!   exists so a receipt can commit WHICH parser produced the tokens the model saw.
+//!
+//! Layout: `<root>/<hash[0..2]>/<hash>` — one fan-out level keeps directories small without
+//! nested churn.
+
+use std::io::Write;
+use std::path::{Path, PathBuf};
+
+use blake2::{Blake2b, Digest, digest::consts::U32};
+
+/// The one parser policy v1 ships (see module docs).
+pub const PARSER_POLICY_UTF8_TEXT_V1: &str = "utf8-text-v1";
+
+pub struct ArtifactBlobStore {
+    root: PathBuf,
+}
+
+pub fn content_hash_hex(bytes: &[u8]) -> String {
+    let mut h = Blake2b::<U32>::new();
+    h.update(bytes);
+    h.finalize().iter().map(|b| format!("{b:02x}")).collect()
+}
+
+impl ArtifactBlobStore {
+    pub fn open(root: &Path) -> Result<Self, String> {
+        std::fs::create_dir_all(root).map_err(|e| format!("create {}: {e}", root.display()))?;
+        Ok(Self { root: root.to_path_buf() })
+    }
+
+    fn blob_path(&self, hash: &str) -> Result<PathBuf, String> {
+        // The hash is used as a path component; refuse anything that is not plain lowercase hex
+        // so a crafted "hash" can never traverse.
+        if hash.len() != 64 || !hash.bytes().all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b)) {
+            return Err(format!("not a blake2b-256 hex hash: {hash:?}"));
+        }
+        Ok(self.root.join(&hash[..2]).join(hash))
+    }
+
+    /// Store bytes; returns the content hash. Idempotent — an existing blob is left untouched
+    /// (same hash ⇒ same bytes, modulo verify-detectable disk tampering).
+    pub fn put(&self, bytes: &[u8]) -> Result<String, String> {
+        let hash = content_hash_hex(bytes);
+        let path = self.blob_path(&hash)?;
+        if path.exists() {
+            return Ok(hash);
+        }
+        let dir = path.parent().expect("blob path has a parent");
+        std::fs::create_dir_all(dir).map_err(|e| format!("create {}: {e}", dir.display()))?;
+        let tmp = dir.join(format!(".tmp-{}-{}", std::process::id(), &hash[..16]));
+        {
+            let mut f = std::fs::File::create(&tmp).map_err(|e| format!("create {}: {e}", tmp.display()))?;
+            f.write_all(bytes).map_err(|e| format!("write {}: {e}", tmp.display()))?;
+            f.sync_all().map_err(|e| format!("fsync {}: {e}", tmp.display()))?;
+        }
+        std::fs::rename(&tmp, &path).map_err(|e| format!("rename into {}: {e}", path.display()))?;
+        Ok(hash)
+    }
+
+    pub fn get(&self, hash: &str) -> Result<Vec<u8>, String> {
+        let path = self.blob_path(hash)?;
+        std::fs::read(&path).map_err(|e| format!("artifact blob {hash}: {e}"))
+    }
+
+    /// Read AND re-hash — the §19 "hash verification" primitive. A blob whose bytes no longer
+    /// match its address (disk corruption, tampering) is an error, never silently returned.
+    pub fn get_verified(&self, hash: &str) -> Result<Vec<u8>, String> {
+        let bytes = self.get(hash)?;
+        let actual = content_hash_hex(&bytes);
+        if actual != hash {
+            return Err(format!("artifact blob {hash} fails verification (bytes hash to {actual}) — refusing to serve"));
+        }
+        Ok(bytes)
+    }
+
+    /// The `utf8-text-v1` parse: the artifact's bytes as UTF-8 text, or an error explaining the
+    /// artifact cannot enter model context under v1's only parser policy.
+    pub fn parse_utf8_text(&self, hash: &str) -> Result<String, String> {
+        let bytes = self.get_verified(hash)?;
+        String::from_utf8(bytes)
+            .map_err(|_| format!("artifact {hash} is not valid UTF-8 — parser policy {PARSER_POLICY_UTF8_TEXT_V1} cannot place it in context"))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn store_at(name: &str) -> ArtifactBlobStore {
+        let dir = std::env::temp_dir().join(format!("palw-gw-blob-{}-{name}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        ArtifactBlobStore::open(&dir).unwrap()
+    }
+
+    #[test]
+    fn roundtrip_idempotent_and_verified() {
+        let s = store_at("roundtrip");
+        let h1 = s.put(b"hello artifact").unwrap();
+        let h2 = s.put(b"hello artifact").unwrap();
+        assert_eq!(h1, h2, "content-addressed: same bytes, same address");
+        assert_eq!(s.get_verified(&h1).unwrap(), b"hello artifact");
+        assert_eq!(s.parse_utf8_text(&h1).unwrap(), "hello artifact");
+    }
+
+    #[test]
+    fn tampered_blob_is_refused() {
+        let s = store_at("tamper");
+        let h = s.put(b"original bytes").unwrap();
+        let path = s.blob_path(&h).unwrap();
+        std::fs::write(&path, b"tampered bytes!").unwrap();
+        assert!(s.get_verified(&h).is_err(), "bytes no longer matching the address must not be served");
+    }
+
+    #[test]
+    fn hash_is_validated_as_path_component() {
+        let s = store_at("path");
+        assert!(s.get("../../etc/passwd").is_err());
+        assert!(s.get("ABCDEF").is_err());
+    }
+
+    #[test]
+    fn non_utf8_cannot_enter_context() {
+        let s = store_at("utf8");
+        let h = s.put(&[0xff, 0xfe, 0x00]).unwrap();
+        assert!(s.parse_utf8_text(&h).is_err());
+        // …but the blob itself is stored and retrievable (it can live as an attachment).
+        assert_eq!(s.get_verified(&h).unwrap(), vec![0xff, 0xfe, 0x00]);
+    }
+}

palw-gateway/src/context.rs

@@ -0,0 +1,635 @@
+//! Context Compiler v1 (design doc §2) + Token Budget Manager (§3) + the Phase-1 inputs:
+//! project instructions (§10), memory snapshot (§12), attachments with deterministic chunk
+//! selection (§8/§11), tool results (§6).
+//!
+//! THE invariant this module exists to enforce (from the Explore survey's root-cause): model
+//! history is assembled from STORED TOKEN IDS, never from detokenized text. The current stack
+//! re-tokenized `decode(gen).strip()` each turn, which is not id-stable, so the engine's prefix
+//! cache missed on every multi-turn exchange and the whole transcript re-prefilled every time.
+//!
+//! Canonical fragment assembly:
+//!
+//! ```text
+//! enc("<|im_start|>system\n{SYS}{project}{memory}<|im_end|>\n")       — per conversation state
+//! per past turn:
+//!   enc("<|im_start|>user\n{B}<|im_end|>\n<|im_start|>assistant\n")   — B is the turn's STORED
+//!                                                                       user block (material +
+//!                                                                       user text), re-encoded
+//!   stored output_ids (EOS stripped)                                  — never re-tokenized
+//!   enc("<|im_end|>\n")                                               — constant, cached
+//! current turn:
+//!   enc("<|im_start|>user\n{B_now}<|im_end|>\n<|im_start|>assistant\n")
+//! ```
+//!
+//! Every fragment BOUNDARY starts with a special token (`<|im_start|>`/`<|im_end|>`), which the
+//! tokenizer never merges across, so fragment-wise encoding is stable under concatenation. Turn
+//! N+1's prompt literally starts with turn N's prompt+output ids, so the engine's
+//! longest-prefix cache HITS across turns — as long as the system region (base + project
+//! instructions + memory) is unchanged. Editing memory/instructions changes token 0 onward and
+//! honestly costs one full re-prefill; that is inherent, not a bug.
+//!
+//! Attachments and tool results are rendered INTO the turn's user block (like a user pasting
+//! text), not into the system region — so attaching a file to turn N leaves turns 1..N-1's
+//! prefix intact. The exact rendered block is persisted per turn (`user_block_text`) and re-used
+//! verbatim by later compiles; with no material the block IS the raw user text, byte-identical
+//! to what the v1 schema produced.
+//!
+//! Budget v0 (§3, the doc's "初期版" verbatim): keep system, keep the current message, drop
+//! OLDEST turns whole — never split a message mid-token, never auto-summarize. Attachments are
+//! bounded per file by deterministic keyword chunk selection (§11's retrieval snapshot in
+//! miniature: policy id, selected chunk indexes, and the roots all land in `context_meta_json`,
+//! which is the future receipt commitment surface).
+
+use blake2::{Blake2b, Digest, digest::consts::U32};
+use serde::Serialize;
+
+use crate::store::StoredTurn;
+use crate::tokenizer::TokenizerHost;
+
+pub const CONTEXT_POLICY_ID: &str = "compile-v1";
+pub const MEMORY_POLICY_ID: &str = "memory-all-active-v1";
+pub const RETRIEVAL_POLICY_ID: &str = "keyword-chunks-v1";
+
+/// Chunk granularity for attachment selection (lines per chunk).
+const CHUNK_LINES: usize = 30;
+
+pub struct ContextCompiler {
+    system_prompt: String,
+    im_end_nl_ids: Vec<u32>,
+    pub max_context_tokens: usize,
+    pub reserved_output_tokens: usize,
+    /// Per-attachment character budget (chunk selection kicks in above it).
+    pub max_file_chars: usize,
+    /// Per-tool-result character budget (head-truncated above it).
+    pub max_tool_chars: usize,
+}
+
+pub struct MemoryForContext {
+    pub memory_id: String,
+    pub content: String,
+}
+
+pub struct AttachmentForContext {
+    pub artifact_id: String,
+    pub display_name: String,
+    pub content_hash: String,
+    pub text: String,
+}
+
+pub struct ToolResultForContext {
+    pub call_id: String,
+    pub tool_name: String,
+    pub text: String,
+}
+
+#[derive(Default)]
+pub struct ContextInputs<'a> {
+    pub project_instructions: Option<&'a str>,
+    pub memory: &'a [MemoryForContext],
+    pub attachments: &'a [AttachmentForContext],
+    pub tool_results: &'a [ToolResultForContext],
+    pub history: &'a [StoredTurn],
+    pub user_text: &'a str,
+    /// Rendered live-search evidence for THIS turn. Appended after the user text inside the
+    /// user block (the legacy `build_prompt_text` convention: `user + "\n\n" + evidence`), so
+    /// the committed prompt ids — and therefore the receipt's prompt commitment — cover the
+    /// bundle digest line transitively.
+    pub search: Option<SearchForContext>,
+}
+
+#[derive(Clone)]
+pub struct SearchForContext {
+    pub evidence_text: String,
+    pub bundle_sha256: String,
+    pub effective_compression: String,
+}
+
+#[derive(Serialize)]
+struct AttachmentMeta {
+    artifact_id: String,
+    content_hash: String,
+    chunks_total: u32,
+    chunks_selected: Vec<u32>,
+}
+
+#[derive(Serialize)]
+struct SearchMetaV1 {
+    bundle_sha256: String,
+    effective_compression: String,
+}
+
+/// What the compiler actually put in front of the model — stored on the turn row; this is the
+/// surface a Phase-2 receipt commits (roots, policies, selections), never UI state.
+#[derive(Serialize)]
+struct ContextMetaV1 {
+    context_policy: &'static str,
+    memory_policy: &'static str,
+    retrieval_policy: &'static str,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    memory_snapshot_root: Option<String>,
+    memory_ids: Vec<String>,
+    attachments: Vec<AttachmentMeta>,
+    tool_calls: Vec<String>,
+    dropped_turns: u32,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    search: Option<SearchMetaV1>,
+}
+
+pub struct CompiledPrompt {
+    pub ids: Vec<u32>,
+    /// How many leading ids are the system region (the engine's `cache_prefix_len` convention —
+    /// this snapshot boundary is stable for the conversation until memory/instructions change).
+    pub system_prefix_len: usize,
+    /// Turns dropped by the budget, oldest-first (surfaced to the client, never silent).
+    pub dropped_turns: usize,
+    /// The EXACT text encoded into the current turn's user block — persist this on the turn so
+    /// later compiles reproduce the same ids.
+    pub user_block_text: String,
+    pub context_meta_json: String,
+}
+
+/// blake2b-256 over `id \n content \n` per entry, in snapshot order — the §12 memory snapshot
+/// root (only what was USED this turn is committed, never the whole memory DB).
+pub fn memory_snapshot_root(memory: &[MemoryForContext]) -> Option<String> {
+    if memory.is_empty() {
+        return None;
+    }
+    let mut h = Blake2b::<U32>::new();
+    for m in memory {
+        h.update(m.memory_id.as_bytes());
+        h.update(b"\n");
+        h.update(m.content.as_bytes());
+        h.update(b"\n");
+    }
+    Some(h.finalize().iter().map(|b| format!("{b:02x}")).collect())
+}
+
+pub struct ChunkSelection {
+    pub chunks_total: u32,
+    pub chunks_selected: Vec<u32>,
+    pub rendered: String,
+}
+
+/// Deterministic keyword chunk selection (`keyword-chunks-v1`): split into fixed line-blocks,
+/// score each by occurrences of the query's terms (lowercased, ≥3 chars, deduped), select
+/// best-first until the char budget is spent, render in DOCUMENT order with `…` gap markers.
+/// No embeddings, no randomness, no clock — B recomputes the identical selection from the same
+/// (text, query, budget).
+pub fn select_chunks(text: &str, query: &str, budget_chars: usize) -> ChunkSelection {
+    if text.chars().count() <= budget_chars {
+        return ChunkSelection { chunks_total: 1, chunks_selected: vec![0], rendered: text.to_string() };
+    }
+    let lines: Vec<&str> = text.lines().collect();
+    let chunks: Vec<String> = lines.chunks(CHUNK_LINES).map(|c| c.join("\n")).collect();
+
+    let mut terms: Vec<String> = query
+        .to_lowercase()
+        .split(|c: char| !c.is_alphanumeric())
+        .filter(|t| t.chars().count() >= 3)
+        .map(String::from)
+        .collect();
+    terms.sort();
+    terms.dedup();
+
+    let mut scored: Vec<(usize, u64)> = chunks
+        .iter()
+        .enumerate()
+        .map(|(i, chunk)| {
+            let lower = chunk.to_lowercase();
+            let score: u64 = terms.iter().map(|t| lower.matches(t.as_str()).count() as u64).sum();
+            (i, score)
+        })
+        .collect();
+    // Best score first; document order breaks ties — fully deterministic.
+    scored.sort_by(|a, b| b.1.cmp(&a.1).then(a.0.cmp(&b.0)));
+
+    let mut selected: Vec<usize> = Vec::new();
+    let mut remaining = budget_chars;
+    for (i, _score) in &scored {
+        let cost = chunks[*i].chars().count();
+        if cost <= remaining {
+            selected.push(*i);
+            remaining -= cost;
+        }
+    }
+    if selected.is_empty() {
+        // Even the best chunk alone is over budget: hard-truncate it at a char boundary rather
+        // than sending nothing.
+        let best = scored.first().map(|(i, _)| *i).unwrap_or(0);
+        let truncated: String = chunks[best].chars().take(budget_chars).collect();
+        return ChunkSelection { chunks_total: chunks.len() as u32, chunks_selected: vec![best as u32], rendered: truncated };
+    }
+    selected.sort();
+
+    let mut rendered = String::new();
+    let mut prev: Option<usize> = None;
+    for i in &selected {
+        if let Some(p) = prev {
+            if *i != p + 1 {
+                rendered.push_str("\n…\n");
+            } else {
+                rendered.push('\n');
+            }
+        }
+        rendered.push_str(&chunks[*i]);
+        prev = Some(*i);
+    }
+    ChunkSelection {
+        chunks_total: chunks.len() as u32,
+        chunks_selected: selected.iter().map(|i| *i as u32).collect(),
+        rendered,
+    }
+}
+
+fn truncate_chars(text: &str, budget: usize) -> (String, bool) {
+    if text.chars().count() <= budget {
+        (text.to_string(), false)
+    } else {
+        (text.chars().take(budget).collect(), true)
+    }
+}
+
+impl ContextCompiler {
+    pub fn new(
+        tokenizer: &TokenizerHost,
+        system_prompt: &str,
+        max_context_tokens: usize,
+        reserved_output_tokens: usize,
+        max_file_chars: usize,
+        max_tool_chars: usize,
+    ) -> Result<Self, String> {
+        // Validate the constant fragment once up front (encode_lossless refuses what it cannot
+        // commit); the system region itself is compiled per turn now that it carries state.
+        let im_end_nl_ids = tokenizer.encode_lossless("<|im_end|>\n")?;
+        Ok(Self {
+            system_prompt: system_prompt.to_string(),
+            im_end_nl_ids,
+            max_context_tokens,
+            reserved_output_tokens,
+            max_file_chars,
+            max_tool_chars,
+        })
+    }
+
+    fn user_block_ids(&self, tokenizer: &TokenizerHost, block_text: &str) -> Result<Vec<u32>, String> {
+        tokenizer.encode_lossless(&format!("<|im_start|>user\n{block_text}<|im_end|>\n<|im_start|>assistant\n"))
+    }
+
+    fn trimmed_output(output_ids: &[u32], eos_id: u32) -> &[u32] {
+        match output_ids.last() {
+            Some(&last) if last == eos_id => &output_ids[..output_ids.len() - 1],
+            _ => output_ids,
+        }
+    }
+
+    /// The system region text: base prompt, then project instructions, then the memory
+    /// snapshot — stable-first, so the least volatile content owns the earliest (most cacheable)
+    /// token positions.
+    fn system_text(&self, inputs: &ContextInputs) -> String {
+        let mut text = self.system_prompt.clone();
+        if let Some(instructions) = inputs.project_instructions {
+            if !instructions.is_empty() {
+                text.push_str("\n\n[project instructions]\n");
+                text.push_str(instructions);
+            }
+        }
+        if !inputs.memory.is_empty() {
+            text.push_str("\n\n[memory]");
+            for m in inputs.memory {
+                text.push_str("\n- ");
+                text.push_str(&m.content);
+            }
+        }
+        text
+    }
+
+    /// The current turn's user block: attachments (chunk-selected), then tool results, then the
+    /// user's text — material first, question last, and the whole block is what gets persisted.
+    fn build_user_block(&self, inputs: &ContextInputs) -> (String, Vec<AttachmentMeta>) {
+        let mut block = String::new();
+        let mut attachment_meta = Vec::new();
+        for a in inputs.attachments {
+            let selection = select_chunks(&a.text, inputs.user_text, self.max_file_chars);
+            block.push_str(&format!(
+                "[file {} blake2b={} chunks={}/{}]\n",
+                a.display_name,
+                &a.content_hash[..16.min(a.content_hash.len())],
+                selection.chunks_selected.len(),
+                selection.chunks_total
+            ));
+            block.push_str(&selection.rendered);
+            block.push_str("\n[/file]\n");
+            attachment_meta.push(AttachmentMeta {
+                artifact_id: a.artifact_id.clone(),
+                content_hash: a.content_hash.clone(),
+                chunks_total: selection.chunks_total,
+                chunks_selected: selection.chunks_selected,
+            });
+        }
+        for t in inputs.tool_results {
+            let (text, truncated) = truncate_chars(&t.text, self.max_tool_chars);
+            block.push_str(&format!("[tool_result {} call={}]\n", t.tool_name, t.call_id));
+            block.push_str(&text);
+            if truncated {
+                block.push_str("\n[truncated]");
+            }
+            block.push_str("\n[/tool_result]\n");
+        }
+        block.push_str(inputs.user_text);
+        if let Some(search) = &inputs.search {
+            block.push_str("\n\n");
+            block.push_str(&search.evidence_text);
+        }
+        (block, attachment_meta)
+    }
+
+    /// Compile the prompt for a new user message. `inputs.history` is the root-first branch;
+    /// applies budget v0 by dropping oldest turns whole.
+    pub fn compile(&self, tokenizer: &TokenizerHost, inputs: &ContextInputs) -> Result<CompiledPrompt, String> {
+        let system_ids =
+            tokenizer.encode_lossless(&format!("<|im_start|>system\n{}<|im_end|>\n", self.system_text(inputs)))?;
+        let (user_block_text, attachment_meta) = self.build_user_block(inputs);
+        let current_block = self.user_block_ids(tokenizer, &user_block_text)?;
+
+        let budget = self
+            .max_context_tokens
+            .checked_sub(self.reserved_output_tokens)
+            .ok_or("reserved_output_tokens exceeds max_context_tokens")?;
+        let fixed = system_ids.len() + current_block.len();
+        if fixed > budget {
+            return Err(format!(
+                "system region + current message need {fixed} tokens against a {budget}-token input budget — \
+                 shorten the message/attachments or raise max_context"
+            ));
+        }
+
+        // Per-turn fragment cost, newest-last; then take the longest suffix that fits.
+        let mut turn_frags: Vec<(Vec<u32>, &[u32])> = Vec::with_capacity(inputs.history.len());
+        for turn in inputs.history {
+            let block = self.user_block_ids(tokenizer, turn.user_block())?;
+            let out = Self::trimmed_output(&turn.output_ids, tokenizer.eos_id);
+            turn_frags.push((block, out));
+        }
+        let mut kept_from = 0usize;
+        loop {
+            let hist_cost: usize = turn_frags[kept_from..]
+                .iter()
+                .map(|(b, o)| b.len() + o.len() + self.im_end_nl_ids.len())
+                .sum();
+            if fixed + hist_cost <= budget {
+                break;
+            }
+            kept_from += 1;
+            if kept_from > turn_frags.len() {
+                unreachable!("fixed-part fit was checked above");
+            }
+        }
+
+        let mut ids = system_ids.clone();
+        for (block, out) in &turn_frags[kept_from..] {
+            ids.extend_from_slice(block);
+            ids.extend_from_slice(out);
+            ids.extend_from_slice(&self.im_end_nl_ids);
+        }
+        ids.extend_from_slice(&current_block);
+
+        let meta = ContextMetaV1 {
+            context_policy: CONTEXT_POLICY_ID,
+            memory_policy: MEMORY_POLICY_ID,
+            retrieval_policy: RETRIEVAL_POLICY_ID,
+            memory_snapshot_root: memory_snapshot_root(inputs.memory),
+            memory_ids: inputs.memory.iter().map(|m| m.memory_id.clone()).collect(),
+            attachments: attachment_meta,
+            tool_calls: inputs.tool_results.iter().map(|t| t.call_id.clone()).collect(),
+            dropped_turns: kept_from as u32,
+            search: inputs.search.as_ref().map(|s| SearchMetaV1 {
+                bundle_sha256: s.bundle_sha256.clone(),
+                effective_compression: s.effective_compression.clone(),
+            }),
+        };
+        let context_meta_json = serde_json::to_string(&meta).map_err(|e| e.to_string())?;
+
+        Ok(CompiledPrompt {
+            ids,
+            system_prefix_len: system_ids.len(),
+            dropped_turns: kept_from,
+            user_block_text,
+            context_meta_json,
+        })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::events::{TurnPrivacyMode, TurnVerificationStatus};
+
+    /// EOS-stripping is what lets a stored answer sit INSIDE a longer prompt: the `<|im_end|>\n`
+    /// fragment provides the turn boundary, so the answer's own EOS must not be duplicated. A
+    /// mistrimmed output would put two end markers back-to-back and desync every downstream id.
+    #[test]
+    fn trimmed_output_drops_exactly_one_trailing_eos() {
+        assert_eq!(ContextCompiler::trimmed_output(&[10, 20, 99], 99), &[10, 20]);
+        // No EOS present (e.g. a max_tokens stop) ⇒ untouched.
+        assert_eq!(ContextCompiler::trimmed_output(&[10, 20], 99), &[10, 20]);
+        // Only the LAST is stripped — an EOS mid-sequence is real content, never removed.
+        assert_eq!(ContextCompiler::trimmed_output(&[99, 10, 99], 99), &[99, 10]);
+        assert_eq!(ContextCompiler::trimmed_output(&[], 99), &[] as &[u32]);
+    }
+
+    #[test]
+    fn memory_root_is_order_sensitive_and_deterministic() {
+        let a = MemoryForContext { memory_id: "m1".into(), content: "likes rust".into() };
+        let b = MemoryForContext { memory_id: "m2".into(), content: "tabs are wrong".into() };
+        let r1 = memory_snapshot_root(&[a, b]).unwrap();
+        let a2 = MemoryForContext { memory_id: "m1".into(), content: "likes rust".into() };
+        let b2 = MemoryForContext { memory_id: "m2".into(), content: "tabs are wrong".into() };
+        assert_eq!(r1, memory_snapshot_root(&[a2, b2]).unwrap(), "same snapshot, same root");
+        let a3 = MemoryForContext { memory_id: "m1".into(), content: "likes rust".into() };
+        let b3 = MemoryForContext { memory_id: "m2".into(), content: "tabs are wrong".into() };
+        assert_ne!(r1, memory_snapshot_root(&[b3, a3]).unwrap(), "order is part of the snapshot");
+        assert_eq!(memory_snapshot_root(&[]), None);
+    }
+
+    #[test]
+    fn chunk_selection_finds_the_needle_deterministically() {
+        // 120 lines; the needle sits at lines 61-62 → chunk index 2 (30-line chunks).
+        let mut lines: Vec<String> = (0..120).map(|i| format!("filler line {i}")).collect();
+        lines[60] = "the needle sits here".into();
+        lines[61] = "another needle mention".into();
+        let text = lines.join("\n");
+        let budget = 700; // forces selection: whole text is ~2000 chars
+
+        let s1 = select_chunks(&text, "where is the needle?", budget);
+        let s2 = select_chunks(&text, "where is the needle?", budget);
+        assert_eq!(s1.chunks_selected, s2.chunks_selected, "deterministic");
+        assert_eq!(s1.chunks_total, 4);
+        assert!(s1.chunks_selected.contains(&2), "the scoring must pick the needle chunk, got {:?}", s1.chunks_selected);
+        assert!(s1.rendered.contains("the needle sits here"));
+        assert!(s1.rendered.chars().count() <= budget);
+
+        // Under budget ⇒ whole text, single logical chunk.
+        let all = select_chunks("short", "anything", 100);
+        assert_eq!(all.chunks_total, 1);
+        assert_eq!(all.rendered, "short");
+    }
+
+    // ---- tokenizer-backed tests (run when the local model checkout provides tokenizer.json;
+    // the file is not git-tracked, so CI without models/ skips them loudly). --------------
+
+    fn load_tokenizer() -> Option<TokenizerHost> {
+        let path = std::path::Path::new("../models/Qwen3.6-35B-A3B-Claude-4.7-base-meta/tokenizer.json");
+        if !path.exists() {
+            eprintln!("SKIP: {} not present — tokenizer-backed compiler tests skipped", path.display());
+            return None;
+        }
+        Some(TokenizerHost::load(path, crate::QWEN_EOS_ID).unwrap())
+    }
+
+    fn stored_turn(user_block: &str, output_ids: Vec<u32>) -> StoredTurn {
+        StoredTurn {
+            turn_id: "t".into(),
+            conversation_id: "c".into(),
+            parent_turn_id: None,
+            role_user_text: user_block.into(),
+            user_block_text: Some(user_block.into()),
+            context_meta_json: None,
+            display_text: String::new(),
+            prompt_ids: Vec::new(),
+            output_ids,
+            stop_reason: None,
+            verification_status: TurnVerificationStatus::LocalComplete,
+            privacy_mode: TurnPrivacyMode::LocalOnly,
+            receipt_json: None,
+            runtime_roots_json: None,
+            search_bundle_json: None,
+            created_ms: 0,
+        }
+    }
+
+    /// The legacy binding convention: rendered evidence joins the user block AFTER the user
+    /// text (`user + "\n\n" + evidence`), so committed prompt ids — and hence the receipt's
+    /// prompt commitment — cover the bundle digest line. The meta records what was committed.
+    #[test]
+    fn search_evidence_joins_the_user_block_and_meta() {
+        let Some(tok) = load_tokenizer() else { return };
+        let compiler = ContextCompiler::new(&tok, "S.", 8192, 512, 6000, 6000).unwrap();
+        let compiled = compiler
+            .compile(
+                &tok,
+                &ContextInputs {
+                    user_text: "question?",
+                    search: Some(SearchForContext {
+                        evidence_text: "[UNTRUSTED LIVE SEARCH EVIDENCE]\nbundle_sha256=deadbeef\n[END]".into(),
+                        bundle_sha256: "deadbeef".into(),
+                        effective_compression: "off".into(),
+                    }),
+                    ..Default::default()
+                },
+            )
+            .unwrap();
+        assert!(compiled.user_block_text.starts_with("question?\n\n[UNTRUSTED"));
+        assert!(compiled.user_block_text.contains("bundle_sha256=deadbeef"));
+        let decoded = tok.decode(&compiled.ids).unwrap();
+        assert!(decoded.contains("bundle_sha256=deadbeef"), "digest line must be inside the committed ids");
+        let meta: serde_json::Value = serde_json::from_str(&compiled.context_meta_json).unwrap();
+        assert_eq!(meta["search"]["bundle_sha256"], "deadbeef");
+        assert_eq!(meta["search"]["effective_compression"], "off");
+        // A searchless turn's meta has no search key at all (schema-stable with pre-search turns).
+        let plain = compiler.compile(&tok, &ContextInputs { user_text: "hi", ..Default::default() }).unwrap();
+        let plain_meta: serde_json::Value = serde_json::from_str(&plain.context_meta_json).unwrap();
+        assert!(plain_meta.get("search").is_none());
+    }
+
+    #[test]
+    fn plain_turns_keep_the_cross_turn_prefix_invariant() {
+        let Some(tok) = load_tokenizer() else { return };
+        let compiler = ContextCompiler::new(&tok, "You are a helpful assistant.", 8192, 512, 6000, 6000).unwrap();
+
+        let c1 = compiler
+            .compile(&tok, &ContextInputs { user_text: "hello there", ..Default::default() })
+            .unwrap();
+        // No material ⇒ the persisted block IS the raw user text (v1-schema compatibility).
+        assert_eq!(c1.user_block_text, "hello there");
+
+        // Pretend the engine answered; next turn's prompt must extend the previous one.
+        let output = vec![c1.ids[5], c1.ids[6], crate::QWEN_EOS_ID];
+        let t1 = stored_turn(&c1.user_block_text, output.clone());
+        let c2 = compiler
+            .compile(&tok, &ContextInputs { history: std::slice::from_ref(&t1), user_text: "and again", ..Default::default() })
+            .unwrap();
+        assert!(c2.ids.starts_with(&c1.ids), "turn 2 prompt must extend turn 1's prompt (prefix-cache invariant)");
+        let continued = &c2.ids[c1.ids.len()..c1.ids.len() + 2];
+        assert_eq!(continued, &output[..2], "stored output ids are spliced in verbatim (EOS trimmed)");
+    }
+
+    #[test]
+    fn memory_lives_in_the_system_region_and_attachments_in_the_user_block() {
+        let Some(tok) = load_tokenizer() else { return };
+        let compiler = ContextCompiler::new(&tok, "Base.", 8192, 512, 6000, 6000).unwrap();
+
+        let memory = vec![MemoryForContext { memory_id: "m1".into(), content: "user prefers Japanese".into() }];
+        let attachments = vec![AttachmentForContext {
+            artifact_id: "a1".into(),
+            display_name: "notes.txt".into(),
+            content_hash: "ab".repeat(32),
+            text: "attachment body".into(),
+        }];
+        let compiled = compiler
+            .compile(
+                &tok,
+                &ContextInputs {
+                    project_instructions: Some("Answer tersely."),
+                    memory: &memory,
+                    attachments: &attachments,
+                    user_text: "question?",
+                    ..Default::default()
+                },
+            )
+            .unwrap();
+
+        let system_text = tok.decode(&compiled.ids[..compiled.system_prefix_len]).unwrap();
+        assert!(system_text.contains("[project instructions]\nAnswer tersely."));
+        assert!(system_text.contains("[memory]\n- user prefers Japanese"));
+        assert!(!system_text.contains("attachment body"), "attachments must not pollute the system region");
+
+        assert!(compiled.user_block_text.starts_with("[file notes.txt blake2b=abababababababab chunks=1/1]\n"));
+        assert!(compiled.user_block_text.contains("attachment body"));
+        assert!(compiled.user_block_text.ends_with("question?"));
+
+        let meta: serde_json::Value = serde_json::from_str(&compiled.context_meta_json).unwrap();
+        assert_eq!(meta["memory_ids"][0], "m1");
+        assert!(meta["memory_snapshot_root"].is_string());
+        assert_eq!(meta["attachments"][0]["artifact_id"], "a1");
+        assert_eq!(meta["context_policy"], CONTEXT_POLICY_ID);
+    }
+
+    #[test]
+    fn budget_drops_oldest_turns_whole() {
+        let Some(tok) = load_tokenizer() else { return };
+        let filler = "some words that cost a handful of tokens each time";
+        let history = vec![
+            stored_turn(filler, vec![9906, 9906, 9906]),
+            stored_turn(filler, vec![9906, 9906, 9906]),
+            stored_turn(filler, vec![9906, 9906, 9906]),
+        ];
+        let inputs = ContextInputs { history: &history, user_text: "final question", ..Default::default() };
+
+        // Measure the unpressured prompt, then rebuild the compiler with an input budget 5
+        // tokens short of it — at least one whole turn must go, and dropping one frees far more
+        // than 5 tokens, so the rest fit. No token-count guessing.
+        let roomy = ContextCompiler::new(&tok, "S.", 8192, 64, 6000, 6000).unwrap();
+        let full = roomy.compile(&tok, &inputs).unwrap();
+        assert_eq!(full.dropped_turns, 0);
+
+        let tight = ContextCompiler::new(&tok, "S.", full.ids.len() + 64 - 5, 64, 6000, 6000).unwrap();
+        let compiled = tight.compile(&tok, &inputs).unwrap();
+        assert_eq!(compiled.dropped_turns, 1, "5 tokens over ⇒ exactly the oldest turn goes");
+        assert!(compiled.ids.len() <= full.ids.len() - 5, "the result honors the shrunken budget");
+        // The oldest turn was dropped, the newest survives: the compiled ids end with the same
+        // current block and keep the LAST history turn's fragment.
+        assert_eq!(&compiled.ids[compiled.system_prefix_len..], &full.ids[full.ids.len() - (compiled.ids.len() - compiled.system_prefix_len)..]);
+        let meta: serde_json::Value = serde_json::from_str(&compiled.context_meta_json).unwrap();
+        assert_eq!(meta["dropped_turns"], 1);
+    }
+}

palw-gateway/src/coordinator.rs

@@ -0,0 +1,567 @@
+//! The PALW coordinator boundary (design doc §15).
+//!
+//! The background worker needs five verbs against "the network": submit an A-commit, poll
+//! verdicts, poll B assignments, decline an assignment, submit a replica result. The REAL
+//! counterparty is the MISAKA node's PALW surface (replica dispatch / receipt submission / DA —
+//! the protocol-side features §15 lists), which lives in the consensus repo and is not finished.
+//! This module therefore freezes the verbs as a TRAIT and ships two honest implementations:
+//!
+//! * `LoopbackCoordinator` — a complete in-process coordinator with the real state machine
+//!   (submit → assign → result → matched → certified, mismatch, deadline requeue). The gateway
+//!   exposes it over HTTP (`/v1/palw/loopback/*`), so a SECOND gateway instance can point its
+//!   `HttpCoordinator` here and run a genuine two-instance A/B loop on one desk. This is the
+//!   devnet harness for the desktop product — it is NOT consensus: no beacons, no bonds, no DA
+//!   retention, no chain. Its verdicts certify the plumbing, not the economics.
+//! * `HttpCoordinator` — the client half of the same JSON protocol (documented in the README),
+//!   which a node-side bridge implements to make settlement real. Plain HTTP/1.1 over TCP,
+//!   `Connection: close`, no TLS — a localhost/LAN dev transport; the production node binding
+//!   replaces this, it does not extend it.
+//!
+//! Determinism note for self-replica dev mode: a single-instance loopback replica runs on the
+//! SAME engine process, so the prefix cache makes B's "replay" nearly free and — more
+//! importantly — not independent. Loopback validates the pipeline, never the security claim;
+//! independence needs a second host by definition.
+
+use std::collections::HashMap;
+use std::io::{Read, Write};
+use std::sync::Mutex;
+
+use serde::{Deserialize, Serialize};
+use serde_json::{Value, json};
+
+use crate::events::RuntimeRootsV1;
+
+/// A-commit: what the submitting side registers for replication. `prompt_ids` doubles as the
+/// context DA in loopback (the doc's Conversation-DA in miniature).
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct JobSubmission {
+    pub job_id: String,
+    pub provider_id: String,
+    pub prompt_ids: Vec<u32>,
+    pub max_new: u32,
+    /// blake2b-256 over the little-endian output ids — A's claim, compared against B's.
+    pub output_root: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub receipt_json: Option<String>,
+    /// Engine execution roots (route/kv/state). When A commits them, an honest replica must
+    /// reproduce them — the match covers execution structure, not just the output ids.
+    #[serde(skip_serializing_if = "Option::is_none", default)]
+    pub runtime_roots: Option<RuntimeRootsV1>,
+}
+
+/// B's answer for an assignment.
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct ReplicaResultV1 {
+    pub job_id: String,
+    pub provider_id: String,
+    pub output_root: String,
+    #[serde(skip_serializing_if = "Option::is_none", default)]
+    pub runtime_roots: Option<RuntimeRootsV1>,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct ReplicaAssignment {
+    pub job_id: String,
+    pub prompt_ids: Vec<u32>,
+    pub max_new: u32,
+    /// Absolute unix-ms deadline; the worker computes remaining time for admission.
+    pub deadline_unix_ms: i64,
+}
+
+/// What the A-side learns when polling. Mirrors `TurnVerificationStatus` names on the wire.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum JobVerdict {
+    ReplicaMatched,
+    Certified,
+    Mismatch,
+}
+
+impl JobVerdict {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::ReplicaMatched => "replica_matched",
+            Self::Certified => "certified",
+            Self::Mismatch => "mismatch",
+        }
+    }
+    pub fn from_str(s: &str) -> Option<Self> {
+        Some(match s {
+            "replica_matched" => Self::ReplicaMatched,
+            "certified" => Self::Certified,
+            "mismatch" => Self::Mismatch,
+            _ => return None,
+        })
+    }
+}
+
+pub trait PalwCoordinator: Send + Sync {
+    /// Idempotent by `job_id` — re-submitting a known job is an Ok no-op (worker restart safety).
+    fn submit_job(&self, submission: &JobSubmission) -> Result<(), String>;
+    /// Verdicts for the given jobs; jobs still pending are simply absent from the map.
+    fn fetch_verdicts(&self, job_ids: &[String]) -> Result<HashMap<String, JobVerdict>, String>;
+    /// Assignments offered to `provider_id` (claimed on fetch; a re-poll does not re-offer).
+    fn fetch_assignments(&self, provider_id: &str) -> Result<Vec<ReplicaAssignment>, String>;
+    fn decline_assignment(&self, job_id: &str, provider_id: &str, reason: &str) -> Result<(), String>;
+    fn submit_replica_result(&self, result: &ReplicaResultV1) -> Result<(), String>;
+}
+
+/// The match rule shared by coordinators: output roots must agree, and IF the submitter
+/// committed runtime roots the replica must reproduce them exactly. (A submitter that omits
+/// roots gets output-only matching — a weaker class, visible in the job record.)
+pub fn replica_matches(submission: &JobSubmission, result: &ReplicaResultV1) -> bool {
+    if submission.output_root != result.output_root {
+        return false;
+    }
+    match &submission.runtime_roots {
+        Some(expected) => result.runtime_roots.as_ref() == Some(expected),
+        None => true,
+    }
+}
+
+pub fn output_root(ids: &[u32]) -> String {
+    use blake2::{Blake2b, Digest, digest::consts::U32};
+    let mut h = Blake2b::<U32>::new();
+    for id in ids {
+        h.update(id.to_le_bytes());
+    }
+    h.finalize().iter().map(|b| format!("{b:02x}")).collect()
+}
+
+// ---- loopback ---------------------------------------------------------------------------
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+enum JobPhase {
+    /// Waiting for a replica provider (or requeued after decline/deadline).
+    Unassigned,
+    Assigned,
+    /// Replica root matched; the NEXT verdict fetch promotes to Certified so the A-side sees
+    /// the intermediate state exactly once.
+    Matched,
+    Certified,
+    Mismatch,
+}
+
+struct LoopbackJob {
+    submission: JobSubmission,
+    phase: JobPhase,
+    assigned_to: Option<String>,
+    deadline_unix_ms: i64,
+    declines: u32,
+}
+
+pub struct LoopbackConfig {
+    /// Offer a job back to its own submitter when nobody else polls. TRUE is the single-desk
+    /// dev default; it validates plumbing while (see module docs) proving nothing about
+    /// independence.
+    pub allow_self_replica: bool,
+    pub assignment_deadline_ms: i64,
+}
+
+impl Default for LoopbackConfig {
+    fn default() -> Self {
+        Self { allow_self_replica: true, assignment_deadline_ms: 120_000 }
+    }
+}
+
+pub struct LoopbackCoordinator {
+    config: LoopbackConfig,
+    jobs: Mutex<HashMap<String, LoopbackJob>>,
+}
+
+fn now_unix_ms() -> i64 {
+    std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).map(|d| d.as_millis() as i64).unwrap_or(0)
+}
+
+impl LoopbackCoordinator {
+    pub fn new(config: LoopbackConfig) -> Self {
+        Self { config, jobs: Mutex::new(HashMap::new()) }
+    }
+
+    /// Introspection for `/v1/palw/status`.
+    pub fn counts(&self) -> HashMap<&'static str, u64> {
+        let jobs = self.jobs.lock().unwrap();
+        let mut out: HashMap<&'static str, u64> =
+            [("unassigned", 0), ("assigned", 0), ("matched", 0), ("certified", 0), ("mismatch", 0)].into();
+        for j in jobs.values() {
+            let key = match j.phase {
+                JobPhase::Unassigned => "unassigned",
+                JobPhase::Assigned => "assigned",
+                JobPhase::Matched => "matched",
+                JobPhase::Certified => "certified",
+                JobPhase::Mismatch => "mismatch",
+            };
+            *out.get_mut(key).unwrap() += 1;
+        }
+        out
+    }
+}
+
+impl PalwCoordinator for LoopbackCoordinator {
+    fn submit_job(&self, submission: &JobSubmission) -> Result<(), String> {
+        let mut jobs = self.jobs.lock().unwrap();
+        if jobs.contains_key(&submission.job_id) {
+            return Ok(()); // idempotent re-submit
+        }
+        jobs.insert(
+            submission.job_id.clone(),
+            LoopbackJob {
+                submission: submission.clone(),
+                phase: JobPhase::Unassigned,
+                assigned_to: None,
+                deadline_unix_ms: 0,
+                declines: 0,
+            },
+        );
+        Ok(())
+    }
+
+    fn fetch_verdicts(&self, job_ids: &[String]) -> Result<HashMap<String, JobVerdict>, String> {
+        let mut jobs = self.jobs.lock().unwrap();
+        let mut out = HashMap::new();
+        for id in job_ids {
+            if let Some(job) = jobs.get_mut(id) {
+                match job.phase {
+                    JobPhase::Matched => {
+                        out.insert(id.clone(), JobVerdict::ReplicaMatched);
+                        // Loopback has no auditor lottery: a matched replica certifies on the
+                        // next observation.
+                        job.phase = JobPhase::Certified;
+                    }
+                    JobPhase::Certified => {
+                        out.insert(id.clone(), JobVerdict::Certified);
+                    }
+                    JobPhase::Mismatch => {
+                        out.insert(id.clone(), JobVerdict::Mismatch);
+                    }
+                    JobPhase::Unassigned | JobPhase::Assigned => {}
+                }
+            }
+        }
+        Ok(out)
+    }
+
+    fn fetch_assignments(&self, provider_id: &str) -> Result<Vec<ReplicaAssignment>, String> {
+        let now = now_unix_ms();
+        let mut jobs = self.jobs.lock().unwrap();
+        let mut out = Vec::new();
+        for job in jobs.values_mut() {
+            // Deadline enforcement: an assigned-but-silent replica loses the claim.
+            if job.phase == JobPhase::Assigned && now > job.deadline_unix_ms {
+                job.phase = JobPhase::Unassigned;
+                job.assigned_to = None;
+            }
+            if job.phase != JobPhase::Unassigned {
+                continue;
+            }
+            if job.submission.provider_id == provider_id && !self.config.allow_self_replica {
+                continue;
+            }
+            job.phase = JobPhase::Assigned;
+            job.assigned_to = Some(provider_id.to_string());
+            job.deadline_unix_ms = now + self.config.assignment_deadline_ms;
+            out.push(ReplicaAssignment {
+                job_id: job.submission.job_id.clone(),
+                prompt_ids: job.submission.prompt_ids.clone(),
+                max_new: job.submission.max_new,
+                deadline_unix_ms: job.deadline_unix_ms,
+            });
+        }
+        Ok(out)
+    }
+
+    fn decline_assignment(&self, job_id: &str, provider_id: &str, _reason: &str) -> Result<(), String> {
+        let mut jobs = self.jobs.lock().unwrap();
+        let job = jobs.get_mut(job_id).ok_or_else(|| format!("unknown job {job_id}"))?;
+        if job.phase == JobPhase::Assigned && job.assigned_to.as_deref() == Some(provider_id) {
+            job.phase = JobPhase::Unassigned;
+            job.assigned_to = None;
+            job.declines += 1;
+        }
+        Ok(())
+    }
+
+    fn submit_replica_result(&self, result: &ReplicaResultV1) -> Result<(), String> {
+        let now = now_unix_ms();
+        let job_id = result.job_id.as_str();
+        let mut jobs = self.jobs.lock().unwrap();
+        let job = jobs.get_mut(job_id).ok_or_else(|| format!("unknown job {job_id}"))?;
+        if job.phase != JobPhase::Assigned || job.assigned_to.as_deref() != Some(result.provider_id.as_str()) {
+            return Err(format!("job {job_id} is not assigned to {}", result.provider_id));
+        }
+        if now > job.deadline_unix_ms {
+            // Too late: the claim is gone, the job goes back to the queue.
+            job.phase = JobPhase::Unassigned;
+            job.assigned_to = None;
+            return Err(format!("job {job_id} deadline passed — result ignored, job requeued"));
+        }
+        job.phase = if replica_matches(&job.submission, result) { JobPhase::Matched } else { JobPhase::Mismatch };
+        Ok(())
+    }
+}
+
+// ---- HTTP client ------------------------------------------------------------------------
+
+/// Client half of the loopback JSON protocol (see README "PALW coordinator protocol"). The
+/// server half is the gateway's `/v1/palw/loopback/*` routes — or, later, a node-side bridge.
+pub struct HttpCoordinator {
+    /// e.g. `http://127.0.0.1:12346/v1/palw/loopback`
+    base: String,
+    bearer: Option<String>,
+}
+
+impl HttpCoordinator {
+    pub fn new(base: &str, bearer: Option<String>) -> Self {
+        Self { base: base.trim_end_matches('/').to_string(), bearer }
+    }
+
+    fn call(&self, method: &str, path_and_query: &str, body: Option<&Value>) -> Result<Value, String> {
+        let url = format!("{}{}", self.base, path_and_query);
+        let (status, bytes) = http_request(method, &url, self.bearer.as_deref(), body)?;
+        let value: Value = if bytes.is_empty() {
+            Value::Null
+        } else {
+            serde_json::from_slice(&bytes).map_err(|e| format!("{method} {url}: bad json: {e}"))?
+        };
+        if status != 200 {
+            let msg = value
+                .get("error")
+                .and_then(|e| e.get("message"))
+                .and_then(|m| m.as_str())
+                .unwrap_or("unexpected status");
+            return Err(format!("{method} {url}: {status} {msg}"));
+        }
+        Ok(value)
+    }
+}
+
+impl PalwCoordinator for HttpCoordinator {
+    fn submit_job(&self, submission: &JobSubmission) -> Result<(), String> {
+        let body = serde_json::to_value(submission).map_err(|e| e.to_string())?;
+        self.call("POST", "/jobs", Some(&body)).map(|_| ())
+    }
+
+    fn fetch_verdicts(&self, job_ids: &[String]) -> Result<HashMap<String, JobVerdict>, String> {
+        let response = self.call("POST", "/verdicts", Some(&json!({ "job_ids": job_ids })))?;
+        let mut out = HashMap::new();
+        if let Some(items) = response.get("verdicts").and_then(|v| v.as_array()) {
+            for item in items {
+                let (Some(id), Some(verdict)) = (
+                    item.get("job_id").and_then(|j| j.as_str()),
+                    item.get("verdict").and_then(|v| v.as_str()).and_then(JobVerdict::from_str),
+                ) else {
+                    continue;
+                };
+                out.insert(id.to_string(), verdict);
+            }
+        }
+        Ok(out)
+    }
+
+    fn fetch_assignments(&self, provider_id: &str) -> Result<Vec<ReplicaAssignment>, String> {
+        let response = self.call("GET", &format!("/assignments?provider_id={provider_id}"), None)?;
+        let mut out = Vec::new();
+        if let Some(items) = response.get("assignments").and_then(|v| v.as_array()) {
+            for item in items {
+                out.push(serde_json::from_value(item.clone()).map_err(|e| format!("bad assignment: {e}"))?);
+            }
+        }
+        Ok(out)
+    }
+
+    fn decline_assignment(&self, job_id: &str, provider_id: &str, reason: &str) -> Result<(), String> {
+        self.call(
+            "POST",
+            &format!("/assignments/{job_id}/decline"),
+            Some(&json!({ "provider_id": provider_id, "reason": reason })),
+        )
+        .map(|_| ())
+    }
+
+    fn submit_replica_result(&self, result: &ReplicaResultV1) -> Result<(), String> {
+        let body = serde_json::to_value(result).map_err(|e| e.to_string())?;
+        self.call("POST", "/replica-results", Some(&body)).map(|_| ())
+    }
+}
+
+/// Minimal HTTP/1.1 request over plain TCP (`http://host[:port]/path` only). Deliberately
+/// dependency-free: this is a localhost/LAN dev transport with `Connection: close` framing —
+/// the response is everything until EOF, which tiny_http honors for close-marked requests.
+fn http_request(method: &str, url: &str, bearer: Option<&str>, body: Option<&Value>) -> Result<(u16, Vec<u8>), String> {
+    let rest = url.strip_prefix("http://").ok_or_else(|| format!("only http:// urls are supported, got {url}"))?;
+    let (host_port, path) = match rest.split_once('/') {
+        Some((hp, p)) => (hp, format!("/{p}")),
+        None => (rest, "/".to_string()),
+    };
+    let authority = if host_port.contains(':') { host_port.to_string() } else { format!("{host_port}:80") };
+
+    let mut stream = std::net::TcpStream::connect(&authority).map_err(|e| format!("connect {authority}: {e}"))?;
+    stream.set_read_timeout(Some(std::time::Duration::from_secs(30))).map_err(|e| e.to_string())?;
+    stream.set_write_timeout(Some(std::time::Duration::from_secs(30))).map_err(|e| e.to_string())?;
+
+    let body_bytes = body.map(serde_json::to_vec).transpose().map_err(|e| e.to_string())?.unwrap_or_default();
+    let mut request = format!(
+        "{method} {path} HTTP/1.1\r\nHost: {host_port}\r\nConnection: close\r\nContent-Type: application/json\r\nContent-Length: {}\r\n",
+        body_bytes.len()
+    );
+    if let Some(token) = bearer {
+        request.push_str(&format!("Authorization: Bearer {token}\r\n"));
+    }
+    request.push_str("\r\n");
+    stream.write_all(request.as_bytes()).map_err(|e| format!("write {url}: {e}"))?;
+    stream.write_all(&body_bytes).map_err(|e| format!("write {url}: {e}"))?;
+
+    let mut response = Vec::new();
+    stream.read_to_end(&mut response).map_err(|e| format!("read {url}: {e}"))?;
+    let header_end = response
+        .windows(4)
+        .position(|w| w == b"\r\n\r\n")
+        .ok_or_else(|| format!("{url}: malformed response"))?;
+    let head = std::str::from_utf8(&response[..header_end]).map_err(|_| "non-utf8 response head".to_string())?;
+    let status: u16 = head
+        .lines()
+        .next()
+        .and_then(|l| l.split_whitespace().nth(1))
+        .and_then(|s| s.parse().ok())
+        .ok_or_else(|| format!("{url}: bad status line"))?;
+    let mut body = response[header_end + 4..].to_vec();
+
+    // tiny_http chunk-frames close-delimited responses too; unwrap if so.
+    if head.to_ascii_lowercase().contains("transfer-encoding: chunked") {
+        body = dechunk(&body)?;
+    }
+    Ok((status, body))
+}
+
+fn dechunk(mut data: &[u8]) -> Result<Vec<u8>, String> {
+    let mut out = Vec::new();
+    loop {
+        let line_end = data.windows(2).position(|w| w == b"\r\n").ok_or("chunked: missing size line")?;
+        let size_str = std::str::from_utf8(&data[..line_end]).map_err(|_| "chunked: bad size")?;
+        let size = usize::from_str_radix(size_str.trim().split(';').next().unwrap_or(""), 16)
+            .map_err(|_| format!("chunked: bad size {size_str:?}"))?;
+        data = &data[line_end + 2..];
+        if size == 0 {
+            return Ok(out);
+        }
+        if data.len() < size + 2 {
+            return Err("chunked: truncated body".into());
+        }
+        out.extend_from_slice(&data[..size]);
+        data = &data[size + 2..];
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn submission(job: &str, provider: &str, root: &str) -> JobSubmission {
+        JobSubmission {
+            job_id: job.into(),
+            provider_id: provider.into(),
+            prompt_ids: vec![1, 2, 3],
+            max_new: 16,
+            output_root: root.into(),
+            receipt_json: None,
+            runtime_roots: None,
+        }
+    }
+
+    fn result(job: &str, provider: &str, root: &str) -> ReplicaResultV1 {
+        ReplicaResultV1 { job_id: job.into(), provider_id: provider.into(), output_root: root.into(), runtime_roots: None }
+    }
+
+    #[test]
+    fn loopback_full_match_pipeline() {
+        let c = LoopbackCoordinator::new(LoopbackConfig::default());
+        let root = output_root(&[7, 8, 9]);
+        c.submit_job(&submission("j1", "prov-a", &root)).unwrap();
+        c.submit_job(&submission("j1", "prov-a", &root)).unwrap(); // idempotent
+
+        // No verdict while unassigned.
+        assert!(c.fetch_verdicts(&["j1".into()]).unwrap().is_empty());
+
+        // Another provider claims it; a re-poll does not double-offer.
+        let got = c.fetch_assignments("prov-b").unwrap();
+        assert_eq!(got.len(), 1);
+        assert_eq!(got[0].prompt_ids, vec![1, 2, 3]);
+        assert!(c.fetch_assignments("prov-b").unwrap().is_empty());
+
+        c.submit_replica_result(&result("j1", "prov-b", &output_root(&[7, 8, 9]))).unwrap();
+        // First observation: matched. Second: certified. (Intermediate state seen exactly once.)
+        assert_eq!(c.fetch_verdicts(&["j1".into()]).unwrap()["j1"], JobVerdict::ReplicaMatched);
+        assert_eq!(c.fetch_verdicts(&["j1".into()]).unwrap()["j1"], JobVerdict::Certified);
+    }
+
+    #[test]
+    fn loopback_mismatch_and_wrong_provider() {
+        let c = LoopbackCoordinator::new(LoopbackConfig::default());
+        c.submit_job(&submission("j1", "prov-a", &output_root(&[7]))).unwrap();
+        let _ = c.fetch_assignments("prov-b").unwrap();
+        // A provider that never claimed the job cannot answer for it.
+        assert!(c.submit_replica_result(&result("j1", "prov-c", &output_root(&[7]))).is_err());
+        c.submit_replica_result(&result("j1", "prov-b", &output_root(&[999]))).unwrap();
+        assert_eq!(c.fetch_verdicts(&["j1".into()]).unwrap()["j1"], JobVerdict::Mismatch);
+        // Mismatch is terminal.
+        assert_eq!(c.fetch_verdicts(&["j1".into()]).unwrap()["j1"], JobVerdict::Mismatch);
+    }
+
+    #[test]
+    fn loopback_decline_and_deadline_requeue() {
+        let c = LoopbackCoordinator::new(LoopbackConfig { allow_self_replica: false, assignment_deadline_ms: 0 });
+        c.submit_job(&submission("j1", "prov-a", "r")).unwrap();
+        // Self-replica disabled: the submitter is never offered its own job.
+        assert!(c.fetch_assignments("prov-a").unwrap().is_empty());
+
+        let got = c.fetch_assignments("prov-b").unwrap();
+        assert_eq!(got.len(), 1);
+        c.decline_assignment("j1", "prov-b", "over capacity").unwrap();
+        // Declined ⇒ requeued ⇒ another provider can claim it.
+        let got = c.fetch_assignments("prov-c").unwrap();
+        assert_eq!(got.len(), 1);
+        // deadline_ms=0 ⇒ instantly late: the result is refused and the job requeued.
+        std::thread::sleep(std::time::Duration::from_millis(5));
+        assert!(c.submit_replica_result(&result("j1", "prov-c", "r")).is_err());
+        assert_eq!(c.fetch_assignments("prov-d").unwrap().len(), 1);
+    }
+
+    #[test]
+    fn output_root_is_order_and_value_sensitive() {
+        assert_eq!(output_root(&[1, 2]), output_root(&[1, 2]));
+        assert_ne!(output_root(&[1, 2]), output_root(&[2, 1]));
+        assert_ne!(output_root(&[1]), output_root(&[]));
+    }
+
+    #[test]
+    fn committed_roots_bind_the_match() {
+        use crate::events::RuntimeRootsV1;
+        let roots = RuntimeRootsV1 { route: "aa".into(), kv: "bb".into(), state: "cc".into() };
+        let mut sub = submission("j1", "prov-a", "root");
+        sub.runtime_roots = Some(roots.clone());
+
+        let mut ok = result("j1", "prov-b", "root");
+        ok.runtime_roots = Some(roots.clone());
+        assert!(replica_matches(&sub, &ok));
+
+        // Replica omits or alters the committed roots ⇒ mismatch even with equal output.
+        assert!(!replica_matches(&sub, &result("j1", "prov-b", "root")));
+        let mut altered = result("j1", "prov-b", "root");
+        altered.runtime_roots = Some(RuntimeRootsV1 { route: "zz".into(), kv: "bb".into(), state: "cc".into() });
+        assert!(!replica_matches(&sub, &altered));
+
+        // Submitter without roots ⇒ output-only class; replica extras are ignored.
+        let plain = submission("j2", "prov-a", "root");
+        let mut extra = result("j2", "prov-b", "root");
+        extra.runtime_roots = Some(roots);
+        assert!(replica_matches(&plain, &extra));
+        assert!(!replica_matches(&plain, &result("j2", "prov-b", "other")));
+    }
+
+    #[test]
+    fn dechunk_unwraps_tiny_http_framing() {
+        let framed = b"5\r\nhello\r\n6\r\n world\r\n0\r\n\r\n";
+        assert_eq!(dechunk(framed).unwrap(), b"hello world");
+        assert!(dechunk(b"zz\r\n").is_err());
+    }
+}

palw-gateway/src/engine.rs

@@ -0,0 +1,239 @@
+//! EngineHost — owns the resident `qi35_model --serve` child and speaks its line protocol
+//! (`SERVE_READY` / `REQ n ids [DRAFT ids]` / `TOK` / `CACHE` / `SPEC` / `GEN` / `ROOTS` /
+//! `RCPT` / `DONE` / `ERR`), exactly as read from `docs/evidence/qi35_model.rs:2432-2475`.
+//!
+//! Serving-loop facts this host designs around:
+//! * One engine process = one generation at a time. The gateway serializes requests through a
+//!   queue (scheduler); multi-engine is a later phase.
+//! * There is NO stop channel in the engine. Cancel therefore = stop forwarding tokens, drain
+//!   the stream to `DONE`, and mark the turn `MintIneligible` — the v1 cancel semantics the
+//!   product doc freezes (`--max-new` bounds the worst-case drain).
+//! * Crash recovery: any read/parse failure poisons the child; the next request respawns it
+//!   (model load is expensive, so we never preemptively restart).
+
+use std::io::{BufRead, BufReader, Write};
+use std::process::{Child, ChildStdin, ChildStdout, Command, Stdio};
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Arc;
+
+#[derive(Clone, Debug)]
+pub struct EngineConfig {
+    pub binary: std::path::PathBuf,
+    pub gguf: std::path::PathBuf,
+    pub tables: std::path::PathBuf,
+    pub threads: u32,
+    pub max_new: u32,
+    pub eos_id: u32,
+    pub metal_v3: bool,
+    pub audit_key_file: Option<std::path::PathBuf>,
+    pub network_label: String,
+}
+
+pub struct EngineOutcome {
+    pub output_ids: Vec<u32>,
+    pub cache_hit_tokens: u32,
+    pub receipt_json: Option<String>,
+    /// The `ROOTS route= kv= state=` execution commitments (present since the host always sets
+    /// `QI35_SERVE_ROOTS`; None only against an older engine build that lacks the line).
+    pub runtime_roots: Option<crate::events::RuntimeRootsV1>,
+    pub eos_reached: bool,
+    pub elapsed_ms: u64,
+}
+
+pub struct EngineHost {
+    config: EngineConfig,
+    child: Option<EngineChild>,
+}
+
+struct EngineChild {
+    process: Child,
+    stdin: ChildStdin,
+    stdout: BufReader<ChildStdout>,
+}
+
+impl Drop for EngineHost {
+    fn drop(&mut self) {
+        if let Some(mut c) = self.child.take() {
+            let _ = writeln!(c.stdin, "/quit");
+            let _ = c.process.wait();
+        }
+    }
+}
+
+impl EngineHost {
+    pub fn new(config: EngineConfig) -> Self {
+        Self { config, child: None }
+    }
+
+    fn spawn(&mut self) -> Result<(), String> {
+        let cfg = &self.config;
+        let mut cmd = Command::new(&cfg.binary);
+        // The Metal build dlopens libqi35metal.dylib relative to the working directory; run the
+        // engine FROM its own directory (the launcher-script convention) so the dylib resolves.
+        if let Some(dir) = cfg.binary.parent() {
+            if !dir.as_os_str().is_empty() {
+                cmd.current_dir(dir);
+            }
+        }
+        // Phase D: 1 token = 1 command buffer — bit-exact, ~4x decode (the launcher's default).
+        cmd.env("QI35_PHASE_D", "1");
+        // Emit `ROOTS route= kv= state=` after every generation: the execution commitments the
+        // PALW replica match consumes (negligible cost — the roots are already computed).
+        cmd.env("QI35_SERVE_ROOTS", "1");
+        cmd.arg(&cfg.gguf)
+            .arg(&cfg.tables)
+            .arg("--serve")
+            .arg("--threads")
+            .arg(cfg.threads.to_string())
+            .arg("--max-new")
+            .arg(cfg.max_new.to_string())
+            .arg("--eos")
+            .arg(cfg.eos_id.to_string())
+            .stdin(Stdio::piped())
+            .stdout(Stdio::piped())
+            .stderr(Stdio::inherit());
+        if cfg.metal_v3 {
+            cmd.arg("--metal-v3");
+        }
+        if let Some(key) = &cfg.audit_key_file {
+            cmd.arg("--audit-key-file").arg(key);
+            cmd.arg("--network").arg(&cfg.network_label);
+        }
+        let mut process = cmd.spawn().map_err(|e| format!("spawn {}: {e}", cfg.binary.display()))?;
+        let stdin = process.stdin.take().ok_or("engine stdin unavailable")?;
+        let stdout = BufReader::new(process.stdout.take().ok_or("engine stdout unavailable")?);
+        let mut child = EngineChild { process, stdin, stdout };
+
+        // Model load can take minutes on first touch; read until SERVE_READY with no artificial
+        // deadline — a wedged load surfaces as EOF (child died), never a silent hang forever,
+        // because the child's death closes the pipe.
+        let mut line = String::new();
+        loop {
+            line.clear();
+            let n = child.stdout.read_line(&mut line).map_err(|e| format!("engine handshake read: {e}"))?;
+            if n == 0 {
+                let _ = child.process.wait();
+                return Err("engine exited before SERVE_READY (see its stderr above)".into());
+            }
+            if line.trim() == "SERVE_READY" {
+                break;
+            }
+        }
+        self.child = Some(child);
+        Ok(())
+    }
+
+    pub fn ensure_running(&mut self) -> Result<(), String> {
+        let dead = match &mut self.child {
+            None => true,
+            Some(c) => c.process.try_wait().map(|s| s.is_some()).unwrap_or(true),
+        };
+        if dead {
+            self.child = None;
+            self.spawn()?;
+        }
+        Ok(())
+    }
+
+    pub fn healthy(&mut self) -> bool {
+        if let Some(c) = &mut self.child {
+            c.process.try_wait().map(|s| s.is_none()).unwrap_or(false)
+        } else {
+            false
+        }
+    }
+
+    /// Run one generation. `on_token` receives each token id as it streams; `cancel` flips the
+    /// stream into drain mode (tokens no longer forwarded, but the protocol is consumed to
+    /// `DONE` so the child stays reusable). Any protocol violation poisons the child.
+    pub fn generate(
+        &mut self,
+        prompt_ids: &[u32],
+        cache_prefix_len: usize,
+        cancel: &Arc<AtomicBool>,
+        mut on_token: impl FnMut(u32, u32),
+    ) -> Result<EngineOutcome, String> {
+        self.ensure_running()?;
+        let started = std::time::Instant::now();
+
+        let idstr: String = prompt_ids.iter().map(|i| i.to_string()).collect::<Vec<_>>().join(",");
+        let write_result = {
+            let child = self.child.as_mut().expect("ensured above");
+            writeln!(child.stdin, "REQ {cache_prefix_len} {idstr}").and_then(|()| child.stdin.flush())
+        };
+        if let Err(e) = write_result {
+            self.child = None;
+            return Err(format!("engine write: {e}"));
+        }
+
+        let mut output_ids: Vec<u32> = Vec::new();
+        let mut cache_hit_tokens = 0u32;
+        let mut receipt_json: Option<String> = None;
+        let mut runtime_roots: Option<crate::events::RuntimeRootsV1> = None;
+        let mut token_index = 0u32;
+        let mut line = String::new();
+        loop {
+            line.clear();
+            let n = {
+                let child = self.child.as_mut().expect("held");
+                child.stdout.read_line(&mut line).map_err(|e| format!("engine read: {e}"))?
+            };
+            if n == 0 {
+                self.child = None;
+                return Err("engine died mid-generation".into());
+            }
+            let line = line.trim_end();
+            if let Some(tok) = line.strip_prefix("TOK ") {
+                let id: u32 = match tok.trim().parse() {
+                    Ok(id) => id,
+                    Err(_) => {
+                        self.child = None;
+                        return Err(format!("engine protocol: bad TOK line {line:?}"));
+                    }
+                };
+                if !cancel.load(Ordering::Relaxed) {
+                    on_token(token_index, id);
+                }
+                token_index += 1;
+            } else if let Some(rest) = line.strip_prefix("CACHE ") {
+                for part in rest.split_whitespace() {
+                    if let Some(v) = part.strip_prefix("hit_tokens=") {
+                        cache_hit_tokens = v.parse().unwrap_or(0);
+                    }
+                }
+            } else if let Some(rest) = line.strip_prefix("GEN ") {
+                output_ids = match rest.split(',').filter(|s| !s.is_empty()).map(|s| s.trim().parse::<u32>()).collect::<Result<_, _>>()
+                {
+                    Ok(ids) => ids,
+                    Err(_) => {
+                        self.child = None;
+                        return Err("engine protocol: bad GEN line".into());
+                    }
+                };
+            } else if let Some(json) = line.strip_prefix("RCPT ") {
+                receipt_json = Some(json.to_string());
+            } else if let Some(rest) = line.strip_prefix("ROOTS ") {
+                let field = |key: &str| {
+                    rest.split_whitespace().find_map(|part| part.strip_prefix(key).map(str::to_string))
+                };
+                if let (Some(route), Some(kv), Some(state)) = (field("route="), field("kv="), field("state=")) {
+                    runtime_roots = Some(crate::events::RuntimeRootsV1 { route, kv, state });
+                }
+            } else if line.starts_with("DONE ") {
+                let eos_reached = (output_ids.len() as u32) < self.config.max_new
+                    || output_ids.last() == Some(&self.config.eos_id);
+                return Ok(EngineOutcome {
+                    output_ids,
+                    cache_hit_tokens,
+                    receipt_json,
+                    runtime_roots,
+                    eos_reached,
+                    elapsed_ms: started.elapsed().as_millis() as u64,
+                });
+            } else if let Some(err) = line.strip_prefix("ERR ") {
+                return Err(format!("engine rejected request: {err}"));
+            }
+            // SPEC and anything else: informational, skipped.
+        }
+    }
+}

palw-gateway/src/events.rs

@@ -0,0 +1,159 @@
+//! Wire types frozen by `docs/palw-desktop-product-architecture.md`.
+//!
+//! Two clocks, never conflated: `GenerationEventV1` is the ANSWER clock (local A tokens,
+//! streamed immediately); `TurnVerificationStatus` is the SETTLEMENT clock (B replica → match →
+//! audit → certificate → maturity), advanced later by the PALW background supervisor (UX Phase
+//! 2). Phase 0 persists the status column from day one so the schema never migrates for it, but
+//! only ever writes `Streaming`/`LocalComplete`/`MintIneligible`.
+
+use serde::{Deserialize, Serialize};
+
+/// 64-byte identity, hex on the wire (the repo-wide Hash64 idiom, without pulling consensus
+/// crates into the product runtime).
+pub type HexHash = String;
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case", tag = "type")]
+pub enum GenerationEventV1 {
+    Started {
+        job_id: HexHash,
+        turn_id: HexHash,
+        /// Engine-reported prefix-cache reuse is only known at the end; this is the compiled
+        /// prompt length so clients can show prefill progress honestly.
+        prompt_tokens: u32,
+    },
+    Token {
+        index: u32,
+        token_id: u32,
+        /// UTF-8 bytes that became SAFE to display at this token (the incremental decoder's
+        /// stable prefix delta — may be empty while a multi-byte/multi-token grapheme is open).
+        utf8_delta: String,
+    },
+    /// Reserved for the Phase-1 tool runtime; the Phase-0 engine never emits it, but freezing
+    /// the variant now means stream consumers are written against the final shape.
+    ToolCall {
+        call_id: HexHash,
+        tool_name: String,
+        arguments_json: String,
+    },
+    Completed {
+        stop_reason: CanonicalStopReason,
+        output_tokens: u32,
+        /// Engine-reported `CACHE hit_tokens=…` — how much prefill the id-stable history saved.
+        cache_hit_tokens: u32,
+        elapsed_ms: u64,
+    },
+    Failed {
+        error_code: u32,
+        message: String,
+    },
+}
+
+#[derive(Clone, Copy, Debug, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum CanonicalStopReason {
+    /// The model emitted EOS.
+    Eos,
+    /// The per-request output budget was reached.
+    MaxTokens,
+    /// The user stopped generation. v1 semantics (frozen in the design doc): the partial answer
+    /// is kept locally and the turn is `MintIneligible` — B cannot reproduce the user's stop
+    /// instant, so a cancelled turn never enters the settlement pipeline.
+    UserCancelled,
+}
+
+/// The settlement clock (design doc §"最重要"). Stored on every turn; Phase 0 writes only the
+/// first two and `MintIneligible` (cancel), the PALW supervisor owns the rest in Phase 2.
+#[derive(Clone, Copy, Debug, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum TurnVerificationStatus {
+    Streaming,
+    LocalComplete,
+    ReplicaPending,
+    ReplicaMatched,
+    AuditPending,
+    Certified,
+    Matured,
+    Mismatch,
+    MintIneligible,
+}
+
+impl TurnVerificationStatus {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Streaming => "streaming",
+            Self::LocalComplete => "local_complete",
+            Self::ReplicaPending => "replica_pending",
+            Self::ReplicaMatched => "replica_matched",
+            Self::AuditPending => "audit_pending",
+            Self::Certified => "certified",
+            Self::Matured => "matured",
+            Self::Mismatch => "mismatch",
+            Self::MintIneligible => "mint_ineligible",
+        }
+    }
+
+    pub fn from_str(s: &str) -> Option<Self> {
+        Some(match s {
+            "streaming" => Self::Streaming,
+            "local_complete" => Self::LocalComplete,
+            "replica_pending" => Self::ReplicaPending,
+            "replica_matched" => Self::ReplicaMatched,
+            "audit_pending" => Self::AuditPending,
+            "certified" => Self::Certified,
+            "matured" => Self::Matured,
+            "mismatch" => Self::Mismatch,
+            "mint_ineligible" => Self::MintIneligible,
+            _ => return None,
+        })
+    }
+}
+
+/// The engine's per-generation execution roots (`ROOTS route= kv= state=`, emitted under
+/// `QI35_SERVE_ROOTS`): the MoE routing-trace root, the KV-cache root, and the recurrent-state
+/// root — real runtime commitments beyond the output ids. Carried on A-commits and replica
+/// results so a coordinator can match replicas on execution structure, not just output.
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
+pub struct RuntimeRootsV1 {
+    pub route: String,
+    pub kv: String,
+    pub state: String,
+}
+
+/// Dual-head pointer pair (design doc §4). `certified_head` stays NULL until UX Phase 2 wires
+/// the supervisor; the column existing from day one is the point — turn N+1 never waits on turn
+/// N's verification, and the schema already knows the difference.
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct ConversationHeadsV1 {
+    pub local_head: Option<HexHash>,
+    pub certified_head: Option<HexHash>,
+}
+
+/// The privacy/mint mode, fixed BEFORE the message is sent (design doc §16 — deciding after
+/// generation invites grinding). Phase 0 implements LocalOnly semantics for all three but
+/// records the user's choice so turns created under a mint intent are marked from birth.
+#[derive(Clone, Copy, Debug, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum TurnPrivacyMode {
+    LocalOnly,
+    VerifiedNoMint,
+    PalwMint,
+}
+
+impl TurnPrivacyMode {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::LocalOnly => "local_only",
+            Self::VerifiedNoMint => "verified_no_mint",
+            Self::PalwMint => "palw_mint",
+        }
+    }
+    pub fn from_str(s: &str) -> Option<Self> {
+        Some(match s {
+            "local_only" => Self::LocalOnly,
+            "verified_no_mint" => Self::VerifiedNoMint,
+            "palw_mint" => Self::PalwMint,
+            _ => return None,
+        })
+    }
+}

palw-gateway/src/http.rs

@@ -0,0 +1,1682 @@
+//! The resident HTTP surface. Route families:
+//!
+//! * `/healthz`, `/v1/models` — supervisor probes (the existing LM Studio plugin's
+//!   `ensureServer()` polls `/healthz`, so the plugin points at this gateway unchanged).
+//! * `/v1/chat/completions` — OpenAI-compatible, SSE streaming. STATELESS compatibility path:
+//!   the client owns the transcript (LM Studio's model). Kept so today's plugin works on day
+//!   one, but it cannot benefit from id-stable history.
+//! * `/v1/sessions/*` — the NATIVE session API (the actual product surface): the gateway owns
+//!   turns/branches/heads, prompts are compiled from stored ids, and `GenerationEventV1` is the
+//!   stream format. This is the path where the prefix cache actually hits.
+//! * `/v1/projects`, `/v1/memory`, `/v1/artifacts` — the Phase-1 workspace layers (§10/§12/§8):
+//!   project instructions and memory feed the compiler's system region; artifacts are
+//!   content-addressed blobs whose metadata (and version chains, §9) live in the session store.
+//! * `/v1/tools/*` — the §6 tool runtime. Deterministic/read-only tools execute immediately and
+//!   are snapshotted; side-effect tools are stored as PROPOSALS and only run through the
+//!   approve → exactly-once-claim path.
+//! * `/v1/turns/{id}/verification` — the Phase-2 settlement-clock writer (background supervisor
+//!   / tests): legal-transition enforcement, mismatch cascade, certified-head recompute all live
+//!   in the store.
+//! * `/v1/scheduler/status` — §14 observability.
+//!
+//! Concurrency model: tiny_http hands each request to a worker thread; engine access serializes
+//! through the §14 ResourceScheduler (priority queue) and then the EngineHost mutex (ownership).
+//! Cancel is a per-job AtomicBool flipped by `POST /v1/jobs/{id}/cancel`.
+
+use std::collections::HashMap;
+use std::io::Write;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Arc, Mutex};
+
+use serde_json::{Value, json};
+use tiny_http::{Header, Method, Request, Response, Server};
+
+use crate::artifact::{ArtifactBlobStore, PARSER_POLICY_UTF8_TEXT_V1};
+use crate::context::{
+    AttachmentForContext, ContextCompiler, ContextInputs, MemoryForContext, SearchForContext, ToolResultForContext,
+};
+use crate::coordinator::{JobSubmission, LoopbackCoordinator, PalwCoordinator};
+use crate::engine::EngineHost;
+use crate::events::{CanonicalStopReason, GenerationEventV1, TurnPrivacyMode, TurnVerificationStatus};
+use crate::lmstudio::{self, ResolutionKind};
+use crate::scheduler::{JobClass, ResourceScheduler};
+use crate::store::{ArtifactMeta, NewTurn, SessionStore, ToolCallRow};
+use crate::tokenizer::{IncrementalDecoder, TokenizerHost};
+use crate::tools::{TOOLS, ToolExecutionMode, ToolRuntime, mode_of};
+use crate::worker::WorkerStatus;
+
+pub struct Gateway {
+    pub engine: Arc<Mutex<EngineHost>>,
+    pub store: Arc<Mutex<SessionStore>>,
+    pub tokenizer: TokenizerHost,
+    pub compiler: ContextCompiler,
+    pub blobs: ArtifactBlobStore,
+    pub tools: ToolRuntime,
+    pub scheduler: Arc<ResourceScheduler>,
+    pub cancels: Mutex<HashMap<String, Arc<AtomicBool>>>,
+    pub model_name: String,
+    pub auth_token: String,
+    /// When set, every turn that produced an engine receipt also lands on disk here as
+    /// `.receipt.json` + `.opening.json` sidecars (0600, dir 0700) — the file form the offline
+    /// verifiers consume, same convention as the legacy server's `lmstudio-receipts/`.
+    pub receipt_dir: Option<std::path::PathBuf>,
+    /// Search sidecar program (stdin/stdout JSON, `docs/evidence/qi35_search_sidecar.py`):
+    /// the whole legacy search stack — routing, SSRF-guarded page fetch, canonical
+    /// `live_search_bundle_v1` — reused as a subprocess. Absent ⇒ turns never search.
+    pub search_cmd: Option<std::path::PathBuf>,
+    /// Present when this instance SERVES the loopback coordinator protocol
+    /// (`/v1/palw/loopback/*`) — the dev-harness stand-in for the node-side surface.
+    pub palw_loopback: Option<Arc<LoopbackCoordinator>>,
+    /// Present when the Phase-2 background worker is running (its live counters).
+    pub palw_status: Option<Arc<WorkerStatus>>,
+    pub palw_provider: Option<String>,
+}
+
+fn now_ms() -> i64 {
+    std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).map(|d| d.as_millis() as i64).unwrap_or(0)
+}
+
+fn fresh_id(prefix: &str) -> String {
+    // Uniqueness without a rand dependency: time + a process counter, hashed.
+    use blake2::{Blake2b, Digest, digest::consts::U16};
+    static COUNTER: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
+    let n = COUNTER.fetch_add(1, Ordering::Relaxed);
+    let mut h = Blake2b::<U16>::new();
+    h.update(now_ms().to_le_bytes());
+    h.update(n.to_le_bytes());
+    h.update(std::process::id().to_le_bytes());
+    format!("{prefix}_{}", hex16(&h.finalize()))
+}
+
+fn hex16(b: &[u8]) -> String {
+    b.iter().map(|x| format!("{x:02x}")).collect()
+}
+
+fn json_response(code: u16, body: &Value) -> Response<std::io::Cursor<Vec<u8>>> {
+    let bytes = serde_json::to_vec(body).unwrap_or_default();
+    Response::from_data(bytes)
+        .with_status_code(code)
+        .with_header(Header::from_bytes("Content-Type", "application/json").unwrap())
+}
+
+fn err_response(code: u16, message: &str) -> Response<std::io::Cursor<Vec<u8>>> {
+    json_response(code, &json!({ "error": { "message": message } }))
+}
+
+/// Minimal query-string access with %XX and '+' decoding — enough for names and ids.
+fn query_param(url: &str, key: &str) -> Option<String> {
+    let query = url.split_once('?')?.1;
+    for pair in query.split('&') {
+        let (k, v) = pair.split_once('=').unwrap_or((pair, ""));
+        if k == key {
+            let mut out = Vec::new();
+            let bytes = v.as_bytes();
+            let mut i = 0;
+            while i < bytes.len() {
+                match bytes[i] {
+                    b'+' => {
+                        out.push(b' ');
+                        i += 1;
+                    }
+                    b'%' if i + 2 < bytes.len() + 1 && i + 2 <= bytes.len() - 1 + 1 => {
+                        let hex = bytes.get(i + 1..i + 3).and_then(|h| std::str::from_utf8(h).ok());
+                        match hex.and_then(|h| u8::from_str_radix(h, 16).ok()) {
+                            Some(b) => {
+                                out.push(b);
+                                i += 3;
+                            }
+                            None => {
+                                out.push(b'%');
+                                i += 1;
+                            }
+                        }
+                    }
+                    b => {
+                        out.push(b);
+                        i += 1;
+                    }
+                }
+            }
+            return String::from_utf8(out).ok();
+        }
+    }
+    None
+}
+
+/// Extract `{id}` from `prefix{id}suffix`.
+fn path_seg<'a>(path: &'a str, prefix: &str, suffix: &str) -> Option<&'a str> {
+    let rest = path.strip_prefix(prefix)?;
+    let id = rest.strip_suffix(suffix)?;
+    if id.is_empty() || id.contains('/') { None } else { Some(id) }
+}
+
+fn artifact_meta_json(meta: &ArtifactMeta) -> Value {
+    json!({
+        "artifact_id": meta.artifact_id,
+        "content_hash": meta.content_hash,
+        "mime_type": meta.mime_type,
+        "byte_length": meta.byte_length,
+        "display_name": meta.display_name,
+        "parent_artifact_id": meta.parent_artifact_id,
+        "version": meta.version,
+        "parser_policy": meta.parser_policy,
+        "project_id": meta.project_id,
+        "created_by_turn": meta.created_by_turn,
+        "created_ms": meta.created_ms,
+    })
+}
+
+/// One turn's search outcome, carried from the sidecar into the native turn path.
+struct TurnSearch {
+    /// Normalized query (`/search ` prefix stripped) — becomes the turn's user text, exactly
+    /// like the legacy server.
+    query: String,
+    context: SearchForContext,
+    /// The full `live_search_bundle_v1` JSON, persisted on the turn and exported as the
+    /// `.search.json` sidecar.
+    bundle_json: String,
+    summary_lines: Vec<String>,
+}
+
+fn tool_call_json(row: &ToolCallRow) -> Value {
+    json!({
+        "call_id": row.call_id,
+        "tool_name": row.tool_name,
+        "mode": row.mode,
+        "arguments": serde_json::from_str::<Value>(&row.arguments_json).unwrap_or(Value::Null),
+        "status": row.status,
+        "result_artifact_id": row.result_artifact_id,
+        "result_preview": row.result_preview,
+        "error": row.error,
+        "conversation_id": row.conversation_id,
+        "created_ms": row.created_ms,
+        "executed_ms": row.executed_ms,
+    })
+}
+
+impl Gateway {
+    pub fn serve(self: Arc<Self>, addr: &str) -> Result<(), String> {
+        let server = Server::http(addr).map_err(|e| format!("bind {addr}: {e}"))?;
+        eprintln!("[palw-gateway] listening on http://{addr}");
+        loop {
+            let request = match server.recv() {
+                Ok(r) => r,
+                Err(e) => {
+                    eprintln!("[palw-gateway] accept error: {e}");
+                    continue;
+                }
+            };
+            let gw = Arc::clone(&self);
+            std::thread::spawn(move || gw.dispatch(request));
+        }
+    }
+
+    fn authorized(&self, request: &Request) -> bool {
+        if self.auth_token.is_empty() {
+            return true;
+        }
+        request
+            .headers()
+            .iter()
+            .find(|h| h.field.equiv("Authorization"))
+            .map(|h| h.value.as_str() == format!("Bearer {}", self.auth_token))
+            .unwrap_or(false)
+    }
+
+    fn dispatch(self: Arc<Self>, mut request: Request) {
+        let method = request.method().clone();
+        let url = request.url().to_string();
+        let path = url.split('?').next().unwrap_or("").to_string();
+
+        if path == "/healthz" {
+            let ok = self.engine.lock().map(|mut e| e.healthy()).unwrap_or(false);
+            let _ = request.respond(json_response(200, &json!({ "ok": true, "engine_resident": ok })));
+            return;
+        }
+        if !self.authorized(&request) {
+            let _ = request.respond(err_response(401, "missing or wrong bearer token"));
+            return;
+        }
+
+        // Bodies are BYTES (artifact upload); JSON handlers decode as needed.
+        let mut body = Vec::new();
+        if matches!(method, Method::Post) && request.as_reader().read_to_end(&mut body).is_err() {
+            let _ = request.respond(err_response(400, "unreadable body"));
+            return;
+        }
+        let body_json = || -> Result<Value, String> {
+            let text = std::str::from_utf8(&body).map_err(|_| "body is not UTF-8".to_string())?;
+            if text.trim().is_empty() {
+                return Ok(json!({}));
+            }
+            serde_json::from_str(text).map_err(|e| format!("bad json: {e}"))
+        };
+
+        let result: Result<(), String> = match (&method, path.as_str()) {
+            (Method::Get, "/v1/models") => {
+                let _ = request.respond(json_response(
+                    200,
+                    &json!({ "object": "list", "data": [{ "id": self.model_name, "object": "model" }] }),
+                ));
+                Ok(())
+            }
+            (Method::Get, "/v1/scheduler/status") => {
+                let s = self.scheduler.status();
+                let mut waiting = serde_json::Map::new();
+                for class in JobClass::ALL {
+                    waiting.insert(class.as_str().into(), json!(s.waiting_by_class[class.index()]));
+                }
+                let _ = request.respond(json_response(
+                    200,
+                    &json!({
+                        "busy": s.busy,
+                        "waiting": waiting,
+                        "ema_millitok_per_sec": s.ema_millitok_per_sec,
+                        "completed_jobs": s.completed_jobs,
+                    }),
+                ));
+                Ok(())
+            }
+            // §14 SLA admission probe — the Phase-2 background worker asks BEFORE accepting a
+            // replica/audit assignment; refusal here means "decline the assignment", which the
+            // doc prefers over accepting and no-showing.
+            (Method::Post, "/v1/scheduler/admission") => self.finish_json(request, body_json().and_then(|v| {
+                let class = v
+                    .get("class")
+                    .and_then(|c| c.as_str())
+                    .and_then(JobClass::from_str)
+                    .ok_or_else(|| "missing or unknown class".to_string())?;
+                let tokens = v.get("estimated_output_tokens").and_then(|t| t.as_u64()).unwrap_or(0);
+                let deadline = v.get("deadline_ms").and_then(|d| d.as_u64()).ok_or_else(|| "missing deadline_ms".to_string())?;
+                Ok(match self.scheduler.try_admit(class, tokens, deadline) {
+                    Ok(()) => json!({ "admitted": true }),
+                    Err(reason) => json!({ "admitted": false, "reason": reason }),
+                })
+            })),
+            (Method::Post, "/v1/chat/completions") => match body_json() {
+                Ok(v) => self.chat_completions(request, &v),
+                Err(e) => {
+                    let _ = request.respond(err_response(400, &e));
+                    Ok(())
+                }
+            },
+            // The LM Studio bridge: a client-owned transcript resolved onto the session store,
+            // then the NATIVE turn path (id-stable prompt, receipt, ROOTS, settlement).
+            (Method::Post, "/v1/lmstudio/turn") => match body_json() {
+                Ok(v) => self.lmstudio_turn(request, &v),
+                Err(e) => {
+                    let _ = request.respond(err_response(400, &e));
+                    Ok(())
+                }
+            },
+            (Method::Get, p) if path_seg(p, "/v1/turns/", "/receipt").is_some() => {
+                let turn = path_seg(p, "/v1/turns/", "/receipt").unwrap().to_string();
+                self.turn_receipt(request, &turn)
+            }
+            (Method::Get, p)
+                if p.starts_with("/v1/turns/") && !p.trim_start_matches("/v1/turns/").contains('/') =>
+            {
+                let turn = p.trim_start_matches("/v1/turns/").to_string();
+                self.turn_info(request, &turn)
+            }
+
+            // ---- sessions ----------------------------------------------------------------
+            (Method::Post, "/v1/sessions") => self.finish_json(request, body_json().and_then(|v| {
+                let title = v.get("title").and_then(|t| t.as_str()).unwrap_or_default().to_string();
+                let project_id = v.get("project_id").and_then(|p| p.as_str()).map(String::from);
+                let id = fresh_id("conv");
+                let store = self.store.lock().unwrap();
+                if let Some(p) = &project_id {
+                    store.get_project(p)?; // referenced project must exist
+                }
+                store.create_conversation(&id, &title, project_id.as_deref(), now_ms())?;
+                Ok(json!({ "conversation_id": id, "title": title, "project_id": project_id }))
+            })),
+            (Method::Get, "/v1/sessions") => self.finish_json(request, (|| {
+                let rows = self.store.lock().unwrap().list_conversations()?;
+                let list: Vec<Value> = rows
+                    .iter()
+                    .map(|c| {
+                        json!({
+                            "conversation_id": c.conversation_id,
+                            "title": c.title,
+                            "project_id": c.project_id,
+                            "local_head": c.heads.local_head,
+                            "certified_head": c.heads.certified_head,
+                            "updated_ms": c.updated_ms,
+                        })
+                    })
+                    .collect();
+                Ok(json!({ "sessions": list }))
+            })()),
+            (Method::Post, p) if path_seg(p, "/v1/sessions/", "/messages").is_some() => {
+                let conv = path_seg(p, "/v1/sessions/", "/messages").unwrap().to_string();
+                match body_json() {
+                    Ok(v) => self.session_message(request, &conv, &v, Vec::new(), None),
+                    Err(e) => {
+                        let _ = request.respond(err_response(400, &e));
+                        Ok(())
+                    }
+                }
+            }
+            (Method::Get, p) if path_seg(p, "/v1/sessions/", "/history").is_some() => {
+                let conv = path_seg(p, "/v1/sessions/", "/history").unwrap().to_string();
+                self.session_history(request, &conv)
+            }
+            (Method::Post, p) if path_seg(p, "/v1/sessions/", "/head").is_some() => {
+                // Branch switching: point local_head at any existing turn (the UI's "go back to
+                // this version" — history is immutable, only the head moves).
+                let conv = path_seg(p, "/v1/sessions/", "/head").unwrap().to_string();
+                self.finish_json(request, body_json().and_then(|v| {
+                    let turn_id = v
+                        .get("turn_id")
+                        .and_then(|t| t.as_str())
+                        .ok_or_else(|| "missing turn_id".to_string())?;
+                    self.store.lock().unwrap().set_local_head(&conv, turn_id, now_ms())?;
+                    Ok(json!({ "local_head": turn_id }))
+                }))
+            }
+            (Method::Post, p) if path_seg(p, "/v1/jobs/", "/cancel").is_some() => {
+                let job = path_seg(p, "/v1/jobs/", "/cancel").unwrap();
+                if let Some(flag) = self.cancels.lock().unwrap().get(job) {
+                    flag.store(true, Ordering::Relaxed);
+                    let _ = request.respond(json_response(200, &json!({ "cancelled": true })));
+                } else {
+                    let _ = request.respond(err_response(404, "unknown or finished job"));
+                }
+                Ok(())
+            }
+
+            // ---- PALW worker + loopback coordinator (§15) --------------------------------
+            (Method::Get, "/v1/palw/status") => {
+                let worker = self.palw_status.as_ref().map(|s| {
+                    json!({
+                        "submitted": s.submitted.load(Ordering::Relaxed),
+                        "verdicts_applied": s.verdicts_applied.load(Ordering::Relaxed),
+                        "replicas_executed": s.replicas_executed.load(Ordering::Relaxed),
+                        "replicas_declined": s.replicas_declined.load(Ordering::Relaxed),
+                        "errors": s.errors.load(Ordering::Relaxed),
+                        "last_cycle_unix_ms": s.last_cycle_unix_ms.load(Ordering::Relaxed),
+                        "last_error": *s.last_error.lock().unwrap(),
+                    })
+                });
+                let loopback = self.palw_loopback.as_ref().map(|l| json!(l.counts()));
+                let _ = request.respond(json_response(
+                    200,
+                    &json!({
+                        "worker_enabled": self.palw_status.is_some(),
+                        "provider_id": self.palw_provider,
+                        "worker": worker,
+                        "loopback": loopback,
+                    }),
+                ));
+                Ok(())
+            }
+            (Method::Post, "/v1/palw/loopback/jobs") => self.finish_json(request, body_json().and_then(|v| {
+                let loopback = self.loopback()?;
+                let submission: JobSubmission =
+                    serde_json::from_value(v).map_err(|e| format!("bad submission: {e}"))?;
+                loopback.submit_job(&submission)?;
+                Ok(json!({ "accepted": true }))
+            })),
+            (Method::Post, "/v1/palw/loopback/verdicts") => self.finish_json(request, body_json().and_then(|v| {
+                let loopback = self.loopback()?;
+                let job_ids: Vec<String> = v
+                    .get("job_ids")
+                    .and_then(|j| j.as_array())
+                    .map(|a| a.iter().filter_map(|x| x.as_str().map(String::from)).collect())
+                    .unwrap_or_default();
+                let verdicts = loopback.fetch_verdicts(&job_ids)?;
+                let list: Vec<Value> =
+                    verdicts.iter().map(|(id, v)| json!({ "job_id": id, "verdict": v.as_str() })).collect();
+                Ok(json!({ "verdicts": list }))
+            })),
+            (Method::Get, "/v1/palw/loopback/assignments") => self.finish_json(request, (|| {
+                let loopback = self.loopback()?;
+                let provider = query_param(&url, "provider_id").ok_or_else(|| "missing provider_id".to_string())?;
+                let assignments = loopback.fetch_assignments(&provider)?;
+                Ok(json!({ "assignments": assignments }))
+            })()),
+            (Method::Post, p) if path_seg(p, "/v1/palw/loopback/assignments/", "/decline").is_some() => {
+                let job = path_seg(p, "/v1/palw/loopback/assignments/", "/decline").unwrap().to_string();
+                self.finish_json(request, body_json().and_then(|v| {
+                    let loopback = self.loopback()?;
+                    let provider =
+                        v.get("provider_id").and_then(|p| p.as_str()).ok_or_else(|| "missing provider_id".to_string())?;
+                    let reason = v.get("reason").and_then(|r| r.as_str()).unwrap_or("");
+                    loopback.decline_assignment(&job, provider, reason)?;
+                    Ok(json!({ "declined": true }))
+                }))
+            }
+            (Method::Post, "/v1/palw/loopback/replica-results") => self.finish_json(request, body_json().and_then(|v| {
+                let loopback = self.loopback()?;
+                let result: crate::coordinator::ReplicaResultV1 =
+                    serde_json::from_value(v).map_err(|e| format!("bad replica result: {e}"))?;
+                loopback.submit_replica_result(&result)?;
+                Ok(json!({ "recorded": true }))
+            })),
+
+            // ---- settlement clock (Phase-2 writer) ---------------------------------------
+            (Method::Post, p) if path_seg(p, "/v1/turns/", "/verification").is_some() => {
+                let turn = path_seg(p, "/v1/turns/", "/verification").unwrap().to_string();
+                self.finish_json(request, body_json().and_then(|v| {
+                    let status = v
+                        .get("status")
+                        .and_then(|s| s.as_str())
+                        .and_then(TurnVerificationStatus::from_str)
+                        .ok_or_else(|| "missing or unknown status".to_string())?;
+                    let outcome = self.store.lock().unwrap().set_verification_status(&turn, status, now_ms())?;
+                    Ok(json!({
+                        "turn_id": turn,
+                        "status": outcome.status.as_str(),
+                        "cascaded_mint_ineligible": outcome.cascaded,
+                        "certified_head": outcome.certified_head,
+                    }))
+                }))
+            }
+
+            // ---- projects (§10) ----------------------------------------------------------
+            (Method::Post, "/v1/projects") => self.finish_json(request, body_json().and_then(|v| {
+                let name = v.get("name").and_then(|n| n.as_str()).ok_or_else(|| "missing name".to_string())?;
+                let instructions = v.get("instructions").and_then(|i| i.as_str()).unwrap_or_default();
+                let id = fresh_id("proj");
+                self.store.lock().unwrap().create_project(&id, name, instructions, now_ms())?;
+                Ok(json!({ "project_id": id, "name": name }))
+            })),
+            (Method::Get, "/v1/projects") => self.finish_json(request, (|| {
+                let rows = self.store.lock().unwrap().list_projects()?;
+                let list: Vec<Value> = rows
+                    .iter()
+                    .map(|p| {
+                        json!({
+                            "project_id": p.project_id,
+                            "name": p.name,
+                            "instructions": p.instructions,
+                            "updated_ms": p.updated_ms,
+                        })
+                    })
+                    .collect();
+                Ok(json!({ "projects": list }))
+            })()),
+            (Method::Post, p) if path_seg(p, "/v1/projects/", "/instructions").is_some() => {
+                let id = path_seg(p, "/v1/projects/", "/instructions").unwrap().to_string();
+                self.finish_json(request, body_json().and_then(|v| {
+                    let instructions = v
+                        .get("instructions")
+                        .and_then(|i| i.as_str())
+                        .ok_or_else(|| "missing instructions".to_string())?;
+                    self.store.lock().unwrap().set_project_instructions(&id, instructions, now_ms())?;
+                    Ok(json!({ "project_id": id }))
+                }))
+            }
+
+            // ---- long-term memory (§12) --------------------------------------------------
+            (Method::Post, "/v1/memory") => self.finish_json(request, body_json().and_then(|v| {
+                let content =
+                    v.get("content").and_then(|c| c.as_str()).ok_or_else(|| "missing content".to_string())?;
+                // Namespace = "global" or a project id (validated).
+                let namespace = match v.get("project_id").and_then(|p| p.as_str()) {
+                    Some(p) => {
+                        self.store.lock().unwrap().get_project(p)?;
+                        p.to_string()
+                    }
+                    None => "global".to_string(),
+                };
+                let source_turn = v.get("source_turn_id").and_then(|t| t.as_str());
+                let id = fresh_id("mem");
+                let seq = self.store.lock().unwrap().add_memory(&id, &namespace, content, source_turn, now_ms())?;
+                Ok(json!({ "memory_id": id, "namespace": namespace, "created_sequence": seq }))
+            })),
+            (Method::Get, "/v1/memory") => self.finish_json(request, (|| {
+                let project = query_param(&url, "project_id");
+                let mut namespaces: Vec<&str> = vec!["global"];
+                if let Some(p) = &project {
+                    namespaces.push(p.as_str());
+                }
+                let rows = self.store.lock().unwrap().active_memory(&namespaces)?;
+                let list: Vec<Value> = rows
+                    .iter()
+                    .map(|m| {
+                        json!({
+                            "memory_id": m.memory_id,
+                            "namespace": m.namespace,
+                            "content": m.content,
+                            "source_turn_id": m.source_turn_id,
+                            "created_sequence": m.created_sequence,
+                            "created_ms": m.created_ms,
+                        })
+                    })
+                    .collect();
+                Ok(json!({ "memory": list }))
+            })()),
+            (Method::Post, p) if path_seg(p, "/v1/memory/", "/delete").is_some() => {
+                let id = path_seg(p, "/v1/memory/", "/delete").unwrap().to_string();
+                self.finish_json(request, (|| {
+                    self.store.lock().unwrap().delete_memory(&id)?;
+                    Ok(json!({ "memory_id": id, "deleted": true }))
+                })())
+            }
+
+            // ---- artifacts (§8/§9) -------------------------------------------------------
+            (Method::Post, "/v1/artifacts") => {
+                let outcome = (|| -> Result<Value, String> {
+                    let name = query_param(&url, "name").unwrap_or_default();
+                    let project_id = query_param(&url, "project_id");
+                    let parent = query_param(&url, "parent_artifact_id");
+                    let created_by_turn = query_param(&url, "created_by_turn");
+                    let mime = request
+                        .headers()
+                        .iter()
+                        .find(|h| h.field.equiv("Content-Type"))
+                        .map(|h| h.value.as_str().to_string())
+                        .unwrap_or_else(|| "application/octet-stream".into());
+                    if body.is_empty() {
+                        return Err("empty artifact body".into());
+                    }
+                    let content_hash = self.blobs.put(&body)?;
+                    let parser_policy = if std::str::from_utf8(&body).is_ok() {
+                        PARSER_POLICY_UTF8_TEXT_V1
+                    } else {
+                        "" // stored, but no parser can place it in context yet
+                    };
+                    let store = self.store.lock().unwrap();
+                    if let Some(p) = &project_id {
+                        store.get_project(p)?;
+                    }
+                    let meta = ArtifactMeta {
+                        artifact_id: fresh_id("art"),
+                        content_hash: content_hash.clone(),
+                        mime_type: mime,
+                        byte_length: body.len() as i64,
+                        display_name: name,
+                        parent_artifact_id: parent,
+                        version: 0, // derived by the store
+                        parser_policy: parser_policy.into(),
+                        project_id,
+                        created_by_turn,
+                        created_ms: now_ms(),
+                    };
+                    let version = store.insert_artifact(&meta)?;
+                    Ok(json!({
+                        "artifact_id": meta.artifact_id,
+                        "content_hash": content_hash,
+                        "byte_length": meta.byte_length,
+                        "version": version,
+                        "parser_policy": meta.parser_policy,
+                    }))
+                })();
+                self.finish_json(request, outcome)
+            }
+            (Method::Get, "/v1/artifacts") => self.finish_json(request, (|| {
+                let project = query_param(&url, "project_id");
+                let rows = self.store.lock().unwrap().list_artifacts(project.as_deref())?;
+                Ok(json!({ "artifacts": rows.iter().map(artifact_meta_json).collect::<Vec<_>>() }))
+            })()),
+            (Method::Get, p) if path_seg(p, "/v1/artifacts/", "/meta").is_some() => {
+                let id = path_seg(p, "/v1/artifacts/", "/meta").unwrap().to_string();
+                self.finish_json(request, (|| {
+                    let store = self.store.lock().unwrap();
+                    let meta = store.get_artifact(&id)?;
+                    let lineage = store.artifact_lineage(&id)?;
+                    let children = store.artifact_children(&id)?;
+                    Ok(json!({
+                        "artifact": artifact_meta_json(&meta),
+                        "lineage": lineage.iter().map(artifact_meta_json).collect::<Vec<_>>(),
+                        "children": children.iter().map(artifact_meta_json).collect::<Vec<_>>(),
+                    }))
+                })())
+            }
+            (Method::Get, p) if p.starts_with("/v1/artifacts/") && !p.trim_start_matches("/v1/artifacts/").contains('/') => {
+                let id = p.trim_start_matches("/v1/artifacts/").to_string();
+                let outcome = (|| -> Result<(Vec<u8>, String), String> {
+                    let meta = self.store.lock().unwrap().get_artifact(&id)?;
+                    let bytes = self.blobs.get_verified(&meta.content_hash)?;
+                    Ok((bytes, meta.mime_type))
+                })();
+                match outcome {
+                    Ok((bytes, mime)) => {
+                        let response = Response::from_data(bytes).with_header(
+                            Header::from_bytes("Content-Type", mime.as_bytes())
+                                .unwrap_or_else(|_| Header::from_bytes("Content-Type", "application/octet-stream").unwrap()),
+                        );
+                        let _ = request.respond(response);
+                    }
+                    Err(e) => {
+                        let _ = request.respond(err_response(404, &e));
+                    }
+                }
+                Ok(())
+            }
+
+            // ---- tools (§6) --------------------------------------------------------------
+            (Method::Get, "/v1/tools") => {
+                let list: Vec<Value> = TOOLS
+                    .iter()
+                    .map(|(name, mode, help)| {
+                        json!({
+                            "tool": name,
+                            "mode": mode.as_str(),
+                            "requires_approval": *mode == ToolExecutionMode::ExactlyOnceSideEffect,
+                            "description": help,
+                        })
+                    })
+                    .collect();
+                let _ = request.respond(json_response(200, &json!({ "tools": list })));
+                Ok(())
+            }
+            (Method::Post, "/v1/tools/execute") => self.finish_json(request, body_json().and_then(|v| self.tool_execute(&v))),
+            (Method::Post, p) if path_seg(p, "/v1/tools/calls/", "/approve").is_some() => {
+                let id = path_seg(p, "/v1/tools/calls/", "/approve").unwrap().to_string();
+                self.finish_json(request, self.tool_approve(&id))
+            }
+            (Method::Post, p) if path_seg(p, "/v1/tools/calls/", "/deny").is_some() => {
+                let id = path_seg(p, "/v1/tools/calls/", "/deny").unwrap().to_string();
+                self.finish_json(request, (|| {
+                    let store = self.store.lock().unwrap();
+                    store.deny_tool_call(&id)?;
+                    Ok(tool_call_json(&store.get_tool_call(&id)?))
+                })())
+            }
+            (Method::Get, p) if p.starts_with("/v1/tools/calls/") && !p.trim_start_matches("/v1/tools/calls/").contains('/') => {
+                let id = p.trim_start_matches("/v1/tools/calls/").to_string();
+                self.finish_json(request, self.store.lock().unwrap().get_tool_call(&id).map(|r| tool_call_json(&r)))
+            }
+
+            _ => {
+                let _ = request.respond(err_response(404, "no such route"));
+                Ok(())
+            }
+        };
+        if let Err(e) = result {
+            eprintln!("[palw-gateway] {method} {path}: {e}");
+        }
+    }
+
+    fn loopback(&self) -> Result<&Arc<LoopbackCoordinator>, String> {
+        self.palw_loopback
+            .as_ref()
+            .ok_or_else(|| "loopback coordinator not enabled on this instance (--palw-loopback)".to_string())
+    }
+
+    /// Respond 200 with the value, or 400 with the error — the uniform JSON endpoint shape.
+    fn finish_json(&self, request: Request, outcome: Result<Value, String>) -> Result<(), String> {
+        match outcome {
+            Ok(v) => {
+                let _ = request.respond(json_response(200, &v));
+            }
+            Err(e) => {
+                let code = if e.contains("not found") || e.contains("no such") { 404 } else { 400 };
+                let _ = request.respond(err_response(code, &e));
+            }
+        }
+        Ok(())
+    }
+
+    // ---- tool runtime glue --------------------------------------------------------------
+
+    /// POST /v1/tools/execute — deterministic/read-only tools run NOW (and are snapshotted);
+    /// side-effect tools are stored as proposals awaiting `/approve`.
+    fn tool_execute(&self, v: &Value) -> Result<Value, String> {
+        let tool = v.get("tool").and_then(|t| t.as_str()).ok_or_else(|| "missing tool".to_string())?;
+        let mode = mode_of(tool).ok_or_else(|| format!("unknown tool {tool:?}"))?;
+        let arguments = v.get("arguments").cloned().unwrap_or_else(|| json!({}));
+        let conversation_id = v.get("conversation_id").and_then(|c| c.as_str()).map(String::from);
+        let call_id = fresh_id("call");
+        let now = now_ms();
+
+        let initial_status = match mode {
+            ToolExecutionMode::ExactlyOnceSideEffect => "proposed",
+            _ => "executing",
+        };
+        {
+            let store = self.store.lock().unwrap();
+            store.insert_tool_call(&ToolCallRow {
+                call_id: call_id.clone(),
+                tool_name: tool.into(),
+                mode: mode.as_str().into(),
+                arguments_json: serde_json::to_string(&arguments).map_err(|e| e.to_string())?,
+                status: initial_status.into(),
+                result_artifact_id: None,
+                result_preview: String::new(),
+                error: None,
+                conversation_id,
+                created_ms: now,
+                executed_ms: None,
+            })?;
+        }
+        if mode == ToolExecutionMode::ExactlyOnceSideEffect {
+            let row = self.store.lock().unwrap().get_tool_call(&call_id)?;
+            return Ok(tool_call_json(&row));
+        }
+        self.run_claimed_tool(&call_id, tool, &arguments)
+    }
+
+    /// POST /v1/tools/calls/{id}/approve — the user's confirmation; claims the exactly-once
+    /// ticket and executes.
+    fn tool_approve(&self, call_id: &str) -> Result<Value, String> {
+        let (tool, arguments) = {
+            let store = self.store.lock().unwrap();
+            let row = store.get_tool_call(call_id)?;
+            store.approve_tool_call(call_id)?;
+            store.claim_tool_execution(call_id)?;
+            let args: Value = serde_json::from_str(&row.arguments_json).map_err(|e| e.to_string())?;
+            (row.tool_name, args)
+        };
+        self.run_claimed_tool(call_id, &tool, &arguments)
+    }
+
+    /// Shared tail: the call row is in `executing`; run the tool, snapshot the result as a
+    /// content-addressed artifact, finish the row either way.
+    fn run_claimed_tool(&self, call_id: &str, tool: &str, arguments: &Value) -> Result<Value, String> {
+        let executed = self.tools.execute(tool, arguments);
+        let now = now_ms();
+        let store = self.store.lock().unwrap();
+        match executed {
+            Ok(outcome) => {
+                let content_hash = self.blobs.put(&outcome.output)?;
+                let artifact_id = fresh_id("art");
+                store.insert_artifact(&ArtifactMeta {
+                    artifact_id: artifact_id.clone(),
+                    content_hash,
+                    mime_type: outcome.mime.into(),
+                    byte_length: outcome.output.len() as i64,
+                    display_name: format!("tool:{tool}"),
+                    parent_artifact_id: None,
+                    version: 0,
+                    parser_policy: if std::str::from_utf8(&outcome.output).is_ok() {
+                        PARSER_POLICY_UTF8_TEXT_V1.into()
+                    } else {
+                        String::new()
+                    },
+                    project_id: None,
+                    created_by_turn: None,
+                    created_ms: now,
+                })?;
+                store.finish_tool_call(call_id, true, Some(&artifact_id), &outcome.preview, None, now)?;
+            }
+            Err(e) => {
+                store.finish_tool_call(call_id, false, None, "", Some(&e), now)?;
+            }
+        }
+        Ok(tool_call_json(&store.get_tool_call(call_id)?))
+    }
+
+    // ---- LM Studio bridge ---------------------------------------------------------------
+
+    /// Run the search sidecar for one query. Fail-open BY DESIGN: any sidecar-level failure
+    /// (spawn error, timeout, bad JSON) logs and returns `None`, and the turn proceeds
+    /// searchless — a broken search stack must degrade the answer, never block the chat.
+    /// (Search failures *inside* the stack are typed into a failure bundle by the sidecar and
+    /// still commit as evidence, exactly like the legacy server.)
+    fn run_search_sidecar(&self, query: &str, previous_user_query: Option<&str>) -> Option<TurnSearch> {
+        const SIDECAR_TIMEOUT_MS: u64 = 90_000;
+        let program = self.search_cmd.as_ref()?;
+        let attempt = (|| -> Result<Option<TurnSearch>, String> {
+            let mut child = std::process::Command::new(program)
+                .stdin(std::process::Stdio::piped())
+                .stdout(std::process::Stdio::piped())
+                .stderr(std::process::Stdio::piped())
+                .spawn()
+                .map_err(|e| format!("spawn {}: {e}", program.display()))?;
+            {
+                use std::io::Write as _;
+                let mut stdin = child.stdin.take().ok_or("sidecar stdin unavailable")?;
+                let request = json!({ "query": query, "previous_user_query": previous_user_query });
+                stdin.write_all(request.to_string().as_bytes()).map_err(|e| e.to_string())?;
+            } // drop closes stdin — the sidecar reads to EOF
+            let stdout = child.stdout.take().ok_or("sidecar stdout unavailable")?;
+            let reader = std::thread::spawn(move || {
+                use std::io::Read as _;
+                let mut out = String::new();
+                let mut handle = stdout;
+                let _ = handle.read_to_string(&mut out);
+                out
+            });
+            let deadline = std::time::Instant::now() + std::time::Duration::from_millis(SIDECAR_TIMEOUT_MS);
+            loop {
+                match child.try_wait().map_err(|e| e.to_string())? {
+                    Some(status) => {
+                        let out = reader.join().unwrap_or_default();
+                        if !status.success() {
+                            return Err(format!("sidecar exit {status}"));
+                        }
+                        let reply: Value = serde_json::from_str(out.trim()).map_err(|e| format!("sidecar json: {e}"))?;
+                        if let Some(error) = reply.get("error").and_then(|e| e.as_str()) {
+                            return Err(format!("sidecar error: {error}"));
+                        }
+                        if reply.get("searched").and_then(|s| s.as_bool()) != Some(true) {
+                            return Ok(None);
+                        }
+                        let field = |k: &str| -> Result<String, String> {
+                            reply
+                                .get(k)
+                                .and_then(|v| v.as_str())
+                                .map(String::from)
+                                .ok_or_else(|| format!("sidecar reply missing {k}"))
+                        };
+                        let bundle = reply.get("bundle").ok_or("sidecar reply missing bundle")?;
+                        let summary_lines = reply
+                            .get("summary_lines")
+                            .and_then(|l| l.as_array())
+                            .map(|a| a.iter().filter_map(|v| v.as_str().map(String::from)).collect())
+                            .unwrap_or_default();
+                        return Ok(Some(TurnSearch {
+                            query: field("query")?,
+                            context: SearchForContext {
+                                evidence_text: field("evidence_text")?,
+                                bundle_sha256: field("bundle_sha256")?,
+                                effective_compression: field("effective_compression")?,
+                            },
+                            bundle_json: serde_json::to_string(bundle).map_err(|e| e.to_string())?,
+                            summary_lines,
+                        }));
+                    }
+                    None if std::time::Instant::now() >= deadline => {
+                        let _ = child.kill();
+                        let _ = child.wait();
+                        return Err(format!("sidecar timeout after {SIDECAR_TIMEOUT_MS}ms"));
+                    }
+                    None => std::thread::sleep(std::time::Duration::from_millis(30)),
+                }
+            }
+        })();
+        match attempt {
+            Ok(result) => result,
+            Err(e) => {
+                eprintln!("[palw-gateway] search sidecar: {e} — continuing without search");
+                None
+            }
+        }
+    }
+
+    /// POST /v1/lmstudio/turn — body `{ "messages": [{role, content}…], "privacy_mode"? }`.
+    ///
+    /// The stateful LM Studio path: the transcript is resolved onto the session store by
+    /// content (`lmstudio::resolve` — continue / branch / new / import), then the turn runs
+    /// through the SAME native pipeline as `/v1/sessions/{id}/messages`: id-stable compiled
+    /// prompt (prefix cache hits), engine receipt + runtime ROOTS persisted on the turn,
+    /// settlement pipeline per `privacy_mode`. The stream is `GenerationEventV1` prefixed with
+    /// one `lmstudio_resolve` frame that also reports the parent turn's current settlement
+    /// status — that is how the plugin shows last turn's verification without polling mid-chat.
+    fn lmstudio_turn(self: &Arc<Self>, request: Request, parsed: &Value) -> Result<(), String> {
+        let empty = Vec::new();
+        let messages = parsed.get("messages").and_then(|m| m.as_array()).unwrap_or(&empty);
+        let (pairs, user_text) = match lmstudio::fold_messages(messages) {
+            Ok(f) => f,
+            Err(e) => {
+                let _ = request.respond(err_response(400, &e));
+                return Ok(());
+            }
+        };
+        let privacy_str = parsed
+            .get("privacy_mode")
+            .and_then(|p| p.as_str())
+            .unwrap_or(TurnPrivacyMode::LocalOnly.as_str())
+            .to_string();
+
+        let planned = (|| -> Result<_, String> {
+            let mut store = self.store.lock().unwrap();
+            let plan = lmstudio::resolve(&store, &pairs)?;
+            let (conversation_id, parent_turn_id, imported_turns) = match &plan.conversation_id {
+                Some(conv) => (conv.clone(), plan.parent_turn_id.clone(), 0usize),
+                None => {
+                    let conv = fresh_id("conv");
+                    let title: String = user_text.trim().chars().take(48).collect();
+                    store.create_conversation(&conv, title.trim(), None, now_ms())?;
+                    let leaf = if plan.kind == ResolutionKind::Imported {
+                        lmstudio::import_pairs(&mut store, &self.tokenizer, &conv, &pairs, || fresh_id("turn"), now_ms())?
+                    } else {
+                        None
+                    };
+                    let imported = if leaf.is_some() { pairs.len() } else { 0 };
+                    (conv, leaf, imported)
+                }
+            };
+            let parent_info = match &parent_turn_id {
+                Some(id) => {
+                    let t = store.get_turn(id)?;
+                    json!({
+                        "turn_id": t.turn_id,
+                        "verification_status": t.verification_status.as_str(),
+                        "privacy_mode": t.privacy_mode.as_str(),
+                        "receipt_present": t.receipt_json.is_some(),
+                    })
+                }
+                None => Value::Null,
+            };
+            let certified_head = store.heads(&conversation_id)?.certified_head;
+            Ok((plan.kind, plan.matched_pairs, conversation_id, parent_turn_id, imported_turns, parent_info, certified_head))
+        })();
+        let (kind, matched_pairs, conversation_id, parent_turn_id, imported_turns, parent_info, certified_head) =
+            match planned {
+                Ok(p) => p,
+                Err(e) => {
+                    let _ = request.respond(err_response(500, &e));
+                    return Ok(());
+                }
+            };
+
+        let mut preambles = vec![json!({
+            "type": "lmstudio_resolve",
+            "resolution": kind.as_str(),
+            "conversation_id": conversation_id,
+            "parent_turn_id": parent_turn_id,
+            "matched_pairs": matched_pairs,
+            "imported_turns": imported_turns,
+            "parent": parent_info,
+            "certified_head": certified_head,
+        })];
+
+        // GPT-style live search, reusing the legacy stack via the sidecar. Runs after resolve
+        // (which only reads past pairs) and before compile; the rendered evidence joins the
+        // user block, so the receipt's prompt commitment covers the bundle digest.
+        let search = self.run_search_sidecar(&user_text, pairs.last().map(|p| p.user.as_str()));
+        let user_text = search.as_ref().map(|s| s.query.clone()).unwrap_or(user_text);
+        if let Some(s) = &search {
+            preambles.push(json!({
+                "type": "search_status",
+                "lines": s.summary_lines,
+                "bundle_sha256": s.context.bundle_sha256,
+            }));
+        }
+
+        let synth = json!({
+            "text": user_text,
+            "parent_turn_id": parent_turn_id,
+            "privacy_mode": privacy_str,
+        });
+        self.session_message(request, &conversation_id, &synth, preambles, search)
+    }
+
+    /// GET /v1/turns/{id} — settlement status + receipt summary for one turn (the plugin's
+    /// post-turn poll target; also generally useful observability).
+    fn turn_info(&self, request: Request, turn_id: &str) -> Result<(), String> {
+        let looked_up = (|| -> Result<_, String> {
+            let store = self.store.lock().unwrap();
+            let turn = store.get_turn(turn_id)?;
+            let certified_head = store.heads(&turn.conversation_id)?.certified_head;
+            Ok((turn, certified_head))
+        })();
+        let (turn, certified_head) = match looked_up {
+            Ok(t) => t,
+            Err(e) => {
+                let _ = request.respond(err_response(404, &e));
+                return Ok(());
+            }
+        };
+        let receipt = match turn.receipt_json.as_deref() {
+            Some(raw) => {
+                let v: Value = serde_json::from_str(raw).unwrap_or(Value::Null);
+                let field = |k: &str| v.get(k).cloned().unwrap_or(Value::Null);
+                json!({
+                    "present": true,
+                    "schema": field("schema"),
+                    "class": field("class"),
+                    "prompt_commitment": field("prompt_commitment"),
+                    "output_commitment": field("output_commitment"),
+                    "signer_key_id": field("signer_key_id"),
+                    "backend": field("backend"),
+                    "eos_reached": field("eos_reached"),
+                })
+            }
+            None => json!({ "present": false }),
+        };
+        let _ = request.respond(json_response(
+            200,
+            &json!({
+                "turn_id": turn.turn_id,
+                "conversation_id": turn.conversation_id,
+                "parent_turn_id": turn.parent_turn_id,
+                "verification_status": turn.verification_status.as_str(),
+                "privacy_mode": turn.privacy_mode.as_str(),
+                "stop_reason": turn.stop_reason,
+                "output_tokens": turn.output_ids.len(),
+                "created_ms": turn.created_ms,
+                "certified_head": certified_head,
+                "receipt": receipt,
+                "runtime_roots": turn
+                    .runtime_roots_json
+                    .as_deref()
+                    .and_then(|r| serde_json::from_str::<Value>(r).ok()),
+                "search": match turn.search_bundle_json.as_deref() {
+                    Some(raw) => {
+                        let bundle: Value = serde_json::from_str(raw).unwrap_or(Value::Null);
+                        json!({
+                            "present": true,
+                            "bundle_sha256": bundle.get("bundle_sha256").cloned().unwrap_or(Value::Null),
+                            "provider": bundle.get("provider").cloned().unwrap_or(Value::Null),
+                        })
+                    }
+                    None => json!({ "present": false }),
+                },
+            }),
+        ));
+        Ok(())
+    }
+
+    /// GET /v1/turns/{id}/receipt — the engine receipt JSON verbatim (404 when the turn ran
+    /// without an audit key or predates receipts).
+    fn turn_receipt(&self, request: Request, turn_id: &str) -> Result<(), String> {
+        let receipt = match self.store.lock().unwrap().get_turn(turn_id) {
+            Ok(t) => t.receipt_json,
+            Err(e) => {
+                let _ = request.respond(err_response(404, &e));
+                return Ok(());
+            }
+        };
+        match receipt {
+            Some(raw) => {
+                let response = Response::from_data(raw.into_bytes())
+                    .with_status_code(200)
+                    .with_header(Header::from_bytes("Content-Type", "application/json").unwrap());
+                let _ = request.respond(response);
+            }
+            None => {
+                let _ = request.respond(err_response(404, "turn has no receipt"));
+            }
+        }
+        Ok(())
+    }
+
+    /// Write `.receipt.json` + `.opening.json` sidecars for a completed turn into
+    /// `--receipt-dir` (dir 0700, files 0600 — the legacy server's convention). The receipt is
+    /// the engine's JSON verbatim; the opening records what an offline verifier needs to replay
+    /// the commitment: exact prompt/output ids, the tokenizer digest they decode under, and the
+    /// turn's identity in the session store.
+    fn write_receipt_sidecars(&self, turn_id: &str) -> Result<(), String> {
+        let Some(dir) = &self.receipt_dir else { return Ok(()) };
+        let turn = self.store.lock().unwrap().get_turn(turn_id)?;
+        let receipt = turn.receipt_json.as_deref().ok_or("turn has no receipt")?;
+        std::fs::create_dir_all(dir).map_err(|e| format!("create {}: {e}", dir.display()))?;
+        #[cfg(unix)]
+        {
+            use std::os::unix::fs::PermissionsExt;
+            let _ = std::fs::set_permissions(dir, std::fs::Permissions::from_mode(0o700));
+        }
+        let commitment16: String = serde_json::from_str::<Value>(receipt)
+            .ok()
+            .and_then(|v| v.get("output_commitment").and_then(|c| c.as_str()).map(|s| s.chars().take(16).collect()))
+            .unwrap_or_default();
+        let base = if commitment16.is_empty() {
+            format!("turn-{turn_id}")
+        } else {
+            format!("turn-{turn_id}-{commitment16}")
+        };
+        // Legacy convention: the .search.json sidecar is the full bundle plus the receipt
+        // binding, so a verifier can tie the bundle to this exact generation.
+        if let Some(bundle_raw) = turn.search_bundle_json.as_deref() {
+            if let Ok(mut bundle) = serde_json::from_str::<Value>(bundle_raw) {
+                if let Some(map) = bundle.as_object_mut() {
+                    let receipt_value: Value = serde_json::from_str(receipt).unwrap_or(Value::Null);
+                    map.insert(
+                        "receipt_binding".into(),
+                        json!({
+                            "prompt_commitment": receipt_value.get("prompt_commitment").cloned().unwrap_or(Value::Null),
+                            "output_commitment": receipt_value.get("output_commitment").cloned().unwrap_or(Value::Null),
+                        }),
+                    );
+                }
+                let path = dir.join(format!("{base}.search.json"));
+                let bytes = serde_json::to_vec_pretty(&bundle).map_err(|e| e.to_string())?;
+                std::fs::write(&path, &bytes).map_err(|e| format!("write {}: {e}", path.display()))?;
+                #[cfg(unix)]
+                {
+                    use std::os::unix::fs::PermissionsExt;
+                    let _ = std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o600));
+                }
+            }
+        }
+        let opening = json!({
+            "schema": "qi35-gateway-opening/v1",
+            "turn_id": turn.turn_id,
+            "conversation_id": turn.conversation_id,
+            "parent_turn_id": turn.parent_turn_id,
+            "privacy_mode": turn.privacy_mode.as_str(),
+            "verification_status_at_write": turn.verification_status.as_str(),
+            "stop_reason": turn.stop_reason,
+            "user_text": turn.role_user_text,
+            "user_block_text": turn.user_block(),
+            "tokenizer_blake2b256": self.tokenizer.digest_hex,
+            "prompt_ids": turn.prompt_ids,
+            "output_ids": turn.output_ids,
+            "runtime_roots": turn.runtime_roots_json.as_deref().and_then(|r| serde_json::from_str::<Value>(r).ok()),
+            "context_meta": turn.context_meta_json.as_deref().and_then(|m| serde_json::from_str::<Value>(m).ok()),
+            "created_ms": turn.created_ms,
+        });
+        for (suffix, bytes) in [
+            (".receipt.json", receipt.as_bytes().to_vec()),
+            (".opening.json", serde_json::to_vec_pretty(&opening).map_err(|e| e.to_string())?),
+        ] {
+            let path = dir.join(format!("{base}{suffix}"));
+            std::fs::write(&path, &bytes).map_err(|e| format!("write {}: {e}", path.display()))?;
+            #[cfg(unix)]
+            {
+                use std::os::unix::fs::PermissionsExt;
+                let _ = std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o600));
+            }
+        }
+        Ok(())
+    }
+
+    // ---- session surface ----------------------------------------------------------------
+
+    fn session_history(&self, request: Request, conversation_id: &str) -> Result<(), String> {
+        let store = self.store.lock().unwrap();
+        let heads = match store.heads(conversation_id) {
+            Ok(h) => h,
+            Err(e) => {
+                let _ = request.respond(err_response(404, &e));
+                return Ok(());
+            }
+        };
+        let turns = match &heads.local_head {
+            Some(leaf) => store.branch_history(leaf)?,
+            None => Vec::new(),
+        };
+        let list: Vec<Value> = turns
+            .iter()
+            .map(|t| {
+                json!({
+                    "turn_id": t.turn_id,
+                    "parent_turn_id": t.parent_turn_id,
+                    "user_text": t.role_user_text,
+                    "assistant_text": t.display_text,
+                    "verification_status": t.verification_status.as_str(),
+                    "privacy_mode": t.privacy_mode.as_str(),
+                    "stop_reason": t.stop_reason,
+                    "context_meta": t.context_meta_json.as_deref().and_then(|m| serde_json::from_str::<Value>(m).ok()),
+                    "created_ms": t.created_ms,
+                })
+            })
+            .collect();
+        let _ = request.respond(json_response(
+            200,
+            &json!({ "local_head": heads.local_head, "certified_head": heads.certified_head, "turns": list }),
+        ));
+        Ok(())
+    }
+
+    /// The native turn endpoint. Body:
+    /// `{ "text": …, "parent_turn_id"?, "privacy_mode"?, "artifact_ids"?: […], "tool_call_ids"?: […] }`.
+    /// `parent_turn_id` other than the current head IS the branch/edit/regenerate mechanism;
+    /// attachments and executed tool results are compiled into THIS turn's user block.
+    /// `preambles` (used by the LM Studio bridge) are streamed as raw SSE frames before
+    /// `Started`, so the client learns how its transcript resolved (and what was searched)
+    /// before tokens arrive. `search` joins the compiled user block and is persisted on the
+    /// turn as the committed bundle.
+    fn session_message(
+        self: &Arc<Self>,
+        request: Request,
+        conversation_id: &str,
+        parsed: &Value,
+        preambles: Vec<Value>,
+        search: Option<TurnSearch>,
+    ) -> Result<(), String> {
+        let user_text = match parsed.get("text").and_then(|t| t.as_str()) {
+            Some(t) if !t.is_empty() => t.to_string(),
+            _ => {
+                let _ = request.respond(err_response(400, "missing text"));
+                return Ok(());
+            }
+        };
+        let privacy = parsed
+            .get("privacy_mode")
+            .and_then(|p| p.as_str())
+            .and_then(TurnPrivacyMode::from_str)
+            .unwrap_or(TurnPrivacyMode::LocalOnly);
+        let id_list = |key: &str| -> Vec<String> {
+            parsed
+                .get(key)
+                .and_then(|v| v.as_array())
+                .map(|a| a.iter().filter_map(|x| x.as_str().map(String::from)).collect())
+                .unwrap_or_default()
+        };
+        let artifact_ids = id_list("artifact_ids");
+        let tool_call_ids = id_list("tool_call_ids");
+
+        // Gather everything the compiler needs under one store lock; blob reads happen outside.
+        let gathered = (|| -> Result<_, String> {
+            let store = self.store.lock().unwrap();
+            let heads = store.heads(conversation_id)?;
+            let parent = parsed
+                .get("parent_turn_id")
+                .and_then(|p| p.as_str())
+                .map(String::from)
+                .or(heads.local_head.clone());
+            let history = match &parent {
+                Some(leaf) => store.branch_history(leaf)?,
+                None => Vec::new(),
+            };
+            let project = match store.conversation_project(conversation_id)? {
+                Some(pid) => Some(store.get_project(&pid)?),
+                None => None,
+            };
+            let mut namespaces = vec!["global".to_string()];
+            if let Some(p) = &project {
+                namespaces.push(p.project_id.clone());
+            }
+            let namespace_refs: Vec<&str> = namespaces.iter().map(String::as_str).collect();
+            let memory = store.active_memory(&namespace_refs)?;
+            let attachment_meta: Vec<ArtifactMeta> =
+                artifact_ids.iter().map(|id| store.get_artifact(id)).collect::<Result<_, _>>()?;
+            let tool_rows: Vec<ToolCallRow> =
+                tool_call_ids.iter().map(|id| store.get_tool_call(id)).collect::<Result<_, _>>()?;
+            Ok((parent, history, project, memory, attachment_meta, tool_rows))
+        })();
+        let (parent, history, project, memory, attachment_meta, tool_rows) = match gathered {
+            Ok(g) => g,
+            Err(e) => {
+                let _ = request.respond(err_response(404, &e));
+                return Ok(());
+            }
+        };
+
+        let prepared = (|| -> Result<_, String> {
+            let mut attachments = Vec::new();
+            for meta in &attachment_meta {
+                if meta.parser_policy != PARSER_POLICY_UTF8_TEXT_V1 {
+                    return Err(format!(
+                        "artifact {} has no context parser (policy {:?}) — only UTF-8 text artifacts can attach in v1",
+                        meta.artifact_id, meta.parser_policy
+                    ));
+                }
+                attachments.push(AttachmentForContext {
+                    artifact_id: meta.artifact_id.clone(),
+                    display_name: if meta.display_name.is_empty() { meta.artifact_id.clone() } else { meta.display_name.clone() },
+                    content_hash: meta.content_hash.clone(),
+                    text: self.blobs.parse_utf8_text(&meta.content_hash)?,
+                });
+            }
+            let mut tool_results = Vec::new();
+            for row in &tool_rows {
+                if row.status != "executed" {
+                    return Err(format!("tool call {} is {:?} — only executed calls can enter context", row.call_id, row.status));
+                }
+                let text = match &row.result_artifact_id {
+                    Some(artifact_id) => {
+                        let meta = self.store.lock().unwrap().get_artifact(artifact_id)?;
+                        self.blobs.parse_utf8_text(&meta.content_hash).unwrap_or_else(|_| row.result_preview.clone())
+                    }
+                    None => row.result_preview.clone(),
+                };
+                tool_results.push(ToolResultForContext { call_id: row.call_id.clone(), tool_name: row.tool_name.clone(), text });
+            }
+            Ok((attachments, tool_results))
+        })();
+        let (attachments, tool_results) = match prepared {
+            Ok(p) => p,
+            Err(e) => {
+                let _ = request.respond(err_response(400, &e));
+                return Ok(());
+            }
+        };
+
+        let memory_ctx: Vec<MemoryForContext> = memory
+            .iter()
+            .map(|m| MemoryForContext { memory_id: m.memory_id.clone(), content: m.content.clone() })
+            .collect();
+        let inputs = ContextInputs {
+            project_instructions: project.as_ref().map(|p| p.instructions.as_str()),
+            memory: &memory_ctx,
+            attachments: &attachments,
+            tool_results: &tool_results,
+            history: &history,
+            user_text: &user_text,
+            search: search.as_ref().map(|s| s.context.clone()),
+        };
+        let compiled = match self.compiler.compile(&self.tokenizer, &inputs) {
+            Ok(c) => c,
+            Err(e) => {
+                let _ = request.respond(err_response(400, &e));
+                return Ok(());
+            }
+        };
+
+        let turn_id = fresh_id("turn");
+        let job_id = fresh_id("job");
+        {
+            let mut store = self.store.lock().unwrap();
+            if let Err(e) = store.begin_turn(&NewTurn {
+                turn_id: &turn_id,
+                conversation_id,
+                parent_turn_id: parent.as_deref(),
+                role_user_text: &user_text,
+                user_block_text: &compiled.user_block_text,
+                context_meta_json: Some(&compiled.context_meta_json),
+                prompt_ids: &compiled.ids,
+                privacy_mode: privacy,
+                search_bundle_json: search.as_ref().map(|s| s.bundle_json.as_str()),
+                now_ms: now_ms(),
+            }) {
+                let _ = request.respond(err_response(500, &e));
+                return Ok(());
+            }
+        }
+
+        let cancel = Arc::new(AtomicBool::new(false));
+        self.cancels.lock().unwrap().insert(job_id.clone(), Arc::clone(&cancel));
+
+        let stream_result = self.stream_generation(
+            request,
+            &job_id,
+            &turn_id,
+            &compiled.ids,
+            compiled.system_prefix_len,
+            compiled.dropped_turns,
+            &cancel,
+            preambles,
+        );
+        self.cancels.lock().unwrap().remove(&job_id);
+        stream_result
+    }
+
+    #[allow(clippy::too_many_arguments)]
+    fn stream_generation(
+        &self,
+        request: Request,
+        job_id: &str,
+        turn_id: &str,
+        prompt_ids: &[u32],
+        cache_prefix_len: usize,
+        dropped_turns: usize,
+        cancel: &Arc<AtomicBool>,
+        preambles: Vec<Value>,
+    ) -> Result<(), String> {
+        let mut writer = request.into_writer();
+        let mut sse = SseWriter::new(&mut writer)?;
+        for frame in &preambles {
+            sse.raw(frame)?;
+        }
+        sse.event(&GenerationEventV1::Started {
+            job_id: job_id.to_string(),
+            turn_id: turn_id.to_string(),
+            prompt_tokens: prompt_ids.len() as u32,
+        })?;
+        if dropped_turns > 0 {
+            // No silent truncation (the doc's rule): surface the budget cut in-stream.
+            sse.raw(&json!({ "type": "context_budget", "dropped_turns": dropped_turns }))?;
+        }
+
+        let mut decoder = IncrementalDecoder::new();
+        let outcome = {
+            // §14: the user-facing turn goes through the scheduler as ForegroundChat — it
+            // overtakes any queued background work, then owns the engine.
+            let _lease = self.scheduler.acquire(JobClass::ForegroundChat);
+            let mut engine = self.engine.lock().unwrap();
+            let tokenizer = &self.tokenizer;
+            let sse_cell = std::cell::RefCell::new(&mut sse);
+            engine.generate(prompt_ids, cache_prefix_len, cancel, |index, token_id| {
+                let delta = decoder.push(tokenizer, token_id).unwrap_or_default();
+                let _ = sse_cell.borrow_mut().event(&GenerationEventV1::Token {
+                    index,
+                    token_id,
+                    utf8_delta: delta,
+                });
+            })
+        };
+
+        match outcome {
+            Ok(outcome) => {
+                self.scheduler.record_generation(outcome.output_ids.len() as u64, outcome.elapsed_ms);
+                let tail = decoder.finish(&self.tokenizer).unwrap_or_default();
+                if !tail.is_empty() && !cancel.load(Ordering::Relaxed) {
+                    let last_index = outcome.output_ids.len().saturating_sub(1) as u32;
+                    sse.event(&GenerationEventV1::Token { index: last_index, token_id: 0, utf8_delta: tail })?;
+                }
+                let cancelled = cancel.load(Ordering::Relaxed);
+                let stop = if cancelled {
+                    CanonicalStopReason::UserCancelled
+                } else if outcome.eos_reached {
+                    CanonicalStopReason::Eos
+                } else {
+                    CanonicalStopReason::MaxTokens
+                };
+                let status = if cancelled {
+                    TurnVerificationStatus::MintIneligible
+                } else {
+                    TurnVerificationStatus::LocalComplete
+                };
+                let display = self.tokenizer.decode_display(&outcome.output_ids).unwrap_or_default();
+                let roots_json = outcome.runtime_roots.as_ref().and_then(|r| serde_json::to_string(r).ok());
+                self.store
+                    .lock()
+                    .unwrap()
+                    .complete_turn(&crate::store::CompletedTurn {
+                        turn_id,
+                        output_ids: &outcome.output_ids,
+                        display_text: display.trim(),
+                        stop_reason: match stop {
+                            CanonicalStopReason::Eos => "eos",
+                            CanonicalStopReason::MaxTokens => "max_tokens",
+                            CanonicalStopReason::UserCancelled => "user_cancelled",
+                        },
+                        status,
+                        receipt_json: outcome.receipt_json.as_deref(),
+                        runtime_roots_json: roots_json.as_deref(),
+                    })
+                    .map_err(|e| format!("persist turn: {e}"))?;
+                if outcome.receipt_json.is_some() {
+                    // Sidecar failure never fails the turn — the receipt is durable in the store;
+                    // the files are the offline-verifier convenience form.
+                    if let Err(e) = self.write_receipt_sidecars(turn_id) {
+                        eprintln!("[palw-gateway] receipt sidecar for {turn_id}: {e}");
+                    }
+                }
+                sse.event(&GenerationEventV1::Completed {
+                    stop_reason: stop,
+                    output_tokens: outcome.output_ids.len() as u32,
+                    cache_hit_tokens: outcome.cache_hit_tokens,
+                    elapsed_ms: outcome.elapsed_ms,
+                })?;
+                sse.done()
+            }
+            Err(e) => {
+                {
+                    let store = self.store.lock().unwrap();
+                    let _ = store.complete_turn(&crate::store::CompletedTurn {
+                        turn_id,
+                        output_ids: &[],
+                        display_text: "",
+                        stop_reason: "engine_error",
+                        status: TurnVerificationStatus::MintIneligible,
+                        receipt_json: None,
+                        runtime_roots_json: None,
+                    });
+                    // Failed turns do not anchor the branch: the next message retries from the
+                    // parent instead of building on a turn that produced nothing.
+                    if let Ok(turn) = store.get_turn(turn_id) {
+                        let _ = store.retract_failed_head(&turn.conversation_id, turn_id, now_ms());
+                    }
+                }
+                sse.event(&GenerationEventV1::Failed { error_code: 1, message: e.clone() })?;
+                sse.done()?;
+                Err(e)
+            }
+        }
+    }
+
+    /// OpenAI-compatible stateless path (existing LM Studio plugin). Transcript comes from the
+    /// client; we build ChatML text exactly like `qi35_chat.py` did, but through the compiler's
+    /// fragment assembly so at least the system prefix caches.
+    fn chat_completions(self: &Arc<Self>, request: Request, parsed: &Value) -> Result<(), String> {
+        let empty = Vec::new();
+        let messages = parsed.get("messages").and_then(|m| m.as_array()).unwrap_or(&empty);
+        // Fold OpenAI messages[] into (history pairs, pending user) — the qi35_lmstudio_server
+        // `conversation()` shape.
+        let mut history: Vec<crate::store::StoredTurn> = Vec::new();
+        let mut pending_user: Option<String> = None;
+        for m in messages {
+            let role = m.get("role").and_then(|r| r.as_str()).unwrap_or("");
+            let content = m.get("content").and_then(|c| c.as_str()).unwrap_or("").to_string();
+            match role {
+                "user" => {
+                    if let Some(prev) = pending_user.take() {
+                        // Two users in a row: treat the earlier as a turn with empty answer.
+                        history.push(synthetic_turn(prev, Vec::new()));
+                    }
+                    pending_user = Some(content);
+                }
+                "assistant" => {
+                    let user = pending_user.take().unwrap_or_default();
+                    // Stateless path: the client only has TEXT, so we must encode the past
+                    // answer. This is exactly the id-instability the native path exists to
+                    // avoid — done once here for compatibility, flagged in the response.
+                    let ids = self.tokenizer.encode_lossless(&content).unwrap_or_default();
+                    history.push(synthetic_turn(user, ids));
+                }
+                _ => {}
+            }
+        }
+        let Some(user_text) = pending_user else {
+            let _ = request.respond(err_response(400, "no trailing user message"));
+            return Ok(());
+        };
+        let inputs = ContextInputs { history: &history, user_text: &user_text, ..Default::default() };
+        let compiled = match self.compiler.compile(&self.tokenizer, &inputs) {
+            Ok(c) => c,
+            Err(e) => {
+                let _ = request.respond(err_response(400, &e));
+                return Ok(());
+            }
+        };
+
+        let cancel = Arc::new(AtomicBool::new(false));
+        let mut writer = request.into_writer();
+        let mut sse = SseWriter::new(&mut writer)?;
+        let created = now_ms() / 1000;
+        let model = self.model_name.clone();
+        let mut decoder = IncrementalDecoder::new();
+        let outcome = {
+            let _lease = self.scheduler.acquire(JobClass::ForegroundChat);
+            let mut engine = self.engine.lock().unwrap();
+            let tokenizer = &self.tokenizer;
+            let sse_cell = std::cell::RefCell::new(&mut sse);
+            engine.generate(&compiled.ids, compiled.system_prefix_len, &cancel, |_, token_id| {
+                if let Ok(delta) = decoder.push(tokenizer, token_id) {
+                    if !delta.is_empty() {
+                        let chunk = json!({
+                            "object": "chat.completion.chunk",
+                            "created": created,
+                            "model": model,
+                            "choices": [{ "index": 0, "delta": { "content": delta }, "finish_reason": Value::Null }],
+                        });
+                        let _ = sse_cell.borrow_mut().raw(&chunk);
+                    }
+                }
+            })
+        };
+        match outcome {
+            Ok(outcome) => {
+                self.scheduler.record_generation(outcome.output_ids.len() as u64, outcome.elapsed_ms);
+                let tail = decoder.finish(&self.tokenizer).unwrap_or_default();
+                if !tail.is_empty() {
+                    sse.raw(&json!({
+                        "object": "chat.completion.chunk",
+                        "created": created,
+                        "model": self.model_name,
+                        "choices": [{ "index": 0, "delta": { "content": tail }, "finish_reason": Value::Null }],
+                    }))?;
+                }
+                sse.raw(&json!({
+                    "object": "chat.completion.chunk",
+                    "created": created,
+                    "model": self.model_name,
+                    "choices": [{ "index": 0, "delta": {}, "finish_reason": if outcome.eos_reached { "stop" } else { "length" } }],
+                }))?;
+                sse.done()
+            }
+            Err(e) => {
+                sse.raw(&json!({ "error": { "message": e } }))?;
+                sse.done()
+            }
+        }
+    }
+}
+
+fn synthetic_turn(user: String, output_ids: Vec<u32>) -> crate::store::StoredTurn {
+    crate::store::StoredTurn {
+        turn_id: String::new(),
+        conversation_id: String::new(),
+        parent_turn_id: None,
+        role_user_text: user,
+        user_block_text: None,
+        context_meta_json: None,
+        display_text: String::new(),
+        prompt_ids: Vec::new(),
+        output_ids,
+        stop_reason: None,
+        verification_status: TurnVerificationStatus::LocalComplete,
+        privacy_mode: TurnPrivacyMode::LocalOnly,
+        receipt_json: None,
+        runtime_roots_json: None,
+        search_bundle_json: None,
+        created_ms: 0,
+    }
+}
+
+/// Minimal SSE writer over tiny_http's raw stream (headers hand-rolled; tiny_http's typed
+/// Response cannot stream a body incrementally).
+///
+/// The body is CHUNKED (HTTP/1.1): tiny_http's `into_writer` hands us the socket but its drop
+/// does NOT close the connection — the library keeps it for the next keep-alive request. A
+/// bare-framed body therefore never signals its end and generic clients (curl, fetch,
+/// EventSource) hang waiting for EOF; the terminating zero-chunk is what tells them the
+/// response is over, and the connection stays legitimately reusable. (HTTP/1.0 clients are not
+/// supported on the streaming endpoints — every real consumer here speaks 1.1.)
+struct SseWriter<'a> {
+    writer: &'a mut dyn Write,
+}
+
+impl<'a> SseWriter<'a> {
+    fn new(writer: &'a mut dyn Write) -> Result<Self, String> {
+        write!(
+            writer,
+            "HTTP/1.1 200 OK\r\nContent-Type: text/event-stream\r\nCache-Control: no-cache\r\nTransfer-Encoding: chunked\r\n\r\n"
+        )
+        .map_err(|e| format!("sse headers: {e}"))?;
+        writer.flush().map_err(|e| e.to_string())?;
+        Ok(Self { writer })
+    }
+
+    fn chunk(&mut self, payload: &str) -> Result<(), String> {
+        write!(self.writer, "{:x}\r\n{payload}\r\n", payload.len()).map_err(|e| format!("sse write: {e}"))?;
+        self.writer.flush().map_err(|e| e.to_string())
+    }
+
+    fn event(&mut self, event: &GenerationEventV1) -> Result<(), String> {
+        let payload = serde_json::to_string(event).map_err(|e| e.to_string())?;
+        self.chunk(&format!("data: {payload}\n\n"))
+    }
+
+    fn raw(&mut self, value: &Value) -> Result<(), String> {
+        self.chunk(&format!("data: {value}\n\n"))
+    }
+
+    fn done(&mut self) -> Result<(), String> {
+        self.chunk("data: [DONE]\n\n")?;
+        // Terminating zero-chunk: end-of-response on the wire.
+        write!(self.writer, "0\r\n\r\n").map_err(|e| format!("sse write: {e}"))?;
+        self.writer.flush().map_err(|e| e.to_string())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn query_param_decodes() {
+        assert_eq!(query_param("/x?name=design.md", "name").as_deref(), Some("design.md"));
+        assert_eq!(query_param("/x?name=a%20b+c&z=1", "name").as_deref(), Some("a b c"));
+        assert_eq!(query_param("/x?a=1", "b"), None);
+        assert_eq!(query_param("/x", "a"), None);
+    }
+
+    #[test]
+    fn path_seg_extracts_single_segment() {
+        assert_eq!(path_seg("/v1/sessions/abc/messages", "/v1/sessions/", "/messages"), Some("abc"));
+        assert_eq!(path_seg("/v1/sessions//messages", "/v1/sessions/", "/messages"), None);
+        assert_eq!(path_seg("/v1/sessions/a/b/messages", "/v1/sessions/", "/messages"), None);
+        assert_eq!(path_seg("/v1/other/abc/messages", "/v1/sessions/", "/messages"), None);
+    }
+}

palw-gateway/src/lmstudio.rs

@@ -0,0 +1,393 @@
+//! LM Studio bridge: resolve a client-owned OpenAI transcript onto the session store.
+//!
+//! LM Studio's generator plugin owns the transcript and sends the WHOLE message list on every
+//! turn — it has no gateway session ids. This module maps that stateless shape onto the native
+//! id-stable session layer by CONTENT: the past `(user, assistant)` pairs are matched against
+//! stored turns, so a continued chat lands on its existing branch (and the prefix cache hits),
+//! an edited/regenerated message lands as a sibling branch of the turn it diverged from, and an
+//! unknown transcript becomes a new conversation with the foreign history imported.
+//!
+//! Matching is on NORMALIZED text: `<think>…</think>` blocks are stripped from assistant text
+//! before comparison, because the plugin re-sends history through LM Studio's own store, which
+//! may or may not retain reasoning blocks (the legacy server's recorded openings show they
+//! sometimes survive). The user side is compared verbatim (trimmed) — user text has no
+//! runtime-injected decoration.
+//!
+//! Import keeps the conversation usable but honest: imported turns carry no engine execution
+//! (`prompt_ids` empty, output ids re-encoded from text — exactly the id-instability the native
+//! path avoids from then on) and are marked `MintIneligible` with stop reason `imported`, so
+//! they can never enter the settlement pipeline.
+
+use crate::events::{TurnPrivacyMode, TurnVerificationStatus};
+use crate::store::{CompletedTurn, NewTurn, SessionStore, StoredTurn};
+use crate::tokenizer::TokenizerHost;
+
+/// One past exchange from the client transcript.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct MessagePair {
+    pub user: String,
+    /// Empty when the transcript had two user messages in a row (the earlier one is treated as
+    /// an exchange with an empty answer, mirroring `chat_completions`' fold).
+    pub assistant: String,
+}
+
+/// Fold an OpenAI `messages` array into `(past pairs, trailing user text)`.
+///
+/// Same rules as the stateless `chat_completions` fold: `system` entries are dropped (the
+/// system region is the gateway's), consecutive `user` messages become pairs with an empty
+/// answer, and the list must end in a user message.
+pub fn fold_messages(messages: &[serde_json::Value]) -> Result<(Vec<MessagePair>, String), String> {
+    let mut pairs = Vec::new();
+    let mut pending_user: Option<String> = None;
+    for m in messages {
+        let role = m.get("role").and_then(|r| r.as_str()).unwrap_or("");
+        let content = m.get("content").and_then(|c| c.as_str()).unwrap_or("").to_string();
+        match role {
+            "user" => {
+                if let Some(prev) = pending_user.take() {
+                    pairs.push(MessagePair { user: prev, assistant: String::new() });
+                }
+                pending_user = Some(content);
+            }
+            "assistant" => {
+                let user = pending_user.take().unwrap_or_default();
+                pairs.push(MessagePair { user, assistant: content });
+            }
+            _ => {}
+        }
+    }
+    match pending_user {
+        Some(user) => Ok((pairs, user)),
+        None => Err("no trailing user message".into()),
+    }
+}
+
+/// Normalization applied to BOTH sides before text comparison: strip `<think>…</think>` blocks
+/// (an unclosed `<think>` drops the rest of the string), collapse CRLF, trim.
+///
+/// This intentionally covers the plugin's `PALW status (receipt対象外)` blocks too — they use
+/// the same tag — so a transcript that still carries them matches the stored display text,
+/// which never contains them.
+pub fn normalize_for_match(text: &str) -> String {
+    const OPEN: &str = "<think>";
+    const CLOSE: &str = "</think>";
+    let mut out = String::with_capacity(text.len());
+    let mut rest = text;
+    loop {
+        match rest.find(OPEN) {
+            None => {
+                out.push_str(rest);
+                break;
+            }
+            Some(start) => {
+                out.push_str(&rest[..start]);
+                let after_open = &rest[start + OPEN.len()..];
+                match after_open.find(CLOSE) {
+                    None => break, // unclosed block: everything after the tag is runtime noise
+                    Some(end) => rest = &after_open[end + CLOSE.len()..],
+                }
+            }
+        }
+    }
+    out.replace("\r\n", "\n").trim().to_string()
+}
+
+fn pair_matches(turn: &StoredTurn, pair: &MessagePair) -> bool {
+    normalize_for_match(&turn.role_user_text) == normalize_for_match(&pair.user)
+        && normalize_for_match(&turn.display_text) == normalize_for_match(&pair.assistant)
+}
+
+/// How the transcript mapped onto the store.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ResolutionKind {
+    /// Every past pair matched the active branch's prefix — plain continuation.
+    Continued,
+    /// A prefix matched, then the transcript diverged (edit/regenerate in LM Studio) — the new
+    /// turn becomes a sibling branch under the last matching turn.
+    Branched,
+    /// Nothing matched and the transcript had no past pairs — a fresh conversation.
+    NewConversation,
+    /// Nothing matched but the transcript HAD past pairs — a fresh conversation with the
+    /// foreign history imported as mint-ineligible turns.
+    Imported,
+}
+
+impl ResolutionKind {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Continued => "continued",
+            Self::Branched => "branched",
+            Self::NewConversation => "new_conversation",
+            Self::Imported => "imported",
+        }
+    }
+}
+
+/// Where the new turn should attach.
+#[derive(Debug)]
+pub struct ResolutionPlan {
+    pub kind: ResolutionKind,
+    /// Existing conversation to attach to (`None` ⇒ create one, importing `pairs` when
+    /// `kind == Imported`).
+    pub conversation_id: Option<String>,
+    /// Turn the new message continues from (`None` ⇒ the new turn is a root).
+    pub parent_turn_id: Option<String>,
+    /// How many leading pairs matched stored turns.
+    pub matched_pairs: usize,
+}
+
+/// Match the transcript's past pairs against stored turns.
+///
+/// Candidates are root turns whose first exchange matches `pairs[0]`; each candidate is walked
+/// down by matching children pair-by-pair (first match in creation order — deterministic under
+/// duplicate regenerations). The deepest match wins; ties go to the oldest root. This is a
+/// content walk over one branch path per candidate, not a search of the whole tree.
+pub fn resolve(store: &SessionStore, pairs: &[MessagePair]) -> Result<ResolutionPlan, String> {
+    if pairs.is_empty() {
+        return Ok(ResolutionPlan {
+            kind: ResolutionKind::NewConversation,
+            conversation_id: None,
+            parent_turn_id: None,
+            matched_pairs: 0,
+        });
+    }
+    let mut best: Option<(usize, StoredTurn)> = None; // (matched pair count, last matched turn)
+    for root in store.root_turns()? {
+        if !pair_matches(&root, &pairs[0]) {
+            continue;
+        }
+        let mut last = root;
+        let mut matched = 1usize;
+        while matched < pairs.len() {
+            let next = store
+                .children_of(&last.turn_id)?
+                .into_iter()
+                .find(|child| pair_matches(child, &pairs[matched]));
+            match next {
+                Some(child) => {
+                    last = child;
+                    matched += 1;
+                }
+                None => break,
+            }
+        }
+        let deeper = best.as_ref().map(|(n, _)| matched > *n).unwrap_or(true);
+        if deeper {
+            let full = matched == pairs.len();
+            best = Some((matched, last));
+            if full {
+                break; // oldest fully-matching root wins; no deeper match exists
+            }
+        }
+    }
+    Ok(match best {
+        Some((matched, last)) => ResolutionPlan {
+            kind: if matched == pairs.len() { ResolutionKind::Continued } else { ResolutionKind::Branched },
+            conversation_id: Some(last.conversation_id.clone()),
+            parent_turn_id: Some(last.turn_id),
+            matched_pairs: matched,
+        },
+        None => ResolutionPlan {
+            kind: ResolutionKind::Imported,
+            conversation_id: None,
+            parent_turn_id: None,
+            matched_pairs: 0,
+        },
+    })
+}
+
+/// Import foreign past pairs as stored turns under `conversation_id`, returning the leaf id.
+///
+/// Imported turns are honest about their provenance: no engine execution happened here, so
+/// `prompt_ids` stays empty, `output_ids` is re-encoded from the normalized assistant TEXT (the
+/// one unavoidable id-unstable step — every turn after this one is id-stable again), the status
+/// is `MintIneligible` and the stop reason is `imported`. Display keeps the original text.
+pub fn import_pairs(
+    store: &mut SessionStore,
+    tokenizer: &TokenizerHost,
+    conversation_id: &str,
+    pairs: &[MessagePair],
+    mut fresh_turn_id: impl FnMut() -> String,
+    now_ms: i64,
+) -> Result<Option<String>, String> {
+    let mut parent: Option<String> = None;
+    for pair in pairs {
+        let turn_id = fresh_turn_id();
+        store.begin_turn(&NewTurn {
+            turn_id: &turn_id,
+            conversation_id,
+            parent_turn_id: parent.as_deref(),
+            role_user_text: &pair.user,
+            user_block_text: &pair.user,
+            context_meta_json: None,
+            prompt_ids: &[],
+            privacy_mode: TurnPrivacyMode::LocalOnly,
+            search_bundle_json: None,
+            now_ms,
+        })?;
+        let clean = normalize_for_match(&pair.assistant);
+        let output_ids = if clean.is_empty() { Vec::new() } else { tokenizer.encode_lossless(&clean)? };
+        store.complete_turn(&CompletedTurn {
+            turn_id: &turn_id,
+            output_ids: &output_ids,
+            display_text: &pair.assistant,
+            stop_reason: "imported",
+            status: TurnVerificationStatus::MintIneligible,
+            receipt_json: None,
+            runtime_roots_json: None,
+        })?;
+        parent = Some(turn_id);
+    }
+    Ok(parent)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn fold_matches_chat_completions_rules() {
+        let messages = vec![
+            json!({"role": "system", "content": "dropped"}),
+            json!({"role": "user", "content": "a"}),
+            json!({"role": "assistant", "content": "b"}),
+            json!({"role": "user", "content": "c"}),
+            json!({"role": "user", "content": "d"}),
+        ];
+        let (pairs, trailing) = fold_messages(&messages).unwrap();
+        assert_eq!(
+            pairs,
+            vec![
+                MessagePair { user: "a".into(), assistant: "b".into() },
+                MessagePair { user: "c".into(), assistant: String::new() },
+            ]
+        );
+        assert_eq!(trailing, "d");
+        assert!(fold_messages(&[json!({"role": "user", "content": "x"}), json!({"role": "assistant", "content": "y"})]).is_err());
+    }
+
+    #[test]
+    fn normalization_strips_think_and_status_blocks() {
+        assert_eq!(normalize_for_match("  answer  "), "answer");
+        assert_eq!(normalize_for_match("<think>reasoning</think>\nanswer"), "answer");
+        assert_eq!(
+            normalize_for_match("<think>PALW status (receipt対象外):\nengine ready\n</think>\n<think>plan</think>body"),
+            "body"
+        );
+        // Unclosed block: everything after the tag is runtime noise, not answer text.
+        assert_eq!(normalize_for_match("head<think>never closed"), "head");
+        assert_eq!(normalize_for_match("a\r\nb"), "a\nb");
+    }
+
+    fn open_store() -> SessionStore {
+        let dir = std::env::temp_dir().join(format!("palw-lmstudio-test-{}-{}", std::process::id(), fastrand()));
+        std::fs::create_dir_all(&dir).unwrap();
+        SessionStore::open(&dir.join("s.sqlite3")).unwrap()
+    }
+
+    fn fastrand() -> u64 {
+        use std::time::{SystemTime, UNIX_EPOCH};
+        static C: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
+        SystemTime::now().duration_since(UNIX_EPOCH).unwrap().subsec_nanos() as u64
+            + C.fetch_add(1, std::sync::atomic::Ordering::Relaxed)
+    }
+
+    fn seed_turn(
+        store: &mut SessionStore,
+        conversation: &str,
+        turn_id: &str,
+        parent: Option<&str>,
+        user: &str,
+        assistant: &str,
+    ) {
+        store
+            .begin_turn(&NewTurn {
+                turn_id,
+                conversation_id: conversation,
+                parent_turn_id: parent,
+                role_user_text: user,
+                user_block_text: user,
+                context_meta_json: None,
+                prompt_ids: &[1, 2, 3],
+                privacy_mode: TurnPrivacyMode::PalwMint,
+                search_bundle_json: None,
+                now_ms: 1,
+            })
+            .unwrap();
+        store
+            .complete_turn(&CompletedTurn {
+                turn_id,
+                output_ids: &[7, 8],
+                display_text: assistant,
+                stop_reason: "eos",
+                status: TurnVerificationStatus::LocalComplete,
+                receipt_json: None,
+                runtime_roots_json: None,
+            })
+            .unwrap();
+    }
+
+    #[test]
+    fn resolve_continues_branches_and_imports() {
+        let mut store = open_store();
+        store.create_conversation("conv1", "t", None, 1).unwrap();
+        seed_turn(&mut store, "conv1", "turn1", None, "hello", "<think>x</think>world");
+        seed_turn(&mut store, "conv1", "turn2", Some("turn1"), "next", "answer2");
+
+        // Continuation: both pairs match (client transcript lost the think block — still matches).
+        let pairs = vec![
+            MessagePair { user: "hello".into(), assistant: "world".into() },
+            MessagePair { user: "next".into(), assistant: "answer2".into() },
+        ];
+        let plan = resolve(&store, &pairs).unwrap();
+        assert_eq!(plan.kind, ResolutionKind::Continued);
+        assert_eq!(plan.conversation_id.as_deref(), Some("conv1"));
+        assert_eq!(plan.parent_turn_id.as_deref(), Some("turn2"));
+
+        // Edit of message 2 in LM Studio: first pair matches, second diverges → branch under turn1.
+        let pairs = vec![
+            MessagePair { user: "hello".into(), assistant: "world".into() },
+            MessagePair { user: "next".into(), assistant: "different answer".into() },
+        ];
+        let plan = resolve(&store, &pairs).unwrap();
+        assert_eq!(plan.kind, ResolutionKind::Branched);
+        assert_eq!(plan.parent_turn_id.as_deref(), Some("turn1"));
+        assert_eq!(plan.matched_pairs, 1);
+
+        // Regenerate (same user, no assistant yet): parent is the turn BEFORE the regenerated one.
+        let pairs = vec![MessagePair { user: "hello".into(), assistant: "world".into() }];
+        let plan = resolve(&store, &pairs).unwrap();
+        assert_eq!(plan.kind, ResolutionKind::Continued);
+        assert_eq!(plan.parent_turn_id.as_deref(), Some("turn1"));
+
+        // Unknown transcript with history → import; empty history → new conversation.
+        let pairs = vec![MessagePair { user: "elsewhere".into(), assistant: "said".into() }];
+        assert_eq!(resolve(&store, &pairs).unwrap().kind, ResolutionKind::Imported);
+        assert_eq!(resolve(&store, &[]).unwrap().kind, ResolutionKind::NewConversation);
+    }
+
+    #[test]
+    fn resolve_prefers_deepest_match_across_duplicate_roots() {
+        let mut store = open_store();
+        store.create_conversation("convA", "a", None, 1).unwrap();
+        store.create_conversation("convB", "b", None, 1).unwrap();
+        // Two conversations with the same first exchange; only convB has the second one.
+        seed_turn(&mut store, "convA", "a1", None, "hi", "yo");
+        seed_turn(&mut store, "convB", "b1", None, "hi", "yo");
+        seed_turn(&mut store, "convB", "b2", Some("b1"), "more", "deep");
+        let pairs = vec![
+            MessagePair { user: "hi".into(), assistant: "yo".into() },
+            MessagePair { user: "more".into(), assistant: "deep".into() },
+        ];
+        let plan = resolve(&store, &pairs).unwrap();
+        assert_eq!(plan.conversation_id.as_deref(), Some("convB"));
+        assert_eq!(plan.parent_turn_id.as_deref(), Some("b2"));
+        assert_eq!(plan.kind, ResolutionKind::Continued);
+        // The shallower duplicate root still wins when the transcript stops at pair 1
+        // (oldest root, deterministic).
+        let pairs = vec![MessagePair { user: "hi".into(), assistant: "yo".into() }];
+        let plan = resolve(&store, &pairs).unwrap();
+        assert_eq!(plan.conversation_id.as_deref(), Some("convA"));
+    }
+}

palw-gateway/src/main.rs

@@ -0,0 +1,322 @@
+//! palw-gateway — PALW Desktop UX Phase 0+1: the resident streaming inference gateway, the
+//! Conversation Session Layer, and the Phase-1 product layers from the frozen design doc
+//! (`docs/palw-desktop-product-architecture.md`).
+//!
+//! Phase 0 (shipped first): resident engine host, token streaming, id-stable turn/branch store —
+//! reuse the forward pass, replace the serving shell.
+//!
+//! Phase 1 (this build): Context Compiler v1 (project instructions §10 + memory snapshot §12 +
+//! attachment chunk selection §11 in the system/user regions), content-addressed artifact store
+//! with version chains (§8/§9), the three-mode tool runtime with sandbox and exactly-once
+//! side-effect approval (§6/§17), the five-priority resource scheduler with SLA admission (§14),
+//! and the settlement-clock writer (legal transitions, mismatch cascade, certified head — §4)
+//! that UX Phase 2's background supervisor will drive.
+
+mod artifact;
+mod context;
+mod coordinator;
+mod engine;
+mod events;
+mod http;
+mod lmstudio;
+mod scheduler;
+mod store;
+mod tokenizer;
+mod tools;
+mod worker;
+
+use std::path::PathBuf;
+use std::sync::{Arc, Mutex};
+
+use crate::artifact::ArtifactBlobStore;
+use crate::context::ContextCompiler;
+use crate::coordinator::{HttpCoordinator, LoopbackConfig, LoopbackCoordinator, PalwCoordinator};
+use crate::engine::{EngineConfig, EngineHost};
+use crate::http::Gateway;
+use crate::scheduler::ResourceScheduler;
+use crate::store::SessionStore;
+use crate::tokenizer::TokenizerHost;
+use crate::tools::{ToolRuntime, ToolSandboxPolicyV1};
+use crate::worker::{EngineReplicaExecutor, WorkerConfig, WorkerStatus};
+
+const DEFAULT_SYSTEM_PROMPT: &str = "You are a helpful assistant.";
+pub(crate) const QWEN_EOS_ID: u32 = 248046; // <|im_end|> — the qi35_chat.py pin.
+
+struct Args {
+    listen: String,
+    engine_binary: PathBuf,
+    gguf: PathBuf,
+    tables: PathBuf,
+    tokenizer_json: PathBuf,
+    db: PathBuf,
+    threads: u32,
+    max_new: u32,
+    max_context: usize,
+    metal_v3: bool,
+    system_prompt: String,
+    auth_token: String,
+    audit_key_file: Option<PathBuf>,
+    receipt_dir: Option<PathBuf>,
+    search_cmd: Option<PathBuf>,
+    // Phase 1
+    artifacts_dir: PathBuf,
+    workspace: PathBuf,
+    readable: Vec<PathBuf>,
+    allow_commands: Vec<PathBuf>,
+    tool_timeout_ms: u64,
+    max_file_chars: usize,
+    max_tool_chars: usize,
+    // Phase 2
+    palw_loopback: bool,
+    palw_coordinator: Option<String>,
+    palw_coordinator_token: Option<String>,
+    palw_provider: String,
+    palw_poll_ms: u64,
+    palw_no_self_replica: bool,
+}
+
+fn parse_args() -> Result<Args, String> {
+    let mut args = Args {
+        listen: "127.0.0.1:12346".into(),
+        engine_binary: PathBuf::from("docs/evidence/qi35_model"),
+        gguf: PathBuf::new(),
+        tables: PathBuf::new(),
+        tokenizer_json: PathBuf::new(),
+        db: PathBuf::from("palw-gateway-sessions.sqlite3"),
+        threads: 8,
+        max_new: 1024,
+        max_context: 8192,
+        metal_v3: true,
+        system_prompt: DEFAULT_SYSTEM_PROMPT.into(),
+        auth_token: std::env::var("PALW_GATEWAY_TOKEN").unwrap_or_default(),
+        audit_key_file: None,
+        receipt_dir: None,
+        search_cmd: None,
+        artifacts_dir: PathBuf::from("palw-artifacts"),
+        workspace: PathBuf::from("palw-workspace"),
+        readable: Vec::new(),
+        allow_commands: Vec::new(),
+        tool_timeout_ms: 30_000,
+        max_file_chars: 6_000,
+        max_tool_chars: 6_000,
+        palw_loopback: false,
+        palw_coordinator: None,
+        palw_coordinator_token: None,
+        palw_provider: "local-dev".into(),
+        palw_poll_ms: 2_000,
+        palw_no_self_replica: false,
+    };
+    let argv: Vec<String> = std::env::args().collect();
+    let mut i = 1;
+    while i < argv.len() {
+        let take = |i: &mut usize| -> Result<String, String> {
+            *i += 1;
+            argv.get(*i).cloned().ok_or_else(|| format!("{} needs a value", argv[*i - 1]))
+        };
+        match argv[i].as_str() {
+            "--listen" => args.listen = take(&mut i)?,
+            "--engine" => args.engine_binary = PathBuf::from(take(&mut i)?),
+            "--gguf" => args.gguf = PathBuf::from(take(&mut i)?),
+            "--tables" => args.tables = PathBuf::from(take(&mut i)?),
+            "--tokenizer" => args.tokenizer_json = PathBuf::from(take(&mut i)?),
+            "--db" => args.db = PathBuf::from(take(&mut i)?),
+            "--threads" => args.threads = take(&mut i)?.parse().map_err(|e| format!("--threads: {e}"))?,
+            "--max-new" => args.max_new = take(&mut i)?.parse().map_err(|e| format!("--max-new: {e}"))?,
+            "--max-context" => args.max_context = take(&mut i)?.parse().map_err(|e| format!("--max-context: {e}"))?,
+            "--no-metal" => args.metal_v3 = false,
+            "--system-prompt" => args.system_prompt = take(&mut i)?,
+            "--auth-token" => args.auth_token = take(&mut i)?,
+            "--audit-key-file" => args.audit_key_file = Some(PathBuf::from(take(&mut i)?)),
+            "--receipt-dir" => args.receipt_dir = Some(PathBuf::from(take(&mut i)?)),
+            "--search-cmd" => args.search_cmd = Some(PathBuf::from(take(&mut i)?)),
+            "--artifacts-dir" => args.artifacts_dir = PathBuf::from(take(&mut i)?),
+            "--workspace" => args.workspace = PathBuf::from(take(&mut i)?),
+            "--readable" => args.readable.push(PathBuf::from(take(&mut i)?)),
+            "--allow-command" => args.allow_commands.push(PathBuf::from(take(&mut i)?)),
+            "--tool-timeout-ms" => {
+                args.tool_timeout_ms = take(&mut i)?.parse().map_err(|e| format!("--tool-timeout-ms: {e}"))?
+            }
+            "--max-file-chars" => {
+                args.max_file_chars = take(&mut i)?.parse().map_err(|e| format!("--max-file-chars: {e}"))?
+            }
+            "--max-tool-chars" => {
+                args.max_tool_chars = take(&mut i)?.parse().map_err(|e| format!("--max-tool-chars: {e}"))?
+            }
+            "--palw-loopback" => args.palw_loopback = true,
+            "--palw-coordinator" => args.palw_coordinator = Some(take(&mut i)?),
+            "--palw-coordinator-token" => args.palw_coordinator_token = Some(take(&mut i)?),
+            "--palw-provider" => args.palw_provider = take(&mut i)?,
+            "--palw-poll-ms" => {
+                args.palw_poll_ms = take(&mut i)?.parse().map_err(|e| format!("--palw-poll-ms: {e}"))?
+            }
+            "--palw-no-self-replica" => args.palw_no_self_replica = true,
+            other => return Err(format!("unknown flag {other}")),
+        }
+        i += 1;
+    }
+    if args.gguf.as_os_str().is_empty() || args.tables.as_os_str().is_empty() || args.tokenizer_json.as_os_str().is_empty() {
+        return Err("required: --gguf <path> --tables <path> --tokenizer <tokenizer.json>".into());
+    }
+    Ok(args)
+}
+
+fn main() {
+    let args = match parse_args() {
+        Ok(a) => a,
+        Err(e) => {
+            eprintln!("palw-gateway: {e}");
+            eprintln!(
+                "usage: palw-gateway --gguf <gguf> --tables <tables> --tokenizer <tokenizer.json> \
+                 [--engine <qi35_model>] [--listen 127.0.0.1:12346] [--db <sqlite>] [--threads N] \
+                 [--max-new N] [--max-context N] [--no-metal] [--system-prompt S] [--auth-token T] \
+                 [--audit-key-file <key>] [--receipt-dir <dir>] [--search-cmd <program>] \
+                 [--artifacts-dir <dir>] [--workspace <dir>] \
+                 [--readable <dir>]... [--allow-command </abs/path>]... [--tool-timeout-ms N] \
+                 [--max-file-chars N] [--max-tool-chars N] \
+                 [--palw-loopback] [--palw-coordinator http://host:port/v1/palw/loopback] \
+                 [--palw-coordinator-token T] [--palw-provider ID] [--palw-poll-ms N] \
+                 [--palw-no-self-replica]"
+            );
+            std::process::exit(2);
+        }
+    };
+
+    // Absolutize engine-facing paths: the engine child runs from ITS OWN directory (Metal dylib
+    // resolution), so relative gguf/tables paths would break.
+    let mut args = args;
+    for path in [&mut args.engine_binary, &mut args.gguf, &mut args.tables] {
+        if let Ok(canonical) = std::fs::canonicalize(&path) {
+            *path = canonical;
+        }
+    }
+
+    let tokenizer = match TokenizerHost::load(&args.tokenizer_json, QWEN_EOS_ID) {
+        Ok(t) => t,
+        Err(e) => {
+            eprintln!("palw-gateway: {e}");
+            std::process::exit(1);
+        }
+    };
+    eprintln!("[palw-gateway] tokenizer blake2b-256 {}", tokenizer.digest_hex);
+
+    let compiler = match ContextCompiler::new(
+        &tokenizer,
+        &args.system_prompt,
+        args.max_context,
+        args.max_new as usize,
+        args.max_file_chars,
+        args.max_tool_chars,
+    ) {
+        Ok(c) => c,
+        Err(e) => {
+            eprintln!("palw-gateway: context compiler: {e}");
+            std::process::exit(1);
+        }
+    };
+
+    let store = match SessionStore::open(&args.db) {
+        Ok(s) => s,
+        Err(e) => {
+            eprintln!("palw-gateway: session store: {e}");
+            std::process::exit(1);
+        }
+    };
+
+    let blobs = match ArtifactBlobStore::open(&args.artifacts_dir) {
+        Ok(b) => b,
+        Err(e) => {
+            eprintln!("palw-gateway: artifact store: {e}");
+            std::process::exit(1);
+        }
+    };
+
+    // Tool output cap 256 KiB, read cap 8 MiB — generous for logs/source, far below anything
+    // that could balloon the context compiler (which additionally clips per file/tool).
+    let sandbox = match ToolSandboxPolicyV1::new(
+        &args.workspace,
+        &args.readable,
+        &args.allow_commands,
+        args.tool_timeout_ms,
+        256 * 1024,
+        8 * 1024 * 1024,
+    ) {
+        Ok(p) => p,
+        Err(e) => {
+            eprintln!("palw-gateway: tool sandbox: {e}");
+            std::process::exit(1);
+        }
+    };
+    eprintln!(
+        "[palw-gateway] workspace {} | {} readable root(s) | {} allowlisted command(s)",
+        sandbox.workspace_root.display(),
+        sandbox.readable_roots.len(),
+        sandbox.allowed_commands.len()
+    );
+
+    let engine = Arc::new(Mutex::new(EngineHost::new(EngineConfig {
+        binary: args.engine_binary,
+        gguf: args.gguf,
+        tables: args.tables,
+        threads: args.threads,
+        max_new: args.max_new,
+        eos_id: QWEN_EOS_ID,
+        metal_v3: args.metal_v3,
+        audit_key_file: args.audit_key_file,
+        network_label: "MISAKA-Qwen-PALW-v1".into(),
+    })));
+    let store = Arc::new(Mutex::new(store));
+    let scheduler = Arc::new(ResourceScheduler::new());
+
+    // Phase 2: the loopback coordinator (served for other instances and/or used in-process)
+    // and the background worker. --palw-coordinator (a remote coordinator) takes precedence as
+    // the WORKER's counterparty; --palw-loopback additionally serves the protocol here.
+    let loopback = args.palw_loopback.then(|| {
+        Arc::new(LoopbackCoordinator::new(LoopbackConfig {
+            allow_self_replica: !args.palw_no_self_replica,
+            ..Default::default()
+        }))
+    });
+    let worker_coordinator: Option<Arc<dyn PalwCoordinator>> = match (&args.palw_coordinator, &loopback) {
+        (Some(url), _) => {
+            Some(Arc::new(HttpCoordinator::new(url, args.palw_coordinator_token.clone())) as Arc<dyn PalwCoordinator>)
+        }
+        (None, Some(l)) => Some(Arc::clone(l) as Arc<dyn PalwCoordinator>),
+        (None, None) => None,
+    };
+    let palw_status = worker_coordinator.as_ref().map(|_| Arc::new(WorkerStatus::default()));
+
+    let gateway = Arc::new(Gateway {
+        engine: Arc::clone(&engine),
+        store: Arc::clone(&store),
+        tokenizer,
+        compiler,
+        blobs,
+        tools: ToolRuntime::new(sandbox),
+        scheduler: Arc::clone(&scheduler),
+        cancels: Mutex::new(Default::default()),
+        model_name: "misaka-qi35".into(),
+        auth_token: args.auth_token,
+        receipt_dir: args.receipt_dir,
+        search_cmd: args.search_cmd,
+        palw_loopback: loopback,
+        palw_status: palw_status.clone(),
+        palw_provider: worker_coordinator.as_ref().map(|_| args.palw_provider.clone()),
+    });
+
+    let _worker = match (worker_coordinator, palw_status) {
+        (Some(coordinator), Some(status)) => Some(worker::spawn(
+            store,
+            Arc::clone(&scheduler),
+            coordinator,
+            Arc::new(EngineReplicaExecutor { engine, scheduler }),
+            WorkerConfig { provider_id: args.palw_provider, poll_ms: args.palw_poll_ms, max_new: args.max_new },
+            status,
+        )),
+        _ => None,
+    };
+
+    if let Err(e) = gateway.serve(&args.listen) {
+        eprintln!("palw-gateway: {e}");
+        std::process::exit(1);
+    }
+}

palw-gateway/src/scheduler.rs

@@ -0,0 +1,311 @@
+//! Local Resource Scheduler (design doc §14).
+//!
+//! One GPU, several masters: the user's own chat, background agents, other people's replica
+//! jobs, auditor replays, maintenance. Phase 0 serialized engine access with a bare Mutex —
+//! correct, but priority-blind. This module puts the doc's five-priority queue IN FRONT of the
+//! engine: a foreground turn that arrives while a maintenance job is queued gets the next slot,
+//! period.
+//!
+//! Two deliberate v1 properties, stated honestly:
+//! * **No mid-generation preemption.** The engine has no stop channel (survey fact), so a
+//!   running job finishes; priority decides who goes NEXT. The worst-case foreground delay is
+//!   one background generation (bounded by `--max-new`).
+//! * **Admission before acceptance** (the doc's no-show rule): `try_admit` answers "could this
+//!   job finish inside its SLA given the measured decode rate and the current queue?" BEFORE the
+//!   job is accepted. Refusing an assignment up front is healthier than taking it and
+//!   no-showing — the caller (Phase-2 replica worker) is expected to decline the assignment when
+//!   admission fails.
+//!
+//! The decode-rate estimate is a local EMA of observed generations (integer milli-tokens/sec —
+//! telemetry, not consensus; nothing here is committed anywhere).
+
+use std::sync::{Condvar, Mutex};
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum JobClass {
+    /// Priority 1: the chat the user is looking at right now.
+    ForegroundChat,
+    /// Priority 2: agents the user started.
+    BackgroundAgent,
+    /// Priority 3: replica jobs with deadlines (Phase 2).
+    ReplicaJob,
+    /// Priority 4: auditor replays (Phase 2).
+    AuditorReplay,
+    /// Priority 5: conformance / indexing / artifact maintenance.
+    Maintenance,
+}
+
+impl JobClass {
+    pub const ALL: [JobClass; 5] =
+        [Self::ForegroundChat, Self::BackgroundAgent, Self::ReplicaJob, Self::AuditorReplay, Self::Maintenance];
+
+    fn priority(self) -> u8 {
+        match self {
+            Self::ForegroundChat => 1,
+            Self::BackgroundAgent => 2,
+            Self::ReplicaJob => 3,
+            Self::AuditorReplay => 4,
+            Self::Maintenance => 5,
+        }
+    }
+
+    pub fn index(self) -> usize {
+        self.priority() as usize - 1
+    }
+
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::ForegroundChat => "foreground_chat",
+            Self::BackgroundAgent => "background_agent",
+            Self::ReplicaJob => "replica_job",
+            Self::AuditorReplay => "auditor_replay",
+            Self::Maintenance => "maintenance",
+        }
+    }
+
+    pub fn from_str(s: &str) -> Option<Self> {
+        Self::ALL.into_iter().find(|c| c.as_str() == s)
+    }
+}
+
+/// Conservative floor used until real generations teach the EMA — QI35 measures ~17 tok/s on
+/// the M-series reference box; assuming 8 keeps early admission promises safe, not flattering.
+const DEFAULT_MILLITOK_PER_SEC: u64 = 8_000;
+/// EMA weight: new sample 1/8 — smooth enough to ignore one weird turn, fresh enough to track
+/// thermal throttling within a few generations.
+const EMA_SHIFT: u32 = 3;
+
+struct SchedState {
+    busy: bool,
+    next_ticket: u64,
+    /// (priority, ticket) — the waiting set; the minimum is granted next (priority first, FIFO
+    /// inside a class via the monotone ticket).
+    waiting: Vec<(u8, u64)>,
+    waiting_by_class: [u32; 5],
+    ema_millitok_per_sec: u64,
+    completed_jobs: u64,
+}
+
+pub struct ResourceScheduler {
+    state: Mutex<SchedState>,
+    granted: Condvar,
+    /// Queue-depth caps per class (index by `JobClass::index`); 0 = unbounded (foreground).
+    queue_caps: [u32; 5],
+}
+
+/// RAII grant: hold it while talking to the engine; drop releases the slot to the best waiter.
+pub struct EngineLease<'a> {
+    scheduler: &'a ResourceScheduler,
+}
+
+impl Drop for EngineLease<'_> {
+    fn drop(&mut self) {
+        let mut s = self.scheduler.state.lock().unwrap();
+        s.busy = false;
+        drop(s);
+        self.scheduler.granted.notify_all();
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct SchedulerStatus {
+    pub busy: bool,
+    pub waiting_by_class: [u32; 5],
+    pub ema_millitok_per_sec: u64,
+    pub completed_jobs: u64,
+}
+
+impl ResourceScheduler {
+    pub fn new() -> Self {
+        Self {
+            state: Mutex::new(SchedState {
+                busy: false,
+                next_ticket: 0,
+                waiting: Vec::new(),
+                waiting_by_class: [0; 5],
+                ema_millitok_per_sec: DEFAULT_MILLITOK_PER_SEC,
+                completed_jobs: 0,
+            }),
+            granted: Condvar::new(),
+            // Foreground unbounded; modest bounded queues elsewhere — a deep background queue
+            // is exactly the "GPU busy for hours after the user left" failure §14 warns about.
+            queue_caps: [0, 4, 4, 4, 2],
+        }
+    }
+
+    /// Block until this job may use the engine. Grants strictly by (priority, arrival) order.
+    pub fn acquire(&self, class: JobClass) -> EngineLease<'_> {
+        let mut s = self.state.lock().unwrap();
+        let ticket = s.next_ticket;
+        s.next_ticket += 1;
+        let me = (class.priority(), ticket);
+        s.waiting.push(me);
+        s.waiting_by_class[class.index()] += 1;
+        loop {
+            let best = s.waiting.iter().copied().min().expect("self is waiting");
+            if !s.busy && best == me {
+                s.waiting.retain(|&w| w != me);
+                s.waiting_by_class[class.index()] -= 1;
+                s.busy = true;
+                return EngineLease { scheduler: self };
+            }
+            s = self.granted.wait(s).unwrap();
+        }
+    }
+
+    /// SLA admission (§14): would a job of `estimated_output_tokens` finish within
+    /// `deadline_ms`, given the measured decode rate and everything already ahead of it?
+    /// Foreground is always admitted (the user is waiting; refusing them helps nobody).
+    pub fn try_admit(&self, class: JobClass, estimated_output_tokens: u64, deadline_ms: u64) -> Result<(), String> {
+        if class == JobClass::ForegroundChat {
+            return Ok(());
+        }
+        let s = self.state.lock().unwrap();
+        let cap = self.queue_caps[class.index()];
+        if cap != 0 && s.waiting_by_class[class.index()] >= cap {
+            return Err(format!("{} queue is full ({cap})", class.as_str()));
+        }
+        // Own runtime at the measured rate, then scale by how many jobs sit in front (each may
+        // be a full generation) — a coarse but SAFE overestimate; refusing borderline work is
+        // the design's stated preference over no-shows.
+        let rate = s.ema_millitok_per_sec.max(1);
+        let own_ms = estimated_output_tokens.saturating_mul(1_000_000) / rate;
+        let ahead = s.waiting.len() as u64 + u64::from(s.busy);
+        let projected_ms = own_ms.saturating_mul(ahead + 1);
+        if projected_ms > deadline_ms {
+            return Err(format!(
+                "projected {projected_ms}ms (rate {}mtok/s, {ahead} ahead) exceeds the {deadline_ms}ms deadline",
+                rate
+            ));
+        }
+        Ok(())
+    }
+
+    /// Feed the decode-rate EMA from a finished generation.
+    pub fn record_generation(&self, output_tokens: u64, elapsed_ms: u64) {
+        if output_tokens == 0 || elapsed_ms == 0 {
+            return;
+        }
+        let sample = output_tokens.saturating_mul(1_000_000) / elapsed_ms;
+        let mut s = self.state.lock().unwrap();
+        let ema = s.ema_millitok_per_sec;
+        s.ema_millitok_per_sec = ema - (ema >> EMA_SHIFT) + (sample >> EMA_SHIFT);
+        s.completed_jobs += 1;
+    }
+
+    pub fn status(&self) -> SchedulerStatus {
+        let s = self.state.lock().unwrap();
+        SchedulerStatus {
+            busy: s.busy,
+            waiting_by_class: s.waiting_by_class,
+            ema_millitok_per_sec: s.ema_millitok_per_sec,
+            completed_jobs: s.completed_jobs,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::Arc;
+    use std::sync::mpsc;
+    use std::time::{Duration, Instant};
+
+    fn wait_until(pred: impl Fn() -> bool) {
+        let deadline = Instant::now() + Duration::from_secs(5);
+        while !pred() {
+            assert!(Instant::now() < deadline, "condition not reached in 5s");
+            std::thread::sleep(Duration::from_millis(5));
+        }
+    }
+
+    #[test]
+    fn foreground_overtakes_earlier_background() {
+        let sched = Arc::new(ResourceScheduler::new());
+        let held = sched.acquire(JobClass::Maintenance);
+
+        let (tx, rx) = mpsc::channel::<&'static str>();
+        let s2 = Arc::clone(&sched);
+        let tx2 = tx.clone();
+        let h_maint = std::thread::spawn(move || {
+            let lease = s2.acquire(JobClass::Maintenance);
+            tx2.send("maintenance").unwrap();
+            drop(lease);
+        });
+        wait_until(|| sched.status().waiting_by_class[JobClass::Maintenance.index()] == 1);
+
+        let s3 = Arc::clone(&sched);
+        let h_fg = std::thread::spawn(move || {
+            let lease = s3.acquire(JobClass::ForegroundChat);
+            tx.send("foreground").unwrap();
+            drop(lease);
+        });
+        wait_until(|| sched.status().waiting_by_class[JobClass::ForegroundChat.index()] == 1);
+
+        drop(held);
+        // The maintenance job queued FIRST, but the foreground turn is granted first.
+        assert_eq!(rx.recv_timeout(Duration::from_secs(5)).unwrap(), "foreground");
+        assert_eq!(rx.recv_timeout(Duration::from_secs(5)).unwrap(), "maintenance");
+        h_maint.join().unwrap();
+        h_fg.join().unwrap();
+    }
+
+    #[test]
+    fn fifo_within_a_class() {
+        let sched = Arc::new(ResourceScheduler::new());
+        let held = sched.acquire(JobClass::ForegroundChat);
+        let (tx, rx) = mpsc::channel::<u32>();
+        let mut handles = Vec::new();
+        for i in 0..3u32 {
+            let s = Arc::clone(&sched);
+            let tx = tx.clone();
+            handles.push(std::thread::spawn(move || {
+                let lease = s.acquire(JobClass::BackgroundAgent);
+                tx.send(i).unwrap();
+                drop(lease);
+            }));
+            // Serialize arrival so tickets are ordered 0,1,2.
+            wait_until(|| s_waiting(&sched) == i + 1);
+        }
+        drop(held);
+        let order: Vec<u32> = (0..3).map(|_| rx.recv_timeout(Duration::from_secs(5)).unwrap()).collect();
+        assert_eq!(order, vec![0, 1, 2]);
+        for h in handles {
+            h.join().unwrap();
+        }
+
+        fn s_waiting(s: &ResourceScheduler) -> u32 {
+            s.status().waiting_by_class[JobClass::BackgroundAgent.index()]
+        }
+    }
+
+    #[test]
+    fn admission_enforces_deadline_and_caps() {
+        let sched = ResourceScheduler::new();
+        // Default EMA 8 tok/s ⇒ 800 tokens ≈ 100s; a 5s deadline must refuse, a 200s one admits.
+        assert!(sched.try_admit(JobClass::ReplicaJob, 800, 5_000).is_err());
+        assert!(sched.try_admit(JobClass::ReplicaJob, 800, 200_000).is_ok());
+        // Foreground is never refused.
+        assert!(sched.try_admit(JobClass::ForegroundChat, u64::MAX, 1).is_ok());
+
+        // Busy engine counts as one job ahead: same estimate now needs double the time.
+        let lease = sched.acquire(JobClass::ForegroundChat);
+        assert!(sched.try_admit(JobClass::ReplicaJob, 800, 150_000).is_err(), "one ahead doubles the projection");
+        assert!(sched.try_admit(JobClass::ReplicaJob, 800, 250_000).is_ok());
+        drop(lease);
+    }
+
+    #[test]
+    fn ema_tracks_observed_rate() {
+        let sched = ResourceScheduler::new();
+        let before = sched.status().ema_millitok_per_sec;
+        // 100 tokens in 1000ms = 100 tok/s — far above the 8 tok/s floor; EMA must move up.
+        sched.record_generation(100, 1_000);
+        let after = sched.status().ema_millitok_per_sec;
+        assert!(after > before, "{after} !> {before}");
+        // Degenerate samples are ignored.
+        sched.record_generation(0, 100);
+        sched.record_generation(100, 0);
+        assert_eq!(sched.status().completed_jobs, 1);
+    }
+}

palw-gateway/src/store.rs

@@ -0,0 +1,1469 @@
+//! The Conversation Session Layer store — the thing the Explore survey confirmed does not exist
+//! anywhere in the repo yet.
+//!
+//! Design constraints carried in from the survey and the frozen product doc:
+//! * **Token-id-stable history is the schema's core invariant.** Every turn stores the exact
+//!   `prompt_ids` it was generated from and the exact `output_ids` the engine returned. The next
+//!   turn's context is built by CONCATENATING stored ids — never by detokenize→retokenize, which
+//!   is what silently defeated the engine's prefix cache in the current stack.
+//! * **Display text is separate from model history.** The receipt footer / search-source block
+//!   polluting the next prompt was a live bug; here `display_text` (what the UI shows) and the
+//!   ids (what the model sees) are different columns, so decoration can never leak into context.
+//! * **Dual-head from day one** (`local_head` / `certified_head`), and a `TurnVerificationStatus`
+//!   column, so UX Phase 2 is a writer of existing columns, not a migration.
+//! * Branching = a turn's `parent_turn_id` pointing at any earlier turn; `local_head` names the
+//!   active leaf. "Edit message N" is: append a new turn whose parent is N-1's turn and move the
+//!   head — history is immutable, exactly like the design doc's message-branch model.
+//!
+//! Schema v2 (UX Phase 1) adds the product-doc layers that live NEXT TO the turn tree:
+//! projects/workspaces (§10), long-term memory with provenance + soft delete (§12), artifact
+//! versioning (§8/§9), the tool-call ledger with the exactly-once side-effect guard (§6), and
+//! two turn columns — `user_block_text` (the EXACT text encoded into the turn's user block:
+//! attachments + tool results + user text, so history recompilation is id-stable even for turns
+//! that carried context material) and `context_meta_json` (what the compiler actually included:
+//! memory snapshot root, chunk selections — the future receipt commitment surface).
+//!
+//! Verification pipeline writes (Phase 2's settlement clock) also live here:
+//! `set_verification_status` enforces the legal transition machine, recomputes `certified_head`
+//! (deepest turn with an unbroken certified prefix from the root), and on `Mismatch` cascades
+//! `MintIneligible` to every descendant — the §4 semantics: local conversation survives, the
+//! reward dependency chain does not.
+//!
+//! Hardening copies the `runtime-palw/state_store.rs` pattern where it is cheap and load-bearing
+//! (application_id, WAL, synchronous=FULL, foreign keys). The consensus ledger itself is NOT
+//! reused — the survey's verdict — because chat state does not belong in a protocol ledger.
+
+use std::path::Path;
+
+use rusqlite::{Connection, OpenFlags, params};
+
+use crate::events::{ConversationHeadsV1, TurnPrivacyMode, TurnVerificationStatus};
+
+/// "PALW" ^ 0x20202020 — distinct from the protocol ledger's 0x5041_4c57 so the two databases
+/// can never be mistaken for one another by application_id.
+const APPLICATION_ID: i64 = 0x7061_6c77; // "palw"
+const SCHEMA_VERSION: i64 = 4;
+
+pub struct SessionStore {
+    conn: Connection,
+}
+
+#[derive(Debug)]
+#[allow(dead_code)] // read-model: fields mirror the row even where the gateway does not read them yet
+pub struct StoredTurn {
+    pub turn_id: String,
+    pub conversation_id: String,
+    pub parent_turn_id: Option<String>,
+    pub role_user_text: String,
+    /// The exact text the compiler encoded into this turn's user block (user text + rendered
+    /// attachments/tool results). `None` on rows written by schema v1 ⇒ the block was the raw
+    /// user text; `user_block()` folds that fallback so history recompilation stays id-stable
+    /// across the migration.
+    pub user_block_text: Option<String>,
+    pub context_meta_json: Option<String>,
+    pub display_text: String,
+    pub prompt_ids: Vec<u32>,
+    pub output_ids: Vec<u32>,
+    pub stop_reason: Option<String>,
+    pub verification_status: TurnVerificationStatus,
+    pub privacy_mode: TurnPrivacyMode,
+    /// The engine's `RCPT` line (present when the engine ran with an audit key) — attached to
+    /// the A-commit by the Phase-2 worker.
+    pub receipt_json: Option<String>,
+    /// Engine execution roots (`RuntimeRootsV1` as JSON) captured at completion — the extra
+    /// commitments the A-commit carries for structural replica matching.
+    pub runtime_roots_json: Option<String>,
+    /// The committed `live_search_bundle_v1` when this turn ran a search. Fixed at
+    /// `begin_turn` because its rendered evidence is inside the compiled user block — the
+    /// prompt commitment covers it transitively, exactly like the legacy server.
+    pub search_bundle_json: Option<String>,
+    pub created_ms: i64,
+}
+
+impl StoredTurn {
+    pub fn user_block(&self) -> &str {
+        self.user_block_text.as_deref().unwrap_or(&self.role_user_text)
+    }
+}
+
+#[derive(Debug)]
+#[allow(dead_code)]
+pub struct ConversationRow {
+    pub conversation_id: String,
+    pub title: String,
+    pub project_id: Option<String>,
+    pub heads: ConversationHeadsV1,
+    pub created_ms: i64,
+    pub updated_ms: i64,
+}
+
+#[derive(Debug, Clone)]
+#[allow(dead_code)]
+pub struct ProjectRow {
+    pub project_id: String,
+    pub name: String,
+    pub instructions: String,
+    pub created_ms: i64,
+    pub updated_ms: i64,
+}
+
+#[derive(Debug, Clone)]
+pub struct MemoryEntryRow {
+    pub memory_id: String,
+    pub namespace: String,
+    pub content: String,
+    pub source_turn_id: Option<String>,
+    pub created_sequence: i64,
+    pub created_ms: i64,
+}
+
+#[derive(Debug, Clone)]
+pub struct ArtifactMeta {
+    pub artifact_id: String,
+    pub content_hash: String,
+    pub mime_type: String,
+    pub byte_length: i64,
+    pub display_name: String,
+    pub parent_artifact_id: Option<String>,
+    pub version: i64,
+    pub parser_policy: String,
+    pub project_id: Option<String>,
+    pub created_by_turn: Option<String>,
+    pub created_ms: i64,
+}
+
+#[derive(Debug, Clone)]
+pub struct ToolCallRow {
+    pub call_id: String,
+    pub tool_name: String,
+    pub mode: String,
+    pub arguments_json: String,
+    pub status: String,
+    pub result_artifact_id: Option<String>,
+    pub result_preview: String,
+    pub error: Option<String>,
+    pub conversation_id: Option<String>,
+    pub created_ms: i64,
+    pub executed_ms: Option<i64>,
+}
+
+pub struct NewTurn<'a> {
+    pub turn_id: &'a str,
+    pub conversation_id: &'a str,
+    pub parent_turn_id: Option<&'a str>,
+    pub role_user_text: &'a str,
+    pub user_block_text: &'a str,
+    pub context_meta_json: Option<&'a str>,
+    pub prompt_ids: &'a [u32],
+    pub privacy_mode: TurnPrivacyMode,
+    pub search_bundle_json: Option<&'a str>,
+    pub now_ms: i64,
+}
+
+/// Completion payload for a turn (mirrors `NewTurn` — struct args, not positional).
+pub struct CompletedTurn<'a> {
+    pub turn_id: &'a str,
+    pub output_ids: &'a [u32],
+    pub display_text: &'a str,
+    pub stop_reason: &'a str,
+    pub status: TurnVerificationStatus,
+    pub receipt_json: Option<&'a str>,
+    pub runtime_roots_json: Option<&'a str>,
+}
+
+/// What a settlement-clock write changed, so the supervisor/UI can react without re-reading.
+#[derive(Debug)]
+pub struct VerificationOutcome {
+    pub status: TurnVerificationStatus,
+    /// Descendant turns forced to `MintIneligible` by a mismatch cascade (empty otherwise).
+    pub cascaded: Vec<String>,
+    pub certified_head: Option<String>,
+}
+
+fn ids_to_blob(ids: &[u32]) -> Vec<u8> {
+    let mut out = Vec::with_capacity(ids.len() * 4);
+    for id in ids {
+        out.extend_from_slice(&id.to_le_bytes());
+    }
+    out
+}
+
+fn blob_to_ids(blob: &[u8]) -> Vec<u32> {
+    blob.chunks_exact(4).map(|c| u32::from_le_bytes([c[0], c[1], c[2], c[3]])).collect()
+}
+
+/// The settlement pipeline's legal moves (§"最重要" + §4). `ReplicaMatched → Certified` is legal
+/// because auditing is SAMPLED — a job the auditor lottery skips certifies straight from the
+/// match. `MintIneligible` is reachable from any live state (policy exit), never from a terminal
+/// one. Nothing ever leaves `Mismatch`, `MintIneligible`, or `Matured`.
+fn verification_transition_legal(from: TurnVerificationStatus, to: TurnVerificationStatus) -> bool {
+    use TurnVerificationStatus::*;
+    matches!(
+        (from, to),
+        (LocalComplete, ReplicaPending)
+            | (ReplicaPending, ReplicaMatched)
+            | (ReplicaPending, Mismatch)
+            | (ReplicaMatched, AuditPending)
+            | (ReplicaMatched, Certified)
+            | (ReplicaMatched, Mismatch)
+            | (AuditPending, Certified)
+            | (AuditPending, Mismatch)
+            | (Certified, Matured)
+    ) || (to == MintIneligible && !matches!(from, Mismatch | MintIneligible | Matured))
+}
+
+fn branch_history_conn(conn: &Connection, leaf: &str) -> Result<Vec<StoredTurn>, String> {
+    let mut chain = Vec::new();
+    let mut cursor = Some(leaf.to_string());
+    while let Some(id) = cursor {
+        let turn = get_turn_conn(conn, &id)?;
+        cursor = turn.parent_turn_id.clone();
+        chain.push(turn);
+        if chain.len() > 100_000 {
+            return Err("turn chain exceeds 100k — refusing (corrupt parent loop?)".into());
+        }
+    }
+    chain.reverse();
+    Ok(chain)
+}
+
+const TURN_COLUMNS: &str = "turn_id, conversation_id, parent_turn_id, role_user_text, display_text,
+                prompt_ids, output_ids, stop_reason, verification_status, privacy_mode, created_ms,
+                user_block_text, context_meta_json, receipt_json, runtime_roots_json, search_bundle_json";
+
+fn turn_from_row(r: &rusqlite::Row) -> rusqlite::Result<StoredTurn> {
+    let prompt: Vec<u8> = r.get(5)?;
+    let output: Vec<u8> = r.get(6)?;
+    let status: String = r.get(8)?;
+    let privacy: String = r.get(9)?;
+    Ok(StoredTurn {
+        turn_id: r.get(0)?,
+        conversation_id: r.get(1)?,
+        parent_turn_id: r.get(2)?,
+        role_user_text: r.get(3)?,
+        display_text: r.get(4)?,
+        prompt_ids: blob_to_ids(&prompt),
+        output_ids: blob_to_ids(&output),
+        stop_reason: r.get(7)?,
+        verification_status: TurnVerificationStatus::from_str(&status)
+            .unwrap_or(TurnVerificationStatus::MintIneligible),
+        privacy_mode: TurnPrivacyMode::from_str(&privacy).unwrap_or(TurnPrivacyMode::LocalOnly),
+        created_ms: r.get(10)?,
+        user_block_text: r.get(11)?,
+        context_meta_json: r.get(12)?,
+        receipt_json: r.get(13)?,
+        runtime_roots_json: r.get(14)?,
+        search_bundle_json: r.get(15)?,
+    })
+}
+
+fn get_turn_conn(conn: &Connection, turn_id: &str) -> Result<StoredTurn, String> {
+    conn.query_row(&format!("SELECT {TURN_COLUMNS} FROM turns WHERE turn_id = ?1"), params![turn_id], turn_from_row)
+        .map_err(|e| format!("turn {turn_id}: {e}"))
+}
+
+/// Recompute `certified_head` = the DEEPEST turn on the local-head branch whose whole prefix
+/// (root..=turn) is `Certified`/`Matured`. Replica/audit results land out of order, so a later
+/// turn certifying before an earlier one must NOT advance the head past the gap — re-issue from
+/// certified head (§4) only makes sense if everything before it is settled.
+fn recompute_certified_head(conn: &Connection, conversation_id: &str, now_ms: i64) -> Result<Option<String>, String> {
+    let local_head: Option<String> = conn
+        .query_row("SELECT local_head FROM conversations WHERE conversation_id = ?1", params![conversation_id], |r| r.get(0))
+        .map_err(|e| format!("conversation {conversation_id}: {e}"))?;
+    let mut head: Option<String> = None;
+    if let Some(leaf) = local_head {
+        for turn in branch_history_conn(conn, &leaf)? {
+            match turn.verification_status {
+                TurnVerificationStatus::Certified | TurnVerificationStatus::Matured => head = Some(turn.turn_id),
+                _ => break,
+            }
+        }
+    }
+    conn.execute(
+        "UPDATE conversations SET certified_head = ?2, updated_ms = ?3 WHERE conversation_id = ?1",
+        params![conversation_id, head, now_ms],
+    )
+    .map_err(|e| e.to_string())?;
+    Ok(head)
+}
+
+impl SessionStore {
+    pub fn open(path: &Path) -> Result<Self, String> {
+        if let Some(parent) = path.parent() {
+            std::fs::create_dir_all(parent).map_err(|e| format!("create {}: {e}", parent.display()))?;
+        }
+        let conn = Connection::open_with_flags(
+            path,
+            OpenFlags::SQLITE_OPEN_READ_WRITE | OpenFlags::SQLITE_OPEN_CREATE | OpenFlags::SQLITE_OPEN_NO_MUTEX,
+        )
+        .map_err(|e| format!("open {}: {e}", path.display()))?;
+
+        conn.pragma_update(None, "journal_mode", "WAL").map_err(|e| e.to_string())?;
+        conn.pragma_update(None, "synchronous", "FULL").map_err(|e| e.to_string())?;
+        conn.pragma_update(None, "foreign_keys", "ON").map_err(|e| e.to_string())?;
+
+        let existing_app_id: i64 = conn.query_row("PRAGMA application_id", [], |r| r.get(0)).map_err(|e| e.to_string())?;
+        if existing_app_id == 0 {
+            conn.pragma_update(None, "application_id", APPLICATION_ID).map_err(|e| e.to_string())?;
+        } else if existing_app_id != APPLICATION_ID {
+            return Err(format!(
+                "database {} has application_id {existing_app_id:#x}; refusing to open a non-session database",
+                path.display()
+            ));
+        }
+
+        let user_version: i64 = conn.query_row("PRAGMA user_version", [], |r| r.get(0)).map_err(|e| e.to_string())?;
+        match user_version {
+            0 => {
+                Self::create_schema(&conn)?;
+                conn.pragma_update(None, "user_version", SCHEMA_VERSION).map_err(|e| e.to_string())?;
+            }
+            1 => {
+                Self::migrate_v1_to_v2(&conn)?;
+                Self::migrate_v2_to_v3(&conn)?;
+                Self::migrate_v3_to_v4(&conn)?;
+            }
+            2 => {
+                Self::migrate_v2_to_v3(&conn)?;
+                Self::migrate_v3_to_v4(&conn)?;
+            }
+            3 => {
+                Self::migrate_v3_to_v4(&conn)?;
+            }
+            SCHEMA_VERSION => {}
+            v => return Err(format!("unsupported session schema version {v} (this build speaks {SCHEMA_VERSION})")),
+        }
+        Ok(Self { conn })
+    }
+
+    fn create_schema(conn: &Connection) -> Result<(), String> {
+        conn.execute_batch(
+            r#"
+            CREATE TABLE IF NOT EXISTS projects (
+                project_id   TEXT PRIMARY KEY,
+                name         TEXT NOT NULL,
+                instructions TEXT NOT NULL DEFAULT '',
+                created_ms   INTEGER NOT NULL,
+                updated_ms   INTEGER NOT NULL
+            );
+            CREATE TABLE IF NOT EXISTS conversations (
+                conversation_id TEXT PRIMARY KEY,
+                title           TEXT NOT NULL DEFAULT '',
+                project_id      TEXT REFERENCES projects(project_id),
+                local_head      TEXT,
+                certified_head  TEXT,
+                created_ms      INTEGER NOT NULL,
+                updated_ms      INTEGER NOT NULL
+            );
+            CREATE TABLE IF NOT EXISTS turns (
+                turn_id             TEXT PRIMARY KEY,
+                conversation_id     TEXT NOT NULL REFERENCES conversations(conversation_id),
+                parent_turn_id      TEXT REFERENCES turns(turn_id),
+                role_user_text      TEXT NOT NULL,
+                user_block_text     TEXT,
+                context_meta_json   TEXT,
+                display_text        TEXT NOT NULL DEFAULT '',
+                prompt_ids          BLOB NOT NULL,
+                output_ids          BLOB NOT NULL DEFAULT x'',
+                stop_reason         TEXT,
+                verification_status TEXT NOT NULL,
+                privacy_mode        TEXT NOT NULL,
+                receipt_json        TEXT,
+                runtime_roots_json  TEXT,
+                search_bundle_json  TEXT,
+                created_ms          INTEGER NOT NULL
+            );
+            CREATE INDEX IF NOT EXISTS turns_by_conversation ON turns(conversation_id, created_ms);
+            CREATE INDEX IF NOT EXISTS turns_by_parent ON turns(parent_turn_id);
+            CREATE TABLE IF NOT EXISTS artifacts (
+                artifact_id        TEXT PRIMARY KEY,
+                content_hash       TEXT NOT NULL,
+                mime_type          TEXT NOT NULL,
+                byte_length        INTEGER NOT NULL,
+                display_name       TEXT NOT NULL DEFAULT '',
+                parent_artifact_id TEXT REFERENCES artifacts(artifact_id),
+                version            INTEGER NOT NULL DEFAULT 1,
+                parser_policy      TEXT NOT NULL DEFAULT '',
+                project_id         TEXT REFERENCES projects(project_id),
+                created_by_turn    TEXT REFERENCES turns(turn_id),
+                created_ms         INTEGER NOT NULL
+            );
+            CREATE INDEX IF NOT EXISTS artifacts_by_project ON artifacts(project_id, created_ms);
+            CREATE TABLE IF NOT EXISTS memory_entries (
+                memory_id        TEXT PRIMARY KEY,
+                namespace        TEXT NOT NULL,
+                content          TEXT NOT NULL,
+                source_turn_id   TEXT REFERENCES turns(turn_id),
+                created_sequence INTEGER NOT NULL,
+                deleted_sequence INTEGER,
+                created_ms       INTEGER NOT NULL
+            );
+            CREATE INDEX IF NOT EXISTS memory_by_namespace ON memory_entries(namespace, created_sequence);
+            CREATE TABLE IF NOT EXISTS tool_calls (
+                call_id            TEXT PRIMARY KEY,
+                tool_name          TEXT NOT NULL,
+                mode               TEXT NOT NULL,
+                arguments_json     TEXT NOT NULL,
+                status             TEXT NOT NULL,
+                result_artifact_id TEXT REFERENCES artifacts(artifact_id),
+                result_preview     TEXT NOT NULL DEFAULT '',
+                error              TEXT,
+                conversation_id    TEXT REFERENCES conversations(conversation_id),
+                created_ms         INTEGER NOT NULL,
+                executed_ms        INTEGER
+            );
+            "#,
+        )
+        .map_err(|e| e.to_string())
+    }
+
+    /// v1 → v2: additive only (§18's migration rule — existing turns stay readable, their
+    /// `user_block_text` NULL means "the user block was the raw user text", which
+    /// `StoredTurn::user_block()` folds back so recompiled prompts are byte-identical to what
+    /// a v1 gateway produced for the same history.
+    fn migrate_v1_to_v2(conn: &Connection) -> Result<(), String> {
+        conn.execute_batch(
+            r#"
+            BEGIN;
+            ALTER TABLE conversations ADD COLUMN project_id TEXT REFERENCES projects(project_id);
+            ALTER TABLE turns ADD COLUMN user_block_text TEXT;
+            ALTER TABLE turns ADD COLUMN context_meta_json TEXT;
+            ALTER TABLE artifacts ADD COLUMN display_name TEXT NOT NULL DEFAULT '';
+            ALTER TABLE artifacts ADD COLUMN parent_artifact_id TEXT REFERENCES artifacts(artifact_id);
+            ALTER TABLE artifacts ADD COLUMN version INTEGER NOT NULL DEFAULT 1;
+            ALTER TABLE artifacts ADD COLUMN parser_policy TEXT NOT NULL DEFAULT '';
+            ALTER TABLE artifacts ADD COLUMN project_id TEXT REFERENCES projects(project_id);
+            CREATE TABLE projects (
+                project_id   TEXT PRIMARY KEY,
+                name         TEXT NOT NULL,
+                instructions TEXT NOT NULL DEFAULT '',
+                created_ms   INTEGER NOT NULL,
+                updated_ms   INTEGER NOT NULL
+            );
+            CREATE TABLE memory_entries (
+                memory_id        TEXT PRIMARY KEY,
+                namespace        TEXT NOT NULL,
+                content          TEXT NOT NULL,
+                source_turn_id   TEXT REFERENCES turns(turn_id),
+                created_sequence INTEGER NOT NULL,
+                deleted_sequence INTEGER,
+                created_ms       INTEGER NOT NULL
+            );
+            CREATE INDEX memory_by_namespace ON memory_entries(namespace, created_sequence);
+            CREATE TABLE tool_calls (
+                call_id            TEXT PRIMARY KEY,
+                tool_name          TEXT NOT NULL,
+                mode               TEXT NOT NULL,
+                arguments_json     TEXT NOT NULL,
+                status             TEXT NOT NULL,
+                result_artifact_id TEXT REFERENCES artifacts(artifact_id),
+                result_preview     TEXT NOT NULL DEFAULT '',
+                error              TEXT,
+                conversation_id    TEXT REFERENCES conversations(conversation_id),
+                created_ms         INTEGER NOT NULL,
+                executed_ms        INTEGER
+            );
+            CREATE INDEX IF NOT EXISTS turns_by_parent ON turns(parent_turn_id);
+            CREATE INDEX IF NOT EXISTS artifacts_by_project ON artifacts(project_id, created_ms);
+            PRAGMA user_version = 2;
+            COMMIT;
+            "#,
+        )
+        .map_err(|e| format!("migrate session schema v1→v2: {e}"))
+    }
+
+    /// v2 → v3: one additive column — the engine execution roots captured per turn.
+    fn migrate_v2_to_v3(conn: &Connection) -> Result<(), String> {
+        conn.execute_batch(
+            r#"
+            BEGIN;
+            ALTER TABLE turns ADD COLUMN runtime_roots_json TEXT;
+            PRAGMA user_version = 3;
+            COMMIT;
+            "#,
+        )
+        .map_err(|e| format!("migrate session schema v2→v3: {e}"))
+    }
+
+    /// v3 → v4: one additive column — the committed live-search bundle. It is fixed BEFORE
+    /// generation (the evidence is part of the compiled user block, hence of the prompt
+    /// commitment), so it lands on `begin_turn`, not completion.
+    fn migrate_v3_to_v4(conn: &Connection) -> Result<(), String> {
+        conn.execute_batch(
+            r#"
+            BEGIN;
+            ALTER TABLE turns ADD COLUMN search_bundle_json TEXT;
+            PRAGMA user_version = 4;
+            COMMIT;
+            "#,
+        )
+        .map_err(|e| format!("migrate session schema v3→v4: {e}"))
+    }
+
+    // ---- conversations ------------------------------------------------------------------
+
+    pub fn create_conversation(
+        &self,
+        conversation_id: &str,
+        title: &str,
+        project_id: Option<&str>,
+        now_ms: i64,
+    ) -> Result<(), String> {
+        self.conn
+            .execute(
+                "INSERT INTO conversations (conversation_id, title, project_id, created_ms, updated_ms)
+                 VALUES (?1, ?2, ?3, ?4, ?4)",
+                params![conversation_id, title, project_id, now_ms],
+            )
+            .map_err(|e| e.to_string())?;
+        Ok(())
+    }
+
+    pub fn list_conversations(&self) -> Result<Vec<ConversationRow>, String> {
+        let mut stmt = self
+            .conn
+            .prepare(
+                "SELECT conversation_id, title, project_id, local_head, certified_head, created_ms, updated_ms
+                 FROM conversations ORDER BY updated_ms DESC",
+            )
+            .map_err(|e| e.to_string())?;
+        let rows = stmt
+            .query_map([], |r| {
+                Ok(ConversationRow {
+                    conversation_id: r.get(0)?,
+                    title: r.get(1)?,
+                    project_id: r.get(2)?,
+                    heads: ConversationHeadsV1 { local_head: r.get(3)?, certified_head: r.get(4)? },
+                    created_ms: r.get(5)?,
+                    updated_ms: r.get(6)?,
+                })
+            })
+            .map_err(|e| e.to_string())?;
+        rows.collect::<Result<Vec<_>, _>>().map_err(|e| e.to_string())
+    }
+
+    pub fn heads(&self, conversation_id: &str) -> Result<ConversationHeadsV1, String> {
+        self.conn
+            .query_row(
+                "SELECT local_head, certified_head FROM conversations WHERE conversation_id = ?1",
+                params![conversation_id],
+                |r| Ok(ConversationHeadsV1 { local_head: r.get(0)?, certified_head: r.get(1)? }),
+            )
+            .map_err(|e| format!("conversation {conversation_id}: {e}"))
+    }
+
+    pub fn conversation_project(&self, conversation_id: &str) -> Result<Option<String>, String> {
+        self.conn
+            .query_row("SELECT project_id FROM conversations WHERE conversation_id = ?1", params![conversation_id], |r| {
+                r.get(0)
+            })
+            .map_err(|e| format!("conversation {conversation_id}: {e}"))
+    }
+
+    // ---- turns --------------------------------------------------------------------------
+
+    /// Append a turn under `parent_turn_id` (None ⇒ a root — either the first turn or a branch
+    /// from "before the first message") and move `local_head` to it. History is append-only:
+    /// edit/regenerate NEVER rewrites a row, it adds a sibling and moves the head.
+    pub fn begin_turn(&mut self, t: &NewTurn) -> Result<(), String> {
+        let tx = self.conn.transaction().map_err(|e| e.to_string())?;
+        if let Some(parent) = t.parent_turn_id {
+            let parent_conv: String = tx
+                .query_row("SELECT conversation_id FROM turns WHERE turn_id = ?1", params![parent], |r| r.get(0))
+                .map_err(|e| format!("parent turn {parent}: {e}"))?;
+            if parent_conv != t.conversation_id {
+                return Err(format!("parent turn {parent} belongs to another conversation"));
+            }
+        }
+        tx.execute(
+            "INSERT INTO turns (turn_id, conversation_id, parent_turn_id, role_user_text, user_block_text,
+                                context_meta_json, prompt_ids, verification_status, privacy_mode,
+                                search_bundle_json, created_ms)
+             VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11)",
+            params![
+                t.turn_id,
+                t.conversation_id,
+                t.parent_turn_id,
+                t.role_user_text,
+                t.user_block_text,
+                t.context_meta_json,
+                ids_to_blob(t.prompt_ids),
+                TurnVerificationStatus::Streaming.as_str(),
+                t.privacy_mode.as_str(),
+                t.search_bundle_json,
+                t.now_ms
+            ],
+        )
+        .map_err(|e| e.to_string())?;
+        tx.execute(
+            "UPDATE conversations SET local_head = ?2, updated_ms = ?3 WHERE conversation_id = ?1",
+            params![t.conversation_id, t.turn_id, t.now_ms],
+        )
+        .map_err(|e| e.to_string())?;
+        tx.commit().map_err(|e| e.to_string())
+    }
+
+    pub fn complete_turn(&self, t: &CompletedTurn) -> Result<(), String> {
+        let n = self
+            .conn
+            .execute(
+                "UPDATE turns SET output_ids = ?2, display_text = ?3, stop_reason = ?4,
+                                  verification_status = ?5, receipt_json = ?6, runtime_roots_json = ?7
+                 WHERE turn_id = ?1",
+                params![
+                    t.turn_id,
+                    ids_to_blob(t.output_ids),
+                    t.display_text,
+                    t.stop_reason,
+                    t.status.as_str(),
+                    t.receipt_json,
+                    t.runtime_roots_json
+                ],
+            )
+            .map_err(|e| e.to_string())?;
+        if n != 1 {
+            return Err(format!("turn {} not found at completion", t.turn_id));
+        }
+        Ok(())
+    }
+
+    pub fn get_turn(&self, turn_id: &str) -> Result<StoredTurn, String> {
+        get_turn_conn(&self.conn, turn_id)
+    }
+
+    /// All root turns (no parent) across every conversation, oldest first. The candidate set for
+    /// LM Studio transcript resolution: that client owns no gateway ids, so a conversation can
+    /// only be re-found by content, starting from its first exchange.
+    pub fn root_turns(&self) -> Result<Vec<StoredTurn>, String> {
+        let mut stmt = self
+            .conn
+            .prepare(&format!(
+                "SELECT {TURN_COLUMNS} FROM turns WHERE parent_turn_id IS NULL ORDER BY created_ms, turn_id"
+            ))
+            .map_err(|e| e.to_string())?;
+        let rows = stmt.query_map([], turn_from_row).map_err(|e| e.to_string())?;
+        rows.collect::<Result<Vec<_>, _>>().map_err(|e| e.to_string())
+    }
+
+    /// Direct children of a turn, oldest first (edit/regenerate siblings in creation order).
+    pub fn children_of(&self, turn_id: &str) -> Result<Vec<StoredTurn>, String> {
+        let mut stmt = self
+            .conn
+            .prepare(&format!(
+                "SELECT {TURN_COLUMNS} FROM turns WHERE parent_turn_id = ?1 ORDER BY created_ms, turn_id"
+            ))
+            .map_err(|e| e.to_string())?;
+        let rows = stmt.query_map(params![turn_id], turn_from_row).map_err(|e| e.to_string())?;
+        rows.collect::<Result<Vec<_>, _>>().map_err(|e| e.to_string())
+    }
+
+    /// Walk parent pointers from `leaf` back to the root, returning ROOT-FIRST. This is the
+    /// branch-aware history the context compiler consumes: exactly the turns on the active
+    /// branch, none from abandoned siblings.
+    pub fn branch_history(&self, leaf: &str) -> Result<Vec<StoredTurn>, String> {
+        branch_history_conn(&self.conn, leaf)
+    }
+
+    /// A turn that FAILED (engine error — no output, nothing a user would keep) must not stay
+    /// the branch head: retract the head to its parent so the next message retries as a sibling
+    /// instead of silently building on a broken turn. The failed row itself is kept (append-only
+    /// history; it remains visible under its own id).
+    pub fn retract_failed_head(&self, conversation_id: &str, failed_turn_id: &str, now_ms: i64) -> Result<(), String> {
+        let turn = self.get_turn(failed_turn_id)?;
+        if turn.conversation_id != conversation_id {
+            return Err(format!("turn {failed_turn_id} belongs to another conversation"));
+        }
+        let head: Option<String> = self
+            .conn
+            .query_row("SELECT local_head FROM conversations WHERE conversation_id = ?1", params![conversation_id], |r| {
+                r.get(0)
+            })
+            .map_err(|e| e.to_string())?;
+        if head.as_deref() == Some(failed_turn_id) {
+            self.conn
+                .execute(
+                    "UPDATE conversations SET local_head = ?2, updated_ms = ?3 WHERE conversation_id = ?1",
+                    params![conversation_id, turn.parent_turn_id, now_ms],
+                )
+                .map_err(|e| e.to_string())?;
+        }
+        Ok(())
+    }
+
+    pub fn set_local_head(&self, conversation_id: &str, turn_id: &str, now_ms: i64) -> Result<(), String> {
+        let turn = self.get_turn(turn_id)?;
+        if turn.conversation_id != conversation_id {
+            return Err(format!("turn {turn_id} belongs to another conversation"));
+        }
+        self.conn
+            .execute(
+                "UPDATE conversations SET local_head = ?2, updated_ms = ?3 WHERE conversation_id = ?1",
+                params![conversation_id, turn_id, now_ms],
+            )
+            .map_err(|e| e.to_string())?;
+        // The certified prefix is branch-relative: switching branches moves it too.
+        recompute_certified_head(&self.conn, conversation_id, now_ms)?;
+        Ok(())
+    }
+
+    // ---- settlement clock (Phase 2 writes) ----------------------------------------------
+
+    /// Advance a turn along the verification pipeline. Enforces the legal transition machine,
+    /// requires replica states to have a non-LocalOnly privacy mode (a LocalOnly turn never
+    /// leaves the device, so it can never be replica-pending), cascades mismatches, and
+    /// recomputes `certified_head`.
+    pub fn set_verification_status(
+        &mut self,
+        turn_id: &str,
+        to: TurnVerificationStatus,
+        now_ms: i64,
+    ) -> Result<VerificationOutcome, String> {
+        let tx = self.conn.transaction().map_err(|e| e.to_string())?;
+        let turn = get_turn_conn(&tx, turn_id)?;
+        let from = turn.verification_status;
+        if !verification_transition_legal(from, to) {
+            return Err(format!("illegal verification transition {} → {}", from.as_str(), to.as_str()));
+        }
+        if to == TurnVerificationStatus::ReplicaPending && turn.privacy_mode == TurnPrivacyMode::LocalOnly {
+            return Err(format!("turn {turn_id} is local_only — it can never enter the replica pipeline"));
+        }
+        tx.execute("UPDATE turns SET verification_status = ?2 WHERE turn_id = ?1", params![turn_id, to.as_str()])
+            .map_err(|e| e.to_string())?;
+
+        // §4: a mismatch keeps the local conversation but invalidates the REWARD dependency
+        // chain — every descendant (any branch below this turn) leaves the pipeline.
+        let mut cascaded = Vec::new();
+        if to == TurnVerificationStatus::Mismatch {
+            let mut stmt = tx
+                .prepare(
+                    "WITH RECURSIVE below(id) AS (
+                         SELECT turn_id FROM turns WHERE parent_turn_id = ?1
+                         UNION ALL
+                         SELECT t.turn_id FROM turns t JOIN below b ON t.parent_turn_id = b.id
+                     )
+                     SELECT id FROM below",
+                )
+                .map_err(|e| e.to_string())?;
+            let descendants: Vec<String> = stmt
+                .query_map(params![turn_id], |r| r.get(0))
+                .map_err(|e| e.to_string())?
+                .collect::<Result<_, _>>()
+                .map_err(|e| e.to_string())?;
+            drop(stmt);
+            for id in descendants {
+                let n = tx
+                    .execute(
+                        "UPDATE turns SET verification_status = ?2 WHERE turn_id = ?1
+                         AND verification_status NOT IN ('mismatch', 'mint_ineligible')",
+                        params![id, TurnVerificationStatus::MintIneligible.as_str()],
+                    )
+                    .map_err(|e| e.to_string())?;
+                if n == 1 {
+                    cascaded.push(id);
+                }
+            }
+        }
+
+        let certified_head = recompute_certified_head(&tx, &turn.conversation_id, now_ms)?;
+        tx.commit().map_err(|e| e.to_string())?;
+        Ok(VerificationOutcome { status: to, cascaded, certified_head })
+    }
+
+    /// A-side scan (§15 "A receipt登録"): completed turns whose privacy mode wants replication
+    /// and that have not yet been submitted. Stateless-worker recovery falls out of this being
+    /// a pure store query — a worker restarted mid-flight simply finds them again and re-submits
+    /// idempotently.
+    pub fn turns_awaiting_palw_submission(&self) -> Result<Vec<StoredTurn>, String> {
+        let mut stmt = self
+            .conn
+            .prepare(&format!(
+                "SELECT {TURN_COLUMNS} FROM turns
+                 WHERE verification_status = 'local_complete'
+                   AND privacy_mode IN ('verified_no_mint', 'palw_mint')
+                 ORDER BY created_ms, turn_id"
+            ))
+            .map_err(|e| e.to_string())?;
+        let rows = stmt.query_map([], turn_from_row).map_err(|e| e.to_string())?;
+        rows.collect::<Result<Vec<_>, _>>().map_err(|e| e.to_string())
+    }
+
+    /// Turns whose settlement is in flight — the worker polls the coordinator for verdicts on
+    /// exactly these.
+    pub fn turns_in_palw_pipeline(&self) -> Result<Vec<StoredTurn>, String> {
+        let mut stmt = self
+            .conn
+            .prepare(&format!(
+                "SELECT {TURN_COLUMNS} FROM turns
+                 WHERE verification_status IN ('replica_pending', 'replica_matched', 'audit_pending')
+                 ORDER BY created_ms, turn_id"
+            ))
+            .map_err(|e| e.to_string())?;
+        let rows = stmt.query_map([], turn_from_row).map_err(|e| e.to_string())?;
+        rows.collect::<Result<Vec<_>, _>>().map_err(|e| e.to_string())
+    }
+
+    // ---- projects (§10) -----------------------------------------------------------------
+
+    pub fn create_project(&self, project_id: &str, name: &str, instructions: &str, now_ms: i64) -> Result<(), String> {
+        self.conn
+            .execute(
+                "INSERT INTO projects (project_id, name, instructions, created_ms, updated_ms) VALUES (?1, ?2, ?3, ?4, ?4)",
+                params![project_id, name, instructions, now_ms],
+            )
+            .map_err(|e| e.to_string())?;
+        Ok(())
+    }
+
+    pub fn get_project(&self, project_id: &str) -> Result<ProjectRow, String> {
+        self.conn
+            .query_row(
+                "SELECT project_id, name, instructions, created_ms, updated_ms FROM projects WHERE project_id = ?1",
+                params![project_id],
+                |r| {
+                    Ok(ProjectRow {
+                        project_id: r.get(0)?,
+                        name: r.get(1)?,
+                        instructions: r.get(2)?,
+                        created_ms: r.get(3)?,
+                        updated_ms: r.get(4)?,
+                    })
+                },
+            )
+            .map_err(|e| format!("project {project_id}: {e}"))
+    }
+
+    pub fn list_projects(&self) -> Result<Vec<ProjectRow>, String> {
+        let mut stmt = self
+            .conn
+            .prepare("SELECT project_id, name, instructions, created_ms, updated_ms FROM projects ORDER BY updated_ms DESC")
+            .map_err(|e| e.to_string())?;
+        let rows = stmt
+            .query_map([], |r| {
+                Ok(ProjectRow {
+                    project_id: r.get(0)?,
+                    name: r.get(1)?,
+                    instructions: r.get(2)?,
+                    created_ms: r.get(3)?,
+                    updated_ms: r.get(4)?,
+                })
+            })
+            .map_err(|e| e.to_string())?;
+        rows.collect::<Result<Vec<_>, _>>().map_err(|e| e.to_string())
+    }
+
+    pub fn set_project_instructions(&self, project_id: &str, instructions: &str, now_ms: i64) -> Result<(), String> {
+        let n = self
+            .conn
+            .execute(
+                "UPDATE projects SET instructions = ?2, updated_ms = ?3 WHERE project_id = ?1",
+                params![project_id, instructions, now_ms],
+            )
+            .map_err(|e| e.to_string())?;
+        if n != 1 {
+            return Err(format!("project {project_id} not found"));
+        }
+        Ok(())
+    }
+
+    // ---- long-term memory (§12) ---------------------------------------------------------
+
+    /// Namespaces: `"global"` or a project id. Provenance (`source_turn_id`) and soft delete
+    /// (`deleted_sequence`) are the §12 requirements — memory is never silently rewritten, and
+    /// "これは忘れて" is a tombstone, not a DELETE.
+    pub fn add_memory(
+        &self,
+        memory_id: &str,
+        namespace: &str,
+        content: &str,
+        source_turn_id: Option<&str>,
+        now_ms: i64,
+    ) -> Result<i64, String> {
+        let seq: i64 = self
+            .conn
+            .query_row("SELECT COALESCE(MAX(created_sequence), 0) + 1 FROM memory_entries", [], |r| r.get(0))
+            .map_err(|e| e.to_string())?;
+        self.conn
+            .execute(
+                "INSERT INTO memory_entries (memory_id, namespace, content, source_turn_id, created_sequence, created_ms)
+                 VALUES (?1, ?2, ?3, ?4, ?5, ?6)",
+                params![memory_id, namespace, content, source_turn_id, seq, now_ms],
+            )
+            .map_err(|e| e.to_string())?;
+        Ok(seq)
+    }
+
+    pub fn delete_memory(&self, memory_id: &str) -> Result<(), String> {
+        let seq: i64 = self
+            .conn
+            .query_row("SELECT COALESCE(MAX(created_sequence), 0) + 1 FROM memory_entries", [], |r| r.get(0))
+            .map_err(|e| e.to_string())?;
+        let n = self
+            .conn
+            .execute(
+                "UPDATE memory_entries SET deleted_sequence = ?2 WHERE memory_id = ?1 AND deleted_sequence IS NULL",
+                params![memory_id, seq],
+            )
+            .map_err(|e| e.to_string())?;
+        if n != 1 {
+            return Err(format!("memory {memory_id} not found or already deleted"));
+        }
+        Ok(())
+    }
+
+    /// Active (non-tombstoned) entries across the given namespaces, oldest-first by global
+    /// sequence — the deterministic order the context compiler serializes into the snapshot.
+    pub fn active_memory(&self, namespaces: &[&str]) -> Result<Vec<MemoryEntryRow>, String> {
+        if namespaces.is_empty() {
+            return Ok(Vec::new());
+        }
+        let placeholders: Vec<String> = (1..=namespaces.len()).map(|i| format!("?{i}")).collect();
+        let sql = format!(
+            "SELECT memory_id, namespace, content, source_turn_id, created_sequence, created_ms
+             FROM memory_entries WHERE namespace IN ({}) AND deleted_sequence IS NULL
+             ORDER BY created_sequence",
+            placeholders.join(", ")
+        );
+        let mut stmt = self.conn.prepare(&sql).map_err(|e| e.to_string())?;
+        let rows = stmt
+            .query_map(rusqlite::params_from_iter(namespaces.iter()), |r| {
+                Ok(MemoryEntryRow {
+                    memory_id: r.get(0)?,
+                    namespace: r.get(1)?,
+                    content: r.get(2)?,
+                    source_turn_id: r.get(3)?,
+                    created_sequence: r.get(4)?,
+                    created_ms: r.get(5)?,
+                })
+            })
+            .map_err(|e| e.to_string())?;
+        rows.collect::<Result<Vec<_>, _>>().map_err(|e| e.to_string())
+    }
+
+    // ---- artifacts (§8/§9) --------------------------------------------------------------
+
+    /// Register artifact metadata. If `parent_artifact_id` is set this is a new VERSION: the
+    /// stored `version` is parent.version + 1 regardless of what the caller guessed — version
+    /// numbers are derived, never client-supplied.
+    pub fn insert_artifact(&self, meta: &ArtifactMeta) -> Result<i64, String> {
+        let version = match &meta.parent_artifact_id {
+            Some(parent) => self.get_artifact(parent)?.version + 1,
+            None => 1,
+        };
+        self.conn
+            .execute(
+                "INSERT INTO artifacts (artifact_id, content_hash, mime_type, byte_length, display_name,
+                                        parent_artifact_id, version, parser_policy, project_id, created_by_turn, created_ms)
+                 VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11)",
+                params![
+                    meta.artifact_id,
+                    meta.content_hash,
+                    meta.mime_type,
+                    meta.byte_length,
+                    meta.display_name,
+                    meta.parent_artifact_id,
+                    version,
+                    meta.parser_policy,
+                    meta.project_id,
+                    meta.created_by_turn,
+                    meta.created_ms
+                ],
+            )
+            .map_err(|e| e.to_string())?;
+        Ok(version)
+    }
+
+    pub fn get_artifact(&self, artifact_id: &str) -> Result<ArtifactMeta, String> {
+        self.conn
+            .query_row(
+                "SELECT artifact_id, content_hash, mime_type, byte_length, display_name, parent_artifact_id,
+                        version, parser_policy, project_id, created_by_turn, created_ms
+                 FROM artifacts WHERE artifact_id = ?1",
+                params![artifact_id],
+                |r| {
+                    Ok(ArtifactMeta {
+                        artifact_id: r.get(0)?,
+                        content_hash: r.get(1)?,
+                        mime_type: r.get(2)?,
+                        byte_length: r.get(3)?,
+                        display_name: r.get(4)?,
+                        parent_artifact_id: r.get(5)?,
+                        version: r.get(6)?,
+                        parser_policy: r.get(7)?,
+                        project_id: r.get(8)?,
+                        created_by_turn: r.get(9)?,
+                        created_ms: r.get(10)?,
+                    })
+                },
+            )
+            .map_err(|e| format!("artifact {artifact_id}: {e}"))
+    }
+
+    /// The version chain containing `artifact_id`, root-first up to and including it (the §9
+    /// "design.md v1 → v2 → v3" walk; forks below it are listed via `artifact_children`).
+    pub fn artifact_lineage(&self, artifact_id: &str) -> Result<Vec<ArtifactMeta>, String> {
+        let mut chain = Vec::new();
+        let mut cursor = Some(artifact_id.to_string());
+        while let Some(id) = cursor {
+            let meta = self.get_artifact(&id)?;
+            cursor = meta.parent_artifact_id.clone();
+            chain.push(meta);
+            if chain.len() > 100_000 {
+                return Err("artifact version chain exceeds 100k — refusing (corrupt parent loop?)".into());
+            }
+        }
+        chain.reverse();
+        Ok(chain)
+    }
+
+    pub fn artifact_children(&self, artifact_id: &str) -> Result<Vec<ArtifactMeta>, String> {
+        let mut stmt = self
+            .conn
+            .prepare(
+                "SELECT artifact_id FROM artifacts WHERE parent_artifact_id = ?1 ORDER BY created_ms, artifact_id",
+            )
+            .map_err(|e| e.to_string())?;
+        let ids: Vec<String> = stmt
+            .query_map(params![artifact_id], |r| r.get(0))
+            .map_err(|e| e.to_string())?
+            .collect::<Result<_, _>>()
+            .map_err(|e| e.to_string())?;
+        ids.iter().map(|id| self.get_artifact(id)).collect()
+    }
+
+    pub fn list_artifacts(&self, project_id: Option<&str>) -> Result<Vec<ArtifactMeta>, String> {
+        let sql = match project_id {
+            Some(_) => {
+                "SELECT artifact_id FROM artifacts WHERE project_id = ?1 ORDER BY created_ms DESC, artifact_id"
+            }
+            None => "SELECT artifact_id FROM artifacts WHERE ?1 IS NULL ORDER BY created_ms DESC, artifact_id",
+        };
+        let mut stmt = self.conn.prepare(sql).map_err(|e| e.to_string())?;
+        let ids: Vec<String> = stmt
+            .query_map(params![project_id], |r| r.get(0))
+            .map_err(|e| e.to_string())?
+            .collect::<Result<_, _>>()
+            .map_err(|e| e.to_string())?;
+        ids.iter().map(|id| self.get_artifact(id)).collect()
+    }
+
+    // ---- tool-call ledger (§6) ----------------------------------------------------------
+
+    pub fn insert_tool_call(&self, call: &ToolCallRow) -> Result<(), String> {
+        self.conn
+            .execute(
+                "INSERT INTO tool_calls (call_id, tool_name, mode, arguments_json, status, result_artifact_id,
+                                         result_preview, error, conversation_id, created_ms, executed_ms)
+                 VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11)",
+                params![
+                    call.call_id,
+                    call.tool_name,
+                    call.mode,
+                    call.arguments_json,
+                    call.status,
+                    call.result_artifact_id,
+                    call.result_preview,
+                    call.error,
+                    call.conversation_id,
+                    call.created_ms,
+                    call.executed_ms
+                ],
+            )
+            .map_err(|e| e.to_string())?;
+        Ok(())
+    }
+
+    pub fn get_tool_call(&self, call_id: &str) -> Result<ToolCallRow, String> {
+        self.conn
+            .query_row(
+                "SELECT call_id, tool_name, mode, arguments_json, status, result_artifact_id, result_preview,
+                        error, conversation_id, created_ms, executed_ms
+                 FROM tool_calls WHERE call_id = ?1",
+                params![call_id],
+                |r| {
+                    Ok(ToolCallRow {
+                        call_id: r.get(0)?,
+                        tool_name: r.get(1)?,
+                        mode: r.get(2)?,
+                        arguments_json: r.get(3)?,
+                        status: r.get(4)?,
+                        result_artifact_id: r.get(5)?,
+                        result_preview: r.get(6)?,
+                        error: r.get(7)?,
+                        conversation_id: r.get(8)?,
+                        created_ms: r.get(9)?,
+                        executed_ms: r.get(10)?,
+                    })
+                },
+            )
+            .map_err(|e| format!("tool call {call_id}: {e}"))
+    }
+
+    /// proposed → approved. The UI confirmation step (§6 step 2) — refuses anything not
+    /// currently proposed, so a denied or already-run call cannot be re-approved.
+    pub fn approve_tool_call(&self, call_id: &str) -> Result<(), String> {
+        let n = self
+            .conn
+            .execute("UPDATE tool_calls SET status = 'approved' WHERE call_id = ?1 AND status = 'proposed'", params![call_id])
+            .map_err(|e| e.to_string())?;
+        if n != 1 {
+            return Err(format!("tool call {call_id} is not awaiting approval"));
+        }
+        Ok(())
+    }
+
+    pub fn deny_tool_call(&self, call_id: &str) -> Result<(), String> {
+        let n = self
+            .conn
+            .execute("UPDATE tool_calls SET status = 'denied' WHERE call_id = ?1 AND status = 'proposed'", params![call_id])
+            .map_err(|e| e.to_string())?;
+        if n != 1 {
+            return Err(format!("tool call {call_id} is not awaiting approval"));
+        }
+        Ok(())
+    }
+
+    /// THE exactly-once guard (§6 step 3): flips approved → executing atomically; the single
+    /// winning UPDATE is the execution ticket. A second caller — a double-click, a retried HTTP
+    /// request, a concurrent thread — finds status ≠ 'approved' and is refused, so a side effect
+    /// can never fire twice.
+    pub fn claim_tool_execution(&self, call_id: &str) -> Result<(), String> {
+        let n = self
+            .conn
+            .execute("UPDATE tool_calls SET status = 'executing' WHERE call_id = ?1 AND status = 'approved'", params![call_id])
+            .map_err(|e| e.to_string())?;
+        if n != 1 {
+            return Err(format!("tool call {call_id} is not approved for execution"));
+        }
+        Ok(())
+    }
+
+    pub fn finish_tool_call(
+        &self,
+        call_id: &str,
+        ok: bool,
+        result_artifact_id: Option<&str>,
+        result_preview: &str,
+        error: Option<&str>,
+        now_ms: i64,
+    ) -> Result<(), String> {
+        let n = self
+            .conn
+            .execute(
+                "UPDATE tool_calls SET status = ?2, result_artifact_id = ?3, result_preview = ?4, error = ?5,
+                                       executed_ms = ?6
+                 WHERE call_id = ?1 AND status = 'executing'",
+                params![call_id, if ok { "executed" } else { "failed" }, result_artifact_id, result_preview, error, now_ms],
+            )
+            .map_err(|e| e.to_string())?;
+        if n != 1 {
+            return Err(format!("tool call {call_id} was not executing"));
+        }
+        Ok(())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn store_at(name: &str) -> SessionStore {
+        let dir = std::env::temp_dir().join(format!("palw-gw-test-{}-{name}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        SessionStore::open(&dir.join("s.sqlite3")).unwrap()
+    }
+
+    fn complete(s: &SessionStore, turn_id: &str, output_ids: &[u32], status: TurnVerificationStatus) {
+        s.complete_turn(&CompletedTurn {
+            turn_id,
+            output_ids,
+            display_text: "ok",
+            stop_reason: "eos",
+            status,
+            receipt_json: None,
+            runtime_roots_json: None,
+        })
+        .unwrap();
+    }
+
+    fn new_turn<'a>(
+        turn_id: &'a str,
+        conversation_id: &'a str,
+        parent: Option<&'a str>,
+        text: &'a str,
+        prompt_ids: &'a [u32],
+        privacy: TurnPrivacyMode,
+        now: i64,
+    ) -> NewTurn<'a> {
+        NewTurn {
+            turn_id,
+            conversation_id,
+            parent_turn_id: parent,
+            role_user_text: text,
+            user_block_text: text,
+            context_meta_json: None,
+            prompt_ids,
+            privacy_mode: privacy,
+            search_bundle_json: None,
+            now_ms: now,
+        }
+    }
+
+    #[test]
+    fn ids_roundtrip_and_branching() {
+        let mut s = store_at("branch");
+        s.create_conversation("c1", "t", None, 1).unwrap();
+        s.begin_turn(&new_turn("t1", "c1", None, "hello", &[1, 2, 3], TurnPrivacyMode::LocalOnly, 2)).unwrap();
+        complete(&s, "t1", &[9, 8], TurnVerificationStatus::LocalComplete);
+        s.begin_turn(&new_turn("t2", "c1", Some("t1"), "next", &[1, 2, 3, 9, 8, 4], TurnPrivacyMode::LocalOnly, 3))
+            .unwrap();
+        complete(&s, "t2", &[7], TurnVerificationStatus::LocalComplete);
+
+        // Branch: edit turn 2 — sibling under t1, head moves, t2 stays intact.
+        s.begin_turn(&new_turn("t2b", "c1", Some("t1"), "next-edited", &[1, 2, 3, 9, 8, 5], TurnPrivacyMode::LocalOnly, 4))
+            .unwrap();
+        let heads = s.heads("c1").unwrap();
+        assert_eq!(heads.local_head.as_deref(), Some("t2b"));
+        assert_eq!(heads.certified_head, None);
+
+        let hist = s.branch_history("t2b").unwrap();
+        assert_eq!(hist.iter().map(|t| t.turn_id.as_str()).collect::<Vec<_>>(), vec!["t1", "t2b"]);
+        // Token ids survive exactly — the id-stable-history invariant.
+        assert_eq!(hist[0].output_ids, vec![9, 8]);
+        let old = s.branch_history("t2").unwrap();
+        assert_eq!(old.len(), 2);
+        assert_eq!(old[1].prompt_ids, vec![1, 2, 3, 9, 8, 4]);
+    }
+
+    /// A database created by the v1 gateway must open, migrate, and keep serving byte-identical
+    /// history — `user_block_text` NULL folds back to the raw user text.
+    #[test]
+    fn migrates_v1_database_in_place() {
+        let dir = std::env::temp_dir().join(format!("palw-gw-test-{}-migrate", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        std::fs::create_dir_all(&dir).unwrap();
+        let path = dir.join("s.sqlite3");
+        {
+            // The v1 DDL, verbatim from the Phase-0 store.
+            let conn = Connection::open(&path).unwrap();
+            conn.pragma_update(None, "application_id", APPLICATION_ID).unwrap();
+            conn.execute_batch(
+                r#"
+                CREATE TABLE conversations (
+                    conversation_id TEXT PRIMARY KEY,
+                    title           TEXT NOT NULL DEFAULT '',
+                    local_head      TEXT,
+                    certified_head  TEXT,
+                    created_ms      INTEGER NOT NULL,
+                    updated_ms      INTEGER NOT NULL
+                );
+                CREATE TABLE turns (
+                    turn_id             TEXT PRIMARY KEY,
+                    conversation_id     TEXT NOT NULL REFERENCES conversations(conversation_id),
+                    parent_turn_id      TEXT REFERENCES turns(turn_id),
+                    role_user_text      TEXT NOT NULL,
+                    display_text        TEXT NOT NULL DEFAULT '',
+                    prompt_ids          BLOB NOT NULL,
+                    output_ids          BLOB NOT NULL DEFAULT x'',
+                    stop_reason         TEXT,
+                    verification_status TEXT NOT NULL,
+                    privacy_mode        TEXT NOT NULL,
+                    receipt_json        TEXT,
+                    created_ms          INTEGER NOT NULL
+                );
+                CREATE INDEX turns_by_conversation ON turns(conversation_id, created_ms);
+                CREATE TABLE artifacts (
+                    artifact_id   TEXT PRIMARY KEY,
+                    content_hash  TEXT NOT NULL,
+                    mime_type     TEXT NOT NULL,
+                    byte_length   INTEGER NOT NULL,
+                    created_by_turn TEXT REFERENCES turns(turn_id),
+                    created_ms    INTEGER NOT NULL
+                );
+                PRAGMA user_version = 1;
+                "#,
+            )
+            .unwrap();
+            conn.execute(
+                "INSERT INTO conversations (conversation_id, title, local_head, created_ms, updated_ms)
+                 VALUES ('c1', 'old', 't1', 1, 1)",
+                [],
+            )
+            .unwrap();
+            conn.execute(
+                "INSERT INTO turns (turn_id, conversation_id, role_user_text, prompt_ids, output_ids,
+                                    verification_status, privacy_mode, created_ms)
+                 VALUES ('t1', 'c1', 'hello', x'01000000', x'02000000', 'local_complete', 'local_only', 1)",
+                [],
+            )
+            .unwrap();
+        }
+
+        let s = SessionStore::open(&path).unwrap();
+        let turn = s.get_turn("t1").unwrap();
+        assert_eq!(turn.user_block_text, None);
+        assert_eq!(turn.user_block(), "hello");
+        assert_eq!(turn.prompt_ids, vec![1]);
+        assert_eq!(turn.output_ids, vec![2]);
+        assert_eq!(turn.search_bundle_json, None, "v4 column readable on migrated rows");
+        // v2 tables exist and take writes after migration.
+        s.create_project("p1", "proj", "", 2).unwrap();
+        s.add_memory("m1", "global", "fact", None, 2).unwrap();
+        let version: i64 = s
+            .conn
+            .query_row("PRAGMA user_version", [], |r| r.get(0))
+            .unwrap();
+        assert_eq!(version, SCHEMA_VERSION);
+    }
+
+    #[test]
+    fn search_bundle_persists_from_begin_turn() {
+        let mut s = store_at("search-bundle");
+        s.create_conversation("c1", "t", None, 1).unwrap();
+        let mut turn = new_turn("t1", "c1", None, "q", &[1], TurnPrivacyMode::PalwMint, 1);
+        turn.search_bundle_json = Some(r#"{"bundle_sha256":"abc"}"#);
+        s.begin_turn(&turn).unwrap();
+        assert_eq!(s.get_turn("t1").unwrap().search_bundle_json.as_deref(), Some(r#"{"bundle_sha256":"abc"}"#));
+    }
+
+    #[test]
+    fn memory_soft_delete_and_namespace_order() {
+        let s = store_at("memory");
+        s.add_memory("m1", "global", "a", None, 1).unwrap();
+        s.add_memory("m2", "proj-1", "b", None, 2).unwrap();
+        s.add_memory("m3", "global", "c", None, 3).unwrap();
+        s.delete_memory("m1").unwrap();
+        assert!(s.delete_memory("m1").is_err(), "double tombstone must be refused");
+
+        let active = s.active_memory(&["global", "proj-1"]).unwrap();
+        assert_eq!(active.iter().map(|m| m.memory_id.as_str()).collect::<Vec<_>>(), vec!["m2", "m3"]);
+        let global_only = s.active_memory(&["global"]).unwrap();
+        assert_eq!(global_only.iter().map(|m| m.memory_id.as_str()).collect::<Vec<_>>(), vec!["m3"]);
+    }
+
+    #[test]
+    fn artifact_versions_are_derived() {
+        let s = store_at("artifacts");
+        let base = ArtifactMeta {
+            artifact_id: "a1".into(),
+            content_hash: "h1".into(),
+            mime_type: "text/markdown".into(),
+            byte_length: 3,
+            display_name: "design.md".into(),
+            parent_artifact_id: None,
+            version: 99, // caller-supplied versions are ignored
+            parser_policy: "utf8-text-v1".into(),
+            project_id: None,
+            created_by_turn: None,
+            created_ms: 1,
+        };
+        assert_eq!(s.insert_artifact(&base).unwrap(), 1);
+        let v2 = ArtifactMeta { artifact_id: "a2".into(), content_hash: "h2".into(), parent_artifact_id: Some("a1".into()), created_ms: 2, ..base.clone() };
+        assert_eq!(s.insert_artifact(&v2).unwrap(), 2);
+        let v3 = ArtifactMeta { artifact_id: "a3".into(), content_hash: "h3".into(), parent_artifact_id: Some("a2".into()), created_ms: 3, ..base.clone() };
+        assert_eq!(s.insert_artifact(&v3).unwrap(), 3);
+
+        let lineage = s.artifact_lineage("a3").unwrap();
+        assert_eq!(lineage.iter().map(|a| a.artifact_id.as_str()).collect::<Vec<_>>(), vec!["a1", "a2", "a3"]);
+        assert_eq!(lineage.iter().map(|a| a.version).collect::<Vec<_>>(), vec![1, 2, 3]);
+        let children = s.artifact_children("a1").unwrap();
+        assert_eq!(children.len(), 1);
+        assert_eq!(children[0].artifact_id, "a2");
+    }
+
+    #[test]
+    fn tool_call_exactly_once_guard() {
+        let s = store_at("tools");
+        let call = ToolCallRow {
+            call_id: "call1".into(),
+            tool_name: "write_file".into(),
+            mode: "exactly_once_side_effect".into(),
+            arguments_json: "{}".into(),
+            status: "proposed".into(),
+            result_artifact_id: None,
+            result_preview: String::new(),
+            error: None,
+            conversation_id: None,
+            created_ms: 1,
+            executed_ms: None,
+        };
+        s.insert_tool_call(&call).unwrap();
+        assert!(s.claim_tool_execution("call1").is_err(), "unapproved call must not execute");
+        s.approve_tool_call("call1").unwrap();
+        assert!(s.approve_tool_call("call1").is_err(), "double approval refused");
+        s.claim_tool_execution("call1").unwrap();
+        assert!(s.claim_tool_execution("call1").is_err(), "second claim refused — exactly once");
+        s.finish_tool_call("call1", true, None, "ok", None, 2).unwrap();
+        assert_eq!(s.get_tool_call("call1").unwrap().status, "executed");
+
+        // A denied proposal is terminal.
+        s.insert_tool_call(&ToolCallRow { call_id: "call2".into(), ..call.clone() }).unwrap();
+        s.deny_tool_call("call2").unwrap();
+        assert!(s.approve_tool_call("call2").is_err());
+    }
+
+    #[test]
+    fn verification_pipeline_certifies_and_cascades() {
+        use TurnVerificationStatus::*;
+        let mut s = store_at("verify");
+        s.create_conversation("c1", "t", None, 1).unwrap();
+        for (id, parent, n) in [("t1", None, 2i64), ("t2", Some("t1"), 3), ("t3", Some("t2"), 4)] {
+            s.begin_turn(&new_turn(id, "c1", parent, "m", &[1], TurnPrivacyMode::PalwMint, n)).unwrap();
+            complete(&s, id, &[2], LocalComplete);
+        }
+
+        // LocalOnly turns can never enter the pipeline.
+        s.begin_turn(&new_turn("t4", "c1", Some("t3"), "m", &[1], TurnPrivacyMode::LocalOnly, 5)).unwrap();
+        complete(&s, "t4", &[2], LocalComplete);
+        assert!(s.set_verification_status("t4", ReplicaPending, 6).is_err());
+        // Put the head back on t3's line for the cascade check below.
+        s.set_local_head("c1", "t3", 6).unwrap();
+
+        // Out-of-order settlement: t2 certifies before t1 — certified_head must NOT move.
+        for id in ["t1", "t2", "t3"] {
+            s.set_verification_status(id, ReplicaPending, 7).unwrap();
+        }
+        s.set_verification_status("t2", ReplicaMatched, 8).unwrap();
+        let out = s.set_verification_status("t2", Certified, 8).unwrap();
+        assert_eq!(out.certified_head, None, "gap at t1 — no certified prefix yet");
+
+        s.set_verification_status("t1", ReplicaMatched, 9).unwrap();
+        s.set_verification_status("t1", AuditPending, 9).unwrap();
+        let out = s.set_verification_status("t1", Certified, 9).unwrap();
+        assert_eq!(out.certified_head.as_deref(), Some("t2"), "prefix t1..t2 now contiguous");
+
+        // Illegal jumps are refused.
+        assert!(s.set_verification_status("t3", Certified, 10).is_err());
+
+        // Mismatch at t3: its only descendant is the LocalOnly t4, which also leaves the reward
+        // pipeline (it was never eligible; the cascade makes that explicit).
+        let out = s.set_verification_status("t3", Mismatch, 11).unwrap();
+        assert_eq!(out.cascaded, vec!["t4"]);
+        assert_eq!(out.certified_head.as_deref(), Some("t2"), "certified prefix survives a later mismatch");
+
+        // A mismatched turn is terminal.
+        assert!(s.set_verification_status("t3", ReplicaMatched, 12).is_err());
+        assert!(s.set_verification_status("t3", MintIneligible, 12).is_err());
+    }
+
+    #[test]
+    fn mismatch_cascade_invalidates_descendants() {
+        use TurnVerificationStatus::*;
+        let mut s = store_at("cascade");
+        s.create_conversation("c1", "t", None, 1).unwrap();
+        // t1 ← t2 ← t3, plus a sibling branch t2b under t1.
+        for (id, parent, n) in [("t1", None, 2i64), ("t2", Some("t1"), 3), ("t3", Some("t2"), 4), ("t2b", Some("t1"), 5)] {
+            s.begin_turn(&new_turn(id, "c1", parent, "m", &[1], TurnPrivacyMode::PalwMint, n)).unwrap();
+            complete(&s, id, &[2], LocalComplete);
+        }
+        s.set_verification_status("t1", ReplicaPending, 6).unwrap();
+        let out = s.set_verification_status("t1", Mismatch, 7).unwrap();
+        let mut cascaded = out.cascaded.clone();
+        cascaded.sort();
+        assert_eq!(cascaded, vec!["t2", "t2b", "t3"], "every descendant leaves the reward pipeline");
+        assert_eq!(s.get_turn("t2").unwrap().verification_status, MintIneligible);
+        assert_eq!(s.get_turn("t3").unwrap().verification_status, MintIneligible);
+        assert_eq!(s.get_turn("t2b").unwrap().verification_status, MintIneligible);
+        // Local conversation survives: rows still exist with their text.
+        assert_eq!(s.get_turn("t3").unwrap().display_text, "ok");
+    }
+}

palw-gateway/src/tokenizer.rs

@@ -0,0 +1,98 @@
+//! Tokenizer host: the pinned `tokenizer.json`, the `encode_lossless` invariant carried over
+//! from `qi35_chat.py`, and the incremental stream decoder (stable-tail hold-back) so SSE
+//! deltas never emit a half-open UTF-8/BPE boundary.
+
+use tokenizers::Tokenizer;
+
+pub struct TokenizerHost {
+    inner: Tokenizer,
+    pub eos_id: u32,
+    pub digest_hex: String,
+}
+
+impl TokenizerHost {
+    pub fn load(path: &std::path::Path, eos_id: u32) -> Result<Self, String> {
+        let bytes = std::fs::read(path).map_err(|e| format!("read {}: {e}", path.display()))?;
+        let digest_hex = {
+            use blake2::{Blake2b, Digest, digest::consts::U32};
+            let mut h = Blake2b::<U32>::new();
+            h.update(&bytes);
+            hex::encode(h.finalize())
+        };
+        let inner = Tokenizer::from_bytes(&bytes).map_err(|e| format!("tokenizer {}: {e}", path.display()))?;
+        Ok(Self { inner, eos_id, digest_hex })
+    }
+
+    /// Encode with the qi35 invariant: the encoding must decode back to the exact input string,
+    /// or we refuse — a prompt we cannot commit losslessly must never reach the engine.
+    pub fn encode_lossless(&self, text: &str) -> Result<Vec<u32>, String> {
+        let enc = self.inner.encode(text, false).map_err(|e| format!("encode: {e}"))?;
+        let ids: Vec<u32> = enc.get_ids().to_vec();
+        let back = self.decode(&ids)?;
+        if back != text {
+            return Err(format!("encode is not lossless for this input ({} chars in, {} chars back)", text.len(), back.len()));
+        }
+        Ok(ids)
+    }
+
+    pub fn decode(&self, ids: &[u32]) -> Result<String, String> {
+        // skip_special_tokens = false: ChatML markers must round-trip for encode_lossless.
+        self.inner.decode(ids, false).map_err(|e| format!("decode: {e}"))
+    }
+
+    /// Decode for DISPLAY: special tokens dropped (an EOS at the end of a stored answer must
+    /// not render as `<|im_end|>` in the UI).
+    pub fn decode_display(&self, ids: &[u32]) -> Result<String, String> {
+        self.inner.decode(ids, true).map_err(|e| format!("decode: {e}"))
+    }
+}
+
+/// Streaming detokenizer with the stable-tail trick from `qi35_chat.py`'s IncrementalDecoder:
+/// re-decode the full generated id list each token, but only emit up to `HOLD_BACK` characters
+/// before the end — the held tail may still change while a multi-token grapheme or BPE merge is
+/// open, the earlier prefix cannot.
+pub struct IncrementalDecoder {
+    ids: Vec<u32>,
+    emitted_chars: usize,
+}
+
+const HOLD_BACK: usize = 8;
+
+impl IncrementalDecoder {
+    pub fn new() -> Self {
+        Self { ids: Vec::new(), emitted_chars: 0 }
+    }
+
+    /// Push one generated token; returns the newly-stable UTF-8 delta (possibly empty).
+    pub fn push(&mut self, host: &TokenizerHost, token_id: u32) -> Result<String, String> {
+        self.ids.push(token_id);
+        let full = host.decode_display(&self.ids)?;
+        let chars: Vec<char> = full.chars().collect();
+        let stable_end = chars.len().saturating_sub(HOLD_BACK);
+        if stable_end <= self.emitted_chars {
+            return Ok(String::new());
+        }
+        let delta: String = chars[self.emitted_chars..stable_end].iter().collect();
+        self.emitted_chars = stable_end;
+        Ok(delta)
+    }
+
+    /// Flush the held tail at end of generation.
+    pub fn finish(&mut self, host: &TokenizerHost) -> Result<String, String> {
+        let full = host.decode_display(&self.ids)?;
+        let chars: Vec<char> = full.chars().collect();
+        if chars.len() <= self.emitted_chars {
+            return Ok(String::new());
+        }
+        let delta: String = chars[self.emitted_chars..].iter().collect();
+        self.emitted_chars = chars.len();
+        Ok(delta)
+    }
+}
+
+// Minimal local hex (avoids another dependency).
+mod hex {
+    pub fn encode(bytes: impl AsRef<[u8]>) -> String {
+        bytes.as_ref().iter().map(|b| format!("{b:02x}")).collect()
+    }
+}

palw-gateway/src/tools.rs

@@ -0,0 +1,572 @@
+//! Tool Runtime + sandbox (design doc §6 / §17).
+//!
+//! The doc's three-way split is the load-bearing structure:
+//! * `DeterministicReplay` — pure functions of their arguments (calculator). A and B can both
+//!   re-run them; no snapshot is strictly needed but we snapshot anyway for a uniform ledger.
+//! * `SnapshotReadOnly` — reads of external state (filesystem here; web/db later). Executed by
+//!   A once, result content-addressed; B reads the snapshot, never re-reads the world. PALW then
+//!   attests "answered FROM this data", not "this data is true".
+//! * `ExactlyOnceSideEffect` — writes to the world. Never auto-executed: the call is stored as
+//!   `proposed`, the user approves (§6 step 2 — over this gateway's API the approval is an
+//!   explicit second request), and the store's `claim_tool_execution` UPDATE is the exactly-once
+//!   ticket. B replicas read the proposal and the result snapshot; they never re-fire.
+//!
+//! Sandbox (§17): read scope = workspace + explicitly configured readable roots, write scope =
+//! the workspace only, `run_command` = an ABSOLUTE-PATH allowlist (no PATH lookup, so what runs
+//! is exactly what the operator listed), cleared child environment (secret 遮断 — the gateway's
+//! env never leaks into tools), wall-clock timeout, output byte cap. Paths are canonicalized
+//! before the scope check, so symlinks cannot escape. v1 limitation, stated honestly: there is
+//! no kernel-level network isolation for spawned commands — the allowlist IS the network policy
+//! (list only binaries that do not reach the network if that matters to you).
+
+use std::path::{Component, Path, PathBuf};
+use std::time::{Duration, Instant};
+
+use serde_json::Value;
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum ToolExecutionMode {
+    DeterministicReplay,
+    SnapshotReadOnly,
+    ExactlyOnceSideEffect,
+}
+
+impl ToolExecutionMode {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::DeterministicReplay => "deterministic_replay",
+            Self::SnapshotReadOnly => "snapshot_read_only",
+            Self::ExactlyOnceSideEffect => "exactly_once_side_effect",
+        }
+    }
+}
+
+#[derive(Clone, Debug)]
+pub struct ToolSandboxPolicyV1 {
+    /// Canonicalized. The write scope, `run_command`'s cwd, and the base for relative reads.
+    pub workspace_root: PathBuf,
+    /// Canonicalized, read-only. The workspace is always readable in addition to these.
+    pub readable_roots: Vec<PathBuf>,
+    /// Absolute binary paths; `run_command` refuses anything not EXACTLY in this list.
+    pub allowed_commands: Vec<PathBuf>,
+    pub max_runtime_ms: u64,
+    pub max_output_bytes: usize,
+    pub max_read_bytes: u64,
+}
+
+impl ToolSandboxPolicyV1 {
+    pub fn new(
+        workspace: &Path,
+        readable: &[PathBuf],
+        allowed_commands: &[PathBuf],
+        max_runtime_ms: u64,
+        max_output_bytes: usize,
+        max_read_bytes: u64,
+    ) -> Result<Self, String> {
+        std::fs::create_dir_all(workspace).map_err(|e| format!("create workspace {}: {e}", workspace.display()))?;
+        let workspace_root =
+            std::fs::canonicalize(workspace).map_err(|e| format!("canonicalize {}: {e}", workspace.display()))?;
+        let mut readable_roots = Vec::new();
+        for r in readable {
+            readable_roots.push(std::fs::canonicalize(r).map_err(|e| format!("readable root {}: {e}", r.display()))?);
+        }
+        for c in allowed_commands {
+            if !c.is_absolute() {
+                return Err(format!("allowed command must be an absolute path: {}", c.display()));
+            }
+            if !c.is_file() {
+                return Err(format!("allowed command does not exist: {}", c.display()));
+            }
+        }
+        Ok(Self {
+            workspace_root,
+            readable_roots,
+            allowed_commands: allowed_commands.to_vec(),
+            max_runtime_ms,
+            max_output_bytes,
+            max_read_bytes,
+        })
+    }
+}
+
+pub struct ToolOutcome {
+    /// Canonical result bytes — what gets content-addressed and (for mint turns) handed to B.
+    pub output: Vec<u8>,
+    pub mime: &'static str,
+    /// Short human-readable form for the tool-call ledger row.
+    pub preview: String,
+}
+
+pub struct ToolRuntime {
+    pub policy: ToolSandboxPolicyV1,
+}
+
+pub const TOOLS: &[(&str, ToolExecutionMode, &str)] = &[
+    ("calculator", ToolExecutionMode::DeterministicReplay, "exact i128 integer arithmetic: + - * / % and parentheses; / must divide exactly"),
+    ("read_file", ToolExecutionMode::SnapshotReadOnly, "read a file inside the readable scope; result is snapshotted"),
+    ("list_dir", ToolExecutionMode::SnapshotReadOnly, "list a directory inside the readable scope, sorted"),
+    ("write_file", ToolExecutionMode::ExactlyOnceSideEffect, "write a workspace-relative file (requires approval)"),
+    ("run_command", ToolExecutionMode::ExactlyOnceSideEffect, "run an allowlisted binary in the workspace (requires approval)"),
+];
+
+pub fn mode_of(tool: &str) -> Option<ToolExecutionMode> {
+    TOOLS.iter().find(|(name, _, _)| *name == tool).map(|(_, mode, _)| *mode)
+}
+
+fn preview_of(text: &str) -> String {
+    const MAX: usize = 400;
+    if text.chars().count() <= MAX {
+        text.to_string()
+    } else {
+        let cut: String = text.chars().take(MAX).collect();
+        format!("{cut}…")
+    }
+}
+
+fn arg_str<'a>(args: &'a Value, key: &str) -> Result<&'a str, String> {
+    args.get(key).and_then(|v| v.as_str()).ok_or_else(|| format!("missing string argument {key:?}"))
+}
+
+impl ToolRuntime {
+    pub fn new(policy: ToolSandboxPolicyV1) -> Self {
+        Self { policy }
+    }
+
+    /// Execute a tool NOW. The caller is responsible for the mode gate: side-effect tools reach
+    /// this only through the store's approved→executing claim.
+    pub fn execute(&self, tool: &str, args: &Value) -> Result<ToolOutcome, String> {
+        match tool {
+            "calculator" => self.calculator(args),
+            "read_file" => self.read_file(args),
+            "list_dir" => self.list_dir(args),
+            "write_file" => self.write_file(args),
+            "run_command" => self.run_command(args),
+            other => Err(format!("unknown tool {other:?}")),
+        }
+    }
+
+    // ---- path scope ---------------------------------------------------------------------
+
+    /// Resolve a read path: relative ⇒ workspace-joined; then canonicalize (symlinks resolve
+    /// HERE, before the scope check) and require the result inside workspace or a readable root.
+    fn resolve_readable(&self, path: &str) -> Result<PathBuf, String> {
+        let joined =
+            if Path::new(path).is_absolute() { PathBuf::from(path) } else { self.policy.workspace_root.join(path) };
+        let canon = std::fs::canonicalize(&joined).map_err(|e| format!("{path:?}: {e}"))?;
+        let in_scope = canon.starts_with(&self.policy.workspace_root)
+            || self.policy.readable_roots.iter().any(|r| canon.starts_with(r));
+        if !in_scope {
+            return Err(format!("{path:?} resolves outside the readable scope"));
+        }
+        Ok(canon)
+    }
+
+    /// Validate a WRITE path: must be relative, no `..`/root components; the (created) parent
+    /// must canonicalize back inside the workspace, so a symlinked subdirectory cannot redirect
+    /// the write outside.
+    fn resolve_writable(&self, path: &str) -> Result<PathBuf, String> {
+        let p = Path::new(path);
+        if p.is_absolute() {
+            return Err("write paths must be workspace-relative".into());
+        }
+        if p.components().any(|c| !matches!(c, Component::Normal(_) | Component::CurDir)) {
+            return Err("write paths may not contain '..' or root components".into());
+        }
+        if p.as_os_str().is_empty() {
+            return Err("empty write path".into());
+        }
+        let target = self.policy.workspace_root.join(p);
+        let parent = target.parent().ok_or("write path has no parent")?;
+        std::fs::create_dir_all(parent).map_err(|e| format!("create {}: {e}", parent.display()))?;
+        let canon_parent = std::fs::canonicalize(parent).map_err(|e| format!("canonicalize {}: {e}", parent.display()))?;
+        if !canon_parent.starts_with(&self.policy.workspace_root) {
+            return Err(format!("{path:?} escapes the workspace through a symlinked directory"));
+        }
+        let file_name = target.file_name().ok_or("write path has no file name")?;
+        Ok(canon_parent.join(file_name))
+    }
+
+    // ---- tools --------------------------------------------------------------------------
+
+    fn calculator(&self, args: &Value) -> Result<ToolOutcome, String> {
+        let expression = arg_str(args, "expression")?;
+        let value = calc_eval(expression)?;
+        let text = value.to_string();
+        Ok(ToolOutcome { preview: preview_of(&text), output: text.into_bytes(), mime: "text/plain" })
+    }
+
+    fn read_file(&self, args: &Value) -> Result<ToolOutcome, String> {
+        let path = arg_str(args, "path")?;
+        let canon = self.resolve_readable(path)?;
+        let len = std::fs::metadata(&canon).map_err(|e| format!("{path:?}: {e}"))?.len();
+        if len > self.policy.max_read_bytes {
+            return Err(format!("{path:?} is {len} bytes — over the {}-byte read cap", self.policy.max_read_bytes));
+        }
+        let bytes = std::fs::read(&canon).map_err(|e| format!("{path:?}: {e}"))?;
+        let preview = match std::str::from_utf8(&bytes) {
+            Ok(text) => preview_of(text),
+            Err(_) => format!("({len} binary bytes)"),
+        };
+        Ok(ToolOutcome { output: bytes, mime: "application/octet-stream", preview })
+    }
+
+    fn list_dir(&self, args: &Value) -> Result<ToolOutcome, String> {
+        let path = arg_str(args, "path")?;
+        let canon = self.resolve_readable(path)?;
+        let mut lines = Vec::new();
+        for entry in std::fs::read_dir(&canon).map_err(|e| format!("{path:?}: {e}"))? {
+            let entry = entry.map_err(|e| e.to_string())?;
+            let name = entry.file_name().to_string_lossy().into_owned();
+            let meta = entry.metadata().map_err(|e| e.to_string())?;
+            let kind = if meta.is_dir() { "dir" } else { "file" };
+            lines.push(format!("{name}\t{kind}\t{}", if meta.is_dir() { 0 } else { meta.len() }));
+        }
+        lines.sort(); // deterministic listing — read_dir order is filesystem-dependent
+        let text = lines.join("\n");
+        Ok(ToolOutcome { preview: preview_of(&text), output: text.into_bytes(), mime: "text/plain" })
+    }
+
+    fn write_file(&self, args: &Value) -> Result<ToolOutcome, String> {
+        let path = arg_str(args, "path")?;
+        let content = arg_str(args, "content")?;
+        let target = self.resolve_writable(path)?;
+        std::fs::write(&target, content.as_bytes()).map_err(|e| format!("write {path:?}: {e}"))?;
+        let hash = crate::artifact::content_hash_hex(content.as_bytes());
+        let text = format!("wrote {} bytes to {path}\ncontent blake2b-256 {hash}", content.len());
+        Ok(ToolOutcome { preview: preview_of(&text), output: text.into_bytes(), mime: "text/plain" })
+    }
+
+    fn run_command(&self, args: &Value) -> Result<ToolOutcome, String> {
+        let command = arg_str(args, "command")?;
+        let argv: Vec<String> = match args.get("args") {
+            None => Vec::new(),
+            Some(Value::Array(items)) => items
+                .iter()
+                .map(|v| v.as_str().map(String::from).ok_or_else(|| "args must be strings".to_string()))
+                .collect::<Result<_, _>>()?,
+            Some(_) => return Err("args must be an array of strings".into()),
+        };
+        let command_path = Path::new(command);
+        if !self.policy.allowed_commands.iter().any(|allowed| allowed == command_path) {
+            return Err(format!("{command:?} is not on the command allowlist"));
+        }
+
+        // Cleared environment: the gateway's env (tokens, keys) never reaches a tool child.
+        // PATH is pinned so anything the child itself spawns is at least system-scoped, and
+        // LC_ALL=C keeps tool output locale-independent (deterministic snapshots).
+        let mut child = std::process::Command::new(command_path)
+            .args(&argv)
+            .current_dir(&self.policy.workspace_root)
+            .env_clear()
+            .env("PATH", "/usr/bin:/bin")
+            .env("LC_ALL", "C")
+            .stdin(std::process::Stdio::null())
+            .stdout(std::process::Stdio::piped())
+            .stderr(std::process::Stdio::piped())
+            .spawn()
+            .map_err(|e| format!("spawn {command}: {e}"))?;
+
+        let cap = self.policy.max_output_bytes;
+        let stdout = child.stdout.take().expect("piped");
+        let stderr = child.stderr.take().expect("piped");
+        let out_reader = std::thread::spawn(move || read_capped(stdout, cap));
+        let err_reader = std::thread::spawn(move || read_capped(stderr, cap));
+
+        let deadline = Instant::now() + Duration::from_millis(self.policy.max_runtime_ms);
+        let mut timed_out = false;
+        let status = loop {
+            match child.try_wait().map_err(|e| e.to_string())? {
+                Some(status) => break Some(status),
+                None if Instant::now() >= deadline => {
+                    let _ = child.kill();
+                    let _ = child.wait();
+                    timed_out = true;
+                    break None;
+                }
+                None => std::thread::sleep(Duration::from_millis(10)),
+            }
+        };
+        let (stdout_bytes, stdout_truncated) = out_reader.join().map_err(|_| "stdout reader panicked")?;
+        let (stderr_bytes, stderr_truncated) = err_reader.join().map_err(|_| "stderr reader panicked")?;
+
+        let exit = if timed_out {
+            format!("timeout after {}ms", self.policy.max_runtime_ms)
+        } else {
+            match status.and_then(|s| s.code()) {
+                Some(code) => format!("exit {code}"),
+                None => "killed by signal".into(),
+            }
+        };
+        let mut text = format!("{exit}\n--- stdout ---\n");
+        text.push_str(&String::from_utf8_lossy(&stdout_bytes));
+        if stdout_truncated {
+            text.push_str("\n[stdout truncated]");
+        }
+        text.push_str("\n--- stderr ---\n");
+        text.push_str(&String::from_utf8_lossy(&stderr_bytes));
+        if stderr_truncated {
+            text.push_str("\n[stderr truncated]");
+        }
+        Ok(ToolOutcome { preview: preview_of(&text), output: text.into_bytes(), mime: "text/plain" })
+    }
+}
+
+/// Read a pipe to EOF, keeping at most `cap` bytes. Draining past the cap (instead of stopping)
+/// keeps the child from blocking on a full pipe after we stop caring.
+fn read_capped(mut reader: impl std::io::Read, cap: usize) -> (Vec<u8>, bool) {
+    let mut kept = Vec::new();
+    let mut truncated = false;
+    let mut buf = [0u8; 8192];
+    loop {
+        match reader.read(&mut buf) {
+            Ok(0) | Err(_) => break,
+            Ok(n) => {
+                if kept.len() < cap {
+                    let take = n.min(cap - kept.len());
+                    kept.extend_from_slice(&buf[..take]);
+                    if take < n {
+                        truncated = true;
+                    }
+                } else {
+                    truncated = true;
+                }
+            }
+        }
+    }
+    (kept, truncated)
+}
+
+// ---- calculator (DeterministicReplay) ---------------------------------------------------
+//
+// Exact i128 integer arithmetic, checked everywhere: overflow, division by zero, and inexact
+// division are ERRORS, never wrapped or rounded — a deterministic-replay tool must have exactly
+// one right answer on every input, on every machine.
+
+const CALC_MAX_LEN: usize = 4096;
+const CALC_MAX_DEPTH: u32 = 64;
+
+struct CalcParser<'a> {
+    bytes: &'a [u8],
+    pos: usize,
+}
+
+pub fn calc_eval(expression: &str) -> Result<i128, String> {
+    if expression.len() > CALC_MAX_LEN {
+        return Err(format!("expression longer than {CALC_MAX_LEN} bytes"));
+    }
+    let mut p = CalcParser { bytes: expression.as_bytes(), pos: 0 };
+    let v = p.expr(0)?;
+    p.skip_ws();
+    if p.pos != p.bytes.len() {
+        return Err(format!("unexpected trailing input at byte {}", p.pos));
+    }
+    Ok(v)
+}
+
+impl<'a> CalcParser<'a> {
+    fn skip_ws(&mut self) {
+        while self.bytes.get(self.pos) == Some(&b' ') {
+            self.pos += 1;
+        }
+    }
+
+    fn peek(&mut self) -> Option<u8> {
+        self.skip_ws();
+        self.bytes.get(self.pos).copied()
+    }
+
+    fn expr(&mut self, depth: u32) -> Result<i128, String> {
+        let mut acc = self.term(depth)?;
+        loop {
+            match self.peek() {
+                Some(b'+') => {
+                    self.pos += 1;
+                    let rhs = self.term(depth)?;
+                    acc = acc.checked_add(rhs).ok_or("overflow in +")?;
+                }
+                Some(b'-') => {
+                    self.pos += 1;
+                    let rhs = self.term(depth)?;
+                    acc = acc.checked_sub(rhs).ok_or("overflow in -")?;
+                }
+                _ => return Ok(acc),
+            }
+        }
+    }
+
+    fn term(&mut self, depth: u32) -> Result<i128, String> {
+        let mut acc = self.factor(depth)?;
+        loop {
+            match self.peek() {
+                Some(b'*') => {
+                    self.pos += 1;
+                    let rhs = self.factor(depth)?;
+                    acc = acc.checked_mul(rhs).ok_or("overflow in *")?;
+                }
+                Some(b'/') => {
+                    self.pos += 1;
+                    let rhs = self.factor(depth)?;
+                    if rhs == 0 {
+                        return Err("division by zero".into());
+                    }
+                    let rem = acc.checked_rem(rhs).ok_or("overflow in /")?;
+                    if rem != 0 {
+                        return Err(format!("{acc}/{rhs} is not exact — integer calculator refuses to round"));
+                    }
+                    acc = acc.checked_div(rhs).ok_or("overflow in /")?;
+                }
+                Some(b'%') => {
+                    self.pos += 1;
+                    let rhs = self.factor(depth)?;
+                    if rhs == 0 {
+                        return Err("modulo by zero".into());
+                    }
+                    acc = acc.checked_rem(rhs).ok_or("overflow in %")?;
+                }
+                _ => return Ok(acc),
+            }
+        }
+    }
+
+    fn factor(&mut self, depth: u32) -> Result<i128, String> {
+        if depth > CALC_MAX_DEPTH {
+            return Err("expression nests too deep".into());
+        }
+        match self.peek() {
+            Some(b'-') => {
+                self.pos += 1;
+                let v = self.factor(depth + 1)?;
+                v.checked_neg().ok_or_else(|| "overflow in unary -".into())
+            }
+            Some(b'(') => {
+                self.pos += 1;
+                let v = self.expr(depth + 1)?;
+                if self.peek() != Some(b')') {
+                    return Err(format!("expected ')' at byte {}", self.pos));
+                }
+                self.pos += 1;
+                Ok(v)
+            }
+            Some(c) if c.is_ascii_digit() => {
+                let start = self.pos;
+                while matches!(self.bytes.get(self.pos), Some(d) if d.is_ascii_digit()) {
+                    self.pos += 1;
+                }
+                let text = std::str::from_utf8(&self.bytes[start..self.pos]).expect("digits are ascii");
+                text.parse::<i128>().map_err(|_| format!("number too large: {text}"))
+            }
+            other => Err(format!("unexpected input {:?} at byte {}", other.map(|c| c as char), self.pos)),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    fn runtime(name: &str, commands: &[PathBuf]) -> (ToolRuntime, PathBuf) {
+        let dir = std::env::temp_dir().join(format!("palw-gw-tools-{}-{name}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        std::fs::create_dir_all(&dir).unwrap();
+        let policy = ToolSandboxPolicyV1::new(&dir, &[], commands, 2_000, 1_000, 1 << 20).unwrap();
+        let ws = policy.workspace_root.clone();
+        (ToolRuntime::new(policy), ws)
+    }
+
+    #[test]
+    fn calculator_is_exact_and_total() {
+        assert_eq!(calc_eval("2+3*4").unwrap(), 14);
+        assert_eq!(calc_eval("(2+3)*4").unwrap(), 20);
+        assert_eq!(calc_eval("-5+2").unwrap(), -3);
+        assert_eq!(calc_eval("10/2").unwrap(), 5);
+        assert_eq!(calc_eval("7%2").unwrap(), 1);
+        assert_eq!(calc_eval(" 1 + 2 ").unwrap(), 3);
+        assert!(calc_eval("7/2").is_err(), "inexact division must refuse, not round");
+        assert!(calc_eval("1/0").is_err());
+        assert!(calc_eval("170141183460469231731687303715884105727+1").is_err(), "overflow is an error");
+        assert!(calc_eval("2+").is_err());
+        assert!(calc_eval("").is_err());
+        let bomb = "(".repeat(200) + "1" + &")".repeat(200);
+        assert!(calc_eval(&bomb).is_err(), "depth-capped");
+    }
+
+    #[test]
+    fn read_scope_blocks_escape_and_symlinks() {
+        let (rt, ws) = runtime("readscope", &[]);
+        std::fs::write(ws.join("ok.txt"), b"fine").unwrap();
+        let out = rt.execute("read_file", &json!({"path": "ok.txt"})).unwrap();
+        assert_eq!(out.output, b"fine");
+
+        assert!(rt.execute("read_file", &json!({"path": "../outside.txt"})).is_err());
+        assert!(rt.execute("read_file", &json!({"path": "/etc/hosts"})).is_err(), "absolute outside scope refused");
+
+        // A symlink INSIDE the workspace pointing outside must not read outside.
+        std::os::unix::fs::symlink("/etc/hosts", ws.join("sneaky")).unwrap();
+        assert!(rt.execute("read_file", &json!({"path": "sneaky"})).is_err(), "symlink escape refused");
+    }
+
+    #[test]
+    fn write_scope_is_workspace_relative_only() {
+        let (rt, ws) = runtime("writescope", &[]);
+        let out = rt.execute("write_file", &json!({"path": "sub/dir/x.txt", "content": "hello"})).unwrap();
+        assert!(String::from_utf8_lossy(&out.output).contains("wrote 5 bytes"));
+        assert_eq!(std::fs::read_to_string(ws.join("sub/dir/x.txt")).unwrap(), "hello");
+
+        assert!(rt.execute("write_file", &json!({"path": "/tmp/abs.txt", "content": "x"})).is_err());
+        assert!(rt.execute("write_file", &json!({"path": "../up.txt", "content": "x"})).is_err());
+
+        // A symlinked subdirectory pointing outside must not redirect the write.
+        let outside = std::env::temp_dir().join(format!("palw-gw-tools-outside-{}", std::process::id()));
+        std::fs::create_dir_all(&outside).unwrap();
+        std::os::unix::fs::symlink(&outside, ws.join("link")).unwrap();
+        assert!(rt.execute("write_file", &json!({"path": "link/y.txt", "content": "x"})).is_err());
+    }
+
+    #[test]
+    fn list_dir_is_sorted() {
+        let (rt, ws) = runtime("listdir", &[]);
+        std::fs::write(ws.join("b.txt"), b"2").unwrap();
+        std::fs::write(ws.join("a.txt"), b"1").unwrap();
+        std::fs::create_dir(ws.join("c")).unwrap();
+        let out = rt.execute("list_dir", &json!({"path": "."})).unwrap();
+        let text = String::from_utf8(out.output).unwrap();
+        assert_eq!(text, "a.txt\tfile\t1\nb.txt\tfile\t1\nc\tdir\t0");
+    }
+
+    #[test]
+    fn run_command_allowlist_timeout_and_cap() {
+        let echo = PathBuf::from("/bin/echo");
+        let sleep = PathBuf::from("/bin/sleep");
+        let (rt, _ws) = runtime("runcmd", &[echo.clone(), sleep.clone()]);
+
+        assert!(rt.execute("run_command", &json!({"command": "/bin/ls"})).is_err(), "not allowlisted");
+        assert!(rt.execute("run_command", &json!({"command": "echo"})).is_err(), "bare names never match");
+
+        let out = rt.execute("run_command", &json!({"command": "/bin/echo", "args": ["hello", "world"]})).unwrap();
+        let text = String::from_utf8(out.output).unwrap();
+        assert!(text.starts_with("exit 0\n"), "got: {text}");
+        assert!(text.contains("hello world"));
+
+        // Timeout: sleep 5 against a 2s policy cap — expect the timeout marker well before 5s.
+        let started = Instant::now();
+        let out = rt.execute("run_command", &json!({"command": "/bin/sleep", "args": ["5"]})).unwrap();
+        assert!(started.elapsed() < Duration::from_secs(4));
+        assert!(String::from_utf8_lossy(&out.output).starts_with("timeout after"));
+
+        // Output cap: 1000-byte policy cap against ~2000 bytes of stdout.
+        let big = "x".repeat(2000);
+        let out = rt.execute("run_command", &json!({"command": "/bin/echo", "args": [big]})).unwrap();
+        let text = String::from_utf8_lossy(&out.output).into_owned();
+        assert!(text.contains("[stdout truncated]"));
+    }
+
+    #[test]
+    fn modes_match_the_frozen_split() {
+        assert_eq!(mode_of("calculator"), Some(ToolExecutionMode::DeterministicReplay));
+        assert_eq!(mode_of("read_file"), Some(ToolExecutionMode::SnapshotReadOnly));
+        assert_eq!(mode_of("write_file"), Some(ToolExecutionMode::ExactlyOnceSideEffect));
+        assert_eq!(mode_of("run_command"), Some(ToolExecutionMode::ExactlyOnceSideEffect));
+        assert_eq!(mode_of("nope"), None);
+    }
+}

palw-gateway/src/worker.rs

@@ -0,0 +1,496 @@
+//! PALW Background Worker (design doc §15) — the settlement-clock driver.
+//!
+//! Deliberate shape: the worker is a STATELESS RECONCILER. It keeps no durable state of its
+//! own — the session store is the single source of truth, and every cycle recomputes what needs
+//! doing from it:
+//!
+//! ```text
+//! 1. A-commit   : turns local_complete ∧ mint-intent  → submit_job (idempotent) → replica_pending
+//! 2. verdicts   : turns in the pipeline               → fetch_verdicts → legal transitions
+//! 3. B replicas : fetch_assignments → admission probe → execute full replay → result root
+//!                                     └─ refused/failed → decline (refusing beats no-showing)
+//! ```
+//!
+//! §15's "timeout/retry, restart recovery" fall out of this construction instead of being
+//! features: a crash between submit and the store write is healed by the next cycle's
+//! idempotent re-submit; a coordinator outage just leaves rows where they are (each cycle
+//! degrades to a logged error and tries again).
+//!
+//! What the worker does NOT do (honest boundary): no beacons, no bonds, no DA retention, no
+//! reward settlement — those are consensus-side. `Matured` is chain state (coinbase maturity)
+//! and is never synthesized here; the loopback coordinator stops at `certified`.
+
+use std::sync::atomic::{AtomicBool, AtomicI64, AtomicU64, Ordering};
+use std::sync::{Arc, Mutex};
+
+use crate::coordinator::{JobSubmission, JobVerdict, PalwCoordinator, ReplicaResultV1, output_root};
+use crate::events::RuntimeRootsV1;
+use crate::events::TurnVerificationStatus;
+use crate::scheduler::{JobClass, ResourceScheduler};
+use crate::store::SessionStore;
+
+pub struct WorkerConfig {
+    pub provider_id: String,
+    pub poll_ms: u64,
+    /// Advertised on A-commits so the replica knows the generation bound. NOTE: the engine's
+    /// serve protocol has no per-request max_new — a replica honors its OWN engine's bound, so
+    /// matching deployments must run the same --max-new (loopback trivially does).
+    pub max_new: u32,
+}
+
+#[derive(Default)]
+pub struct WorkerStatus {
+    pub submitted: AtomicU64,
+    pub verdicts_applied: AtomicU64,
+    pub replicas_executed: AtomicU64,
+    pub replicas_declined: AtomicU64,
+    pub errors: AtomicU64,
+    pub last_cycle_unix_ms: AtomicI64,
+    pub last_error: Mutex<Option<String>>,
+}
+
+impl WorkerStatus {
+    fn record_error(&self, context: &str, error: &str) {
+        self.errors.fetch_add(1, Ordering::Relaxed);
+        *self.last_error.lock().unwrap() = Some(format!("{context}: {error}"));
+        eprintln!("[palw-worker] {context}: {error}");
+    }
+}
+
+/// What a replica execution yields: the output ids plus (when the engine emits them) the
+/// execution roots the match key covers.
+pub struct ReplicaOutput {
+    pub output_ids: Vec<u32>,
+    pub runtime_roots: Option<RuntimeRootsV1>,
+}
+
+/// How a replica actually runs — trait so the reconciler is testable without a 35B engine.
+pub trait ReplicaExecutor: Send + Sync {
+    fn execute(&self, prompt_ids: &[u32], max_new: u32) -> Result<ReplicaOutput, String>;
+}
+
+/// The real thing: a §5-v1 Full Context Job on the resident engine, behind the §14 scheduler
+/// as `ReplicaJob` priority (a foreground turn arriving first goes first). `cache_prefix_len=0`
+/// asks the engine to snapshot nothing extra; NOTE the engine still reuses any matching prefix
+/// it happens to hold (deterministic, so the output is identical either way) — which is exactly
+/// why single-process loopback replicas prove plumbing, not independence.
+pub struct EngineReplicaExecutor {
+    pub engine: Arc<Mutex<crate::engine::EngineHost>>,
+    pub scheduler: Arc<ResourceScheduler>,
+}
+
+impl ReplicaExecutor for EngineReplicaExecutor {
+    fn execute(&self, prompt_ids: &[u32], _max_new: u32) -> Result<ReplicaOutput, String> {
+        // _max_new: the serve protocol has no per-request bound — the engine's own --max-new
+        // applies (see WorkerConfig::max_new note).
+        let _lease = self.scheduler.acquire(JobClass::ReplicaJob);
+        let mut engine = self.engine.lock().unwrap();
+        let cancel = Arc::new(AtomicBool::new(false));
+        let outcome = engine.generate(prompt_ids, 0, &cancel, |_, _| {})?;
+        self.scheduler.record_generation(outcome.output_ids.len() as u64, outcome.elapsed_ms);
+        Ok(ReplicaOutput { output_ids: outcome.output_ids, runtime_roots: outcome.runtime_roots })
+    }
+}
+
+/// The legal-transition path from the turn's current status to what a verdict implies. The
+/// store enforces legality anyway; this keeps the worker from ever ASKING for an illegal jump
+/// (e.g. a `certified` verdict against a still-replica_pending turn walks matched→certified).
+pub fn steps_to(current: TurnVerificationStatus, verdict: JobVerdict) -> Vec<TurnVerificationStatus> {
+    use TurnVerificationStatus as S;
+    match verdict {
+        JobVerdict::ReplicaMatched => match current {
+            S::ReplicaPending => vec![S::ReplicaMatched],
+            _ => vec![],
+        },
+        JobVerdict::Certified => match current {
+            S::ReplicaPending => vec![S::ReplicaMatched, S::Certified],
+            S::ReplicaMatched | S::AuditPending => vec![S::Certified],
+            _ => vec![],
+        },
+        JobVerdict::Mismatch => match current {
+            S::ReplicaPending | S::ReplicaMatched | S::AuditPending => vec![S::Mismatch],
+            _ => vec![],
+        },
+    }
+}
+
+fn now_unix_ms() -> i64 {
+    std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).map(|d| d.as_millis() as i64).unwrap_or(0)
+}
+
+/// One reconciliation cycle. Locks are held only around store reads/writes — never across a
+/// coordinator call or a replica execution.
+pub fn run_cycle(
+    store: &Mutex<SessionStore>,
+    scheduler: &ResourceScheduler,
+    coordinator: &dyn PalwCoordinator,
+    executor: &dyn ReplicaExecutor,
+    config: &WorkerConfig,
+    status: &WorkerStatus,
+) {
+    status.last_cycle_unix_ms.store(now_unix_ms(), Ordering::Relaxed);
+
+    // ---- 1. A-commits -------------------------------------------------------------------
+    let awaiting = match store.lock().unwrap().turns_awaiting_palw_submission() {
+        Ok(t) => t,
+        Err(e) => {
+            status.record_error("scan awaiting", &e);
+            Vec::new()
+        }
+    };
+    for turn in awaiting {
+        let submission = JobSubmission {
+            job_id: turn.turn_id.clone(),
+            provider_id: config.provider_id.clone(),
+            prompt_ids: turn.prompt_ids.clone(),
+            max_new: config.max_new,
+            output_root: output_root(&turn.output_ids),
+            receipt_json: turn.receipt_json.clone(),
+            runtime_roots: turn.runtime_roots_json.as_deref().and_then(|j| serde_json::from_str(j).ok()),
+        };
+        match coordinator.submit_job(&submission) {
+            Ok(()) => {
+                match store.lock().unwrap().set_verification_status(
+                    &turn.turn_id,
+                    TurnVerificationStatus::ReplicaPending,
+                    now_unix_ms(),
+                ) {
+                    Ok(_) => {
+                        status.submitted.fetch_add(1, Ordering::Relaxed);
+                    }
+                    Err(e) => status.record_error("mark replica_pending", &e),
+                }
+            }
+            Err(e) => {
+                // A PROTOCOL rejection (our HttpCoordinator formats these as "...: 400 ...") is
+                // permanent — the coordinator will refuse this submission forever (e.g. a turn
+                // generated before ROOTS capture against a class-strict bridge). Retrying every
+                // cycle is noise; the turn leaves the mint path. Transport errors keep retrying.
+                if e.contains(": 400 ") {
+                    let _ = store.lock().unwrap().set_verification_status(
+                        &turn.turn_id,
+                        TurnVerificationStatus::MintIneligible,
+                        now_unix_ms(),
+                    );
+                    status.record_error("submit rejected permanently — turn marked mint_ineligible", &e);
+                } else {
+                    status.record_error("submit job", &e);
+                }
+            }
+        }
+    }
+
+    // ---- 2. verdicts --------------------------------------------------------------------
+    let pending = match store.lock().unwrap().turns_in_palw_pipeline() {
+        Ok(t) => t,
+        Err(e) => {
+            status.record_error("scan pipeline", &e);
+            Vec::new()
+        }
+    };
+    if !pending.is_empty() {
+        let ids: Vec<String> = pending.iter().map(|t| t.turn_id.clone()).collect();
+        match coordinator.fetch_verdicts(&ids) {
+            Ok(verdicts) => {
+                for turn in &pending {
+                    let Some(verdict) = verdicts.get(&turn.turn_id) else { continue };
+                    for step in steps_to(turn.verification_status, *verdict) {
+                        match store.lock().unwrap().set_verification_status(&turn.turn_id, step, now_unix_ms()) {
+                            Ok(_) => {
+                                status.verdicts_applied.fetch_add(1, Ordering::Relaxed);
+                            }
+                            Err(e) => {
+                                status.record_error("apply verdict", &e);
+                                break;
+                            }
+                        }
+                    }
+                }
+            }
+            Err(e) => status.record_error("fetch verdicts", &e),
+        }
+    }
+
+    // ---- 3. B replicas ------------------------------------------------------------------
+    let assignments = match coordinator.fetch_assignments(&config.provider_id) {
+        Ok(a) => a,
+        Err(e) => {
+            status.record_error("fetch assignments", &e);
+            Vec::new()
+        }
+    };
+    for assignment in assignments {
+        let remaining_ms = assignment.deadline_unix_ms - now_unix_ms();
+        let admit = if remaining_ms <= 0 {
+            Err("deadline already passed".to_string())
+        } else {
+            scheduler.try_admit(JobClass::ReplicaJob, u64::from(assignment.max_new), remaining_ms as u64)
+        };
+        if let Err(reason) = admit {
+            status.replicas_declined.fetch_add(1, Ordering::Relaxed);
+            if let Err(e) = coordinator.decline_assignment(&assignment.job_id, &config.provider_id, &reason) {
+                status.record_error("decline", &e);
+            }
+            continue;
+        }
+        match executor.execute(&assignment.prompt_ids, assignment.max_new) {
+            Ok(output) => {
+                let result = ReplicaResultV1 {
+                    job_id: assignment.job_id.clone(),
+                    provider_id: config.provider_id.clone(),
+                    output_root: output_root(&output.output_ids),
+                    runtime_roots: output.runtime_roots,
+                };
+                match coordinator.submit_replica_result(&result) {
+                    Ok(()) => {
+                        status.replicas_executed.fetch_add(1, Ordering::Relaxed);
+                    }
+                    Err(e) => status.record_error("submit replica result", &e),
+                }
+            }
+            Err(e) => {
+                status.replicas_declined.fetch_add(1, Ordering::Relaxed);
+                let reason = format!("execution failed: {e}");
+                if let Err(decline_err) = coordinator.decline_assignment(&assignment.job_id, &config.provider_id, &reason)
+                {
+                    status.record_error("decline after failure", &decline_err);
+                }
+                status.record_error("replica execution", &e);
+            }
+        }
+    }
+}
+
+pub struct WorkerHandle {
+    stop: Arc<AtomicBool>,
+    // The gateway binary never returns from serve(), so only tests and future embedders join
+    // the thread — the field is dead code from the bin's point of view, kept for them.
+    #[allow(dead_code)]
+    join: Option<std::thread::JoinHandle<()>>,
+}
+
+impl WorkerHandle {
+    #[allow(dead_code)]
+    pub fn shutdown(mut self) {
+        self.stop.store(true, Ordering::Relaxed);
+        if let Some(join) = self.join.take() {
+            let _ = join.join();
+        }
+    }
+}
+
+impl Drop for WorkerHandle {
+    fn drop(&mut self) {
+        self.stop.store(true, Ordering::Relaxed);
+    }
+}
+
+/// Spawn the reconciler thread. Dependencies come in as Arcs so the caller (main) can share
+/// the gateway's own store/scheduler.
+pub fn spawn(
+    store: Arc<Mutex<SessionStore>>,
+    scheduler: Arc<ResourceScheduler>,
+    coordinator: Arc<dyn PalwCoordinator>,
+    executor: Arc<dyn ReplicaExecutor>,
+    config: WorkerConfig,
+    status: Arc<WorkerStatus>,
+) -> WorkerHandle {
+    let stop = Arc::new(AtomicBool::new(false));
+    let stop_thread = Arc::clone(&stop);
+    let join = std::thread::Builder::new()
+        .name("palw-worker".into())
+        .spawn(move || {
+            eprintln!(
+                "[palw-worker] started: provider {} poll {}ms",
+                config.provider_id, config.poll_ms
+            );
+            while !stop_thread.load(Ordering::Relaxed) {
+                run_cycle(&store, &scheduler, coordinator.as_ref(), executor.as_ref(), &config, &status);
+                // Sleep in small slices so shutdown stays prompt.
+                let mut slept = 0u64;
+                while slept < config.poll_ms && !stop_thread.load(Ordering::Relaxed) {
+                    let slice = (config.poll_ms - slept).min(100);
+                    std::thread::sleep(std::time::Duration::from_millis(slice));
+                    slept += slice;
+                }
+            }
+        })
+        .expect("spawn palw-worker");
+    WorkerHandle { stop, join: Some(join) }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::coordinator::{LoopbackConfig, LoopbackCoordinator};
+    use crate::events::TurnPrivacyMode;
+    use crate::store::NewTurn;
+
+    struct FakeExecutor(Vec<u32>);
+    impl ReplicaExecutor for FakeExecutor {
+        fn execute(&self, _prompt_ids: &[u32], _max_new: u32) -> Result<ReplicaOutput, String> {
+            Ok(ReplicaOutput { output_ids: self.0.clone(), runtime_roots: None })
+        }
+    }
+
+    fn store_with_turn(name: &str, privacy: TurnPrivacyMode, output: &[u32]) -> Mutex<SessionStore> {
+        let dir = std::env::temp_dir().join(format!("palw-gw-worker-{}-{name}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        let mut s = SessionStore::open(&dir.join("s.sqlite3")).unwrap();
+        s.create_conversation("c1", "t", None, 1).unwrap();
+        s.begin_turn(&NewTurn {
+            turn_id: "t1",
+            conversation_id: "c1",
+            parent_turn_id: None,
+            role_user_text: "q",
+            user_block_text: "q",
+            context_meta_json: None,
+            prompt_ids: &[1, 2, 3],
+            privacy_mode: privacy,
+            search_bundle_json: None,
+            now_ms: 2,
+        })
+        .unwrap();
+        s.complete_turn(&crate::store::CompletedTurn {
+            turn_id: "t1",
+            output_ids: output,
+            display_text: "ans",
+            stop_reason: "eos",
+            status: TurnVerificationStatus::LocalComplete,
+            receipt_json: None,
+            runtime_roots_json: None,
+        })
+        .unwrap();
+        Mutex::new(s)
+    }
+
+    fn worker_config() -> WorkerConfig {
+        WorkerConfig { provider_id: "prov-a".into(), poll_ms: 10, max_new: 16 }
+    }
+
+    #[test]
+    fn full_loopback_match_reaches_certified_head() {
+        let store = store_with_turn("match", TurnPrivacyMode::PalwMint, &[7, 8, 9]);
+        let scheduler = ResourceScheduler::new();
+        let coordinator = LoopbackCoordinator::new(LoopbackConfig::default());
+        let executor = FakeExecutor(vec![7, 8, 9]); // honest replica: same ids as A stored
+        let config = worker_config();
+        let status = WorkerStatus::default();
+
+        // Cycle 1: submit + self-assign + execute + result.
+        run_cycle(&store, &scheduler, &coordinator, &executor, &config, &status);
+        assert_eq!(status.submitted.load(Ordering::Relaxed), 1);
+        assert_eq!(status.replicas_executed.load(Ordering::Relaxed), 1);
+        assert_eq!(
+            store.lock().unwrap().get_turn("t1").unwrap().verification_status,
+            TurnVerificationStatus::ReplicaPending
+        );
+
+        // Cycle 2: verdict replica_matched.
+        run_cycle(&store, &scheduler, &coordinator, &executor, &config, &status);
+        assert_eq!(
+            store.lock().unwrap().get_turn("t1").unwrap().verification_status,
+            TurnVerificationStatus::ReplicaMatched
+        );
+
+        // Cycle 3: verdict certified — certified_head advances (the §4 dual-head payoff).
+        run_cycle(&store, &scheduler, &coordinator, &executor, &config, &status);
+        let s = store.lock().unwrap();
+        assert_eq!(s.get_turn("t1").unwrap().verification_status, TurnVerificationStatus::Certified);
+        assert_eq!(s.heads("c1").unwrap().certified_head.as_deref(), Some("t1"));
+        assert!(status.last_error.lock().unwrap().is_none(), "{:?}", status.last_error.lock().unwrap());
+    }
+
+    #[test]
+    fn dishonest_replica_yields_mismatch() {
+        let store = store_with_turn("mismatch", TurnPrivacyMode::PalwMint, &[7, 8, 9]);
+        let scheduler = ResourceScheduler::new();
+        let coordinator = LoopbackCoordinator::new(LoopbackConfig::default());
+        let executor = FakeExecutor(vec![666]); // wrong output
+        let config = worker_config();
+        let status = WorkerStatus::default();
+
+        run_cycle(&store, &scheduler, &coordinator, &executor, &config, &status); // submit+replica
+        run_cycle(&store, &scheduler, &coordinator, &executor, &config, &status); // verdict
+        assert_eq!(
+            store.lock().unwrap().get_turn("t1").unwrap().verification_status,
+            TurnVerificationStatus::Mismatch
+        );
+    }
+
+    #[test]
+    fn local_only_turns_never_leave_the_device() {
+        let store = store_with_turn("localonly", TurnPrivacyMode::LocalOnly, &[7]);
+        let scheduler = ResourceScheduler::new();
+        let coordinator = LoopbackCoordinator::new(LoopbackConfig::default());
+        let executor = FakeExecutor(vec![7]);
+        let status = WorkerStatus::default();
+        run_cycle(&store, &scheduler, &coordinator, &executor, &worker_config(), &status);
+        assert_eq!(status.submitted.load(Ordering::Relaxed), 0);
+        assert_eq!(coordinator.counts()["unassigned"], 0, "nothing was ever submitted");
+        assert_eq!(
+            store.lock().unwrap().get_turn("t1").unwrap().verification_status,
+            TurnVerificationStatus::LocalComplete
+        );
+    }
+
+    #[test]
+    fn admission_refusal_declines_and_requeues() {
+        let store = store_with_turn("decline", TurnPrivacyMode::VerifiedNoMint, &[7]);
+        let scheduler = ResourceScheduler::new();
+        let coordinator = LoopbackCoordinator::new(LoopbackConfig::default());
+        let executor = FakeExecutor(vec![7]);
+        // 10M tokens at the 8 tok/s default EMA ⇒ admission must refuse against a 120s deadline.
+        let config = WorkerConfig { provider_id: "prov-a".into(), poll_ms: 10, max_new: 10_000_000 };
+        let status = WorkerStatus::default();
+
+        run_cycle(&store, &scheduler, &coordinator, &executor, &config, &status);
+        assert_eq!(status.replicas_declined.load(Ordering::Relaxed), 1);
+        assert_eq!(status.replicas_executed.load(Ordering::Relaxed), 0);
+        // Declined ⇒ requeued at the coordinator; the turn itself stays replica_pending.
+        assert_eq!(coordinator.counts()["unassigned"], 1);
+        assert_eq!(
+            store.lock().unwrap().get_turn("t1").unwrap().verification_status,
+            TurnVerificationStatus::ReplicaPending
+        );
+    }
+
+    #[test]
+    fn spawned_worker_reconciles_and_shuts_down() {
+        let store = store_with_turn("spawned", TurnPrivacyMode::PalwMint, &[7, 8, 9]);
+        let store = Arc::new(store);
+        let scheduler = Arc::new(ResourceScheduler::new());
+        let coordinator: Arc<dyn crate::coordinator::PalwCoordinator> =
+            Arc::new(LoopbackCoordinator::new(LoopbackConfig::default()));
+        let executor: Arc<dyn ReplicaExecutor> = Arc::new(FakeExecutor(vec![7, 8, 9]));
+        let status = Arc::new(WorkerStatus::default());
+
+        let handle = spawn(
+            Arc::clone(&store),
+            scheduler,
+            coordinator,
+            executor,
+            WorkerConfig { provider_id: "prov-a".into(), poll_ms: 10, max_new: 16 },
+            Arc::clone(&status),
+        );
+        let deadline = std::time::Instant::now() + std::time::Duration::from_secs(10);
+        while store.lock().unwrap().get_turn("t1").unwrap().verification_status != TurnVerificationStatus::Certified {
+            assert!(std::time::Instant::now() < deadline, "worker did not certify within 10s");
+            std::thread::sleep(std::time::Duration::from_millis(10));
+        }
+        handle.shutdown();
+        assert!(status.submitted.load(Ordering::Relaxed) >= 1);
+        assert_eq!(store.lock().unwrap().heads("c1").unwrap().certified_head.as_deref(), Some("t1"));
+    }
+
+    #[test]
+    fn steps_never_request_illegal_jumps() {
+        use TurnVerificationStatus as S;
+        assert_eq!(steps_to(S::ReplicaPending, JobVerdict::Certified), vec![S::ReplicaMatched, S::Certified]);
+        assert_eq!(steps_to(S::ReplicaMatched, JobVerdict::Certified), vec![S::Certified]);
+        assert_eq!(steps_to(S::ReplicaPending, JobVerdict::ReplicaMatched), vec![S::ReplicaMatched]);
+        assert!(steps_to(S::Certified, JobVerdict::ReplicaMatched).is_empty(), "stale verdicts are ignored");
+        assert!(steps_to(S::Mismatch, JobVerdict::Certified).is_empty());
+        assert_eq!(steps_to(S::AuditPending, JobVerdict::Mismatch), vec![S::Mismatch]);
+    }
+}

runtime-palw/src/lib.rs

@@ -27,6 +27,7 @@ pub mod lifecycle;
 pub mod manifest;
 pub mod matcher;
 pub mod mint;
+pub mod model_genesis;
 pub mod observer;
 pub mod protocol_v2;
 pub mod qwen_adapter;

runtime-palw/src/model_genesis.rs

@@ -0,0 +1,1152 @@
+//! `ModelGenesisManifest` — the ADR-0047 in-repo prerequisite.
+//!
+//! ADR-0047 (`MisakaLLM-palw-shared/docs/adr/0047-model-genesis-dual-reproduction.md` §1) fixes the
+//! two-party reproduction protocol as: weights → sha256 → deterministic conversion →
+//! `ModelGenesisManifest` → keyed-BLAKE2b(palw-k1 convention) hash → ML-DSA signature, with
+//! acceptance defined as a **bit-exact manifest-hash match between two parties**. Before this
+//! module the type did not exist anywhere in either repository, so two operators running the
+//! external procedure had nothing to compare: the ADR's acceptance criterion was unevaluable.
+//!
+//! # What this module is, and what it is not
+//!
+//! It is the *comparable artifact*: a canonical, backend-independent, weights-derived encoding and
+//! its domain-separated digest, plus a field-level diff so a mismatch names a field instead of
+//! saying "the hashes differ".
+//!
+//! It is **not** a genesis. Every external item of the ADR remains open: official-weights
+//! provenance, the two real GPU runs, and the evidence bundle. [`assess_genesis`] can never return
+//! an eligible assessment (see [`GenesisDisqualifier::ManifestUnsigned`]), and that is enforced by
+//! a unit test, in the same shape as `crate::mint`'s `MainnetBlocker::ExternalModelGenesis` gate.
+//!
+//! # Backend independence (ADR §1)
+//!
+//! The proof-of-llm verifier's Metal/CUDA token asymmetry is the reason the ADR demands a manifest
+//! that contains no execution trace: any host-, backend- or build-dependent field makes the
+//! two-party comparison fail for reasons that have nothing to do with the weights. This module
+//! enforces that mechanically rather than by convention — [`ModelGenesisManifest::validate`]
+//! rejects a conversion procedure that mentions a backend or host token, and rejects absolute or
+//! traversal-bearing paths (which carry the operator's home directory into the digest).
+//!
+//! # Domain separation
+//!
+//! The digest primitive here (keyed BLAKE2b-512) is the same one used for receipt bodies, match
+//! projections and file hashes (`palw-k1/file`, see `crate::receipt_v3`). Keying by a per-object
+//! domain is what keeps those digest spaces unrelated: without it, a byte string that is a valid
+//! canonical manifest could simultaneously be a valid preimage of another object class, and a
+//! commitment or signature over one would silently be a commitment over the other. The model
+//! genesis therefore takes its own key, [`PALW_MODEL_GENESIS_V1_HASH_DOMAIN`], distinct from every
+//! domain in `crate::receipt_v3`.
+//!
+//! # Signing is blocked, deliberately
+//!
+//! The ML-DSA-87 signature-context table (`consensus/core/src/signature_domains.rs`) was LOCKED on
+//! 2026-07-25 and is guarded by a golden test. A model-genesis signature therefore cannot be
+//! produced today, and this module contains **no signing function at all**.
+//! [`PALW_MODEL_GENESIS_V1_MLDSA87_CONTEXT_UNREGISTERED`] records the exact context bytes that
+//! would be requested, so the unlock decision has something concrete to review; it is not usable
+//! until that decision is taken.
+
+use crate::receipt_v3::Hash64;
+use thiserror::Error;
+
+/// Schema version of the canonical model-genesis encoding.
+pub const MODEL_GENESIS_SCHEMA_V1: u16 = 1;
+
+/// Keyed-BLAKE2b-512 domain (used as the `BLAKE2b` *key*) for [`ModelGenesisManifest::manifest_hash`].
+///
+/// Distinct from every `crate::receipt_v3` domain and from `palw-k1/file`; see the module note on
+/// why domain separation is load-bearing rather than cosmetic.
+pub const PALW_MODEL_GENESIS_V1_HASH_DOMAIN: &[u8] = b"misaka-palw-v1/model-genesis";
+
+/// The ML-DSA-87 signature context a signed model genesis WOULD require.
+///
+/// **UNREGISTERED — do not sign with this.** The signature-domain table is LOCKED (2026-07-25) and
+/// adding a row is an explicit human unlock decision. The row that would be required is recorded in
+/// ADR-0047 and in `docs/model-genesis-candidate.md`. This constant exists only so that the review
+/// of that decision can check distinctness and prefix-freedom against the contexts this crate
+/// already knows (see `tests::proposed_context_is_distinct_and_prefix_free`).
+pub const PALW_MODEL_GENESIS_V1_MLDSA87_CONTEXT_UNREGISTERED: &[u8] =
+    b"misaka-palw-v1/model-genesis/mldsa87";
+
+/// A SHA-256 file digest, as published by the weights host and recomputed locally.
+pub type Sha256Digest = [u8; 32];
+
+/// Errors from [`ModelGenesisManifest::validate`].
+#[derive(Debug, Clone, PartialEq, Eq, Error)]
+pub enum ModelGenesisError {
+    /// A text field contained a byte outside printable ASCII (`0x20..=0x7e`).
+    ///
+    /// Non-ASCII text has multiple encodings of the same-looking string; permitting it would make
+    /// the "two parties typed the same thing" assumption unverifiable.
+    #[error("{field}: byte {index} is outside printable ASCII")]
+    NonPrintableAscii {
+        /// Dotted field path.
+        field: &'static str,
+        /// Index of the offending byte.
+        index: usize,
+    },
+    /// A field that must pin an immutable revision was not 40 or 64 lowercase hex characters.
+    #[error("{field}: {value:?} is not an immutable revision pin (40 or 64 lowercase hex)")]
+    NotARevisionPin {
+        /// Dotted field path.
+        field: &'static str,
+        /// The rejected value.
+        value: String,
+    },
+    /// A path field was empty, absolute, or contained a `..` / `~` component.
+    #[error("{field}: {value:?} must be a relative, traversal-free path")]
+    UnsafePath {
+        /// Dotted field path.
+        field: &'static str,
+        /// The rejected value.
+        value: String,
+    },
+    /// The weight-file list was not strictly ascending by path.
+    ///
+    /// Sorting is required rather than applied silently: two operators whose listings differ have a
+    /// real difference in what they hashed, and hiding it behind a sort would hide that.
+    #[error("weights.files: must be strictly ascending by path ({0:?} is not before {1:?})")]
+    UnsortedFiles(String, String),
+    /// The weight-file list was empty.
+    #[error("weights.files: at least one weight file must be recorded")]
+    NoWeightFiles,
+    /// A conversion-procedure field named a backend- or host-specific token (ADR §1).
+    #[error(
+        "conversion.{field}: contains {token:?} — the manifest must be weights-derived only, \
+         backend/host-specific inputs make the two-party comparison meaningless (ADR-0047 §1)"
+    )]
+    BackendSpecificField {
+        /// Dotted field path within the conversion procedure.
+        field: &'static str,
+        /// The denied token that matched.
+        token: &'static str,
+    },
+    /// An architecture or tokenizer field that must describe real geometry was zero.
+    #[error("{0}: must be non-zero")]
+    ZeroField(&'static str),
+}
+
+/// How far the recorded provenance chain reaches.
+///
+/// This is a claim both parties must make identically; it is part of the hashed encoding precisely
+/// so that one party cannot quietly record "official" while the other records "derivative".
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ProvenanceTier {
+    /// The recorded source is the official upstream publisher's checkpoint.
+    OfficialUpstream,
+    /// The recorded source is a third-party derivative (for example an "abliterated" re-release).
+    ///
+    /// This is what the pins in `docs/model-genesis-candidate.md` currently are. A manifest with
+    /// this tier is reproducible, but it can never become the genesis — disqualifier (1).
+    ThirdPartyDerivative,
+}
+
+impl ProvenanceTier {
+    /// Canonical wire tag.
+    #[must_use]
+    pub const fn tag(self) -> u8 {
+        match self {
+            Self::OfficialUpstream => 0,
+            Self::ThirdPartyDerivative => 1,
+        }
+    }
+}
+
+/// A repository/revision pair the recorded weights claim to descend from.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct UpstreamRef {
+    /// Publisher-scoped repository identifier, for example `Qwen/Qwen3.6-35B-A3B`.
+    pub source_id: String,
+    /// Immutable revision pin (40 or 64 lowercase hex characters).
+    pub revision: String,
+}
+
+/// One downloaded weight-side file and its locally recomputed digest.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct WeightFile {
+    /// Repository-relative, traversal-free path.
+    pub path: String,
+    /// SHA-256 of the file bytes as they exist on disk.
+    pub sha256: Sha256Digest,
+    /// Exact byte length.
+    pub size: u64,
+}
+
+/// Where the weights came from and exactly which bytes were obtained.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct WeightsProvenance {
+    /// How far the chain reaches.
+    pub tier: ProvenanceTier,
+    /// Repository identifier actually downloaded from.
+    pub source_id: String,
+    /// Immutable revision pin actually downloaded.
+    pub source_revision: String,
+    /// The upstream this source declares itself derived from, when it is not itself upstream.
+    pub upstream_of_record: Option<UpstreamRef>,
+    /// Every file that participates in the conversion, strictly ascending by `path`.
+    pub files: Vec<WeightFile>,
+}
+
+/// Model geometry, read from the checkpoint's own configuration.
+///
+/// Every field here is a property of the weights, not of any runtime: the same numbers are read by
+/// a Metal host and a CUDA host from the same `config.json`.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ModelArchitecture {
+    /// Architecture class string, for example `Qwen3ForCausalLM`.
+    pub architecture: String,
+    /// Hidden size.
+    pub hidden_size: u32,
+    /// Transformer layer count.
+    pub layers: u32,
+    /// Attention head count.
+    pub attention_heads: u32,
+    /// Key/value head count.
+    pub key_value_heads: u32,
+    /// Feed-forward intermediate size.
+    pub intermediate_size: u32,
+    /// Per-head dimension.
+    pub head_dim: u32,
+    /// `RoPE` base.
+    ///
+    /// Integral by construction: a non-integral base must extend the schema rather than be rounded,
+    /// because rounding is exactly the kind of silent per-implementation difference that breaks a
+    /// bit-exact comparison.
+    pub rope_theta: u64,
+    /// Vocabulary size declared by the model configuration.
+    pub vocab_size: u32,
+    /// Maximum position embeddings.
+    pub max_position_embeddings: u32,
+    /// Stored parameter dtype, for example `bfloat16`.
+    pub parameter_dtype: String,
+}
+
+/// Tokenizer identity.
+///
+/// Redundant with [`WeightsProvenance::files`] on purpose: naming the semantically load-bearing
+/// files individually means a diff reports `tokenizer.tokenizer_sha256` rather than an index into a
+/// file list.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct TokenizerIdentity {
+    /// SHA-256 of `tokenizer.json`.
+    pub tokenizer_sha256: Sha256Digest,
+    /// SHA-256 of `tokenizer_config.json`.
+    pub tokenizer_config_sha256: Sha256Digest,
+    /// SHA-256 of the chat template shipped with the checkpoint.
+    pub chat_template_sha256: Sha256Digest,
+    /// Vocabulary size as the tokenizer itself reports it.
+    pub tokenizer_vocab_size: u32,
+}
+
+/// The deterministic derivation both parties must run identically.
+///
+/// A conversion *procedure* is not backend state: `convert_hf_to_gguf.py` at a pinned commit
+/// produces the same bytes on any host. That is a claim the two-party run TESTS; recording it here
+/// is what makes the test meaningful. Anything host- or backend-flavoured is rejected by
+/// [`ModelGenesisManifest::validate`].
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ConversionProcedure {
+    /// Converter source repository URL.
+    pub converter_repo: String,
+    /// Converter commit pin (40 or 64 lowercase hex characters).
+    pub converter_commit: String,
+    /// Repository-relative converter entrypoint, for example `convert_hf_to_gguf.py`.
+    pub converter_entrypoint: String,
+    /// Exact ordered argument tail passed to the converter, excluding input/output paths.
+    pub converter_args: Vec<String>,
+    /// Repository-relative quantizer entrypoint, for example `llama-quantize`.
+    pub quantizer_entrypoint: String,
+    /// Exact ordered argument tail passed to the quantizer, excluding input/output paths.
+    pub quantizer_args: Vec<String>,
+    /// Target quantization label, for example `Q4_K_M`.
+    pub quantization: String,
+}
+
+/// The artifact the conversion produced.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct DerivedArtifact {
+    /// SHA-256 of the produced `GGUF`.
+    pub gguf_sha256: Sha256Digest,
+    /// Exact byte length of the produced `GGUF`.
+    pub gguf_size: u64,
+}
+
+/// The comparable object of ADR-0047 §1.
+///
+/// Canonical encoding: all integers big-endian, every variable-length field length-prefixed with a
+/// `u64` big-endian length, fields in declaration order. Length prefixing everywhere makes the
+/// encoding injective (prefix-free), so no two distinct manifests can share canonical bytes.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ModelGenesisManifest {
+    /// Encoding schema version; [`MODEL_GENESIS_SCHEMA_V1`] today.
+    pub schema_version: u16,
+    /// Where the weights came from.
+    pub weights: WeightsProvenance,
+    /// Geometry read from the checkpoint configuration.
+    pub architecture: ModelArchitecture,
+    /// Tokenizer identity.
+    pub tokenizer: TokenizerIdentity,
+    /// The derivation both parties run.
+    pub conversion: ConversionProcedure,
+    /// What the derivation produced.
+    pub artifact: DerivedArtifact,
+}
+
+/// Tokens that must never appear in a conversion-procedure field.
+///
+/// Short or ambiguous substrings are deliberately excluded (`hip` matches `chip`), and the list is
+/// applied only to the conversion procedure, where a hit is unambiguous evidence that host state
+/// leaked into a weights-derived object.
+const BACKEND_TOKENS: &[&str] = &[
+    "metal", "cuda", "cublas", "rocm", "vulkan", "sycl", "opencl", "gpu", "ngl", "device",
+    "thread", "darwin", "arm64", "x86_64", "avx", "neon",
+];
+
+fn push_framed(out: &mut Vec<u8>, bytes: &[u8]) {
+    let len = u64::try_from(bytes.len()).expect("field length fits in u64 on supported platforms");
+    out.extend_from_slice(&len.to_be_bytes());
+    out.extend_from_slice(bytes);
+}
+
+fn check_ascii(field: &'static str, value: &str) -> Result<(), ModelGenesisError> {
+    for (index, byte) in value.as_bytes().iter().enumerate() {
+        if !(0x20..=0x7e).contains(byte) {
+            return Err(ModelGenesisError::NonPrintableAscii { field, index });
+        }
+    }
+    Ok(())
+}
+
+fn check_revision_pin(field: &'static str, value: &str) -> Result<(), ModelGenesisError> {
+    let ok = (value.len() == 40 || value.len() == 64)
+        && value
+            .bytes()
+            .all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b));
+    if ok {
+        Ok(())
+    } else {
+        Err(ModelGenesisError::NotARevisionPin {
+            field,
+            value: value.to_owned(),
+        })
+    }
+}
+
+fn check_relative_path(field: &'static str, value: &str) -> Result<(), ModelGenesisError> {
+    let bad = value.is_empty()
+        || value.starts_with('/')
+        || value.starts_with('~')
+        || value.split('/').any(|part| part == ".." || part.is_empty());
+    if bad {
+        return Err(ModelGenesisError::UnsafePath {
+            field,
+            value: value.to_owned(),
+        });
+    }
+    Ok(())
+}
+
+fn check_backend_free(field: &'static str, value: &str) -> Result<(), ModelGenesisError> {
+    let lowered = value.to_ascii_lowercase();
+    for token in BACKEND_TOKENS {
+        if lowered.contains(token) {
+            return Err(ModelGenesisError::BackendSpecificField { field, token });
+        }
+    }
+    Ok(())
+}
+
+impl WeightsProvenance {
+    fn append_canonical(&self, out: &mut Vec<u8>) {
+        out.push(self.tier.tag());
+        push_framed(out, self.source_id.as_bytes());
+        push_framed(out, self.source_revision.as_bytes());
+        match &self.upstream_of_record {
+            None => out.push(0),
+            Some(upstream) => {
+                out.push(1);
+                push_framed(out, upstream.source_id.as_bytes());
+                push_framed(out, upstream.revision.as_bytes());
+            }
+        }
+        let count =
+            u64::try_from(self.files.len()).expect("file count fits in u64 on supported platforms");
+        out.extend_from_slice(&count.to_be_bytes());
+        for file in &self.files {
+            push_framed(out, file.path.as_bytes());
+            out.extend_from_slice(&file.sha256);
+            out.extend_from_slice(&file.size.to_be_bytes());
+        }
+    }
+}
+
+impl ModelArchitecture {
+    fn append_canonical(&self, out: &mut Vec<u8>) {
+        push_framed(out, self.architecture.as_bytes());
+        for value in [
+            self.hidden_size,
+            self.layers,
+            self.attention_heads,
+            self.key_value_heads,
+            self.intermediate_size,
+            self.head_dim,
+        ] {
+            out.extend_from_slice(&value.to_be_bytes());
+        }
+        out.extend_from_slice(&self.rope_theta.to_be_bytes());
+        out.extend_from_slice(&self.vocab_size.to_be_bytes());
+        out.extend_from_slice(&self.max_position_embeddings.to_be_bytes());
+        push_framed(out, self.parameter_dtype.as_bytes());
+    }
+}
+
+impl TokenizerIdentity {
+    fn append_canonical(&self, out: &mut Vec<u8>) {
+        out.extend_from_slice(&self.tokenizer_sha256);
+        out.extend_from_slice(&self.tokenizer_config_sha256);
+        out.extend_from_slice(&self.chat_template_sha256);
+        out.extend_from_slice(&self.tokenizer_vocab_size.to_be_bytes());
+    }
+}
+
+impl ConversionProcedure {
+    fn append_canonical(&self, out: &mut Vec<u8>) {
+        push_framed(out, self.converter_repo.as_bytes());
+        push_framed(out, self.converter_commit.as_bytes());
+        push_framed(out, self.converter_entrypoint.as_bytes());
+        append_string_list(out, &self.converter_args);
+        push_framed(out, self.quantizer_entrypoint.as_bytes());
+        append_string_list(out, &self.quantizer_args);
+        push_framed(out, self.quantization.as_bytes());
+    }
+}
+
+fn append_string_list(out: &mut Vec<u8>, values: &[String]) {
+    let count =
+        u64::try_from(values.len()).expect("list length fits in u64 on supported platforms");
+    out.extend_from_slice(&count.to_be_bytes());
+    for value in values {
+        push_framed(out, value.as_bytes());
+    }
+}
+
+impl DerivedArtifact {
+    fn append_canonical(&self, out: &mut Vec<u8>) {
+        out.extend_from_slice(&self.gguf_sha256);
+        out.extend_from_slice(&self.gguf_size.to_be_bytes());
+    }
+}
+
+impl ModelGenesisManifest {
+    /// Canonical bytes (big-endian integers, `u64`-length-framed variable fields).
+    ///
+    /// Hashing an unvalidated manifest is meaningless for comparison — call [`Self::validate`]
+    /// first; the assessment path does.
+    #[must_use]
+    pub fn canonical_bytes(&self) -> Vec<u8> {
+        let mut out = Vec::new();
+        out.extend_from_slice(&self.schema_version.to_be_bytes());
+        self.weights.append_canonical(&mut out);
+        self.architecture.append_canonical(&mut out);
+        self.tokenizer.append_canonical(&mut out);
+        self.conversion.append_canonical(&mut out);
+        self.artifact.append_canonical(&mut out);
+        out
+    }
+
+    /// Keyed BLAKE2b-512 of [`Self::canonical_bytes`] under
+    /// [`PALW_MODEL_GENESIS_V1_HASH_DOMAIN`].
+    ///
+    /// This is the value ADR-0047 requires to be bit-exact between the two parties.
+    #[must_use]
+    pub fn manifest_hash(&self) -> Hash64 {
+        let mut out = [0u8; 64];
+        out.copy_from_slice(
+            blake2b_simd::Params::new()
+                .hash_length(64)
+                .key(PALW_MODEL_GENESIS_V1_HASH_DOMAIN)
+                .to_state()
+                .update(&self.canonical_bytes())
+                .finalize()
+                .as_bytes(),
+        );
+        out
+    }
+
+    /// Structural validation: printable ASCII, immutable revision pins, safe relative paths, a
+    /// strictly ascending file list, non-zero geometry, and a backend/host-free conversion.
+    pub fn validate(&self) -> Result<(), ModelGenesisError> {
+        self.validate_weights()?;
+        self.validate_architecture()?;
+        self.validate_conversion()?;
+        if self.tokenizer.tokenizer_vocab_size == 0 {
+            return Err(ModelGenesisError::ZeroField(
+                "tokenizer.tokenizer_vocab_size",
+            ));
+        }
+        if self.artifact.gguf_size == 0 {
+            return Err(ModelGenesisError::ZeroField("artifact.gguf_size"));
+        }
+        Ok(())
+    }
+
+    fn validate_weights(&self) -> Result<(), ModelGenesisError> {
+        let weights = &self.weights;
+        check_ascii("weights.source_id", &weights.source_id)?;
+        check_revision_pin("weights.source_revision", &weights.source_revision)?;
+        if let Some(upstream) = &weights.upstream_of_record {
+            check_ascii("weights.upstream_of_record.source_id", &upstream.source_id)?;
+            check_revision_pin("weights.upstream_of_record.revision", &upstream.revision)?;
+        }
+        if weights.files.is_empty() {
+            return Err(ModelGenesisError::NoWeightFiles);
+        }
+        for file in &weights.files {
+            check_ascii("weights.files.path", &file.path)?;
+            check_relative_path("weights.files.path", &file.path)?;
+        }
+        for pair in weights.files.windows(2) {
+            if pair[0].path >= pair[1].path {
+                return Err(ModelGenesisError::UnsortedFiles(
+                    pair[0].path.clone(),
+                    pair[1].path.clone(),
+                ));
+            }
+        }
+        Ok(())
+    }
+
+    fn validate_architecture(&self) -> Result<(), ModelGenesisError> {
+        let arch = &self.architecture;
+        check_ascii("architecture.architecture", &arch.architecture)?;
+        check_ascii("architecture.parameter_dtype", &arch.parameter_dtype)?;
+        let scalars: [(&'static str, u64); 9] = [
+            ("architecture.hidden_size", u64::from(arch.hidden_size)),
+            ("architecture.layers", u64::from(arch.layers)),
+            (
+                "architecture.attention_heads",
+                u64::from(arch.attention_heads),
+            ),
+            (
+                "architecture.key_value_heads",
+                u64::from(arch.key_value_heads),
+            ),
+            (
+                "architecture.intermediate_size",
+                u64::from(arch.intermediate_size),
+            ),
+            ("architecture.head_dim", u64::from(arch.head_dim)),
+            ("architecture.rope_theta", arch.rope_theta),
+            ("architecture.vocab_size", u64::from(arch.vocab_size)),
+            (
+                "architecture.max_position_embeddings",
+                u64::from(arch.max_position_embeddings),
+            ),
+        ];
+        for (name, value) in scalars {
+            if value == 0 {
+                return Err(ModelGenesisError::ZeroField(name));
+            }
+        }
+        Ok(())
+    }
+
+    fn validate_conversion(&self) -> Result<(), ModelGenesisError> {
+        let conv = &self.conversion;
+        let single: [(&'static str, &str); 4] = [
+            ("converter_repo", conv.converter_repo.as_str()),
+            ("converter_commit", conv.converter_commit.as_str()),
+            ("converter_entrypoint", conv.converter_entrypoint.as_str()),
+            ("quantization", conv.quantization.as_str()),
+        ];
+        for (name, value) in single {
+            check_ascii(name, value)?;
+            check_backend_free(name, value)?;
+        }
+        check_ascii("quantizer_entrypoint", &conv.quantizer_entrypoint)?;
+        check_revision_pin("conversion.converter_commit", &conv.converter_commit)?;
+        check_relative_path(
+            "conversion.converter_entrypoint",
+            &conv.converter_entrypoint,
+        )?;
+        check_relative_path(
+            "conversion.quantizer_entrypoint",
+            &conv.quantizer_entrypoint,
+        )?;
+        for arg in &conv.converter_args {
+            check_ascii("converter_args", arg)?;
+            check_backend_free("converter_args", arg)?;
+        }
+        for arg in &conv.quantizer_args {
+            check_ascii("quantizer_args", arg)?;
+            check_backend_free("quantizer_args", arg)?;
+        }
+        Ok(())
+    }
+
+    /// First field whose value differs, using dotted paths, or `None` when the two manifests are
+    /// identical.
+    ///
+    /// This is the whole point of the type: ADR-0047's acceptance test is a hash comparison, and a
+    /// hash comparison alone tells a failing operator nothing about what to fix.
+    #[must_use]
+    #[allow(clippy::too_many_lines)]
+    pub fn first_mismatch(&self, other: &Self) -> Option<&'static str> {
+        if self.schema_version != other.schema_version {
+            return Some("schema_version");
+        }
+        if self.weights.tier != other.weights.tier {
+            return Some("weights.tier");
+        }
+        if self.weights.source_id != other.weights.source_id {
+            return Some("weights.source_id");
+        }
+        if self.weights.source_revision != other.weights.source_revision {
+            return Some("weights.source_revision");
+        }
+        if self.weights.upstream_of_record != other.weights.upstream_of_record {
+            return Some("weights.upstream_of_record");
+        }
+        if self.weights.files != other.weights.files {
+            return Some("weights.files");
+        }
+        if self.architecture != other.architecture {
+            return Some("architecture");
+        }
+        if self.tokenizer.tokenizer_sha256 != other.tokenizer.tokenizer_sha256 {
+            return Some("tokenizer.tokenizer_sha256");
+        }
+        if self.tokenizer.tokenizer_config_sha256 != other.tokenizer.tokenizer_config_sha256 {
+            return Some("tokenizer.tokenizer_config_sha256");
+        }
+        if self.tokenizer.chat_template_sha256 != other.tokenizer.chat_template_sha256 {
+            return Some("tokenizer.chat_template_sha256");
+        }
+        if self.tokenizer.tokenizer_vocab_size != other.tokenizer.tokenizer_vocab_size {
+            return Some("tokenizer.tokenizer_vocab_size");
+        }
+        if self.conversion != other.conversion {
+            return Some("conversion");
+        }
+        if self.artifact.gguf_sha256 != other.artifact.gguf_sha256 {
+            return Some("artifact.gguf_sha256");
+        }
+        if self.artifact.gguf_size != other.artifact.gguf_size {
+            return Some("artifact.gguf_size");
+        }
+        None
+    }
+}
+
+/// One party's claim to have reproduced the manifest.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ReproductionAttestation {
+    /// Free-form label for the reproducing stack, for example `mac-metal` or `rtx-cuda`.
+    pub party_id: String,
+    /// Stable identity of the *operator* running that stack.
+    ///
+    /// Two stacks owned by the same operator are the weak form of "two parties" that ADR-0047 §1
+    /// records honestly rather than hiding.
+    pub operator_id: String,
+    /// The manifest hash that party computed.
+    pub manifest_hash: Hash64,
+}
+
+/// The set of reproduction claims collected so far.
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct DualReproduction {
+    /// Every claim, in collection order.
+    pub attestations: Vec<ReproductionAttestation>,
+}
+
+/// Strength of the two-party evidence actually held.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum TwoPartyForm {
+    /// Fewer than two matching attestations.
+    None,
+    /// Two or more matching attestations, all from the same operator (ADR-0047 §1 weak form).
+    Weak,
+    /// Two or more matching attestations from distinct operators.
+    Strong,
+}
+
+/// A reason the recorded candidate is not the genesis.
+///
+/// Mirrors the four disqualifiers frozen in `docs/model-genesis-candidate.md`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum GenesisDisqualifier {
+    /// (1) Provenance does not reach official upstream weights.
+    ProvenanceNotOfficial,
+    /// (2) Fewer than two parties produced a matching manifest hash.
+    ConversionNotReproduced,
+    /// (3) The manifest is unsigned, and cannot currently be signed at all.
+    ///
+    /// Unconditional: the ML-DSA-87 signature-domain table is LOCKED, no model-genesis context is
+    /// registered, and this module deliberately exposes no signing function. Only an explicit human
+    /// unlock decision can change that — writing code cannot.
+    ManifestUnsigned,
+    /// (4) The committed compute-set is not the model this manifest describes.
+    ComputeSetNotCommitted,
+}
+
+/// Outcome of [`assess_genesis`].
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct GenesisAssessment {
+    /// Always `false` today; see [`GenesisDisqualifier::ManifestUnsigned`].
+    pub eligible: bool,
+    /// Every disqualifier that applies, in stable order.
+    pub disqualifiers: Vec<GenesisDisqualifier>,
+    /// Strength of the reproduction evidence held.
+    pub two_party_form: TwoPartyForm,
+    /// Structural validation error, when the manifest itself does not validate.
+    pub validation_error: Option<ModelGenesisError>,
+}
+
+/// Assess how far a candidate is from being a model genesis.
+///
+/// `compute_set_committed` is supplied by the caller because it is a Receipt-v3 / compute-set
+/// question, out of ADR-0047's scope; it is disqualifier (4) of the candidate document.
+#[must_use]
+pub fn assess_genesis(
+    manifest: &ModelGenesisManifest,
+    reproduction: &DualReproduction,
+    compute_set_committed: bool,
+) -> GenesisAssessment {
+    let validation_error = manifest.validate().err();
+    let expected = manifest.manifest_hash();
+    let matching: Vec<&ReproductionAttestation> = reproduction
+        .attestations
+        .iter()
+        .filter(|attestation| attestation.manifest_hash == expected)
+        .collect();
+    let distinct_operators = {
+        let mut operators: Vec<&str> = matching
+            .iter()
+            .map(|attestation| attestation.operator_id.as_str())
+            .collect();
+        operators.sort_unstable();
+        operators.dedup();
+        operators.len()
+    };
+    let two_party_form = if matching.len() < 2 {
+        TwoPartyForm::None
+    } else if distinct_operators >= 2 {
+        TwoPartyForm::Strong
+    } else {
+        TwoPartyForm::Weak
+    };
+
+    let mut disqualifiers = Vec::new();
+    if manifest.weights.tier != ProvenanceTier::OfficialUpstream {
+        disqualifiers.push(GenesisDisqualifier::ProvenanceNotOfficial);
+    }
+    if matching.len() < 2 || validation_error.is_some() {
+        disqualifiers.push(GenesisDisqualifier::ConversionNotReproduced);
+    }
+    // Unconditional — no registered signature context exists, so no signature can exist.
+    disqualifiers.push(GenesisDisqualifier::ManifestUnsigned);
+    if !compute_set_committed {
+        disqualifiers.push(GenesisDisqualifier::ComputeSetNotCommitted);
+    }
+
+    GenesisAssessment {
+        eligible: disqualifiers.is_empty(),
+        disqualifiers,
+        two_party_form,
+        validation_error,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// The golden manifest. The identical structure is rebuilt independently by
+    /// `scripts/model_genesis_manifest.py --selftest`; the two implementations agreeing on
+    /// [`GOLDEN_MANIFEST_HASH_HEX`] is the cross-implementation parity check.
+    fn golden_manifest() -> ModelGenesisManifest {
+        ModelGenesisManifest {
+            schema_version: MODEL_GENESIS_SCHEMA_V1,
+            weights: WeightsProvenance {
+                tier: ProvenanceTier::OfficialUpstream,
+                source_id: "Example/Model-Genesis-Golden".to_owned(),
+                source_revision: "0123456789abcdef0123456789abcdef01234567".to_owned(),
+                upstream_of_record: None,
+                files: vec![
+                    WeightFile {
+                        path: "config.json".to_owned(),
+                        sha256: [0x11; 32],
+                        size: 1024,
+                    },
+                    WeightFile {
+                        path: "model-00001-of-00002.safetensors".to_owned(),
+                        sha256: [0x22; 32],
+                        size: 4_294_967_296,
+                    },
+                    WeightFile {
+                        path: "model-00002-of-00002.safetensors".to_owned(),
+                        sha256: [0x33; 32],
+                        size: 2_147_483_648,
+                    },
+                    WeightFile {
+                        path: "tokenizer.json".to_owned(),
+                        sha256: [0x44; 32],
+                        size: 11_534_336,
+                    },
+                ],
+            },
+            architecture: ModelArchitecture {
+                architecture: "Qwen3ForCausalLM".to_owned(),
+                hidden_size: 4096,
+                layers: 36,
+                attention_heads: 32,
+                key_value_heads: 8,
+                intermediate_size: 12288,
+                head_dim: 128,
+                rope_theta: 1_000_000,
+                vocab_size: 151_936,
+                max_position_embeddings: 40960,
+                parameter_dtype: "bfloat16".to_owned(),
+            },
+            tokenizer: TokenizerIdentity {
+                tokenizer_sha256: [0x44; 32],
+                tokenizer_config_sha256: [0x55; 32],
+                chat_template_sha256: [0x66; 32],
+                tokenizer_vocab_size: 151_936,
+            },
+            conversion: ConversionProcedure {
+                converter_repo: "https://github.com/ggml-org/llama.cpp.git".to_owned(),
+                converter_commit: "12127defda4f41b7679cb2477a4b0d65ee6a0c8f".to_owned(),
+                converter_entrypoint: "convert_hf_to_gguf.py".to_owned(),
+                converter_args: vec!["--outtype".to_owned(), "bf16".to_owned()],
+                quantizer_entrypoint: "llama-quantize".to_owned(),
+                quantizer_args: Vec::new(),
+                quantization: "Q4_K_M".to_owned(),
+            },
+            artifact: DerivedArtifact {
+                gguf_sha256: [0x77; 32],
+                gguf_size: 23_938_321_728,
+            },
+        }
+    }
+
+    const GOLDEN_MANIFEST_HASH_HEX: &str = concat!(
+        "b747790722bdf626a263f222c794a02ac3d32a08436bbc11a5af1f7cfaecc1b8",
+        "262474f15a819b4858b14fe49643c2445c771d8c8a0919bc107361ecf756d9b3"
+    );
+
+    #[test]
+    fn golden_vector_is_pinned() {
+        let manifest = golden_manifest();
+        manifest.validate().expect("golden manifest validates");
+        assert_eq!(
+            hex::encode(manifest.manifest_hash()),
+            GOLDEN_MANIFEST_HASH_HEX
+        );
+    }
+
+    #[test]
+    fn encoding_is_deterministic() {
+        let a = golden_manifest();
+        let b = golden_manifest();
+        assert_eq!(a.canonical_bytes(), b.canonical_bytes());
+        assert_eq!(a.manifest_hash(), b.manifest_hash());
+        assert_eq!(a.first_mismatch(&b), None);
+    }
+
+    #[test]
+    fn domain_separation_from_other_palw_digest_spaces() {
+        let bytes = golden_manifest().canonical_bytes();
+        let under_file_domain = blake2b_simd::Params::new()
+            .hash_length(64)
+            .key(b"palw-k1/file")
+            .to_state()
+            .update(&bytes)
+            .finalize();
+        assert_ne!(
+            golden_manifest().manifest_hash().as_slice(),
+            under_file_domain.as_bytes(),
+            "identical bytes under a different domain must not produce the same digest"
+        );
+    }
+
+    #[test]
+    fn encoding_is_prefix_free_across_adjacent_fields() {
+        let mut a = golden_manifest();
+        let mut b = golden_manifest();
+        a.weights.source_id = "ab".to_owned();
+        a.architecture.architecture = "c".to_owned();
+        b.weights.source_id = "a".to_owned();
+        b.architecture.architecture = "bc".to_owned();
+        assert_ne!(a.canonical_bytes(), b.canonical_bytes());
+        assert_ne!(a.manifest_hash(), b.manifest_hash());
+    }
+
+    /// One single-field mutation applied to a copy of the golden manifest.
+    type Mutator = fn(&mut ModelGenesisManifest);
+
+    #[test]
+    #[allow(clippy::too_many_lines)]
+    fn every_field_changes_the_hash() {
+        let base = golden_manifest();
+        let baseline = base.manifest_hash();
+        let mutators: Vec<(&str, Mutator)> = vec![
+            ("schema_version", |m| m.schema_version += 1),
+            ("weights.tier", |m| {
+                m.weights.tier = ProvenanceTier::ThirdPartyDerivative;
+            }),
+            ("weights.source_id", |m| m.weights.source_id.push('x')),
+            ("weights.source_revision", |m| {
+                m.weights.source_revision = "0123456789abcdef0123456789abcdef01234568".to_owned();
+            }),
+            ("weights.upstream_of_record", |m| {
+                m.weights.upstream_of_record = Some(UpstreamRef {
+                    source_id: "Example/Upstream".to_owned(),
+                    revision: "89abcdef0123456789abcdef0123456789abcdef".to_owned(),
+                });
+            }),
+            ("weights.files.path", |m| {
+                m.weights.files[0].path = "confiig.json".to_owned();
+            }),
+            ("weights.files.sha256", |m| {
+                m.weights.files[0].sha256[31] ^= 1;
+            }),
+            ("weights.files.size", |m| m.weights.files[0].size += 1),
+            ("architecture.architecture", |m| {
+                m.architecture.architecture.push('X');
+            }),
+            ("architecture.hidden_size", |m| {
+                m.architecture.hidden_size += 1;
+            }),
+            ("architecture.layers", |m| m.architecture.layers += 1),
+            ("architecture.attention_heads", |m| {
+                m.architecture.attention_heads += 1;
+            }),
+            ("architecture.key_value_heads", |m| {
+                m.architecture.key_value_heads += 1;
+            }),
+            ("architecture.intermediate_size", |m| {
+                m.architecture.intermediate_size += 1;
+            }),
+            ("architecture.head_dim", |m| m.architecture.head_dim += 1),
+            ("architecture.rope_theta", |m| {
+                m.architecture.rope_theta += 1;
+            }),
+            ("architecture.vocab_size", |m| {
+                m.architecture.vocab_size += 1;
+            }),
+            ("architecture.max_position_embeddings", |m| {
+                m.architecture.max_position_embeddings += 1;
+            }),
+            ("architecture.parameter_dtype", |m| {
+                m.architecture.parameter_dtype = "float16".to_owned();
+            }),
+            ("tokenizer.tokenizer_sha256", |m| {
+                m.tokenizer.tokenizer_sha256[0] ^= 1;
+            }),
+            ("tokenizer.tokenizer_config_sha256", |m| {
+                m.tokenizer.tokenizer_config_sha256[0] ^= 1;
+            }),
+            ("tokenizer.chat_template_sha256", |m| {
+                m.tokenizer.chat_template_sha256[0] ^= 1;
+            }),
+            ("tokenizer.tokenizer_vocab_size", |m| {
+                m.tokenizer.tokenizer_vocab_size += 1;
+            }),
+            ("conversion.converter_repo", |m| {
+                m.conversion.converter_repo.push('/');
+            }),
+            ("conversion.converter_commit", |m| {
+                m.conversion.converter_commit =
+                    "12127defda4f41b7679cb2477a4b0d65ee6a0c8e".to_owned();
+            }),
+            ("conversion.converter_entrypoint", |m| {
+                m.conversion.converter_entrypoint = "convert.py".to_owned();
+            }),
+            ("conversion.converter_args", |m| {
+                m.conversion.converter_args.push("f32".to_owned());
+            }),
+            ("conversion.quantizer_entrypoint", |m| {
+                m.conversion.quantizer_entrypoint = "quantize".to_owned();
+            }),
+            ("conversion.quantizer_args", |m| {
+                m.conversion.quantizer_args.push("--pure".to_owned());
+            }),
+            ("conversion.quantization", |m| {
+                m.conversion.quantization = "Q5_K_M".to_owned();
+            }),
+            ("artifact.gguf_sha256", |m| m.artifact.gguf_sha256[17] ^= 1),
+            ("artifact.gguf_size", |m| m.artifact.gguf_size -= 1),
+        ];
+        let mut seen = Vec::new();
+        for (name, mutate) in mutators {
+            let mut mutated = base.clone();
+            mutate(&mut mutated);
+            let hash = mutated.manifest_hash();
+            assert_ne!(
+                hash, baseline,
+                "{name}: mutation did not change the manifest hash"
+            );
+            assert!(
+                base.first_mismatch(&mutated).is_some(),
+                "{name}: diff did not report a field"
+            );
+            assert!(
+                !seen.contains(&hash),
+                "{name}: mutation collided with another mutation"
+            );
+            seen.push(hash);
+        }
+    }
+
+    #[test]
+    fn backend_specific_conversion_is_rejected() {
+        for bad in ["--n-gpu-layers", "-ngl", "CUDA", "metal", "--threads"] {
+            let mut manifest = golden_manifest();
+            manifest.conversion.converter_args = vec![bad.to_owned()];
+            assert!(
+                matches!(
+                    manifest.validate(),
+                    Err(ModelGenesisError::BackendSpecificField { .. })
+                ),
+                "{bad}: backend/host-specific argument must be rejected"
+            );
+        }
+    }
+
+    #[test]
+    fn host_paths_and_mutable_pins_are_rejected() {
+        let mut absolute = golden_manifest();
+        absolute.weights.files[0].path = "/Users/operator/config.json".to_owned();
+        assert!(matches!(
+            absolute.validate(),
+            Err(ModelGenesisError::UnsafePath { .. })
+        ));
+
+        let mut traversal = golden_manifest();
+        traversal.conversion.converter_entrypoint = "../convert_hf_to_gguf.py".to_owned();
+        assert!(matches!(
+            traversal.validate(),
+            Err(ModelGenesisError::UnsafePath { .. })
+        ));
+
+        let mut branch = golden_manifest();
+        branch.weights.source_revision = "main".to_owned();
+        assert!(matches!(
+            branch.validate(),
+            Err(ModelGenesisError::NotARevisionPin { .. })
+        ));
+
+        let mut unsorted = golden_manifest();
+        unsorted.weights.files.swap(0, 1);
+        assert!(matches!(
+            unsorted.validate(),
+            Err(ModelGenesisError::UnsortedFiles(..))
+        ));
+
+        let mut non_ascii = golden_manifest();
+        non_ascii.weights.source_id = "Example/モデル".to_owned();
+        assert!(matches!(
+            non_ascii.validate(),
+            Err(ModelGenesisError::NonPrintableAscii { .. })
+        ));
+    }
+
+    fn attestation(party: &str, operator: &str, hash: Hash64) -> ReproductionAttestation {
+        ReproductionAttestation {
+            party_id: party.to_owned(),
+            operator_id: operator.to_owned(),
+            manifest_hash: hash,
+        }
+    }
+
+    #[test]
+    fn no_input_can_produce_an_eligible_genesis() {
+        let manifest = golden_manifest();
+        let hash = manifest.manifest_hash();
+        // The most favourable input that can exist in-repo: official tier, two independent
+        // operators matching bit-exactly, compute-set committed.
+        let best = DualReproduction {
+            attestations: vec![
+                attestation("mac-metal", "operator-a", hash),
+                attestation("rtx-cuda", "operator-b", hash),
+            ],
+        };
+        let assessment = assess_genesis(&manifest, &best, true);
+        assert!(
+            !assessment.eligible,
+            "genesis must never be reachable by writing code"
+        );
+        assert_eq!(
+            assessment.disqualifiers,
+            vec![GenesisDisqualifier::ManifestUnsigned]
+        );
+        assert_eq!(assessment.two_party_form, TwoPartyForm::Strong);
+        assert!(assessment.validation_error.is_none());
+    }
+
+    #[test]
+    fn same_operator_two_stacks_is_only_the_weak_form() {
+        let manifest = golden_manifest();
+        let hash = manifest.manifest_hash();
+        let weak = DualReproduction {
+            attestations: vec![
+                attestation("mac-metal", "operator-a", hash),
+                attestation("rtx-cuda", "operator-a", hash),
+            ],
+        };
+        assert_eq!(
+            assess_genesis(&manifest, &weak, true).two_party_form,
+            TwoPartyForm::Weak
+        );
+    }
+
+    #[test]
+    fn current_pins_record_every_candidate_disqualifier() {
+        // The shape of the pins actually in `config/runtime-pins.sh`: a third-party abliterated
+        // derivative, one party, and a compute-set that is the integer-canonical 0.5B set.
+        let mut manifest = golden_manifest();
+        manifest.weights.tier = ProvenanceTier::ThirdPartyDerivative;
+        manifest.weights.source_id =
+            "huihui-ai/Huihui-Qwen3.6-35B-A3B-Claude-4.7-Opus-abliterated".to_owned();
+        manifest.weights.source_revision = "ac18882735d037f6074a7630eb68d85db8234c25".to_owned();
+        let alone = DualReproduction {
+            attestations: vec![attestation(
+                "mac-metal",
+                "operator-a",
+                manifest.manifest_hash(),
+            )],
+        };
+        let assessment = assess_genesis(&manifest, &alone, false);
+        assert_eq!(
+            assessment.disqualifiers,
+            vec![
+                GenesisDisqualifier::ProvenanceNotOfficial,
+                GenesisDisqualifier::ConversionNotReproduced,
+                GenesisDisqualifier::ManifestUnsigned,
+                GenesisDisqualifier::ComputeSetNotCommitted,
+            ]
+        );
+        assert_eq!(assessment.two_party_form, TwoPartyForm::None);
+    }
+
+    #[test]
+    fn proposed_context_is_distinct_and_prefix_free() {
+        use crate::receipt_v3::{PALW_JOBSPEC_V2_MLDSA87_CONTEXT, PALW_RECEIPT_V3_MLDSA87_CONTEXT};
+        let known: [&[u8]; 2] = [
+            PALW_RECEIPT_V3_MLDSA87_CONTEXT,
+            PALW_JOBSPEC_V2_MLDSA87_CONTEXT,
+        ];
+        for other in known {
+            assert_ne!(PALW_MODEL_GENESIS_V1_MLDSA87_CONTEXT_UNREGISTERED, other);
+            assert!(!PALW_MODEL_GENESIS_V1_MLDSA87_CONTEXT_UNREGISTERED.starts_with(other));
+            assert!(!other.starts_with(PALW_MODEL_GENESIS_V1_MLDSA87_CONTEXT_UNREGISTERED));
+        }
+        // The hash domain and the signature context live in different namespaces, but keeping them
+        // textually distinct removes any chance of one being pasted where the other belongs.
+        assert_ne!(
+            PALW_MODEL_GENESIS_V1_HASH_DOMAIN,
+            PALW_MODEL_GENESIS_V1_MLDSA87_CONTEXT_UNREGISTERED
+        );
+    }
+}

scripts/model_genesis_manifest.py

@@ -0,0 +1,716 @@
+#!/usr/bin/env python3
+"""Deterministic model-genesis conversion and manifest tool (ADR-0047 prerequisite).
+
+ADR-0047 fixes the two-party reproduction protocol but its acceptance criterion — a bit-exact
+`ModelGenesisManifest` hash match between two operators — was unevaluable, because no tool built
+the manifest.  This script is the procedure both operators run, so that two runs are comparable.
+
+It is an independent reimplementation of `runtime-palw/src/model_genesis.rs`.  The two
+implementations agreeing on the pinned golden vector (`selftest`) is the parity check; a silent
+divergence between them would make a cross-operator mismatch unattributable.
+
+Honesty boundary (do not paper over it):
+
+  * The weight pins currently shipped in ``config/runtime-pins.sh`` terminate at a THIRD-PARTY
+    "abliterated" derivative, not official Alibaba weights.  A manifest built from them is
+    reproducible but can never be the genesis — the tier is recorded in the hash, and
+    ``--provenance-tier third-party-derivative`` is what those pins require.
+  * Nothing here signs anything.  The ML-DSA-87 signature-domain table is LOCKED (2026-07-25);
+    the model-genesis context is not registered, so a signed manifest cannot be produced.
+  * Every command fails closed.  Missing weights, a missing converter, a missing quantizer, or an
+    unpinned checkout is an error naming exactly what is absent — never a manifest built from
+    inputs that were not there.
+
+Subcommands
+-----------
+  selftest   Re-derive the golden vector and compare with the Rust golden constant.
+  convert    Check every precondition and emit the exact conversion argv (runs it with --execute).
+  manifest   Hash real local inputs and emit manifest JSON + its keyed-BLAKE2b-512 hash.
+  verify     Compare two or more manifest JSON files; report the first differing field.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+SCHEMA_NAME = "misaka.palw.model-genesis.v1"
+SCHEMA_VERSION = 1
+
+# Keyed-BLAKE2b-512 domain.  Distinct from every receipt/file domain (`palw-k1/file`,
+# `misaka-palw-v3/...`): identical bytes under a different domain must not collide, or a commitment
+# over one object class silently becomes a commitment over another.
+HASH_DOMAIN = b"misaka-palw-v1/model-genesis"
+
+# The ML-DSA-87 context a signed genesis WOULD need.  UNREGISTERED — the signature-domain table is
+# LOCKED and adding a row is an explicit human unlock decision.  Recorded, never used.
+MLDSA87_CONTEXT_UNREGISTERED = b"misaka-palw-v1/model-genesis/mldsa87"
+
+# Pinned in runtime-palw/src/model_genesis.rs::tests::GOLDEN_MANIFEST_HASH_HEX.
+GOLDEN_MANIFEST_HASH_HEX = (
+    "b747790722bdf626a263f222c794a02ac3d32a08436bbc11a5af1f7cfaecc1b8"
+    "262474f15a819b4858b14fe49643c2445c771d8c8a0919bc107361ecf756d9b3"
+)
+
+PROVENANCE_TIER_TAGS = {"official-upstream": 0, "third-party-derivative": 1}
+
+# Mirrors BACKEND_TOKENS in model_genesis.rs.  Short ambiguous substrings are excluded on purpose.
+BACKEND_TOKENS = (
+    "metal", "cuda", "cublas", "rocm", "vulkan", "sycl", "opencl", "gpu", "ngl",
+    "device", "thread", "darwin", "arm64", "x86_64", "avx", "neon",
+)
+
+REQUIRED_METADATA_FILES = ("config.json", "tokenizer.json", "tokenizer_config.json")
+HASH_CHUNK_BYTES = 1 << 22
+
+
+class FailClosed(SystemExit):
+    """Abort with an explicit message naming what was missing or wrong."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(f"model-genesis: {message}")
+
+
+# --------------------------------------------------------------------------------------------
+# canonical encoding — byte-for-byte identical to runtime-palw/src/model_genesis.rs
+# --------------------------------------------------------------------------------------------
+
+
+def _framed(value: bytes) -> bytes:
+    return len(value).to_bytes(8, "big") + value
+
+
+def _text(field: str, value: Any) -> bytes:
+    if not isinstance(value, str):
+        raise FailClosed(f"{field}: expected a string, got {type(value).__name__}")
+    for index, byte in enumerate(value.encode("utf-8")):
+        if not 0x20 <= byte <= 0x7E:
+            raise FailClosed(f"{field}: byte {index} is outside printable ASCII")
+    return value.encode("ascii")
+
+
+def _u(field: str, value: Any, width: int) -> bytes:
+    if not isinstance(value, int) or isinstance(value, bool) or value < 0:
+        raise FailClosed(f"{field}: expected a non-negative integer, got {value!r}")
+    if value >> (width * 8):
+        raise FailClosed(f"{field}: {value} does not fit in u{width * 8}")
+    return value.to_bytes(width, "big")
+
+
+def _digest(field: str, value: Any) -> bytes:
+    if not isinstance(value, str) or len(value) != 64 or any(c not in "0123456789abcdef" for c in value):
+        raise FailClosed(f"{field}: expected 64 lowercase hex characters, got {value!r}")
+    return bytes.fromhex(value)
+
+
+def _string_list(field: str, values: Any) -> bytes:
+    if not isinstance(values, list):
+        raise FailClosed(f"{field}: expected a list")
+    out = len(values).to_bytes(8, "big")
+    for index, value in enumerate(values):
+        out += _framed(_text(f"{field}[{index}]", value))
+    return out
+
+
+def canonical_bytes(manifest: dict[str, Any]) -> bytes:
+    """Canonical encoding: big-endian integers, u64-length-framed variable fields, declaration order."""
+    weights = manifest["weights"]
+    arch = manifest["architecture"]
+    tok = manifest["tokenizer"]
+    conv = manifest["conversion"]
+    art = manifest["artifact"]
+
+    tier = weights["tier"]
+    if tier not in PROVENANCE_TIER_TAGS:
+        raise FailClosed(f"weights.tier: unknown tier {tier!r}")
+
+    out = _u("schema_version", manifest["schema_version"], 2)
+    out += bytes([PROVENANCE_TIER_TAGS[tier]])
+    out += _framed(_text("weights.source_id", weights["source_id"]))
+    out += _framed(_text("weights.source_revision", weights["source_revision"]))
+    upstream = weights.get("upstream_of_record")
+    if upstream is None:
+        out += b"\x00"
+    else:
+        out += b"\x01"
+        out += _framed(_text("weights.upstream_of_record.source_id", upstream["source_id"]))
+        out += _framed(_text("weights.upstream_of_record.revision", upstream["revision"]))
+    files = weights["files"]
+    out += len(files).to_bytes(8, "big")
+    for entry in files:
+        out += _framed(_text("weights.files.path", entry["path"]))
+        out += _digest("weights.files.sha256", entry["sha256"])
+        out += _u("weights.files.size", entry["size"], 8)
+
+    out += _framed(_text("architecture.architecture", arch["architecture"]))
+    for name in (
+        "hidden_size",
+        "layers",
+        "attention_heads",
+        "key_value_heads",
+        "intermediate_size",
+        "head_dim",
+    ):
+        out += _u(f"architecture.{name}", arch[name], 4)
+    out += _u("architecture.rope_theta", arch["rope_theta"], 8)
+    out += _u("architecture.vocab_size", arch["vocab_size"], 4)
+    out += _u("architecture.max_position_embeddings", arch["max_position_embeddings"], 4)
+    out += _framed(_text("architecture.parameter_dtype", arch["parameter_dtype"]))
+
+    out += _digest("tokenizer.tokenizer_sha256", tok["tokenizer_sha256"])
+    out += _digest("tokenizer.tokenizer_config_sha256", tok["tokenizer_config_sha256"])
+    out += _digest("tokenizer.chat_template_sha256", tok["chat_template_sha256"])
+    out += _u("tokenizer.tokenizer_vocab_size", tok["tokenizer_vocab_size"], 4)
+
+    out += _framed(_text("conversion.converter_repo", conv["converter_repo"]))
+    out += _framed(_text("conversion.converter_commit", conv["converter_commit"]))
+    out += _framed(_text("conversion.converter_entrypoint", conv["converter_entrypoint"]))
+    out += _string_list("conversion.converter_args", conv["converter_args"])
+    out += _framed(_text("conversion.quantizer_entrypoint", conv["quantizer_entrypoint"]))
+    out += _string_list("conversion.quantizer_args", conv["quantizer_args"])
+    out += _framed(_text("conversion.quantization", conv["quantization"]))
+
+    out += _digest("artifact.gguf_sha256", art["gguf_sha256"])
+    out += _u("artifact.gguf_size", art["gguf_size"], 8)
+    return out
+
+
+def manifest_hash(manifest: dict[str, Any]) -> str:
+    """Keyed BLAKE2b-512 of the canonical bytes, hex — the value ADR-0047 compares between parties."""
+    return hashlib.blake2b(canonical_bytes(manifest), key=HASH_DOMAIN, digest_size=64).hexdigest()
+
+
+# --------------------------------------------------------------------------------------------
+# validation — mirrors ModelGenesisManifest::validate
+# --------------------------------------------------------------------------------------------
+
+
+def _check_revision_pin(field: str, value: str) -> None:
+    if len(value) not in (40, 64) or any(c not in "0123456789abcdef" for c in value):
+        raise FailClosed(
+            f"{field}: {value!r} is not an immutable revision pin (40 or 64 lowercase hex). "
+            "A branch or tag name is not reproducible."
+        )
+
+
+def _check_relative_path(field: str, value: str) -> None:
+    parts = value.split("/")
+    if not value or value.startswith("/") or value.startswith("~") or any(p in ("", "..") for p in parts):
+        raise FailClosed(f"{field}: {value!r} must be a relative, traversal-free path")
+
+
+def _check_backend_free(field: str, value: str) -> None:
+    lowered = value.lower()
+    for token in BACKEND_TOKENS:
+        if token in lowered:
+            raise FailClosed(
+                f"conversion.{field}: contains {token!r} — the manifest must be weights-derived only; "
+                "a backend/host-specific input makes the two-party comparison meaningless (ADR-0047 §1)"
+            )
+
+
+def validate(manifest: dict[str, Any]) -> None:
+    """Reject anything that would make two operators' manifests incomparable."""
+    weights = manifest["weights"]
+    _check_revision_pin("weights.source_revision", weights["source_revision"])
+    upstream = weights.get("upstream_of_record")
+    if upstream is not None:
+        _check_revision_pin("weights.upstream_of_record.revision", upstream["revision"])
+    files = weights["files"]
+    if not files:
+        raise FailClosed("weights.files: at least one weight file must be recorded")
+    for entry in files:
+        _check_relative_path("weights.files.path", entry["path"])
+    for previous, following in zip(files, files[1:]):
+        if previous["path"] >= following["path"]:
+            raise FailClosed(
+                f"weights.files: must be strictly ascending by path "
+                f"({previous['path']!r} is not before {following['path']!r})"
+            )
+
+    arch = manifest["architecture"]
+    for name in (
+        "hidden_size",
+        "layers",
+        "attention_heads",
+        "key_value_heads",
+        "intermediate_size",
+        "head_dim",
+        "rope_theta",
+        "vocab_size",
+        "max_position_embeddings",
+    ):
+        if arch[name] == 0:
+            raise FailClosed(f"architecture.{name}: must be non-zero")
+    if manifest["tokenizer"]["tokenizer_vocab_size"] == 0:
+        raise FailClosed("tokenizer.tokenizer_vocab_size: must be non-zero")
+    if manifest["artifact"]["gguf_size"] == 0:
+        raise FailClosed("artifact.gguf_size: must be non-zero")
+
+    conv = manifest["conversion"]
+    for name in ("converter_repo", "converter_commit", "converter_entrypoint", "quantization"):
+        _check_backend_free(name, conv[name])
+    for name in ("converter_args", "quantizer_args"):
+        for arg in conv[name]:
+            _check_backend_free(name, arg)
+    _check_revision_pin("conversion.converter_commit", conv["converter_commit"])
+    _check_relative_path("conversion.converter_entrypoint", conv["converter_entrypoint"])
+    _check_relative_path("conversion.quantizer_entrypoint", conv["quantizer_entrypoint"])
+    canonical_bytes(manifest)
+
+
+FIELD_ORDER = (
+    ("schema_version", lambda m: m["schema_version"]),
+    ("weights.tier", lambda m: m["weights"]["tier"]),
+    ("weights.source_id", lambda m: m["weights"]["source_id"]),
+    ("weights.source_revision", lambda m: m["weights"]["source_revision"]),
+    ("weights.upstream_of_record", lambda m: m["weights"].get("upstream_of_record")),
+    ("weights.files", lambda m: m["weights"]["files"]),
+    ("architecture", lambda m: m["architecture"]),
+    ("tokenizer.tokenizer_sha256", lambda m: m["tokenizer"]["tokenizer_sha256"]),
+    ("tokenizer.tokenizer_config_sha256", lambda m: m["tokenizer"]["tokenizer_config_sha256"]),
+    ("tokenizer.chat_template_sha256", lambda m: m["tokenizer"]["chat_template_sha256"]),
+    ("tokenizer.tokenizer_vocab_size", lambda m: m["tokenizer"]["tokenizer_vocab_size"]),
+    ("conversion", lambda m: m["conversion"]),
+    ("artifact.gguf_sha256", lambda m: m["artifact"]["gguf_sha256"]),
+    ("artifact.gguf_size", lambda m: m["artifact"]["gguf_size"]),
+)
+
+
+def first_mismatch(left: dict[str, Any], right: dict[str, Any]) -> str | None:
+    """First differing field, dotted — mirrors ModelGenesisManifest::first_mismatch."""
+    for name, getter in FIELD_ORDER:
+        if getter(left) != getter(right):
+            return name
+    return None
+
+
+# --------------------------------------------------------------------------------------------
+# local input hashing
+# --------------------------------------------------------------------------------------------
+
+
+def sha256_file(path: Path) -> tuple[str, int]:
+    digest = hashlib.sha256()
+    size = 0
+    with path.open("rb") as handle:
+        while chunk := handle.read(HASH_CHUNK_BYTES):
+            digest.update(chunk)
+            size += len(chunk)
+    return digest.hexdigest(), size
+
+
+def collect_weight_files(weights_dir: Path) -> list[dict[str, Any]]:
+    """Hash every file under ``weights_dir``, failing closed on an empty or weightless directory."""
+    if not weights_dir.is_dir():
+        raise FailClosed(f"--weights-dir {weights_dir} does not exist")
+    entries: list[dict[str, Any]] = []
+    for path in sorted(weights_dir.rglob("*")):
+        if not path.is_file() or path.is_symlink():
+            continue
+        relative = path.relative_to(weights_dir).as_posix()
+        if relative.startswith(".") or "/." in relative:
+            continue
+        sha256, size = sha256_file(path)
+        entries.append({"path": relative, "sha256": sha256, "size": size})
+    if not entries:
+        raise FailClosed(f"--weights-dir {weights_dir} contains no files")
+    names = {entry["path"] for entry in entries}
+    missing = [name for name in REQUIRED_METADATA_FILES if name not in names]
+    if missing:
+        raise FailClosed(
+            f"--weights-dir {weights_dir} is missing required checkpoint files: {', '.join(missing)}"
+        )
+    if not any(entry["path"].endswith((".safetensors", ".bin")) for entry in entries):
+        raise FailClosed(
+            f"--weights-dir {weights_dir} contains metadata only — no *.safetensors/*.bin weight "
+            "shards were found. Download the full checkpoint; a manifest must never be built from "
+            "absent weights."
+        )
+    entries.sort(key=lambda entry: entry["path"])
+    return entries
+
+
+def architecture_from_config(config_path: Path) -> dict[str, Any]:
+    config = json.loads(config_path.read_text(encoding="utf-8"))
+    architectures = config.get("architectures")
+    if not isinstance(architectures, list) or not architectures:
+        raise FailClosed(f"{config_path}: 'architectures' is missing or empty")
+    rope_theta = config.get("rope_theta")
+    if isinstance(rope_theta, float):
+        if not rope_theta.is_integer():
+            raise FailClosed(
+                f"{config_path}: rope_theta={rope_theta} is non-integral. Extend the manifest schema "
+                "rather than rounding — rounding is a per-implementation difference and would break "
+                "the bit-exact comparison."
+            )
+        rope_theta = int(rope_theta)
+    mapping = {
+        "hidden_size": "hidden_size",
+        "layers": "num_hidden_layers",
+        "attention_heads": "num_attention_heads",
+        "key_value_heads": "num_key_value_heads",
+        "intermediate_size": "intermediate_size",
+        "head_dim": "head_dim",
+        "vocab_size": "vocab_size",
+        "max_position_embeddings": "max_position_embeddings",
+    }
+    architecture: dict[str, Any] = {"architecture": architectures[0]}
+    for field, key in mapping.items():
+        value = config.get(key)
+        if not isinstance(value, int) or isinstance(value, bool):
+            raise FailClosed(f"{config_path}: {key!r} is missing or not an integer")
+        architecture[field] = value
+    architecture["rope_theta"] = rope_theta
+    architecture["parameter_dtype"] = config.get("torch_dtype") or config.get("dtype")
+    if not isinstance(architecture["parameter_dtype"], str):
+        raise FailClosed(f"{config_path}: 'torch_dtype'/'dtype' is missing")
+    ordered = (
+        "architecture", "hidden_size", "layers", "attention_heads", "key_value_heads",
+        "intermediate_size", "head_dim", "rope_theta", "vocab_size",
+        "max_position_embeddings", "parameter_dtype",
+    )
+    return {key: architecture[key] for key in ordered}
+
+
+def tokenizer_vocab_size(tokenizer_path: Path) -> int:
+    """Highest token id + 1 — a single unambiguous rule, so both operators compute the same number."""
+    tokenizer = json.loads(tokenizer_path.read_text(encoding="utf-8"))
+    ids: list[int] = []
+    vocab = tokenizer.get("model", {}).get("vocab")
+    if isinstance(vocab, dict):
+        ids.extend(int(value) for value in vocab.values())
+    elif isinstance(vocab, list):
+        ids.extend(range(len(vocab)))
+    else:
+        raise FailClosed(f"{tokenizer_path}: 'model.vocab' is missing or has an unsupported shape")
+    for token in tokenizer.get("added_tokens", []) or []:
+        if isinstance(token, dict) and isinstance(token.get("id"), int):
+            ids.append(token["id"])
+    if not ids:
+        raise FailClosed(f"{tokenizer_path}: no token ids found")
+    return max(ids) + 1
+
+
+# --------------------------------------------------------------------------------------------
+# subcommands
+# --------------------------------------------------------------------------------------------
+
+
+def golden_manifest() -> dict[str, Any]:
+    """The vector duplicated in runtime-palw/src/model_genesis.rs::tests::golden_manifest."""
+    return {
+        "schema": SCHEMA_NAME,
+        "schema_version": SCHEMA_VERSION,
+        "weights": {
+            "tier": "official-upstream",
+            "source_id": "Example/Model-Genesis-Golden",
+            "source_revision": "0123456789abcdef0123456789abcdef01234567",
+            "upstream_of_record": None,
+            "files": [
+                {"path": "config.json", "sha256": "11" * 32, "size": 1024},
+                {"path": "model-00001-of-00002.safetensors", "sha256": "22" * 32, "size": 4294967296},
+                {"path": "model-00002-of-00002.safetensors", "sha256": "33" * 32, "size": 2147483648},
+                {"path": "tokenizer.json", "sha256": "44" * 32, "size": 11534336},
+            ],
+        },
+        "architecture": {
+            "architecture": "Qwen3ForCausalLM",
+            "hidden_size": 4096,
+            "layers": 36,
+            "attention_heads": 32,
+            "key_value_heads": 8,
+            "intermediate_size": 12288,
+            "head_dim": 128,
+            "rope_theta": 1000000,
+            "vocab_size": 151936,
+            "max_position_embeddings": 40960,
+            "parameter_dtype": "bfloat16",
+        },
+        "tokenizer": {
+            "tokenizer_sha256": "44" * 32,
+            "tokenizer_config_sha256": "55" * 32,
+            "chat_template_sha256": "66" * 32,
+            "tokenizer_vocab_size": 151936,
+        },
+        "conversion": {
+            "converter_repo": "https://github.com/ggml-org/llama.cpp.git",
+            "converter_commit": "12127defda4f41b7679cb2477a4b0d65ee6a0c8f",
+            "converter_entrypoint": "convert_hf_to_gguf.py",
+            "converter_args": ["--outtype", "bf16"],
+            "quantizer_entrypoint": "llama-quantize",
+            "quantizer_args": [],
+            "quantization": "Q4_K_M",
+        },
+        "artifact": {"gguf_sha256": "77" * 32, "gguf_size": 23938321728},
+    }
+
+
+def cmd_selftest(_args: argparse.Namespace) -> int:
+    manifest = golden_manifest()
+    validate(manifest)
+    computed = manifest_hash(manifest)
+    if computed != GOLDEN_MANIFEST_HASH_HEX:
+        raise FailClosed(
+            "PARITY BROKEN: this script and runtime-palw/src/model_genesis.rs disagree on the golden "
+            f"vector.\n  python: {computed}\n  rust:   {GOLDEN_MANIFEST_HASH_HEX}\n"
+            "A cross-operator mismatch would be unattributable until this is fixed."
+        )
+    mutated = golden_manifest()
+    mutated["artifact"]["gguf_sha256"] = "78" * 32
+    if manifest_hash(mutated) == computed or first_mismatch(manifest, mutated) != "artifact.gguf_sha256":
+        raise FailClosed("field sensitivity check failed")
+    print(f"golden vector OK (Rust/Python parity): {computed}")
+    print(f"hash domain:            {HASH_DOMAIN.decode()}")
+    print(f"ML-DSA context (UNREGISTERED, unusable): {MLDSA87_CONTEXT_UNREGISTERED.decode()}")
+    return 0
+
+
+def _require_pinned_checkout(llama_dir: Path, commit: str) -> None:
+    if not llama_dir.is_dir():
+        raise FailClosed(f"--llama-dir {llama_dir} does not exist")
+    converter = llama_dir / "convert_hf_to_gguf.py"
+    if not converter.is_file():
+        raise FailClosed(f"missing converter: {converter} (clone llama.cpp at {commit})")
+    if shutil.which("git") is None:
+        raise FailClosed("missing tool: git — the converter commit pin cannot be verified")
+    result = subprocess.run(
+        ["git", "-C", str(llama_dir), "rev-parse", "HEAD"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        raise FailClosed(f"{llama_dir} is not a git checkout: {result.stderr.strip()}")
+    head = result.stdout.strip()
+    if head != commit:
+        raise FailClosed(f"{llama_dir} is at {head}, not the pinned converter commit {commit}")
+
+
+def cmd_convert(args: argparse.Namespace) -> int:
+    weights_dir: Path = args.weights_dir
+    if not weights_dir.is_dir():
+        raise FailClosed(f"--weights-dir {weights_dir} does not exist")
+    if not any(weights_dir.rglob("*.safetensors")) and not any(weights_dir.rglob("*.bin")):
+        raise FailClosed(
+            f"--weights-dir {weights_dir} holds no *.safetensors/*.bin shards — the conversion has "
+            "no input. Download the full checkpoint first."
+        )
+    _require_pinned_checkout(args.llama_dir, args.converter_commit)
+
+    quantizer = args.quantizer
+    if quantizer is None or not Path(quantizer).is_file():
+        raise FailClosed(
+            f"missing quantizer binary: {quantizer or '--quantizer not given'}. Build it from the "
+            f"pinned checkout: cmake --build {args.llama_dir}/build-palw --target llama-quantize"
+        )
+    if args.out_gguf.exists():
+        raise FailClosed(f"--out-gguf {args.out_gguf} already exists; refusing to overwrite")
+
+    intermediate = args.out_gguf.with_suffix(".bf16.gguf")
+    convert_argv = [
+        sys.executable,
+        str(args.llama_dir / "convert_hf_to_gguf.py"),
+        str(weights_dir),
+        "--outfile",
+        str(intermediate),
+        "--outtype",
+        "bf16",
+        "--no-lazy",
+        "--model-name",
+        args.model_name,
+    ]
+    quantize_argv = [str(quantizer), str(intermediate), str(args.out_gguf), args.quantization]
+    # A fixed environment: locale/timezone/hash-seed differences between two operators are exactly
+    # the kind of host state that must not reach the artifact.
+    env = {
+        "PATH": os.environ.get("PATH", ""),
+        "HOME": os.environ.get("HOME", ""),
+        "LC_ALL": "C",
+        "TZ": "UTC",
+        "PYTHONHASHSEED": "0",
+        "SOURCE_DATE_EPOCH": "0",
+    }
+    print("conversion procedure (both operators must run exactly this):")
+    print("  1) " + " ".join(convert_argv))
+    print("  2) " + " ".join(quantize_argv))
+    print("  env: " + " ".join(f"{k}={v}" for k, v in sorted(env.items()) if k not in ("PATH", "HOME")))
+    if not args.execute:
+        print("dry run: nothing was executed (pass --execute to run)")
+        return 0
+    for argv in (convert_argv, quantize_argv):
+        result = subprocess.run(argv, env=env, check=False)
+        if result.returncode != 0:
+            raise FailClosed(f"command failed with exit {result.returncode}: {' '.join(argv)}")
+    print(f"produced {args.out_gguf}")
+    return 0
+
+
+def cmd_manifest(args: argparse.Namespace) -> int:
+    weights_dir: Path = args.weights_dir
+    files = collect_weight_files(weights_dir)
+    if not args.gguf.is_file():
+        raise FailClosed(
+            f"--gguf {args.gguf} does not exist. Run the 'convert' subcommand first; a manifest is "
+            "never emitted for an artifact that was not produced."
+        )
+    _require_pinned_checkout(args.llama_dir, args.converter_commit)
+
+    chat_template = weights_dir / args.chat_template
+    if not chat_template.is_file():
+        raise FailClosed(f"missing chat template: {chat_template}")
+    by_path = {entry["path"]: entry for entry in files}
+    gguf_sha256, gguf_size = sha256_file(args.gguf)
+
+    manifest = {
+        "schema": SCHEMA_NAME,
+        "schema_version": SCHEMA_VERSION,
+        "weights": {
+            "tier": args.provenance_tier,
+            "source_id": args.source_id,
+            "source_revision": args.source_revision,
+            "upstream_of_record": (
+                {"source_id": args.upstream_source_id, "revision": args.upstream_revision}
+                if args.upstream_source_id
+                else None
+            ),
+            "files": files,
+        },
+        "architecture": architecture_from_config(weights_dir / "config.json"),
+        "tokenizer": {
+            "tokenizer_sha256": by_path["tokenizer.json"]["sha256"],
+            "tokenizer_config_sha256": by_path["tokenizer_config.json"]["sha256"],
+            "chat_template_sha256": by_path[args.chat_template]["sha256"],
+            "tokenizer_vocab_size": tokenizer_vocab_size(weights_dir / "tokenizer.json"),
+        },
+        "conversion": {
+            "converter_repo": args.converter_repo,
+            "converter_commit": args.converter_commit,
+            "converter_entrypoint": "convert_hf_to_gguf.py",
+            "converter_args": ["--outtype", "bf16", "--no-lazy"],
+            "quantizer_entrypoint": "llama-quantize",
+            "quantizer_args": [],
+            "quantization": args.quantization,
+        },
+        "artifact": {"gguf_sha256": gguf_sha256, "gguf_size": gguf_size},
+    }
+    if (args.upstream_source_id is None) != (args.upstream_revision is None):
+        raise FailClosed("--upstream-source-id and --upstream-revision must be given together")
+    validate(manifest)
+    digest = manifest_hash(manifest)
+    document = dict(manifest)
+    document["manifest_hash"] = digest
+    document["notes"] = {
+        "signature": "UNSIGNED — the ML-DSA-87 signature-domain table is LOCKED; no model-genesis "
+        "context is registered, so no signature can exist (ADR-0047 prerequisites).",
+        "provenance": "tier is a claim recorded IN the hash; 'third-party-derivative' can never "
+        "become the genesis (candidate disqualifier 1).",
+    }
+    args.out.parent.mkdir(parents=True, exist_ok=True)
+    args.out.write_text(json.dumps(document, indent=2, sort_keys=False) + "\n", encoding="utf-8")
+    print(f"manifest: {args.out}")
+    print(f"manifest_hash: {digest}")
+    if args.provenance_tier != "official-upstream":
+        print(
+            "NOTE: provenance tier is 'third-party-derivative' — this manifest is comparable and "
+            "reproducible, but it is NOT a genesis candidate (disqualifier 1)."
+        )
+    return 0
+
+
+def _load_manifest(path: Path) -> dict[str, Any]:
+    if not path.is_file():
+        raise FailClosed(f"manifest {path} does not exist")
+    document = json.loads(path.read_text(encoding="utf-8"))
+    if document.get("schema") != SCHEMA_NAME:
+        raise FailClosed(f"{path}: schema is {document.get('schema')!r}, expected {SCHEMA_NAME!r}")
+    recorded = document.pop("manifest_hash", None)
+    document.pop("notes", None)
+    validate(document)
+    computed = manifest_hash(document)
+    if recorded is not None and recorded != computed:
+        raise FailClosed(f"{path}: recorded manifest_hash {recorded} != recomputed {computed}")
+    return document
+
+
+def cmd_verify(args: argparse.Namespace) -> int:
+    if len(args.manifest) < 2:
+        raise FailClosed("verify needs at least two --manifest paths (that is the whole point)")
+    loaded = [(path, _load_manifest(path)) for path in args.manifest]
+    reference_path, reference = loaded[0]
+    reference_hash = manifest_hash(reference)
+    print(f"{reference_path}: {reference_hash}")
+    mismatched = False
+    for path, other in loaded[1:]:
+        digest = manifest_hash(other)
+        print(f"{path}: {digest}")
+        if digest != reference_hash:
+            mismatched = True
+            field = first_mismatch(reference, other) or "<hash differs but no field diff — schema bug>"
+            print(f"  MISMATCH vs {reference_path}: first differing field = {field}")
+    if mismatched:
+        raise FailClosed("manifests do not match — ADR-0047 acceptance requires a bit-exact match")
+    print(f"MATCH: {len(loaded)} manifests agree bit-exactly")
+    print(
+        "NOTE: a match is reproduction evidence only. It is not a genesis: the manifest is unsigned "
+        "(signature-domain table LOCKED), and two stacks owned by one operator are the weak form of "
+        "'two parties' (ADR-0047 §1)."
+    )
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    sub.add_parser("selftest", help="re-derive the golden vector and check Rust/Python parity").set_defaults(
+        func=cmd_selftest
+    )
+
+    convert = sub.add_parser("convert", help="check preconditions and emit/run the exact conversion")
+    convert.add_argument("--weights-dir", required=True, type=Path)
+    convert.add_argument("--llama-dir", required=True, type=Path)
+    convert.add_argument("--converter-commit", required=True)
+    convert.add_argument("--quantizer", type=Path)
+    convert.add_argument("--out-gguf", required=True, type=Path)
+    convert.add_argument("--quantization", default="Q4_K_M")
+    convert.add_argument("--model-name", required=True, help="pinned GGUF general.name; must match between operators")
+    convert.add_argument("--execute", action="store_true", help="actually run (default: dry run)")
+    convert.set_defaults(func=cmd_convert)
+
+    manifest = sub.add_parser("manifest", help="hash real inputs and emit the manifest + its hash")
+    manifest.add_argument("--weights-dir", required=True, type=Path)
+    manifest.add_argument("--gguf", required=True, type=Path)
+    manifest.add_argument("--llama-dir", required=True, type=Path)
+    manifest.add_argument("--converter-commit", required=True)
+    manifest.add_argument("--converter-repo", default="https://github.com/ggml-org/llama.cpp.git")
+    manifest.add_argument("--provenance-tier", required=True, choices=sorted(PROVENANCE_TIER_TAGS))
+    manifest.add_argument("--source-id", required=True)
+    manifest.add_argument("--source-revision", required=True)
+    manifest.add_argument("--upstream-source-id")
+    manifest.add_argument("--upstream-revision")
+    manifest.add_argument("--chat-template", default="chat_template.jinja")
+    manifest.add_argument("--quantization", default="Q4_K_M")
+    manifest.add_argument("--out", required=True, type=Path)
+    manifest.set_defaults(func=cmd_manifest)
+
+    verify = sub.add_parser("verify", help="compare two or more manifests field by field")
+    verify.add_argument("--manifest", action="append", required=True, type=Path, default=[])
+    verify.set_defaults(func=cmd_verify)
+    return parser
+
+
+def main() -> int:
+    args = build_parser().parse_args()
+    return int(args.func(args))
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/tests/test_model_genesis_manifest.py

@@ -0,0 +1,327 @@
+#!/usr/bin/env python3
+"""Tests for the ADR-0047 model-genesis manifest tool.
+
+Two properties matter here and nothing else does:
+
+  * **Parity** — the Python encoder and `runtime-palw/src/model_genesis.rs` must agree on the
+    golden vector. If they drift, a cross-operator hash mismatch becomes unattributable (is it the
+    weights, or the tool?), which defeats the purpose of the ADR's acceptance criterion.
+  * **Fail-closed** — a manifest must never be emitted from inputs that were not there. The repo's
+    current state exercises this for real: the checkpoint directory holds metadata only and
+    `llama-quantize` is not built.
+"""
+
+import json
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parents[2]
+SCRIPTS = REPO / "scripts"
+TOOL = SCRIPTS / "model_genesis_manifest.py"
+RUST_MODULE = REPO / "runtime-palw" / "src" / "model_genesis.rs"
+
+sys.path.insert(0, str(SCRIPTS))
+
+import model_genesis_manifest as mg  # noqa: E402
+
+
+def run_tool(*args: str) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        [sys.executable, str(TOOL), *args], capture_output=True, text=True, check=False
+    )
+
+
+def write_checkpoint(directory: Path, *, with_weights: bool = True) -> None:
+    directory.mkdir(parents=True, exist_ok=True)
+    (directory / "config.json").write_text(
+        json.dumps(
+            {
+                "architectures": ["Qwen3ForCausalLM"],
+                "model_type": "qwen3",
+                "hidden_size": 4096,
+                "num_hidden_layers": 36,
+                "num_attention_heads": 32,
+                "num_key_value_heads": 8,
+                "intermediate_size": 12288,
+                "head_dim": 128,
+                "rope_theta": 1000000,
+                "vocab_size": 151936,
+                "max_position_embeddings": 40960,
+                "torch_dtype": "bfloat16",
+            }
+        ),
+        encoding="utf-8",
+    )
+    (directory / "tokenizer.json").write_text(
+        json.dumps({"model": {"vocab": {"a": 0, "b": 1}}, "added_tokens": [{"id": 7}]}),
+        encoding="utf-8",
+    )
+    (directory / "tokenizer_config.json").write_text("{}", encoding="utf-8")
+    (directory / "chat_template.jinja").write_text("{{ messages }}", encoding="utf-8")
+    if with_weights:
+        (directory / "model-00001-of-00001.safetensors").write_bytes(b"synthetic-weights")
+
+
+def make_pinned_checkout(directory: Path) -> str:
+    directory.mkdir(parents=True, exist_ok=True)
+    (directory / "convert_hf_to_gguf.py").write_text("# stub\n", encoding="utf-8")
+    subprocess.run(["git", "init", "-q", str(directory)], check=True)
+    subprocess.run(["git", "-C", str(directory), "add", "-A"], check=True)
+    subprocess.run(
+        [
+            "git",
+            "-c",
+            "user.email=test@example.com",
+            "-c",
+            "user.name=test",
+            "-C",
+            str(directory),
+            "commit",
+            "-q",
+            "-m",
+            "stub",
+        ],
+        check=True,
+    )
+    return subprocess.run(
+        ["git", "-C", str(directory), "rev-parse", "HEAD"],
+        capture_output=True,
+        text=True,
+        check=True,
+    ).stdout.strip()
+
+
+class GoldenVectorParity(unittest.TestCase):
+    def test_selftest_passes(self):
+        result = run_tool("selftest")
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertIn(mg.GOLDEN_MANIFEST_HASH_HEX, result.stdout)
+
+    def test_rust_module_pins_the_same_golden(self):
+        """The parity binding: the Rust golden constant contains the same 128 hex characters."""
+        source = RUST_MODULE.read_text(encoding="utf-8")
+        halves = [mg.GOLDEN_MANIFEST_HASH_HEX[:64], mg.GOLDEN_MANIFEST_HASH_HEX[64:]]
+        self.assertTrue(
+            mg.GOLDEN_MANIFEST_HASH_HEX in source or all(half in source for half in halves),
+            "runtime-palw/src/model_genesis.rs no longer pins this golden vector",
+        )
+
+    def test_domain_separation(self):
+        import hashlib
+
+        payload = mg.canonical_bytes(mg.golden_manifest())
+        other = hashlib.blake2b(payload, key=b"palw-k1/file", digest_size=64).hexdigest()
+        self.assertNotEqual(other, mg.GOLDEN_MANIFEST_HASH_HEX)
+
+
+class Validation(unittest.TestCase):
+    def test_backend_specific_conversion_rejected(self):
+        for bad in ("--n-gpu-layers", "-ngl", "metal", "CUDA", "--threads"):
+            manifest = mg.golden_manifest()
+            manifest["conversion"]["converter_args"] = [bad]
+            with self.assertRaises(SystemExit, msg=bad):
+                mg.validate(manifest)
+
+    def test_host_paths_and_mutable_pins_rejected(self):
+        absolute = mg.golden_manifest()
+        absolute["weights"]["files"][0]["path"] = "/Users/operator/config.json"
+        with self.assertRaises(SystemExit):
+            mg.validate(absolute)
+
+        branch = mg.golden_manifest()
+        branch["weights"]["source_revision"] = "main"
+        with self.assertRaises(SystemExit):
+            mg.validate(branch)
+
+        unsorted = mg.golden_manifest()
+        files = unsorted["weights"]["files"]
+        files[0], files[1] = files[1], files[0]
+        with self.assertRaises(SystemExit):
+            mg.validate(unsorted)
+
+    def test_field_sensitivity(self):
+        base = mg.golden_manifest()
+        baseline = mg.manifest_hash(base)
+        seen = {baseline}
+        for path in (
+            ("weights", "source_id"),
+            ("architecture", "layers"),
+            ("tokenizer", "tokenizer_vocab_size"),
+            ("conversion", "quantization"),
+            ("artifact", "gguf_size"),
+        ):
+            mutated = mg.golden_manifest()
+            section, field = path
+            value = mutated[section][field]
+            mutated[section][field] = value + 1 if isinstance(value, int) else value + "x"
+            digest = mg.manifest_hash(mutated)
+            self.assertNotIn(digest, seen, f"{section}.{field} did not change the hash")
+            seen.add(digest)
+            self.assertIsNotNone(mg.first_mismatch(base, mutated))
+
+
+class FailClosed(unittest.TestCase):
+    def test_metadata_only_checkpoint_is_refused(self):
+        """The repo's real state: base metadata is present, the weight shards are not."""
+        with tempfile.TemporaryDirectory() as tmp:
+            weights = Path(tmp) / "weights"
+            write_checkpoint(weights, with_weights=False)
+            llama = Path(tmp) / "llama"
+            commit = make_pinned_checkout(llama)
+            result = run_tool(
+                "manifest",
+                "--weights-dir", str(weights),
+                "--gguf", str(Path(tmp) / "absent.gguf"),
+                "--llama-dir", str(llama),
+                "--converter-commit", commit,
+                "--provenance-tier", "official-upstream",
+                "--source-id", "Example/Model",
+                "--source-revision", "0" * 40,
+                "--out", str(Path(tmp) / "manifest.json"),
+            )
+            self.assertEqual(result.returncode, 1)
+            self.assertIn("no *.safetensors", result.stderr)
+            self.assertFalse((Path(tmp) / "manifest.json").exists())
+
+    def test_absent_gguf_is_refused(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            weights = Path(tmp) / "weights"
+            write_checkpoint(weights)
+            llama = Path(tmp) / "llama"
+            commit = make_pinned_checkout(llama)
+            result = run_tool(
+                "manifest",
+                "--weights-dir", str(weights),
+                "--gguf", str(Path(tmp) / "absent.gguf"),
+                "--llama-dir", str(llama),
+                "--converter-commit", commit,
+                "--provenance-tier", "official-upstream",
+                "--source-id", "Example/Model",
+                "--source-revision", "0" * 40,
+                "--out", str(Path(tmp) / "manifest.json"),
+            )
+            self.assertEqual(result.returncode, 1)
+            self.assertIn("does not exist", result.stderr)
+            self.assertFalse((Path(tmp) / "manifest.json").exists())
+
+    def test_unpinned_checkout_is_refused(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            weights = Path(tmp) / "weights"
+            write_checkpoint(weights)
+            llama = Path(tmp) / "llama"
+            make_pinned_checkout(llama)
+            gguf = Path(tmp) / "model.gguf"
+            gguf.write_bytes(b"gguf")
+            result = run_tool(
+                "manifest",
+                "--weights-dir", str(weights),
+                "--gguf", str(gguf),
+                "--llama-dir", str(llama),
+                "--converter-commit", "1" * 40,
+                "--provenance-tier", "official-upstream",
+                "--source-id", "Example/Model",
+                "--source-revision", "0" * 40,
+                "--out", str(Path(tmp) / "manifest.json"),
+            )
+            self.assertEqual(result.returncode, 1)
+            self.assertIn("not the pinned converter commit", result.stderr)
+
+    def test_missing_quantizer_is_named(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            weights = Path(tmp) / "weights"
+            write_checkpoint(weights)
+            llama = Path(tmp) / "llama"
+            commit = make_pinned_checkout(llama)
+            result = run_tool(
+                "convert",
+                "--weights-dir", str(weights),
+                "--llama-dir", str(llama),
+                "--converter-commit", commit,
+                "--out-gguf", str(Path(tmp) / "out.gguf"),
+                "--model-name", "Example",
+            )
+            self.assertEqual(result.returncode, 1)
+            self.assertIn("missing quantizer binary", result.stderr)
+            self.assertIn("llama-quantize", result.stderr)
+
+
+class EndToEnd(unittest.TestCase):
+    def _emit(self, tmp: Path, name: str, *, tier: str = "official-upstream") -> Path:
+        weights = tmp / "weights"
+        write_checkpoint(weights)
+        llama = tmp / "llama"
+        commit = make_pinned_checkout(llama) if not (llama / ".git").exists() else subprocess.run(
+            ["git", "-C", str(llama), "rev-parse", "HEAD"], capture_output=True, text=True, check=True
+        ).stdout.strip()
+        gguf = tmp / "model.gguf"
+        gguf.write_bytes(b"synthetic-gguf-bytes")
+        out = tmp / name
+        result = run_tool(
+            "manifest",
+            "--weights-dir", str(weights),
+            "--gguf", str(gguf),
+            "--llama-dir", str(llama),
+            "--converter-commit", commit,
+            "--provenance-tier", tier,
+            "--source-id", "Example/Model",
+            "--source-revision", "0" * 40,
+            "--out", str(out),
+        )
+        self.assertEqual(result.returncode, 0, result.stderr)
+        return out
+
+    def test_two_identical_runs_match_and_a_changed_input_does_not(self):
+        with tempfile.TemporaryDirectory() as raw:
+            tmp = Path(raw)
+            first = self._emit(tmp, "a.json")
+            second = self._emit(tmp, "b.json")
+            self.assertEqual(
+                json.loads(first.read_text())["manifest_hash"],
+                json.loads(second.read_text())["manifest_hash"],
+            )
+            match = run_tool("verify", "--manifest", str(first), "--manifest", str(second))
+            self.assertEqual(match.returncode, 0, match.stderr)
+            self.assertIn("MATCH", match.stdout)
+            # A match is reproduction evidence, never a genesis claim.
+            self.assertIn("unsigned", match.stdout)
+
+            divergent = json.loads(second.read_text())
+            divergent.pop("manifest_hash")
+            divergent["weights"]["files"][0]["sha256"] = "ab" * 32
+            second.write_text(json.dumps(divergent), encoding="utf-8")
+            mismatch = run_tool("verify", "--manifest", str(first), "--manifest", str(second))
+            self.assertEqual(mismatch.returncode, 1)
+            self.assertIn("first differing field = weights.files", mismatch.stdout)
+
+    def test_derivative_tier_is_flagged_in_output(self):
+        with tempfile.TemporaryDirectory() as raw:
+            tmp = Path(raw)
+            weights = tmp / "weights"
+            write_checkpoint(weights)
+            llama = tmp / "llama"
+            commit = make_pinned_checkout(llama)
+            gguf = tmp / "model.gguf"
+            gguf.write_bytes(b"synthetic-gguf-bytes")
+            result = run_tool(
+                "manifest",
+                "--weights-dir", str(weights),
+                "--gguf", str(gguf),
+                "--llama-dir", str(llama),
+                "--converter-commit", commit,
+                "--provenance-tier", "third-party-derivative",
+                "--source-id", "huihui-ai/Huihui-Qwen3.6-35B-A3B-Claude-4.7-Opus-abliterated",
+                "--source-revision", "ac18882735d037f6074a7630eb68d85db8234c25",
+                "--out", str(tmp / "m.json"),
+            )
+            self.assertEqual(result.returncode, 0, result.stderr)
+            self.assertIn("NOT a genesis candidate", result.stdout)
+            document = json.loads((tmp / "m.json").read_text())
+            self.assertEqual(document["weights"]["tier"], "third-party-derivative")
+            self.assertIn("UNSIGNED", document["notes"]["signature"])
+
+
+if __name__ == "__main__":
+    unittest.main()