superlocalmemory 3.8.3 → 3.8.6

package/src/superlocalmemory/core/remote_mode.py

@@ -182,7 +182,9 @@ def is_rate_limit_exempt(client_host: str) -> bool:
     same rapid reads, so it is exempt too — otherwise normal dashboard polling
     trips the limiter (issue #40 Issue 3).
     """
-    if client_host in ("127.0.0.1", "::1", "localhost"):
+    from superlocalmemory.server.loopback import is_loopback as _is_loopback_host
+
+    if _is_loopback_host(client_host):
         return True
     return is_lan_client_allowed(client_host)
 

package/src/superlocalmemory/core/scale_engine.py

@@ -349,7 +349,24 @@ class ScaleEngineManager:
             self._release_lifecycle_lock(lock_path)
 
     def _promote(self, stage_id: str) -> dict[str, Any]:
-        """Promote while the caller owns the lifecycle lock."""
+        """Promote while the caller owns the lifecycle lock.
+
+        Concurrency fix (v3.8.4): the original code held a SQLite
+        BEGIN IMMEDIATE lock across multiple fsync/rename filesystem operations
+        (mkdir_durable, replace_durable, write_promotion_journal) which could
+        starve other memory.db writers for 30+ seconds.
+
+        Fix: the fingerprint check runs inside a short memory_read() block
+        (consistent WAL snapshot, no write lock).  All filesystem operations
+        happen AFTER that block with no SQLite lock held.  The lifecycle lock
+        (file-based, acquired by the caller) already serialises concurrent
+        promote/rollback calls.
+
+        Lock-ordering invariant preserved: get_write_lock is OUTERMOST; no
+        SQLite write lock is held here at all (only a read snapshot).
+        """
+        from superlocalmemory.storage.memory_write import memory_read
+
         stage_dir, manifest = self._load_stage(stage_id)
         self._validate_manifest(manifest, state="verified")
         staged = (stage_dir / "cozo", stage_dir / "lance")
@@ -357,17 +374,30 @@ class ScaleEngineManager:
             raise ScaleEngineError("verified stage is incomplete; prepare a new stage")
         backup_dir = self.backup_root / f"{stage_id}-{uuid.uuid4().hex[:6]}"
         active = self.active_paths
-        gate = sqlite3.connect(self.db_path, timeout=30)
+
+        # ── Phase 1: fingerprint check (short read snapshot, no write lock) ──
+        # memory_read() gives a consistent WAL snapshot and closes the
+        # connection immediately on exit — no lock held after this block.
+        try:
+            with memory_read(self.db_path) as gate:
+                canonical = self._canonical_counts(gate)
+                if manifest["source_fingerprint"] != self._projection_fingerprint(
+                    gate, canonical
+                ):
+                    raise ScaleEngineError(
+                        "canonical SQLite changed after verification; prepare a new stage"
+                    )
+        except ScaleEngineError:
+            raise
+        except Exception as exc:
+            raise ScaleEngineError(
+                f"fingerprint check failed: {exc}"
+            ) from exc
+
+        # ── Phase 2: filesystem operations — NO SQLite lock held ─────────────
+        # The lifecycle lock (file-based, held by the caller) serialises
+        # concurrent promotions; no SQLite fence is required for the swaps.
         try:
-            # The stage was built from a point-in-time SQLite snapshot. Hold a
-            # short writer fence for the final fingerprint check and directory
-            # swap so no successful promotion can trail a canonical write.
-            gate.execute("BEGIN IMMEDIATE")
-            canonical = self._canonical_counts(gate)
-            if manifest["source_fingerprint"] != self._projection_fingerprint(gate, canonical):
-                raise ScaleEngineError(
-                    "canonical SQLite changed after verification; prepare a new stage"
-                )
             self._mkdir_durable(self.backup_root)
             journal = {
                 "schema_version": self.SCHEMA_VERSION,
@@ -409,13 +439,8 @@ class ScaleEngineManager:
             journal["state"] = "committed"
             self._write_promotion_journal(journal)
             self.promotion_journal_path.unlink(missing_ok=True)
-            gate.rollback()
             return manifest
         except Exception as exc:
-            try:
-                gate.rollback()
-            except sqlite3.Error:
-                pass
             try:
                 recovery = self._recover_interrupted_promotion()
             except Exception as recovery_error:
@@ -426,8 +451,6 @@ class ScaleEngineManager:
                 _, recovered_manifest = self._load_stage(stage_id)
                 return recovered_manifest
             raise ScaleEngineError(f"promotion rolled back: {exc}") from exc
-        finally:
-            gate.close()
 
     def rollback(self, backup_id: str) -> dict[str, Any]:
         """Restore an explicitly named pre-promotion backup."""

package/src/superlocalmemory/core/store_pipeline.py

@@ -166,10 +166,24 @@ def enrich_fact(
     from superlocalmemory.encoding.emotional import emotional_importance_boost, tag_emotion
     from superlocalmemory.encoding.signal_inference import infer_signal
 
-    embedding = embedder.embed(fact.content) if embedder else None
-    fisher_mean, fisher_variance = (None, None)
-    if embedder and embedding:
-        fisher_mean, fisher_variance = embedder.compute_fisher_params(embedding)
+    # v3.8.4 D: if the fact already carries a sync-embedded vector (warm-guard
+    # path in store_fast), reuse it — avoids a redundant embed call in the
+    # materializer and keeps the vector consistent with the one indexed in the
+    # vector store at write time.
+    if fact.embedding is not None:
+        embedding = fact.embedding
+        fisher_mean = fact.fisher_mean
+        fisher_variance = fact.fisher_variance
+        # fisher_params are computed in the warm-guard path too, but guard
+        # against the edge case where they weren't (e.g. compute_fisher_params
+        # raised after embed succeeded).
+        if (fisher_mean is None or fisher_variance is None) and embedder and embedding:
+            fisher_mean, fisher_variance = embedder.compute_fisher_params(embedding)
+    else:
+        embedding = embedder.embed(fact.content) if embedder else None
+        fisher_mean, fisher_variance = (None, None)
+        if embedder and embedding:
+            fisher_mean, fisher_variance = embedder.compute_fisher_params(embedding)
 
     canonical = {}
     if entity_resolver and fact.entities:

package/src/superlocalmemory/encoding/entity_resolver.py

@@ -563,18 +563,25 @@ class EntityResolver:
         self._db.store_alias(alias, profile_id)
 
     def _touch_last_seen(self, entity_id: str, profile_id: str = "default") -> None:
-        """Update last_seen timestamp on a canonical entity scoped to profile.
-
-        L-01 fix: the original query had no profile_id guard. Since entity_ids are
-        UUIDs today the blast radius is theoretical, but the guard is required for
-        defense-in-depth against future import/sharing features that could introduce
-        UUID collisions across profiles.
+        """Record a last_seen touch (DEFERRED, non-blocking).
+
+        last_seen is dashboard-only bookkeeping (entities/graph "last seen"
+        columns); it never feeds recall ranking.  Writing it INLINE made recall
+        a WRITER that waited on the global write lock — the root of the
+        "recall is 8 s" regression.  We now record it in memory and flush from a
+        single background thread in coalesced batches, so recall stays
+        READ-ONLY on its hot path.  The dashboard stays correct within the flush
+        interval (~2 s).  The profile_id guard (L-01) is preserved in the
+        deferred UPDATE (see storage/deferred_writes.py).
         """
-        self._db.execute(
-            "UPDATE canonical_entities SET last_seen = ? "
-            "WHERE entity_id = ? AND profile_id = ?",
-            (_now(), entity_id, profile_id),
-        )
+        try:
+            from superlocalmemory.storage.deferred_writes import (
+                get_deferred_last_seen,
+            )
+            get_deferred_last_seen(self._db).touch(entity_id, profile_id, _now())
+        except Exception:
+            # Bookkeeping must never break entity resolution.
+            pass
 
     # -- Internal: LLM disambiguation (Mode B/C) ---------------------------
 

package/src/superlocalmemory/graph/cozo_backend.py

@@ -75,12 +75,12 @@ class _CozoResult:
 
 
 class _CozoClientAdapter:
-    """Bridge PyCozo 0.3 embedded bindings and later client conveniences.
+    """Bridge legacy PyCozo responses and the pinned 0.7.6 client surface.
 
-    PyCozo 0.3 is the last client compatible with the published macOS native
-    binding. It returns dictionaries and exposes ``import_relations`` rather
-    than ``put``; later clients return dataframe-like values and add ``put``.
-    SLM only needs relation upserts and row results, so normalize those here.
+    PyCozo 0.7.6 publishes embedded wheels for macOS, Linux x86_64/aarch64,
+    and Windows. Older installations can still return dictionaries and expose
+    ``import_relations`` rather than ``put``. SLM only needs relation upserts
+    and row results, so normalize both forms here.
     """
 
     def __init__(self, client: Any) -> None:

package/src/superlocalmemory/hooks/_outcome_common.py

@@ -40,8 +40,15 @@ from typing import IO, Optional
 # Budget constants
 # ---------------------------------------------------------------------------
 
-#: Hot-path SQLite busy timeout (ms). Fail fast rather than block a host tool.
-BUSY_TIMEOUT_MS: int = 50
+#: Hot-path SQLite busy timeout (ms).
+#
+# Raised to 10 000 ms to match the daemon's SLM_DB_BUSY_TIMEOUT_MS default.
+# Hooks run as a SEPARATE OS process — the daemon's threading.RLock write-lock
+# cannot help cross-process — so PRAGMA busy_timeout is the ONLY lever that
+# prevents SQLITE_BUSY when the daemon or CLI holds the WAL write lock.
+# 10 s is long enough to outlast a typical daemon write cycle while staying
+# safely below Claude Code's hook-kill timeout.
+BUSY_TIMEOUT_MS: int = 10_000
 
 #: Cap on tool_response bytes scanned — bounds substring work to O(100 KB).
 SCAN_BYTES_CAP: int = 100_000

package/src/superlocalmemory/hooks/adapter_base.py

@@ -32,6 +32,8 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Protocol, runtime_checkable
 
+from superlocalmemory.storage.write_lock import get_write_lock
+
 
 # ---------------------------------------------------------------------------
 # Constants
@@ -86,25 +88,31 @@ def _ensure_memory_log(db_path: Path) -> None:
     """Lazily create ``cross_platform_sync_log`` if a test-mode memory.db is
     fresh. Production code goes through the migration runner, but tests can
     hand us an empty DB; this keeps adapters usable without pre-running
-    migrations."""
-    conn = sqlite3.connect(str(db_path))
-    try:
-        conn.executescript(
-            "CREATE TABLE IF NOT EXISTS cross_platform_sync_log ("
-            " adapter_name TEXT NOT NULL,"
-            " profile_id TEXT NOT NULL,"
-            " target_path_sha256 TEXT NOT NULL,"
-            " target_basename TEXT NOT NULL,"
-            " last_sync_at TEXT NOT NULL,"
-            " bytes_written INTEGER NOT NULL,"
-            " content_sha256 TEXT NOT NULL,"
-            " success INTEGER NOT NULL,"
-            " error_msg TEXT,"
-            " PRIMARY KEY (adapter_name, target_path_sha256));"
-        )
-        conn.commit()
-    finally:
-        conn.close()
+    migrations.
+
+    Acquires the process-level write lock for *db_path* before opening
+    a sqlite3 connection so that this DDL write is serialised with all
+    other in-process writers (DatabaseManager, VectorStore, etc.).
+    """
+    with get_write_lock(db_path):
+        conn = sqlite3.connect(str(db_path))
+        try:
+            conn.executescript(
+                "CREATE TABLE IF NOT EXISTS cross_platform_sync_log ("
+                " adapter_name TEXT NOT NULL,"
+                " profile_id TEXT NOT NULL,"
+                " target_path_sha256 TEXT NOT NULL,"
+                " target_basename TEXT NOT NULL,"
+                " last_sync_at TEXT NOT NULL,"
+                " bytes_written INTEGER NOT NULL,"
+                " content_sha256 TEXT NOT NULL,"
+                " success INTEGER NOT NULL,"
+                " error_msg TEXT,"
+                " PRIMARY KEY (adapter_name, target_path_sha256));"
+            )
+            conn.commit()
+        finally:
+            conn.close()
 
 
 def sync_log_last_content_sha256(
@@ -156,31 +164,37 @@ def sync_log_record(
         )
     if os.sep in target_path_sha256 or "/" in target_path_sha256:
         raise ValueError("target_path_sha256 must be a hash, not a raw path")
-    _ensure_memory_log(db_path)
-    conn = sqlite3.connect(str(db_path))
-    try:
-        conn.execute(
-            "INSERT INTO cross_platform_sync_log ("
-            "adapter_name, profile_id, target_path_sha256, target_basename, "
-            "last_sync_at, bytes_written, content_sha256, success, error_msg"
-            ") VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?) "
-            "ON CONFLICT(adapter_name, target_path_sha256) DO UPDATE SET "
-            " profile_id = excluded.profile_id,"
-            " target_basename = excluded.target_basename,"
-            " last_sync_at = excluded.last_sync_at,"
-            " bytes_written = excluded.bytes_written,"
-            " content_sha256 = excluded.content_sha256,"
-            " success = excluded.success,"
-            " error_msg = excluded.error_msg",
-            (
-                adapter_name, profile_id, target_path_sha256, target_basename,
-                _now_iso(), bytes_written, content_sha256,
-                1 if success else 0, error_msg,
-            ),
-        )
-        conn.commit()
-    finally:
-        conn.close()
+    # Acquire the process-level write lock BEFORE opening the sqlite3 connection.
+    # This ensures the INSERT/UPDATE below is serialised with all other in-process
+    # writers (DatabaseManager, VectorStore, consolidation) via the single shared
+    # RLock for memory.db, eliminating SQLITE_BUSY races at the WAL layer.
+    # _ensure_memory_log also acquires the same RLock (re-entrant — safe).
+    with get_write_lock(db_path):
+        _ensure_memory_log(db_path)
+        conn = sqlite3.connect(str(db_path))
+        try:
+            conn.execute(
+                "INSERT INTO cross_platform_sync_log ("
+                "adapter_name, profile_id, target_path_sha256, target_basename, "
+                "last_sync_at, bytes_written, content_sha256, success, error_msg"
+                ") VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?) "
+                "ON CONFLICT(adapter_name, target_path_sha256) DO UPDATE SET "
+                " profile_id = excluded.profile_id,"
+                " target_basename = excluded.target_basename,"
+                " last_sync_at = excluded.last_sync_at,"
+                " bytes_written = excluded.bytes_written,"
+                " content_sha256 = excluded.content_sha256,"
+                " success = excluded.success,"
+                " error_msg = excluded.error_msg",
+                (
+                    adapter_name, profile_id, target_path_sha256, target_basename,
+                    _now_iso(), bytes_written, content_sha256,
+                    1 if success else 0, error_msg,
+                ),
+            )
+            conn.commit()
+        finally:
+            conn.close()
 
 
 # ---------------------------------------------------------------------------

package/src/superlocalmemory/hooks/ide_connector.py

@@ -188,8 +188,18 @@ class IDEConnector:  # pragma: no cover — legacy shim, covered by test_ide_con
         path.write_text(content + "\n" + section)
         return True
 
-    def _merge_json(self, path: Path) -> bool:
-        """Merge SLM config into a JSON config file."""
+    def _merge_json(
+        self,
+        path: Path,
+        transport: str = "stdio",
+        daemon_port: int = 8765,
+    ) -> bool:
+        """Merge SLM config into a JSON config file.
+
+        Args:
+            transport: "stdio" (default), "http", or "http-mcp-remote".
+            daemon_port: Daemon port for http transports (default 8765).
+        """
         data: dict[str, Any] = {}
         if path.exists():
             try:
@@ -201,12 +211,20 @@ class IDEConnector:  # pragma: no cover — legacy shim, covered by test_ide_con
         if "mcpServers" not in data:
             data["mcpServers"] = {}
 
-        data["mcpServers"]["superlocalmemory"] = {
-            "type": "stdio",
-            "command": "slm",
-            "args": ["mcp"],
-            "enabled": True,
-        }
+        base_url = f"http://127.0.0.1:{daemon_port}/mcp/"
+        if transport == "http":
+            block: dict[str, Any] = {"type": "http", "url": base_url}
+        elif transport == "http-mcp-remote":
+            block = {"type": "stdio", "command": "mcp-remote", "args": [base_url]}
+        else:
+            block = {
+                "type": "stdio",
+                "command": "slm",
+                "args": ["mcp"],
+                "enabled": True,
+            }
+
+        data["mcpServers"]["superlocalmemory"] = block
 
         path.parent.mkdir(parents=True, exist_ok=True)
         path.write_text(json.dumps(data, indent=2))

package/src/superlocalmemory/hooks/portable_kit.py

@@ -32,6 +32,12 @@ logger = logging.getLogger(__name__)
 SLM_MARKER_START = "<!-- SLM-START -->"
 SLM_MARKER_END = "<!-- SLM-END -->"
 
+# Valid transport values for connect_ide() and slm connect --transport.
+# "stdio"           — default, zero regression; uses desc.server_block as-is.
+# "http"            — native MCP Streamable-HTTP; requires daemon at :daemon_port.
+# "http-mcp-remote" — mcp-remote stdio bridge for stdio-only clients.
+VALID_TRANSPORTS: frozenset[str] = frozenset({"stdio", "http", "http-mcp-remote"})
+
 CLAUDE_CODE_PLUGIN_POINTER = (
     "slm connect claude-code: Claude Code is configured via the SLM plugin (WP-06).\n"
     "Run: slm plugin install  OR  see plugin-src/ for manual installation.\n"
@@ -241,16 +247,26 @@ def connect_ide(
     profile: str | None = None,
     agents_md_source: Callable[[], str] | None = None,
     dry_run: bool = False,
+    transport: str = "stdio",
+    daemon_port: int = 8765,
 ) -> dict[str, Any]:
     """Wire SLM into the target IDE config via merge-not-clobber.
 
+    Args:
+        transport: MCP transport to write into the config.
+            "stdio" (default, zero regression) — uses the IDE's canonical server_block.
+            "http" — native MCP Streamable-HTTP block; requires SLM daemon at daemon_port.
+            "http-mcp-remote" — stdio bridge via mcp-remote for stdio-only clients.
+        daemon_port: Daemon listen port for http / http-mcp-remote (default 8765).
+
     Returns a result dict:
-        {ide, mcp_config: wrote|merged|unchanged|would_write|skipped|error,
+        {ide, transport, mcp_config: wrote|merged|unchanged|would_write|skipped|error,
          mcp_path, agents_md: wrote|skipped(...)|unchanged|error,
          servers_preserved: int, error: str|None}
     """
     result: dict[str, Any] = {
         "ide": ide_id,
+        "transport": transport,
         "mcp_config": "error",
         "mcp_path": "",
         "agents_md": "skipped(not-run)",
@@ -258,6 +274,14 @@ def connect_ide(
         "error": None,
     }
 
+    # Step 0 — validate transport
+    if transport not in VALID_TRANSPORTS:
+        result["error"] = (
+            f"Invalid transport '{transport}'. "
+            f"Valid choices: {', '.join(sorted(VALID_TRANSPORTS))}"
+        )
+        return result
+
     # Step 1 — resolve
     desc = resolve_descriptor(ide_id)
     if desc is None:
@@ -303,9 +327,25 @@ def connect_ide(
         # File is untouched (we never wrote; abort)
         return result
 
-    # Step 4 — extract server container
-    # For continue (yaml list), special-case
+    # Step 4 — daemon health-check for HTTP transports (advisory, never blocks write)
+    if transport in ("http", "http-mcp-remote") and desc.fmt != "":
+        if not _check_daemon_health(daemon_port):
+            print(
+                f"[SLM] Warning: daemon not reachable at http://127.0.0.1:{daemon_port}/api/v3/health. "
+                f"Run `slm serve start` to start it, or `slm serve install` to register as an OS service.",
+                file=sys.stderr,
+            )
+
+    # Step 5 — extract server container and build block
+    # For YAML-format IDEs (continue.dev), transport is ignored — their block
+    # structure is list-based and incompatible with the JSON http/mcp-remote block.
     if desc.fmt == "yaml":
+        if transport != "stdio":
+            logger.warning(
+                "transport=%r is not supported for YAML-format IDE %r; using stdio fallback.",
+                transport,
+                ide_id,
+            )
         mcp_status, servers_preserved = _merge_yaml_list(
             data, desc, profile
         )
@@ -316,10 +356,8 @@ def connect_ide(
         pre_count = len(servers)
         pre_slm = copy.deepcopy(servers.get("superlocalmemory"))
 
-        # Step 5 — merge
-        block = copy.deepcopy(desc.server_block)
-        if profile:
-            block.setdefault("env", {})["SLM_MCP_PROFILE"] = profile
+        # Build the server block for the requested transport
+        block = _build_server_block(desc, transport, daemon_port, profile)
 
         servers["superlocalmemory"] = block
 
@@ -384,6 +422,8 @@ def connect_many(
     here: bool = False,
     profile: str | None = None,
     agents_md_source: Callable[[], str] | None = None,
+    transport: str = "stdio",
+    daemon_port: int = 8765,
 ) -> list[dict[str, Any]]:
     """Wire SLM into multiple IDE configs via non-destructive merge.
 
@@ -402,14 +442,17 @@ def connect_many(
         home: Override ``$HOME`` (test hook).
         project: Project root for ``here=True`` installs.
         here: When True, write to project-relative path instead of global.
-        profile: Inject ``SLM_MCP_PROFILE`` env-var into every server block.
+        profile: Inject ``SLM_MCP_PROFILE`` env-var (stdio) or URL param (http).
         agents_md_source: Callable returning AGENTS.md content to append.
+        transport: MCP transport to use for all IDEs ("stdio", "http",
+            "http-mcp-remote"). Default "stdio" preserves existing behavior.
+        daemon_port: Daemon listen port for http/http-mcp-remote (default 8765).
 
     Returns:
         List of per-IDE result dicts, one per input id.  Each dict has the
         same shape as :func:`connect_ide`'s return value::
 
-            {ide, mcp_config, mcp_path, agents_md, servers_preserved, error}
+            {ide, transport, mcp_config, mcp_path, agents_md, servers_preserved, error}
     """
     return [
         connect_ide(
@@ -419,6 +462,8 @@ def connect_many(
             here=here,
             profile=profile,
             agents_md_source=agents_md_source,
+            transport=transport,
+            daemon_port=daemon_port,
         )
         for ide_id in ide_ids
     ]
@@ -507,6 +552,57 @@ def _merge_yaml_list(
         return "wrote", pre_count
 
 
+def _build_server_block(
+    desc: IDEDescriptor,
+    transport: str,
+    daemon_port: int,
+    profile: str | None,
+) -> dict[str, Any]:
+    """Return the server block for the requested transport.
+
+    YAML and TOML IDEs use a format-specific block structure that is
+    incompatible with the JSON http/mcp-remote block — caller should never
+    reach here for those (they take the yaml branch in connect_ide).
+    For JSON-format IDEs:
+      "stdio"           → copy of desc.server_block with optional SLM_MCP_PROFILE env
+      "http"            → native MCP HTTP block; profile goes as URL query param
+      "http-mcp-remote" → mcp-remote stdio bridge; profile appended to proxied URL
+    """
+    base_url = f"http://127.0.0.1:{daemon_port}/mcp/"
+
+    if transport == "http":
+        url = base_url + (f"?profile={profile}" if profile else "")
+        return {"type": "http", "url": url}
+
+    if transport == "http-mcp-remote":
+        url = base_url + (f"?profile={profile}" if profile else "")
+        return {"type": "stdio", "command": "mcp-remote", "args": [url]}
+
+    # Default: stdio — preserve existing behavior exactly
+    block = copy.deepcopy(desc.server_block)
+    if profile:
+        block.setdefault("env", {})["SLM_MCP_PROFILE"] = profile
+    return block
+
+
+def _check_daemon_health(daemon_port: int, timeout: float = 2.0) -> bool:
+    """Non-blocking probe of the SLM daemon health endpoint.
+
+    Returns True if the daemon responds with HTTP 200, False otherwise.
+    Never raises — all exceptions are caught and treated as "unreachable".
+    """
+    try:
+        import urllib.request
+        import urllib.error
+
+        url = f"http://127.0.0.1:{daemon_port}/api/v3/health"
+        req = urllib.request.Request(url, method="GET")
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            return resp.status == 200
+    except Exception:
+        return False
+
+
 def _atomic_write(path: Path, data: dict[str, Any], fmt: str) -> None:
     """Serialize data and atomically write to path (.tmp + os.replace)."""
     path.parent.mkdir(parents=True, exist_ok=True)

package/src/superlocalmemory/hooks/prewarm_auth.py

@@ -38,6 +38,8 @@ _ORIGIN_HEADER_VARIANTS: tuple[str, ...] = ("Origin", "origin")
 
 # Loopback addresses accepted by LLD-01. ``localhost`` is NOT included per
 # SEC-01-02 — we want literal IPs only to avoid DNS-based bypass tricks.
+# Note: ::ffff:127.x.x.x is handled dynamically via ipaddress.ip_address()
+# in is_loopback() below to cover dual-stack container deployments (#90).
 _LOOPBACK_ADDRS: frozenset[str] = frozenset({"127.0.0.1", "::1"})
 
 # Body-size cap: LLD-01 §4.5 step 4 → 8 KB.
@@ -65,10 +67,27 @@ class AuthDecision:
 
 
 def is_loopback(client_host: str) -> bool:
-    """Return True iff ``client_host`` is an accepted loopback literal."""
+    """Return True iff ``client_host`` is an accepted loopback literal.
+
+    Deliberately excludes ``"localhost"`` per SEC-01-02 — /internal/prewarm
+    callers are in-process hooks that always connect to a literal IP, so
+    hostname aliases are rejected to prevent DNS-based bypass tricks.
+
+    Accepts IPv4-mapped IPv6 loopback (``::ffff:127.x.x.x``) for dual-stack
+    correctness (issue #90), while still excluding ``"localhost"``.
+    """
     if not isinstance(client_host, str) or not client_host:
         return False
-    return client_host in _LOOPBACK_ADDRS
+    if client_host in _LOOPBACK_ADDRS:
+        return True
+    # Handle IPv4-mapped IPv6 loopback (::ffff:127.x.x.x) — dual-stack fix.
+    # Intentionally NOT accepting "localhost" (SEC-01-02 preserved).
+    try:
+        import ipaddress as _ipa
+        ip = _ipa.ip_address(client_host)
+        return ip.is_loopback
+    except ValueError:
+        return False
 
 
 # ---------------------------------------------------------------------------

package/src/superlocalmemory/infra/auth_middleware.py

@@ -137,7 +137,9 @@ def authorize_http_mcp_request(
     peer must present the configured SLM API key.  The LAN allowlist limits
     reachability but deliberately does not grant a write identity.
     """
-    if client_host in ("127.0.0.1", "::1", "localhost"):
+    from superlocalmemory.server.loopback import is_loopback as _is_loopback_host
+
+    if _is_loopback_host(client_host):
         return True
     provided = request_headers.get("x-slm-api-key", "")
     return verify_api_key(provided, key_file=key_file)