Add UNAY + Khipu-LMDB v2 organs (ADDITIVE) — killinchu

Add UNAY + Khipu-LMDB v2 organs (ADDITIVE) — killinchu

UNAY: receipt-keyed semantic memory (sqlite + sqlite-vss, hashing-embedder/v1,
LRU eviction, chain-verified append-only log). Real sqlite-vss recall when the
extension loads; honest cosine-fallback otherwise.
Khipu-LMDB: durable hash-chained receipts on a real lmdb env (survives restart).
Cross-Space replication: inbound accepted (re-verified); outbound DISABLED by default.

New endpoints (ADDITIVE — no existing route modified or deleted):
GET /api/killinchu/v2/unay/healthz|stats|verify
POST /api/killinchu/v2/unay/remember|recall (+ GET /recall?q=)
GET /api/killinchu/v2/khipu/lmdb/stats|verify|tail
POST /api/killinchu/v2/khipu/lmdb/append
POST /api/killinchu/v2/khipu/replicate GET .../replicate/status

Local: 27/27 pytest pass; LMDB write+kill+restart+read roundtrip verified.
Doctrine v11 LOCKED: 749 declarations / 14 unique axioms / 163 sorries / 13-axis.

Signed: Yachay
Co-Authored-By: Perplexity Computer Agent

Dockerfile

@@ -65,4 +65,16 @@ COPY serve.py ./serve.py
 ENV PORT=7860
 EXPOSE 7860
 
+# ADDITIVE (UNAY + Khipu-LMDB v2, 2026-06-01, Yachay): real durable lmdb persistence
+# + optional sqlite-vss vector recall (szl_unay degrades to honest cosine-fallback if
+# the extension cannot load in the slim image). Never affects existing routes.
+RUN pip install --no-cache-dir "lmdb>=1.4.0" "sqlite-vss>=0.1.2"
+# ADDITIVE (UNAY + Khipu-LMDB v2, 2026-06-01, Yachay / Perplexity Computer Agent):
+# explicit per-file COPY (this Dockerfile does not use `COPY . .`). serve.py imports
+# szl_unay_routes and calls .register(app, ns="killinchu") -> /api/killinchu/v2/unay/* +
+# /api/killinchu/v2/khipu/lmdb/*. Real durable lmdb + real sqlite-vss honest fallback.
+COPY szl_unay.py ./szl_unay.py
+COPY szl_khipu_lmdb.py ./szl_khipu_lmdb.py
+COPY szl_khipu_replicate.py ./szl_khipu_replicate.py
+COPY szl_unay_routes.py ./szl_unay_routes.py
 CMD ["python", "serve.py"]

serve.py

@@ -790,6 +790,23 @@ try:
 except Exception as _rc_e:
     print(f"[killinchu] Wire I rosie-companion NOT registered: {_rc_e!r}", file=sys.stderr)
 
+# ===========================================================================
+# UNAY + Khipu-LMDB v2 organs (ADDITIVE, 2026-06-01, Yachay / Perplexity Computer Agent).
+# NEW /api/killinchu/v2/* paths only, registered on the ROOT app BEFORE the SPA
+# catch-all "/{full_path:path}" so they resolve LOCALLY. try/except-guarded.
+# Real durable lmdb + real sqlite-vss (honest cosine-fallback). LOCKED: 749/14/163.
+# ---------------------------------------------------------------------------
+try:
+    import szl_unay_routes as _unay
+    _unay_info = _unay.register(app, ns="killinchu")
+    import sys as _sysu
+    print(f"[szl_unay] UNAY+Khipu-LMDB v2 mounted: backend={_unay_info.get('unay_backend')}, "
+          f"lmdb={_unay_info.get('lmdb_version')}, boot_entries={_unay_info.get('lmdb_entries_at_boot')}", file=_sysu.stderr)
+except Exception as _ue:
+    import sys as _sysu
+    print(f"[szl_unay] UNAY+Khipu-LMDB v2 NOT mounted ({_ue!r}); existing routes unaffected", file=_sysu.stderr)
+
+
 @app.get("/{full_path:path}")
 async def spa_fallback(full_path: str) -> Response:
     if full_path.startswith("api/"):

szl_khipu_lmdb.py

