frutebox-node 0.1.0__py3-none-any.whl

frutebox/config.py

@@ -0,0 +1,367 @@
+"""Central configuration for frutebox.
+
+Values can be overridden with environment variables (prefixed ``FRUTEBOX_``, with the
+legacy ``STEVAI_`` name still honoured — see ``frutebox.envvars``), e.g.
+``FRUTEBOX_EPOCH_SECONDS=30``.  Keeping this in one place means the control
+plane, provider nodes and the economics engine all agree on the same rules.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import Dict, List
+
+from .envvars import env as _env
+
+
+def _env_float(name: str, default: float) -> float:
+    try:
+        return float(_env(name))          # type: ignore[arg-type]
+    except (KeyError, ValueError, TypeError):
+        return default
+
+
+def _env_int(name: str, default: int) -> int:
+    try:
+        return int(_env(name))            # type: ignore[arg-type]
+    except (KeyError, ValueError, TypeError):
+        return default
+
+
+def _env_str(name: str, default: str) -> str:
+    return _env(name, default) or default
+
+
+def _env_bool(name: str, default: bool) -> bool:
+    val = _env(name)
+    if val is None:
+        return default
+    return val.strip().lower() in ("1", "true", "yes", "on")
+
+
+def _env_list(name: str, default: List[str]) -> List[str]:
+    val = _env(name)
+    if not val:
+        return list(default)
+    return [x.strip() for x in val.split(",") if x.strip()]
+
+
+# The jurisdictions a user is allowed to pin their inference to. In production
+# these map to legally-attested data-centre locations; here they are logical
+# labels used by the router as a *hard* constraint.
+DEFAULT_REGIONS: List[str] = [
+    "eu-west",       # e.g. Ireland / Belgium
+    "eu-central",    # e.g. Germany / Netherlands
+    "eu-north",      # e.g. Sweden / Finland
+    "us-east",
+    "us-west",
+    "uk",
+    "ap-southeast",  # e.g. Singapore
+]
+
+
+@dataclass
+class Config:
+    # --- networking -------------------------------------------------------
+    control_host: str = _env_str("CONTROL_HOST", "127.0.0.1")
+    control_port: int = _env_int("CONTROL_PORT", 8080)
+
+    # A provider node considered dead if no heartbeat within this window.
+    stale_seconds: float = _env_float("STALE_SECONDS", 12.0)
+    heartbeat_seconds: float = _env_float("HEARTBEAT_SECONDS", 4.0)
+    # How long the control plane waits for a provider to return a job. Frontier REASONING models
+    # (e.g. Kimi K2.7-Code) think for minutes before the answer, so a 60s cap would time the node
+    # out mid-reasoning → exclude it → re-plan onto nobody → a misleading "no capacity" 503. On the
+    # streaming path this is a per-chunk gap (reasoning tokens keep it alive); on the non-stream path
+    # it bounds the whole turn. Sized for a long reasoning turn; a genuinely hung node still fails
+    # fast on streaming. Override per-deploy with JOB_TIMEOUT_S.
+    job_timeout_s: float = _env_float("JOB_TIMEOUT_S", 1800.0)
+
+    # --- routing weights (lower score = better provider) ------------------
+    w_latency: float = _env_float("W_LATENCY", 0.5)
+    w_load: float = _env_float("W_LOAD", 0.35)
+    w_price: float = _env_float("W_PRICE", 0.15)
+
+    # --- economics --------------------------------------------------------
+    # One "epoch" is deliberately short here so you can watch the reward
+    # decay live. In production an epoch might be a day or a week.
+    epoch_seconds: float = _env_float("EPOCH_SECONDS", 60.0)
+    # The bonus emission halves every N epochs (the "Bitcoin halving").
+    halving_epochs: int = _env_int("HALVING_EPOCHS", 4)
+
+    # Default price a provider charges to cover energy + basic maintenance,
+    # expressed per 1000 tokens, in the platform's accounting unit (credits).
+    default_cost_per_1k: float = _env_float("DEFAULT_COST_PER_1K", 0.06)
+
+    # Provider profit on top of their costs.
+    margin_rate: float = _env_float("MARGIN_RATE", 0.15)
+    # Our (the platform operator's) cut.
+    platform_rate: float = _env_float("PLATFORM_RATE", 0.05)
+    # The decaying bootstrap bonus, as a multiple of base cost, at epoch 0.
+    # Funded from a treasury / emission pool, NOT paid by users.
+    initial_bonus_rate: float = _env_float("INITIAL_BONUS_RATE", 1.0)
+
+    # --- File 01-D: settlement is priced on what serving actually costs -------------------
+    # A node operator pays for BANDWIDTH and ELECTRICITY, not for tokens. The reward on top is
+    # the §8A headroom — what we saved versus the cheapest alternative — so it is capped and
+    # floored rather than being a free-running multiple of a made-up base.
+    reward_cap_eur: float = _env_float("REWARD_CAP_EUR", 0.50)
+    reward_floor_eur: float = _env_float("REWARD_FLOOR_EUR", 0.0)
+    #: Fallback wattage per GPU tier when a node has not been benchmarked yet (file 01-D3).
+    #: Deliberately a declaration, not a guess dressed as a measurement — `power_measured`
+    #: on the settlement result says which one was used.
+    tier_watts_c: float = _env_float("TIER_WATTS_C", 60.0)
+    tier_watts_b: float = _env_float("TIER_WATTS_B", 200.0)
+    tier_watts_a: float = _env_float("TIER_WATTS_A", 350.0)
+    tier_watts_s: float = _env_float("TIER_WATTS_S", 700.0)
+
+    # How many epochs to render on the reward-curve chart.
+    curve_epochs: int = _env_int("CURVE_EPOCHS", 8)
+
+    default_region: str = _env_str("DEFAULT_REGION", "eu-west")
+    regions: List[str] = field(default_factory=lambda: list(DEFAULT_REGIONS))
+
+    # --- zero-trust redaction --------------------------------------------
+    # Strip secrets before a prompt reaches any provider. Ideally the client
+    # scrubs first (secrets never leave the user); this is the operator-side
+    # safety net for callers who don't. Placeholders go to the node; the
+    # gateway holds the vault and restores real values in the answer.
+    redact_at_gateway: bool = _env_bool("REDACT_AT_GATEWAY", True)
+
+    # --- reactive detection & accountability (Phase C) --------------------
+    # Fraction of jobs that get a planted honeytoken / a redundant re-run. Kept
+    # at 0 by default so latency and existing behaviour are untouched; demos and
+    # the operator dial these up. Staking backs the slashing penalties.
+    canary_rate: float = _env_float("CANARY_RATE", 0.0)
+    verify_rate: float = _env_float("VERIFY_RATE", 0.0)
+    default_stake: float = _env_float("DEFAULT_STAKE", 100.0)
+    # Self-consistency (Phase D quality): on HARD, quality-profile queries the
+    # gateway re-samples the brain this many times total and the pipeline scores
+    # agreement — disagreement lowers confidence and can trigger abstention. 1 =
+    # off (no extra samples) by default, since each sample is another full
+    # inference (latency); the operator dials it up when quality > speed matters.
+    self_consistency_samples: int = _env_int("SELF_CONSISTENCY_SAMPLES", 1)
+
+    #: File 03-F3 — how many CONVERSATIONAL turns survive context hygiene. The plan names this
+    #: knob and its default. Instruction roles (system/developer) are held out of the budget
+    #: entirely, so this counts the conversation, not the prompt.
+    ctx_turns: int = _env_int("CTX_TURNS", 20)
+    # Smart triage (§5.1): consult a small model to classify difficulty for quality queries the
+    # keyword pass thinks are EASY (catching hard ones it misses). One tiny extra call on the
+    # quality path only; off by default so latency/behaviour are unchanged until enabled.
+    smart_triage: bool = _env_bool("SMART_TRIAGE", False)
+    # Chain-of-Verification (§5.5): plan verification questions about the draft, answer each in a
+    # FRESH context, revise. It was the only quality pass with no operator switch, and it is not a
+    # cheap one — measured 2026-10-07 on a stock deployment (every other flag at its default) with a
+    # query the keyword pass calls hard: SEVEN node calls, one answer plus six verification calls,
+    # four of them serial. `self_consistency_samples` is off by default and `smart_triage` is off by
+    # default precisely because each costs an extra inference; CoVe cost six and could not be turned
+    # off at all. DEFAULT TRUE, so no deployment's behaviour changes: this closes the gap between
+    # what the quality stage's docstring promised an operator ("off or cheap by default") and what
+    # they could actually control. Turn it off where latency or power matters more than the
+    # hallucination guard — the draft is then returned unrevised, which is what every failure path
+    # in `cove_verify` already does.
+    cove_enabled: bool = _env_bool("COVE_ENABLED", True)
+    # Enforce software integrity attestation on node connect when the operator
+    # has published allowed agent digests. Off if no digests are configured.
+    require_attestation: bool = _env_bool("REQUIRE_ATTESTATION", True)
+    # Additional agent digests the operator publishes alongside this build's own.
+    # A directory only ever knows the digest of the code IT was built from, so any
+    # node-agent change locks out every still-running older node the moment the
+    # directory deploys first. Listing the outgoing digest here keeps both versions
+    # admissible for the length of a rollout; drop it once the fleet has caught up.
+    extra_agent_digests: List[str] = field(
+        default_factory=lambda: _env_list("EXTRA_AGENT_DIGESTS", []))
+
+    # --- governance (the accountable-operator model) ----------------------
+    # frutebox is deliberately NOT a leaderless community like Bitcoin. One
+    # company operates the control plane, is legally liable, and can act
+    # instantly. These switches are how that control is exercised.
+    #
+    # When admission is required, a newly-connected provider is parked as
+    # "pending" and CANNOT receive traffic until the operator approves it.
+    require_admission: bool = _env_bool("REQUIRE_ADMISSION", True)
+    # Bearer token protecting every /admin endpoint. Override in production.
+    admin_token: str = _env_str("ADMIN_TOKEN", "dev-admin-token")
+    # Provider ids pre-approved at startup (skip the pending queue).
+    approved_ids: List[str] = field(
+        default_factory=lambda: _env_list("APPROVED_IDS", []))
+
+    # --- signed node credentials (admission without an in-memory allow-list) ---
+    # A node credential is a directory-signed ticket ("this node id, owned by this
+    # user, may join") that the gateway verifies on connect. Unlike APPROVED_IDS —
+    # which lives in the directory's memory and evaporates on every restart — the
+    # grant travels WITH the node, so admission survives a control-plane restart.
+    # Revocation is still the operator's kill switch (SUSPENDED_IDS wins over any
+    # valid credential) plus a short-enough TTL, so keep the TTL modest.
+    node_credential_ttl_s: float = _env_float("NODE_CREDENTIAL_TTL_S", 30 * 86400.0)
+    # Hard ceiling on a caller-requested TTL: a credential cannot be un-signed, so
+    # the longest life we will ever mint is bounded here (90 days).
+    node_credential_max_ttl_s: float = _env_float("NODE_CREDENTIAL_MAX_TTL_S", 90 * 86400.0)
+
+    # Node ids the operator vouches for (KYC'd, staked) — eligible to run
+    # *sensitive* jobs. Everything else defaults to "untrusted" (general work
+    # only). Owned/neutral labels are assigned per-node via the admin API.
+    trusted_ids: List[str] = field(
+        default_factory=lambda: _env_list("TRUSTED_IDS", []))
+
+    # --- node-side job governance (defence in depth on a volunteer's machine) ---
+    # A node runs on somebody's real laptop/server and takes work from any signed-up
+    # user, so the job frame is attacker-controlled. These are the limits the NODE
+    # enforces on itself — deliberately not negotiable by the job, and enforced even
+    # if the gateway is compromised. Enforcement lives in frutebox/engine_guard.py
+    # (payload shape + engine surface) and frutebox/provider.py (concurrency + clock).
+    #
+    # Simultaneous jobs one node will run. Was advertised in the register frame but
+    # never enforced: every inbound `job` frame became an asyncio task, so one user
+    # could start unlimited concurrent generations on a volunteer's machine.
+    node_max_concurrent_jobs: int = _env_int("NODE_MAX_CONCURRENT_JOBS", 4)
+    # Hard wall-clock ceiling on ONE job, cancel included. Matches the gateway's own
+    # job_timeout_s: past that the gateway has already given up and re-planned, so a
+    # node computing on is pure waste (and the amplification vector — one request
+    # burning compute on N machines).
+    node_job_timeout_s: float = _env_float("NODE_JOB_TIMEOUT_S", 1800.0)
+    # Prompt bounds. The WebSocket frame limit is 8 MB; a prompt has no business
+    # being anywhere near that.
+    node_max_prompt_bytes: int = _env_int("NODE_MAX_PROMPT_BYTES", 1_000_000)
+    node_max_messages: int = _env_int("NODE_MAX_MESSAGES", 200)
+    # Generation budget. Ollama received NO options at all before, meaning "generate
+    # until the context fills"; 4096 matches Ollama's own default context so nothing
+    # gets shorter — it is now explicit, bounded and tunable instead of implicit.
+    node_max_context_tokens: int = _env_int("NODE_MAX_CONTEXT_TOKENS", 4096)
+    node_max_output_tokens: int = _env_int("NODE_MAX_OUTPUT_TOKENS", 4096)
+    # llama.cpp serves the reasoning models (Kimi K2.x), which legitimately think for
+    # many tokens before answering — same value the engine already used, kept separate
+    # so bounding a laptop never quietly downgrades the frontier node.
+    node_max_output_tokens_llamacpp: int = _env_int("NODE_MAX_OUTPUT_TOKENS_LLAMACPP", 20000)
+    # Backstop that does not depend on the engine honouring a token budget.
+    node_max_output_bytes: int = _env_int("NODE_MAX_OUTPUT_BYTES", 2_000_000)
+    # Tool DEFINITIONS forwarded to the engine (bounded + scrubbed first). Untrusted
+    # JSON Schema is rendered through the engine's chat template — llama.cpp runs with
+    # --jinja — so an owner can switch the surface off entirely.
+    node_max_tools: int = _env_int("NODE_MAX_TOOLS", 32)
+    node_max_tool_bytes: int = _env_int("NODE_MAX_TOOL_BYTES", 128_000)
+    node_allow_tool_defs: bool = _env_bool("NODE_ALLOW_TOOL_DEFS", True)
+    # Tool EXECUTION on the node's host. OFF by default and, on top of that, only ever
+    # possible on an operator-trusted node (see engine_guard.tool_execution_allowed).
+    # Today nothing on the node executes tools at all; this is the seam being sealed
+    # before a node-side runner could ever ship.
+    node_allow_tool_exec: bool = _env_bool("NODE_ALLOW_TOOL_EXEC", False)
+    # The engine must sit on loopback: a node is not a proxy that forwards user
+    # prompts to somebody else's host.
+    node_engine_allow_remote: bool = _env_bool("NODE_ENGINE_ALLOW_REMOTE", False)
+    # Attacker-supplied audio handed to a torch/C++ decoder — bound it hard.
+    node_max_voice_sample_bytes: int = _env_int("NODE_MAX_VOICE_SAMPLE_BYTES", 5_000_000)
+
+
+CONFIG = Config()
+
+
+# ---------------------------------------------------------------------------
+# File 11-A — latency budgets.
+#
+# The plan is explicit that these live HERE ("Budgets live in frutebox/config.py as
+# LATENCY_BUDGETS"), alongside every other operational number, rather than in a module of their
+# own. `frutebox/latency.py` holds the percentile and verdict MACHINERY that reads them; the numbers
+# are config, and config lives in the config file.
+#
+# Overridable per key as FRUTEBOX_LAT_<PATH>_<STAT>_MS (STEVAI_LAT_* still read).
+# ---------------------------------------------------------------------------
+
+def _lat(path: str, stat: str, default_ms: float) -> float:
+    # RULE 11 (2026-09-24): `FRUTEBOX_LAT_*` first, `STEVAI_LAT_*` second, through the same
+    # dual-read every other variable uses. Both spellings are accepted deliberately — a rename
+    # that breaks a live override the moment it ships is a worse bug than the old spelling, and
+    # nothing is removed until the senders have moved.
+    from .envvars import env as _env
+    suffix = f"LAT_{path.upper().replace('-', '_')}_{stat.upper()}_MS"
+    raw = (_env(suffix) or "").strip()
+    try:
+        return float(raw) if raw else default_ms
+    except ValueError:
+        return default_ms
+
+
+def latency_budgets() -> Dict[str, Dict[str, float]]:
+    """File 11 table A. `{path: {ttft_p50, ttft_p95, tps}}`, in milliseconds (tps in tokens/s)."""
+    return {
+        "local_chat":       {"ttft_p50": _lat("local_chat", "ttft_p50", 300),
+                             "ttft_p95": _lat("local_chat", "ttft_p95", 600),
+                             "tps": _lat("local_chat", "tps", 30)},
+        "network_chat":     {"ttft_p50": _lat("network_chat", "ttft_p50", 800),
+                             "ttft_p95": _lat("network_chat", "ttft_p95", 1500),
+                             "tps": _lat("network_chat", "tps", 30)},
+        "network_frontier": {"ttft_p50": _lat("network_frontier", "ttft_p50", 1200),
+                             "ttft_p95": _lat("network_frontier", "ttft_p95", 2500),
+                             "tps": _lat("network_frontier", "tps", 20)},
+        "voice_local":      {"ttft_p50": _lat("voice_local", "ttft_p50", 300),
+                             "ttft_p95": _lat("voice_local", "ttft_p95", 500),
+                             "tps": _lat("voice_local", "tps", 0)},
+        # FILE 13's done-criterion, as a NUMBER rather than prose: "answers a wake-word question
+        # <=3 s with a citation". It was written only in the plan, so nothing could fail when the
+        # companion took four seconds. p95 is the 3 s the plan names; p50 is half of it, because a
+        # budget whose only number is the ceiling is one nobody notices drifting toward it.
+        # `tps` is 0: a meeting answer is <=3 spoken sentences (§C3), so throughput is not what
+        # makes it feel fast — time to the first word is.
+        "meeting_answer":   {"ttft_p50": _lat("meeting_answer", "ttft_p50", 1500),
+                             "ttft_p95": _lat("meeting_answer", "ttft_p95", 3000),
+                             "tps": _lat("meeting_answer", "tps", 0)},
+    }
+
+
+def latency_stage_budgets() -> Dict[str, float]:
+    """Stages measured on their own rather than as a whole path (file 11-A)."""
+    return {
+        "gateway_overhead": _lat("gateway_overhead", "p95", 50),
+        "screening_verdict": _lat("screening_verdict", "p95", 80),
+        "steer_resume": _lat("steer_resume", "p95", 700),
+        # FILE 13 line 53, verbatim: "answers a wake-word question <=3 s with a citation". The
+        # number is the plan's, not a guess — a spoken answer that arrives after the conversation
+        # has moved on is worse than no answer.
+        "meeting_answer": _lat("meeting_answer", "p95", 3000),
+        # The router+rewriter pair, which 11-A budgets "together under 15 ms". It lived as a
+        # literal in `scripts/perf_harness.py` and as prose in `latency._NOTES`, so unlike the
+        # other three it could NOT be relaxed by an operator setting an override, and a drift
+        # between the two copies failed nothing. One source, same mechanism.
+        "router_rewriter": _lat("router_rewriter", "p95", 15),
+    }
+
+
+LATENCY_BUDGETS: Dict[str, Dict[str, float]] = latency_budgets()
+LATENCY_STAGE_BUDGETS: Dict[str, float] = latency_stage_budgets()
+
+
+def json_flag(value, default: bool = False) -> bool:
+    """Parse a CLIENT-SUPPLIED boolean. NEVER `bool(x)`.
+
+    `bool("false")` is True, and so is `bool("no")` and `bool("0")`. A client whose checkbox
+    serialises as a string — a form post, a JS `String(x)`, an SDK that stringifies — flips the
+    caller's "off" into "on", silently, at the door.
+
+    THIS HAS ALREADY COST SOMETHING. It was caught at plan 13's integration as a CONSENT BYPASS:
+    a client sending `"consent_confirmed": "false"` joined a meeting without consent and had
+    `save_minutes` turned on, against two §D promises ("join without confirming consent is
+    impossible"; "No covert retention"). `decide_join` implemented them correctly; the coercion
+    destroyed them before the decision was reached.
+
+    It lives HERE, in the one module both the gateway and the directory already import, because
+    the fix is the RULE and not the door it was found at — the same reason credential logging was
+    fixed as a rule in September. Two copies of a parser like this is two chances for one of them
+    to go back to `bool()`.
+
+    Real booleans and real JSON literals only. Anything else is the DEFAULT, because a value this
+    function cannot read is a value the caller did not clearly say.
+    """
+    if isinstance(value, bool):
+        return value
+    if value is None:
+        return default
+    if isinstance(value, (int, float)) and not isinstance(value, bool):
+        return value != 0
+    if isinstance(value, str):
+        v = value.strip().lower()
+        if v in ("true", "yes", "on", "1"):
+            return True
+        if v in ("false", "no", "off", "0", ""):
+            return False
+    return default

frutebox/deltasync.py

@@ -0,0 +1,211 @@
+"""FILE 03-F2 — delta-sync: the client resends only what is new.
+
+THE SAVING, AND WHERE IT COMES FROM
+A 20-turn conversation re-sends 19 turns of context on turn 20. Those tokens are paid for on
+every single turn, and almost all of them are bytes the server already has. Delta-sync sends the
+NEW turns plus a hash of the prefix; the server reconstructs the rest.
+
+WHERE THE PREFIX COMES FROM — AND WHERE IT DOES NOT (owner ruling, 2026-09-03)
+From the **existing consented conversation store**, under its own consent and retention rules.
+NOT from the operational session cache: `sessionstate.py` deliberately refuses to hold
+prompt/messages/completion/content, because an operational cache with a 24h TTL is not where
+someone's conversation belongs, and that refusal is enforced in code rather than promised. There
+is also no Redis here (Neon only, rule 10). The plan's original "reconstruct from Redis session
+state" wording was the wrong half of that conflict and has been corrected.
+
+FAIL SAFE, NOT FAIL CHEAP
+If the hash does not match — the client edited a turn, a message was deleted, the client is out
+of date — reconstruction REFUSES and the caller asks for the full context. Answering with a
+prefix that is not the one the user is looking at would be a wrong answer produced confidently,
+which is worse than resending some tokens.
+
+THE OTHER HALF OF THE SAVING
+Prefix reuse at the engine (`cache_prompt=true`) means the reconstructed prefix is not
+re-evaluated either — the KV cache is reused across turns. That is where the compute saving
+comes from; delta-sync is where the transfer saving comes from.
+"""
+from __future__ import annotations
+
+import hashlib
+import os
+from typing import Any, Callable, Dict, List, Optional, Sequence, Tuple
+from .envvars import env as envvar, env_bool, env_required
+from . import adminheader
+
+#: Roughly four characters per token. Only ever used to REPORT a saving, never to bill: the
+#: real token count comes from the engine. A rough number is fine for "did this help".
+CHARS_PER_TOKEN = 4
+
+#: The web app that owns the conversation store. Same variable the session-state client uses.
+#:
+#: RESOLVED LAZILY, AND THAT IS NOT A STYLE CHOICE. At module scope this raised `MissingConfig` on
+#: import, and `frutebox/inference.py` imports this module for `engine_cache_options()` — so
+#: `python -m frutebox.provider` stopped starting at all for anyone without `FRUTEBOX_WEB_URL`.
+#: That is the DOWNLOADABLE NODE: `run.sh`, `docker-entrypoint.sh`'s provider role, the Dockerfile
+#: and every runbook set no such variable, and a GPU box has no business knowing the web app's URL.
+#: The gateway already required it via `sessionstate`, so a gateway deploy and CI both stayed green
+#: while the node was dead — it would have surfaced when an operator restarted a node.
+#:
+#: Only `fetch_prefix` needs it, and `fetch_prefix` is still unwired, so nothing pays this cost
+#: until the transfer half of delta-sync is built.
+def web_url() -> str:
+    return env_required("WEB_URL").rstrip("/")
+TIMEOUT_S = float(envvar("CONTEXT_PREFIX_TIMEOUT_S", "3.0"))
+
+#: Keys that must never travel into the operational session cache. Mirrors
+#: `sessionstate._FORBIDDEN` so a drift in either is caught by a test rather than in production.
+FORBIDDEN_IN_SESSION_STATE = frozenset(
+    {"prompt", "messages", "completion", "content", "vault", "secrets"}
+)
+
+
+def _norm(msg: Dict[str, Any]) -> str:
+    """One message, reduced to what actually identifies it: who said it and what they said."""
+    return f"{str(msg.get('role', '')).strip().lower()}\x1f{str(msg.get('content', ''))}"
+
+
+def context_hash(messages: Sequence[Dict[str, Any]]) -> str:
+    """A stable fingerprint of a conversation prefix.
+
+    Order-sensitive on purpose: the same turns in a different order are a different conversation,
+    and a hash that ignored that would let a reordered history pass as the original.
+    """
+    h = hashlib.sha256()
+    for m in messages:
+        h.update(_norm(m).encode("utf8"))
+        h.update(b"\x1e")
+    return h.hexdigest()
+
+
+def split_prefix(messages: Sequence[Dict[str, Any]], keep_last: int) -> Tuple[List[Dict[str, Any]], List[Dict[str, Any]]]:
+    """(prefix, new_turns) — what the server already has vs what the client must send."""
+    n = max(0, int(keep_last))
+    if n == 0 or n >= len(messages):
+        return [], list(messages)
+    return list(messages[:-n]), list(messages[-n:])
+
+
+def build_request(messages: Sequence[Dict[str, Any]], *, session_id: str, keep_last: int = 1) -> Dict[str, Any]:
+    """What a client sends INSTEAD of the whole conversation."""
+    prefix, new_turns = split_prefix(messages, keep_last)
+    return {
+        "session_id": session_id,
+        "context_hash": context_hash(prefix),
+        "prefix_len": len(prefix),
+        "new_turns": new_turns,
+    }
+
+
+class ContextMismatch(Exception):
+    """The stored prefix is not the one the client hashed. Ask for the full context."""
+
+
+def reconstruct(
+    request: Dict[str, Any],
+    *,
+    load_prefix: Callable[[str], Optional[List[Dict[str, Any]]]],
+) -> List[Dict[str, Any]]:
+    """Rebuild the full message list from the stored prefix plus the client's new turns.
+
+    `load_prefix` is injected — this module imports no store, so the same logic is exercised in
+    tests against real data instead of a stand-in for the thing under test.
+
+    Raises `ContextMismatch` when the stored prefix is absent or does not hash to what the client
+    claimed. Callers treat that as "resend everything", never as "close enough".
+    """
+    new_turns = list(request.get("new_turns") or [])
+    claimed = str(request.get("context_hash") or "")
+    session_id = str(request.get("session_id") or "")
+
+    if not claimed:
+        raise ContextMismatch("no context hash supplied")
+
+    # An empty prefix is a legitimate first turn: nothing to load, and the hash of nothing is a
+    # known value. Checking it rather than special-casing keeps one code path.
+    if claimed == context_hash([]):
+        if int(request.get("prefix_len") or 0) != 0:
+            raise ContextMismatch("prefix length disagrees with the empty-prefix hash")
+        return new_turns
+
+    prefix = load_prefix(session_id)
+    if prefix is None:
+        raise ContextMismatch("no stored prefix for this session")
+    if context_hash(prefix) != claimed:
+        raise ContextMismatch("stored prefix does not match the client's context hash")
+    if int(request.get("prefix_len") or -1) != len(prefix):
+        raise ContextMismatch("prefix length disagrees with the stored prefix")
+
+    return list(prefix) + new_turns
+
+
+def approx_tokens(messages: Sequence[Dict[str, Any]]) -> int:
+    return sum(len(_norm(m)) for m in messages) // CHARS_PER_TOKEN
+
+
+def input_token_saving(full: Sequence[Dict[str, Any]], request: Dict[str, Any]) -> float:
+    """The fraction of resent input tokens delta-sync removes, 0.0–1.0.
+
+    Measured against what the client WOULD have sent — the whole conversation — because that is
+    the bill the user was actually paying.
+    """
+    before = approx_tokens(full)
+    if before <= 0:
+        return 0.0
+    after = approx_tokens(request.get("new_turns") or [])
+    return max(0.0, (before - after) / before)
+
+
+#: 03-F2: prefix reuse at the engine. The reconstructed prefix must not be re-evaluated either —
+#: without this the transfer gets cheaper and the compute does not.
+#: Accepts the SAME falsey words as `envvars.env_bool` ({"0","false","no","off"}). It used to
+#: compare against "false" alone, so an operator whose engine rejected the field and who
+#: reached for the instinctive `FRUTEBOX_KV_PREFIX_REUSE=0` would not have turned it off.
+#: That was harmless while nothing called this; wiring it made the switch load-bearing.
+KV_PREFIX_REUSE = env_bool("KV_PREFIX_REUSE", True)
+
+
+def engine_cache_options() -> Dict[str, bool]:
+    """`cache_prompt` for the local engine, so the reused prefix is also a reused KV cache."""
+    return {"cache_prompt": True} if KV_PREFIX_REUSE else {}
+
+
+def fetch_prefix(conversation_id: str, *, context_hash_hex: str, prefix_len: int) -> Optional[List[Dict[str, Any]]]:
+    """Load the verified prefix from the consented conversation store (03-F2).
+
+    Mirrors `sessionstate.py`'s service-to-service shape — same admin header, same short timeout,
+    same "degrade to nothing rather than fail the turn" contract. A None here is not an error the
+    user should ever see: the caller resends the full context and the turn proceeds.
+
+    The hash goes UP with the request, so the store only returns a prefix to a caller that
+    already knows what it is asking for.
+    """
+    import httpx
+    from .config import CONFIG
+
+    try:
+        r = httpx.post(
+            f"{web_url()}/api/internal/context-prefix",
+            headers=adminheader.send(CONFIG.admin_token),
+            json={"conversationId": conversation_id,
+                  "contextHash": context_hash_hex,
+                  "prefixLen": int(prefix_len)},
+            timeout=TIMEOUT_S,
+        )
+    except Exception:
+        return None                      # network trouble: resend the full context, do not fail
+    if r.status_code != 200:
+        return None                      # 409 = the client's view is stale; same answer
+    try:
+        msgs = r.json().get("messages")
+    except Exception:
+        return None
+    return list(msgs) if isinstance(msgs, list) else None
+
+
+def safe_for_session_state(state: Dict[str, Any]) -> bool:
+    """Would this dict be legal to hand to `sessionstate.save`?
+
+    Delta-sync exists BECAUSE conversation content must not go into that cache, so the module
+    that reconstructs content also carries the check that it never puts any there.
+    """
+    return not any(k.lower() in FORBIDDEN_IN_SESSION_STATE for k in (state or {}))