@bendyline/gezel-service 1.1.1 → 1.1.2

package/dist/memory/embed-worker.js

@@ -4,7 +4,7 @@
 import { parentPort } from "worker_threads";
 
 // src/memory/embed-core.ts
-import { createHash } from "crypto";
+import { createHash as createHash2 } from "crypto";
 import { createLogger as createLogger2 } from "@bendyline/gezel";
 import {
   EmbedderUnavailableError,
@@ -15,12 +15,131 @@ import {
 } from "@bendyline/gezel-knowledge";
 
 // src/transformers-cache.ts
-import { mkdir } from "fs/promises";
-import { join } from "path";
+import { createHash } from "crypto";
+import { mkdir, rm, stat, writeFile } from "fs/promises";
+import { dirname as dirname2, join as join2, resolve as resolve2 } from "path";
 import { createLogger } from "@bendyline/gezel";
+
+// src/fs/safe-paths.ts
+import { realpath } from "fs/promises";
+import { basename, dirname, isAbsolute, join, normalize, resolve, sep } from "path";
+function pathEq(a, b) {
+  if (process.platform === "win32" || process.platform === "darwin") {
+    return a.toLowerCase() === b.toLowerCase();
+  }
+  return a === b;
+}
+function pathStartsWithDir(candidate, base) {
+  if (process.platform === "win32" || process.platform === "darwin") {
+    return candidate.toLowerCase().startsWith(base.toLowerCase() + sep.toLowerCase());
+  }
+  return candidate.startsWith(base + sep);
+}
+function isPathInside(target, root) {
+  const resolvedTarget = resolve(target);
+  const resolvedRoot = resolve(root);
+  if (pathEq(resolvedTarget, resolvedRoot)) return true;
+  return pathStartsWithDir(resolvedTarget, resolvedRoot);
+}
+
+// src/transformers-cache.ts
 var log = createLogger("service");
 var HF_CACHE_DIR_ENV = "GEZEL_HF_CACHE_DIR";
 var TRANSFORMERS_MODULE = "@huggingface/transformers";
+var DEFAULT_MODEL_LOCK_TIMEOUT_MS = 10 * 60 * 1e3;
+var DEFAULT_MODEL_LOCK_STALE_MS = 2 * 60 * 60 * 1e3;
+var DEFAULT_MODEL_LOCK_POLL_MS = 100;
+function modelLockDir(cacheDir, modelId) {
+  const key = createHash("sha256").update(modelId, "utf8").digest("hex").slice(0, 24);
+  return join2(cacheDir, ".gezel-locks", `${key}.lock`);
+}
+function cacheModelDir(cacheDir, modelId) {
+  const parts = modelId.split("/");
+  if (parts.length === 0 || parts.some((part) => !part || part === "." || part === ".." || part.includes("\\"))) {
+    throw new Error(`refusing unsafe transformers model id: ${modelId}`);
+  }
+  const root = resolve2(cacheDir);
+  const target = resolve2(root, ...parts);
+  if (target === root || !isPathInside(target, root)) {
+    throw new Error(`refusing transformers cache path outside ${root}: ${modelId}`);
+  }
+  return target;
+}
+function errorCode(err) {
+  return err?.code;
+}
+function delay(ms) {
+  return new Promise((resolveDelay) => setTimeout(resolveDelay, ms));
+}
+async function staleOrMissing(lockDir, staleMs) {
+  try {
+    const info = await stat(lockDir);
+    return Date.now() - info.mtimeMs > staleMs;
+  } catch (err) {
+    if (errorCode(err) === "ENOENT") return true;
+    throw err;
+  }
+}
+async function withTransformersModelCacheLock(cacheDir, modelId, run, options = {}) {
+  const timeoutMs = options.timeoutMs ?? DEFAULT_MODEL_LOCK_TIMEOUT_MS;
+  const staleMs = options.staleMs ?? DEFAULT_MODEL_LOCK_STALE_MS;
+  const pollMs = options.pollMs ?? DEFAULT_MODEL_LOCK_POLL_MS;
+  const lockDir = modelLockDir(cacheDir, modelId);
+  await mkdir(dirname2(lockDir), { recursive: true });
+  const startedAt = Date.now();
+  while (true) {
+    try {
+      await mkdir(lockDir);
+      break;
+    } catch (err) {
+      if (errorCode(err) !== "EEXIST") throw err;
+      if (await staleOrMissing(lockDir, staleMs)) {
+        await rm(lockDir, { recursive: true, force: true });
+        continue;
+      }
+      if (Date.now() - startedAt >= timeoutMs) {
+        throw new Error(`timed out waiting for transformers cache lock for ${modelId}`);
+      }
+      await delay(pollMs);
+    }
+  }
+  try {
+    await writeFile(
+      join2(lockDir, "owner.json"),
+      `${JSON.stringify({ pid: process.pid, modelId, acquiredAt: (/* @__PURE__ */ new Date()).toISOString() })}
+`
+    );
+    return await run();
+  } finally {
+    await rm(lockDir, { recursive: true, force: true });
+  }
+}
+async function removeTransformersModelCache(cacheDir, modelId) {
+  await rm(cacheModelDir(cacheDir, modelId), { recursive: true, force: true });
+}
+function isCorruptTransformersCacheFailure(error) {
+  const messages = [];
+  let current = error;
+  for (let depth = 0; depth < 6 && current; depth++) {
+    messages.push(current instanceof Error ? current.message : String(current));
+    current = current instanceof Error ? current.cause : void 0;
+  }
+  return /(?:protobuf parsing failed|failed to parse protobuf|invalid protobuf|unexpected end of (?:file|data)|failed to load model|load model .* failed|invalid wire type)/i.test(
+    messages.join(" ")
+  );
+}
+async function loadTransformersModelWithCacheRecovery(cacheDir, modelId, load, onCorrupt) {
+  return withTransformersModelCacheLock(cacheDir, modelId, async () => {
+    try {
+      return await load();
+    } catch (err) {
+      if (!isCorruptTransformersCacheFailure(err)) throw err;
+      await onCorrupt?.();
+      await removeTransformersModelCache(cacheDir, modelId);
+      return await load();
+    }
+  });
+}
 function isMissingModule(err, specifier) {
   if (!(err instanceof Error)) return false;
   const { code } = err;
@@ -124,7 +243,16 @@ async function loadPipeline() {
         const { pipeline } = await import("@huggingface/transformers");
         const modelId = embedModelId();
         if (modelId !== DEFAULT_EMBED_MODEL) log2.info(`[embed] using model ${modelId}`);
-        return await pipeline("feature-extraction", modelId, daemonLoadOptions());
+        const createPipeline = () => pipeline("feature-extraction", modelId, daemonLoadOptions());
+        if (!cacheDir) return await createPipeline();
+        return await loadTransformersModelWithCacheRecovery(
+          cacheDir,
+          modelId,
+          createPipeline,
+          () => {
+            log2.warn(`[embed] discarded corrupt cached model files for ${modelId}; retrying once`);
+          }
+        );
       } catch (err) {
         const missing = isMissingModule(err, TRANSFORMERS_MODULE);
         const message = missing ? "Local memory embeddings are an optional npm feature. Install @huggingface/transformers@^3.8.1 alongside @bendyline/gezel-service (see the service README)." : err instanceof Error ? err.message : String(err);

package/dist/memory/image-embed-worker.js

@@ -4,7 +4,7 @@
 import { parentPort } from "worker_threads";
 
 // src/memory/embed-core.ts
-import { createHash } from "crypto";
+import { createHash as createHash2 } from "crypto";
 import { createLogger as createLogger2 } from "@bendyline/gezel";
 import {
   EmbedderUnavailableError,
@@ -15,12 +15,21 @@ import {
 } from "@bendyline/gezel-knowledge";
 
 // src/transformers-cache.ts
-import { mkdir } from "fs/promises";
-import { join } from "path";
+import { createHash } from "crypto";
+import { mkdir, rm, stat, writeFile } from "fs/promises";
+import { dirname as dirname2, join as join2, resolve as resolve2 } from "path";
 import { createLogger } from "@bendyline/gezel";
+
+// src/fs/safe-paths.ts
+import { realpath } from "fs/promises";
+import { basename, dirname, isAbsolute, join, normalize, resolve, sep } from "path";
+
+// src/transformers-cache.ts
 var log = createLogger("service");
 var HF_CACHE_DIR_ENV = "GEZEL_HF_CACHE_DIR";
 var TRANSFORMERS_MODULE = "@huggingface/transformers";
+var DEFAULT_MODEL_LOCK_TIMEOUT_MS = 10 * 60 * 1e3;
+var DEFAULT_MODEL_LOCK_STALE_MS = 2 * 60 * 60 * 1e3;
 function isMissingModule(err, specifier) {
   if (!(err instanceof Error)) return false;
   const { code } = err;
@@ -268,7 +277,7 @@ import { open } from "fs/promises";
 import { createRequire } from "module";
 
 // src/index-store/image-meta.ts
-import { createHash as createHash2 } from "crypto";
+import { createHash as createHash3 } from "crypto";
 import { inflateSync } from "zlib";
 function readImageMeta(buf) {
   if (buf.length < 24) return null;
@@ -329,7 +338,7 @@ function readImageStaticMeta(buf, opts) {
   const meta = {
     format: dims?.format ?? (looksLikeSvg(buf) ? "svg" : "unknown"),
     byteLength: buf.length,
-    sha256: createHash2("sha256").update(buf).digest("hex")
+    sha256: createHash3("sha256").update(buf).digest("hex")
   };
   if (dims) {
     meta.width = dims.width;

package/dist/providers/mlx/python/cache_persist.py

@@ -29,6 +29,7 @@ from __future__ import annotations
 import json
 import os
 import time
+from importlib import import_module
 from pathlib import Path
 from typing import Any, Optional
 
@@ -41,8 +42,16 @@ from mlx.utils import tree_flatten, tree_unflatten
 # or some operator has both installed and a model uses one set vs the
 # other. We resolve lazily on each load so an import failure here
 # can't take down the server module at import time.
-def _resolve_cache_class(name: str) -> Optional[type]:
+def _resolve_cache_class(name: str, module_name: Optional[str] = None) -> Optional[type]:
     candidates: list[Any] = []
+    # Custom caches such as Qwen4's QSAKVCache live in the model's language
+    # module, not either package's shared cache module. Persist the originating
+    # module and import it only inside the two trusted MLX package namespaces.
+    if module_name and module_name.startswith(("mlx_vlm.models.", "mlx_lm.models.")):
+        try:
+            candidates.append(import_module(module_name))
+        except Exception:  # noqa: BLE001 — fall through to legacy lookup
+            pass
     try:
         from mlx_vlm.models import cache as vlm_cache  # type: ignore[attr-defined]
 
@@ -64,8 +73,24 @@ def _resolve_cache_class(name: str) -> Optional[type]:
 
 # Schema version baked into sidecar metadata. Bump when the on-disk
 # layout changes incompatibly so older entries are rejected on load
-# instead of silently corrupting reconstruction.
-SCHEMA_VERSION = "1"
+# instead of silently corrupting reconstruction. Version 2 stores scalar
+# cache-state leaves in metadata: Qwen4's QSA cache carries an integer block
+# compression ratio alongside its arrays, and passing that integer to
+# ``mx.save_safetensors`` raises ``std::bad_cast``. Version 3 also records the
+# defining module for model-specific caches such as QSAKVCache.
+SCHEMA_VERSION = "3"
+
+
+def _split_state_leaves(layer_states: Any) -> tuple[dict[str, Any], dict[str, Any]]:
+    """Partition cache state into safetensor arrays and JSON scalar leaves."""
+    arrays: dict[str, Any] = {}
+    scalars: dict[str, Any] = {}
+    for path, value in tree_flatten(layer_states):
+        if value is None or isinstance(value, (bool, int, float, str)):
+            scalars[path] = value
+        else:
+            arrays[path] = value
+    return arrays, scalars
 
 
 def cache_path(persist_dir: Path, model_fingerprint: str, cache_id: str) -> Path:
@@ -107,11 +132,12 @@ def save_cache(
         # default to an empty dict so reconstruction can still proceed.
         meta_state = [getattr(c, "meta_state", {}) for c in cache_layers]
         class_names = [type(c).__name__ for c in cache_layers]
+        class_modules = [type(c).__module__ for c in cache_layers]
         # tree_flatten turns a nested structure of arrays into a flat
         # list of (path, array) tuples — exactly what save_safetensors
         # wants. The path encoding is what tree_unflatten reads back to
         # reconstruct the structure.
-        flat = dict(tree_flatten(layer_states))
+        flat, state_scalars = _split_state_leaves(layer_states)
         if not flat:
             # Nothing array-shaped to save; reconstruction would always
             # fail. Treat as a no-op rather than writing an empty file.
@@ -120,7 +146,9 @@ def save_cache(
         metadata = {
             "schema_version": SCHEMA_VERSION,
             "classes": json.dumps(class_names),
+            "class_modules": json.dumps(class_modules),
             "meta_state": json.dumps(meta_state, default=str),
+            "state_scalars": json.dumps(state_scalars),
             "token_ids": json.dumps(token_ids),
             "model_fingerprint": model_fingerprint,
             "saved_at": str(time.time()),
@@ -193,17 +221,31 @@ def load_cache(
 
     try:
         class_names = json.loads(metadata.get("classes", "[]"))
+        class_modules = json.loads(metadata.get("class_modules", "[]"))
         meta_state_list = json.loads(metadata.get("meta_state", "[]"))
         token_ids = json.loads(metadata.get("token_ids", "[]"))
+        state_scalars = json.loads(metadata.get("state_scalars", "{}"))
     except json.JSONDecodeError as exc:
         print(f"[cache] metadata parse failed for cache_id={cache_id}: {exc}", flush=True)
         return None
 
-    if not class_names or not token_ids:
+    if (
+        not class_names
+        or len(class_modules) != len(class_names)
+        or not token_ids
+        or not isinstance(state_scalars, dict)
+    ):
         return None
 
     try:
-        layer_states = tree_unflatten(list(flat.items()))
+        # Scalar leaves use the same tree paths as the mmap-backed arrays, so
+        # merging the two flat maps reconstructs the original cache state
+        # exactly. Reject an overlap rather than letting metadata replace a
+        # tensor silently.
+        if set(flat).intersection(state_scalars):
+            print(f"[cache] scalar/array path overlap for cache_id={cache_id}; ignoring", flush=True)
+            return None
+        layer_states = tree_unflatten([*flat.items(), *state_scalars.items()])
     except Exception as exc:  # noqa: BLE001
         print(f"[cache] tree_unflatten failed for cache_id={cache_id}: {exc}", flush=True)
         return None
@@ -217,8 +259,10 @@ def load_cache(
         return None
 
     cache_layers: list[Any] = []
-    for cls_name, meta, layer_state in zip(class_names, meta_state_list, layer_states):
-        cls = _resolve_cache_class(cls_name)
+    for cls_name, cls_module, meta, layer_state in zip(
+        class_names, class_modules, meta_state_list, layer_states
+    ):
+        cls = _resolve_cache_class(cls_name, cls_module)
         if cls is None:
             print(
                 f"[cache] unknown cache class {cls_name!r} for cache_id={cache_id}; ignoring",

package/dist/providers/mlx/python/gezel_mlx_server.py

@@ -80,6 +80,7 @@ import tool_call_stream  # noqa: E402
 import template_stability  # noqa: E402
 from lfm2_compat import ensure_lfm2_config_compat  # noqa: E402
 from qwen3_5_text_compat import is_text_only_qwen3_5_checkpoint  # noqa: E402
+from qwen4_ple import prepare_external_ple_view  # noqa: E402
 
 
 def log_contained_exception(tag: str) -> None:
@@ -266,6 +267,28 @@ def _tool_call_close_stop_ids(model_dir: str) -> "List[int]":
 
 parser = argparse.ArgumentParser(description="gezel MLX wrapper server")
 parser.add_argument("--model", required=True, help="Path to the MLX model directory")
+parser.add_argument(
+    "--external-ple-dir",
+    type=str,
+    default=None,
+    help=(
+        "Derived model-view directory for Qwen4's disk-backed PLE table. "
+        "Applicable checkpoints are hard-linked into this view and the large "
+        "n-gram table is memory-mapped by mlx-vlm 0.7.1. Other model families "
+        "keep the source directory; an eligible Qwen4 checkpoint fails safely "
+        "when the configured runtime cannot prepare the view."
+    ),
+)
+parser.add_argument(
+    "--allow-resident-ple-fallback",
+    action="store_true",
+    help=(
+        "Advanced/manual override: if a quantized Qwen4 checkpoint is eligible "
+        "for --external-ple-dir but the derived view cannot be prepared, load "
+        "the full PLE table resident. Gezel never passes this because its "
+        "catalog working-set reservation assumes external PLE is active."
+    ),
+)
 parser.add_argument("--host", default="127.0.0.1")
 parser.add_argument("--port", type=int, default=8080)
 parser.add_argument(
@@ -508,6 +531,22 @@ _start_parent_death_watchdog()
 
 print(f"Started server process [{os.getpid()}]", flush=True)
 print("Waiting for application startup.", flush=True)
+_SOURCE_MODEL_DIR = ARGS.model
+ARGS.model, _ple_status, _ple_applicable = prepare_external_ple_view(
+    ARGS.model, ARGS.external_ple_dir
+)
+if ARGS.model != _SOURCE_MODEL_DIR:
+    print(f"[ple] external view {_ple_status}: {ARGS.model}", flush=True)
+elif ARGS.external_ple_dir:
+    if not _ple_applicable:
+        print(f"[ple] not applicable: {_ple_status}", flush=True)
+    elif ARGS.allow_resident_ple_fallback:
+        print(f"[ple] resident fallback explicitly allowed: {_ple_status}", flush=True)
+    else:
+        raise RuntimeError(
+            "external Qwen4 PLE view is required by the planned memory footprint "
+            f"but could not be prepared: {_ple_status}"
+        )
 print(f"Loading model from: {ARGS.model}", flush=True)
 _LFM2_FF_DIM = ensure_lfm2_config_compat(ARGS.model)
 if _LFM2_FF_DIM is not None:
@@ -729,7 +768,11 @@ def _metal_recommended_working_set() -> int:
     """Metal's `max_recommended_working_set_size` (bytes), or 0 if unavailable.
     This is the OS's own soft ceiling for GPU-resident memory."""
     try:
-        info = mx.metal.device_info()
+        # mlx 0.32.2 (resolved by mlx-vlm 0.7.1) deprecates the old
+        # mx.metal.device_info() namespace. Keep the fallback so an operator's
+        # older, explicitly configured mlx package still gets a useful cap.
+        device_info = getattr(mx, "device_info", None)
+        info = device_info() if callable(device_info) else mx.metal.device_info()
         return int(info.get("max_recommended_working_set_size", 0) or 0)
     except Exception:  # noqa: BLE001 — API shape varies across mlx versions
         return 0

package/dist/providers/mlx/python/qwen4_ple.py

@@ -0,0 +1,159 @@
+"""Prepare MLX-VLM 0.7.1's disk-backed Qwen4 PLE model view.
+
+Qwen3.8 Flash Next's hashed n-gram table is tens of GiB.  Loading every row
+into Metal leaves a 128 GiB Mac with very little room for KV and activations,
+even though a turn touches only a tiny fraction of those rows.  mlx-vlm 0.7.1
+ships ``prepare_external_ple_model`` and ``QuantizedMMapNGramEmbedding`` for
+this exact checkpoint shape.
+
+The view contains hard links to the ordinary model shards plus a small index
+that excludes resident PLE tensors.  The original install stays immutable and
+is still the source of mmap reads.  Publication is lock-protected and atomic,
+so concurrent replicas cannot observe a half-built view.
+"""
+
+from __future__ import annotations
+
+import fcntl
+import hashlib
+import json
+import os
+import shutil
+import uuid
+from pathlib import Path
+from typing import Callable, Optional, Tuple
+
+
+PLE_MARKER = ".ple.ple_embedding.ngram_embedding.shards."
+VIEW_MARKER = "GEZEL_PLE_VIEW.json"
+
+
+def _read_json(path: Path):
+    try:
+        return json.loads(path.read_text())
+    except (OSError, ValueError, TypeError):
+        return None
+
+
+def _file_sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as stream:
+        for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def checkpoint_signature(source: Path) -> Optional[dict]:
+    """Return the cheap immutable identity used to validate a derived view."""
+    config_path = source / "config.json"
+    index_path = source / "model.safetensors.index.json"
+    config = _read_json(config_path)
+    index = _read_json(index_path)
+    if not isinstance(config, dict) or not isinstance(index, dict):
+        return None
+
+    text_config = config.get("text_config")
+    if not isinstance(text_config, dict):
+        text_config = {}
+    model_types = {str(config.get("model_type", "")), str(text_config.get("model_type", ""))}
+    if not ({"qwen4_exp", "qwen4_exp_text"} & model_types):
+        return None
+
+    weight_map = index.get("weight_map")
+    if not isinstance(weight_map, dict) or not any(PLE_MARKER in str(key) for key in weight_map):
+        return None
+
+    return {
+        "source": str(source.resolve()),
+        "config_sha256": _file_sha256(config_path),
+        "index_sha256": _file_sha256(index_path),
+    }
+
+
+def _valid_view(target: Path, signature: dict) -> bool:
+    marker = _read_json(target / VIEW_MARKER)
+    config = _read_json(target / "config.json")
+    ple_manifest = target / "ple-store.json"
+    if marker != signature or not isinstance(config, dict) or not ple_manifest.is_file():
+        return False
+    text_config = config.get("text_config")
+    ple_storage = text_config.get("ple_storage") if isinstance(text_config, dict) else None
+    return isinstance(ple_storage, dict) and ple_storage.get("manifest") == ple_manifest.name
+
+
+def _same_device_target(source: Path, requested: Path) -> Path:
+    """Prefer the managed view root, then a same-volume sibling if needed."""
+    requested.parent.mkdir(parents=True, exist_ok=True)
+    if source.stat().st_dev == requested.parent.stat().st_dev:
+        return requested
+    sibling = source.parent / ".gezel-views" / requested.name
+    sibling.parent.mkdir(parents=True, exist_ok=True)
+    return sibling
+
+
+def prepare_external_ple_view(
+    source_dir: str,
+    requested_view_dir: Optional[str],
+    *,
+    prepare_fn: Optional[Callable[..., object]] = None,
+) -> Tuple[str, str, bool]:
+    """Return ``(effective_model_dir, status, applicable)``.
+
+    Any unsupported shape or contained preparation failure returns the source
+    directory plus a diagnostic status. The caller decides whether a resident
+    fallback is safe for its memory reservation; Gezel's managed launcher
+    requires the view for applicable checkpoints.
+    """
+    source = Path(source_dir).expanduser().resolve()
+    if not requested_view_dir:
+        return str(source), "disabled", False
+    try:
+        signature = checkpoint_signature(source)
+    except OSError as exc:
+        return str(source), f"signature unavailable: {exc}", False
+    if signature is None:
+        return str(source), "not a quantized Qwen4 PLE checkpoint", False
+
+    try:
+        target = _same_device_target(source, Path(requested_view_dir).expanduser().resolve())
+    except OSError as exc:
+        return str(source), f"view root unavailable: {exc}", True
+
+    lock_path = target.parent / f".{target.name}.lock"
+    try:
+        with lock_path.open("a+b") as lock:
+            fcntl.flock(lock.fileno(), fcntl.LOCK_EX)
+            if _valid_view(target, signature):
+                return str(target), "reused", True
+
+            # A SIGKILL during an earlier publication can leave a sibling
+            # staging directory whose hard links would otherwise retain the
+            # checkpoint after a later model deletion. The per-target lock
+            # makes these unambiguously stale here.
+            for stale in target.parent.glob(f".{target.name}.*.partial"):
+                if stale.is_dir():
+                    shutil.rmtree(stale, ignore_errors=True)
+
+            if prepare_fn is None:
+                try:
+                    from mlx_vlm.models.qwen4_exp.ple_storage import (
+                        prepare_external_ple_model,
+                    )
+                except Exception as exc:  # noqa: BLE001 - optional across configured runtimes
+                    return str(source), f"mlx-vlm external PLE unavailable: {exc}", True
+                prepare_fn = prepare_external_ple_model
+
+            if target.exists():
+                shutil.rmtree(target)
+            staging = target.parent / f".{target.name}.{os.getpid()}.{uuid.uuid4().hex}.partial"
+            try:
+                prepare_fn(source, staging, cache_rows=0)
+                (staging / VIEW_MARKER).write_text(json.dumps(signature, indent=2) + "\n")
+                os.rename(staging, target)
+            finally:
+                shutil.rmtree(staging, ignore_errors=True)
+            if not _valid_view(target, signature):
+                return str(source), "prepared view failed validation", True
+            return str(target), "prepared", True
+    except Exception as exc:  # noqa: BLE001 - report a contained preparation failure
+        return str(source), f"preparation failed: {exc}", True