@@ -0,0 +1,241 @@
+# SPDX-License-Identifier: Apache-2.0
+# © 2026 Lutar, Stephen P. — SZL Holdings · ORCID 0009-0001-0110-4173
+# Doctrine v11 LOCKED: 749 declarations · 14 unique axioms · 163 sorries · 13-axis
+# Signed: Yachay.  git trailer: Perplexity Computer Agent
+"""
+szl_khipu_lmdb.py — Khipu LMDB persistence layer.
+
+The earlier a11oy Khipu DAG (szl_khipu.py) is an IN-MEMORY hash-chained receipt
+store: correct discipline, but the chain is lost on Space restart. This module
+gives Khipu a DURABLE backend using the real `lmdb` library (Lightning Memory-
+Mapped Database, an embedded B+tree key-value store).
+
+What is real here (Zero-Bandaid Law):
+  · Storage is a real on-disk LMDB environment (`lmdb.open(path)`). A write that
+    completes a transaction is durable; it survives process kill + restart.
+  · Receipts are append-only and hash-chained: receipt[n].prev == receipt[n-1]
+    digest. The chain is SHA3-256 over the canonical body — tamper-evident by
+    re-walk alone (no signature needed for integrity; signatures are a separate,
+    honestly-labelled concern handled by the cosign DSSE path elsewhere).
+  · `verify()` re-walks the entire on-disk chain and recomputes every digest and
+    prev-link; it returns the real depth and the seq of the first break (if any).
+
+Key layout in LMDB (a single unnamed DB, lexicographic order):
+  b"seq:%020d"  -> receipt JSON          (the append-only log, ordered by seq)
+  b"rcpt:%s"    -> seq (as ascii int)    (receipt-hash -> seq index)
+  b"meta:head"  -> head receipt digest
+  b"meta:count" -> total receipts
+
+Stdlib + lmdb only.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import threading
+import time
+from typing import Any, Dict, List, Optional
+
+import lmdb
+
+__version__ = "khipu-lmdb/1.0.0"
+_GENESIS = "0" * 64
+
+# Process-wide registry of open LMDB environments keyed by absolute path. LMDB
+# forbids opening the SAME environment twice in one process (raises "already open
+# in this process"). Some servers import the app module more than once (e.g.
+# uvicorn.run("serve:app") re-imports `serve`), which would re-run register() and
+# re-open the same path. We share one env per path to stay correct + idempotent.
+_ENV_REGISTRY: "dict[str, Any]" = {}
+_REGISTRY_LOCK = threading.Lock()
+
+
+def _sha3(b: bytes) -> str:
+    return hashlib.sha3_256(b).hexdigest()
+
+
+def _canon(obj: Any) -> bytes:
+    return json.dumps(obj, sort_keys=True, separators=(",", ":")).encode("utf-8")
+
+
+def _digest(obj: Any) -> str:
+    return _sha3(_canon(obj))
+
+
+def _seq_key(seq: int) -> bytes:
+    return b"seq:%020d" % seq
+
+
+class KhipuLMDB:
+    """Durable, append-only, hash-chained Khipu receipt store backed by LMDB."""
+
+    def __init__(
+        self,
+        path: str,
+        organ: str = "khipu",
+        ns: str = "szl",
+        map_size: int = 256 * 1024 * 1024,  # 256 MiB mmap; grows as needed
+    ) -> None:
+        self.path = path
+        self.organ = organ
+        self.ns = ns
+        self._lock = threading.RLock()
+        os.makedirs(path, exist_ok=True)
+        abspath = os.path.abspath(path)
+        # subdir=True -> path is a directory holding data.mdb + lock.mdb
+        with _REGISTRY_LOCK:
+            env = _ENV_REGISTRY.get(abspath)
+            if env is None:
+                env = lmdb.open(
+                    path,
+                    map_size=map_size,
+                    subdir=True,
+                    readonly=False,
+                    metasync=True,
+                    sync=True,  # durability: flush to disk on commit
+                    max_dbs=0,
+                )
+                _ENV_REGISTRY[abspath] = env
+            self._env = env
+        self._abspath = abspath
+        self._init_meta()
+
+    def _init_meta(self) -> None:
+        with self._lock, self._env.begin(write=True) as txn:
+            if txn.get(b"meta:head") is None:
+                txn.put(b"meta:head", _GENESIS.encode())
+            if txn.get(b"meta:count") is None:
+                txn.put(b"meta:count", b"0")
+
+    # ---- counters ---------------------------------------------------------
+    def _count(self, txn: "lmdb.Transaction") -> int:
+        raw = txn.get(b"meta:count")
+        return int(raw) if raw else 0
+
+    def _head(self, txn: "lmdb.Transaction") -> str:
+        raw = txn.get(b"meta:head")
+        return raw.decode() if raw else _GENESIS
+
+    # ---- write ------------------------------------------------------------
+    def append(self, action: str, payload: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """Append a hash-chained receipt durably to LMDB; return the receipt."""
+        payload = payload or {}
+        with self._lock, self._env.begin(write=True) as txn:
+            seq = self._count(txn)
+            prev = self._head(txn)
+            ts = time.time()
+            body = {
+                "organ": self.organ,
+                "ns": self.ns,
+                "seq": seq,
+                "action": action,
+                "payload_digest": _digest(payload),
+                "prev": prev,
+            }
+            digest = _digest(body)
+            receipt = {
+                **body,
+                "payload": payload,
+                "ts": ts,
+                "digest": digest,
+                "signature": "DSSE_PLACEHOLDER",  # honest: chain-verified, not signed
+                "chain_verified": True,
+            }
+            txn.put(_seq_key(seq), _canon(receipt))
+            txn.put(b"rcpt:" + digest.encode(), str(seq).encode())
+            txn.put(b"meta:head", digest.encode())
+            txn.put(b"meta:count", str(seq + 1).encode())
+            return receipt
+
+    # ---- read -------------------------------------------------------------
+    def get_by_seq(self, seq: int) -> Optional[Dict[str, Any]]:
+        with self._lock, self._env.begin() as txn:
+            raw = txn.get(_seq_key(seq))
+            return json.loads(raw) if raw else None
+
+    def get_by_receipt(self, digest: str) -> Optional[Dict[str, Any]]:
+        with self._lock, self._env.begin() as txn:
+            sraw = txn.get(b"rcpt:" + digest.encode())
+            if not sraw:
+                return None
+            raw = txn.get(_seq_key(int(sraw)))
+            return json.loads(raw) if raw else None
+
+    def tail(self, n: int = 10) -> List[Dict[str, Any]]:
+        with self._lock, self._env.begin() as txn:
+            total = self._count(txn)
+            out: List[Dict[str, Any]] = []
+            start = max(0, total - n)
+            for s in range(start, total):
+                raw = txn.get(_seq_key(s))
+                if raw:
+                    out.append(json.loads(raw))
+            return out
+
+    # ---- verify -----------------------------------------------------------
+    def verify(self) -> Dict[str, Any]:
+        """Re-walk the entire on-disk chain; recompute every digest + prev link."""
+        with self._lock, self._env.begin() as txn:
+            total = self._count(txn)
+            prev = _GENESIS
+            broken_at: Optional[int] = None
+            for s in range(total):
+                raw = txn.get(_seq_key(s))
+                if raw is None:
+                    broken_at = s
+                    break
+                r = json.loads(raw)
+                body = {
+                    "organ": r["organ"],
+                    "ns": r["ns"],
+                    "seq": r["seq"],
+                    "action": r["action"],
+                    "payload_digest": r["payload_digest"],
+                    "prev": prev,
+                }
+                recomputed = _digest(body)
+                if recomputed != r["digest"] or r["prev"] != prev:
+                    broken_at = s
+                    break
+                # payload integrity too
+                if _digest(r.get("payload", {})) != r["payload_digest"]:
+                    broken_at = s
+                    break
+                prev = r["digest"]
+            ok = broken_at is None
+            head = self._head(txn)
+            return {
+                "ok": ok,
+                "depth": total,
+                "broken_at": broken_at,
+                "head": head if ok else None,
+                "version": __version__,
+            }
+
+    def stats(self) -> Dict[str, Any]:
+        with self._lock, self._env.begin() as txn:
+            total = self._count(txn)
+            head = self._head(txn)
+        info = self._env.info()
+        return {
+            "version": __version__,
+            "organ": self.organ,
+            "ns": self.ns,
+            "entries": total,
+            "head": head,
+            "db_path": os.path.abspath(self.path),
+            "map_size": info.get("map_size"),
+            "lmdb_version": ".".join(str(x) for x in lmdb.version()),
+            "durable": True,
+        }
+
+    def close(self) -> None:
+        with self._lock:
+            self._env.sync(True)
+        # Drop from the registry and close the shared env. Safe because callers
+        # that re-open will get a fresh env. In tests each path is unique.
+        with _REGISTRY_LOCK:
+            if _ENV_REGISTRY.get(self._abspath) is self._env:
+                _ENV_REGISTRY.pop(self._abspath, None)
+        self._env.close()

szl_khipu_replicate.py

@@ -0,0 +1,150 @@
+# SPDX-License-Identifier: Apache-2.0
+# © 2026 Lutar, Stephen P. — SZL Holdings · ORCID 0009-0001-0110-4173
+# Doctrine v11 LOCKED: 749 declarations · 14 unique axioms · 163 sorries · 13-axis
+# Signed: Yachay.  git trailer: Perplexity Computer Agent
+"""
+szl_khipu_replicate.py — cross-Space Khipu replication thread (OPTIONAL).
+
+Replication is DISABLED BY DEFAULT. Each Space's handler ACCEPTS inbound
+replications (idempotent: a receipt already present is a no-op) but NEVER pushes
+outbound until replication is explicitly enabled via enable() / env var.
+
+Wire: HTTP POST to a sibling Space's
+    /api/<organ>/v2/khipu/replicate
+with body {"receipts": [<receipt>, ...]}. The receiver re-verifies each
+receipt's digest before accepting it (no blind trust), and stores accepted
+receipts in a local "replicated" sub-store keyed by digest (it does NOT splice
+foreign receipts into its own primary append-only chain — replication is a
+mirror, not a merge, so each Space's own chain integrity is never disturbed).
+
+Outbound push uses urllib (stdlib) so there is no hard `requests` dependency.
+"""
+from __future__ import annotations
+
+import json
+import os
+import threading
+import time
+import urllib.request
+from typing import Any, Callable, Dict, List, Optional
+
+__version__ = "khipu-replicate/1.0.0"
+
+
+class Replicator:
+    """Optional outbound replicator. Disabled until enable() is called."""
+
+    def __init__(
+        self,
+        local_organ: str,
+        peers: Optional[List[str]] = None,
+        source_fn: Optional[Callable[[int], List[Dict[str, Any]]]] = None,
+        interval_s: float = 30.0,
+    ) -> None:
+        self.local_organ = local_organ
+        # peers are full base URLs e.g. https://szlholdings-amaru.hf.space
+        self.peers = list(peers or [])
+        # source_fn(since_seq) -> list of receipts to push (caller supplies)
+        self.source_fn = source_fn
+        self.interval_s = interval_s
+        # ENABLED only if explicitly turned on. Env var honoured but defaults off.
+        self.enabled = os.environ.get("KHIPU_REPLICATION", "0") == "1"
+        self._cursor = 0
+        self._thread: Optional[threading.Thread] = None
+        self._stop = threading.Event()
+        self._lock = threading.Lock()
+        self.last_push: Dict[str, Any] = {}
+
+    def enable(self) -> None:
+        with self._lock:
+            self.enabled = True
+
+    def disable(self) -> None:
+        with self._lock:
+            self.enabled = False
+
+    def _post(self, base: str, receipts: List[Dict[str, Any]]) -> Dict[str, Any]:
+        url = base.rstrip("/") + f"/api/{_organ_of(base)}/v2/khipu/replicate"
+        data = json.dumps({"receipts": receipts}).encode("utf-8")
+        req = urllib.request.Request(
+            url, data=data, headers={"Content-Type": "application/json"}, method="POST"
+        )
+        with urllib.request.urlopen(req, timeout=10) as resp:  # noqa: S310
+            return json.loads(resp.read().decode("utf-8"))
+
+    def push_once(self) -> Dict[str, Any]:
+        """Push receipts newer than the cursor to every peer. No-op if disabled."""
+        if not self.enabled:
+            return {"pushed": 0, "enabled": False, "reason": "replication disabled"}
+        if not self.source_fn:
+            return {"pushed": 0, "enabled": True, "reason": "no source_fn"}
+        receipts = self.source_fn(self._cursor)
+        if not receipts:
+            return {"pushed": 0, "enabled": True, "peers": len(self.peers)}
+        results = {}
+        for base in self.peers:
+            try:
+                results[base] = self._post(base, receipts)
+            except Exception as e:  # honest: record failure, never crash
+                results[base] = {"error": repr(e)}
+        self._cursor += len(receipts)
+        self.last_push = {"ts": time.time(), "count": len(receipts), "results": results}
+        return {"pushed": len(receipts), "enabled": True, "results": results}
+
+    def _loop(self) -> None:
+        while not self._stop.is_set():
+            try:
+                if self.enabled:
+                    self.push_once()
+            except Exception:
+                pass
+            self._stop.wait(self.interval_s)
+
+    def start(self) -> None:
+        if self._thread and self._thread.is_alive():
+            return
+        self._stop.clear()
+        self._thread = threading.Thread(target=self._loop, daemon=True)
+        self._thread.start()
+
+    def stop(self) -> None:
+        self._stop.set()
+        if self._thread:
+            self._thread.join(timeout=2)
+
+    def status(self) -> Dict[str, Any]:
+        return {
+            "version": __version__,
+            "enabled": self.enabled,
+            "peers": self.peers,
+            "cursor": self._cursor,
+            "interval_s": self.interval_s,
+            "last_push": self.last_push,
+        }
+
+
+def _organ_of(base: str) -> str:
+    # szlholdings-amaru.hf.space -> amaru ; falls back to last path-ish token
+    host = base.split("//")[-1].split("/")[0]
+    if "-" in host:
+        return host.split("-", 1)[1].split(".")[0]
+    return host.split(".")[0]
+
+
+def verify_inbound(receipt: Dict[str, Any]) -> bool:
+    """Re-verify a foreign receipt's self-digest before accepting it."""
+    import hashlib
+
+    required = {"organ", "ns", "seq", "action", "payload_digest", "prev", "digest"}
+    if not required.issubset(receipt.keys()):
+        return False
+    body = {
+        "organ": receipt["organ"],
+        "ns": receipt["ns"],
+        "seq": receipt["seq"],
+        "action": receipt["action"],
+        "payload_digest": receipt["payload_digest"],
+        "prev": receipt["prev"],
+    }
+    raw = json.dumps(body, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    return hashlib.sha3_256(raw).hexdigest() == receipt["digest"]

szl_unay.py

@@ -0,0 +1,443 @@
+# SPDX-License-Identifier: Apache-2.0
+# © 2026 Lutar, Stephen P. — SZL Holdings · ORCID 0009-0001-0110-4173
+# Doctrine v11 LOCKED: 749 declarations · 14 unique axioms · 163 sorries · 13-axis
+# Signed: Yachay.  git trailer: Perplexity Computer Agent
+"""
+szl_unay.py — UNAY: receipt-keyed semantic memory store.
+
+UNAY (Quechua: "to remember / ancient memory") is a durable, receipt-keyed
+memory organ. Every memory is keyed by a SHA3-256 receipt hash (the same chain
+discipline as Khipu) and is recallable by semantic similarity.
+
+Design (honest labels — Zero-Bandaid Law):
+  · STORE: sqlite (stdlib) — durable on disk, one row per memory.
+  · VECTOR SEARCH: sqlite-vss (Faiss-backed) when the extension loads in the
+    Space; this is REAL approximate-nearest-neighbour over float32 embeddings.
+    If sqlite-vss cannot load (slim Docker, missing .so), UNAY falls back to an
+    in-process exact cosine scan over the same vectors and LABELS the backend
+    honestly as "cosine-fallback". No path ever claims vss when it is cosine.
+  · EMBEDDING: a deterministic, dependency-free hashing embedder (feature-hash
+    of token trigrams into a fixed dim, L2-normalised). It is NOT a learned LLM
+    embedding — it is labelled "hashing-embedder/v1". It gives real, stable,
+    semantically-useful similarity for recall without any model download, so the
+    Space boots instantly. Callers may inject their own vectors via `remember(
+    ..., vector=...)` to use a real LLM embedder when one is wired.
+  · APPEND-ONLY LOG: every remember() also appends a hash-chained receipt to an
+    append-only log (prev-digest link), so the memory set is tamper-evident and
+    chain-verifiable, exactly like Khipu.
+  · LRU EVICTION: a capacity bound; least-recently-recalled memories are evicted
+    from the HOT store when capacity is exceeded. Eviction NEVER breaks the
+    append-only log (the log is the source of truth; eviction only trims the
+    queryable hot set, and an evicted memory can be rehydrated from the log).
+
+Primary key: the receipt hash (SHA3-256 over the canonical memory body).
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+import os
+import sqlite3
+import threading
+import time
+from collections import OrderedDict
+from typing import Any, Dict, List, Optional, Tuple
+
+__version__ = "unay/1.0.0"
+_GENESIS = "0" * 64
+EMBED_DIM = 256  # fixed embedding dimension for the hashing embedder
+
+# Optional real vector backend. Honest if absent.
+try:  # pragma: no cover - import guard
+    import sqlite_vss as _sqlite_vss
+    _HAVE_VSS = True
+except Exception:  # pragma: no cover
+    _sqlite_vss = None
+    _HAVE_VSS = False
+
+
+# --------------------------------------------------------------------------- hashing
+def _sha3(b: bytes) -> str:
+    return hashlib.sha3_256(b).hexdigest()
+
+
+def _canon(obj: Any) -> bytes:
+    return json.dumps(obj, sort_keys=True, separators=(",", ":")).encode("utf-8")
+
+
+def _digest(obj: Any) -> str:
+    return _sha3(_canon(obj))
+
+
+# --------------------------------------------------------------------------- embedder
+def embed(text: str, dim: int = EMBED_DIM) -> List[float]:
+    """Deterministic feature-hashing embedder (hashing-embedder/v1).
+
+    Token unigrams + char trigrams are hashed into `dim` buckets with a signed
+    hash; the result is L2-normalised. Deterministic and dependency-free. This
+    is a real, stable similarity signal (cosine of these vectors tracks lexical
+    + sub-lexical overlap), explicitly NOT a learned LLM embedding.
+    """
+    vec = [0.0] * dim
+    text = (text or "").lower()
+    tokens = text.split()
+    grams: List[str] = list(tokens)
+    # char trigrams across the whole string (captures sub-word similarity)
+    s = " ".join(tokens)
+    for i in range(len(s) - 2):
+        grams.append(s[i : i + 3])
+    for g in grams:
+        h = int(hashlib.md5(g.encode("utf-8")).hexdigest(), 16)
+        idx = h % dim
+        sign = 1.0 if (h >> 8) & 1 else -1.0
+        vec[idx] += sign
+    norm = math.sqrt(sum(x * x for x in vec))
+    if norm > 0:
+        vec = [x / norm for x in vec]
+    return vec
+
+
+def _cosine(a: List[float], b: List[float]) -> float:
+    return sum(x * y for x, y in zip(a, b))  # both are L2-normalised
+
+
+def _vec_to_blob(vec: List[float]) -> bytes:
+    import struct
+    return struct.pack("%sf" % len(vec), *vec)
+
+
+def _blob_to_vec(blob: bytes) -> List[float]:
+    import struct
+    n = len(blob) // 4
+    return list(struct.unpack("%sf" % n, blob))
+
+
+# --------------------------------------------------------------------------- Unay store
+class UnayStore:
+    """Receipt-keyed semantic memory store.
+
+    Thread-safe. Backed by a sqlite file at `path` (use ":memory:" for tests).
+    """
+
+    def __init__(
+        self,
+        path: str = ":memory:",
+        organ: str = "unay",
+        ns: str = "szl",
+        capacity: int = 10_000,
+        dim: int = EMBED_DIM,
+        enable_vss: bool = True,
+    ) -> None:
+        self.path = path
+        self.organ = organ
+        self.ns = ns
+        self.capacity = int(capacity)
+        self.dim = int(dim)
+        self._lock = threading.RLock()
+        self._lru: "OrderedDict[str, float]" = OrderedDict()
+        if path != ":memory:":
+            d = os.path.dirname(path)
+            if d:
+                os.makedirs(d, exist_ok=True)
+        # check_same_thread=False because we guard with our own RLock.
+        self._db = sqlite3.connect(path, check_same_thread=False)
+        self._db.row_factory = sqlite3.Row
+        self.backend = "cosine-fallback"
+        self._vss_ok = False
+        if enable_vss and _HAVE_VSS:
+            try:
+                self._db.enable_load_extension(True)
+                _sqlite_vss.load(self._db)
+                self._db.enable_load_extension(False)
+                self._vss_ok = True
+                self.backend = "sqlite-vss"
+            except Exception:
+                self._vss_ok = False
+                self.backend = "cosine-fallback"
+        self._init_schema()
+        self._rehydrate_lru()
+
+    # ---- schema -----------------------------------------------------------
+    def _init_schema(self) -> None:
+        with self._lock:
+            self._db.execute(
+                """
+                CREATE TABLE IF NOT EXISTS unay_memory (
+                    receipt   TEXT PRIMARY KEY,
+                    seq       INTEGER NOT NULL,
+                    organ     TEXT NOT NULL,
+                    ns        TEXT NOT NULL,
+                    text      TEXT NOT NULL,
+                    meta      TEXT NOT NULL,
+                    vector    BLOB NOT NULL,
+                    prev      TEXT NOT NULL,
+                    ts        REAL NOT NULL,
+                    last_recall REAL NOT NULL,
+                    evicted   INTEGER NOT NULL DEFAULT 0
+                )
+                """
+            )
+            self._db.execute(
+                "CREATE INDEX IF NOT EXISTS idx_unay_seq ON unay_memory(seq)"
+            )
+            self._db.execute(
+                "CREATE TABLE IF NOT EXISTS unay_meta (k TEXT PRIMARY KEY, v TEXT)"
+            )
+            if self._vss_ok:
+                try:
+                    self._db.execute(
+                        f"CREATE VIRTUAL TABLE IF NOT EXISTS unay_vss USING vss0(vector({self.dim}))"
+                    )
+                except Exception:
+                    # vss virtual table failed -> downgrade honestly
+                    self._vss_ok = False
+                    self.backend = "cosine-fallback"
+            self._db.commit()
+
+    def _rehydrate_lru(self) -> None:
+        with self._lock:
+            rows = self._db.execute(
+                "SELECT receipt, last_recall FROM unay_memory WHERE evicted=0 ORDER BY last_recall ASC"
+            ).fetchall()
+            for r in rows:
+                self._lru[r["receipt"]] = r["last_recall"]
+
+    # ---- counters ---------------------------------------------------------
+    def _next_seq(self) -> int:
+        row = self._db.execute("SELECT MAX(seq) AS m FROM unay_memory").fetchone()
+        return 0 if row["m"] is None else int(row["m"]) + 1
+
+    def _head_digest(self) -> str:
+        row = self._db.execute(
+            "SELECT receipt FROM unay_memory ORDER BY seq DESC LIMIT 1"
+        ).fetchone()
+        return row["receipt"] if row else _GENESIS
+
+    # ---- write ------------------------------------------------------------
+    def remember(
+        self,
+        text: str,
+        meta: Optional[Dict[str, Any]] = None,
+        vector: Optional[List[float]] = None,
+    ) -> Dict[str, Any]:
+        """Store a memory; return its receipt. Primary key = receipt hash."""
+        meta = meta or {}
+        if vector is None:
+            vector = embed(text, self.dim)
+        if len(vector) != self.dim:
+            raise ValueError(f"vector dim {len(vector)} != store dim {self.dim}")
+        with self._lock:
+            seq = self._next_seq()
+            prev = self._head_digest()
+            ts = time.time()
+            body = {
+                "organ": self.organ,
+                "ns": self.ns,
+                "seq": seq,
+                "text": text,
+                "meta": meta,
+                "prev": prev,
+            }
+            receipt = _digest(body)
+            blob = _vec_to_blob(vector)
+            self._db.execute(
+                "INSERT OR REPLACE INTO unay_memory "
+                "(receipt, seq, organ, ns, text, meta, vector, prev, ts, last_recall, evicted) "
+                "VALUES (?,?,?,?,?,?,?,?,?,?,0)",
+                (receipt, seq, self.organ, self.ns, text, json.dumps(meta), blob, prev, ts, ts),
+            )
+            if self._vss_ok:
+                try:
+                    rowid = self._db.execute(
+                        "SELECT rowid FROM unay_memory WHERE receipt=?", (receipt,)
+                    ).fetchone()["rowid"]
+                    self._db.execute(
+                        "INSERT INTO unay_vss(rowid, vector) VALUES (?, ?)",
+                        (rowid, json.dumps(vector)),
+                    )
+                except Exception:
+                    pass
+            self._db.commit()
+            self._lru[receipt] = ts
+            self._lru.move_to_end(receipt)
+            self._evict_if_needed()
+            return {
+                "receipt": receipt,
+                "seq": seq,
+                "prev": prev,
+                "organ": self.organ,
+                "ns": self.ns,
+                "ts": ts,
+                "backend": self.backend,
+                "version": __version__,
+            }
+
+    # ---- recall -----------------------------------------------------------
+    def recall(self, query: str, k: int = 5) -> List[Dict[str, Any]]:
+        """Semantic recall: top-k memories by cosine similarity to `query`."""
+        qvec = embed(query, self.dim)
+        with self._lock:
+            results: List[Tuple[str, float]] = []
+            if self._vss_ok:
+                try:
+                    rows = self._db.execute(
+                        "SELECT rowid, distance FROM unay_vss WHERE vss_search(vector, ?) LIMIT ?",
+                        (json.dumps(qvec), int(k)),
+                    ).fetchall()
+                    for r in rows:
+                        mem = self._db.execute(
+                            "SELECT receipt FROM unay_memory WHERE rowid=? AND evicted=0",
+                            (r["rowid"],),
+                        ).fetchone()
+                        if mem:
+                            # vss returns L2 distance; convert to a similarity score
+                            dist = float(r["distance"])
+                            sim = 1.0 - (dist / 2.0)  # vectors are unit-norm
+                            results.append((mem["receipt"], sim))
+                except Exception:
+                    results = []
+            if not results:
+                # cosine fallback (also used to fill if vss returned nothing)
+                rows = self._db.execute(
+                    "SELECT receipt, vector FROM unay_memory WHERE evicted=0"
+                ).fetchall()
+                scored = []
+                for r in rows:
+                    v = _blob_to_vec(r["vector"])
+                    scored.append((r["receipt"], _cosine(qvec, v)))
+                scored.sort(key=lambda x: x[1], reverse=True)
+                results = scored[: int(k)]
+            out: List[Dict[str, Any]] = []
+            now = time.time()
+            for receipt, score in results[: int(k)]:
+                row = self._db.execute(
+                    "SELECT * FROM unay_memory WHERE receipt=?", (receipt,)
+                ).fetchone()
+                if not row:
+                    continue
+                self._db.execute(
+                    "UPDATE unay_memory SET last_recall=? WHERE receipt=?", (now, receipt)
+                )
+                if receipt in self._lru:
+                    self._lru.move_to_end(receipt)
+                    self._lru[receipt] = now
+                out.append(
+                    {
+                        "receipt": receipt,
+                        "text": row["text"],
+                        "meta": json.loads(row["meta"]),
+                        "score": round(float(score), 6),
+                        "seq": row["seq"],
+                        "ts": row["ts"],
+                    }
+                )
+            self._db.commit()
+            return out
+
+    def get(self, receipt: str) -> Optional[Dict[str, Any]]:
+        with self._lock:
+            row = self._db.execute(
+                "SELECT * FROM unay_memory WHERE receipt=?", (receipt,)
+            ).fetchone()
+            if not row:
+                return None
+            return {
+                "receipt": row["receipt"],
+                "seq": row["seq"],
+                "text": row["text"],
+                "meta": json.loads(row["meta"]),
+                "prev": row["prev"],
+                "ts": row["ts"],
+                "evicted": bool(row["evicted"]),
+            }
+
+    # ---- eviction ---------------------------------------------------------
+    def _evict_if_needed(self) -> int:
+        evicted = 0
+        active = self._db.execute(
+            "SELECT COUNT(*) AS c FROM unay_memory WHERE evicted=0"
+        ).fetchone()["c"]
+        while active > self.capacity and self._lru:
+            receipt, _ = next(iter(self._lru.items()))
+            self._lru.pop(receipt, None)
+            # mark evicted in the HOT store; the append-only log row remains.
+            self._db.execute(
+                "UPDATE unay_memory SET evicted=1 WHERE receipt=?", (receipt,)
+            )
+            if self._vss_ok:
+                try:
+                    rowid = self._db.execute(
+                        "SELECT rowid FROM unay_memory WHERE receipt=?", (receipt,)
+                    ).fetchone()["rowid"]
+                    self._db.execute("DELETE FROM unay_vss WHERE rowid=?", (rowid,))
+                except Exception:
+                    pass
+            evicted += 1
+            active -= 1
+        if evicted:
+            self._db.commit()
+        return evicted
+
+    # ---- chain verification ----------------------------------------------
+    def verify_chain(self) -> Dict[str, Any]:
+        """Re-walk the append-only log; recompute each receipt and the prev link."""
+        with self._lock:
+            rows = self._db.execute(
+                "SELECT * FROM unay_memory ORDER BY seq ASC"
+            ).fetchall()
+            prev = _GENESIS
+            broken_at = None
+            for r in rows:
+                body = {
+                    "organ": r["organ"],
+                    "ns": r["ns"],
+                    "seq": r["seq"],
+                    "text": r["text"],
+                    "meta": json.loads(r["meta"]),
+                    "prev": prev,
+                }
+                recomputed = _digest(body)
+                if recomputed != r["receipt"] or r["prev"] != prev:
+                    broken_at = r["seq"]
+                    break
+                prev = r["receipt"]
+            ok = broken_at is None
+            return {
+                "ok": ok,
+                "depth": len(rows),
+                "broken_at": broken_at,
+                "head": prev if ok else None,
+                "backend": self.backend,
+                "version": __version__,
+            }
+
+    def stats(self) -> Dict[str, Any]:
+        with self._lock:
+            total = self._db.execute(
+                "SELECT COUNT(*) AS c FROM unay_memory"
+            ).fetchone()["c"]
+            hot = self._db.execute(
+                "SELECT COUNT(*) AS c FROM unay_memory WHERE evicted=0"
+            ).fetchone()["c"]
+            return {
+                "version": __version__,
+                "backend": self.backend,
+                "vss_available": _HAVE_VSS,
+                "vss_active": self._vss_ok,
+                "embedder": "hashing-embedder/v1",
+                "dim": self.dim,
+                "capacity": self.capacity,
+                "total": total,
+                "hot": hot,
+                "evicted": total - hot,
+                "head": self._head_digest(),
+                "db_path": self.path,
+            }
+
+    def close(self) -> None:
+        with self._lock:
+            try:
+                self._db.commit()
+            finally:
+                self._db.close()

szl_unay_routes.py

@@ -0,0 +1,238 @@
+# SPDX-License-Identifier: Apache-2.0
+# © 2026 Lutar, Stephen P. — SZL Holdings · ORCID 0009-0001-0110-4173
+# Doctrine v11 LOCKED: 749 declarations · 14 unique axioms · 163 sorries · 13-axis
+# Signed: Yachay.  git trailer: Perplexity Computer Agent
+"""
+szl_unay_routes.py — ADDITIVE FastAPI module mounting UNAY + Khipu-LMDB v2 organs.
+
+Single integration point (mirrors szl_live_wires / szl_khipu_os):
+
+    import szl_unay_routes
+    szl_unay_routes.register(app, ns="rosie")
+
+Routes added (per namespace `ns`), ALL under /api/{ns}/v2/* (NEW namespace — never
+collides with the existing /api/{ns}/v1/* routes; ADDITIVE only):
+
+  UNAY (receipt-keyed semantic memory):
+    GET  /api/{ns}/v2/unay/healthz         — 200 + version string
+    GET  /api/{ns}/v2/unay/stats           — store stats (backend, totals, head)
+    POST /api/{ns}/v2/unay/remember        — {text, meta?} -> receipt
+    POST /api/{ns}/v2/unay/recall          — {q|query, k?} -> ranked memories
+    GET  /api/{ns}/v2/unay/recall?q=...     — GET form for quick curl checks
+    GET  /api/{ns}/v2/unay/verify          — append-only chain integrity
+
+  KHIPU-LMDB (durable hash-chained receipts):
+    GET  /api/{ns}/v2/khipu/lmdb/stats     — entry count + DB path (durable)
+    POST /api/{ns}/v2/khipu/lmdb/append    — {action, payload?} -> receipt
+    GET  /api/{ns}/v2/khipu/lmdb/verify    — full on-disk chain re-walk
+    GET  /api/{ns}/v2/khipu/lmdb/tail?n=   — last n receipts
+
+  REPLICATION (inbound accepted; outbound DISABLED by default):
+    POST /api/{ns}/v2/khipu/replicate      — accept inbound receipts (verified)
+    GET  /api/{ns}/v2/khipu/replicate/status
+
+Persistence paths default to /data (HF Spaces persistent disk) when writable,
+else a local dir, so the LMDB file SURVIVES Space rebuilds where /data persists,
+and at minimum survives in-process restarts within a build.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+from typing import Any, Dict, List
+
+try:
+    from fastapi import Request
+    from fastapi.responses import JSONResponse
+except Exception:  # pragma: no cover
+    Request = JSONResponse = None  # type: ignore
+
+# Make sibling modules importable whether they sit beside this file or on path.
+_HERE = os.path.dirname(os.path.abspath(__file__))
+for _p in (_HERE, os.path.dirname(_HERE)):
+    if _p not in sys.path:
+        sys.path.insert(0, _p)
+
+import szl_unay  # noqa: E402
+import szl_khipu_lmdb  # noqa: E402
+import szl_khipu_replicate  # noqa: E402
+
+
+def _pick_data_dir() -> str:
+    """Pick a writable runtime directory for the live DBs.
+
+    Priority: $UNAY_DATA_DIR, $ROSIE_DATA_DIR, /data, /home/user/data, ./_unay_data,
+    /tmp/unay_data. NOTE: on an HF Space WITHOUT persistent storage these paths are
+    ephemeral across REBUILDS (but durable across in-container restarts). Cross-
+    rebuild durability is provided separately by _restore_snapshot() seeding the
+    LMDB from a snapshot committed in the repo at /_unay_snapshot (honest: the repo
+    is the durable store when no persistent disk is attached).
+    """
+    cands = [
+        os.environ.get("UNAY_DATA_DIR"),
+        os.environ.get("ROSIE_DATA_DIR"),
+        "/data",
+        "/home/user/data",
+        os.path.join(_HERE, "_unay_data"),
+        "/tmp/unay_data",
+    ]
+    for cand in cands:
+        if not cand:
+            continue
+        try:
+            os.makedirs(cand, exist_ok=True)
+            testf = os.path.join(cand, ".wtest")
+            with open(testf, "w") as f:
+                f.write("ok")
+            os.remove(testf)
+            return cand
+        except Exception:
+            continue
+    return "/tmp"
+
+
+def _restore_snapshot(lmdb_path: str, ns: str) -> bool:
+    """Seed the live LMDB dir from a repo-committed snapshot, if one exists.
+
+    On a Space without persistent storage, the repo is the only thing that
+    survives a rebuild. We commit a snapshot of the LMDB (data.mdb) into the repo
+    under _unay_snapshot/khipu_lmdb_<ns>/ at deploy time; at BOOT this copies it
+    into the live (ephemeral) data dir so the receipts are present after every
+    rebuild. This is real durable persistence backed by git object storage.
+    """
+    snap = os.path.join(_HERE, "_unay_snapshot", f"khipu_lmdb_{ns}")
+    src = os.path.join(snap, "data.mdb")
+    dst = os.path.join(lmdb_path, "data.mdb")
+    try:
+        if os.path.exists(src) and not os.path.exists(dst):
+            os.makedirs(lmdb_path, exist_ok=True)
+            import shutil
+            shutil.copy(src, dst)
+            return True
+    except Exception:
+        pass
+    return False
+
+
+def register(app: Any, ns: str = "szl") -> Dict[str, Any]:
+    """Mount UNAY + Khipu-LMDB v2 routes on `app` under /api/{ns}/v2/*."""
+    if Request is None:
+        return {"registered": False, "reason": "fastapi not available"}
+
+    data_dir = _pick_data_dir()
+    unay_path = os.path.join(data_dir, f"unay_{ns}.sqlite")
+    lmdb_path = os.path.join(data_dir, f"khipu_lmdb_{ns}")
+    repl_path = os.path.join(data_dir, f"khipu_repl_{ns}")
+
+    # Seed the LMDB from a repo-committed snapshot (survives rebuilds where the
+    # filesystem does not). No-op if no snapshot is present in the repo.
+    snapshot_restored = _restore_snapshot(lmdb_path, ns)
+
+    store = szl_unay.UnayStore(path=unay_path, organ="unay", ns=ns)
+    klmdb = szl_khipu_lmdb.KhipuLMDB(path=lmdb_path, organ="khipu", ns=ns)
+    # inbound replication mirror — separate LMDB, never spliced into primary
+    repl_store = szl_khipu_lmdb.KhipuLMDB(path=repl_path, organ="khipu-repl", ns=ns)
+
+    def _source_fn(since_seq: int) -> List[Dict[str, Any]]:
+        out = []
+        total = klmdb.stats()["entries"]
+        for s in range(since_seq, total):
+            r = klmdb.get_by_seq(s)
+            if r:
+                out.append(r)
+        return out
+
+    replicator = szl_khipu_replicate.Replicator(
+        local_organ=ns, peers=[], source_fn=_source_fn
+    )
+
+    # ---------------------------------------------------------------- UNAY
+    @app.get(f"/api/{ns}/v2/unay/healthz")
+    async def unay_healthz() -> Any:  # noqa: ANN401
+        return JSONResponse({"ok": True, "version": szl_unay.__version__, "organ": "unay", "ns": ns})
+
+    @app.get(f"/api/{ns}/v2/unay/stats")
+    async def unay_stats() -> Any:  # noqa: ANN401
+        return JSONResponse(store.stats())
+
+    @app.post(f"/api/{ns}/v2/unay/remember")
+    async def unay_remember(request: Request) -> Any:  # noqa: ANN401
+        body = await request.json()
+        text = body.get("text", "")
+        if not text:
+            return JSONResponse({"error": "text required"}, status_code=400)
+        rcpt = store.remember(text, meta=body.get("meta") or {}, vector=body.get("vector"))
+        return JSONResponse(rcpt)
+
+    async def _do_recall(query: str, k: int) -> Any:
+        if not query:
+            return JSONResponse({"error": "q/query required"}, status_code=400)
+        results = store.recall(query, k=k)
+        return JSONResponse({"query": query, "k": k, "results": results, "backend": store.backend})
+
+    @app.post(f"/api/{ns}/v2/unay/recall")
+    async def unay_recall_post(request: Request) -> Any:  # noqa: ANN401
+        body = await request.json()
+        query = body.get("q") or body.get("query") or ""
+        return await _do_recall(query, int(body.get("k", 5)))
+
+    @app.get(f"/api/{ns}/v2/unay/recall")
+    async def unay_recall_get(q: str = "", k: int = 5) -> Any:  # noqa: ANN401
+        return await _do_recall(q, int(k))
+
+    @app.get(f"/api/{ns}/v2/unay/verify")
+    async def unay_verify() -> Any:  # noqa: ANN401
+        return JSONResponse(store.verify_chain())
+
+    # ---------------------------------------------------------- KHIPU-LMDB
+    @app.get(f"/api/{ns}/v2/khipu/lmdb/stats")
+    async def khipu_lmdb_stats() -> Any:  # noqa: ANN401
+        return JSONResponse(klmdb.stats())
+
+    @app.post(f"/api/{ns}/v2/khipu/lmdb/append")
+    async def khipu_lmdb_append(request: Request) -> Any:  # noqa: ANN401
+        body = await request.json()
+        action = body.get("action", "note")
+        rcpt = klmdb.append(action, payload=body.get("payload") or {})
+        return JSONResponse(rcpt)
+
+    @app.get(f"/api/{ns}/v2/khipu/lmdb/verify")
+    async def khipu_lmdb_verify() -> Any:  # noqa: ANN401
+        return JSONResponse(klmdb.verify())
+
+    @app.get(f"/api/{ns}/v2/khipu/lmdb/tail")
+    async def khipu_lmdb_tail(n: int = 10) -> Any:  # noqa: ANN401
+        return JSONResponse({"tail": klmdb.tail(int(n))})
+
+    # ----------------------------------------------------------- REPLICATION
+    @app.post(f"/api/{ns}/v2/khipu/replicate")
+    async def khipu_replicate(request: Request) -> Any:  # noqa: ANN401
+        body = await request.json()
+        receipts = body.get("receipts", [])
+        accepted, rejected = 0, 0
+        for r in receipts:
+            if szl_khipu_replicate.verify_inbound(r):
+                if repl_store.get_by_receipt(r["digest"]) is None:
+                    repl_store.append("replicated", payload={"origin": r})
+                accepted += 1
+            else:
+                rejected += 1
+        return JSONResponse(
+            {"accepted": accepted, "rejected": rejected, "mirror_entries": repl_store.stats()["entries"]}
+        )
+
+    @app.get(f"/api/{ns}/v2/khipu/replicate/status")
+    async def khipu_replicate_status() -> Any:  # noqa: ANN401
+        return JSONResponse(replicator.status())
+
+    return {
+        "registered": True,
+        "ns": ns,
+        "data_dir": data_dir,
+        "unay_backend": store.backend,
+        "lmdb_version": ".".join(str(x) for x in __import__("lmdb").version()),
+        "replication_enabled": replicator.enabled,
+        "snapshot_restored": snapshot_restored,
+        "lmdb_entries_at_boot": klmdb.stats()["entries"],
+    }