deja-cli 0.2.1__tar.gz → 0.3.1__tar.gz

{deja_cli-0.2.1 → deja_cli-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deja-cli
-Version: 0.2.1
+Version: 0.3.1
 Summary: Local-first persistent memory CLI for coding agents
 Author-email: Mike <mike@bigtreeproduction.com>
 License: MIT

{deja_cli-0.2.1 → deja_cli-0.3.1}/deja/cloud.py

@@ -12,13 +12,90 @@ import threading
 import webbrowser
 from http.server import BaseHTTPRequestHandler, HTTPServer
 from pathlib import Path
-from typing import Callable, Iterator, Optional
+from typing import Callable, Iterator, Optional, Union
 from urllib.parse import parse_qs, urlparse
 
 import httpx
+from pydantic import BaseModel, ConfigDict, Field
 
 logger = logging.getLogger(__name__)
 
+
+# ── Typed payloads (R8, 2026-04-22 review) ──────────────────────────────────
+# Replace the previous ``dict → dict`` boundary at auth + push with typed
+# Pydantic models. The bugs the prior pass caught (N5 trigger→triggerCmds
+# silent drop; N6 endpoint not persisted in auth; theoretical AuthState
+# typo wedging every command) all lived in dict access patterns where a
+# missing or misspelled key was indistinguishable from "field not set."
+# Pydantic models make construction the single point that enforces the
+# field contract.
+
+
+class AuthState(BaseModel):
+    """The contents of ``~/.deja/auth.json``.
+
+    ``access_token`` is the PAT; ``endpoint`` is the host the token was
+    issued by (Bug N6, 2026-04-19) and travels with the credential — it
+    overrides ``config.cloud.endpoint`` so a token issued by host A is
+    never sent to host B. The two extra OAuth-flow fields (``token_type``,
+    ``user_id``) are tolerated but not required so legacy auth files keep
+    parsing.
+    """
+
+    model_config = ConfigDict(extra="allow")  # tolerate forward-compat fields
+
+    access_token: str
+    endpoint: Optional[str] = None
+    token_type: Optional[str] = None
+    user_id: Optional[str] = None
+
+
+class CloudPushPayload(BaseModel):
+    """The shape ``POST /v1/memories`` and ``POST /v1/sync/push`` accept.
+
+    The cloud uses ``forbidNonWhitelisted`` validation, so any unknown
+    key 400s. The previous string-allowlist filter dropped fields whose
+    canonical name on the cloud side differs from the local schema —
+    most notoriously the local ``trigger`` (comma string) vs cloud
+    ``triggerCmds`` (list[str]) (Bug N5). Pydantic aliases handle the
+    rename in one place.
+
+    Field set / aliases must match the cloud DTO at
+    ``apps/api/src/memories/dto/create-memory.dto.ts``. When the cloud
+    adds a new accepted field, add it here with the correct alias and
+    every save path picks it up automatically.
+    """
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    # Required identification
+    local_id: str = Field(serialization_alias="localId")
+    content: str
+    type: str
+    scope: str
+    # Optional metadata accepted by the cloud (must match the cloud DTO —
+    # ``domain`` / ``source`` / ``entity_graph`` / ``embedding`` / the
+    # raw ``trigger`` comma-string / timestamps other than lastConfirmed
+    # are deliberately excluded; the cloud rejects unknown keys with a
+    # 400 under ``forbidNonWhitelisted``).
+    project: Optional[str] = None
+    confidence: Optional[float] = None
+    category: Optional[str] = None
+    trigger_cmds: Optional[list[str]] = Field(
+        default=None, serialization_alias="triggerCmds",
+    )
+    last_confirmed: Optional[str] = Field(
+        default=None, serialization_alias="lastConfirmed",
+    )
+    archived: Optional[bool] = None
+    archived_at: Optional[str] = Field(
+        default=None, serialization_alias="archivedAt",
+    )
+
+    def to_wire(self) -> dict:
+        """Serialize to the camelCase shape the cloud DTO expects, dropping Nones."""
+        return self.model_dump(by_alias=True, exclude_none=True)
+
 CLI_REDIRECT_PORT = 51234
 
 AUTH_FILE = Path.home() / ".deja" / "auth.json"
@@ -46,8 +123,8 @@ def _get_endpoint(config=None) -> str:
     "where these specific creds belong."
     """
     auth = load_auth()
-    if auth and auth.get("endpoint"):
-        return str(auth["endpoint"]).rstrip("/")
+    if auth and auth.endpoint:
+        return str(auth.endpoint).rstrip("/")
     if config is None:
         return DEFAULT_ENDPOINT
     cloud = getattr(config, "cloud", None)
@@ -59,13 +136,22 @@ def _get_endpoint(config=None) -> str:
 # ── Token storage ─────────────────────────────────────────────────────
 
 
-def load_auth() -> Optional[dict]:
+def load_auth() -> Optional[AuthState]:
+    """Read ``~/.deja/auth.json`` into a typed AuthState, or None if absent.
+
+    R8 (2026-04-22 review): previously returned ``Optional[dict]`` and
+    every caller did ``auth.get("access_token")`` / ``auth.get("endpoint")``.
+    A future caller passing ``{"token": ...}`` instead of
+    ``{"access_token": ...}`` would silently wedge every subsequent
+    command. Pydantic construction now rejects that at the boundary.
+    """
     if not AUTH_FILE.exists():
         return None
-    return json.loads(AUTH_FILE.read_text())
+    raw = json.loads(AUTH_FILE.read_text())
+    return AuthState.model_validate(raw)
 
 
-def save_auth(data: dict) -> None:
+def save_auth(data: Union[AuthState, dict]) -> None:
     # Bug Q2 (2026-04-19 pass 3): atomic rewrite. ``Path.write_text``
     # truncates then writes, so a crash mid-write (Ctrl-C, OOM, kernel
     # panic) leaves ``auth.json`` empty or half-written — ``load_auth``
@@ -75,8 +161,14 @@ def save_auth(data: dict) -> None:
     # same directory + ``os.replace`` + cleanup on failure.
     # Bug Q3 (2026-04-19 pass 3): 0700 on the parent so new installs
     # don't create a world-readable ~/.deja.
+    # Accept either a typed ``AuthState`` or a raw dict (for legacy callers
+    # / tests). Normalize via model construction so a dict missing
+    # ``access_token`` raises a validation error here, not later when a
+    # caller tries to read the field.
+    if not isinstance(data, AuthState):
+        data = AuthState.model_validate(data)
     AUTH_FILE.parent.mkdir(exist_ok=True, mode=0o700)
-    payload = json.dumps(data, indent=2)
+    payload = json.dumps(data.model_dump(exclude_none=True), indent=2)
     fd, tmp_name = tempfile.mkstemp(
         prefix=".auth.", suffix=".tmp", dir=AUTH_FILE.parent,
     )
@@ -104,7 +196,7 @@ def get_token(config=None) -> Optional[str]:
     auth = load_auth()
     if not auth:
         return None
-    return auth.get("access_token")
+    return auth.access_token
 
 
 # ── Browser login flow ────────────────────────────────────────────────
@@ -190,9 +282,6 @@ def whoami(config=None) -> Optional[dict]:
 # ── Save to cloud ─────────────────────────────────────────────────────
 
 
-_PUSH_FIELDS = {"content", "type", "project", "confidence", "triggerCmds", "category"}
-
-
 def push_memory(memory: dict, config=None) -> tuple[bool, Optional[str]]:
     """Push a single memory to cloud. Best-effort, never raises.
 
@@ -411,47 +500,57 @@ def save_stuck_ids(endpoint: str, stuck: dict[str, str]) -> None:
 def _sanitize_for_push(memory: dict) -> dict:
     """Convert a local memory dict to the shape the cloud API accepts.
 
-    The cloud uses ``forbidNonWhitelisted`` validation, so any key not on the
-    DTO causes ``HTTP 400 "property X should not exist"``. This function
-    (1) filters to the snake_case allowlist ``_PUSH_FIELDS`` and (2) maps the
-    snake_case local schema fields that have a different camelCase name on
-    the cloud DTO (``last_confirmed``→``lastConfirmed``, ``archived_at``→
-    ``archivedAt``, plus the synthetic ``archived`` boolean derived from
-    ``archived_at IS NOT NULL`` since the local schema has no boolean column).
-
-    Bug N5 (2026-04-19): the local schema stores command-boundary triggers as
-    a snake-case ``trigger`` comma-string (``"alembic upgrade, db migrate"``),
-    while the cloud DTO expects camelCase ``triggerCmds: list[str]``. The
-    pre-fix sanitizer's allowlist filter dropped ``trigger`` (wrong key) and
-    never synthesized ``triggerCmds``, so the **batch** push path
-    (``sync_push`` → ``_sanitize_for_push``) silently lost every trigger on
-    every backlog flush. Single-row pushes worked only because the two
-    eager-push call sites manually pre-translated before calling
-    ``push_memory``. Translation is now done here so all three codepaths
-    (eager-CLI, eager-MCP, batch-sync) share one source of truth.
-
-    Keep this in sync with ``CreateMemoryDto`` in
+    The cloud uses ``forbidNonWhitelisted`` validation, so any key not on
+    the DTO causes ``HTTP 400 "property X should not exist"``. R8
+    (2026-04-22 review) replaces the previous string-allowlist filter
+    with a typed :class:`CloudPushPayload`. Construction picks the
+    accepted fields, the model's serialization aliases handle the
+    snake→camel rename in one place (``last_confirmed`` →
+    ``lastConfirmed``, ``archived_at`` → ``archivedAt``,
+    ``trigger`` → ``triggerCmds``), and ``to_wire`` drops fields that
+    are ``None`` so we never send a key whose value the cloud would
+    have to special-case.
+
+    Bug N5 (2026-04-19): the local schema stores command-boundary
+    triggers as a snake-case ``trigger`` comma-string (``"alembic
+    upgrade, db migrate"``), while the cloud DTO expects camelCase
+    ``triggerCmds: list[str]``. The pre-fix sanitizer's allowlist
+    filter dropped ``trigger`` (wrong key) and never synthesized
+    ``triggerCmds``, so the **batch** push path silently lost every
+    trigger on every backlog flush. Translation now lives on the
+    Pydantic model so eager-CLI, eager-MCP, and batch-sync share the
+    one source of truth.
+
+    Keep field set + aliases in sync with ``CreateMemoryDto`` in
     ``~/projects/deja_sh/apps/api/src/memories/dto/create-memory.dto.ts``.
     """
-    payload = {k: v for k, v in memory.items() if k in _PUSH_FIELDS}
-    if "id" in memory:
-        payload["localId"] = memory["id"]
-    payload["scope"] = "global"
-    if memory.get("last_confirmed"):
-        payload["lastConfirmed"] = memory["last_confirmed"]
-    archived_at = memory.get("archived_at")
-    if archived_at:
-        # Local truth is the timestamp; the boolean is derived. Send both so
-        # the cloud has the original archive time for LWW conflict resolution
-        # rather than auto-stamping NOW() on receipt.
-        payload["archived"] = True
-        payload["archivedAt"] = archived_at
     trigger_str = memory.get("trigger")
+    trigger_cmds: Optional[list[str]] = None
     if trigger_str:
         tokens = [t.strip() for t in trigger_str.split(",") if t.strip()]
-        if tokens:
-            payload["triggerCmds"] = tokens
-    return payload
+        trigger_cmds = tokens or None
+
+    archived_at = memory.get("archived_at")
+    payload = CloudPushPayload(
+        local_id=memory.get("id", ""),
+        content=memory.get("content", ""),
+        type=memory.get("type", ""),
+        # Cloud-side scope is flat — the local "global" / "project:<name>"
+        # encoding doesn't apply (the cloud derives scope from its own
+        # ``project`` column).
+        scope="global",
+        project=memory.get("project"),
+        confidence=memory.get("confidence"),
+        category=memory.get("category"),
+        trigger_cmds=trigger_cmds,
+        last_confirmed=memory.get("last_confirmed"),
+        # Send both the boolean and the timestamp so the cloud uses the
+        # original archive time for LWW conflict resolution rather than
+        # auto-stamping NOW() on receipt.
+        archived=True if archived_at else None,
+        archived_at=archived_at,
+    )
+    return payload.to_wire()
 
 
 _PULL_RENAME = {
@@ -532,6 +631,27 @@ def _sanitize_for_pull(memory: dict) -> dict:
     return out
 
 
+class SyncPushPartialError(RuntimeError):
+    """Raised by :func:`sync_push` when a transport failure aborts the
+    push mid-stream. Carries the ``partial`` dict (``accepted``,
+    ``skipped``, ``conflicts``, ``serverTime`` aggregated across the
+    batches that DID land) so callers can persist what landed before
+    the failure rather than re-pushing everything blind.
+
+    Bug N1 (2026-05-01 review): the previous shape raised plain
+    ``RuntimeError`` and discarded ``aggregated["conflicts"]`` —
+    earlier-batch quota / content-too-long rejections never reached
+    the user, who saw "sync push failed" with no list of which rows
+    were already permanently rejected. With LWW upserts the next
+    sync re-pushes everything (safe), but the operator still has no
+    signal about the rejected subset.
+    """
+
+    def __init__(self, message: str, *, partial: dict) -> None:
+        super().__init__(message)
+        self.partial = partial
+
+
 SYNC_PUSH_BATCH_SIZE = 50
 """Max rows per ``POST /v1/sync/push`` body.
 
@@ -593,9 +713,23 @@ def sync_push(memories: list[dict], config=None) -> dict:
         chunk = sanitized[start : start + SYNC_PUSH_BATCH_SIZE]
         resp = httpx.post(url, json={"memories": chunk}, headers=headers, timeout=60)
         if not resp.is_success:
-            raise RuntimeError(
+            # N1 (2026-05-01 review): before raising, log any conflicts
+            # we accumulated from EARLIER successful batches so they're
+            # at least observable — and attach the full partial dict to
+            # the exception so callers that catch ``SyncPushPartialError``
+            # can persist it (e.g. into ``sync_state.json`` so the next
+            # sync knows which rows the cloud already rejected).
+            if aggregated["conflicts"]:
+                logger.warning(
+                    "cloud sync push aborted with %d earlier-batch "
+                    "rejection(s) before the transport error — see "
+                    "exception.partial['conflicts']",
+                    len(aggregated["conflicts"]),
+                )
+            raise SyncPushPartialError(
                 f"sync push failed ({resp.status_code}) after "
-                f"{aggregated['accepted']} accepted in earlier batches: {resp.text}"
+                f"{aggregated['accepted']} accepted in earlier batches: {resp.text}",
+                partial=aggregated,
             )
         body = resp.json()
         aggregated["accepted"] += body.get("accepted", 0) or 0
@@ -642,3 +776,61 @@ def sync_pull(since: Optional[str] = None, config=None) -> dict:
     )
     resp.raise_for_status()
     return resp.json()
+
+
+def get_memory_by_local_id(
+    local_id: str, config=None
+) -> Optional[list[dict]]:
+    """Fetch the cloud's view of a row by its local id (Layer 2 verify).
+
+    Hits ``GET /v1/memories/by-local-id/<local_id>`` (shipped 2026-05-04 on
+    deja_sh) and returns the body — an array of cloud rows matching
+    ``(user_id, local_id)``, sorted ``updatedAt DESC``. Per the cloud
+    contract:
+
+    - ``200`` with an array → success. ``len == 0`` means no row matches.
+      ``len == 1`` is the normal case. ``len > 1`` is an anomaly the
+      verify path is expected to surface (no UNIQUE on
+      ``(user_id, local_id)`` in Postgres yet).
+    - ``404`` → no row matches; surfaced as an empty list so callers can
+      handle "missing" and "anomaly" with one branch.
+    - Anything else → returns ``None`` (best-effort: a transient
+      verification failure must not be conflated with a divergence
+      signal — that would spam ``_stuck`` on every flaky network).
+
+    The call is intentionally one localId at a time; the divergence
+    surface is rare (only fires on push-archive verification today) and
+    the cloud endpoint is single-id by design.
+    """
+    token = get_token(config)
+    if not token:
+        raise RuntimeError("Not logged in. Run `deja login`.")
+    endpoint = _get_endpoint(config)
+    url = f"{endpoint}/v1/memories/by-local-id/{local_id}"
+    try:
+        resp = httpx.get(
+            url,
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=10,
+        )
+    except Exception as exc:
+        logger.warning("verify-by-local-id %s failed: %s", local_id, exc)
+        return None
+    if resp.status_code == 404:
+        return []
+    if not resp.is_success:
+        logger.warning(
+            "verify-by-local-id %s returned %d: %s",
+            local_id, resp.status_code, resp.text[:120],
+        )
+        return None
+    body = resp.json()
+    if isinstance(body, list):
+        return body
+    # Unexpected shape (cloud contract change?). Treat as best-effort
+    # failure rather than asserting; logging gives the operator signal.
+    logger.warning(
+        "verify-by-local-id %s returned non-list body: %r",
+        local_id, body,
+    )
+    return None

{deja_cli-0.2.1 → deja_cli-0.3.1}/deja/core/store/__init__.py

@@ -328,6 +328,25 @@ class MemoryStore:
         db = await self._connection.get()
         return await self._mem().without_embeddings(db, project)
 
+    async def fetch_one_existing_embedding(self) -> Optional[bytes]:
+        """Return one stored embedding blob, or None if no row has one yet.
+
+        Used by ``deja embed`` (N4, 2026-05-01 review) to detect dim
+        mismatch between the vault and the configured embedding model
+        BEFORE the backfill loop starts writing new rows at a different
+        dimension. Cheap probe — single ``LIMIT 1`` SELECT.
+        """
+        db = await self._connection.get()
+        cursor = await db.execute(
+            "SELECT embedding FROM memories WHERE embedding IS NOT NULL "
+            "AND archived_at IS NULL AND invalidated_at IS NULL LIMIT 1"
+        )
+        row = await cursor.fetchone()
+        await cursor.close()
+        if row is None:
+            return None
+        return row["embedding"]
+
     async def update_memory(self, memory_id: str, fields: dict) -> bool:
         """Update allowed metadata fields on an existing active memory.
 
@@ -489,11 +508,32 @@ class MemoryStore:
             if not existing:
                 fields = list(memory.keys())
                 placeholders = ",".join("?" for _ in fields)
-                await db.execute(
-                    f"INSERT INTO memories ({','.join(fields)}) VALUES ({placeholders})",
-                    [memory[f] for f in fields],
-                )
-                return "inserted"
+                try:
+                    await db.execute(
+                        f"INSERT INTO memories ({','.join(fields)}) VALUES ({placeholders})",
+                        [memory[f] for f in fields],
+                    )
+                    return "inserted"
+                except sqlite3.IntegrityError as e:
+                    # Bug L4 (2026-05-04, cloud-sync-divergence doc §Layer 4):
+                    # the partial UNIQUE index ``idx_memories_dedup_unique_active``
+                    # rejects this INSERT because another *different-id* active
+                    # row already holds the same (scope, COALESCE(project,''),
+                    # type, content). Without this catch the IntegrityError
+                    # propagates up, ``deja sync`` aborts mid-pull, the cursor
+                    # never advances, and every subsequent sync re-fails on the
+                    # same row — exactly the wedge observed and hand-recovered
+                    # on 2026-05-04. Resolve via the same survivor algorithm
+                    # as ``backfill_unique_active_dedup_index`` and let pull
+                    # continue.
+                    #
+                    # Match strictly on the index name so the M2 PK-race path
+                    # (``IntegrityError: NOT NULL/UNIQUE constraint failed:
+                    # memories.id``) and any other constraint violation still
+                    # propagate — we only know how to self-heal *this* one.
+                    if "idx_memories_dedup_unique_active" not in str(e):
+                        raise
+                    return await self._resolve_dedup_conflict(db, memory)
             if merge_strategy == "skip":
                 return "skipped"
             if merge_strategy == "overwrite":
@@ -520,15 +560,188 @@ class MemoryStore:
                 new_confidence = min(
                     CONFIDENCE_MAX, existing["confidence"] + CONFIDENCE_BUMP
                 )
+                # Bug FB1 (2026-05-04, cloud-sync feedback loop —
+                # docs/sync-feedback-loop-2026-05-04.md): pre-fix this
+                # path stamped ``updated_at = now`` (local wall-clock).
+                # ``deja sync``'s push filter is ``updated_at > cursor``,
+                # and the cursor is set to the cloud's ``serverTime``
+                # which was captured *before* this upsert ran — so
+                # ``now > cursor`` always, and the pulled row sweeps
+                # straight back into the next push. Cloud's bulkUpsert
+                # then restamps the cloud-side ``updated_at`` on receipt,
+                # the next pull returns the row again, and ``deja sync``
+                # ships the entire mirrored corpus on every cycle
+                # forever (idempotent at the data layer, but turns
+                # every sync into O(corpus) instead of O(delta)).
+                #
+                # Fix: preserve the cloud-supplied ``updated_at`` —
+                # already in ``memory["updated_at"]`` after
+                # ``_sanitize_for_pull`` does the camelCase rename.
+                # ``last_confirmed`` is genuinely changing here (this
+                # IS a re-confirmation event), so it stamps to local
+                # now() unchanged.
+                cloud_updated_at = memory.get("updated_at") or now
                 await db.execute(
                     "UPDATE memories "
                     "SET confidence = ?, last_confirmed = ?, updated_at = ? "
                     "WHERE id = ?",
-                    (new_confidence, now, now, mem_id),
+                    (new_confidence, now, cloud_updated_at, mem_id),
                 )
                 return "updated"
             return "skipped"
 
+    async def _resolve_dedup_conflict(self, db, incoming: dict) -> str:
+        """Pull-side dedup-conflict self-heal (Layer 4 of the 2026-05-04
+        cloud-sync-divergence recovery plan).
+
+        Triggered when ``upsert``'s INSERT trips ``idx_memories_dedup_unique_active``:
+        an active local row already holds the incoming row's
+        (scope, COALESCE(project,''), type, content) tuple under a *different*
+        primary key id (typical cause: cross-machine duplicate where the same
+        content was saved on two machines, both pushed, and the cloud now
+        sends down both copies — see docs/cloud-sync-divergence-2026-05-04.md
+        for the worked example).
+
+        Survivor algorithm — symmetric with
+        :func:`backfill_unique_active_dedup_index` so changes stay in
+        lockstep across the boot-time batch path and this row-time path:
+
+        1. Pick survivor by reuse_count DESC → confidence DESC → id DESC
+           (lex-largest). Deterministic across machines on the same input,
+           so all clients converge on the same survivor without coordination.
+        2. Merge stats onto the survivor: ``SUM(reuse_count)``,
+           ``MAX(confidence)``, ``MAX(updated_at)``, ``MAX(last_confirmed)``,
+           and the union of trigger phrases via :func:`_merge_trigger_phrases`
+           (the single source of truth — same helper SaveService and
+           MaintenanceService use, so trigger semantics never drift).
+        3. Archive the loser (``archived_at = now()``) — never delete; the
+           archive transition will sync back to the cloud on the next push
+           (because ``updated_at`` was just bumped past the cursor) so all
+           machines converge on one-active-per-content with no extra wiring.
+
+        Two paths depending on which row wins the survivor election. Both
+        end in exactly one active row for the content key — the partial
+        UNIQUE index is restored to a satisfied state inside the same
+        transaction, so a crash between the two writes leaves the DB in
+        the original pre-resolve state, never half-merged.
+
+        Runs inside the caller's ``async with self._connection.transaction()``
+        block; never opens its own. Returns one of:
+
+        - ``"merged_existing_archived"`` — incoming won; existing was
+          archived in place and incoming was inserted active with the
+          merged stats.
+        - ``"merged_incoming_archived"`` — existing won; existing's stats
+          were updated in place and incoming was inserted as archived.
+        """
+        now = _now_iso()
+
+        cur = await db.execute(
+            "SELECT id, reuse_count, confidence, trigger, "
+            "       updated_at, last_confirmed "
+            "FROM memories "
+            "WHERE scope = ? AND COALESCE(project, '') = COALESCE(?, '') "
+            "  AND type = ? AND content = ? "
+            "  AND archived_at IS NULL AND invalidated_at IS NULL",
+            (incoming["scope"], incoming.get("project"),
+             incoming["type"], incoming["content"]),
+        )
+        rows = await cur.fetchall()
+        await cur.close()
+        if not rows:
+            # Defensive: the partial UNIQUE fired but we can't find a
+            # matching active row. Either the schema diverged or another
+            # writer archived the row between the IntegrityError and now.
+            # Re-raise rather than guess; the caller's transaction rolls
+            # back cleanly.
+            raise sqlite3.IntegrityError(
+                "idx_memories_dedup_unique_active fired but no matching "
+                "active row found — schema invariant broken"
+            )
+        existing_row = rows[0]  # there can be only one active row by the
+                                # partial UNIQUE itself; defense in depth.
+
+        # Survivor election — same tiebreak chain as the migration's batch
+        # dedup. Tuple comparison: higher reuse_count first, then higher
+        # confidence, then lex-larger id.
+        existing_key = (
+            existing_row["reuse_count"] or 0,
+            existing_row["confidence"] or 0.0,
+            existing_row["id"] or "",
+        )
+        incoming_key = (
+            incoming.get("reuse_count") or 0,
+            incoming.get("confidence") or 0.0,
+            incoming.get("id") or "",
+        )
+        existing_wins = existing_key >= incoming_key
+
+        merged_reuse = (existing_row["reuse_count"] or 0) + (
+            incoming.get("reuse_count") or 0
+        )
+        merged_confidence = max(
+            existing_row["confidence"] or 0.0,
+            incoming.get("confidence") or 0.0,
+        )
+        merged_trigger = _merge_trigger_phrases(
+            existing_row["trigger"], incoming.get("trigger")
+        )
+        merged_updated_at = max(
+            existing_row["updated_at"] or "",
+            incoming.get("updated_at") or "",
+        ) or now
+        merged_last_confirmed = max(
+            existing_row["last_confirmed"] or "",
+            incoming.get("last_confirmed") or "",
+        ) or None
+
+        if existing_wins:
+            # Survivor stays in place; merge stats onto it. Loser (incoming)
+            # lands as a fresh archived row so its id remains resolvable for
+            # any peer that already pulled it under that id.
+            await db.execute(
+                "UPDATE memories "
+                "SET reuse_count = ?, confidence = ?, trigger = ?, "
+                "    updated_at = ?, last_confirmed = ? "
+                "WHERE id = ?",
+                (merged_reuse, merged_confidence, merged_trigger,
+                 merged_updated_at, merged_last_confirmed,
+                 existing_row["id"]),
+            )
+            loser = dict(incoming)
+            loser["archived_at"] = now
+            loser["updated_at"] = now  # bump so the archive transition
+                                       # propagates on next push
+            fields = list(loser.keys())
+            placeholders = ",".join("?" for _ in fields)
+            await db.execute(
+                f"INSERT INTO memories ({','.join(fields)}) "
+                f"VALUES ({placeholders})",
+                [loser[f] for f in fields],
+            )
+            return "merged_incoming_archived"
+
+        # Incoming wins. Archive existing first (clears it from the partial
+        # UNIQUE's active set), then insert incoming with the merged stats.
+        await db.execute(
+            "UPDATE memories SET archived_at = ?, updated_at = ? WHERE id = ?",
+            (now, now, existing_row["id"]),
+        )
+        survivor = dict(incoming)
+        survivor["reuse_count"] = merged_reuse
+        survivor["confidence"] = merged_confidence
+        survivor["trigger"] = merged_trigger
+        survivor["updated_at"] = merged_updated_at
+        survivor["last_confirmed"] = merged_last_confirmed
+        fields = list(survivor.keys())
+        placeholders = ",".join("?" for _ in fields)
+        await db.execute(
+            f"INSERT INTO memories ({','.join(fields)}) "
+            f"VALUES ({placeholders})",
+            [survivor[f] for f in fields],
+        )
+        return "merged_existing_archived"
+
     # ── observations + reflection meta (delegate to repos) ───────────────────
 
     async def save_observation(self, project: Optional[str], content: str) -> str:

{deja_cli-0.2.1 → deja_cli-0.3.1}/deja/core/store/_helpers.py

@@ -99,6 +99,24 @@ def _bytes_to_emb(data: bytes) -> list[float]:
 
 
 def _cosine_similarity(a: list[float], b: list[float]) -> float:
+    """Cosine similarity between two equal-length vectors.
+
+    Bug R20 (2026-04-22 review): raises ``ValueError`` on dim mismatch
+    instead of silently truncating to the shorter length via ``zip``.
+    Truncated cosine produces garbage scores and the user sees no
+    signal — the typical trigger is a vault that mixes embeddings from
+    two different models (e.g. ``nomic-embed-text`` 768-dim → switch to
+    ``mxbai-embed-large`` 1024-dim without re-embedding old rows).
+    Callers in :mod:`deja.core.store.services.search` and
+    :mod:`deja.core.store.services.ranking` catch this and skip the
+    row, logging once per pass.
+    """
+    if len(a) != len(b):
+        raise ValueError(
+            f"cosine_similarity dim mismatch: {len(a)} vs {len(b)}. "
+            "Likely mixed-dim embeddings — re-run `deja embed` with the "
+            "current embedding.model after changing it in ~/.deja/config.yaml."
+        )
     dot = sum(x * y for x, y in zip(a, b))
     mag_a = math.sqrt(sum(x * x for x in a))
     mag_b = math.sqrt(sum(x * x for x in b))