superlocalmemory 4.0.8 → 4.0.10

package/src/superlocalmemory/server/unified_daemon.py

@@ -26,6 +26,8 @@ License: AGPL-3.0-or-later
 from __future__ import annotations
 
 import asyncio
+import concurrent.futures
+import functools
 import hashlib
 import json
 import logging
@@ -50,7 +52,7 @@ os.environ.setdefault("SLM_MCP_EMBEDDED", "1")
 from fastapi import FastAPI, HTTPException, Request
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.middleware.gzip import GZipMiddleware
-from pydantic import BaseModel
+from pydantic import BaseModel, field_validator
 
 from superlocalmemory.core.config import CANONICAL_RECALL_LIMIT
 from superlocalmemory.infra.daemon_identity import (
@@ -67,6 +69,126 @@ from superlocalmemory.infra.data_root import (
 )
 
 
+def _notify_migration_applied(
+    applied: list,
+    elapsed: float,
+    backup_dir: "Path | None" = None,
+) -> None:
+    """Print a one-line confirmation after migrations complete successfully.
+
+    Written to stdout so it is visible in daemon.log and in interactive runs.
+    """
+    count = len(applied)
+    if count == 0:
+        return
+    parts = [f"[SLM] {count} migration(s) applied in {elapsed:.1f}s."]
+    if backup_dir is not None:
+        parts.append(f"Backup: {backup_dir}")
+    print(" ".join(parts), flush=True)
+
+
+def _write_migration_error_log(
+    failed: list,
+    backup_dir: "Path | None",
+    slm_home: "Path | None" = None,
+    applied: "list | None" = None,
+) -> "Path":
+    """Write a migration-error-{timestamp}.log to the SLM home directory.
+
+    Returns the Path of the written log file.
+    """
+    import datetime
+
+    if slm_home is None:
+        slm_home = canonical_data_root()
+
+    slm_home.mkdir(parents=True, exist_ok=True)
+    ts = datetime.datetime.now().strftime("%Y%m%d-%H%M%S")
+    log_path = slm_home / f"migration-error-{ts}.log"
+
+    lines = [
+        f"Migration error — {ts}",
+        f"Failed: {', '.join(str(f) for f in failed)}",
+    ]
+    # An upgrade is applied step by step and is deliberately non-fatal: some
+    # steps can succeed while a later one fails. Saying "your data was not
+    # modified" whenever a snapshot exists was therefore untrue in exactly the
+    # case that matters — and a user who believes nothing changed may delete the
+    # snapshot to reclaim space.
+    if applied:
+        lines.append(f"Applied before the failure: {', '.join(str(a) for a in applied)}")
+        lines.append(
+            "YOUR DATABASE WAS PARTIALLY CHANGED. The steps listed above "
+            "completed; the ones under 'Failed' did not."
+        )
+    elif applied is not None:
+        lines.append("No steps completed, so your database was not changed.")
+    if backup_dir is not None:
+        lines.append(f"Snapshot of the state before the upgrade: {backup_dir}")
+        lines.append(
+            "That snapshot is intact and can be restored. Keep it until you are "
+            "satisfied your data is correct."
+        )
+    else:
+        lines.append(
+            "NO SNAPSHOT WAS TAKEN for this attempt — do not assume a recovery "
+            "copy exists. Check for earlier snapshots before changing anything."
+        )
+    lines.append("")
+    lines.append("To diagnose, run: slm doctor")
+
+    log_path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    return log_path
+
+
+def _notify_windows_user(message: str) -> None:
+    """Best-effort notification on Windows.  Silent no-op on other platforms."""
+    import sys
+
+    if sys.platform != "win32":
+        return
+
+    # Attempt 1 — Windows MessageBox via PowerShell
+    try:
+        import subprocess
+
+        safe_msg = message.replace("'", "").replace('"', "")
+        subprocess.run(
+            [
+                "powershell",
+                "-Command",
+                "[System.Reflection.Assembly]::LoadWithPartialName"
+                "('System.Windows.Forms') | Out-Null; "
+                f"[System.Windows.Forms.MessageBox]::Show('{safe_msg}', "
+                "'SuperLocalMemory')",
+            ],
+            check=False,
+            timeout=5,
+        )
+        return
+    except Exception:
+        pass
+
+    # Attempt 2 — Windows Application EventLog
+    try:
+        import subprocess
+
+        subprocess.run(
+            [
+                "eventcreate",
+                "/T", "INFORMATION",
+                "/ID", "1001",
+                "/L", "APPLICATION",
+                "/SO", "SuperLocalMemory",
+                "/D", message[:512],
+            ],
+            check=False,
+            timeout=5,
+        )
+    except Exception:
+        pass  # best-effort only
+
+
 def _learning_db_for_config(config) -> Path:
     """Single learning.db path for daemon migration + engine (F-05).
 
@@ -115,11 +237,142 @@ _SOURCE_QUALITY_MAX_BATCH_SIZE = 250
 _SOURCE_QUALITY_PROFILE_REFRESH_SECONDS = 60.0
 _FACT_ENTITY_REPAIR_MIN_RETRY_SECONDS = 0.05
 _FACT_ENTITY_REPAIR_MAX_RETRY_SECONDS = 30.0
-# ``wait=true`` is a compatibility affordance, never permission to hold the
-# ASGI event loop hostage to a local LLM.  Normal clients omit it and receive
-# an immediate durable/queryable receipt; explicit waiters get this small
-# completion window, then the M018 materializer continues in the background.
-_REMEMBER_ENRICHMENT_WAIT_SECONDS = 0.75
+# How long a write may spend making itself findable by meaning before the
+# receipt goes out. Storing a memory has a 1.5 s ceiling, and this is a ceiling
+# rather than a target: the cost of coming in under it is a memory that can only
+# be found by quoting its own wording, which is not how anyone asks. So the
+# window is most of the budget, not a token amount of it. ``wait=true`` is still
+# never permission to hold the event loop open indefinitely — past this the
+# background pass finishes the job.
+# The ceiling for a whole store request, shared by the durable write and the
+# window that makes the memory findable by meaning. Both are sequential, so the
+# second gets what the first left rather than a fresh grant.
+_REMEMBER_TOTAL_CEILING_SECONDS = 1.5
+_REMEMBER_ENRICHMENT_WAIT_SECONDS = 1.2
+
+# Enrichment runs off the event loop, but NOT on the loop's default executor.
+# `asyncio.to_thread` uses that default pool, so N simultaneous writers really did
+# create N threads — and every other handler that borrows the same pool queued
+# behind them. One shared, small pool bounds the cost of a burst: past its width
+# the extra callers miss their deadline and defer, which is the intended
+# degradation, instead of multiplying threads.
+_ENRICHMENT_WORKERS = 2
+_enrichment_pool: "concurrent.futures.ThreadPoolExecutor | None" = None
+_enrichment_pool_lock = threading.Lock()
+
+# Bounds how much enrichment may be in flight at once. A ThreadPoolExecutor
+# queues without limit, so bounding the pool's WIDTH does not bound what can be
+# handed to it: a burst of writers all submit, the first two run, and the rest sit
+# in a queue nobody is waiting for any more — then wake up and write to the
+# database after their callers have already been answered. A permit is taken
+# before submitting and released by the worker when it has really finished, so at
+# most `_ENRICHMENT_WORKERS` pieces of work exist at once and a caller that
+# cannot get one is told immediately instead of being queued.
+_enrichment_semaphore = threading.Semaphore(_ENRICHMENT_WORKERS)
+
+# Set once the pool has been shut down, and never cleared. Without it, a caller
+# that passed the unlocked check below arrives after shutdown, finds None, and
+# builds a replacement pool that the completed shutdown will never reach.
+_enrichment_pool_closed = False
+
+
+class _EnrichmentAtCapacity(Exception):
+    """No permit was free, so nothing was submitted.
+
+    Its own type, so that "we chose not to start" is never reported through the
+    same path as "it started and then failed" — those are different events and
+    only one of them is worth a warning about degradation.
+    """
+
+
+def _enrichment_executor():
+    """The one pool inline enrichment may use. Created on first need.
+
+    Raises ``RuntimeError`` once the pool has been shut down. It deliberately
+    does not return ``None`` on that path: ``run_in_executor(None, ...)`` means
+    *the event loop's default executor*, which is the unbounded-thread behaviour
+    this pool exists to replace, so a None here would silently reintroduce it at
+    exactly the moment the process is trying to stop.
+    """
+    global _enrichment_pool
+    # Everything happens under the lock, including the read that is returned. An
+    # earlier version checked the closed flag only on the create branch and then
+    # returned the global, so a caller that found a live pool, lost the CPU, and
+    # resumed after shutdown returned None — and None means the event loop's own
+    # default executor, unbounded and shared with every other handler. That is
+    # the precise failure this function exists to prevent, reintroduced at the
+    # one moment it matters.
+    with _enrichment_pool_lock:
+        if _enrichment_pool_closed:
+            raise RuntimeError("enrichment pool is shut down")
+        if _enrichment_pool is None:
+            _enrichment_pool = concurrent.futures.ThreadPoolExecutor(
+                max_workers=_ENRICHMENT_WORKERS,
+                thread_name_prefix="slm-enrich",
+            )
+        pool = _enrichment_pool
+    if pool is None:  # pragma: no cover — belt and braces around the invariant
+        raise RuntimeError("enrichment pool is unavailable")
+    return pool
+
+
+def _open_enrichment_pool() -> None:
+    """Allow the pool to be created again, for a fresh run in this process.
+
+    The closed flag has to survive shutdown — that is its whole purpose — so
+    something has to clear it when a new run legitimately begins. Without this a
+    second startup in one process (a restart, or a test that builds the app more
+    than once) would find enrichment permanently refused and every write would
+    come back findable by wording only, with nothing in the logs to explain it.
+    """
+    global _enrichment_pool_closed, _enrichment_semaphore
+    with _enrichment_pool_lock:
+        _enrichment_pool_closed = False
+        # A fresh run starts with its full capacity. Shutdown cancels work that
+        # was queued and never started, and a task that never starts never runs
+        # the release in its finally — so permits taken by cancelled work are
+        # gone. Without this reset the next run in the same process would run at
+        # reduced capacity, or none at all, and the only symptom would be every
+        # write coming back findable by wording with nothing in the log.
+        _enrichment_semaphore = threading.Semaphore(_ENRICHMENT_WORKERS)
+
+
+def _enrich_and_release(engine, fact_ids: list[str], budget: float) -> int:
+    """Run inline enrichment, releasing the permit only when it is really done.
+
+    The permit has to be released here rather than by the caller. A caller that
+    stops waiting at its own deadline has not finished the work — the worker is
+    still holding a pool thread — so releasing on the caller's timeout would let
+    the next request submit into a pool that is still fully occupied, which is
+    the unbounded queueing this permit exists to prevent.
+    """
+    try:
+        return engine.enrich_new_facts_now(fact_ids, timeout_s=budget)
+    finally:
+        _enrichment_semaphore.release()
+
+
+def _shutdown_enrichment_pool_if_created() -> None:
+    """Shut down the enrichment pool if it was ever created.
+
+    Safe to call when the pool was never created (no-op) and safe to call
+    twice (second call is a no-op because the pool is set to None under the
+    lock before shutdown is called).
+
+    cancel_futures=True drops any work that is still queued but has not yet
+    started.  Workers already inside embed() will finish their current call
+    and then stop; they do not block the caller because wait=False.
+    """
+    global _enrichment_pool, _enrichment_pool_closed
+    with _enrichment_pool_lock:
+        # Marked closed under the same lock that guards creation, so a caller
+        # already past the unlocked check cannot build a replacement pool that
+        # this shutdown has already walked past.
+        _enrichment_pool_closed = True
+        pool = _enrichment_pool
+        _enrichment_pool = None
+    if pool is not None:
+        pool.shutdown(wait=False, cancel_futures=True)
 _SENSITIVE_READ_PREFIXES = (
     "/api/memories", "/api/facts", "/api/clusters", "/api/graph",
     "/api/v3/associations", "/api/v3/core-memory",
@@ -334,6 +587,62 @@ class RememberRequest(BaseModel):
     metadata: dict | None = None  # v3.4.26: pass-through from MCP pool_store
     idempotency_key: str | None = None
     session_id: str = ""
+    #: WHEN this memory is about, as distinct from when it was written.
+    #:
+    #: The internal admission record has carried this field all along and this
+    #: model never had it, so every memory arriving over HTTP — which is every
+    #: memory, from the CLI, the tool interface and the dashboard alike — was
+    #: stamped with its ingestion date. Measured on the author's store: 200 of
+    #: the 200 most recent facts have an observation_date, and 196 of them are
+    #: the day they were written. A store that cannot be told "this happened in
+    #: March" cannot answer a question about March.
+    #:
+    #: Empty means "today", the previous behaviour. Format is YYYY-MM-DD or a
+    #: full ISO 8601 timestamp.
+    session_date: str = ""
+
+    @field_validator("session_date")
+    @classmethod
+    def _session_date_is_a_date(cls, value: str) -> str:
+        """Reject a malformed date rather than ignore it.
+
+        Dropping it silently would leave the caller believing the date was
+        recorded while the memory quietly filed itself under today — which is
+        the exact failure this field exists to fix, reintroduced one layer up.
+        Rejecting is recoverable: the caller sees the error and resends.
+
+        ISO ONLY, DELIBERATELY, even though this system ships a parser that is
+        far more permissive. ``encoding/temporal_parser.parse_session_date``
+        accepts "May 8, 2026", "1:56 pm on 8 May, 2026", "14/03/2026", and also
+        "last tuesday" and "March 2026" — and those last two are why it is not
+        used here. Asked on 2026-08-21 it resolves "last tuesday" to
+        **2026-08-25**, four days into the future, and "March 2026" to the 21st,
+        a day it invents. Accepting either at this boundary would file a memory
+        under a confidently wrong date, silently, which is precisely the class
+        of defect this field was added to remove.
+
+        The caller here is a program — the command line, the tool interface, the
+        dashboard — not a person typing. ISO is the right contract for a
+        program, and a caller holding a human-typed date can run it through the
+        parser itself and send the result.
+        """
+        if not value:
+            return value
+        from datetime import datetime as _dt
+
+        text = value.strip()
+        try:
+            _dt.fromisoformat(text.replace("Z", "+00:00"))
+        except ValueError:
+            raise ValueError(
+                "session_date must be YYYY-MM-DD or a full ISO 8601 timestamp; "
+                f"got {value!r}. To accept looser human phrasing, parse it "
+                "first with TemporalParser.parse_session_date and send the ISO "
+                "result — but check what it returns, because it resolves "
+                "relative phrases against today and can answer with a future "
+                "date."
+            ) from None
+        return text
     # v3.6.15 multi-scope: visibility of the new memory. ``None`` scope means
     # "use the configured default_scope" (personal). shared_with is the list of
     # profile_ids for scope='shared'.
@@ -1500,6 +1809,11 @@ async def lifespan(application: FastAPI):
     """Initialize engine, workers, and optional services on startup."""
     global _last_activity
 
+    # A previous run in this process left the enrichment pool closed so that a
+    # write racing its shutdown could not resurrect it. This run is entitled to
+    # one.
+    _open_enrichment_pool()
+
     engine = None
     config = None
     deployment = None
@@ -1592,6 +1906,7 @@ async def lifespan(application: FastAPI):
         _path_config = None
 
     try:
+        from superlocalmemory.storage.backup import InsufficientDiskSpaceError
         from superlocalmemory.storage.migration_runner import apply_all
         if _path_config is None:
             # Catastrophic early-load failure: still one root via Mode-A default
@@ -1602,13 +1917,56 @@ async def lifespan(application: FastAPI):
             _path_config = _SLMFallback.for_mode(_ModeFallback.A)
         _learning_db = _learning_db_for_config(_path_config)
         _memory_db = _memory_db_for_config(_path_config)
+        import time as _time_mod
+        _t0 = _time_mod.monotonic()
         _result = apply_all(_learning_db, _memory_db)
+        _elapsed = _time_mod.monotonic() - _t0
         _applied = _result.get("applied", [])
         _failed = _result.get("failed", [])
+        _backup_dir = _result.get("details", {}).get("_backup")
+        _backup_path = Path(_backup_dir) if _backup_dir else None
         if _applied:
             logger.info("migrations applied: %s", _applied)
+            _notify_migration_applied(_applied, _elapsed, _backup_path)
+            _notify_windows_user(
+                f"SuperLocalMemory: {len(_applied)} database migration(s) applied."
+            )
         if _failed:
             logger.warning("migrations failed (non-fatal): %s", _failed)
+            try:
+                _err_log = _write_migration_error_log(
+                    _failed, _backup_path,
+                    slm_home=_memory_db.parent if _memory_db else None,
+                    applied=_applied,
+                )
+                import sys as _sys
+                # "Data is safe" is only true when NOTHING was applied. Migrations
+                # are non-fatal and applied in order, so a later failure can leave
+                # earlier ones committed — a partially changed store. Saying the
+                # data is untouched then tells the user to ignore the one copy
+                # that still holds the original.
+                if _applied:
+                    _headline = (
+                        f"[SLM] Migration incomplete. YOUR DATABASE WAS PARTIALLY "
+                        f"CHANGED — {len(_applied)} step(s) applied, "
+                        f"{len(_failed)} failed. The pre-change copy is at "
+                        f"{_backup_path} — keep it until this is resolved."
+                    )
+                else:
+                    _headline = (
+                        f"[SLM] Migration failed before any change was made. Your "
+                        f"data is as it was; a copy is also at {_backup_path}."
+                    )
+                print(
+                    f"{_headline} See {_err_log}. Run: slm doctor",
+                    file=_sys.stderr,
+                    flush=True,
+                )
+                _notify_windows_user(
+                    f"SuperLocalMemory migration failed. Run slm doctor. Log: {_err_log}"
+                )
+            except Exception:
+                pass  # notification failures are non-fatal
         application.state.migration_result = _result
         # S9-SKEP-15: only commit the new `.last_version` AFTER migrations
         # complete with zero failures. A partial upgrade (schema didn't
@@ -1626,6 +1984,35 @@ async def lifespan(application: FastAPI):
                 _version_marker.write_text(_slm_version, encoding="utf-8")
             except OSError:
                 pass  # non-fatal
+    except InsufficientDiskSpaceError as _disk_exc:
+        # This is not a crash and it must not be reported as "non-fatal". The
+        # migration deliberately refused to start because there was not enough
+        # room to keep a recoverable copy first. The store is intact and
+        # unmigrated; the generic handler below would have logged a warning and
+        # left the daemon serving as though nothing had happened.
+        logger.error(
+            "MIGRATION NOT RUN — not enough free disk to keep a recoverable "
+            "copy first. Your data has NOT been modified. Need %s bytes, have "
+            "%s free. Free some space and restart; run `slm doctor` for details.",
+            f"{_disk_exc.needed_bytes:,}", f"{_disk_exc.free_bytes:,}",
+        )
+        try:
+            _log_path = _write_migration_error_log(
+                ["_insufficient_disk_space"], None,
+                slm_home=locals().get("_memory_db").parent if locals().get("_memory_db") else None,
+                applied=[],
+            )
+            logger.error("Details written to %s", _log_path)
+        except OSError:
+            pass
+        application.state.migration_result = {
+            "applied": [], "skipped": [], "failed": ["_insufficient_disk_space"],
+            "details": {
+                "_needed_bytes": _disk_exc.needed_bytes,
+                "_free_bytes": _disk_exc.free_bytes,
+                "_store_modified": False,
+            },
+        }
     except Exception as _exc:
         logger.warning("migration runner crashed (non-fatal): %s", _exc)
         application.state.migration_result = {
@@ -2068,6 +2455,10 @@ async def lifespan(application: FastAPI):
                 "state": "checking_components", "embeddings_backfilled": 0,
                 "expansion_backfilled": 0, "null_remaining": None,
                 "components": None,
+                # Declared here so /status carries the same keys whatever
+                # happens; a field that only appears on failure is a field
+                # nobody's dashboard renders.
+                "incomplete_reason": None,
                 "started_at": _t.time(), "finished_at": None,
             }
             # Step 0 (v3.8.2 "whole self-healer"): repair components that
@@ -2176,9 +2567,42 @@ async def lifespan(application: FastAPI):
                     _backfill_vector_store()
                 except Exception as exc:
                     logger.warning("Self-heal vector index failed (non-fatal): %s", exc)
-                _SELF_HEAL_STATUS["state"] = "complete"
+
+                # "complete" has to mean complete.
+                #
+                # This line used to set "complete" unconditionally, so a
+                # backfill that gave up after five no-progress attempts, or ran
+                # out its 500-iteration budget, reported success with facts
+                # still unembedded — and an unembedded fact cannot be found by
+                # meaning at all. That is how a machine sat at 56.3% of its
+                # memory reachable while its own status endpoint said the heal
+                # had finished. Nobody was going to look past a green light.
+                #
+                # Now the state is derived from the remaining count, and the
+                # gap is named in plain language for the dashboard, so an
+                # incomplete heal is visible and gets retried on next start
+                # instead of being declared done forever.
+                _remaining = _SELF_HEAL_STATUS.get("null_remaining")
                 _SELF_HEAL_STATUS["finished_at"] = _t.time()
-                logger.info("Self-heal complete: %s", _SELF_HEAL_STATUS)
+                if _remaining is None:
+                    _SELF_HEAL_STATUS["state"] = "complete"
+                elif int(_remaining) > 0:
+                    _SELF_HEAL_STATUS["state"] = "incomplete"
+                    _SELF_HEAL_STATUS["incomplete_reason"] = (
+                        f"{int(_remaining)} memories still have no meaning "
+                        f"vector, so they cannot be found by asking a question. "
+                        f"This retries automatically next time the service "
+                        f"starts. It usually means the embedding model was "
+                        f"unavailable."
+                    )
+                    logger.warning(
+                        "Self-heal INCOMPLETE: %d facts still unembedded and "
+                        "therefore unreachable by meaning; will retry on next "
+                        "start. %s", int(_remaining), _SELF_HEAL_STATUS,
+                    )
+                else:
+                    _SELF_HEAL_STATUS["state"] = "complete"
+                    logger.info("Self-heal complete: %s", _SELF_HEAL_STATUS)
             except Exception as exc:
                 _SELF_HEAL_STATUS["state"] = "error"
                 logger.warning("Self-heal failed (non-fatal): %s", exc)
@@ -2822,6 +3246,19 @@ async def lifespan(application: FastAPI):
     except Exception as exc:  # pragma: no cover — defensive
         logger.warning("perf_log flush failed: %s", exc)
 
+    # Shut down the enrichment pool before engine.close() so that any worker
+    # still inside embed() receives cancellation before the embed pool is torn
+    # down.  shutdown(wait=False, cancel_futures=True) is non-blocking: queued
+    # futures are dropped and running futures complete their current call on
+    # their own.  This prevents Python's atexit handler from calling
+    # shutdown(wait=True) on a live embed worker, which would push the daemon
+    # past the graceful-shutdown budget and cause the service manager to
+    # SIGKILL the process.
+    try:
+        _shutdown_enrichment_pool_if_created()
+    except Exception as exc:  # pragma: no cover — defensive
+        logger.warning("enrichment pool shutdown failed (non-fatal): %s", exc)
+
     materializer_stopped = _stop_pending_materializer()
     canonical_writer_stopped = _release_canonical_remember_runtime(application)
     _profile_runtime = None
@@ -3631,8 +4068,16 @@ def _register_dashboard_routes(application: FastAPI) -> None:
         # v3.4.23: substitute version placeholder so the dashboard can detect
         # upgrades and auto-reload. Read fresh each request (daemon uptime is
         # days, but we want zero caching surprises during development).
-        html = index_path.read_text()
-        return html.replace("__SLM_VERSION__", _SLM_VERSION)
+        #
+        # 4.0.10: asset ?v= strings are now derived from file content instead of
+        # being hand-written literals that tracked nothing. See
+        # server/asset_versions.py — including what that does and does not fix.
+        from superlocalmemory.server.asset_versions import render_index
+
+        return render_index(
+            index_path, UI_DIR,
+            substitutions={"__SLM_VERSION__": _SLM_VERSION},
+        )
 
     @application.get("/favicon.ico", include_in_schema=False)
     async def favicon():
@@ -3802,7 +4247,7 @@ def _register_daemon_routes(application: FastAPI) -> None:
             "runtime_state": runtime_state,
             "active_profile": profile_snapshot.profile_id,
             "profile_generation": profile_snapshot.generation,
-            # Wave-3: operational failure counts (visible to all team members)
+            # operational failure counts (visible to all team members)
             **_ops_failure_counts(engine, application),
             # issue #107: does this daemon's *imported* code still match the
             # installed distribution? ``version`` above reports what this
@@ -4169,12 +4614,17 @@ def _register_daemon_routes(application: FastAPI) -> None:
                 shared_with=tuple(shared_with or ()),
                 trusted_actor_id=trusted_actor_id,
                 session_id=req.session_id,
+                session_date=req.session_date,
             )
             actor = Actor(
                 principal_id=trusted_actor_id,
                 allowed_profiles=frozenset({engine._profile_id}),
                 allowed_scopes=frozenset({scope}),
             )
+            # The whole request has a 1.5 s ceiling, and the two phases below
+            # are sequential, so the ceiling has to be shared between them
+            # rather than granted twice. Measured from here.
+            _store_started = time.monotonic()
             receipt = await asyncio.to_thread(
                 runtime.remember,
                 admission,
@@ -4183,10 +4633,105 @@ def _register_daemon_routes(application: FastAPI) -> None:
             )
             payload = dict(receipt.payload)
             fact_ids = list(payload.get("fact_ids") or [])
+
+            # The durable receipt is already committed above; nothing below can
+            # fail this write. What remains is the window in which the memory can
+            # only be found by quoting its own wording — a fact with no vector is
+            # invisible to the semantic channel, so the memory describing what is
+            # happening right now is the hardest one to find.
+            #
+            # Every entry point — command line, tool interface, dashboard —
+            # arrives here, so closing the window here closes it for all of them
+            # rather than for whichever door happened to be used.
+            #
+            # Strictly bounded, because this daemon serves many sessions at once:
+            # the work runs off the event loop, on a two-worker pool, and yields
+            # to any recall in flight. Past the deadline the caller gets exactly
+            # the previous behaviour and the background materializer finishes the
+            # job.
+            # A caller that did not ask to wait still gets a real attempt, not a
+            # token one. Almost no client passes wait=true, so a small budget
+            # here meant almost every memory in practice was returned findable by
+            # wording only — the default path deciding the product's behaviour.
+            #
+            # But it gets what is LEFT of the ceiling, not a second full budget.
+            # The durable write above can legitimately consume most of the 1.5 s
+            # under contention, and granting the full enrichment window on top of
+            # that produced receipts well past 3 s — over a ceiling the changelog
+            # states. A caller that asked to wait may exceed the shared ceiling,
+            # because that is what asking to wait means; nobody else may.
+            _elapsed = time.monotonic() - _store_started
+            _remaining = _REMEMBER_TOTAL_CEILING_SECONDS - _elapsed
+            if wait:
+                enrich_budget = _REMEMBER_ENRICHMENT_WAIT_SECONDS
+            else:
+                enrich_budget = min(
+                    1.0, _REMEMBER_ENRICHMENT_WAIT_SECONDS, max(0.0, _remaining),
+                )
+            if enrich_budget <= 0.0:
+                logger.warning(
+                    "the durable write used the whole %.1fs budget (%.2fs) — this "
+                    "memory is findable by its wording and the background pass "
+                    "will attach its vector",
+                    _REMEMBER_TOTAL_CEILING_SECONDS, _elapsed,
+                )
+            enriched = 0
+            # Taken before submitting, released by the worker. If none is free
+            # the pool is already saturated, and queueing behind it would mean
+            # writing to the database after this response has been sent — so the
+            # write is simply reported as findable by wording and the background
+            # pass picks it up, which is the intended degradation.
+            _permit = _enrichment_semaphore.acquire(blocking=False)
+            if not _permit:
+                logger.warning(
+                    "inline enrichment at capacity for %d fact(s) — deferred to "
+                    "the background pass", len(fact_ids),
+                )
+            try:
+                if not _permit:
+                    raise _EnrichmentAtCapacity
+                loop = asyncio.get_running_loop()
+                try:
+                    _pending = loop.run_in_executor(
+                        _enrichment_executor(),
+                        functools.partial(
+                            _enrich_and_release,
+                            engine, fact_ids, enrich_budget,
+                        ),
+                    )
+                except BaseException:
+                    # Never handed to a worker, so nothing will release it.
+                    _enrichment_semaphore.release()
+                    raise
+                enriched = await asyncio.wait_for(
+                    _pending, timeout=enrich_budget + 0.25,
+                )
+            except _EnrichmentAtCapacity:
+                pass
+            except (TimeoutError, asyncio.TimeoutError):
+                # Worth seeing. Sustained timeouts mean writes are coming back
+                # findable by wording only, which is a real degradation and was
+                # previously visible at debug level alone.
+                logger.warning(
+                    "inline enrichment exceeded its budget for %d fact(s) — "
+                    "deferred to the background pass", len(fact_ids),
+                )
+            except Exception as exc:
+                logger.warning(
+                    "inline enrichment unavailable (%s: %s) — deferred to the "
+                    "background pass", type(exc).__name__, exc,
+                )
+
+            searchable = "meaning" if enriched == len(fact_ids) and fact_ids else "wording"
             return {
                 "ok": True,
                 "fact_ids": fact_ids,
                 "count": len(fact_ids),
+                # Storing a memory and being able to find it again are different
+                # things, and reporting only the first is how a caller ends up
+                # believing a memory is retrievable when it is not yet.
+                "searchable_by": searchable,
+                "enriched_now": enriched,
                 "operation_id": payload["operation_id"],
                 # One-release compatibility alias. The durable operation ID is
                 # opaque and replaces the integer pending.db row identifier.
@@ -4194,8 +4739,17 @@ def _register_daemon_routes(application: FastAPI) -> None:
                 "status": "queryable",
                 "materialization_state": payload["materialization_state"],
                 "commit_sequence": payload.get("commit_sequence"),
-                "note": "queryable now; canonical enrichment continues in the background",
-                "wait_ignored": bool(wait),
+                "note": (
+                    "stored and searchable by meaning"
+                    if searchable == "meaning"
+                    else "stored and searchable by wording; "
+                         "searchable by meaning shortly"
+                ),
+                # Retained for callers that already read it. It used to be
+                # unconditionally true, because `wait` bought nothing. It now
+                # buys a larger best-effort enrichment budget — still never a
+                # guarantee, and still never a block on durability.
+                "wait_ignored": False if wait else True,
             }
         except Exception as exc:
             from superlocalmemory.core.remember_admission import AdmissionRejected
@@ -4407,7 +4961,7 @@ def _register_daemon_routes(application: FastAPI) -> None:
             # index backfill after an upgrade). Dashboard renders a plain
             # "Optimizing memory…" line from this. Defaults to idle before start.
             "self_heal": globals().get("_SELF_HEAL_STATUS", {"state": "idle"}),
-            # Wave-3: operational failure counts (dead-letter, degraded, stalled)
+            # operational failure counts (dead-letter, degraded, stalled)
             **_ops_failure_counts(engine, application),
         }
 
@@ -4461,7 +5015,7 @@ def _register_daemon_routes(application: FastAPI) -> None:
         return {"status": "started"}
 
     # ------------------------------------------------------------------
-    # Wave-3: Operational Recovery & Admin Remediation  (V4 resilience slice)
+    # Operational Recovery & Admin Remediation  (V4 resilience slice)
     # ------------------------------------------------------------------
 
     @application.get("/operations/failed")
@@ -5008,7 +5562,7 @@ def _terminalize_orphan_operation(engine, operation_id: str) -> None:
 
 
 def _ops_failure_counts(engine, application) -> dict:
-    """Return Wave-3 operational failure counts for /status and /health.
+    """Return operational failure counts for /status and /health.
 
     Always returns a dict (never raises). Counts default to 0 on any error.
     Includes: dead_letter_count, degraded_operations, exhausted_obligations,