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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deja-cli
-Version: 0.2.0
+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.0 → 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.0 → deja_cli-0.3.1}/deja/core/extractor.py

@@ -97,15 +97,25 @@ async def extract_memories(
 
     user_prompt = f"Session transcript/summary to extract memories from:\n\n{transcript}"
 
-    try:
-        result = await adapter.complete_structured(
-            system=EXTRACTION_SYSTEM,
-            user=user_prompt,
-            schema=EXTRACTION_SCHEMA,
-        )
-    except Exception as e:
-        logger.error("Extraction LLM error: %s", e)
-        return []
+    # Bug R2 (2026-04-22): let adapter / transport / JSON-parse errors
+    # propagate. The previous ``except Exception: return []`` made every
+    # LLM outage indistinguishable from "the model had nothing to
+    # extract." The watcher's ``_process`` then treated the empty list
+    # as a successful extraction and stamped ``_processed[path]`` —
+    # silently burning the transcript. Same bug class as H5 on the read
+    # side. Callers decide:
+    #
+    # - Watcher (``deja/ingest/watchers/base.py``) wraps this call in
+    #   its own try/except and routes to ``_schedule_extraction_retry``
+    #   (bounded N8/P2 backoff: 30s / 2min / 10min, then give up loudly).
+    # - CLI callers (``deja save-session``, ``deja ingest-skills``,
+    #   ``deja backfill``) catch and either exit cleanly or log + skip
+    #   the one file and continue.
+    result = await adapter.complete_structured(
+        system=EXTRACTION_SYSTEM,
+        user=user_prompt,
+        schema=EXTRACTION_SCHEMA,
+    )
 
     memories = result.get("memories", [])
     if not isinstance(memories, list):

{deja_cli-0.2.0 → deja_cli-0.3.1}/deja/core/reflection.py

@@ -336,6 +336,37 @@ class ReflectionEngine:
         await self.store.set_reflection_meta(None, last_archive_at=_now_iso())
         return count
 
+    async def run_dedup_fuzzy(self, project: Optional[str] = None) -> dict:
+        """Bug R4 (2026-04-22): wire fuzzy dedup into scheduled reflection.
+
+        ``MaintenanceService.dedup_fuzzy`` has shipped since the Phase 7
+        restructure but was never invoked from ``run_full`` — while
+        docstrings (MemoryStore, SaveService, MaintenanceService) and
+        user-facing docs (code-reading-guide, plan.md, AGENTS.md,
+        GEMINI.md, repo-strategic-assessment) all asserted it ran at
+        reflection time. Save-side dedup stayed exact-match only, so
+        two-character edits accumulated forever and the vault's
+        top-ranked results filled with near-duplicates over time.
+        Returns ``{"merged": N, "archived": N}``.
+
+        When ``project is None``, fan out per-project + globals (mirrors
+        ``run_reflector(None)``'s N2 pattern). The underlying service's
+        ``dedup_fuzzy(project=None)`` touches only the global bucket
+        because ``fetch_active(None)`` is global-only by convention —
+        so a single call would silently leave every project-scoped
+        near-duplicate unmerged. Fanning out keeps the scheduled pass
+        honest.
+        """
+        if project is not None:
+            return await self.store.dedup_fuzzy(project=project)
+        merged = 0
+        archived = 0
+        for p in await self.store.list_memory_projects():
+            result = await self.store.dedup_fuzzy(project=p)
+            merged += result.get("merged", 0)
+            archived += result.get("archived", 0)
+        return {"merged": merged, "archived": archived}
+
     # ── Agent mode ─────────────────────────────────────────────────────────
 
     async def agent_mode_prompt(self, project: Optional[str] = None) -> str:
@@ -354,26 +385,53 @@ class ReflectionEngine:
         lines = [
             f"You are acting as a memory reflector for project '{project_label}'.",
             "",
-            f"Review the {len(memories)} active memories below and identify any that should be:",
-            f"  1. Archived (stale, no longer relevant):",
-            f"       deja archive <id>",
-            f"  2. Invalidated (contradicted by newer information):",
-            f"       deja invalidate <id>",
-            f"  3. Consolidated (two memories express the same thing):",
-            f"       deja archive <id1>",
-            f"       deja archive <id2>",
+            f"PROCESS EVERY ONE of the {len(memories)} active memories below — not just",
+            "whatever topic the user happened to ask about in this session. The default",
+            "mode of `deja reflect --agent-mode` is a complete sweep: comb every row,",
+            "build a punch list of all obvious issues, then execute the punch list in",
+            "one pass.",
+            "",
+            "Scan for, in roughly this priority order:",
+            "  - Exact-content duplicates (same words across multiple IDs — pick the",
+            "    one with highest reuse_count, archive the rest)",
+            "  - Scope-leaks (same content saved at scope:global AND scope:project:X —",
+            "    keep the correctly-scoped one, archive the other)",
+            "  - Junk / save errors (single-word patterns, truncated content, malformed",
+            "    entries)",
+            "  - Stale stub TODO lists ('next items: 1. X, 2. Y') — typically archive",
+            "  - Untriggered gotchas tied to a specific command boundary (add --trigger)",
+            "  - Misclassified entries (pattern that is really a gotcha; gotcha that is",
+            "    really a preference)",
+            "  - Semantic duplicates (same rule, different wording — fuzzy threshold",
+            "    won't catch these, you must)",
+            "",
+            "Actions:",
+            "  1. Archive (stale, no longer relevant):",
+            "       deja archive <id>",
+            "  2. Invalidate (actively contradicted by newer information):",
+            "       deja invalidate <id>",
+            "  3. Consolidate (two or more memories express the same thing):",
+            "       deja archive <id1>",
+            "       deja archive <id2>",
             f'       deja save "<condensed content>" --type <type>{project_flag}',
-            f"  4. Trigger-tagged (gotcha clearly tied to a specific command but has no trigger):",
-            f'       deja update <id> --trigger "cmd1, cmd2"',
-            f"       Use this for gotchas about what to do right before/after a specific command.",
-            f"       Example triggers: 'kubectl apply', 'alembic upgrade', 'terraform apply'.",
-            f"       Only tag gotchas — not preferences, decisions, or progress.",
-            f"  5. Reclassified (saved as the wrong type — e.g. pattern that is really a gotcha):",
-            f"       deja update <id> --type gotcha",
+            "     (If one existing version is clearly better, just archive the lesser",
+            "     and keep the better as-is — no new save needed.)",
+            "  4. Trigger-tag (gotcha clearly tied to a specific command, no trigger yet):",
+            '       deja update <id> --trigger "cmd1, cmd2"',
+            "       Use this for gotchas about what to do right before/after a specific",
+            "       command. Example triggers: 'kubectl apply', 'alembic upgrade',",
+            "       'terraform apply'. Only tag gotchas — not preferences, decisions,",
+            "       or progress.",
+            "  5. Reclassify (saved as the wrong type — e.g. pattern that is really a",
+            "     gotcha):",
+            "       deja update <id> --type gotcha",
             "",
-            "Be conservative — only act on memories that clearly need attention.",
-            "For trigger tagging: if a gotcha is already tagged (shown as [trigger:...]), skip it.",
-            "If everything looks good, do nothing.",
+            "Be conservative on each ACTION (skip a memory when intent is unclear),",
+            "but exhaustive on COVERAGE (visit every memory, not just user-flagged ones).",
+            "For trigger tagging: if a gotcha is already tagged (shown as [trigger:...]),",
+            "skip it.",
+            f"If after sweeping all {len(memories)} you find nothing actionable, that's",
+            "fine — say so.",
             "",
             "--- MEMORIES ---",
             "",
@@ -395,7 +453,15 @@ class ReflectionEngine:
     # ── Full pass + auto-trigger ────────────────────────────────────────────
 
     async def run_full(self, project: Optional[str] = None) -> dict:
-        """Full reflection pass: observer → reflector → decay → promote → archive."""
+        """Full reflection pass: observer → reflector → decay → promote → dedup_fuzzy → archive.
+
+        Bug R4 (2026-04-22): ``dedup_fuzzy`` slots between ``promote``
+        and ``archive`` — after promotion (so promoted patterns are in
+        the active set for cross-project dedup) and before archival (so
+        archive sweeps low-confidence rows AFTER near-duplicates have
+        been merged, giving the survivor the full merged confidence/
+        reuse bump).
+        """
         results: dict = {}
         if self.adapter:
             results["observer"] = await self.run_observer(project)
@@ -405,6 +471,7 @@ class ReflectionEngine:
             results["reflector"] = 0
         results["decay"] = await self.run_decay()
         results["promote"] = await self.run_promote()
+        results["dedup_fuzzy"] = await self.run_dedup_fuzzy(project)
         results["archive"] = await self.run_archive()
         return results