fix(sdk): gate near-duplicate demotion with the MMR top-k threshold

near_dup_demote compares each candidate with every earlier
non-duplicate by Jaccard, quadratic when candidates differ. Its pool
grows with limit (about max(3*limit, 30) plus keyword hits), so a
limit-200 page could cost ~180k comparisons. It now runs only when the
caller's limit is below MMR_MAX_TOP_K, like MMR; large pages want every
relevant item, similar ones included. The read reports
near_dup_applied next to mmr_applied.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

CHANGELOG.md

@@ -4,6 +4,78 @@ Hy Memory and MemHub are versioned and released independently.
 
 ## Unreleased
 
+- SDK: `search(..., rerank=False)` skips every reranking stage for that one
+  call (the local cross-encoder, the memory-graph rerank, and the BM25 rerank of
+  working/coding facts), so results come back in retrieval-score order. The
+  flag travels on the read request, so concurrent searches do not affect each
+  other. The default (`True`) keeps current behavior; `/api/v1/search` accepts
+  it too.
+- SDK: MMR diversity selection now runs only when the requested `limit` is
+  below 20 (`MMR_MAX_TOP_K`) and is skipped for larger limits, where its
+  quadratic token-overlap pass is slow and gains little. Previously it ran for
+  every limit. `MEMORY_HYBRID_V2_MMR_LAMBDA` still sets the weight.
+  Near-duplicate demotion follows the same gate: it compares each candidate
+  with every earlier non-duplicate, which is quadratic in a pool that grows
+  with `limit`, and large result pages should show similar items anyway.
+- SDK: `search(scene="all")` searches chat, working and coding at the same time
+  and merges them with Reciprocal Rank Fusion (k=60) over each scene's own
+  ranking, so no scene is crowded out by the other scenes' score scales. Each
+  result says which scene and kind it came from. A scene that fails or is turned
+  off is reported in `errors` and does not fail the search. Source filters apply
+  to all three.
+- SDK: `list_memories(scene="all")` lists chat, working and coding memories
+  together, newest update first, with `limit`/`offset` paging over the merged
+  order and `total` summing all three. `scene="coding"` and `"working"` now
+  honor `include_sources` / `exclude_sources`, and `total` counts only the
+  filtered memories.
+- SDK: `update()` and `delete()` now work on working/coding experiences and
+  facts, not just chat memories. They take the same optional `kind` / `variant`
+  as `get()`, and an ID found in more than one place raises
+  `AmbiguousMemoryIdError` instead of guessing. Updating an experience replaces
+  its solution and keeps its task, unless a new `task=` is also passed; updating
+  a fact replaces its statement. Deleting removes the stored row and its vectors.
+- SDK: `list_memories(scene="chat" | "coding" | "working")` lists one kind of
+  memory. `coding` and `working` list that scene's whole store, newest update
+  first (`workspace_id` still narrows it), and `total` is now the real count
+  rather than the page size. The new `memory_stats()` returns the count and the
+  latest created/updated time for each scene and their total, without reading
+  any memory text. Previously coding and working memories could not be listed
+  or counted without a workspace, so a library of 45 memories listed 22.
+- The SDK migration no longer fails its first run on a home with legacy
+  vectors: reattaching them left a Chroma instance open with its own settings,
+  and the readback that followed could not open the same store
+  ("An instance of Chroma already exists ... with different settings").
+- MemHub "添加记忆" (add a memory) no longer waits behind unprocessed history.
+  Notes are claimed ahead of the event-time window that keeps history strictly
+  old to new; they still run one at a time and in order within their session.
+- SDK reconcile keeps time order. Both reconcile prompts now state that only
+  `memory_at` decides which memory is newer, that an older memory must never
+  supersede or overwrite a newer one, and that an unknown time is not newer;
+  the Chinese prompt now lists `memory_at` among the new-memory fields. The
+  reconciler also enforces this in code: a SUPERSEDE or UPDATE aimed at a memory
+  with a later `memory_at` becomes an ADD, so the newer memory stays current.
+- The SDK memory page now reads its list, count, source and time labels and
+  graph from one page response for one source filter, so rows, totals and the
+  map no longer disagree. Memories with no recorded source are shown and
+  filterable as "unidentified source"; library search keeps only memories
+  that contain the words within the SDK's relevance window.
+- Metadata repair v2 follows `governed_memory_evidence` across every
+  pre-cutover bundle, which restores the source of memories the cutover
+  backfilled without one, and moves impossible future conversation times back
+  to the write time.
+- Reused the existing three-column memory map for SDK-authority list/detail
+  views and removed the retired "original evidence" surface. SDK-native status,
+  source, conversation time and creation time now render without fabricated
+  revisions; source and text filters are applied by the paged Core endpoint.
+- SDK memory search now calls the SDK search contract instead of listing the
+  entire library in Core. Corrupt empty records are skipped and diagnosed
+  without mutating data or failing a page, and post-cutover metadata repair
+  restores source and original times from the verified migration bundle.
+- Kept Cursor's WAL change token separate from the file mtime so a hash can no
+  longer appear as a conversation date centuries in the future.
+- A trusted packaged Runtime now repairs a dirty same-build installation by
+  staging a clean replacement, and `runtime_service_not_ready` is rendered as
+  user-facing startup guidance instead of an internal code.
 - Fixed legacy-to-SDK startup migration to adopt native Coding Experience and
   Working Fact IDs instead of importing them as Chat layers. Raw migration now
   rebuilds bounded user/assistant turns from the latest three days, excludes

hy_memory/agent/prompts_zh.py

@@ -743,6 +743,7 @@ RECONCILE_PROMPT_ZH = """你是一个记忆整合系统（Memory Reconciler）
 
 * content
 * owner
+* memory_at（发生时间）
 * tags
 
 new memories 没有 ID。
@@ -791,6 +792,7 @@ new memories 没有 ID。
 * 无损合并
 * 保留所有有效信息
 * 不要产生重复 memory
+* 两者在某个值上不一致时，保留 memory_at 更晚的那个值；绝不用更早的 memory 覆盖更新的值
 
 ### 同一次事件的补充 vs 另一次发生
 
@@ -823,6 +825,7 @@ new memories 没有 ID。
 * 新 memory 与旧 memory 在同一维度冲突
 * 两者不能同时为真
 * 旧 memory 已不再代表当前状态
+* 新 memory 的 memory_at 不早于旧 memory 的 memory_at
 
 例如：
 
@@ -837,6 +840,7 @@ new memories 没有 ID。
 * wording 差异
 * 同义表达
 * 可共存偏好
+* 新 memory 的 memory_at 早于旧 memory：它是更早的状态，绝不能取代更新的状态（见「时间规则」）
 
 要求：
 
@@ -859,7 +863,7 @@ new memories 没有 ID。
 
 ### 把多条旧记忆折叠进同一条链
 
-如果**两条或更多**已有记忆描述的是**同一维度**，而新记忆是该维度上的最新变化，
+如果**两条或更多**已有记忆描述的是**同一维度**，而新记忆是该维度上的最新变化（它的 memory_at 晚于所有被折叠的记忆），
 你可以把它们折叠进同一条演化链。此时用 `memory_ids`（有序列表，**旧→新**）
 代替单个 `memory_id`：
 
@@ -951,13 +955,16 @@ SUPERSEDE 不需要复制旧内容，因为旧节点仍存在。
 
 ## 时间规则
 
-`memory_at: null`
+每条 memory（新的和已有的）都带 memory_at，表示它发生的时间。记忆**不一定按发生顺序写入**：
+历史可能晚导入，导入还没处理完时用户也可能手动添加记忆。所以一条 new memory 可能**比已有记忆更早**。
 
-表示时间未知。
-
-不要编造时间顺序。
-
-不要仅因为“看起来更新”就 supersede。
+* 新旧**只看 memory_at**。"New memories" 只表示"正在写入"，不表示"更近"。
+* 更早的 memory 绝不能取代更新的 memory：不能 SUPERSEDE 一条更新的记忆，也不能用 UPDATE 拿更早的值覆盖更新的值。
+* 如果 new memory 比与它冲突的已有记忆更早：保留已有记忆作为当前状态；把 new memory 以"过去状态"ADD
+  （用过去时，并带上时间，例如"2023 年用户住在上海"），没有新信息就不输出。
+* `memory_at: null` 表示时间未知。未知**不算更新**：不要用 memory_at 为 null 的 memory 去 SUPERSEDE 一条有时间的记忆。
+* 不要编造时间顺序。
+* 不要仅因为“看起来更新”就 supersede。
 
 ---
 

hy_memory/agent/reconciler.py

@@ -221,6 +221,8 @@ Rules:
 * merge losslessly
 * preserve all useful information
 * do NOT create duplicates
+* if the two disagree on a value, keep the value from the memory with the later
+  `memory_at`; never let an older memory overwrite a newer value
 
 ### Same occurrence vs. another occurrence
 
@@ -255,6 +257,7 @@ Use ONLY when:
 * the new memory contradicts an existing memory
 * both cannot be true at the same time
 * the old memory would now give the wrong current-state answer
+* the new memory's `memory_at` is the same as or LATER than the existing memory's `memory_at`
 
 Examples:
 
@@ -268,6 +271,8 @@ Do NOT use for:
 * compatible preferences
 * wording differences
 * semantic equivalence
+* a new memory whose `memory_at` is EARLIER than the existing memory's — it is an
+  older state and must never replace a newer one (see "Time order")
 
 Rules:
 
@@ -289,7 +294,8 @@ Rules:
 ### Folding several existing memories into one chain
 
 If TWO OR MORE existing memories track the SAME dimension and the new memory is
-the latest change on that dimension, you may fold them into a single evolution
+the latest change on that dimension — its `memory_at` is later than every folded
+memory's `memory_at` — you may fold them into a single evolution
 chain. Use `memory_ids` (an ordered list, OLDEST → NEWEST) instead of a single
 `memory_id`:
 
@@ -318,8 +324,7 @@ older memories' text into it; they remain queryable in the chain history.
 * Separate dated occurrences stay separate ADDs; use `same_series` only for the
   same subject and same concrete activity/event type.
 * Keep each memory focused on one coherent topic.
-* Do not invent chronology.
-* `memory_at: null` means unknown time.
+* Follow "Time order" below.
 * **NEVER merge or supersede across different subjects.** The subject is whoever
   the content is about: "The user ..." vs "John ..." vs "Mary ...". Memories about
   different people are independent facts even when the sentence is otherwise
@@ -332,6 +337,27 @@ older memories' text into it; they remain queryable in the chain history.
 
 ---
 
+# Time order
+
+Every memory, new or existing, has `memory_at`: when it happened. Memories are
+NOT always written in the order they happened — history can be imported late,
+and a memory can be added while older history is still being processed. A new
+memory can therefore be OLDER than an existing one.
+
+* Decide which memory is newer ONLY by `memory_at`. "New memories" means "being
+  written now", not "more recent".
+* An older memory must never replace a newer one: no SUPERSEDE of a newer
+  memory, and no UPDATE that overwrites a newer value with an older one.
+* If a new memory is older than an existing memory it conflicts with, keep the
+  existing memory as the current state. ADD the new one as a past state, worded
+  in the past with its time (for example "In 2023 the user lived in Shanghai"),
+  or output nothing if it adds no information.
+* `memory_at: null` means unknown time. Unknown is NOT newer: never SUPERSEDE a
+  memory that has a known `memory_at` with one whose `memory_at` is null.
+* Do not invent chronology.
+
+---
+
 # Optional: `related`
 
 On any op you MAY add a `related` array recording how the memory being written
@@ -441,6 +467,81 @@ def append_reconcile_structure_prompt(
     return prompt + RECONCILE_STRUCTURE_METADATA_PROMPT_EN
 
 
+def _as_aware(value: Any) -> Optional[datetime]:
+    """memory_at as a comparable aware datetime; None when unknown or unreadable."""
+    if isinstance(value, str) and value:
+        try:
+            value = datetime.fromisoformat(value)
+        except (TypeError, ValueError):
+            return None
+    if not isinstance(value, datetime):
+        return None
+    # Stored nodes rebuild memory_at from epoch seconds as naive local time
+    # (MemoryNode.from_dict), so a naive value is local, not UTC.
+    return value if value.tzinfo is not None else value.astimezone()
+
+
+def enforce_time_order(
+    ops: List["ReconcileOp"],
+    new_memory_at: Any,
+    existing: Dict[str, Any],
+) -> List["ReconcileOp"]:
+    """An older memory must never replace a newer one, whatever the model says.
+
+    Memories are not always written in the order they happened: history is
+    imported late, and a person can add a memory while older history is still
+    being processed. The prompt tells the model to compare `memory_at`; this
+    makes it hold. A SUPERSEDE or UPDATE aimed at an existing memory whose
+    `memory_at` is later than the memory being written is turned into an ADD,
+    so the newer memory stays the current state. Unknown times are not
+    compared. A content-less UPDATE (the legacy DELETE mapping) is dropped.
+    """
+    written_at = _as_aware(new_memory_at)
+    if written_at is None:
+        return ops
+    kept: List[ReconcileOp] = []
+    for op in ops:
+        if op.op not in ("SUPERSEDE", "UPDATE"):
+            kept.append(op)
+            continue
+        targets = list(op.memory_ids) if op.memory_ids else [op.memory_id]
+        newer = [
+            target for target in targets
+            if target and (node := existing.get(target)) is not None
+            and (target_at := _as_aware(getattr(node, "memory_at", None))) is not None
+            and target_at > written_at
+        ]
+        if not newer:
+            kept.append(op)
+            continue
+        logger.warning(
+            "[reconciler] %s blocked: memory_at %s is older than existing %s; "
+            "kept the newer memory",
+            op.op, written_at.isoformat(), ",".join(newer),
+        )
+        if not op.content:
+            continue
+        kept.append(ReconcileOp(
+            op="ADD",
+            content=op.content,
+            layer=op.layer,
+            owner=op.owner,
+            tags=list(op.tags),
+            tag_ners=list(op.tag_ners),
+            topic_paths=list(op.topic_paths),
+            event_facet=dict(op.event_facet),
+            topic_assignments=list(op.topic_assignments),
+            structure_references=list(op.structure_references),
+            topic_paths_provided=op.topic_paths_provided,
+            event_facet_provided=op.event_facet_provided,
+            topic_assignments_provided=op.topic_assignments_provided,
+            speculate=op.speculate,
+            related=list(op.related),
+            reason=f"time_order: older than {','.join(newer)}; {op.reason}"[:500],
+        ))
+    return kept
+
+
 def build_reconcile_prompt(
     *,
     new_memories: List[str],
@@ -1399,6 +1500,7 @@ class MemoryReconciler:
                 _tok_total += response.tokens_used
                 raw_response = response.content
                 ops = self._parse_ops(raw_response)
+                ops = enforce_time_order(ops, current_time, candidate_map)
                 ops = self._inherit_exact_input_structure(
                     ops, new_memories_with_meta,
                 )

hy_memory/coding/store.py

@@ -217,6 +217,21 @@ def _in_clause(column: str, values: Optional[List[str]]) -> Tuple[str, List[Any]
     return f"{column} IN ({placeholders})", list(values)
 
 
+def _source_where(
+    include_sources: Optional[List[str]], exclude_sources: Optional[List[str]],
+) -> Tuple[str, List[Any]]:
+    """Caller-source filter as SQL (``1`` when unfiltered); exclusion wins."""
+    clauses: List[str] = []
+    params: List[Any] = []
+    if include_sources:
+        clauses.append(f"source IN ({','.join('?' for _ in include_sources)})")
+        params.extend(include_sources)
+    if exclude_sources:
+        clauses.append(f"source NOT IN ({','.join('?' for _ in exclude_sources)})")
+        params.extend(exclude_sources)
+    return (" AND ".join(clauses) or "1"), params
+
+
 def _scope_matches(
     row_workspace_id: Optional[str],
     row_branch: Optional[str],
@@ -603,6 +618,86 @@ class CodingMemoryStore:
         logger.info(f"[coding-store] deleted experience_id={experience_id}")
         return True
 
+    async def edit_experience(
+        self,
+        experience_id: str,
+        *,
+        user_id: Optional[str] = None,
+        task: Optional[str] = None,
+        solution: Optional[str] = None,
+        search_keys: Optional[List[str]] = None,
+    ) -> Optional[CodingMemory]:
+        """调用方手动改一条经验（client.update 用）。返回改后的经验；不存在返回 None。
+
+        与 update() 的区别：update 是写入链路的覆盖式重写，带写授权校验（同
+        agent/session/workspace 才能改）；这里是用户对已有条目的直接编辑，只动
+        给定的字段，其余原样保留，因此不做授权校验。
+
+        向量行只嵌 task + search_keys（solution 不进向量），所以只改 solution 时
+        不重嵌、不碰向量库；改了 task / search_keys 才删旧 key 行重写。
+        updated_at 总是刷新。
+        """
+        prev = await self.get_by_id(experience_id, user_id=user_id)
+        if prev is None:
+            return None
+        updated = deepcopy(prev)
+        if task is not None:
+            updated.task = task
+        if solution is not None:
+            updated.solution = solution
+        if search_keys is not None:
+            updated.search_keys = list(search_keys)
+        updated.updated_at = datetime.utcnow()
+        await _run_in_pool(self._upsert_sql_sync, updated)
+        if updated.task != prev.task or updated.search_keys != prev.search_keys:
+            await self._delete_vec_keys_by_count(experience_id, 1 + len(prev.search_keys))
+            await self._upsert_vec_keys(updated)
+        logger.info(f"[coding-store] edited experience_id={experience_id}")
+        return updated
+
+    async def edit_fact(
+        self,
+        fact_id: str,
+        *,
+        statement: str,
+        user_id: Optional[str] = None,
+    ) -> Optional[WorkingFact]:
+        """调用方手动改一条事实的 statement。返回改后的事实；不存在返回 None。
+
+        statement 是事实层的检索文本，所以 active 事实会重嵌并覆盖它那一行向量
+        （node_id 就是 fact_id，upsert 即覆盖）。superseded 事实的向量行早已撤掉，
+        这里不把它加回去，否则会让过期结论重新占召回名额。
+        """
+        prev = await self.get_fact(fact_id, user_id=user_id)
+        if prev is None:
+            return None
+        updated = deepcopy(prev)
+        updated.statement = statement
+        await _run_in_pool(self._upsert_fact_sql_sync, updated)
+        if updated.status == "active":
+            await self._upsert_fact_vec(updated)
+        logger.info(f"[coding-store] edited fact_id={fact_id}")
+        return updated
+
+    async def delete_fact(self, fact_id: str, user_id: Optional[str] = None) -> bool:
+        """物理删除一条事实（SQLite 行 + 事实向量行），返回是否真有删到。
+
+        别处留下的引用（经验的 source_fact_ids、后继事实的 fact_link）不清：
+        召回侧本来就按存在性过滤死链（get_many / get_facts 查不到自然掉队）。
+        """
+        prev = await self.get_fact(fact_id, user_id=user_id)
+        if prev is None:
+            logger.info(f"[coding-store] delete fact skipped (not found): {fact_id}")
+            return False
+        if self._fact_vec is not None:
+            try:
+                await self._fact_vec.delete(fact_id)
+            except Exception as e:
+                logger.debug(f"[coding-store] delete fact vec {fact_id} ignored: {e}")
+        await _run_in_pool(self._delete_fact_sql_sync, fact_id, prev.user_id)
+        logger.info(f"[coding-store] deleted fact_id={fact_id}")
+        return True
+
     # ------------------------------------------------------------
     # 读取
     # ------------------------------------------------------------
@@ -687,29 +782,84 @@ class CodingMemoryStore:
         branch: Optional[str] = None,
         limit: int = 100,
         offset: int = 0,
+        include_sources: Optional[List[str]] = None,
+        exclude_sources: Optional[List[str]] = None,
     ) -> List["CodingMemory"]:
         """按 workspace_id（+可选 branch）纯过滤列出该 user 的完整 coding memory。
 
         作用域规则见 _scope_where（与 search 路径共用同一套）。无语义排序，按
-        updated_at 倒序（最近修改优先）。
+        updated_at 倒序（最近修改优先）。include_sources / exclude_sources 按
+        source 列在 SQL 里过滤（排除优先），所以 LIMIT/OFFSET 在过滤之后生效。
         """
         return await _run_in_pool(
-            self._list_by_workspace_sync, user_id, workspace_id, branch, limit, offset
+            self._list_by_workspace_sync, user_id, workspace_id, branch, limit, offset,
+            include_sources, exclude_sources,
         )
 
     def _list_by_workspace_sync(
         self, user_id: str, workspace_id: str, branch: Optional[str],
         limit: int, offset: int,
+        include_sources: Optional[List[str]] = None,
+        exclude_sources: Optional[List[str]] = None,
     ) -> List["CodingMemory"]:
         scope_sql, scope_params = _scope_where(workspace_id, branch)
+        source_sql, source_params = _source_where(include_sources, exclude_sources)
         with self._lock:
             assert self._conn is not None
             sql = (f"SELECT * FROM coding_memory_meta WHERE user_id = ? AND {scope_sql} "
-                   f"ORDER BY updated_at DESC LIMIT ? OFFSET ?")
-            params: List[Any] = [user_id] + scope_params + [limit, offset]
+                   f"AND {source_sql} "
+                   f"ORDER BY updated_at DESC, experience_id ASC LIMIT ? OFFSET ?")
+            params: List[Any] = ([user_id] + scope_params + source_params
+                                 + [limit, offset])
             cur = self._conn.execute(sql, params)
             return [_row_to_memory(r) for r in cur.fetchall()]
 
+    async def stats(
+        self,
+        user_id: str,
+        workspace_id: Optional[str] = None,
+        branch: Optional[str] = None,
+        include_sources: Optional[List[str]] = None,
+        exclude_sources: Optional[List[str]] = None,
+    ) -> Dict[str, Any]:
+        """经验数、最新创建/修改时间、active 事实数。纯聚合，不读正文。
+
+        作用域与 list_by_workspace 相同：workspace_id 为空表示该 user 全部；
+        来源过滤同样与 list_by_workspace 一致，count 因此恒等于分页可翻到的总数。
+        """
+        return await _run_in_pool(
+            self._stats_sync, user_id, workspace_id, branch,
+            include_sources, exclude_sources,
+        )
+
+    def _stats_sync(
+        self, user_id: str, workspace_id: Optional[str], branch: Optional[str],
+        include_sources: Optional[List[str]] = None,
+        exclude_sources: Optional[List[str]] = None,
+    ) -> Dict[str, Any]:
+        scope_sql, scope_params = _scope_where(workspace_id, branch)
+        source_sql, source_params = _source_where(include_sources, exclude_sources)
+        with self._lock:
+            assert self._conn is not None
+            row = self._conn.execute(
+                f"SELECT COUNT(*) AS n, MAX(created_at) AS created, "
+                f"MAX(updated_at) AS updated FROM coding_memory_meta "
+                f"WHERE user_id = ? AND {scope_sql} AND {source_sql}",
+                [user_id] + scope_params + source_params,
+            ).fetchone()
+            facts = self._conn.execute(
+                f"SELECT COUNT(*) AS n FROM working_fact "
+                f"WHERE user_id = ? AND status = 'active' AND {scope_sql} "
+                f"AND {source_sql}",
+                [user_id] + scope_params + source_params,
+            ).fetchone()
+        return {
+            "count": int(row["n"] or 0),
+            "latest_created_at": _parse_dt(row["created"]) if row["created"] else None,
+            "latest_updated_at": _parse_dt(row["updated"]) if row["updated"] else None,
+            "facts": int(facts["n"] or 0),
+        }
+
     # ------------------------------------------------------------
     # 召回
     # ------------------------------------------------------------
@@ -1088,6 +1238,14 @@ class CodingMemoryStore:
                 (experience_id, user_id),
             )
 
+    def _delete_fact_sql_sync(self, fact_id: str, user_id: str) -> None:
+        with self._lock:
+            assert self._conn is not None
+            self._conn.execute(
+                "DELETE FROM working_fact WHERE fact_id = ? AND user_id = ?",
+                (fact_id, user_id),
+            )
+
     def _get_by_id_sync(
         self, experience_id: str, user_id: Optional[str]
     ) -> Optional[CodingMemory]:

hy_memory/pipelines/_retrieval/diversity.py

@@ -160,6 +160,28 @@ def near_dup_demote(
     return out
 
 
+# MMR 只在调用方请求的 top-k（search 的 limit）小于这个值时自动启用。
+# mmr_select 的贪心是 O(k^2 * pool) 次 Jaccard，k 大时代价陡增，而大 k 本身已
+# 足够容纳多样性，收益很小。权重仍由 MEMORY_HYBRID_V2_MMR_LAMBDA 控制。
+MMR_MAX_TOP_K = 20
+
+
+def mmr_applies(top_k: int, lambda_: float) -> bool:
+    """本次检索是否走 MMR：λ 在有效区间内，且 top_k < MMR_MAX_TOP_K。"""
+    return 0.0 < float(lambda_) < 0.999 and int(top_k) < MMR_MAX_TOP_K
+
+
+def near_dup_applies(top_k: int) -> bool:
+    """本次检索是否走近重复降权：与 MMR 同一个 top-k 门槛。
+
+    near_dup_demote 让每个候选和此前所有"非重复"候选两两算 Jaccard，候选
+    互不相似时是 O(pool^2)；池子随 limit 放大（约 max(3*limit, 30) + 关键词
+    命中），limit 达到 MMR_MAX_TOP_K 时代价同样陡增。大 k 的调用方（如记忆
+    面板翻页）要的是全部相关项，相似项也应照常出现，降权没有收益。
+    """
+    return int(top_k) < MMR_MAX_TOP_K
+
+
 def mmr_select(
     hits: Sequence[Dict[str, Any]],
     limit: int,

hy_memory/pipelines/base.py

@@ -401,6 +401,11 @@ class ReadRequest:
     intention_limit: int = 0           # Intention 路的 topk，默认 0 关闭
 
 
+    # 重排开关（按次生效）。False 时跳过全部重排阶段：本地 cross-encoder
+    # (recall.local_rerank_enabled) 与记忆关系图重排 (_apply_graph_rerank)，
+    # 结果按召回分排序。走请求对象而非环境变量，并发请求互不影响。
+    rerank: bool = True
+
     # 时间过滤
     created_after: Optional[float] = None  # Unix timestamp (float)，只返回 gmt_created >= 此值的记忆
 

hy_memory/pipelines/reader_base.py

@@ -57,7 +57,9 @@ from ._retrieval.ner import (
     memory_matches_time_hints,
 )
 from ._retrieval.diversity import (
+    near_dup_applies,
     near_dup_demote,
+    mmr_applies,
     mmr_select,
     social_boilerplate_demote,
     pool_df_demote,
@@ -1279,7 +1281,10 @@ class BaseReadPipeline(ReadPipeline):
             SAME_SERIES_TIMELINE_ON = bool(
                 getattr(self.config.recall, "same_series_timeline_enabled", False)
             )
-            LOCAL_RERANK_ON = bool(
+            # 按次的重排开关（search(rerank=False)）：关掉本地 cross-encoder 与图重排，
+            # 结果按召回分排序。只读请求对象，不碰共享状态，并发请求互不影响。
+            RERANK_ON = bool(getattr(request, "rerank", True))
+            LOCAL_RERANK_ON = RERANK_ON and bool(
                 getattr(self.config.recall, "local_rerank_enabled", False)
             )
             LOCAL_RERANK_POOL_FACTOR = max(1, int(
@@ -1431,6 +1436,11 @@ class BaseReadPipeline(ReadPipeline):
             MIN_SCORE = _resolve_normal_min_score(request.min_score)
 
             final_limit = request.limit if request.limit > 0 else 10
+            # MMR 只在调用方的 top-k（final_limit，即 search 的 limit）< MMR_MAX_TOP_K
+            # 时启用；池子（LOCAL_RERANK 下是 final_limit 的若干倍）不参与判定。
+            MMR_ON = mmr_applies(final_limit, MMR_LAMBDA)
+            # 近重复降权同样是候选两两比较，用同一个 top-k 门槛。
+            NEAR_DUP_ON = near_dup_applies(final_limit)
             vdb_sem_limit = max(final_limit * 3, 30)
             vdb_kw_limit = max(final_limit * 5, 80)
             graph_limit = max(
@@ -2462,7 +2472,7 @@ class BaseReadPipeline(ReadPipeline):
             # 只把已选出的 top-N 换个顺序收益很小。
             relation_paths: List[Dict[str, Any]] = []
             _graph_stats: Dict[str, Any] = {}
-            if self._expansion_on():
+            if RERANK_ON and self._expansion_on():
                 _t_graph = datetime.now()
                 _pool_before = len(normal_results)
                 normal_results, relation_paths, _graph_stats = await self._apply_graph_rerank(
@@ -2525,7 +2535,7 @@ class BaseReadPipeline(ReadPipeline):
                         df_thr=POOL_DF_THR,
                         penalty=POOL_DF_PENALTY,
                     )
-                if NEAR_DUP_THR > 0 and NEAR_DUP_PENALTY > 0:
+                if NEAR_DUP_ON and NEAR_DUP_THR > 0 and NEAR_DUP_PENALTY > 0:
                     normal_results = near_dup_demote(
                         normal_results,
                         jaccard_thr=NEAR_DUP_THR,
@@ -2538,7 +2548,7 @@ class BaseReadPipeline(ReadPipeline):
                     ))
                     if LOCAL_RERANK_ON else final_limit
                 )
-                if 0.0 < MMR_LAMBDA < 0.999 and len(normal_results) > _pre_rerank_limit:
+                if MMR_ON and len(normal_results) > _pre_rerank_limit:
                     normal_results = mmr_select(
                         normal_results,
                         _pre_rerank_limit,
@@ -2715,7 +2725,7 @@ class BaseReadPipeline(ReadPipeline):
                         reverse=True,
                     )
                     if (
-                        0.0 < MMR_LAMBDA < 0.999
+                        MMR_ON
                         and len(multi_seed_pool) > _pre_rerank_limit
                     ):
                         multi_seed_pool = mmr_select(
@@ -3544,6 +3554,9 @@ class BaseReadPipeline(ReadPipeline):
                 "episode_capsule_render_mode": EPISODE_CAPSULE_RENDER_MODE,
                 "same_series_timeline_enabled": SAME_SERIES_TIMELINE_ON,
                 "local_rerank_enabled": LOCAL_RERANK_ON,
+                "rerank": RERANK_ON,
+                "mmr_applied": MMR_ON,
+                "near_dup_applied": NEAR_DUP_ON,
                 "local_rerank_model": getattr(
                     self.config.recall,
                     "local_rerank_model",

hy_memory/server.py

@@ -33,9 +33,28 @@ import threading
 from datetime import datetime
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 from typing import Any, Dict, Optional
+from urllib.parse import parse_qs, urlparse
+
+from .retrieval import AmbiguousMemoryIdError
 
 logger = logging.getLogger("hy_memory.server")
 
+
+def _namespace_args(values: Dict[str, Any]) -> Dict[str, Any]:
+    """kind / variant from a query string (lists) or a JSON body (scalars).
+
+    They disambiguate an id that exists in more than one namespace (chat,
+    experience, fact; working or coding). Absent means "resolve it".
+    """
+    args: Dict[str, Any] = {}
+    for key in ("kind", "variant"):
+        value = values.get(key)
+        if isinstance(value, list):
+            value = value[0] if value else None
+        if value:
+            args[key] = str(value)
+    return args
+
 # Lazy-init global client
 _client = None
 _client_lock = None
@@ -148,7 +167,6 @@ class MemoryHTTPHandler(BaseHTTPRequestHandler):
             if path == "/api/v1/metrics":
                 minutes = 5
                 if "?" in self.path:
-                    from urllib.parse import parse_qs, urlparse
                     qs = parse_qs(urlparse(self.path).query)
                     minutes = int(qs.get("minutes", ["5"])[0])
                 client = _get_client()
@@ -161,7 +179,8 @@ class MemoryHTTPHandler(BaseHTTPRequestHandler):
             if m:
                 memory_id = m.group(1)
                 client = _get_client()
-                result = client.get(memory_id)
+                query = parse_qs(urlparse(self.path).query)
+                result = client.get(memory_id, **_namespace_args(query))
                 if result is None:
                     _json_response(self, 404, {"error": "not_found", "memory_id": memory_id})
                 else:
@@ -170,6 +189,10 @@ class MemoryHTTPHandler(BaseHTTPRequestHandler):
 
             _json_response(self, 404, {"error": "not_found", "path": path})
 
+        except AmbiguousMemoryIdError as e:
+            _json_response(self, 409, {"error": "ambiguous_memory_id", "detail": str(e)})
+        except ValueError as e:
+            _json_response(self, 400, {"error": str(e)})
         except Exception as e:
             logger.error(f"[server] GET {path} error: {e}", exc_info=True)
             _json_response(self, 500, {"error": str(e)})
@@ -213,7 +236,7 @@ class MemoryHTTPHandler(BaseHTTPRequestHandler):
             _json_response(self, 500, {"error": str(e)})
 
     def do_PUT(self):
-        path = self.path.rstrip("/")
+        path = self.path.split("?")[0].rstrip("/")
         body = _read_json_body(self)
         if body is None:
             _json_response(self, 400, {"error": "invalid JSON body"})
@@ -228,29 +251,43 @@ class MemoryHTTPHandler(BaseHTTPRequestHandler):
                     _json_response(self, 400, {"error": "content is required"})
                     return
                 client = _get_client()
-                result = client.update(memory_id, content)
+                result = client.update(
+                    memory_id,
+                    content,
+                    **_namespace_args(body),
+                    **({"task": body["task"]} if body.get("task") else {}),
+                )
                 _json_response(self, 200, result)
                 return
 
             _json_response(self, 404, {"error": "not_found", "path": path})
 
+        except AmbiguousMemoryIdError as e:
+            _json_response(self, 409, {"error": "ambiguous_memory_id", "detail": str(e)})
+        except ValueError as e:
+            _json_response(self, 400, {"error": str(e)})
         except Exception as e:
             logger.error(f"[server] PUT {path} error: {e}", exc_info=True)
             _json_response(self, 500, {"error": str(e)})
 
     def do_DELETE(self):
-        path = self.path.rstrip("/")
+        path = self.path.split("?")[0].rstrip("/")
         try:
             m = re.match(r"^/api/v1/memories/([^/]+)$", path)
             if m:
                 memory_id = m.group(1)
                 client = _get_client()
-                result = client.delete(memory_id)
+                query = parse_qs(urlparse(self.path).query)
+                result = client.delete(memory_id, **_namespace_args(query))
                 _json_response(self, 200, result)
                 return
 
             _json_response(self, 404, {"error": "not_found", "path": path})
 
+        except AmbiguousMemoryIdError as e:
+            _json_response(self, 409, {"error": "ambiguous_memory_id", "detail": str(e)})
+        except ValueError as e:
+            _json_response(self, 400, {"error": str(e)})
         except Exception as e:
             logger.error(f"[server] DELETE {path} error: {e}", exc_info=True)
             _json_response(self, 500, {"error": str(e)})
@@ -455,7 +492,8 @@ class MemoryHTTPHandler(BaseHTTPRequestHandler):
             if key in body:
                 kwargs[key] = body[key]
 
-        for key in ("limit", "min_score", "schema_min_score", "schema_limit", "reader"):
+        for key in ("limit", "min_score", "schema_min_score", "schema_limit", "reader",
+                    "rerank"):
             if key in body:
                 kwargs[key] = body[key]
 

memhub/MEMORY.md

@@ -15,6 +15,8 @@
 3. MemHub **不存 memory 实体**；**可以存 `memory_id`** 做组织/回执。原文进入 **SDK raw**。
 4. SDK raw 只保留滚动三天；一条 raw 对应一个完整 turn，只含真人 user 与
    assistant，tool 不持久化。提取后的高层 memory 不受该窗口影响。
+5. `source_raw_ids` 是 SDK 内部溯源关系，不是产品 Evidence 合同；记忆详情不提供
+   “原始依据”或按 raw ID 展开原文的入口。
 
 生产入口通过共享 Runtime 租约取得公开 `HyMemoryClient`；MemHub 只在调用前执行
 模型配置、密钥和 harness/model 门禁，不维护第二套 memory 正文权威。

memhub/apps/cli/scripts/real-read-probe.mjs

@@ -21,18 +21,21 @@ const TOKEN = "probe-token-not-a-real-credential";
 
 const MEMORY = {
   memory_id: "probe-1",
-  user_id: "local",
-  kind: "chat",
-  status: "confirmed",
   content: "部署脚本要先跑 verify_merge_plan。",
-  scopes: ["all-apps"],
-  evidence_ids: ["probe-e1"],
-  origin: "extracted",
+  layer: "l2_fact",
+  status: "active",
+  is_latest: true,
+  supersedes: [],
+  superseded_by: [],
   tags: [],
-  revision: 2,
-  created_at: "2026-09-19T00:00:00Z",
-  updated_at: "2026-09-19T00:00:00Z",
-  deleted_at: null,
+  owner: null,
+  source_raw_ids: ["probe-raw-1"],
+  user_id: "local",
+  agent_id: "codex",
+  session_id: "probe-session",
+  source: "codex",
+  memory_at: 1758240000,
+  gmt_created: 1758240000,
 };
 
 const ROUTES = new Map([
@@ -124,26 +127,6 @@ const ROUTES = new Map([
       },
     ],
   ],
-  [
-    "/api/v1/memory-tasks",
-    [
-      {
-        task_id: "probe-task",
-        request_id: "probe-request",
-        user_id: "local",
-        kind: "extract",
-        input_ref: "probe",
-        status: "waiting_for_model",
-        profile_id: "probe-profile",
-        profile_revision: 1,
-        profile_snapshot: {},
-        attempts: 0,
-        last_error_code: "model_missing",
-        created_at: "2026-09-19T00:00:00Z",
-        updated_at: "2026-09-19T00:00:01Z",
-      },
-    ],
-  ],
   [
     "/api/v1/model-profiles",
     [
@@ -159,28 +142,20 @@ const ROUTES = new Map([
       },
     ],
   ],
-  ["/api/v1/home-summary", { memory_count: 1, latest: null, observed_at: "T" }],
   [
-    "/api/v1/memory-library",
-    { total: 1, offset: 0, limit: 100, items: [MEMORY] },
-  ],
-  [
-    "/api/v1/memories/probe-1",
+    "/api/v2/home-summary",
     {
-      memory: MEMORY,
-      evidence: [
-        {
-          evidence_id: "probe-e1",
-          available: true,
-          source_id: "codex",
-          written_by: "user",
-          created_at: "2026-09-19T00:00:00Z",
-          verbatim: "部署前先跑 verify_merge_plan，别靠读 diff 猜冲突。",
-        },
-      ],
-      history: [{ memory_id: "probe-1", revision: 2, action: "confirm" }],
+      schema_version: 2,
+      memory_count: 1,
+      latest: MEMORY,
+      observed_at: "2026-09-19T00:00:01Z",
     },
   ],
+  [
+    "/api/v2/memory-library",
+    { memories: [MEMORY], total: 1, offset: 0, limit: 100 },
+  ],
+  ["/api/v2/memories/probe-1", MEMORY],
 ]);
 
 const seen = [];

memhub/apps/cli/src/cli.test.ts

@@ -4,6 +4,7 @@ import path from "node:path";
 import {
   claimRuntimeServiceForApp,
   readRuntimeServiceOwner,
+  recordSdkMigrationBlock,
   resolveRuntimeCliConfig,
 } from "@one-memory/runtime-control";
 import { describe, expect, it, vi } from "vitest";
@@ -790,7 +791,7 @@ describe("public One Memory CLI", () => {
       }
     });
 
-    it("upgrade failure restarts the restored artifact with the same data identity", async () => {
+    it("upgrade restart failure keeps the new version and never restarts the old one", async () => {
       vi.clearAllMocks();
       runtimeMocks.planCliLink.mockResolvedValueOnce({
         schema_version: 1,
@@ -832,25 +833,27 @@ describe("public One Memory CLI", () => {
         command: "upgrade",
         code: "restart failed",
       });
-      expect(runtimeMocks.rollbackLocalInstall).toHaveBeenCalledOnce();
-      // The CLI manages the objective aliases the package does not own
-      // (`memhub` + `memhub-cli`); both are rolled back.
-      expect(aliasMocks.rollbackManagedCliLink).toHaveBeenCalledTimes(2);
-      expect(runtimeMocks.restartUserService).toHaveBeenCalledTimes(2);
-      for (const call of runtimeMocks.restartUserService.mock
-        .calls as unknown[][]) {
-        expect(call[0]).toMatchObject({
-          dataDir: "/tmp/custom data",
-          installRoot: "/tmp/install/current",
-        });
-      }
+      expect(JSON.parse(streams.stderr())).toMatchObject({
+        rolled_back: false,
+      });
+      // Product rule: the previous Runtime may predate the SDK migration gate,
+      // so it is never restored after the migration was handed the home.
+      expect(runtimeMocks.rollbackLocalInstall).not.toHaveBeenCalled();
+      expect(aliasMocks.rollbackManagedCliLink).not.toHaveBeenCalled();
+      expect(runtimeMocks.restartUserService).toHaveBeenCalledOnce();
+      expect(
+        (runtimeMocks.restartUserService.mock.calls as unknown[][])[0]?.[0],
+      ).toMatchObject({
+        dataDir: "/tmp/custom data",
+        installRoot: "/tmp/install/current",
+      });
     });
 
     // O-22 (2026-09-29 C8 H17): `upgrade --yes` on a manifest-valid but
     // crash-looping version reported exit 0 and left `current` on the bad
     // version. A restart that merely returns is not proof the new Runtime came
     // up, so the CLI now verifies health and rolls back if it never does.
-    it("rolls back and fails when the upgraded Runtime never becomes healthy", async () => {
+    it("fails without rolling back when the upgraded Runtime never becomes healthy", async () => {
       vi.clearAllMocks();
       runtimeMocks.planCliLink.mockResolvedValueOnce({
         schema_version: 1,
@@ -890,9 +893,9 @@ describe("public One Memory CLI", () => {
         command: "upgrade",
         code: "upgrade_health_check_failed",
       });
-      // Rolled back to the previous version and restarted it.
-      expect(runtimeMocks.rollbackLocalInstall).toHaveBeenCalledOnce();
-      expect(runtimeMocks.restartUserService).toHaveBeenCalledTimes(2);
+      // Kept on the new version; the old Runtime is not restarted.
+      expect(runtimeMocks.rollbackLocalInstall).not.toHaveBeenCalled();
+      expect(runtimeMocks.restartUserService).toHaveBeenCalledOnce();
     });
 
     const upgradeArguments = [
@@ -948,7 +951,7 @@ describe("public One Memory CLI", () => {
       );
     });
 
-    it("rolls back to the previous version when the migration does not finish", async () => {
+    it("stays on the new version, not serving, when the migration does not finish", async () => {
       vi.clearAllMocks();
       runtimeMocks.planCliLink.mockResolvedValueOnce(presentCliLink);
       runtimeMocks.runSdkMigration.mockResolvedValueOnce({
@@ -967,11 +970,87 @@ describe("public One Memory CLI", () => {
         streams.restore();
       }
       expect(code!).toBe(1);
-      expect(JSON.parse(streams.stderr())).toMatchObject({
+      const failure = JSON.parse(streams.stderr());
+      expect(failure).toMatchObject({
         command: "upgrade",
         code: "sdk_migration_disk_space_insufficient",
+        // The one file support needs, and where to send it.
+        log_file: "/tmp/custom data/logs/sdk-migration.log",
+        issues_url: "https://github.com/Tencent-Hunyuan/Hy-Memory/issues/new",
       });
+      expect(failure.message).toContain(
+        "/tmp/custom data/logs/sdk-migration.log",
+      );
+      expect(failure.message).toContain("GitHub");
+      expect(failure.message).not.toContain("回滚到上一版本");
+      expect(runtimeMocks.runSdkMigration).toHaveBeenCalledWith(
+        expect.objectContaining({ caller: "cli-upgrade" }),
+      );
+      // No rollback: the old Runtime has no migration gate. The new service is
+      // (re)started so its gate, not the old Runtime, holds the data dir.
+      expect(runtimeMocks.rollbackLocalInstall).not.toHaveBeenCalled();
+      expect(aliasMocks.rollbackManagedCliLink).not.toHaveBeenCalled();
+      expect(runtimeMocks.restartUserService).toHaveBeenCalledOnce();
+      expect(
+        (runtimeMocks.restartUserService.mock.calls as unknown[][])[0]?.[0],
+      ).toMatchObject({
+        installRoot: "/tmp/install/current",
+      });
+    });
+
+    it("stays on the new version when the migration itself throws", async () => {
+      vi.clearAllMocks();
+      runtimeMocks.planCliLink.mockResolvedValueOnce(presentCliLink);
+      runtimeMocks.runSdkMigration.mockRejectedValueOnce(
+        new Error("sdk_migration_fence_failed"),
+      );
+      const streams = captureStreams();
+      let code: number;
+      try {
+        code = await run(
+          upgradeArguments,
+          {},
+          { waitForRuntimeReady: async () => true },
+        );
+      } finally {
+        streams.restore();
+      }
+      expect(code!).toBe(1);
+      expect(JSON.parse(streams.stderr())).toMatchObject({
+        command: "upgrade",
+        code: "sdk_migration_fence_failed",
+        log_file: "/tmp/custom data/logs/sdk-migration.log",
+        issues_url: "https://github.com/Tencent-Hunyuan/Hy-Memory/issues/new",
+      });
+      expect(runtimeMocks.rollbackLocalInstall).not.toHaveBeenCalled();
+    });
+
+    it("still rolls back a failure before the migration touched the home", async () => {
+      vi.clearAllMocks();
+      runtimeMocks.planCliLink.mockResolvedValueOnce(presentCliLink);
+      aliasMocks.installManagedCliLink.mockRejectedValueOnce(
+        new Error("cli_link_failed"),
+      );
+      const streams = captureStreams();
+      let code: number;
+      try {
+        code = await run(
+          upgradeArguments,
+          {},
+          { waitForRuntimeReady: async () => true },
+        );
+      } finally {
+        streams.restore();
+      }
+      expect(code!).toBe(1);
+      expect(JSON.parse(streams.stderr())).toMatchObject({
+        command: "upgrade",
+        code: "cli_link_failed",
+      });
+      expect(runtimeMocks.runSdkMigration).not.toHaveBeenCalled();
       expect(runtimeMocks.rollbackLocalInstall).toHaveBeenCalledOnce();
+      // The previous Runtime was never stopped; nothing is (re)started.
+      expect(runtimeMocks.restartUserService).not.toHaveBeenCalled();
     });
 
     it("keeps the new version when a migrated home is slow to come up", async () => {
@@ -1492,7 +1571,7 @@ describe("public One Memory CLI", () => {
     expect(JSON.parse(output.value()).apply).toBe(true);
   });
 
-  it("rolls back the distribution when service installation fails", async () => {
+  it("keeps the distribution when service installation fails after the migration ran", async () => {
     runtimeMocks.applyLocalInstall.mockResolvedValueOnce({
       schema_version: 1,
       source: "/tmp/distribution",
@@ -1533,13 +1612,14 @@ describe("public One Memory CLI", () => {
       command: "install",
       status: "error",
       code: "service failed",
+      rolled_back: false,
     });
-    expect(runtimeMocks.rollbackLocalInstall).toHaveBeenCalledOnce();
-    expect(runtimeMocks.rollbackCliLink).toHaveBeenCalledOnce();
-    expect(aliasMocks.rollbackManagedCliLink).toHaveBeenCalledTimes(2);
+    expect(runtimeMocks.rollbackLocalInstall).not.toHaveBeenCalled();
+    expect(runtimeMocks.rollbackCliLink).not.toHaveBeenCalled();
+    expect(aliasMocks.rollbackManagedCliLink).not.toHaveBeenCalled();
   });
 
-  it("upgrades only an existing managed CLI and rolls back a failed restart", async () => {
+  it("upgrades only an existing managed CLI and keeps it after a failed restart", async () => {
     runtimeMocks.planCliLink.mockResolvedValueOnce({
       schema_version: 1,
       platform: "linux",
@@ -1579,7 +1659,7 @@ describe("public One Memory CLI", () => {
       status: "error",
       code: "restart failed",
     });
-    expect(runtimeMocks.rollbackLocalInstall).toHaveBeenCalledOnce();
+    expect(runtimeMocks.rollbackLocalInstall).not.toHaveBeenCalled();
     expect(runtimeMocks.installCliLink).not.toHaveBeenCalled();
   });
 
@@ -2003,6 +2083,101 @@ describe("lifecycle commands accept --json", () => {
   });
 });
 
+// A Runtime service that refuses to serve an unmigrated home must be reported
+// as that, with the migration log and where to send it, not as a generic
+// "not ready within budget".
+describe("lifecycle commands report a migration block", () => {
+  async function blockedHome() {
+    const dataDir = await mkdtemp(path.join(tmpdir(), "memhub-blocked-"));
+    await recordSdkMigrationBlock(
+      dataDir,
+      "sdk_migration_disk_space_insufficient",
+      "runtime-service",
+    );
+    return dataDir;
+  }
+  // darwin: kickstart "restarts" but never becomes ready. Elsewhere: no
+  // service, so the direct spawn fails. Both must surface the block.
+  const blockedControls = () => ({
+    restartManagedRuntime: vi.fn(async () => "restarted" as const),
+    waitForRuntimeReady: vi.fn(async () => false),
+    stopRuntime: vi.fn(async () => "stopped" as const),
+    ensureRuntime: vi.fn(async () => {
+      throw new Error("Timed out waiting for MemHub Runtime");
+    }),
+  });
+
+  it("restart --json prints the block code, log file and issues URL", async () => {
+    const dataDir = await blockedHome();
+    const output = captureStdout();
+    let code: number;
+    try {
+      code = await run(
+        ["restart", "--json"],
+        { ONE_MEMORY_DATA_DIR: dataDir },
+        blockedControls(),
+      );
+    } finally {
+      output.restore();
+      await rm(dataDir, { recursive: true, force: true });
+    }
+    expect(code!).toBe(1);
+    const lines = output.value().trim().split("\n");
+    const document = JSON.parse(lines[lines.length - 1]!);
+    expect(document).toMatchObject({
+      command: "restart",
+      state: "blocked",
+      code: "sdk_migration_disk_space_insufficient",
+      log_file: path.join(dataDir, "logs", "sdk-migration.log"),
+      issues_url: "https://github.com/Tencent-Hunyuan/Hy-Memory/issues/new",
+    });
+    expect(output.value()).not.toContain("runtime_not_ready_within_budget");
+  });
+
+  it("restart in text mode names the log file and GitHub issues", async () => {
+    const dataDir = await blockedHome();
+    const output = captureStdout();
+    try {
+      expect(
+        await run(
+          ["restart"],
+          { ONE_MEMORY_DATA_DIR: dataDir },
+          blockedControls(),
+        ),
+      ).toBe(1);
+    } finally {
+      output.restore();
+      await rm(dataDir, { recursive: true, force: true });
+    }
+    expect(output.value()).toContain("sdk_migration_disk_space_insufficient");
+    expect(output.value()).toContain(
+      path.join(dataDir, "logs", "sdk-migration.log"),
+    );
+    expect(output.value()).toContain(
+      "https://github.com/Tencent-Hunyuan/Hy-Memory/issues/new",
+    );
+  });
+
+  it("ui --json reports the block instead of runtime_not_running", async () => {
+    const dataDir = await blockedHome();
+    const output = captureStdout();
+    let code: number;
+    try {
+      code = await run(["ui", "--json"], { ONE_MEMORY_DATA_DIR: dataDir });
+    } finally {
+      output.restore();
+      await rm(dataDir, { recursive: true, force: true });
+    }
+    expect(code!).not.toBe(0);
+    expect(JSON.parse(output.value())).toMatchObject({
+      command: "ui",
+      state: "blocked",
+      code: "sdk_migration_disk_space_insufficient",
+      log_file: path.join(dataDir, "logs", "sdk-migration.log"),
+    });
+  });
+});
+
 // The objective names `memhub host install <host>` (host as a positional). Both
 // that and the `--host <id>` flag form must reach the same command; naming both
 // at once is ambiguous and refused rather than guessed.
@@ -2112,7 +2287,7 @@ describe("install gates on Runtime readiness", () => {
     });
   }
 
-  it("fails and rolls back when the installed Runtime never becomes ready", async () => {
+  it("fails without rolling back when the installed Runtime never becomes ready", async () => {
     vi.clearAllMocks();
     stubInstallPlan();
     const streams = captureStreams();
@@ -2141,10 +2316,10 @@ describe("install gates on Runtime readiness", () => {
     }
     expect(code!).toBe(1);
     expect(streams.stderr()).toContain("install_runtime_not_ready");
-    expect(runtimeMocks.rollbackLocalInstall).toHaveBeenCalledOnce();
+    expect(runtimeMocks.rollbackLocalInstall).not.toHaveBeenCalled();
     expect(
       lifecycleMocks.rollbackPreparedServiceInstall,
-    ).toHaveBeenCalledOnce();
+    ).not.toHaveBeenCalled();
   });
 
   it("takes CLI ownership after a successful install over an App-owned Runtime", async () => {
@@ -2189,7 +2364,7 @@ describe("install gates on Runtime readiness", () => {
     }
   });
 
-  it("restores App ownership before relaunching the old Runtime after install failure", async () => {
+  it("never hands the home back to the App Runtime after the migration ran", async () => {
     vi.clearAllMocks();
     stubInstallPlan();
     const root = await mkdtemp(path.join(tmpdir(), "memhub-cli-owner-"));
@@ -2199,14 +2374,6 @@ describe("install gates on Runtime readiness", () => {
       appBundle: "/Applications/MemHub.app",
       appExecutable: "/Applications/MemHub.app/Contents/MacOS/MemHub",
     });
-    lifecycleMocks.rollbackPreparedServiceInstall.mockImplementationOnce(
-      async (_prepared: unknown, rollback: () => Promise<void>) => {
-        await rollback();
-        await expect(readRuntimeServiceOwner(dataDir)).resolves.toMatchObject({
-          owner: "app",
-        });
-      },
-    );
     const streams = captureStreams();
     try {
       expect(
@@ -2229,15 +2396,114 @@ describe("install gates on Runtime readiness", () => {
           { waitForRuntimeReady: async () => false },
         ),
       ).toBe(1);
+      // The App Runtime may predate the SDK migration gate: CLI keeps it.
       await expect(readRuntimeServiceOwner(dataDir)).resolves.toMatchObject({
-        owner: "app",
+        owner: "cli",
       });
+      expect(
+        lifecycleMocks.rollbackPreparedServiceInstall,
+      ).not.toHaveBeenCalled();
     } finally {
       streams.restore();
       await rm(root, { recursive: true, force: true });
     }
   });
 
+  it("keeps the install, not serving, when its migration is deferred", async () => {
+    vi.clearAllMocks();
+    stubInstallPlan();
+    runtimeMocks.runSdkMigration.mockResolvedValueOnce({
+      state: "deferred",
+      code: "sdk_migration_memory_unreadable",
+    });
+    const waitForRuntimeReady = vi.fn(async () => true);
+    const streams = captureStreams();
+    let code: number;
+    try {
+      code = await run(
+        [
+          "install",
+          "--source",
+          "/tmp/dist",
+          "--home",
+          "/tmp/home",
+          "--install-root",
+          "/tmp/install",
+          "--bin-dir",
+          "/tmp/bin",
+          "--data-dir",
+          "/tmp/data",
+          "--yes",
+        ],
+        {},
+        { waitForRuntimeReady },
+      );
+    } finally {
+      streams.restore();
+    }
+    expect(code!).toBe(1);
+    const failure = JSON.parse(streams.stderr());
+    expect(failure).toMatchObject({
+      command: "install",
+      code: "sdk_migration_memory_unreadable",
+      log_file: "/tmp/data/logs/sdk-migration.log",
+      issues_url: "https://github.com/Tencent-Hunyuan/Hy-Memory/issues/new",
+    });
+    expect(failure.message).toContain("/tmp/data/logs/sdk-migration.log");
+    expect(runtimeMocks.runSdkMigration).toHaveBeenCalledWith(
+      expect.objectContaining({ caller: "cli-install" }),
+    );
+    // The new (gated) service owns the data dir; the previous registration is
+    // never re-bootstrapped and nothing is rolled back.
+    expect(lifecycleMocks.applyPreparedServiceInstall).toHaveBeenCalledWith(
+      expect.objectContaining({ restorePreviousOnFailure: false }),
+    );
+    expect(runtimeMocks.rollbackLocalInstall).not.toHaveBeenCalled();
+    expect(
+      lifecycleMocks.rollbackPreparedServiceInstall,
+    ).not.toHaveBeenCalled();
+    expect(waitForRuntimeReady).not.toHaveBeenCalled();
+  });
+
+  it("still rolls back an install that failed before its migration ran", async () => {
+    vi.clearAllMocks();
+    stubInstallPlan();
+    runtimeMocks.installCliLink.mockRejectedValueOnce(
+      new Error("cli_link_failed"),
+    );
+    const streams = captureStreams();
+    let code: number;
+    try {
+      code = await run(
+        [
+          "install",
+          "--source",
+          "/tmp/dist",
+          "--home",
+          "/tmp/home",
+          "--install-root",
+          "/tmp/install",
+          "--bin-dir",
+          "/tmp/bin",
+          "--data-dir",
+          "/tmp/data",
+          "--yes",
+        ],
+        {},
+        { waitForRuntimeReady: async () => true },
+      );
+    } finally {
+      streams.restore();
+    }
+    expect(code!).toBe(1);
+    expect(JSON.parse(streams.stderr())).toMatchObject({
+      command: "install",
+      code: "cli_link_failed",
+    });
+    expect(runtimeMocks.runSdkMigration).not.toHaveBeenCalled();
+    expect(runtimeMocks.rollbackLocalInstall).toHaveBeenCalledOnce();
+  });
+
   it("succeeds when the installed Runtime becomes ready", async () => {
     vi.clearAllMocks();
     stubInstallPlan();

memhub/apps/cli/src/cli.ts

@@ -32,6 +32,7 @@ import {
   processIsAlive,
   type ResolvedRuntimeRelease,
   RuntimeDiscoveryError,
+  readSdkMigrationBlock,
   removeRuntimeServiceOwner,
   resolveRuntimeCliConfig,
   resolveRuntimeRelease,
@@ -42,6 +43,7 @@ import {
   runSdkMigration,
   runtimeInstallLayout,
   type SdkMigrationResult,
+  sdkMigrationLogPath,
   stopRuntimeProcess,
 } from "@one-memory/runtime-control";
 import axios from "axios";
@@ -177,21 +179,10 @@ import {
   removeManagedCliLink,
   rollbackManagedCliLink,
 } from "./managed-cli-link.js";
-import {
-  executeMemoryMutation,
-  inspectMemoryPlan,
-  type MemoryFlowDocument,
-  memoryFlowExitCode,
-  memoryPlanAcceptsContent,
-  parseMemoryContent,
-  planExistingMemoryMutation,
-  planMemoryAdd,
-  readMemoryMutationReceipt,
-  renderMemoryFlowText,
-} from "./memory-flows.js";
 import {
   isMemoryId,
   type MemoryQuery,
+  parseMemoryContent,
   readMemoryDetail,
   readMemoryPage,
   renderMemoryDetailText,
@@ -1197,6 +1188,28 @@ async function runCommand(
           : state === "already_running"
             ? "MemHub Runtime 已在运行。\n"
             : "Runtime 服务已注册但未就绪；请运行 memhub logs 查看原因。\n";
+    // A Runtime that did not come up because its service refuses to serve an
+    // unmigrated home reports that cause, the migration log and where to send
+    // it, instead of a generic budget timeout.
+    const migrationBlocked = async (): Promise<string | null> => {
+      const blocked = await runtimeMigrationBlock(config.dataDir, command);
+      if (blocked === null) return null;
+      return asJson
+        ? `${JSON.stringify({
+            schema_version: 1,
+            product: PRODUCT,
+            command,
+            state: "blocked",
+            code: blocked.code,
+            message: blocked.message,
+            log_file: blocked.log_file,
+            issues_url: blocked.issues_url,
+          })}\n`
+        : `${blocked.message}\n`;
+    };
+    const notReady = async () =>
+      (await migrationBlocked()) ??
+      lifecycle("not-ready", "runtime_not_ready_within_budget");
     // A launchd-managed Runtime must be driven through launchctl. Spawning a
     // second process while the service holds the data directory is exactly what
     // produced "Runtime exited before becoming ready".
@@ -1241,16 +1254,12 @@ async function runCommand(
             process.stdout.write(lifecycle("restarted", "runtime_verified"));
             return EXIT_OK;
           }
-          process.stdout.write(
-            lifecycle("not-ready", "runtime_not_ready_within_budget"),
-          );
+          process.stdout.write(await notReady());
           await restoreEnableState();
           return EXIT_FAILED;
         }
         if (restarted === "not-ready") {
-          process.stdout.write(
-            lifecycle("not-ready", "runtime_not_ready_within_budget"),
-          );
+          process.stdout.write(await notReady());
           await restoreEnableState();
           return EXIT_FAILED;
         }
@@ -1306,16 +1315,12 @@ async function runCommand(
           process.stdout.write(lifecycle("started", "runtime_verified"));
           return EXIT_OK;
         }
-        process.stdout.write(
-          lifecycle("not-ready", "runtime_not_ready_within_budget"),
-        );
+        process.stdout.write(await notReady());
         await restoreEnableState();
         return EXIT_FAILED;
       }
       if (startedManaged === "not-ready") {
-        process.stdout.write(
-          lifecycle("not-ready", "runtime_not_ready_within_budget"),
-        );
+        process.stdout.write(await notReady());
         await restoreEnableState();
         return EXIT_FAILED;
       }
@@ -1344,6 +1349,11 @@ async function runCommand(
       // A spawned Runtime that exits before ready is a failure of this command,
       // not a crash: report it as a structured document (JSON) or a plain
       // message, with a non-zero exit, instead of letting it escape.
+      const blocked = await migrationBlocked();
+      if (blocked !== null) {
+        process.stdout.write(blocked);
+        return EXIT_FAILED;
+      }
       const message = error instanceof Error ? error.message : String(error);
       process.stdout.write(
         asJson
@@ -1540,6 +1550,24 @@ async function runCommand(
       return uiExitCode(result);
     };
     if (attachment === null) {
+      const migration = await runtimeMigrationBlock(config.dataDir, "ui");
+      if (migration !== null) {
+        emit(
+          asJson
+            ? `${JSON.stringify({
+                schema_version: 1,
+                product: PRODUCT,
+                command: "ui",
+                state: "blocked",
+                code: migration.code,
+                message: migration.message,
+                log_file: migration.log_file,
+                issues_url: migration.issues_url,
+              })}\n`
+            : `ui 未打开：${migration.code}\n${migration.message}\n`,
+        );
+        return uiExitCode({ state: "blocked", code: migration.code });
+      }
       return emitUi(
         { state: "blocked", code: "runtime_not_running" },
         `先运行 ${PRODUCT} start 启动 Runtime。`,
@@ -1644,7 +1672,7 @@ async function runCommand(
     });
     if (runtime.state !== "running") {
       const document: ContextSearchDocument = {
-        schema_version: 1,
+        schema_version: 2,
         product: PRODUCT,
         state: "unavailable",
         code: runtime.code,
@@ -1668,7 +1696,7 @@ async function runCommand(
           timeout_ms: parsed.timeoutMs,
         })
       : ({
-          schema_version: 1,
+          schema_version: 2,
           product: PRODUCT,
           state: "unavailable",
           code: attached.failure ?? "runtime_attach_failed",
@@ -2434,20 +2462,20 @@ async function runCommand(
       };
     }
     if (blocked || !reader) {
-      if (
-        parsed.kind === "update" ||
-        parsed.kind === "delete" ||
-        parsed.kind === "plan-add" ||
-        parsed.kind === "plan-existing" ||
-        parsed.kind === "apply"
-      ) {
-        const document: MemoryFlowDocument = {
-          schema_version: 1,
+      if (parsed.kind === "update" || parsed.kind === "delete") {
+        const document = {
+          schema_version: 2,
           product: PRODUCT,
           state: "unknown",
+          operation: parsed.kind,
+          memory_id: parsed.memoryId,
           code: blocked?.code ?? "runtime_attach_failed",
         };
-        emitMemoryFlow(document, asJson);
+        emit(
+          asJson
+            ? `${JSON.stringify(document)}\n`
+            : `记忆操作未完成：${document.state}（${document.code}）\n`,
+        );
         return runtime.state === "stopped" ? 3 : 1;
       }
       const document =
@@ -2541,73 +2569,7 @@ async function runCommand(
       );
       return outcome.state === "committed" ? EXIT_OK : EXIT_FAILED;
     }
-    if (parsed.kind === "plan-add") {
-      const content = await readMemoryContentFile(parsed.contentFile);
-      if (content === null) return usage();
-      const document = planMemoryAdd({
-        content,
-        memoryKind: parsed.memoryKind,
-        scopes: parsed.scopes,
-        evidenceIds: parsed.evidenceIds,
-      });
-      emitMemoryFlow(document, asJson);
-      return memoryFlowExitCode(document);
-    }
-    if (parsed.kind === "plan-existing") {
-      let content: string | undefined;
-      if (parsed.contentFile) {
-        const read = await readMemoryContentFile(parsed.contentFile);
-        if (read === null) return usage();
-        content = read;
-      }
-      const document = await planExistingMemoryMutation(reader, {
-        operation: parsed.operation,
-        memoryId: parsed.memoryId,
-        ...(content === undefined ? {} : { content }),
-      });
-      emitMemoryFlow(document, asJson);
-      return memoryFlowExitCode(document);
-    }
-    if (!operations) {
-      const document: MemoryFlowDocument = {
-        schema_version: 1,
-        product: PRODUCT,
-        state: "unknown",
-        code: "runtime_attach_failed",
-      };
-      emitMemoryFlow(document, asJson);
-      return EXIT_FAILED;
-    }
-    const file = await readBoundedJson(parsed.planFile);
-    if (file === null) return usage();
-    const plan = unwrapPlan(file);
-    const identity = inspectMemoryPlan(plan);
-    if (!identity) return usage();
-    let content: string | undefined;
-    if (parsed.contentFile) {
-      const read = await readMemoryContentFile(parsed.contentFile);
-      if (read === null) return usage();
-      content = read;
-    }
-    if (
-      (identity.needsContent && content === undefined) ||
-      (!identity.needsContent && content !== undefined) ||
-      !memoryPlanAcceptsContent(plan, content)
-    ) {
-      return usage();
-    }
-    const attempt = await claimPlanAttempt(parsed.planFile, {
-      schema_version: 1,
-      operation_id: identity.operationId,
-      plan_digest: identity.digest,
-    });
-    if (attempt === "invalid") return usage();
-    const document =
-      attempt === "prior"
-        ? await readMemoryMutationReceipt(reader, plan)
-        : await executeMemoryMutation(plan, content, operations, reader);
-    emitMemoryFlow(document, asJson);
-    return memoryFlowExitCode(document);
+    return usage();
   }
   if (named === "calls" || named === "import-file") {
     const parsed = parseUiWriteCommand(named, arguments_.slice(1));
@@ -2817,10 +2779,15 @@ async function runCommand(
         if (!ready) throw new Error("runtime_service_activation_unverified");
         return plan;
       })
-      .catch((error: unknown) => {
+      .catch(async (error: unknown) => {
+        const migration =
+          error instanceof Error &&
+          error.message === "runtime_service_activation_unverified"
+            ? await runtimeMigrationBlock(layout.dataDir, "service-install")
+            : null;
         process.stderr.write(
           `${JSON.stringify(
-            serviceErrorDocument("service-install", error),
+            migration ?? serviceErrorDocument("service-install", error),
             null,
             2,
           )}\n`,
@@ -3155,6 +3122,9 @@ async function runCommand(
     let installReceiptWritten = false;
     let serviceApplied = false;
     let migrated = false;
+    // `null` until the migration is handed this home; "failed" if it threw.
+    let migrationState: SdkMigrationResult["state"] | "failed" | null = null;
+    let deferredCode: string | null = null;
     let previousOwner:
       | Awaited<ReturnType<typeof claimCliServiceOwnership>>
       | undefined;
@@ -3167,6 +3137,7 @@ async function runCommand(
       previousOwner = await claimCliServiceOwnership(layout.dataDir);
       // `install` over an existing home (reinstall, App-to-CLI takeover) must
       // migrate it too, before the new Runtime starts serving it.
+      migrationState = "failed";
       const migration = await (
         controls.migrateSdkData ?? migrateSdkDataBeforeStart
       )({
@@ -3174,14 +3145,24 @@ async function runCommand(
         dataDir: layout.dataDir,
         runtimeBuild: String(plan.build_number ?? plan.version),
         asJson: true,
+        caller: "cli-install",
       });
+      migrationState = migration.state;
+      // A deferred migration keeps this install: the new Runtime service is
+      // registered and its migration gate keeps Core down until the home is
+      // migrated. Rolling back would hand the home to the previous (App or CLI)
+      // Runtime, which has no gate and would serve the legacy data.
       if (migration.state === "deferred") {
-        throw new SdkMigrationDeferred(
-          migration.code ?? "sdk_migration_incomplete",
-        );
+        deferredCode = migration.code ?? "sdk_migration_incomplete";
       }
-      migrated = migration.state === "cutover";
-      await applyPreparedServiceInstall(preparedService);
+      migrated =
+        migration.state === "cutover" || migration.state === "complete";
+      // From here the previous LaunchAgent is never re-bootstrapped: it may
+      // be an older Runtime with no migration gate.
+      await applyPreparedServiceInstall({
+        ...preparedService,
+        restorePreviousOnFailure: false,
+      });
       serviceApplied = true;
       // The receipt exists so a later command can find the data dir without
       // flags. An isolated install named its data dir explicitly, and writing
@@ -3197,6 +3178,7 @@ async function runCommand(
         });
         installReceiptWritten = true;
       }
+      if (deferredCode !== null) throw new SdkMigrationDeferred(deferredCode);
       // Registering the service is not the same as a working install: on a host
       // where Core cold-start stalls, launchd reports a pid while status is
       // still `runtime_service_running`. Gate on real readiness (same predicate
@@ -3232,10 +3214,38 @@ async function runCommand(
           );
         }
       };
-      if (migrated) {
-        // An older Runtime refuses a migrated home: keep this install.
+      // Once the migration has been handed this home nothing rolls back: the
+      // previous version (App or CLI) may be an older Runtime without the
+      // migration gate, and restoring it could serve a home that is not on SDK
+      // authority. This install stays; its service keeps Core down until the
+      // home is migrated. Only a failure before the migration ran (the
+      // previous Runtime was never stopped and the service never touched) is
+      // rolled back below.
+      if (migrationState !== null) {
+        if (!serviceApplied && !migrated && deferredCode === null) {
+          // The migration threw. Hand the data dir to this version's gated
+          // service anyway so that the previous Runtime does not come back.
+          await applyPreparedServiceInstall({
+            ...preparedService,
+            restorePreviousOnFailure: false,
+          }).catch(() => undefined);
+        }
         process.stderr.write(
-          `${JSON.stringify(notReadyAfterMigration("install"), null, 2)}\n`,
+          `${JSON.stringify(
+            deferredCode !== null
+              ? sdkMigrationFailure("install", deferredCode, layout.dataDir)
+              : migrated
+                ? notReadyAfterMigration("install")
+                : migrationState === "failed"
+                  ? sdkMigrationFailure(
+                      "install",
+                      sdkMigrationErrorCode(error),
+                      layout.dataDir,
+                    )
+                  : notReadyAfterUpgrade("install", error),
+            null,
+            2,
+          )}\n`,
         );
         return EXIT_FAILED;
       }
@@ -3248,13 +3258,7 @@ async function runCommand(
         await rollbackFilesAndOwner();
       }
       process.stderr.write(
-        `${JSON.stringify(
-          error instanceof SdkMigrationDeferred
-            ? sdkMigrationFailure("install", error.code)
-            : serviceErrorDocument("install", error),
-          null,
-          2,
-        )}\n`,
+        `${JSON.stringify(serviceErrorDocument("install", error), null, 2)}\n`,
       );
       return EXIT_FAILED;
     }
@@ -3617,9 +3621,17 @@ async function runCommand(
       | Awaited<ReturnType<typeof claimCliServiceOwnership>>
       | undefined;
     let migrated = false;
-    const rollbackUpgrade = async (
-      dataDir: string | undefined,
-    ): Promise<void> => {
+    // `null` until the migration is handed this home; "failed" if it threw.
+    let migrationState: SdkMigrationResult["state"] | "failed" | null = null;
+    /**
+     * Restore the previous version's files and ownership. Only used for a
+     * failure before the migration ran: the previous Runtime was never stopped
+     * and the service never restarted, so nothing new starts serving. After
+     * the migration has been handed the home the upgrade never rolls back:
+     * the previous Runtime may predate the migration gate and would serve a
+     * home that is not on SDK authority.
+     */
+    const rollbackUpgrade = async (): Promise<void> => {
       for (const receipt of memhubReceipts.reverse()) {
         await rollbackManagedCliLink(receipt);
       }
@@ -3629,25 +3641,29 @@ async function runCommand(
           () => undefined,
         );
       }
-      await restartUserService(
-        runtimeInstallLayout({
-          platform: plan.platform,
-          home: parsed.home,
-          installRoot: canonicalManagedServiceRoot(
-            plan.platform,
-            plan.current_link,
-          ),
-          dataDir,
-          ...hourlyIsolationFromEnvironment(environment),
-        }),
-        serviceOptions,
-      ).catch(() => undefined);
+    };
+    /**
+     * After a migration that did not finish, make sure the process holding the
+     * data dir is the new version's service (gated: it keeps Core down while
+     * the migration is deferred) and not the previous Runtime. The migration
+     * fence already stopped it unless the status probe itself failed.
+     */
+    const keepUpgradedRuntimeOffLegacyHome = async (): Promise<void> => {
+      try {
+        await restartUserService(layout, serviceOptions);
+      } catch {
+        await (controls.stopRuntime ?? stopRuntimeProcess)({
+          dataDir: parsed.dataDir ?? layout.dataDir,
+          probeIdentity,
+        }).catch(() => undefined);
+      }
     };
     try {
       for (const link of companionLinks) {
         memhubReceipts.push(await installManagedCliLink(link));
       }
       previousOwner = await claimCliServiceOwnership(layout.dataDir);
+      migrationState = "failed";
       const migration = await (
         controls.migrateSdkData ?? migrateSdkDataBeforeStart
       )({
@@ -3655,24 +3671,31 @@ async function runCommand(
         dataDir: parsed.dataDir ?? layout.dataDir,
         runtimeBuild: String(plan.build_number ?? plan.version),
         asJson,
+        caller: "cli-upgrade",
       });
+      migrationState = migration.state;
       if (migration.state === "deferred") {
-        await rollbackUpgrade(parsed.dataDir);
+        // Stay on the new version. Its Runtime service refuses to spawn Core
+        // while the migration is deferred, so nothing serves the legacy home;
+        // rolling back would restart the old Runtime, which has no such gate.
+        await keepUpgradedRuntimeOffLegacyHome();
         process.stderr.write(
-          `${JSON.stringify(sdkMigrationFailure("upgrade", migration.code ?? "sdk_migration_incomplete"), null, 2)}\n`,
+          `${JSON.stringify(sdkMigrationFailure("upgrade", migration.code ?? "sdk_migration_incomplete", parsed.dataDir ?? layout.dataDir), null, 2)}\n`,
         );
         return EXIT_FAILED;
       }
-      // An older Runtime refuses a migrated home, so from here a failure
-      // keeps the new version instead of rolling back to one that cannot start.
-      migrated = migration.state === "cutover";
+      // From here a failure keeps the new version: an older Runtime either
+      // refuses a migrated home or, predating the migration gate, would serve
+      // one that is not on SDK authority.
+      migrated =
+        migration.state === "cutover" || migration.state === "complete";
       await restartUserService(layout, serviceOptions);
       // A restart that returns without error only means launchd/systemd
       // accepted the command. O-22: the first `upgrade` implementation
       // reported success even when the new artifact crash-looped, leaving
       // `current` on a version that never came up. Verify the restarted
-      // Runtime actually becomes healthy; if it does not, roll back to the
-      // previously working version.
+      // Runtime actually becomes healthy; if it does not, fail loudly. It is
+      // not rolled back (product rule: SDK authority or not serving at all).
       const dataDir = parsed.dataDir ?? layout.dataDir;
       const ready = await (controls.waitForRuntimeReady ?? waitForRuntimeReady)(
         dataDir,
@@ -3684,20 +3707,11 @@ async function runCommand(
         return EXIT_FAILED;
       }
       if (!ready) {
-        await rollbackUpgrade(parsed.dataDir);
+        // Not rolled back: see `rollbackUpgrade`. If the service is blocked on
+        // the migration (it re-runs it before spawning Core), say so.
+        const blocked = await runtimeMigrationBlock(dataDir, "upgrade");
         process.stderr.write(
-          `${JSON.stringify(
-            {
-              schema_version: 1,
-              product: PRODUCT,
-              command: "upgrade",
-              status: "error",
-              code: "upgrade_health_check_failed",
-              message: "新版本重启后未在限定时间内就绪，已回滚到上一版本。",
-            },
-            null,
-            2,
-          )}\n`,
+          `${JSON.stringify(blocked ?? notReadyAfterUpgrade("upgrade"), null, 2)}\n`,
         );
         return EXIT_FAILED;
       }
@@ -3710,9 +3724,32 @@ async function runCommand(
         });
       }
     } catch (error) {
-      if (!migrated) await rollbackUpgrade(parsed.dataDir);
+      if (migrationState === null) {
+        await rollbackUpgrade();
+        process.stderr.write(
+          `${JSON.stringify(serviceErrorDocument("upgrade", error), null, 2)}\n`,
+        );
+        return EXIT_FAILED;
+      }
+      if (migrated) {
+        // An older Runtime refuses a migrated home: keep the new version.
+        process.stderr.write(
+          `${JSON.stringify(notReadyAfterMigration("upgrade"), null, 2)}\n`,
+        );
+        return EXIT_FAILED;
+      }
+      if (migrationState === "failed") {
+        // The migration itself threw: its outcome is unknown, so treat the
+        // home as not migrated and keep the old Runtime off it.
+        await keepUpgradedRuntimeOffLegacyHome();
+        process.stderr.write(
+          `${JSON.stringify(sdkMigrationFailure("upgrade", sdkMigrationErrorCode(error), parsed.dataDir ?? layout.dataDir), null, 2)}\n`,
+        );
+        return EXIT_FAILED;
+      }
+      // `not_required`: the restart itself failed. Stay on the new version.
       process.stderr.write(
-        `${JSON.stringify(migrated ? notReadyAfterMigration("upgrade") : serviceErrorDocument("upgrade", error), null, 2)}\n`,
+        `${JSON.stringify(notReadyAfterUpgrade("upgrade", error), null, 2)}\n`,
       );
       return EXIT_FAILED;
     }
@@ -4098,11 +4135,13 @@ async function migrateSdkDataBeforeStart(options: {
   dataDir: string;
   runtimeBuild: string;
   asJson: boolean;
+  caller?: "cli-install" | "cli-upgrade";
 }): Promise<SdkMigrationResult> {
   return runSdkMigration({
     dataDir: options.dataDir,
     core: { command: options.coreCommand },
     runtimeBuild: options.runtimeBuild,
+    ...(options.caller === undefined ? {} : { caller: options.caller }),
     onProgress: (step) => {
       process.stderr.write(
         options.asJson
@@ -4131,25 +4170,105 @@ function notReadyAfterMigration(command: "install" | "upgrade") {
   };
 }
 
-function sdkMigrationFailure(command: "install" | "upgrade", code: string) {
+/**
+ * The new version did not come up and was not rolled back: the previous one
+ * may predate the SDK migration gate. `error` carries the underlying code
+ * (a failed service restart), never free text from a child process.
+ */
+function notReadyAfterUpgrade(command: "install" | "upgrade", error?: unknown) {
+  return {
+    schema_version: 1,
+    product: PRODUCT,
+    command,
+    status: "error",
+    code:
+      error !== undefined
+        ? serviceErrorDocument(command, error).code
+        : command === "upgrade"
+          ? "upgrade_health_check_failed"
+          : "install_runtime_not_ready",
+    rolled_back: false,
+    message:
+      "新版本 Runtime 没有启动或没有在限定时间内就绪。为避免旧版本打开记忆数据，已保留新版本，没有回滚。请运行 memhub restart 重试，或运行 memhub doctor 查看原因；如果仍然失败，请在 GitHub 提交反馈：" +
+      MIGRATION_ISSUES_URL,
+    issues_url: MIGRATION_ISSUES_URL,
+  };
+}
+
+const SDK_MIGRATION_FAILURES: Record<string, string> = {
+  sdk_migration_disk_space_insufficient:
+    "磁盘空间不足，记忆数据迁移没有完成。请腾出与记忆数据同等大小的空间后运行 memhub restart 重试。",
+  sdk_migration_memory_unreadable:
+    "核对发现新版本还读不到你的全部记忆，没有切换数据源。",
+  sdk_migration_model_profile_required:
+    "迁移需要先有可用的模型配置，用来核对新版本能否读回记忆。请先用 memhub models setup 完成配置，再运行 memhub restart 重试。",
+};
+
+const MIGRATION_ISSUES_URL =
+  "https://github.com/Tencent-Hunyuan/Hy-Memory/issues/new";
+
+/**
+ * Why MemHub is not serving: the home has not reached SDK authority.
+ *
+ * Product rule: after an upgrade the home is on SDK authority or MemHub does
+ * not serve it at all. Nothing here rolls back to an older Runtime (it has no
+ * migration gate and would serve the legacy home); the user gets the code, the
+ * migration log and where to report it.
+ */
+function sdkMigrationFailure(
+  command: string,
+  code: string,
+  dataDir: string,
+  context: "upgrade" | "blocked" = "upgrade",
+) {
+  const logFile = sdkMigrationLogPath(dataDir);
+  const reason =
+    SDK_MIGRATION_FAILURES[code] ??
+    "记忆数据迁移没有完成。可以运行 memhub restart 重试。";
+  const lead =
+    context === "upgrade"
+      ? `${reason}已保留新版本；在迁移完成前 MemHub 不会启动，也不会用旧版本打开未迁移的数据。`
+      : `MemHub 没有启动：记忆数据还没有迁移到新版本（${code}）。${reason}`;
   return {
     schema_version: 1,
     product: PRODUCT,
     command,
     status: "error",
     code,
-    message:
-      code === "sdk_migration_disk_space_insufficient"
-        ? "磁盘空间不足，记忆数据迁移没有完成，已回滚到上一版本。请腾出与记忆数据同等大小的空间后重试；原有记忆数据不会丢失。"
-        : "记忆数据迁移没有完成，已回滚到上一版本。请重试；如果仍然失败，请把这个错误码反馈给我们。原有记忆数据不会丢失。",
+    message: `${lead}原有记忆数据不会丢失。迁移日志：${logFile}。请在 GitHub 提交反馈并附上这个日志文件：${MIGRATION_ISSUES_URL}`,
+    log_file: logFile,
+    issues_url: MIGRATION_ISSUES_URL,
   };
 }
 
+/** A stable code from a thrown migration error, never its free text. */
+function sdkMigrationErrorCode(error: unknown): string {
+  const message = error instanceof Error ? error.message : "";
+  return /^[a-z][a-z0-9_]{0,95}$/.test(message)
+    ? message
+    : "sdk_migration_incomplete";
+}
+
+/**
+ * The Runtime service refuses to spawn Core while this home's migration is
+ * deferred and leaves a block note; report that instead of a generic
+ * "not ready within budget".
+ */
+async function runtimeMigrationBlock(
+  dataDir: string,
+  command: string,
+): Promise<ReturnType<typeof sdkMigrationFailure> | null> {
+  const block = await readSdkMigrationBlock(dataDir).catch(() => null);
+  if (block === null) return null;
+  return sdkMigrationFailure(command, block.code, dataDir, "blocked");
+}
+
 async function waitForRuntimeReady(
   dataDir: string,
   timeoutMs = 45_000,
 ): Promise<boolean> {
-  const deadline = Date.now() + timeoutMs;
+  const started = Date.now();
+  const deadline = started + timeoutMs;
   while (Date.now() < deadline) {
     const runtime = await inspectRuntimeStatus({
       dataDir,
@@ -4157,6 +4276,11 @@ async function waitForRuntimeReady(
       requireServiceReceipt: true,
     }).catch(() => null);
     if (runtimeIsReady(runtime)) return true;
+    // The service deferred its migration during this wait and will not spawn
+    // Core: stop waiting. An older note may predate a retry still running, so
+    // only a note written after the wait began ends it early.
+    const blocked = await readSdkMigrationBlock(dataDir).catch(() => null);
+    if (blocked !== null && Date.parse(blocked.at) >= started) return false;
     await new Promise((resolve) => setTimeout(resolve, 500));
   }
   return false;
@@ -4861,10 +4985,10 @@ async function runMaintenanceRestore(options: {
   const instanceId = randomUUID();
   const child = spawn(options.coreCommand, ["serve", "--maintenance"], {
     env: {
-      // Do not pass the caller's Runtime tuning variables (for example
-      // retrieval-index flags) into a maintenance process: a restore must
-      // start the product's minimal maintenance configuration, not inherit
-      // an unrelated experiment from the shell.
+      // Do not pass the caller's Runtime tuning variables into a
+      // maintenance process: a restore must start the product's minimal
+      // maintenance configuration, not inherit an unrelated experiment from
+      // the shell.
       PATH: process.env.PATH,
       HOME: process.env.HOME,
       LANG: process.env.LANG,
@@ -6076,21 +6200,7 @@ type MemoryCommand =
       contentFile: string;
       confirmed: boolean;
     }
-  | { kind: "delete"; memoryId: string; confirmed: boolean }
-  | {
-      kind: "plan-add";
-      contentFile: string;
-      memoryKind: string;
-      scopes: string[];
-      evidenceIds: string[];
-    }
-  | {
-      kind: "plan-existing";
-      operation: "correct" | "delete";
-      memoryId: string;
-      contentFile?: string;
-    }
-  | { kind: "apply"; planFile: string; contentFile?: string };
+  | { kind: "delete"; memoryId: string; confirmed: boolean };
 
 async function parseMemoryCommand(
   rest: readonly string[],
@@ -6130,31 +6240,6 @@ async function parseMemoryCommand(
       ? { kind: "delete", memoryId, confirmed }
       : null;
   }
-  if (action === "plan" || action === "apply") return null;
-  if (action === "plan") return parseMemoryPlanCommand(tokens.slice(1));
-  if (action === "apply") {
-    let planFile: string | undefined;
-    let contentFile: string | undefined;
-    let confirmed = false;
-    for (let index = 1; index < tokens.length; index += 1) {
-      const flag = tokens[index];
-      if (flag === "--confirm") {
-        if (confirmed) return null;
-        confirmed = true;
-        continue;
-      }
-      const value = tokens[index + 1];
-      if (value === undefined || value.startsWith("--")) return null;
-      if (flag === "--plan-file" && planFile === undefined) planFile = value;
-      else if (flag === "--content-file" && contentFile === undefined)
-        contentFile = value;
-      else return null;
-      index += 1;
-    }
-    return planFile && confirmed
-      ? { kind: "apply", planFile, ...(contentFile ? { contentFile } : {}) }
-      : null;
-  }
   if (action !== "list") return null;
   let status: string | undefined;
   let offset = 0;
@@ -6181,73 +6266,11 @@ async function parseMemoryCommand(
   return { kind: "list", query: { status, offset, limit } };
 }
 
-function parseMemoryPlanCommand(
-  tokens: readonly string[],
-): MemoryCommand | null {
-  const operation = tokens[0];
-  const add = operation === "add";
-  if (!add && !["correct", "delete"].includes(operation)) {
-    return null;
-  }
-  const memoryId = add ? undefined : tokens[1];
-  if (!add && (!memoryId || !isMemoryId(memoryId))) return null;
-  let contentFile: string | undefined;
-  let memoryKind = "chat";
-  let kindSet = false;
-  const scopes: string[] = [];
-  const evidenceIds: string[] = [];
-  for (let index = add ? 1 : 2; index < tokens.length; index += 1) {
-    const flag = tokens[index];
-    const value = tokens[index + 1];
-    if (value === undefined || value.startsWith("--")) return null;
-    if (flag === "--content-file" && contentFile === undefined)
-      contentFile = value;
-    else if (flag === "--kind" && add && !kindSet) {
-      memoryKind = value;
-      kindSet = true;
-    } else if (flag === "--scope" && add && !scopes.includes(value))
-      scopes.push(value);
-    else if (flag === "--evidence" && add && !evidenceIds.includes(value))
-      evidenceIds.push(value);
-    else return null;
-    index += 1;
-  }
-  if (add) {
-    return contentFile && scopes.length > 0 && evidenceIds.length > 0
-      ? {
-          kind: "plan-add",
-          contentFile,
-          memoryKind,
-          scopes,
-          evidenceIds,
-        }
-      : null;
-  }
-  if (
-    (operation === "correct" && !contentFile) ||
-    (operation === "delete" && (contentFile !== undefined || scopes.length > 0))
-  ) {
-    return null;
-  }
-  return {
-    kind: "plan-existing",
-    operation: operation as "correct" | "delete",
-    memoryId: memoryId as string,
-    ...(contentFile ? { contentFile } : {}),
-  };
-}
-
 async function readMemoryContentFile(file: string): Promise<string | null> {
   const bytes = await readBoundedFile(file, 100_000 * 4 + 2);
   return bytes ? parseMemoryContent(bytes) : null;
 }
 
-function emitMemoryFlow(document: MemoryFlowDocument, asJson: boolean): void {
-  emit(
-    asJson ? `${JSON.stringify(document)}\n` : renderMemoryFlowText(document),
-  );
-}
-
 function emitModelWriteDocument(
   document: ModelWriteDocument,
   asJson: boolean,
@@ -6420,6 +6443,8 @@ function serviceErrorDocument(
       "服务文件不属于当前 MemHub 安装；请保留文件并确认其来源后再处理。",
     runtime_service_managed_upgrade_failed:
       "新服务启动失败，旧 MemHub 服务已恢复；检查新安装日志后重试。",
+    runtime_service_replacement_failed:
+      "新服务启动失败；记忆数据尚未处于新版本可用的状态，所以没有恢复旧服务。请运行 memhub doctor 检查服务状态。",
     runtime_service_managed_upgrade_rollback_failed:
       "新服务启动失败且旧服务恢复失败；请运行 memhub doctor 检查服务状态。",
     runtime_service_file_modified:

memhub/apps/cli/src/command-catalog.ts

@@ -387,7 +387,7 @@ export const COMMANDS: readonly CommandDescriptor[] = [
       {
         flag: "--content-file <path>",
         summary:
-          "从有界普通文件读取新增/纠正正文；计划只保存摘要，执行时再次校验。",
+          "从有界普通文件读取 update 的新正文；预览只显示摘要，--confirm 时才写入。",
       },
       DIRECT_CONFIRM_OPTION,
       JSON_OPTION,
@@ -485,7 +485,7 @@ export const COMMANDS: readonly CommandDescriptor[] = [
   {
     name: "recall",
     summary:
-      "从当前授权的原文与治理记忆统一检索上下文；本地只读，不调用模型、不触发补索引。",
+      "从当前授权的原文与已沉淀记忆统一检索上下文；本地只读，不调用模型、不触发补索引。",
     usage:
       "memhub recall <query> [--kind <raw|memory>] [--source <id>] [--limit <n>] [--character-budget <n>] [--timeout-ms <n>] [--json]\n            memhub recall --query-file <path> [...]\n            memhub recall --stdin [...]",
     options: [

memhub/apps/cli/src/context-search.test.ts

@@ -43,61 +43,35 @@ const ATTACHED = {
 };
 
 const RESPONSE = {
-  schema_version: 1,
+  schema_version: 2,
   request_id: "context-request-1",
   state: "grounded",
-  paths: {
-    raw: {
-      status: "ok",
-      reason: null,
-      elapsed_ms: 2,
-      returned_count: 1,
-      truncated: false,
-      truncated_by: [],
-    },
-    memory: {
-      status: "ok",
-      reason: null,
-      elapsed_ms: 3,
-      returned_count: 1,
-      truncated: false,
-      truncated_by: [],
-    },
-  },
   items: [
     {
       kind: "raw",
-      source_id: "codex",
-      conversation_id: "conversation-1",
-      anchor_evidence_id: "evidence-1",
-      messages: [
-        {
-          evidence_id: "evidence-1",
-          revision: 1,
-          role: "user",
-          written_by: "user",
-          created_at: "2026-09-19T00:00:00Z",
-          text: "Synthetic raw citation.",
-          truncated: false,
-        },
-      ],
+      raw_id: "raw-1",
+      content: "Synthetic raw citation.",
+      source: "codex",
+      session_id: "session-1",
+      memory_at: "2026-09-19T00:00:00Z",
+      score: 0.8,
       truncated: false,
     },
     {
       kind: "memory",
       memory_id: "memory-1",
-      revision: 2,
-      content: "Synthetic governed memory.",
-      memory_kind: "working",
+      content: "Synthetic SDK memory.",
+      layer: "l2_fact",
+      status: "active",
+      source: "codex",
       updated_at: "2026-09-19T00:00:01Z",
-      evidence_ids: ["evidence-1"],
+      score: 0.7,
       truncated: false,
     },
   ],
-  used_characters: 49,
+  used_characters: 44,
   truncated: false,
   total_ms: 5,
-  adoption: "unknown",
 };
 
 beforeEach(() => {
@@ -115,42 +89,17 @@ beforeEach(() => {
 });
 
 describe("unified context search", () => {
-  it("accepts an empty tool message in a valid partial context response", async () => {
+  it("accepts an empty raw item in a valid partial context response", async () => {
     transport.post.mockResolvedValue({
       status: 200,
       data: {
         ...RESPONSE,
         state: "partial",
-        paths: {
-          raw: {
-            ...RESPONSE.paths.raw,
-            status: "degraded",
-            reason: "lexical_only",
-            returned_count: 1,
-          },
-          memory: {
-            ...RESPONSE.paths.memory,
-            status: "empty",
-            returned_count: 0,
-          },
-        },
         items: [
           {
-            kind: "raw",
-            source_id: "workbuddy",
-            conversation_id: "conversation-1",
-            anchor_evidence_id: "evidence-1",
-            messages: [
-              {
-                evidence_id: "evidence-1",
-                revision: 1,
-                role: "tool",
-                written_by: "tool",
-                created_at: "2026-10-05T20:48:12Z",
-                text: "",
-                truncated: true,
-              },
-            ],
+            ...RESPONSE.items[0],
+            source: "workbuddy",
+            content: "",
             truncated: true,
           },
         ],
@@ -165,8 +114,9 @@ describe("unified context search", () => {
       streams.restore();
     }
     expect(JSON.parse(streams.stdout())).toMatchObject({
+      schema_version: 2,
       state: "partial",
-      items: [{ kind: "raw", messages: [{ text: "" }] }],
+      items: [{ kind: "raw", content: "" }],
     });
   });
 
@@ -178,12 +128,12 @@ describe("unified context search", () => {
       streams.restore();
     }
     const output = streams.stdout();
-    expect(output).toContain("Synthetic governed memory.");
+    expect(output).toContain("Synthetic SDK memory.");
     expect(output).toContain("Synthetic raw citation.");
-    expect(output).not.toMatch(/^- raw |memory-1|evidence-1|采用状态/m);
+    expect(output).not.toMatch(/^- raw |memory-1|raw-1|采用状态/m);
   });
 
-  it("queries the current read-only context endpoint and preserves citations", async () => {
+  it("queries the SDK context endpoint directly and preserves item ids", async () => {
     const streams = captureStreams();
     try {
       expect(
@@ -209,7 +159,7 @@ describe("unified context search", () => {
       streams.restore();
     }
     expect(transport.post).toHaveBeenCalledWith(
-      "/api/v1/context/search",
+      "/api/v2/context/search",
       {
         query: "synthetic question",
         kinds: ["raw", "memory"],
@@ -222,12 +172,18 @@ describe("unified context search", () => {
     );
     const output = JSON.parse(streams.stdout());
     expect(output).toMatchObject({
+      schema_version: 2,
       state: "grounded",
       request_id: "context-request-1",
-      adoption: "unknown",
     });
-    expect(output.items[0].messages[0].evidence_id).toBe("evidence-1");
-    expect(output.items[1].evidence_ids).toEqual(["evidence-1"]);
+    expect(output).not.toHaveProperty("paths");
+    expect(output.items[0]).toMatchObject({ kind: "raw", raw_id: "raw-1" });
+    expect(output.items[1]).toMatchObject({
+      kind: "memory",
+      memory_id: "memory-1",
+      layer: "l2_fact",
+    });
+    // No authority pre-query: released Core always serves the SDK data plane.
     expect(transport.get).not.toHaveBeenCalled();
     expect(transport.put).not.toHaveBeenCalled();
     expect(transport.patch).not.toHaveBeenCalled();
@@ -242,19 +198,8 @@ describe("unified context search", () => {
       status: 200,
       data: {
         ...RESPONSE,
-        paths: {
-          ...RESPONSE.paths,
-          raw: {
-            status: "not_requested",
-            reason: "not_requested",
-            elapsed_ms: 0,
-            returned_count: 0,
-            truncated: false,
-            truncated_by: [],
-          },
-        },
         items: [RESPONSE.items[1]],
-        used_characters: 26,
+        used_characters: 21,
       },
     });
     const streams = captureStreams();
@@ -394,29 +339,7 @@ describe("unified context search", () => {
       status: 200,
       data: {
         ...RESPONSE,
-        paths: {
-          ...RESPONSE.paths,
-          memory: {
-            ...RESPONSE.paths.memory,
-            status: "empty",
-            returned_count: 0,
-          },
-        },
-        items: [
-          {
-            ...(RESPONSE.items[0] as Record<string, unknown>),
-            messages: [
-              {
-                ...(
-                  RESPONSE.items[0] as {
-                    messages: Array<Record<string, unknown>>;
-                  }
-                ).messages[0],
-                text,
-              },
-            ],
-          },
-        ],
+        items: [{ ...RESPONSE.items[0], content: text }],
         used_characters: 10,
       },
     });
@@ -429,7 +352,7 @@ describe("unified context search", () => {
     expect(JSON.parse(streams.stdout())).toMatchObject({
       state: "grounded",
       used_characters: 10,
-      items: [{ kind: "raw", messages: [{ text }] }],
+      items: [{ kind: "raw", content: text }],
     });
   });
 
@@ -441,29 +364,7 @@ describe("unified context search", () => {
       status: 200,
       data: {
         ...RESPONSE,
-        paths: {
-          ...RESPONSE.paths,
-          memory: {
-            ...RESPONSE.paths.memory,
-            status: "empty",
-            returned_count: 0,
-          },
-        },
-        items: [
-          {
-            ...(RESPONSE.items[0] as Record<string, unknown>),
-            messages: [
-              {
-                ...(
-                  RESPONSE.items[0] as {
-                    messages: Array<Record<string, unknown>>;
-                  }
-                ).messages[0],
-                text,
-              },
-            ],
-          },
-        ],
+        items: [{ ...RESPONSE.items[0], content: text }],
         used_characters: 12,
       },
     });
@@ -479,6 +380,40 @@ describe("unified context search", () => {
     });
   });
 
+  it.each([
+    [
+      "a raw item from a source that was not asked for",
+      ["--source", "codex"],
+      { ...RESPONSE.items[0], source: "cursor" },
+    ],
+    [
+      "a raw item when only memory was asked for",
+      ["--kind", "memory"],
+      RESPONSE.items[0],
+    ],
+    ["a score outside 0..1", [], { ...RESPONSE.items[1], score: 1.5 }],
+  ])("rejects %s as an invalid response", async (_label, flags, item) => {
+    transport.post.mockResolvedValue({
+      status: 200,
+      data: {
+        ...RESPONSE,
+        items: [item],
+        used_characters: Array.from(String(item.content)).length,
+      },
+    });
+    const streams = captureStreams();
+    try {
+      expect(await run(["recall", "query", ...flags, "--json"])).toBe(1);
+    } finally {
+      streams.restore();
+    }
+    expect(JSON.parse(streams.stdout())).toMatchObject({
+      schema_version: 2,
+      state: "invalid",
+      code: "response_invalid",
+    });
+  });
+
   it("reports endpoint denial without exposing the response body", async () => {
     transport.post.mockResolvedValue({
       status: 403,

memhub/apps/cli/src/context-search.ts

@@ -3,31 +3,6 @@ import { PRODUCT } from "./version.js";
 
 export const CONTEXT_QUERY_MAX_CHARACTERS = 2_000;
 const CONTEXT_KINDS = ["raw", "memory"] as const;
-const PATH_STATES = [
-  "ok",
-  "empty",
-  "not_requested",
-  "not_authorized",
-  "unavailable",
-  "degraded",
-] as const;
-const PATH_REASONS = [
-  "not_requested",
-  "permission_required",
-  "source_revoked",
-  "read_unavailable",
-  "timeout_budget",
-  "evidence_changed",
-  "memory_changed",
-  "lexical_only",
-] as const;
-const LIMIT_REASONS = [
-  "count_budget",
-  "character_budget",
-  "timeout_budget",
-  "metadata_budget",
-] as const;
-
 export interface ContextSearchInput {
   query: string;
   kinds: Array<(typeof CONTEXT_KINDS)[number]>;
@@ -37,8 +12,9 @@ export interface ContextSearchInput {
   timeout_ms: number;
 }
 
+/** The CLI's JSON document mirrors Core's SDK-native context schema v2. */
 export interface ContextSearchDocument {
-  schema_version: 1;
+  schema_version: 2;
   product: string;
   state:
     | "grounded"
@@ -50,12 +26,10 @@ export interface ContextSearchDocument {
     | "invalid";
   code?: string;
   request_id?: string;
-  paths?: Record<string, unknown>;
   items: Array<Record<string, unknown>>;
   used_characters?: number;
   truncated?: boolean;
   total_ms?: number;
-  adoption?: "unknown";
 }
 
 export async function searchContext(
@@ -67,7 +41,7 @@ export async function searchContext(
   const validated = validateContextResponse(outcome.data, input);
   return (
     validated ?? {
-      schema_version: 1,
+      schema_version: 2,
       product: PRODUCT,
       state: "invalid",
       code: "response_invalid",
@@ -131,13 +105,7 @@ export function renderContextText(document: ContextSearchDocument): string {
         : "查到以下相关内容：",
   ];
   for (const item of document.items) {
-    if (item.kind === "memory") {
-      lines.push(`- ${String(item.content)}`);
-    } else {
-      for (const message of item.messages as Array<Record<string, unknown>>) {
-        lines.push(`- ${String(message.text)}`);
-      }
-    }
+    lines.push(`- ${String(item.content)}`);
   }
   if (document.truncated) lines.push("结果已按请求预算截断。");
   return `${lines.join("\n")}\n`;
@@ -149,84 +117,37 @@ function validateContextResponse(
 ): ContextSearchDocument | null {
   const response = record(value);
   if (
-    response?.schema_version !== 1 ||
+    response?.schema_version !== 2 ||
     !oneOf(response.state, ["grounded", "empty", "partial", "unavailable"]) ||
     !boundedText(response.request_id, 64) ||
-    !record(response.paths) ||
     !Array.isArray(response.items) ||
     response.items.length > request.limit ||
     !integer(response.used_characters, 0, request.character_budget) ||
     typeof response.truncated !== "boolean" ||
-    !number(response.total_ms, 0) ||
-    response.adoption !== "unknown"
+    !number(response.total_ms, 0)
   ) {
     return null;
   }
-  const paths = response.paths as Record<string, unknown>;
-  const rawPath = validatePath(paths.raw);
-  const memoryPath = validatePath(paths.memory);
-  if (!rawPath || !memoryPath) return null;
   const requested = new Set(request.kinds);
-  if (
-    (!requested.has("raw") && rawPath.status !== "not_requested") ||
-    (!requested.has("memory") && memoryPath.status !== "not_requested")
-  ) {
-    return null;
-  }
   const items: Array<Record<string, unknown>> = [];
   let characters = 0;
   for (const itemValue of response.items) {
     const item = validateItem(itemValue, request);
     if (!item || !requested.has(item.kind as "raw" | "memory")) return null;
     items.push(item);
-    characters +=
-      item.kind === "memory"
-        ? characterCount(item.content)
-        : (item.messages as Array<Record<string, unknown>>).reduce(
-            (sum, message) => sum + characterCount(message.text),
-            0,
-          );
+    characters += characterCount(item.content);
   }
   if (characters !== response.used_characters) return null;
   if (response.state === "empty" && items.length !== 0) return null;
   return {
-    schema_version: 1,
+    schema_version: 2,
     product: PRODUCT,
     state: response.state,
     request_id: response.request_id as string,
-    paths: { raw: rawPath, memory: memoryPath },
     items,
     used_characters: response.used_characters as number,
     truncated: response.truncated,
     total_ms: response.total_ms as number,
-    adoption: "unknown",
-  };
-}
-
-function validatePath(value: unknown): Record<string, unknown> | null {
-  const path = record(value);
-  if (
-    !path ||
-    !oneOf(path.status, PATH_STATES) ||
-    !number(path.elapsed_ms, 0) ||
-    !integer(path.returned_count, 0, 20) ||
-    typeof path.truncated !== "boolean" ||
-    !enumList(path.truncated_by, LIMIT_REASONS) ||
-    !(
-      path.reason === null ||
-      path.reason === undefined ||
-      oneOf(path.reason, PATH_REASONS)
-    )
-  ) {
-    return null;
-  }
-  return {
-    status: path.status,
-    reason: path.reason ?? null,
-    elapsed_ms: path.elapsed_ms,
-    returned_count: path.returned_count,
-    truncated: path.truncated,
-    truncated_by: path.truncated_by,
   };
 }
 
@@ -235,88 +156,65 @@ function validateItem(
   request: ContextSearchInput,
 ): Record<string, unknown> | null {
   const item = record(value);
-  if (!item || !oneOf(item.kind, CONTEXT_KINDS)) return null;
+  if (
+    !item ||
+    !oneOf(item.kind, CONTEXT_KINDS) ||
+    boundedText(item.content, 20_000, true) === null ||
+    !number(item.score, 0) ||
+    (item.score as number) > 1 ||
+    typeof item.truncated !== "boolean"
+  ) {
+    return null;
+  }
   if (item.kind === "memory") {
     if (
       !boundedText(item.memory_id, 512) ||
-      !integer(item.revision, 1) ||
-      boundedText(item.content, 20_000, true) === null ||
-      boundedText(item.memory_kind, 64, true) === null ||
-      !boundedText(item.updated_at, 64) ||
-      !textList(item.evidence_ids, 128, 512) ||
-      typeof item.truncated !== "boolean"
+      boundedText(item.layer, 64, true) === null ||
+      boundedText(item.status, 32, true) === null ||
+      !optionalText(item.source, 128) ||
+      !optionalText(item.updated_at, 64)
     ) {
       return null;
     }
     return {
       kind: "memory",
       memory_id: item.memory_id,
-      revision: item.revision,
       content: item.content,
-      memory_kind: item.memory_kind,
-      updated_at: item.updated_at,
-      evidence_ids: item.evidence_ids,
+      layer: item.layer,
+      status: item.status,
+      source: item.source ?? null,
+      updated_at: item.updated_at ?? null,
+      score: item.score,
       truncated: item.truncated,
     };
   }
   if (
-    !boundedText(item.source_id, 128) ||
+    !boundedText(item.raw_id, 512) ||
+    !boundedText(item.source, 128) ||
     (request.raw_source_ids !== undefined &&
-      !request.raw_source_ids.includes(item.source_id as string)) ||
-    !boundedText(item.conversation_id, 512) ||
-    !boundedText(item.anchor_evidence_id, 512) ||
-    !Array.isArray(item.messages) ||
-    item.messages.length < 1 ||
-    item.messages.length > 3 ||
-    typeof item.truncated !== "boolean"
+      !request.raw_source_ids.includes(item.source as string)) ||
+    !boundedText(item.session_id, 512) ||
+    !optionalText(item.memory_at, 64)
   ) {
     return null;
   }
-  const messages = item.messages.map(validateMessage);
-  if (messages.some((message) => message === null)) return null;
   return {
     kind: "raw",
-    source_id: item.source_id,
-    conversation_id: item.conversation_id,
-    anchor_evidence_id: item.anchor_evidence_id,
-    messages,
+    raw_id: item.raw_id,
+    content: item.content,
+    source: item.source,
+    session_id: item.session_id,
+    memory_at: item.memory_at ?? null,
+    score: item.score,
     truncated: item.truncated,
   };
 }
 
-function validateMessage(value: unknown): Record<string, unknown> | null {
-  const message = record(value);
-  if (
-    !message ||
-    !boundedText(message.evidence_id, 512) ||
-    !integer(message.revision, 1) ||
-    boundedText(message.role, 32, true) === null ||
-    boundedText(message.written_by, 32, true) === null ||
-    !(
-      message.created_at === null ||
-      boundedText(message.created_at, 64) !== null
-    ) ||
-    boundedText(message.text, 20_000, true) === null ||
-    typeof message.truncated !== "boolean"
-  ) {
-    return null;
-  }
-  return {
-    evidence_id: message.evidence_id,
-    revision: message.revision,
-    role: message.role,
-    written_by: message.written_by,
-    created_at: message.created_at,
-    text: message.text,
-    truncated: message.truncated,
-  };
-}
-
 function failed(
   outcome: Exclude<ReadOutcome<unknown>, { state: "ok" }>,
 ): ContextSearchDocument {
   return {
-    schema_version: 1,
+    schema_version: 2,
     product: PRODUCT,
     state: outcome.state,
     code: outcome.code,
@@ -374,27 +272,10 @@ function oneOf<const T extends readonly string[]>(
   return typeof value === "string" && values.includes(value as T[number]);
 }
 
-function enumList(
-  value: unknown,
-  values: readonly string[],
-): value is string[] {
+function optionalText(value: unknown, maximum: number): boolean {
   return (
-    Array.isArray(value) &&
-    value.length <= 4 &&
-    new Set(value).size === value.length &&
-    value.every((item) => oneOf(item, values))
-  );
-}
-
-function textList(
-  value: unknown,
-  maximumItems: number,
-  maximumText: number,
-): value is string[] {
-  return (
-    Array.isArray(value) &&
-    value.length <= maximumItems &&
-    new Set(value).size === value.length &&
-    value.every((item) => boundedText(item, maximumText) !== null)
+    value === null ||
+    value === undefined ||
+    boundedText(value, maximum) !== null
   );
 }

memhub/apps/cli/src/core-client.ts

@@ -8,14 +8,12 @@ import axios from "axios";
  */
 const READ_ONLY_PATHS = [
   "/api/v1/call-events",
-  "/api/v1/home-summary",
   "/api/v1/import-jobs",
   "/api/v1/live-sync",
-  "/api/v1/memory-library",
   "/api/v1/memory-processing",
-  "/api/v1/memory-tasks",
   "/api/v1/model-profiles",
   "/api/v1/sources",
+  "/api/v2/home-summary",
   "/api/v2/memory-library",
   "/api/v2/user-profile",
 ] as const;
@@ -67,13 +65,10 @@ export function createUiSessionRequest(attachment: {
   };
 }
 
-const MEMORY_DETAIL = /^\/api\/v1\/memories\/[A-Za-z0-9][\w.-]{0,127}$/;
 const IMPORT_JOB =
   /^\/api\/v1\/import-jobs\/[A-Za-z0-9][\w.-]{0,127}(?:\/issues)?$/;
 const OPERATION_RECEIPT =
   /^\/api\/v1\/(?:source-connections|model-profile-creations|model-probe-operations)\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
-const MEMORY_MUTATION_RECEIPT =
-  /^\/api\/v1\/memory-mutations\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 /**
  * Core registers these static routes before `/{memory_id}`, so a memory whose
  * id happens to be one of them would reach a different handler: `graph`
@@ -173,7 +168,7 @@ export function createCoreContextQuery(attachment: {
     let response: { status: number; data: unknown };
     try {
       response = await client.post(
-        "/api/v1/context/search",
+        "/api/v2/context/search",
         body,
         options?.signal ? { signal: options.signal } : undefined,
       );
@@ -197,10 +192,8 @@ export function isReadOnlyPath(path: string): boolean {
   if ((READ_ONLY_PATHS as readonly string[]).includes(path)) return true;
   if (IMPORT_JOB.test(path)) return true;
   if (OPERATION_RECEIPT.test(path)) return true;
-  if (MEMORY_MUTATION_RECEIPT.test(path)) return true;
-  if (SDK_MEMORY_DETAIL.test(path)) return true;
-  if (!MEMORY_DETAIL.test(path)) return false;
-  const segment = path.slice("/api/v1/memories/".length);
+  if (!SDK_MEMORY_DETAIL.test(path)) return false;
+  const segment = path.slice("/api/v2/memories/".length);
   return !(RESERVED_MEMORY_SEGMENTS as readonly string[]).includes(segment);
 }
 

memhub/apps/cli/src/core-responses.ts

@@ -1,18 +1,20 @@
 import type {
-  GovernedMemory,
-  HomeSummary,
   ImportIssue,
   ImportJob,
   LiveSyncHealth,
-  MemoryDetail,
-  MemoryEvidenceExcerpt,
-  MemoryLibraryPage,
   MemoryProcessingSummary,
   ModelProfile,
   SourceResponse,
 } from "@one-memory/contracts";
-/** The only memory states a response may carry, and the only ones a filter may ask for. */
-export const MEMORY_STATUSES = ["confirmed", "deleted", "superseded"] as const;
+/** SDK memory states `memhub memories list --status` may ask for. */
+export const MEMORY_STATUSES = [
+  "active",
+  "superseded",
+  "shadow",
+  "negated",
+  "conflicted",
+  "archived",
+] as const;
 
 /**
  * HTTP 200 is not a contract. Everything here re-checks the shape and the
@@ -23,7 +25,6 @@ export const MEMORY_STATUSES = ["confirmed", "deleted", "superseded"] as const;
 
 const ID_MAX = 128;
 const LABEL_MAX = 256;
-const TEXT_MAX = 100_000;
 const LIST_MAX = 500;
 const LIVE_SYNC_STATES = [
   "idle",
@@ -39,14 +40,6 @@ const PROVIDER_KINDS = [
   "local_onnx",
 ] as const;
 const CREDENTIAL_STATES = ["available", "missing", "unavailable"] as const;
-const MEMORY_KINDS = [
-  "chat",
-  "working",
-  "coding",
-  "schema",
-  "intention",
-] as const;
-const MEMORY_ORIGINS = ["extracted", "answered", "agent", "manual"] as const;
 const IMPORT_STATUSES = [
   "pending",
   "running",
@@ -57,16 +50,6 @@ const IMPORT_STATUSES = [
   "cancelled",
 ] as const;
 const SCAN_PHASES = ["discover", "read", "emit", "done"] as const;
-const MEMORY_TASK_KINDS = ["extract", "system2", "ultra", "sweeper"] as const;
-const MEMORY_TASK_STATUSES = [
-  "pending",
-  "running",
-  "waiting_for_model",
-  "completed",
-  "failed",
-  "cancelled",
-  "deferred_outside_window",
-] as const;
 const CAPABILITY_STATES = ["not_implemented", "implemented"] as const;
 const VERIFICATION_STATES = ["fixture_only", "real_replayed"] as const;
 const SYNC_COMPLETENESS = [
@@ -87,16 +70,6 @@ const LOCATION_STATES = [
 ] as const;
 const LIVE_SYNC_MODES = ["polling", "watch_and_polling"] as const;
 
-export interface ValidatedMemoryTask {
-  task_id: string;
-  kind: (typeof MEMORY_TASK_KINDS)[number];
-  status: (typeof MEMORY_TASK_STATUSES)[number];
-  attempts: number;
-  last_error_code: string | null;
-  created_at: string;
-  updated_at: string;
-}
-
 export interface SourceConnectionCandidate {
   source_id: string;
   display_name: string;
@@ -352,45 +325,6 @@ export function validateImportIssues(
   });
 }
 
-export function validateMemoryTasks(
-  value: unknown,
-): ValidatedMemoryTask[] | null {
-  return list(value, (item) => {
-    const task = record(item);
-    if (!task) return null;
-    const taskId = text(task.task_id, ID_MAX);
-    if (
-      task.last_error_code !== null &&
-      text(task.last_error_code, LABEL_MAX) === null
-    ) {
-      return null;
-    }
-    const error = task.last_error_code as string | null;
-    const createdAt = text(task.created_at, LABEL_MAX);
-    const updatedAt = text(task.updated_at, LABEL_MAX);
-    const attempts = count(task.attempts);
-    if (
-      taskId === null ||
-      createdAt === null ||
-      updatedAt === null ||
-      attempts === null ||
-      !oneOf(task.kind, MEMORY_TASK_KINDS) ||
-      !oneOf(task.status, MEMORY_TASK_STATUSES)
-    ) {
-      return null;
-    }
-    return {
-      task_id: taskId,
-      kind: task.kind,
-      status: task.status,
-      attempts,
-      last_error_code: error,
-      created_at: createdAt,
-      updated_at: updatedAt,
-    };
-  });
-}
-
 export function validateProcessing(
   value: unknown,
 ): MemoryProcessingSummary | null {
@@ -444,150 +378,32 @@ export function validateModelProfiles(value: unknown): ModelProfile[] | null {
   });
 }
 
-export function validateHomeSummary(value: unknown): HomeSummary | null {
+/** `GET /api/v2/home-summary`: the SDK-authority home card. */
+export interface SdkHomeSummary {
+  schema_version: 2;
+  memory_count: number;
+  latest: { memory_id: string } | null;
+  observed_at: string;
+}
+
+export function validateHomeSummary(value: unknown): SdkHomeSummary | null {
   const summary = record(value);
   if (
     !summary ||
+    summary.schema_version !== 2 ||
     count(summary.memory_count) === null ||
     text(summary.observed_at, LABEL_MAX) === null
   ) {
     return null;
   }
-  return summary as unknown as HomeSummary;
-}
-
-/** The page must be the page that was asked for, not merely a page. */
-export function validateMemoryPage(
-  value: unknown,
-  request: { offset: number; limit: number },
-): MemoryLibraryPage | null {
-  const page = record(value);
-  if (!page) return null;
-  const total = count(page.total);
-  if (
-    total === null ||
-    page.offset !== request.offset ||
-    page.limit !== request.limit
-  ) {
-    return null;
-  }
-  const items = list(page.items, validateGovernedMemory);
-  if (items === null || items.length > request.limit) return null;
-  if (items.length > 0 && total < request.offset + items.length) return null;
-  return { items, total, offset: page.offset, limit: page.limit };
-}
-
-export function validateMemoryDetail(
-  value: unknown,
-  memoryId: string,
-): MemoryDetail | null {
-  const detail = record(value);
-  if (!detail) return null;
-  const memory = validateGovernedMemory(detail.memory);
-  if (memory === null || memory.memory_id !== memoryId) return null;
-  const cited = new Set(memory.evidence_ids);
-  const returned = new Set<string>();
-  const evidence = list(detail.evidence ?? [], (item) => {
-    const excerpt = record(item);
-    if (!excerpt) return null;
-    const evidenceId = text(excerpt.evidence_id, ID_MAX);
-    // Core builds this list from the memory's own citations; anything else is
-    // another record's excerpt and must not be shown under this memory.
-    if (
-      evidenceId === null ||
-      !cited.has(evidenceId) ||
-      returned.has(evidenceId) ||
-      typeof excerpt.available !== "boolean"
-    ) {
+  const latest = summary.latest;
+  if (latest !== null) {
+    const memory = record(latest);
+    if (!memory || typeof memory.memory_id !== "string" || !memory.memory_id) {
       return null;
     }
-    returned.add(evidenceId);
-    const available = excerpt.available === true;
-    const verbatim = available ? text(excerpt.verbatim ?? "", TEXT_MAX) : "";
-    if (verbatim === null) return null;
-    return {
-      evidence_id: evidenceId,
-      available,
-      source_id: optional(excerpt.source_id, ID_MAX),
-      written_by: optional(excerpt.written_by, LABEL_MAX),
-      created_at: optional(excerpt.created_at, LABEL_MAX),
-      // An excerpt the user cannot read has no text, whatever the server sent.
-      verbatim,
-    } as unknown as MemoryEvidenceExcerpt;
-  });
-  if (evidence === null || evidence.length !== memory.evidence_ids.length) {
-    return null;
   }
-  const history = list(detail.history ?? [], (item) => {
-    const version = record(item);
-    if (
-      !version ||
-      typeof version.revision !== "number" ||
-      !Number.isSafeInteger(version.revision) ||
-      version.revision < 1 ||
-      text(version.action, LABEL_MAX) === null ||
-      !oneOf(version.status, MEMORY_STATUSES) ||
-      text(version.content, TEXT_MAX) === null ||
-      identifiers(version.scopes) === null ||
-      text(version.created_at, LABEL_MAX) === null
-    ) {
-      return null;
-    }
-    return {
-      revision: version.revision,
-      action: version.action,
-      status: version.status,
-      content: version.content,
-      scopes: identifiers(version.scopes) as string[],
-      created_at: version.created_at,
-    };
-  });
-  if (history === null) return null;
-  return {
-    memory,
-    evidence,
-    history,
-    index_sync: null,
-  } as unknown as MemoryDetail;
-}
-
-export function validateGovernedMemory(value: unknown): GovernedMemory | null {
-  const memory = record(value);
-  if (
-    !memory ||
-    !text(memory.memory_id, ID_MAX) ||
-    !text(memory.user_id, LABEL_MAX) ||
-    !text(memory.content, TEXT_MAX) ||
-    !oneOf(memory.kind, MEMORY_KINDS) ||
-    !oneOf(memory.origin, MEMORY_ORIGINS) ||
-    typeof memory.revision !== "number" ||
-    !Number.isSafeInteger(memory.revision) ||
-    memory.revision < 1 ||
-    !oneOf(memory.status, MEMORY_STATUSES) ||
-    !text(memory.created_at, LABEL_MAX) ||
-    !text(memory.updated_at, LABEL_MAX)
-  ) {
-    return null;
-  }
-  const scopes = identifiers(memory.scopes);
-  const evidenceIds = identifiers(memory.evidence_ids);
-  const tags = identifiers(memory.tags ?? []);
-  if (
-    scopes === null ||
-    scopes.length < 1 ||
-    evidenceIds === null ||
-    evidenceIds.length < 1 ||
-    tags === null ||
-    tags.length > 32
-  ) {
-    return null;
-  }
-  return {
-    ...memory,
-    scopes,
-    evidence_ids: evidenceIds,
-    tags,
-  } as unknown as GovernedMemory;
+  return summary as unknown as SdkHomeSummary;
 }
 
 function identifiers(value: unknown): string[] | null {
@@ -618,10 +434,6 @@ function text(value: unknown, max: number): string | null {
   return typeof value === "string" && value.length <= max ? value : null;
 }
 
-function optional(value: unknown, max: number): string | undefined {
-  return typeof value === "string" && value.length <= max ? value : undefined;
-}
-
 function count(value: unknown): number | null {
   return typeof value === "number" && Number.isSafeInteger(value) && value >= 0
     ? value

memhub/apps/cli/src/doctor-report.test.ts

@@ -134,11 +134,6 @@ function progress(): ProgressDocument {
     generation: {
       summary_state: { state: "ok" },
       summary: { waiting_for_model: 1, failed: 0 },
-      tasks_state: { state: "ok" },
-      tasks: [{ task_id: "t1", status: "waiting_for_model" }],
-      returned: 1,
-      validated: 1,
-      output_truncated: false,
     },
   };
 }

memhub/apps/cli/src/doctor-report.ts

@@ -65,6 +65,9 @@ export function renderDoctorText(document: DoctorDocument): string {
     model: "模型",
     pending_operations: "待处理操作",
   };
+  const migration = document.checks.find(
+    (check) => check.id === "core" && check.details?.log_file,
+  );
   return [
     `MemHub 检查：${doctorState(document.state)}`,
     ...document.checks.map(
@@ -73,7 +76,13 @@ export function renderDoctorText(document: DoctorDocument): string {
     ),
     ...(document.state === "healthy"
       ? []
-      : ["下一步：打开 MemHub 的“帮助与诊断”查看并处理异常。"]),
+      : migration
+        ? [
+            `升级迁移没有完成（错误码：${migration.code}），MemHub 不会启动。`,
+            `下一步：把迁移日志附在 GitHub 反馈里发给我们：${migration.details?.log_file}`,
+            `反馈地址：${migration.details?.issues_url}`,
+          ]
+        : ["下一步：打开 MemHub 的“帮助与诊断”查看并处理异常。"]),
     "",
   ].join("\n");
 }
@@ -107,6 +116,14 @@ function coreCheck(status: StatusDocument): DoctorCheck {
     id: "core",
     state: status.runtime.state === "stopped" ? "warn" : "fail",
     code: status.runtime.code,
+    ...(status.runtime.log_file
+      ? {
+          details: {
+            log_file: status.runtime.log_file,
+            issues_url: status.runtime.issues_url ?? "",
+          },
+        }
+      : {}),
   };
 }
 
@@ -200,8 +217,7 @@ function modelCheck(status: StatusDocument): DoctorCheck {
 function pendingCheck(progress: ProgressDocument | null): DoctorCheck {
   if (
     progress?.imports.state !== "ok" ||
-    progress.generation.summary_state.state !== "ok" ||
-    progress.generation.tasks_state.state !== "ok"
+    progress.generation.summary_state.state !== "ok"
   ) {
     return {
       id: "pending_operations",
@@ -212,27 +228,20 @@ function pendingCheck(progress: ProgressDocument | null): DoctorCheck {
   const jobAttention = progress.imports.jobs.filter((item) =>
     ["paused", "interrupted", "failed"].includes(text(item.status) ?? ""),
   ).length;
-  const taskAttention = progress.generation.tasks.filter((item) =>
-    ["waiting_for_model", "failed"].includes(text(item.status) ?? ""),
-  ).length;
   const summary = progress.generation.summary;
   const waiting = summary ? number(summary.waiting_for_model) : 0;
   const failed = summary ? number(summary.failed) : 0;
-  const attention = jobAttention + taskAttention + waiting + failed;
+  const attention = jobAttention + waiting + failed;
   return {
     id: "pending_operations",
     state: attention > 0 ? "warn" : "pass",
     code: attention > 0 ? "operations_need_attention" : "pending_operations_ok",
     details: {
       import_jobs_validated: progress.imports.validated,
-      generation_tasks_validated: progress.generation.validated,
       jobs_need_attention: jobAttention,
-      tasks_need_attention: taskAttention,
       waiting_for_model: waiting,
       failed,
-      output_truncated:
-        progress.imports.output_truncated ||
-        progress.generation.output_truncated,
+      output_truncated: progress.imports.output_truncated,
     },
   };
 }

memhub/apps/cli/src/memory-flows.ts

@@ -1,700 +0,0 @@
-import { createHash, randomUUID, timingSafeEqual } from "node:crypto";
-import type { GovernedMemory } from "@one-memory/contracts";
-import {
-  buildMemoryActionRequest,
-  buildMemoryCorrectRequest,
-  buildMemoryCreateRequest,
-  parseMemoryReceipt,
-} from "@one-memory/operations";
-import type { CoreReader } from "./core-client.js";
-import type { CoreOperations } from "./core-operations.js";
-import { validateMemoryDetail } from "./core-responses.js";
-import { isMemoryId } from "./memory-report.js";
-import { PRODUCT } from "./version.js";
-
-const MEMORY_KINDS = [
-  "chat",
-  "working",
-  "coding",
-  "schema",
-  "intention",
-] as const;
-const OPERATIONS = ["add", "correct", "delete"] as const;
-const MEMORY_ORIGINS = ["extracted", "answered", "agent", "manual"] as const;
-const MUTATION_RECEIPT_KEYS = new Set([
-  "schema_version",
-  "request_id",
-  "state",
-  "operation",
-  "memory_id",
-  "result_revision",
-  "result_status",
-  "memory_state",
-  "migrated_from",
-]);
-const CONTENT_MAX_CHARACTERS = 100_000;
-const ID = /^[A-Za-z0-9][\w.-]{0,127}$/;
-const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
-
-interface PlanBody {
-  schema_version: 1;
-  kind: "memory_mutation";
-  operation: (typeof OPERATIONS)[number];
-  request_id: string;
-  memory_id?: string;
-  expected_revision?: number;
-  expected_status?: string;
-  expected_origin?: string;
-  memory_kind?: (typeof MEMORY_KINDS)[number];
-  scopes?: string[];
-  evidence_ids?: string[];
-  content_sha256?: string;
-  content_characters?: number;
-  current?: {
-    status: string;
-    origin: string;
-    revision: number;
-    scopes: string[];
-    evidence: Array<{
-      evidence_id: string;
-      available: boolean;
-      source_id?: string;
-      written_by?: string;
-    }>;
-  };
-}
-
-export type MemoryMutationPlan = PlanBody & { digest: string };
-
-export type MemoryFlowDocument =
-  | {
-      schema_version: 1;
-      product: string;
-      state: "preview";
-      plan: MemoryMutationPlan;
-    }
-  | {
-      schema_version: 1;
-      product: string;
-      state: "committed" | "recovered";
-      operation_id: string;
-      receipt: Record<string, unknown>;
-    }
-  | {
-      schema_version: 1;
-      product: string;
-      state: "rejected" | "unknown" | "invalid";
-      operation_id?: string;
-      code: string;
-    };
-
-export function parseMemoryContent(bytes: Buffer): string | null {
-  if (bytes.byteLength > CONTENT_MAX_CHARACTERS * 4 + 2) return null;
-  let decoded: string;
-  try {
-    decoded = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
-  } catch {
-    return null;
-  }
-  const content = decoded.replace(/\r?\n$/, "");
-  return content.trim().length > 0 &&
-    [...content].length <= CONTENT_MAX_CHARACTERS &&
-    ![...content].some((character) => {
-      const code = character.charCodeAt(0);
-      return code <= 8 || (code >= 11 && code <= 31) || code === 127;
-    })
-    ? content
-    : null;
-}
-
-export function planMemoryAdd(input: {
-  content: string;
-  memoryKind: string;
-  scopes: string[];
-  evidenceIds: string[];
-}): MemoryFlowDocument {
-  if (
-    !validContent(input.content) ||
-    !oneOf(input.memoryKind, MEMORY_KINDS) ||
-    !validScopes(input.scopes) ||
-    !validIds(input.evidenceIds, 500)
-  ) {
-    return invalid("memory_add_input_invalid");
-  }
-  return preview(
-    withDigest({
-      schema_version: 1,
-      kind: "memory_mutation",
-      operation: "add",
-      request_id: randomUUID(),
-      memory_kind: input.memoryKind,
-      scopes: input.scopes,
-      evidence_ids: input.evidenceIds,
-      ...contentIdentity(input.content),
-    }),
-  );
-}
-
-export async function planExistingMemoryMutation(
-  reader: CoreReader,
-  input: {
-    operation: Exclude<(typeof OPERATIONS)[number], "add">;
-    memoryId: string;
-    content?: string;
-  },
-): Promise<MemoryFlowDocument> {
-  if (
-    !isMemoryId(input.memoryId) ||
-    (input.operation === "correct" && input.content === undefined) ||
-    (input.content !== undefined && !validContent(input.content))
-  ) {
-    return invalid("memory_plan_input_invalid");
-  }
-  const outcome = await reader<unknown>(`/api/v1/memories/${input.memoryId}`);
-  if (outcome.state !== "ok") {
-    return invalid(`memory_${outcome.state}:${outcome.code}`);
-  }
-  const detail = validateMemoryDetail(outcome.data, input.memoryId);
-  if (!detail) return invalid("memory_response_invalid");
-  const memory = detail.memory;
-  if (memory.status !== "confirmed") {
-    return invalid("memory_operation_not_allowed");
-  }
-  const body: PlanBody = {
-    schema_version: 1,
-    kind: "memory_mutation",
-    operation: input.operation,
-    request_id: randomUUID(),
-    memory_id: memory.memory_id,
-    expected_revision: memory.revision,
-    expected_status: memory.status,
-    expected_origin: memory.origin,
-    ...(input.content ? contentIdentity(input.content) : {}),
-    current: {
-      status: memory.status,
-      origin: memory.origin,
-      revision: memory.revision,
-      scopes: [...memory.scopes],
-      evidence: detail.evidence.map((item) => ({
-        evidence_id: item.evidence_id,
-        available: item.available,
-        ...(item.source_id ? { source_id: item.source_id } : {}),
-        ...(item.written_by ? { written_by: item.written_by } : {}),
-      })),
-    },
-  };
-  return preview(withDigest(body));
-}
-
-export function inspectMemoryPlan(
-  value: unknown,
-): { operationId: string; digest: string; needsContent: boolean } | null {
-  const plan = validatePlan(value);
-  return plan
-    ? {
-        operationId: plan.request_id,
-        digest: plan.digest,
-        needsContent: plan.operation === "add" || plan.operation === "correct",
-      }
-    : null;
-}
-
-export function memoryPlanAcceptsContent(
-  value: unknown,
-  content: string | undefined,
-): boolean {
-  const plan = validatePlan(value);
-  if (!plan) return false;
-  if (plan.operation !== "add" && plan.operation !== "correct") {
-    return content === undefined;
-  }
-  if (content === undefined) return false;
-  const identity = contentIdentity(content);
-  return (
-    identity.content_sha256 === plan.content_sha256 &&
-    identity.content_characters === plan.content_characters
-  );
-}
-
-export async function executeMemoryMutation(
-  value: unknown,
-  content: string | undefined,
-  operations: CoreOperations,
-  reader?: CoreReader,
-): Promise<MemoryFlowDocument> {
-  const plan = validatePlan(value);
-  if (!plan) return invalid("memory_plan_invalid");
-  if (!memoryPlanAcceptsContent(plan, content)) {
-    return invalid("memory_content_mismatch");
-  }
-  const { path, body } = operationRequest(plan, content);
-  const outcome = await operations.post<unknown>(path, body);
-  if (outcome.state === "rejected") {
-    return {
-      schema_version: 1,
-      product: PRODUCT,
-      state: "rejected",
-      operation_id: plan.request_id,
-      code: outcome.code,
-    };
-  }
-  if (outcome.state === "unknown") {
-    return reader
-      ? readMemoryMutationReceipt(reader, plan)
-      : pending(plan.request_id, outcome.code);
-  }
-  const memory = validateWriteResponse(outcome.data, plan);
-  if (!memory || !matchesReceipt(memory, plan, content)) {
-    return reader
-      ? readMemoryMutationReceipt(reader, plan)
-      : pending(plan.request_id, "memory_receipt_invalid");
-  }
-  return {
-    schema_version: 1,
-    product: PRODUCT,
-    state: "committed",
-    operation_id: plan.request_id,
-    receipt: {
-      memory_id: memory.memory_id,
-      status: memory.status,
-      origin: memory.origin,
-      revision: memory.revision,
-      scopes: memory.scopes,
-      evidence_ids: memory.evidence_ids,
-      content_sha256: contentIdentity(memory.content).content_sha256,
-      content_characters: [...memory.content].length,
-      created_at: memory.created_at,
-      updated_at: memory.updated_at,
-    },
-  };
-}
-
-/**
- * Validate the write response through the shared `parseMemoryReceipt`, which
- * owns the GovernedMemory shape and the revision/status binding Core must
- * satisfy. The CLI keeps only its own plan binding (`matchesReceipt`, which
- * also checks `origin`, `kind` and the echoed content), so the two surfaces
- * judge a write response identically and no shape rule is duplicated here.
- *
- * `add` creates the first revision and expects `confirmed`; the shared parser
- * derives that from `expectedRevision: 0`. Every other operation advances the
- * revision the caller acted against and expects `confirmed` (correct/scope)
- * or `deleted` (delete).
- */
-function validateWriteResponse(
-  value: unknown,
-  plan: MemoryMutationPlan,
-): GovernedMemory | null {
-  const expectedStatus = plan.operation === "delete" ? "deleted" : "confirmed";
-  // For `add` there is no id or prior revision to bind yet, so the parser's
-  // own receipt is the only source for both; the plan binding that follows is
-  // what proves the response belongs to this request.
-  const memoryId =
-    plan.operation === "add"
-      ? String((value as { memory_id?: unknown } | null)?.memory_id ?? "")
-      : (plan.memory_id as string);
-  if (memoryId === "") return null;
-  return parseMemoryReceipt(value, {
-    memoryId,
-    expectedRevision:
-      plan.operation === "add" ? 0 : (plan.expected_revision as number),
-    expectedStatus,
-  });
-}
-
-export async function readMemoryMutationReceipt(
-  reader: CoreReader,
-  value: unknown,
-): Promise<MemoryFlowDocument> {
-  const plan = validatePlan(value);
-  if (!plan) return invalid("memory_plan_invalid");
-  const outcome = await reader<unknown>(
-    `/api/v1/memory-mutations/${encodeURIComponent(plan.request_id)}`,
-  );
-  if (outcome.state !== "ok") {
-    return pending(plan.request_id, `memory_mutation_receipt_${outcome.code}`);
-  }
-  const receipt = validateMutationReceipt(outcome.data, plan);
-  if (receipt === "not_found") {
-    return pending(
-      plan.request_id,
-      "memory_mutation_receipt_not_found_after_attempt",
-    );
-  }
-  if (!receipt) {
-    return pending(plan.request_id, "memory_mutation_receipt_invalid");
-  }
-  return {
-    schema_version: 1,
-    product: PRODUCT,
-    state: "recovered",
-    operation_id: plan.request_id,
-    receipt,
-  };
-}
-
-export function memoryFlowExitCode(document: MemoryFlowDocument): number {
-  return ["preview", "committed", "recovered"].includes(document.state) ? 0 : 1;
-}
-
-export function renderMemoryFlowText(document: MemoryFlowDocument): string {
-  if (document.state === "preview") {
-    const plan = document.plan;
-    const lines = [
-      `记忆操作预览：${plan.operation}`,
-      `request_id：${plan.request_id}`,
-    ];
-    if (plan.memory_id) lines.push(`memory_id：${plan.memory_id}`);
-    if (plan.expected_revision) {
-      lines.push(
-        `当前版本：${plan.expected_revision}  状态：${plan.expected_status}  来源方式：${plan.expected_origin}`,
-      );
-    }
-    if (plan.scopes) lines.push(`使用范围：${plan.scopes.join(",")}`);
-    if (plan.current) {
-      for (const evidence of plan.current.evidence) {
-        lines.push(
-          `证据 ${evidence.evidence_id}：source=${evidence.source_id ?? "unknown"} author=${evidence.written_by ?? "unknown"} available=${evidence.available}`,
-        );
-      }
-    }
-    if (plan.content_characters !== undefined) {
-      lines.push(
-        `正文：${plan.content_characters} 字符，sha256=${plan.content_sha256}`,
-      );
-    }
-    lines.push("尚未写入；保存 JSON 计划后用 memories apply --confirm 执行。");
-    return `${lines.join("\n")}\n`;
-  }
-  if (document.state === "committed" || document.state === "recovered") {
-    return `记忆操作${document.state === "recovered" ? "已从治理回执恢复" : "已提交"}：${document.operation_id}\n${JSON.stringify(document.receipt)}\n`;
-  }
-  return `记忆操作未完成：${document.state}（${"code" in document ? document.code : "memory_operation_state_invalid"}）${document.operation_id ? ` request_id=${document.operation_id}` : ""}\n`;
-}
-
-function operationRequest(
-  plan: MemoryMutationPlan,
-  content: string | undefined,
-): { path: string; body: Record<string, unknown> } {
-  if (plan.operation === "add") {
-    // The shared create builder is the Web console's manual-add body, which
-    // always creates `chat` (the Web has no kind picker). The CLI exposes
-    // `--kind`, so it builds through the same builder and then sets the kind,
-    // keeping every other field (user_id/scope/evidence/origin) shared.
-    const request = buildMemoryCreateRequest(
-      {
-        content: content as string,
-        scopes: plan.scopes ?? [],
-        evidence_ids: plan.evidence_ids ?? [],
-        origin: "manual",
-      },
-      plan.request_id,
-    );
-    const draft = request.body.draft as Record<string, unknown>;
-    draft.kind = plan.memory_kind;
-    return { path: request.path, body: request.body };
-  }
-  if (plan.operation === "correct") {
-    return buildMemoryCorrectRequest(
-      plan.memory_id as string,
-      plan.expected_revision as number,
-      content as string,
-      undefined,
-      plan.request_id,
-    );
-  }
-  return buildMemoryActionRequest(
-    plan.memory_id as string,
-    plan.operation,
-    plan.expected_revision as number,
-    plan.request_id,
-  );
-}
-
-function matchesReceipt(
-  memory: GovernedMemory,
-  plan: MemoryMutationPlan,
-  content: string | undefined,
-): boolean {
-  if (plan.operation === "add") {
-    return (
-      memory.status === "confirmed" &&
-      memory.origin === "manual" &&
-      memory.revision === 1 &&
-      memory.kind === plan.memory_kind &&
-      same(memory.scopes, plan.scopes ?? []) &&
-      same(memory.evidence_ids, plan.evidence_ids ?? []) &&
-      memory.content === content
-    );
-  }
-  if (
-    memory.memory_id !== plan.memory_id ||
-    memory.revision !== (plan.expected_revision as number) + 1 ||
-    memory.origin !== plan.expected_origin
-  ) {
-    return false;
-  }
-  if (plan.operation === "delete" && memory.status !== "deleted") return false;
-  if (plan.operation === "correct" && memory.status !== plan.expected_status) {
-    return false;
-  }
-  if (plan.operation === "correct" && memory.content !== content) return false;
-  const expectedScopes =
-    plan.scopes ?? (plan.current?.scopes as string[] | undefined);
-  return expectedScopes ? same(memory.scopes, expectedScopes) : true;
-}
-
-function validateMutationReceipt(
-  value: unknown,
-  plan: MemoryMutationPlan,
-): Record<string, unknown> | "not_found" | null {
-  const receipt = record(value);
-  if (
-    !receipt ||
-    Object.keys(receipt).length !== MUTATION_RECEIPT_KEYS.size ||
-    Object.keys(receipt).some((key) => !MUTATION_RECEIPT_KEYS.has(key)) ||
-    receipt.schema_version !== 2 ||
-    receipt.request_id !== plan.request_id
-  ) {
-    return null;
-  }
-  if (receipt.state === "not_found") {
-    return [
-      receipt.operation,
-      receipt.memory_id,
-      receipt.result_revision,
-      receipt.result_status,
-      receipt.memory_state,
-      receipt.migrated_from,
-    ].every((item) => item === null)
-      ? "not_found"
-      : null;
-  }
-  const expectedOperation =
-    plan.operation === "add" ? "create" : plan.operation;
-  const expectedRevision =
-    plan.operation === "add" ? 1 : (plan.expected_revision as number) + 1;
-  const expectedStatus = plan.operation === "delete" ? "deleted" : "confirmed";
-  // A migrated receipt records an operation from before v2; no plan made
-  // today can have produced it.
-  if (
-    receipt.state !== "committed" ||
-    receipt.migrated_from !== null ||
-    receipt.operation !== expectedOperation ||
-    typeof receipt.memory_id !== "string" ||
-    !isMemoryId(receipt.memory_id) ||
-    (plan.memory_id !== undefined && receipt.memory_id !== plan.memory_id) ||
-    receipt.result_revision !== expectedRevision ||
-    receipt.result_status !== expectedStatus ||
-    !["present", "deleted"].includes(String(receipt.memory_state))
-  ) {
-    return null;
-  }
-  return {
-    schema_version: 2,
-    request_id: plan.request_id,
-    state: "committed",
-    operation: expectedOperation,
-    memory_id: receipt.memory_id,
-    result_revision: expectedRevision,
-    result_status: expectedStatus,
-    memory_state: receipt.memory_state,
-    proof_scope: "governance_transaction_only",
-    downstream_sync_verified: false,
-    payload_fingerprint_verified: false,
-  };
-}
-
-function validatePlan(value: unknown): MemoryMutationPlan | null {
-  const plan = record(value);
-  if (
-    plan?.schema_version !== 1 ||
-    plan.kind !== "memory_mutation" ||
-    !oneOf(plan.operation, OPERATIONS) ||
-    typeof plan.request_id !== "string" ||
-    !UUID.test(plan.request_id) ||
-    typeof plan.digest !== "string"
-  ) {
-    return null;
-  }
-  const body = { ...plan };
-  delete body.digest;
-  const expected = withDigest(body as unknown as PlanBody);
-  if (!safeEqual(expected.digest, plan.digest)) return null;
-  if (plan.operation === "add") {
-    if (
-      !oneOf(plan.memory_kind, MEMORY_KINDS) ||
-      !validScopes(plan.scopes) ||
-      !validIds(plan.evidence_ids, 500) ||
-      !contentFields(plan)
-    ) {
-      return null;
-    }
-  } else if (
-    typeof plan.memory_id !== "string" ||
-    !isMemoryId(plan.memory_id) ||
-    !Number.isSafeInteger(plan.expected_revision) ||
-    (plan.expected_revision as number) < 1 ||
-    plan.expected_status !== "confirmed" ||
-    !oneOf(plan.expected_origin, MEMORY_ORIGINS) ||
-    !validCurrent(plan) ||
-    (plan.operation === "correct" && !contentFields(plan))
-  ) {
-    return null;
-  }
-  return plan as unknown as MemoryMutationPlan;
-}
-
-function contentFields(plan: Record<string, unknown>): boolean {
-  return (
-    typeof plan.content_sha256 === "string" &&
-    /^[0-9a-f]{64}$/.test(plan.content_sha256) &&
-    Number.isSafeInteger(plan.content_characters) &&
-    (plan.content_characters as number) >= 1 &&
-    (plan.content_characters as number) <= CONTENT_MAX_CHARACTERS
-  );
-}
-
-function validCurrent(plan: Record<string, unknown>): boolean {
-  const current = record(plan.current);
-  if (
-    !current ||
-    current.status !== plan.expected_status ||
-    current.origin !== plan.expected_origin ||
-    current.revision !== plan.expected_revision ||
-    !validScopes(current.scopes) ||
-    !Array.isArray(current.evidence) ||
-    current.evidence.length < 1 ||
-    current.evidence.length > 500
-  ) {
-    return false;
-  }
-  return current.evidence.every((value) => {
-    const evidence = record(value);
-    return (
-      evidence !== null &&
-      typeof evidence.evidence_id === "string" &&
-      ID.test(evidence.evidence_id) &&
-      typeof evidence.available === "boolean" &&
-      (evidence.source_id === undefined ||
-        (typeof evidence.source_id === "string" &&
-          evidence.source_id.length <= 128)) &&
-      (evidence.written_by === undefined ||
-        (typeof evidence.written_by === "string" &&
-          evidence.written_by.length <= 256))
-    );
-  });
-}
-
-function contentIdentity(content: string): {
-  content_sha256: string;
-  content_characters: number;
-} {
-  return {
-    content_sha256: createHash("sha256").update(content, "utf8").digest("hex"),
-    content_characters: [...content].length,
-  };
-}
-
-function validContent(content: string): boolean {
-  return (
-    content.trim().length > 0 &&
-    [...content].length <= CONTENT_MAX_CHARACTERS &&
-    ![...content].some((character) => {
-      const code = character.charCodeAt(0);
-      return code <= 8 || (code >= 11 && code <= 31) || code === 127;
-    })
-  );
-}
-
-function validScopes(value: unknown): value is string[] {
-  if (
-    !Array.isArray(value) ||
-    value.length < 1 ||
-    value.length > 128 ||
-    new Set(value).size !== value.length ||
-    value.some(
-      (scope) =>
-        typeof scope !== "string" ||
-        scope.trim() !== scope ||
-        scope.length < 1 ||
-        scope.length > 512 ||
-        scope === "*",
-    )
-  ) {
-    return false;
-  }
-  return !value.includes("private") || value.length === 1;
-}
-
-function validIds(value: unknown, maximum: number): value is string[] {
-  return (
-    Array.isArray(value) &&
-    value.length >= 1 &&
-    value.length <= maximum &&
-    new Set(value).size === value.length &&
-    value.every((item) => typeof item === "string" && ID.test(item))
-  );
-}
-
-function withDigest(body: PlanBody): MemoryMutationPlan {
-  return {
-    ...body,
-    digest: createHash("sha256")
-      .update(JSON.stringify(body), "utf8")
-      .digest("hex"),
-  };
-}
-
-function preview(plan: MemoryMutationPlan): MemoryFlowDocument {
-  return {
-    schema_version: 1,
-    product: PRODUCT,
-    state: "preview",
-    plan,
-  };
-}
-
-function invalid(code: string): MemoryFlowDocument {
-  return {
-    schema_version: 1,
-    product: PRODUCT,
-    state: "invalid",
-    code,
-  };
-}
-
-function pending(operationId: string, code: string): MemoryFlowDocument {
-  return {
-    schema_version: 1,
-    product: PRODUCT,
-    state: "unknown",
-    operation_id: operationId,
-    code,
-  };
-}
-
-function same(left: readonly string[], right: readonly string[]): boolean {
-  return (
-    left.length === right.length &&
-    left.every((value, index) => value === right[index])
-  );
-}
-
-function safeEqual(left: string, right: string): boolean {
-  if (left.length !== right.length) return false;
-  return timingSafeEqual(Buffer.from(left), Buffer.from(right));
-}
-
-function oneOf<const T extends readonly string[]>(
-  value: unknown,
-  values: T,
-): value is T[number] {
-  return typeof value === "string" && values.includes(value as T[number]);
-}
-
-function record(value: unknown): Record<string, unknown> | null {
-  return value !== null && typeof value === "object" && !Array.isArray(value)
-    ? (value as Record<string, unknown>)
-    : null;
-}

memhub/apps/cli/src/memory-receipt-contract.test.ts

@@ -1,211 +0,0 @@
-import { readFileSync } from "node:fs";
-import { describe, expect, it } from "vitest";
-import type { CoreReader } from "./core-client.js";
-import {
-  planExistingMemoryMutation,
-  planMemoryAdd,
-  readMemoryMutationReceipt,
-} from "./memory-flows.js";
-
-// Written by a real Core and checked against it on the Core side, so these are
-// the receipts the CLI meets in use rather than ones shaped to fit the parser.
-const FIXTURE = JSON.parse(
-  readFileSync(
-    new URL(
-      "../../../packages/contracts/fixtures/memory-mutation-receipts.v2.json",
-      import.meta.url,
-    ),
-    "utf8",
-  ),
-) as { receipts: Record<"add" | "correct" | "delete", Receipt> };
-
-interface Receipt {
-  schema_version: number;
-  request_id: string;
-  memory_id: string;
-  result_revision: number;
-  result_status: string;
-  operation: string;
-}
-
-function reader(data: unknown): CoreReader {
-  return async <T>() => ({ state: "ok", data: data as T });
-}
-
-function detail(sample: Receipt) {
-  const revision = sample.result_revision - 1;
-  return {
-    memory: {
-      memory_id: sample.memory_id,
-      user_id: "local",
-      kind: "chat",
-      status: "confirmed",
-      content: "Synthetic memory.",
-      scopes: ["all-apps"],
-      evidence_ids: ["evidence-1"],
-      origin: "manual",
-      tags: [],
-      revision,
-      created_at: "2026-09-19T00:00:00Z",
-      updated_at: "2026-09-19T00:00:01Z",
-      deleted_at: null,
-    },
-    evidence: [
-      {
-        evidence_id: "evidence-1",
-        available: true,
-        source_id: "fixture",
-        written_by: "person",
-        created_at: "2026-09-19T00:00:00Z",
-        verbatim: "Synthetic source text.",
-      },
-    ],
-    history: [
-      {
-        revision,
-        action: "create",
-        status: "confirmed",
-        content: "Synthetic memory.",
-        scopes: ["all-apps"],
-        created_at: "2026-09-19T00:00:01Z",
-      },
-    ],
-    index_sync: null,
-  };
-}
-
-describe("memory mutation receipt v2 from Core", () => {
-  it("recovers an add from the receipt Core returns for a create", async () => {
-    const sample = FIXTURE.receipts.add;
-    expect(sample.schema_version).toBe(2);
-    const preview = planMemoryAdd({
-      content: "Synthetic memory.",
-      memoryKind: "chat",
-      scopes: ["all-apps"],
-      evidenceIds: ["evidence-1"],
-    });
-    if (preview.state !== "preview") throw new Error("preview expected");
-    // The request id is the one binding a receipt to its plan; the plan picks it.
-    const result = await readMemoryMutationReceipt(
-      reader({ ...sample, request_id: preview.plan.request_id }),
-      preview.plan,
-    );
-    expect(result).toMatchObject({
-      state: "recovered",
-      receipt: {
-        schema_version: 2,
-        operation: "create",
-        memory_id: sample.memory_id,
-        result_revision: 1,
-        result_status: "confirmed",
-        memory_state: "present",
-      },
-    });
-  });
-
-  it.each<["correct" | "delete", { content?: string }]>([
-    ["correct", { content: "Corrected synthetic memory." }],
-    ["delete", {}],
-  ])(
-    "recovers %s from the receipt Core returns for it",
-    async (operation, extra) => {
-      const sample = FIXTURE.receipts[operation];
-      const preview = await planExistingMemoryMutation(reader(detail(sample)), {
-        operation,
-        memoryId: sample.memory_id,
-        ...extra,
-      });
-      if (preview.state !== "preview") {
-        throw new Error(`preview expected: ${JSON.stringify(preview)}`);
-      }
-      const result = await readMemoryMutationReceipt(
-        reader({ ...sample, request_id: preview.plan.request_id }),
-        preview.plan,
-      );
-      expect(result).toMatchObject({
-        state: "recovered",
-        receipt: {
-          schema_version: 2,
-          operation: sample.operation,
-          memory_id: sample.memory_id,
-          result_revision: sample.result_revision,
-          result_status: sample.result_status,
-        },
-      });
-    },
-  );
-
-  it("does not take a v1 receipt for a v2 one", async () => {
-    const sample = FIXTURE.receipts.delete;
-    const preview = await planExistingMemoryMutation(reader(detail(sample)), {
-      operation: "delete",
-      memoryId: sample.memory_id,
-    });
-    if (preview.state !== "preview") throw new Error("preview expected");
-    const { migrated_from: _dropped, ...v1 } = sample as Receipt & {
-      migrated_from: null;
-    };
-    // As v1 was, and with v2's fields but v1's number: either alone is refused.
-    for (const receipt of [
-      { ...v1, schema_version: 1 },
-      { ...sample, schema_version: 1 },
-    ]) {
-      const result = await readMemoryMutationReceipt(
-        reader({ ...receipt, request_id: preview.plan.request_id }),
-        preview.plan,
-      );
-      expect(result).toMatchObject({
-        state: "unknown",
-        code: "memory_mutation_receipt_invalid",
-      });
-    }
-  });
-
-  it("does not take a not-found receipt that names a migrated operation", async () => {
-    const sample = FIXTURE.receipts.delete;
-    const preview = await planExistingMemoryMutation(reader(detail(sample)), {
-      operation: "delete",
-      memoryId: sample.memory_id,
-    });
-    if (preview.state !== "preview") throw new Error("preview expected");
-    const notFound = {
-      schema_version: 2,
-      request_id: preview.plan.request_id,
-      state: "not_found",
-      operation: null,
-      memory_id: null,
-      result_revision: null,
-      result_status: null,
-      memory_state: null,
-    };
-    expect(
-      await readMemoryMutationReceipt(
-        reader({ ...notFound, migrated_from: null }),
-        preview.plan,
-      ),
-    ).toMatchObject({
-      code: "memory_mutation_receipt_not_found_after_attempt",
-    });
-    expect(
-      await readMemoryMutationReceipt(
-        reader({ ...notFound, migrated_from: "reject" }),
-        preview.plan,
-      ),
-    ).toMatchObject({ code: "memory_mutation_receipt_invalid" });
-  });
-
-  it("plans nothing on a memory that is not in effect", async () => {
-    const sample = FIXTURE.receipts.delete;
-    const superseded = detail(sample);
-    superseded.memory.status = "superseded";
-    superseded.history[0].status = "superseded";
-    const result = await planExistingMemoryMutation(reader(superseded), {
-      operation: "delete",
-      memoryId: sample.memory_id,
-    });
-    expect(result).toMatchObject({
-      state: "invalid",
-      code: "memory_operation_not_allowed",
-    });
-  });
-});

memhub/apps/cli/src/memory-report.ts

@@ -15,6 +15,29 @@ export function isMemoryId(value: string): boolean {
   );
 }
 
+const CONTENT_MAX_CHARACTERS = 100_000;
+
+/** A memory body read from `--content-file`: UTF-8, non-blank, bounded, and
+ * free of control characters other than tab and newline. */
+export function parseMemoryContent(bytes: Buffer): string | null {
+  if (bytes.byteLength > CONTENT_MAX_CHARACTERS * 4 + 2) return null;
+  let decoded: string;
+  try {
+    decoded = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    return null;
+  }
+  const content = decoded.replace(/\r?\n$/, "");
+  return content.trim().length > 0 &&
+    [...content].length <= CONTENT_MAX_CHARACTERS &&
+    ![...content].some((character) => {
+      const code = character.charCodeAt(0);
+      return code <= 8 || (code >= 11 && code <= 31) || code === 127;
+    })
+    ? content
+    : null;
+}
+
 export interface MemoryQuery {
   query?: string;
   status?: string;

memhub/apps/cli/src/read-only-queries.test.ts

@@ -184,8 +184,16 @@ const CORE = new Map<string, { status: number; data: unknown }>([
     },
   ],
   [
-    "/api/v1/home-summary",
-    { status: 200, data: { memory_count: 42, latest: null, observed_at: "T" } },
+    "/api/v2/home-summary",
+    {
+      status: 200,
+      data: {
+        schema_version: 2,
+        memory_count: 42,
+        latest: null,
+        observed_at: "T",
+      },
+    },
   ],
 ]);
 
@@ -194,9 +202,7 @@ const READ_ONLY_PATHS = [
   "/api/v1/live-sync",
   "/api/v1/memory-processing",
   "/api/v1/model-profiles",
-  "/api/v1/home-summary",
-  "/api/v1/memory-library",
-  "/api/v1/memories/",
+  "/api/v2/home-summary",
   "/api/v2/memory-library",
   "/api/v2/memories/",
   "/api/v2/user-profile",
@@ -816,7 +822,7 @@ describe("CLI-21 memory reads", () => {
     expect(report.history).toEqual([]);
   });
 
-  // Core registers /api/v1/memories/graph before /{memory_id}, and that static
+  // Core registers /api/v2/memories/graph before /{memory_id}, and that static
   // handler initializes the HY bridge. A memory id that collides with a
   // reserved segment must never become a request.
   it("refuses a memory id that collides with a static Core route", async () => {
@@ -830,18 +836,15 @@ describe("CLI-21 memory reads", () => {
       expect(streams.stdout()).toBe("");
     }
     expect(transport.get).not.toHaveBeenCalled();
-    expect(isReadOnlyPath("/api/v1/memories/graph")).toBe(false);
-    expect(isReadOnlyPath("/api/v1/memories/ask")).toBe(false);
-    expect(isReadOnlyPath("/api/v1/memories/m1")).toBe(true);
-    expect(isReadOnlyPath("/api/v2/memory-library")).toBe(true);
+    expect(isReadOnlyPath("/api/v2/memories/graph")).toBe(false);
+    expect(isReadOnlyPath("/api/v2/memories/ask")).toBe(false);
     expect(isReadOnlyPath("/api/v2/memories/m1")).toBe(true);
+    expect(isReadOnlyPath("/api/v2/memory-library")).toBe(true);
+    expect(isReadOnlyPath("/api/v2/home-summary")).toBe(true);
+    // The retired v1 data plane is no longer a CLI read.
+    expect(isReadOnlyPath("/api/v1/memories/m1")).toBe(false);
+    expect(isReadOnlyPath("/api/v1/home-summary")).toBe(false);
     expect(isReadOnlyPath("/api/v1/model-content-permission")).toBe(false);
-    expect(
-      isReadOnlyPath(
-        "/api/v1/memory-mutations/123e4567-e89b-12d3-a456-426614174000",
-      ),
-    ).toBe(true);
-    expect(isReadOnlyPath("/api/v1/memory-mutations/../sources")).toBe(false);
   });
 
   it("refuses a memory id that would escape the memories path", async () => {
@@ -861,6 +864,26 @@ describe("CLI-21 memory reads", () => {
 // was cast to the expected type, so a wrong record, an unavailable excerpt, an
 // oversized page and a non-string model field all reached stdout as success.
 describe("malformed success responses", () => {
+  it("treats a v1-shaped home summary as invalid, not as a memory count", async () => {
+    transport.get.mockImplementation(async (url: string) =>
+      url === "/api/v2/home-summary"
+        ? {
+            status: 200,
+            data: { memory_count: 7, latest: null, observed_at: "T" },
+          }
+        : (CORE.get(url) ?? { status: 404, data: { detail: "not_found" } }),
+    );
+    const streams = captureStreams();
+    try {
+      await run(["status", "--json"], {});
+    } finally {
+      streams.restore();
+    }
+    expect(JSON.parse(streams.stdout()).sections.memories).toMatchObject({
+      state: "invalid",
+    });
+  });
+
   it("refuses a detail that is not the memory that was asked for", async () => {
     transport.get.mockResolvedValue({
       status: 200,

memhub/apps/cli/src/service-lifecycle.test.ts

@@ -315,6 +315,40 @@ describe("macOS service lifecycle", () => {
     expect(deps.verifyRegistrationSnapshot).toHaveBeenCalledTimes(2);
   });
 
+  it("does not re-bootstrap a previous registration that may serve a legacy home", async () => {
+    const f = fixture();
+    const oldPath = "/Users/example/Library/LaunchAgents/old-runtime.plist";
+    const runCommand = vi
+      .fn()
+      .mockResolvedValueOnce(undefined)
+      .mockRejectedValueOnce(new Error("bootstrap failed"));
+    const deps = dependencies({
+      inspectRegistration: vi.fn(async () => ({
+        kind: "managed" as const,
+        plistPath: oldPath,
+        content: "old managed plist",
+      })),
+      runCommand,
+    });
+
+    const prepared = await prepareServiceInstall(f.layout, f.options, deps);
+    await expect(
+      applyPreparedServiceInstall(
+        { ...prepared, restorePreviousOnFailure: false },
+        deps,
+      ),
+    ).rejects.toThrow("runtime_service_replacement_failed");
+
+    // bootout + the failed bootstrap only; the old plist is not bootstrapped.
+    expect(runCommand).toHaveBeenCalledTimes(2);
+    expect(runCommand).not.toHaveBeenCalledWith([
+      "launchctl",
+      "bootstrap",
+      "gui/501",
+      oldPath,
+    ]);
+  });
+
   it("removes the replacement plist and restores the previous registration", async () => {
     const f = fixture();
     const oldPath = "/Users/example/Library/LaunchAgents/old-runtime.plist";

memhub/apps/cli/src/service-lifecycle.ts

@@ -72,6 +72,13 @@ export type PreparedServiceInstall = {
   mode: "direct" | "bootstrap-existing" | "restart" | "replace";
   previous?: ManagedSnapshot;
   previouslyEnabled: boolean;
+  /**
+   * Re-bootstrap the previous (possibly older) LaunchAgent when the new one
+   * fails to bootstrap. `install` turns this off once the home has been handed
+   * to this version's SDK migration: an older Runtime has no migration gate and
+   * would serve a home that is not on SDK authority.
+   */
+  restorePreviousOnFailure?: boolean;
 };
 
 const defaultDependencies: ServiceLifecycleDependencies = {
@@ -191,7 +198,8 @@ export async function applyPreparedServiceInstall(
     if (!previous) throw new Error("runtime_service_upgrade_state_invalid");
     await verifyPreparedRegistration(prepared, dependencies);
     const domain = launchdDomain(options.uid);
-    let replacementFailure: "upgrade" | "rollback" | null = null;
+    let replacementFailure: "upgrade" | "rollback" | "not-restored" | null =
+      null;
     const replaceCommand: ServiceCommandRunner = async (command) => {
       if (command[0] !== "launchctl" || command[1] !== "bootstrap") {
         await dependencies.runCommand(command);
@@ -208,6 +216,10 @@ export async function applyPreparedServiceInstall(
         await dependencies.runCommand(command);
       } catch {
         replacementFailure = "upgrade";
+        if (prepared.restorePreviousOnFailure === false) {
+          replacementFailure = "not-restored";
+          throw new Error("runtime_service_replacement_failed");
+        }
         try {
           await dependencies.verifyRegistrationSnapshot(previous);
           await dependencies.runCommand([
@@ -234,6 +246,9 @@ export async function applyPreparedServiceInstall(
       if (replacementFailure === "upgrade") {
         throw new Error("runtime_service_managed_upgrade_failed");
       }
+      if (replacementFailure === "not-restored") {
+        throw new Error("runtime_service_replacement_failed");
+      }
       throw error;
     }
   } catch (error) {

memhub/apps/cli/src/source-progress-report.ts

@@ -7,12 +7,10 @@ import type {
 } from "@one-memory/contracts";
 import type { CoreReader, ReadOutcome } from "./core-client.js";
 import {
-  type ValidatedMemoryTask,
   validateImportIssues,
   validateImportJob,
   validateImportJobs,
   validateLiveSync,
-  validateMemoryTasks,
   validateProcessing,
   validateSources,
 } from "./core-responses.js";
@@ -70,11 +68,6 @@ export interface ProgressDocument {
   generation: {
     summary_state: ReadState;
     summary: Record<string, unknown> | null;
-    tasks_state: ReadState;
-    tasks: Array<Record<string, unknown>>;
-    returned: number;
-    validated: number;
-    output_truncated: boolean;
   };
 }
 
@@ -134,12 +127,13 @@ export async function readProgress(
   const importsPath = options.jobId
     ? `/api/v1/import-jobs/${options.jobId}`
     : "/api/v1/import-jobs";
-  const [importsRead, sourcesRead, processingRead, tasksRead, issuesRead] =
+  // Generation progress comes from `memory-processing` alone: under SDK
+  // authority the per-task list (`/api/v1/memory-tasks`) is retired and empty.
+  const [importsRead, sourcesRead, processingRead, issuesRead] =
     await Promise.all([
       reader<unknown>(importsPath),
       reader<unknown>("/api/v1/sources"),
       reader<unknown>("/api/v1/memory-processing"),
-      reader<unknown>("/api/v1/memory-tasks"),
       options.jobId && options.issues
         ? reader<unknown>(`/api/v1/import-jobs/${options.jobId}/issues`)
         : Promise.resolve(null),
@@ -153,7 +147,6 @@ export async function readProgress(
     : validated(importsRead, validateImportJobs);
   const processing = validated(processingRead, validateProcessing);
   const sources = validated(sourcesRead, validateSources);
-  const tasks = validated(tasksRead, validateMemoryTasks);
   const issues =
     options.jobId && options.issues && issuesRead
       ? validated(issuesRead, (value) =>
@@ -162,25 +155,19 @@ export async function readProgress(
       : null;
 
   const jobs = imports.state === "ok" ? imports.data : [];
-  const taskItems = tasks.state === "ok" ? tasks.data : [];
   const issueItems = issues?.state === "ok" ? issues.data : [];
   const importState = stateOnly(imports);
   const summaryState = stateOnly(processing);
-  const tasksState = stateOnly(tasks);
 
   const hasReadFailure =
     importState.state !== "ok" ||
     sources.state !== "ok" ||
     summaryState.state !== "ok" ||
-    tasksState.state !== "ok" ||
     (issues !== null && issues.state !== "ok");
   const hasProblem =
     jobs.some((job) =>
       ["paused", "interrupted", "failed"].includes(job.status),
     ) ||
-    taskItems.some((task) =>
-      ["waiting_for_model", "failed"].includes(task.status),
-    ) ||
     (processing.state === "ok" &&
       (processing.data.failed > 0 ||
         processing.data.waiting_for_model > 0 ||
@@ -188,7 +175,6 @@ export async function readProgress(
     issueItems.length > 0;
   const hasActive =
     jobs.some((job) => ["pending", "running"].includes(job.status)) ||
-    taskItems.some((task) => ["pending", "running"].includes(task.status)) ||
     (processing.state === "ok" &&
       (processing.data.pending > 0 || processing.data.running > 0));
 
@@ -229,11 +215,6 @@ export async function readProgress(
       summary_state: summaryState,
       summary:
         processing.state === "ok" ? projectProcessing(processing.data) : null,
-      tasks_state: tasksState,
-      tasks: taskItems.slice(0, options.limit).map(projectTask),
-      returned: Math.min(taskItems.length, options.limit),
-      validated: taskItems.length,
-      output_truncated: taskItems.length > options.limit,
     },
   };
 }
@@ -289,10 +270,7 @@ export function renderProgressText(document: ProgressDocument): string {
       ? `记忆整理：待处理 ${document.generation.summary.pending} · 进行中 ${document.generation.summary.running} · 等待模型 ${document.generation.summary.waiting_for_model} · 失败 ${document.generation.summary.failed}`
       : "记忆整理：暂时无法读取",
   );
-  if (
-    document.imports.output_truncated ||
-    document.generation.output_truncated
-  ) {
+  if (document.imports.output_truncated) {
     lines.push("这里只显示汇总；完整记录请使用 --json。");
   }
   lines.push("");
@@ -353,11 +331,6 @@ export function unreadProgress(
     generation: {
       summary_state: failed,
       summary: null,
-      tasks_state: failed,
-      tasks: [],
-      returned: 0,
-      validated: 0,
-      output_truncated: false,
     },
   };
 }
@@ -465,7 +438,3 @@ function projectProcessing(
     })),
   };
 }
-
-function projectTask(task: ValidatedMemoryTask): Record<string, unknown> {
-  return { ...task };
-}

memhub/apps/cli/src/source-progress.test.ts

@@ -129,18 +129,6 @@ const RESPONSES = new Map<string, { status: number; data: unknown }>([
       },
     },
   ],
-  [
-    "/api/v1/memory-tasks",
-    {
-      status: 200,
-      data: [
-        memoryTask("task-pending", "pending"),
-        memoryTask("task-running", "running"),
-        memoryTask("task-model", "waiting_for_model", "model_missing"),
-        memoryTask("task-failed", "failed", "provider_unavailable"),
-      ],
-    },
-  ],
   [
     "/api/v1/import-jobs/job-running",
     { status: 200, data: importJob("job-running", "running") },
@@ -282,9 +270,9 @@ describe("CLI-19 progress and issue reads", () => {
       imported_messages: 20,
       totals_state: { state: "ok" },
     });
-    expect(
-      report.generation.tasks.map((task: { status: string }) => task.status),
-    ).toEqual(["pending", "running", "waiting_for_model", "failed"]);
+    // The retired per-task list is no longer read or reported.
+    expect(report.generation).not.toHaveProperty("tasks");
+    expect(requestedPaths()).not.toContain("/api/v1/memory-tasks");
     expect(streams.stdout()).not.toMatch(/percent|percentage|%/i);
   });
 
@@ -374,7 +362,7 @@ describe("CLI-19 progress and issue reads", () => {
     expect(streams.stdout()).not.toContain("SYNTHETIC_FOREIGN_ISSUE");
   });
 
-  it("bounds each task list and emits an explicit truncation receipt", async () => {
+  it("bounds the import job list and emits an explicit truncation receipt", async () => {
     const streams = captureStreams();
     try {
       expect(await run(["progress", "--limit", "1", "--json"], {})).toBe(1);
@@ -388,12 +376,6 @@ describe("CLI-19 progress and issue reads", () => {
       validated: 3,
       output_truncated: true,
     });
-    expect(report.generation.tasks).toHaveLength(1);
-    expect(report.generation).toMatchObject({
-      returned: 1,
-      validated: 4,
-      output_truncated: true,
-    });
   });
 
   it("streams bounded progress snapshots as serial NDJSON", async () => {
@@ -428,7 +410,6 @@ describe("CLI-19 progress and issue reads", () => {
       "/api/v1/import-jobs",
       "/api/v1/sources",
       "/api/v1/memory-processing",
-      "/api/v1/memory-tasks",
     ]) {
       expect(requestedPaths().filter((item) => item === path)).toHaveLength(2);
     }
@@ -500,7 +481,7 @@ describe("CLI-19 progress and issue reads", () => {
   it("preserves denied, unavailable and malformed sections in one partial report", async () => {
     transport.get.mockImplementation(async (url: string) => {
       if (url === "/api/v1/import-jobs") return { status: 503, data: {} };
-      if (url === "/api/v1/memory-tasks") return { status: 403, data: {} };
+      if (url === "/api/v1/sources") return { status: 403, data: {} };
       if (url === "/api/v1/memory-processing") {
         return { status: 200, data: { pending: { secret: "nested" } } };
       }
@@ -521,7 +502,7 @@ describe("CLI-19 progress and issue reads", () => {
       state: "invalid",
       code: "response_invalid",
     });
-    expect(report.generation.tasks_state).toEqual({
+    expect(report.imports.totals_state).toEqual({
       state: "denied",
       code: "http_403",
     });
@@ -574,7 +555,6 @@ describe("CLI-19 progress and issue reads", () => {
           "/api/v1/live-sync",
           "/api/v1/import-jobs",
           "/api/v1/memory-processing",
-          "/api/v1/memory-tasks",
         ].some((allowed) => path === allowed || path.startsWith(`${allowed}/`)),
       ),
     ).toBe(true);
@@ -634,28 +614,6 @@ function importJob(
   };
 }
 
-function memoryTask(
-  taskId: string,
-  status: string,
-  error: string | null = null,
-) {
-  return {
-    task_id: taskId,
-    request_id: `request-${taskId}`,
-    user_id: "local",
-    kind: "extract",
-    input_ref: "synthetic",
-    status,
-    profile_id: "profile-1",
-    profile_revision: 1,
-    profile_snapshot: {},
-    attempts: status === "failed" ? 2 : 0,
-    last_error_code: error,
-    created_at: "T1",
-    updated_at: "T2",
-  };
-}
-
 function requestedPaths(): string[] {
   return (transport.get.mock.calls as [string][]).map(([path]) => path);
 }

memhub/apps/cli/src/status-report.test.ts

@@ -1,6 +1,11 @@
 import { describe, expect, it } from "vitest";
 
-import { renderStatusText, type StatusDocument } from "./status-report.js";
+import { composeDoctorReport, renderDoctorText } from "./doctor-report.js";
+import {
+  composeStatusReport,
+  renderStatusText,
+  type StatusDocument,
+} from "./status-report.js";
 
 describe("status default output", () => {
   it("formats blocked task objects recursively instead of printing object coercions", () => {
@@ -35,3 +40,40 @@ describe("status default output", () => {
     );
   });
 });
+
+describe("status and doctor on an unfinished upgrade migration", () => {
+  it("names the migration log and the issues page", async () => {
+    const report = await composeStatusReport({
+      dataDir: "/tmp/isolated/.one-memory",
+      runtime: { state: "stopped", code: "sdk_migration_required" },
+      background: null,
+      reader: null,
+    });
+
+    expect(report.runtime.log_file).toBe(
+      "/tmp/isolated/.one-memory/logs/sdk-migration.log",
+    );
+    expect(report.runtime.issues_url).toBe(
+      "https://github.com/Tencent-Hunyuan/Hy-Memory/issues/new",
+    );
+    const text = renderStatusText(report, "MemHub");
+    expect(text).toContain("sdk_migration_required");
+    expect(text).toContain("/tmp/isolated/.one-memory/logs/sdk-migration.log");
+
+    const doctor = renderDoctorText(composeDoctorReport(report, null));
+    expect(doctor).toContain(
+      "/tmp/isolated/.one-memory/logs/sdk-migration.log",
+    );
+    expect(doctor).not.toContain("帮助与诊断");
+  });
+
+  it("adds no log path for an ordinary stopped runtime", async () => {
+    const report = await composeStatusReport({
+      dataDir: "/tmp/isolated/.one-memory",
+      runtime: { state: "stopped", code: "runtime_not_running" },
+      background: null,
+      reader: null,
+    });
+    expect(report.runtime.log_file).toBeUndefined();
+  });
+});

memhub/apps/cli/src/status-report.ts

@@ -1,5 +1,4 @@
 import type {
-  HomeSummary,
   LiveSyncHealth,
   MemoryProcessingSummary,
   ModelProfile,
@@ -9,8 +8,10 @@ import type {
   BackgroundHealth,
   RuntimeStatus,
 } from "@one-memory/runtime-control";
+import { sdkMigrationLogPath } from "@one-memory/runtime-control";
 import type { CoreReader, ReadOutcome } from "./core-client.js";
 import {
+  type SdkHomeSummary,
   validateHomeSummary,
   validateLiveSync,
   validateModelProfiles,
@@ -19,6 +20,9 @@ import {
 } from "./core-responses.js";
 import { PRODUCT } from "./version.js";
 
+const MIGRATION_ISSUES_URL =
+  "https://github.com/Tencent-Hunyuan/Hy-Memory/issues/new";
+
 export type SectionState =
   | "ok"
   | "denied"
@@ -42,6 +46,9 @@ export interface StatusDocument {
     host?: string;
     port?: number;
     version?: string;
+    /** Set only when an unfinished upgrade migration is why nothing serves. */
+    log_file?: string;
+    issues_url?: string;
   };
   bridge: {
     state: BackgroundHealth["state"] | "not_checked";
@@ -102,7 +109,7 @@ export async function composeStatusReport(options: {
       reader<unknown>("/api/v1/live-sync"),
       reader<unknown>("/api/v1/memory-processing"),
       reader<unknown>("/api/v1/model-profiles"),
-      reader<unknown>("/api/v1/home-summary"),
+      reader<unknown>("/api/v2/home-summary"),
     ]);
     sections.sources = section(sources, validateSources, describeSources);
     sections.sync = section(sync, validateLiveSync, describeSync);
@@ -153,6 +160,12 @@ export async function composeStatusReport(options: {
       host: options.runtime.host,
       port: options.runtime.port,
       version: options.runtime.version,
+      ...(options.runtime.code.startsWith("sdk_migration_")
+        ? {
+            log_file: sdkMigrationLogPath(options.dataDir),
+            issues_url: MIGRATION_ISSUES_URL,
+          }
+        : {}),
     },
     bridge,
     sections,
@@ -177,6 +190,13 @@ export function renderStatusText(
 ): string {
   const lines = [
     `${heading}：${runtimeLine(report)}`,
+    ...(report.runtime.log_file
+      ? [
+          `升级迁移没有完成（错误码：${report.runtime.code}），MemHub 不会启动。`,
+          `请把迁移日志附在 GitHub 反馈里发给我们：${report.runtime.log_file}`,
+          `反馈地址：${report.runtime.issues_url}`,
+        ]
+      : []),
     `资料空间：${report.data_dir}`,
     `应用连接：${BRIDGE_LABELS[report.bridge.state]}`,
   ];
@@ -347,7 +367,7 @@ function describeModel(profiles: ModelProfile[]): Record<string, unknown> {
   };
 }
 
-function describeMemories(summary: HomeSummary): Record<string, unknown> {
+function describeMemories(summary: SdkHomeSummary): Record<string, unknown> {
   return {
     memory_count: summary.memory_count,
   };

memhub/apps/core/pyproject.toml

@@ -13,7 +13,8 @@ dependencies = [
     "filelock>=3.32.4",
     # Public SDK version validated against MemHub's permission and recall contracts.
     "hy-memory==2.0.5",
-    # Retrieval's derived vector index directly consumes these locked versions.
+    # chromadb arrives through the HY SDK; locked here so an unrelated upgrade
+    # cannot move the SDK's store. Built-in embedding consumes numpy directly.
     "chromadb==1.5.9",
     "numpy==2.5.2",
     "httpx>=0.28.1",

memhub/apps/core/src/one_memory/call_event_recorder.py

@@ -15,7 +15,7 @@ from one_memory.call_event_store import (
     CallTool,
     HostId,
 )
-from one_memory.context_models import ContextSearchResponse, MemoryContextItem, RawContextItem
+from one_memory.context_models import SdkContextSearchResponse
 from one_memory.external_memory_access import ExternalMemoryAccess
 from one_memory.recall import RecallReceipt
 
@@ -41,75 +41,27 @@ def _host_id(access: ExternalMemoryAccess | None) -> HostId | None:
     return cast(HostId, host) if host in HOSTS else None
 
 
-def context_call_event(
-    result: ContextSearchResponse,
+def sdk_context_call_event(
+    result: SdkContextSearchResponse,
     access: ExternalMemoryAccess | None,
+    *,
+    memory_searched: bool,
+    timed_out: bool,
 ) -> CallEvent:
-    references: list[CallReference] = []
-    seen: set[tuple[str, str, int]] = set()
-    for item in result.items:
-        if isinstance(item, RawContextItem):
-            candidates = [
-                CallReference(
-                    kind="raw",
-                    id=message.evidence_id,
-                    revision=message.revision,
-                    source_id=item.source_id,
-                )
-                for message in item.messages
-            ]
-        elif isinstance(item, MemoryContextItem):
-            candidates = [
-                CallReference(
-                    kind="memory", id=item.memory_id, revision=item.revision, source_id=None
-                )
-            ]
-        else:
-            continue
-        for reference in candidates:
-            identity = (reference.kind, reference.id, reference.revision)
-            if identity not in seen:
-                seen.add(identity)
-                references.append(reference)
-    timed_out = any(
-        path.reason == "timeout_budget" for path in (result.paths.raw, result.paths.memory)
+    # SDK items carry no Evidence/Governance revision, and the reference
+    # resolver reads the legacy store, so the event records counts only.
+    raw_count = sum(item.kind == "raw" for item in result.items)
+    memory_count = sum(item.kind == "memory" for item in result.items)
+    state: CallState = "timed_out" if timed_out else result.state
+    return _metadata_event(
+        tool="om_recall" if memory_searched else "om_conversations",
+        state=state,
+        elapsed_ms=result.total_ms,
+        access=access,
+        raw_count=raw_count,
+        memory_count=memory_count,
+        event_id=UUID(result.request_id),
     )
-    state: CallState = (
-        "partial" if timed_out and references else "timed_out" if timed_out else result.state
-    )
-    return CallEvent.model_validate(
-        {
-            "event_id": UUID(result.request_id),
-            "occurred_at": datetime.now(UTC),
-            "host_id": _host_id(access),
-            "installation_id": UUID(access.installation_id) if access else None,
-            "tool": _context_tool(result),
-            "state": state,
-            "stage": "core_result",
-            "delivery": "unknown",
-            "adoption": "unknown",
-            "host_session_id": None,
-            "injection_elapsed_ms": None,
-            "elapsed_ms": result.total_ms,
-            "raw_count": sum(isinstance(item, RawContextItem) for item in result.items),
-            "memory_count": sum(isinstance(item, MemoryContextItem) for item in result.items),
-            "references": tuple(references),
-        }
-    )
-
-
-def record_context_result(
-    store: CallEventStore,
-    result: ContextSearchResponse,
-    access: ExternalMemoryAccess | None,
-) -> None:
-    store.record(context_call_event(result, access))
-
-
-def _context_tool(result: ContextSearchResponse) -> CallTool:
-    if result.paths.memory.status not in {"not_requested", "not_authorized"}:
-        return "om_recall"
-    return "om_conversations"
 
 
 def _metadata_event(
@@ -142,26 +94,6 @@ def _metadata_event(
     )
 
 
-def conversation_call_event(
-    result: object,
-    access: ExternalMemoryAccess | None,
-    elapsed_ms: float,
-) -> CallEvent:
-    hits = tuple(getattr(result, "hits", ()) or ())
-    conversations = {
-        conversation_id
-        for hit in hits
-        if (conversation_id := getattr(hit, "conversation_id", None))
-    }
-    return _metadata_event(
-        tool="om_conversations",
-        state="grounded" if hits else "empty",
-        elapsed_ms=elapsed_ms,
-        access=access,
-        raw_count=min(len(conversations), 20),
-    )
-
-
 def ask_call_event(
     result: object,
     access: ExternalMemoryAccess | None,
@@ -255,8 +187,9 @@ def record_legacy_result(
             host_session_id=None,
             injection_elapsed_ms=None,
             elapsed_ms=elapsed_ms,
-            raw_count=0,
-            memory_count=len(receipt.hits),
+            # A raw-fallback recall returned conversation excerpts, not memories.
+            raw_count=len(receipt.hits) if receipt.mode == "raw" else 0,
+            memory_count=0 if receipt.mode == "raw" else len(receipt.hits),
             references=(),
         )
     )

memhub/apps/core/src/one_memory/cli.py

@@ -1,6 +1,5 @@
 import os
 import signal
-import socket
 import sys
 
 # A handed-off capture ends itself: the hook that gave it the prompt has
@@ -29,10 +28,13 @@ def _end_by(seconds: str | None) -> None:
 if __name__ == "__main__" and sys.argv[1:2] == ["capture"]:
     _end_by(os.environ.get("ONE_MEMORY_CAPTURE_DEADLINE_S"))
 
+import contextlib  # noqa: E402
 import errno  # noqa: E402
 import json  # noqa: E402
 import re  # noqa: E402
+import time  # noqa: E402
 from collections.abc import Iterator, Sequence  # noqa: E402
+from pathlib import Path  # noqa: E402
 from typing import TextIO  # noqa: E402
 
 from one_memory.config import load_settings  # noqa: E402
@@ -68,6 +70,9 @@ def migration_failure_code(
             return "sdk_migration_disk_space_insufficient"
     for item in chain:
         code = getattr(item, "code", "")
+        # `sdk_data_plane_write_job_input_missing:<job_id>`: the name is the
+        # code; the id is for the log, not for the dialog.
+        code = code.split(":", 1)[0] if isinstance(code, str) else code
         if not isinstance(code, str) or not _SAFE_MIGRATION_CODE.match(code):
             continue
         if code.startswith(("sdk_data_plane_", "sdk_migration_")):
@@ -103,12 +108,8 @@ def run(arguments: Sequence[str], *, output: TextIO | None = None) -> int:
     if not arguments or list(arguments) in (
         ["serve"],
         ["serve", "--maintenance"],
-        ["serve", "--reader"],
     ):
-        serve(
-            maintenance=list(arguments) == ["serve", "--maintenance"],
-            reader=list(arguments) == ["serve", "--reader"],
-        )
+        serve(maintenance=list(arguments) == ["serve", "--maintenance"])
         return 0
     command, *options = arguments
     if command == "restore":
@@ -117,29 +118,17 @@ def run(arguments: Sequence[str], *, output: TextIO | None = None) -> int:
         return sdk_migrate(options, stream)
     if command == "sdk-migration-status":
         return sdk_migration_status(options, stream)
-    if command == "boundary" and not options:
-        from one_memory.workbuddy_boundary import write_hook
-
-        return write_hook(stream, sys.stdin)
-    if command == "boundary" and options == ["--peek"]:
-        from one_memory.workbuddy_boundary import write_peek
-
-        return write_peek(stream, sys.stdin)
-    if command == "boundary" and len(options) == 2 and options[0] == "--ack":
-        from one_memory.workbuddy_boundary import run_confirm
-
-        return run_confirm(options[1])
     if command == "capture" and len(options) == 1:
         from one_memory.live_capture import capture_stdio
 
         return capture_stdio(options[0], sys.stdin, stream)
     if command not in {"status", "doctor"} or options not in ([], ["--json"]):
         stream.write(
-            "Usage: one-memory [serve [--maintenance|--reader]|status [--json]|doctor [--json]"
+            "Usage: one-memory [serve [--maintenance]|status [--json]|doctor [--json]"
             "|restore --source <managed-backup> --yes [--json]"
             "|sdk-migrate --runtime-build <build> --yes [--json]"
             "|sdk-migration-status [--json]"
-            "|boundary [--peek|--ack TOKEN]|capture SOURCE]\n"
+            "|capture SOURCE]\n"
         )
         return 2
 
@@ -312,7 +301,22 @@ def sdk_migrate(options: Sequence[str], stream: TextIO) -> int:
         stream.write("one-memory: sdk-migrate 需要 --runtime-build <build>\n")
         return 2
 
+    from one_memory.sdk_migration_log import authority_snapshot, write_migration_log
+
     settings = load_settings()
+    database_path = settings.data_dir / "one-memory.sqlite3"
+    started = time.monotonic()
+    write_migration_log(
+        settings.data_dir,
+        writer="core-sdk-migrate",
+        event="migrate.invoked",
+        outcome="started",
+        details={
+            "runtime_build": runtime_build,
+            "confirmed": confirmed,
+            **authority_snapshot(database_path),
+        },
+    )
     status = inspect_runtime(settings.data_dir)
     if status.state != "stopped":
         document = {
@@ -321,6 +325,14 @@ def sdk_migrate(options: Sequence[str], stream: TextIO) -> int:
             "code": "sdk_migration_runtime_running",
             "runtime_state": status.state,
         }
+        write_migration_log(
+            settings.data_dir,
+            writer="core-sdk-migrate",
+            event="migrate.blocked",
+            outcome="blocked",
+            code="sdk_migration_runtime_running",
+            details={"runtime_state": status.state},
+        )
         _write_restore(stream, as_json, document, "Runtime 仍在运行；不能迁移。")
         return 4
     if not confirmed:
@@ -328,49 +340,205 @@ def sdk_migrate(options: Sequence[str], stream: TextIO) -> int:
         _write_restore(stream, as_json, document, "预览通过；加 --yes 后执行迁移。")
         return 4
 
-    from one_memory.hy_runtime_config import HY_MEMORY_NAMESPACE, HY_MEMORY_VERSION
+    from one_memory.hy_runtime_config import (
+        HY_MEMORY_NAMESPACE,
+        HY_MEMORY_VERSION,
+        configure_hy_runtime_environment,
+    )
+
+    configure_hy_runtime_environment(settings.data_dir)
     from one_memory.sdk_migration_runner import run_startup_migration
 
     step_names = {
         "bundle": "正在备份记忆数据……",
         "prepare": "正在整理待处理的写入任务……",
         "cutover": "正在切换数据源……",
+        "vectors": "正在接回旧版本的向量数据……",
+        "verify": "正在用新版本核对记忆能否读回……",
         "cleanup": "正在删除旧表……",
     }
 
+    # Everything before the first progress step (authority read, profile
+    # read, resumable identity, legacy id scan, model-profile check) is the
+    # preflight. A failure is logged with the phase it happened in.
+    phase = {"name": "preflight", "started": time.monotonic()}
+
     def progress(step: str) -> None:
+        now = time.monotonic()
+        write_migration_log(
+            settings.data_dir,
+            writer="core-sdk-migrate",
+            event="phase.finished",
+            outcome="succeeded",
+            details={"phase": phase["name"], "duration_ms": (now - phase["started"]) * 1000},
+        )
+        phase["name"], phase["started"] = step, now
+        write_migration_log(
+            settings.data_dir,
+            writer="core-sdk-migrate",
+            event="phase.started",
+            outcome="started",
+            details={"phase": step},
+        )
         if as_json:
-            stream.write(
-                json.dumps({"schema_version": 1, "state": "running", "step": step}) + "\n"
-            )
+            stream.write(json.dumps({"schema_version": 1, "state": "running", "step": step}) + "\n")
         else:
             stream.write(f"{step_names.get(step, step)}\n")
         stream.flush()
 
     try:
-        result = run_startup_migration(
-            data_dir=settings.data_dir,
-            runtime_build=runtime_build,
-            sdk_version=HY_MEMORY_VERSION,
-            namespace=HY_MEMORY_NAMESPACE,
-            progress=progress,
-        )
+        with _migration_lock(settings.data_dir):
+            result = run_startup_migration(
+                data_dir=settings.data_dir,
+                runtime_build=runtime_build,
+                sdk_version=HY_MEMORY_VERSION,
+                namespace=HY_MEMORY_NAMESPACE,
+                progress=progress,
+            )
     except Exception as error:
+        from one_memory.sdk_migration_verify import MemoryReadbackFailed
+
         code = migration_failure_code(error)
-        document = {"schema_version": 1, "state": "failed", "code": code}
-        _write_restore(stream, as_json, document, f"迁移未完成：{code}")
+        failed: dict[str, object] = {"schema_version": 1, "state": "failed", "code": code}
+        if isinstance(error, MemoryReadbackFailed):
+            failed["readback"] = error.report.as_document()
+        write_migration_log(
+            settings.data_dir,
+            writer="core-sdk-migrate",
+            event="migrate.failed",
+            outcome="failed",
+            code=code,
+            error=error,
+            details={
+                "phase": phase["name"],
+                "phase_duration_ms": (time.monotonic() - phase["started"]) * 1000,
+                "duration_ms": (time.monotonic() - started) * 1000,
+                # A generic fallback code means the cause is only in `error`.
+                "code_is_fallback": code == "sdk_migration_preflight_failed"
+                and not _names_code(error, code),
+                **({"readback": failed["readback"]} if "readback" in failed else {}),
+                **authority_snapshot(database_path),
+            },
+        )
+        _write_restore(stream, as_json, failed, f"迁移未完成：{code}")
         return 1
+    document = result.as_document()
+    write_migration_log(
+        settings.data_dir,
+        writer="core-sdk-migrate",
+        event="migrate.finished",
+        outcome="succeeded",
+        migration_id=result.migration_id,
+        details={
+            "state": result.state,
+            "last_phase": phase["name"],
+            "duration_ms": (time.monotonic() - started) * 1000,
+            "result": document,
+            **authority_snapshot(database_path),
+        },
+    )
     messages = {
         "not_required": "不需要迁移。",
-        "complete": "迁移已完成，旧表已清理。",
+        "complete": "迁移已完成；遗留的旧表或向量已处理。",
         "cutover": "迁移完成：记忆数据已以 SDK 为准。",
     }
-    _write_restore(stream, as_json, result.as_document(), messages[result.state])
+    _write_restore(stream, as_json, document, messages[result.state])
     return 0
 
 
+@contextlib.contextmanager
+def _migration_lock(data_dir: Path) -> Iterator[None]:
+    """One `sdk-migrate` per home at a time.
+
+    Desktop, CLI install/upgrade and the Runtime service each migrate before
+    serving, and a login-started service can be migrating when the person
+    opens the app. The second waits here and then finds the work done (or
+    resumes it); two runs never interleave.
+    """
+    from one_memory.sdk_migration_log import write_migration_log
+
+    data_dir.mkdir(parents=True, exist_ok=True, mode=0o700)
+    descriptor = os.open(data_dir / "sdk-migration.lock", os.O_RDWR | os.O_CREAT, 0o600)
+    try:
+        if os.name == "nt":
+            import msvcrt
+
+            def acquire(blocking: bool) -> None:
+                while True:
+                    try:
+                        os.lseek(descriptor, 0, os.SEEK_SET)
+                        msvcrt.locking(descriptor, msvcrt.LK_NBLCK, 1)
+                        return
+                    except OSError:
+                        if not blocking:
+                            raise
+                        time.sleep(0.5)
+
+            def release() -> None:
+                os.lseek(descriptor, 0, os.SEEK_SET)
+                msvcrt.locking(descriptor, msvcrt.LK_UNLCK, 1)
+        else:
+            import fcntl
+
+            def acquire(blocking: bool) -> None:
+                fcntl.flock(descriptor, fcntl.LOCK_EX | (0 if blocking else fcntl.LOCK_NB))
+
+            def release() -> None:
+                fcntl.flock(descriptor, fcntl.LOCK_UN)
+
+        try:
+            acquire(False)
+        except OSError:
+            write_migration_log(
+                data_dir,
+                writer="core-sdk-migrate",
+                event="migrate.waiting_for_lock",
+                outcome="started",
+            )
+            waited = time.monotonic()
+            acquire(True)
+            write_migration_log(
+                data_dir,
+                writer="core-sdk-migrate",
+                event="migrate.lock_acquired",
+                outcome="succeeded",
+                details={"waited_ms": (time.monotonic() - waited) * 1000},
+            )
+        try:
+            yield
+        finally:
+            release()
+    finally:
+        os.close(descriptor)
+
+
+def _names_code(error: BaseException, code: str) -> bool:
+    return any(
+        str(getattr(item, "code", "")).split(":", 1)[0] == code for item in _exception_chain(error)
+    )
+
+
 def sdk_migration_status(options: Sequence[str], stream: TextIO) -> int:
     """Read-only probe: does this home need `sdk-migrate`?"""
+    try:
+        return _sdk_migration_status(options, stream)
+    except Exception as error:
+        from one_memory.sdk_migration_log import write_migration_log
+
+        # The orchestrator only sees a non-zero exit and reports
+        # `sdk_migration_status_unavailable`; the cause is recorded here.
+        write_migration_log(
+            load_settings().data_dir,
+            writer="core-sdk-migration-status",
+            event="status.failed",
+            outcome="failed",
+            code="sdk_migration_status_unavailable",
+            error=error,
+        )
+        raise
+
+
+def _sdk_migration_status(options: Sequence[str], stream: TextIO) -> int:
     if list(options) not in ([], ["--json"]):
         stream.write("one-memory: sdk-migration-status 只接受 --json\n")
         return 2
@@ -390,21 +558,34 @@ def sdk_migration_status(options: Sequence[str], stream: TextIO) -> int:
             SdkDataPlaneMigrationStore,
         )
         from one_memory.sdk_migration_runner import abandoned_staging_present
+        from one_memory.sdk_migration_verify import read_active_profile
+        from one_memory.sdk_vector_reattach import legacy_vector_collections
         from one_memory.target_schema import legacy_tables_present
 
         authority = SdkDataPlaneMigrationStore(database_path).authority()
         if authority is MemoryAuthority.SDK:
+            profile = read_active_profile(database_path)
             leftovers = bool(
                 legacy_tables_present(database_path)
                 or abandoned_staging_present(
                     data_dir=settings.data_dir,
                     namespace=HY_MEMORY_NAMESPACE,
                 )
+                or (profile is not None and legacy_vector_collections(settings.data_dir, profile))
             )
             state = "required" if leftovers else "not_required"
         else:
             state = "required"
         document = {"schema_version": 1, "authority": authority.value, "state": state}
+    from one_memory.sdk_migration_log import write_migration_log
+
+    write_migration_log(
+        settings.data_dir,
+        writer="core-sdk-migration-status",
+        event="status.probed",
+        outcome="succeeded",
+        details={"authority": document["authority"], "state": document["state"]},
+    )
     if as_json:
         stream.write(f"{json.dumps(document, ensure_ascii=False)}\n")
     else:
@@ -424,30 +605,58 @@ def _status_text(command: str, status: RuntimeStatus) -> str:
     return f"MemHub Runtime 状态不可验证：{status.code}。"
 
 
-def _reserve_reader_port(host: str, port: int) -> int:
-    """Resolve the port the Reader will listen on, including the ephemeral case.
+#: Exit status of a serving Core refused because the home is not on SDK
+#: authority (`EX_CONFIG`). The Runtime maps it to `sdk_migration_required`.
+SDK_MIGRATION_REQUIRED_EXIT = 78
 
-    The supervisor asks for an ephemeral port (`ONE_MEMORY_READER_PORT=0`) and
-    then reads the real one back from stderr. Letting uvicorn bind port 0
-    itself would give a port nobody can report, so claim a free port here by
-    binding and immediately releasing it, then serve on that exact port.
+
+def _refuse_unmigrated_home(data_dir: Path) -> None:
+    """Exit before binding when an existing home has not reached SDK authority.
+
+    A brand-new home has no database yet and is created on SDK authority by
+    startup. Anything else that is not SDK is an upgrade that did not finish,
+    and is never served: the migration must run first.
     """
-    if port != 0:
-        return port
-    probe = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    from one_memory.sdk_data_plane_migration import MemoryAuthority, SdkDataPlaneMigrationStore
+    from one_memory.sdk_migration_log import authority_snapshot, write_migration_log
+
+    database_path = data_dir / "one-memory.sqlite3"
+    if not database_path.is_file():
+        return
     try:
-        probe.bind((host, 0))
-        return int(probe.getsockname()[1])
-    finally:
-        probe.close()
+        authority = SdkDataPlaneMigrationStore(database_path).authority()
+    except Exception as error:  # noqa: BLE001 - an unreadable home is not served either
+        write_migration_log(
+            data_dir,
+            writer="core-startup",
+            event="core.refused_legacy",
+            outcome="refused",
+            code="sdk_migration_required",
+            error=error,
+        )
+        print("sdk_migration_required", file=sys.stderr, flush=True)
+        raise SystemExit(SDK_MIGRATION_REQUIRED_EXIT) from None
+    if authority is MemoryAuthority.SDK:
+        return
+    write_migration_log(
+        data_dir,
+        writer="core-startup",
+        event="core.refused_legacy",
+        outcome="refused",
+        code="sdk_migration_required",
+        details={"stage": "serve_entry", **authority_snapshot(database_path)},
+    )
+    print("sdk_migration_required", file=sys.stderr, flush=True)
+    raise SystemExit(SDK_MIGRATION_REQUIRED_EXIT)
 
 
-def serve(*, maintenance: bool = False, reader: bool = False) -> None:
+def serve(*, maintenance: bool = False) -> None:
     import uvicorn
 
     from one_memory.diagnostic_log import configure_diagnostics, diagnostic_event
     from one_memory.hy_runtime_config import (
         apply_diagnostic_log_level,
+        configure_hy_runtime_environment,
         diagnostic_log_level,
     )
     from one_memory.log_file import start_logging_to_file
@@ -455,40 +664,13 @@ def serve(*, maintenance: bool = False, reader: bool = False) -> None:
     from one_memory.runtime import CoreRuntime, parent_pid
 
     settings = load_settings()
-    if reader:
-        settings = settings.model_copy(
-            update={
-                "port": int(os.environ.get("ONE_MEMORY_READER_PORT", "0") or "0"),
-                "api_token": settings.api_token,
-            }
-        )
-        from one_memory.reader_app import ReaderSettings, create_reader_app
-
-        core_port = int(os.environ.get("ONE_MEMORY_CORE_PORT", "8765"))
-        # The supervisor learns the Reader's port by watching stderr for
-        # `reader_port:<n>`. With `ONE_MEMORY_READER_PORT=0` uvicorn would bind
-        # an OS-chosen port that nothing reports back, so claim the port up
-        # front and serve on that exact one.
-        port = _reserve_reader_port(settings.host, settings.port)
-        reader_settings = ReaderSettings(
-            data_dir=settings.data_dir,
-            host=settings.host,
-            port=port,
-            api_token=settings.api_token,
-            core_port=core_port,
-            core_api_token=os.environ.get("ONE_MEMORY_CORE_API_TOKEN", ""),
-        )
-        application = create_reader_app(reader_settings)
-        print(f"reader_port:{port}", file=sys.stderr, flush=True)
-        uvicorn.run(
-            application,
-            host=settings.host,
-            port=port,
-            reload=False,
-            access_log=False,
-        )
-        return
-
+    if not maintenance:
+        _refuse_unmigrated_home(settings.data_dir)
+    # HY resolves some trace paths at import time and its pipeline path when
+    # SharedRuntime starts. Bind both to the MemHub root before importing the
+    # application graph; otherwise HY falls back to ~/.hy_memory while the
+    # desktop Debug panel watches the managed data directory.
+    configure_hy_runtime_environment(settings.data_dir)
     from one_memory.api import create_app
 
     start_logging_to_file(settings.data_dir)

memhub/apps/core/src/one_memory/config.py

@@ -23,10 +23,6 @@ class Settings(BaseSettings):
     live_sync_enabled: bool = True
     automatic_memory_processing: bool = True
     imports_enabled: bool = True
-    # Experimental and unreleased: ownership/error shutdown still requires acceptance.
-    # Resume only explicitly initialized generations; never migrate at startup.
-    retrieval_index_enabled: bool = False
-    retrieval_minimum_free_bytes: int = Field(default=256 * 1024 * 1024, ge=0)
     # Bounded metadata only: query, original text and answers are never stored.
     call_event_retention_days: int | None = Field(default=30, ge=1, le=365)
     call_event_max_events: int | None = Field(default=10_000, ge=1, le=100_000)

memhub/apps/core/src/one_memory/context_models.py

@@ -47,6 +47,19 @@ class ContextSearchRequest(BaseModel):
         return self
 
 
+class SdkContextSearchRequest(ContextSearchRequest):
+    """`POST /api/v2/context/search`: the three SDK recall lanes are set apart.
+
+    `limit` is the normal lane's top-k and the cap on returned items;
+    `schema_limit` and `intention_limit` are the SDK's schema (L6) and
+    proactive intention (L7) lanes. A caller's values are passed through.
+    """
+
+    limit: int = Field(default=10, ge=1, le=20, strict=True)
+    schema_limit: int = Field(default=3, ge=0, le=20, strict=True)
+    intention_limit: int = Field(default=1, ge=0, le=20, strict=True)
+
+
 class ContextMessage(BaseModel):
     model_config = ConfigDict(frozen=True, extra="forbid")
 

memhub/apps/core/src/one_memory/context_routes.py

@@ -1,7 +1,6 @@
-"""Authenticated composite read route, without generation or reindex side effects."""
+"""Authenticated SDK context search route, without generation or reindex side effects."""
 
 import asyncio
-import sqlite3
 import time
 from collections.abc import Sequence
 from datetime import UTC, datetime
@@ -11,36 +10,15 @@ from uuid import uuid4
 from fastapi import APIRouter, HTTPException, Request, Response
 from fastapi.params import Depends
 
-from one_memory.background_work import (
-    in_interactive_read,
-    in_read_pool,
-    memory_read_pool,
-    raw_read_pool,
-)
-from one_memory.call_event_recorder import context_call_event
+from one_memory.call_event_recorder import sdk_context_call_event
 from one_memory.context_access import resolve_context_authority
-from one_memory.context_memory import (
-    merge_memory_candidates,
-    read_memory_context,
-    revalidate_memory_context,
-)
 from one_memory.context_models import (
-    ContextItem,
-    ContextKind,
-    ContextLaneResult,
-    ContextSearchRequest,
-    ContextSearchResponse,
-    ContextSemanticStatus,
-    MemoryContextItem,
-    RawContextItem,
     SdkContextItem,
+    SdkContextSearchRequest,
     SdkContextSearchResponse,
     SdkMemoryContextItem,
     SdkRawContextItem,
 )
-from one_memory.context_raw import revalidate_raw_context
-from one_memory.context_search import search_context
-from one_memory.diagnostic_log import diagnostic_event, diagnostic_exception
 from one_memory.external_memory_access import external_access
 from one_memory.hy_runtime_config import HY_MEMORY_READER
 from one_memory.hy_sdk_runtime import sdk_relevance_floor
@@ -50,389 +28,8 @@ from one_memory.hy_sdk_types import (
     parse_sdk_search,
 )
 from one_memory.imports.storage import EvidenceStore
-from one_memory.retrieval.raw_lane import read_raw_indexed_context
-from one_memory.semantic_deadline import hy_wait_budget, search_within
 
 CALL_EVENT_RESPONSE_BUDGET_MS = 250
-RESPONSE_SERIALIZATION_RESERVE_MS = 100
-INTERACTIVE_TOTAL_BUDGET_MS = 900
-RAW_LANE_BUDGET_SECONDS = 0.3
-MEMORY_LANE_BUDGET_SECONDS = 0.75
-MEMORY_FINALIZE_RESERVE_SECONDS = 0.1
-
-
-def context_router(dependencies: Sequence[Depends]) -> APIRouter:
-    router = APIRouter(prefix="/api/v1/context", dependencies=dependencies)
-
-    @router.post("/search", response_model=ContextSearchResponse)
-    async def search(
-        value: ContextSearchRequest, request: Request, response: Response
-    ) -> ContextSearchResponse:
-        response.headers["Cache-Control"] = "no-store"
-        started = time.monotonic()
-        search_budget_ms = min(
-            INTERACTIVE_TOTAL_BUDGET_MS,
-            max(50, value.timeout_ms - RESPONSE_SERIALIZATION_RESERVE_MS),
-        )
-        deadline = started + search_budget_ms / 1000
-        access = external_access(request.headers)
-        try:
-            database = cast(EvidenceStore, request.app.state.evidence_store).database_path
-            authority = await asyncio.wait_for(
-                in_interactive_read(
-                    resolve_context_authority, value, access, database, deadline=deadline
-                ),
-                timeout=max(0, deadline - time.monotonic()),
-            )
-        except HTTPException:
-            raise
-        except Exception:
-            # Authority could not be established; do not try an unbounded local lane.
-            raise HTTPException(503, "context_authority_unavailable") from None
-
-        lane_observations: dict[ContextKind, ContextLaneResult] = {}
-        lane_failures: dict[ContextKind, tuple[str, str]] = {}
-        stage_timings: dict[str, float] = {}
-
-        async def raw(end: float) -> ContextLaneResult:
-            lane_end = min(end, time.monotonic() + RAW_LANE_BUDGET_SECONDS)
-            read = asyncio.create_task(
-                in_read_pool(
-                    raw_read_pool(),
-                    read_raw_indexed_context,
-                    database,
-                    value,
-                    source_ids=authority.raw_sources,
-                    deadline=lane_end,
-                    index=getattr(request.app.state, "retrieval_runtime", None),
-                )
-            )
-            done, _ = await asyncio.wait({read}, timeout=max(0, lane_end - time.monotonic()))
-            if read not in done:
-                read.cancel()
-                read.add_done_callback(
-                    lambda task: task.exception() if not task.cancelled() else None
-                )
-                result = ContextLaneResult(
-                    status="degraded",
-                    reason="timeout_budget",
-                    searched_channels=("lexical", "semantic"),
-                    timed_out=True,
-                    truncated_by=("timeout_budget",),
-                )
-            else:
-                result = read.result()
-            lane_observations["raw"] = result
-            return result
-
-        async def memory(end: float) -> ContextLaneResult:
-            lane_end = min(end, time.monotonic() + MEMORY_LANE_BUDGET_SECONDS)
-            target = getattr(request.app.state, "recall_target", None)
-            lexical = asyncio.create_task(
-                in_read_pool(
-                    memory_read_pool(),
-                    read_memory_context,
-                    database,
-                    value,
-                    scopes=authority.memory_scopes,
-                    deadline=lane_end,
-                    semantic_ids=(),
-                    semantic_outcome="absent",
-                )
-            )
-            semantic_hits, outcome = await search_within(
-                getattr(target, "semantic_search", None),
-                value.query,
-                hy_wait_budget(lane_end - time.monotonic()),
-            )
-            done, _ = await asyncio.wait({lexical}, timeout=max(0, lane_end - time.monotonic()))
-            if lexical not in done:
-                lexical.cancel()
-                lexical.add_done_callback(
-                    lambda task: task.exception() if not task.cancelled() else None
-                )
-                result = ContextLaneResult(
-                    status="unavailable",
-                    reason="timeout_budget",
-                    searched_channels=("lexical", "semantic"),
-                    semantic_status=cast(
-                        ContextSemanticStatus,
-                        {
-                            "absent": "not_searched",
-                            "answered": "completed",
-                            "failed": "failed",
-                            "timed_out": "timed_out",
-                        }[outcome],
-                    ),
-                    timed_out=True,
-                    truncated_by=("timeout_budget",),
-                )
-                lane_observations["memory"] = result
-                return result
-            try:
-                lexical_result = lexical.result()
-            except (sqlite3.Error, OSError, ValueError) as error:
-                diagnostic_event(
-                    level="warn",
-                    component="context.search",
-                    event="context.lexical_memory_failed",
-                    outcome="degraded",
-                    error_code="lexical_memory_read_failed",
-                    **diagnostic_exception(error),
-                )
-                lexical_result = ContextLaneResult(
-                    status="unavailable",
-                    reason="read_unavailable",
-                    searched_channels=("lexical",),
-                    failure_site="memory_lexical",
-                    error_class=type(error).__name__,
-                )
-            if outcome == "absent":
-                result = lexical_result
-            elif outcome in {"failed", "timed_out"}:
-                truncated_by = list(lexical_result.truncated_by)
-                has_lexical_memory = bool(lexical_result.items)
-                if (
-                    outcome == "timed_out"
-                    and not has_lexical_memory
-                    and "timeout_budget" not in truncated_by
-                ):
-                    truncated_by.append("timeout_budget")
-                result = lexical_result.model_copy(
-                    update={
-                        "status": "degraded",
-                        "reason": "lexical_only" if has_lexical_memory else "timeout_budget",
-                        "truncated_by": tuple(truncated_by),
-                        "searched_channels": ("lexical", "semantic"),
-                        "semantic_status": "timed_out" if outcome == "timed_out" else "failed",
-                        "timed_out": outcome == "timed_out" and not has_lexical_memory,
-                    }
-                )
-            else:
-                semantic_request = value.model_copy(update={"query": ""})
-                enriched = asyncio.create_task(
-                    in_interactive_read(
-                        read_memory_context,
-                        database,
-                        semantic_request,
-                        scopes=authority.memory_scopes,
-                        deadline=lane_end,
-                        semantic_hits=semantic_hits,
-                        semantic_outcome=outcome,
-                    )
-                )
-                done, _ = await asyncio.wait(
-                    {enriched},
-                    timeout=max(
-                        0,
-                        lane_end - MEMORY_FINALIZE_RESERVE_SECONDS - time.monotonic(),
-                    ),
-                )
-                if enriched not in done:
-                    enriched.cancel()
-                    enriched.add_done_callback(
-                        lambda task: task.exception() if not task.cancelled() else None
-                    )
-                    result = lexical_result.model_copy(
-                        update={
-                            "status": "degraded",
-                            "reason": "lexical_only",
-                            "searched_channels": ("lexical", "semantic"),
-                            "semantic_status": "completed",
-                            "timed_out": False,
-                        }
-                    )
-                else:
-                    try:
-                        semantic_result = enriched.result()
-                    except (sqlite3.Error, OSError, ValueError) as error:
-                        diagnostic_event(
-                            level="warn",
-                            component="context.search",
-                            event="context.semantic_enrichment_failed",
-                            outcome="degraded",
-                            error_code="semantic_enrichment_read_failed",
-                            **diagnostic_exception(error),
-                        )
-                        result = lexical_result.model_copy(
-                            update={
-                                "status": "degraded",
-                                "reason": "lexical_only",
-                                "searched_channels": ("lexical", "semantic"),
-                                "semantic_status": "completed",
-                                "timed_out": False,
-                            }
-                        )
-                        lane_observations["memory"] = result
-                        return result
-                    if semantic_result.status == "unavailable" and lexical_result.items:
-                        result = lexical_result.model_copy(
-                            update={
-                                "status": "degraded",
-                                "reason": "lexical_only",
-                                "searched_channels": ("lexical", "semantic"),
-                                "semantic_status": "completed",
-                                "timed_out": False,
-                            }
-                        )
-                        lane_observations["memory"] = result
-                        return result
-                    semantic_items = tuple(
-                        item
-                        for item in semantic_result.items
-                        if isinstance(item, MemoryContextItem)
-                    )
-                    lexical_items = tuple(
-                        item for item in lexical_result.items if isinstance(item, MemoryContextItem)
-                    )
-                    combined_count = len(
-                        {item.memory_id for item in (*semantic_items, *lexical_items)}
-                    )
-                    merged = merge_memory_candidates(
-                        lexical_items,
-                        semantic_items,
-                        limit=value.limit + 1,
-                    )
-                    truncated_by = list(semantic_result.truncated_by)
-                    if combined_count > len(merged) and "count_budget" not in truncated_by:
-                        truncated_by.append("count_budget")
-                    result = semantic_result.model_copy(
-                        update={
-                            "items": tuple(merged),
-                            # An answered semantic search may legitimately
-                            # return no IDs. Lexical can still have a grounded
-                            # hit; retaining semantic's `empty` status while
-                            # attaching that hit violates the lane contract
-                            # and makes the aggregator reject the whole lane.
-                            "status": "ok" if merged else semantic_result.status,
-                            "truncated_by": tuple(truncated_by),
-                        }
-                    )
-            lane_observations["memory"] = result
-            return result
-
-        async def finalizer(
-            kind: ContextKind, items: tuple[ContextItem, ...], end: float
-        ) -> tuple[ContextItem, ...]:
-            if kind == "raw":
-                return await in_interactive_read(
-                    revalidate_raw_context,
-                    database,
-                    tuple(item for item in items if isinstance(item, RawContextItem)),
-                    source_ids=authority.raw_sources,
-                    deadline=end,
-                )
-            return await in_interactive_read(
-                revalidate_memory_context,
-                database,
-                tuple(item for item in items if isinstance(item, MemoryContextItem)),
-                scopes=authority.memory_scopes,
-                deadline=end,
-            )
-
-        result = await search_context(
-            value,
-            raw_reader=raw if authority.raw_allowed else None,
-            memory_reader=memory if authority.memory_allowed else None,
-            finalizer=finalizer,
-            deadline=deadline,
-            timing_observer=stage_timings.update,
-            failure_observer=lambda kind, site, error_class: lane_failures.__setitem__(
-                kind, (site, error_class)
-            ),
-        )
-        final = result.model_copy(update={"total_ms": (time.monotonic() - started) * 1000})
-        serialization_started = time.monotonic()
-        final.model_dump_json()
-        stage_timings["serialization_ms"] = (time.monotonic() - serialization_started) * 1000
-        for phase, duration in stage_timings.items():
-            diagnostic_event(
-                level="info",
-                component="context.search",
-                event="context_stage.completed",
-                outcome="succeeded",
-                request_id=final.request_id,
-                duration_ms=max(0, round(duration)),
-                details={"phase": phase},
-            )
-        for kind in ("raw", "memory"):
-            path = getattr(final.paths, kind)
-            observed = lane_observations.get(kind)
-            failure = lane_failures.get(kind)
-            lexical_hits = (
-                sum(
-                    1
-                    for item in observed.items
-                    if isinstance(item, MemoryContextItem) and "lexical" in item.matched_by
-                )
-                if observed is not None and kind == "memory"
-                else 0
-            )
-            semantic_hits = (
-                sum(
-                    1
-                    for item in observed.items
-                    if isinstance(item, MemoryContextItem)
-                    and "governed_semantic" in item.matched_by
-                )
-                if observed is not None and kind == "memory"
-                else 0
-            )
-            timed_out = path.reason == "timeout_budget" or (
-                observed.timed_out if observed is not None else False
-            )
-            diagnostic_failure_site = failure[0] if failure is not None else None
-            diagnostic_error_class = failure[1] if failure is not None else None
-            if observed is not None:
-                diagnostic_failure_site = diagnostic_failure_site or observed.failure_site
-                diagnostic_error_class = diagnostic_error_class or observed.error_class
-            diagnostic_event(
-                level="warn" if path.status in {"degraded", "unavailable"} else "info",
-                component="context.search",
-                event="context_lane.completed",
-                outcome=path.status,
-                request_id=final.request_id,
-                duration_ms=round(path.elapsed_ms),
-                details={
-                    "operation_kind": kind,
-                    "mode": ",".join(observed.searched_channels) if observed else "none",
-                    "status": path.status,
-                    "index_complete": observed.index_complete if observed else None,
-                    **(
-                        {"lexical_hits": lexical_hits, "semantic_hits": semantic_hits}
-                        if kind == "memory"
-                        else {}
-                    ),
-                    "reason": path.reason,
-                    "truncated": path.truncated,
-                    "timed_out": timed_out,
-                    **(
-                        {
-                            "failure_site": diagnostic_failure_site,
-                            "error_class": diagnostic_error_class,
-                        }
-                        if diagnostic_failure_site is not None
-                        and diagnostic_error_class is not None
-                        else {}
-                    ),
-                },
-            )
-        store = getattr(request.app.state, "call_event_store", None)
-        if store is not None and value.query != "__om_probe__":
-            event = context_call_event(final, access)
-            try:
-                await asyncio.to_thread(
-                    store.record,
-                    event,
-                    busy_timeout_ms=CALL_EVENT_RESPONSE_BUDGET_MS,
-                )
-                response.headers["X-One-Memory-Call-Recorded"] = "true"
-            except Exception:
-                response.headers["X-One-Memory-Call-Recorded"] = "false"
-                request.app.state.call_event_recording_error = True
-        return final
-
-    return router
 
 
 def sdk_context_router(dependencies: Sequence[Depends]) -> APIRouter:
@@ -441,7 +38,7 @@ def sdk_context_router(dependencies: Sequence[Depends]) -> APIRouter:
 
     @router.post("/search", response_model=SdkContextSearchResponse)
     async def search(
-        value: ContextSearchRequest,
+        value: SdkContextSearchRequest,
         request: Request,
         response: Response,
     ) -> SdkContextSearchResponse:
@@ -516,8 +113,8 @@ def sdk_context_router(dependencies: Sequence[Depends]) -> APIRouter:
                 limit=value.limit,
                 min_score=sdk_relevance_floor(),
                 schema_min_score=sdk_relevance_floor(),
-                schema_limit=value.limit,
-                intention_limit=value.limit,
+                schema_limit=value.schema_limit,
+                intention_limit=value.intention_limit,
                 scene="normal",
                 reader=HY_MEMORY_READER,
             )
@@ -551,6 +148,29 @@ def sdk_context_router(dependencies: Sequence[Depends]) -> APIRouter:
                 )
             return tuple(items)
 
+        async def record(final: SdkContextSearchResponse, *, timed_out: bool) -> None:
+            # Same boundary as v2 ask: only a host's call is history. The
+            # renderer's own searches are the person reading their library.
+            store = getattr(request.app.state, "call_event_store", None)
+            if store is None or access is None or value.query == "__om_probe__":
+                return
+            event = sdk_context_call_event(
+                final,
+                access,
+                memory_searched=authority.memory_allowed,
+                timed_out=timed_out,
+            )
+            try:
+                await asyncio.to_thread(
+                    store.record,
+                    event,
+                    busy_timeout_ms=CALL_EVENT_RESPONSE_BUDGET_MS,
+                )
+                response.headers["X-One-Memory-Call-Recorded"] = "true"
+            except Exception:
+                response.headers["X-One-Memory-Call-Recorded"] = "false"
+                request.app.state.call_event_recording_error = True
+
         lanes = (raw_lane(), memory_lane())
         try:
             raw_items, memory_items = await asyncio.wait_for(
@@ -558,7 +178,7 @@ def sdk_context_router(dependencies: Sequence[Depends]) -> APIRouter:
                 timeout=value.timeout_ms / 1000,
             )
         except TimeoutError:
-            return SdkContextSearchResponse(
+            final = SdkContextSearchResponse(
                 request_id=str(uuid4()),
                 state="unavailable",
                 items=(),
@@ -566,6 +186,8 @@ def sdk_context_router(dependencies: Sequence[Depends]) -> APIRouter:
                 truncated=True,
                 total_ms=(time.monotonic() - started) * 1000,
             )
+            await record(final, timed_out=True)
+            return final
         partial = isinstance(raw_items, Exception) or isinstance(memory_items, Exception)
         raw_candidates = (
             () if isinstance(raw_items, Exception) else cast(tuple[SdkContextItem, ...], raw_items)
@@ -597,7 +219,7 @@ def sdk_context_router(dependencies: Sequence[Depends]) -> APIRouter:
                 truncated = True
             selected.append(item)
             used += len(item.content)
-        return SdkContextSearchResponse(
+        final = SdkContextSearchResponse(
             request_id=str(uuid4()),
             state=("partial" if partial else "grounded" if selected else "empty"),
             items=tuple(selected),
@@ -605,5 +227,7 @@ def sdk_context_router(dependencies: Sequence[Depends]) -> APIRouter:
             truncated=truncated,
             total_ms=(time.monotonic() - started) * 1000,
         )
+        await record(final, timed_out=False)
+        return final
 
     return router

memhub/apps/core/src/one_memory/context_search.py

@@ -1,464 +0,0 @@
-"""Bounded two-lane orchestration; readers and finalizers own trusted read access."""
-
-import asyncio
-import time
-from collections.abc import Awaitable, Callable, Mapping
-from dataclasses import dataclass, field
-from uuid import uuid4
-
-from pydantic import TypeAdapter
-
-from one_memory.context_models import (
-    ContextItem,
-    ContextKind,
-    ContextLaneResult,
-    ContextLimit,
-    ContextPath,
-    ContextPaths,
-    ContextSearchRequest,
-    ContextSearchResponse,
-    MemoryContextItem,
-    RawContextItem,
-)
-
-Reader = Callable[[float], Awaitable[ContextLaneResult]]
-Finalizer = Callable[
-    [ContextKind, tuple[ContextItem, ...], float], Awaitable[tuple[ContextItem, ...]]
-]
-TimingObserver = Callable[[Mapping[str, float]], None]
-FailureObserver = Callable[[ContextKind, str, str], None]
-_KINDS: tuple[ContextKind, ...] = ("raw", "memory")
-_ITEMS = TypeAdapter(tuple[ContextItem, ...])
-
-
-@dataclass
-class _Lane:
-    result: ContextLaneResult
-    elapsed_ms: float = 0
-    limits: list[ContextLimit] = field(default_factory=list)
-
-
-def _identity(item: ContextItem) -> tuple[str, ...]:
-    if isinstance(item, RawContextItem):
-        return (item.kind, item.source_id, item.conversation_id, item.anchor_evidence_id)
-    return (item.kind, item.memory_id)
-
-
-def _validate_items(kind: ContextKind, items: tuple[ContextItem, ...]) -> None:
-    if len(items) > 21 or any(item.kind != kind for item in items):
-        raise ValueError("invalid lane items")
-    for item in items:
-        if isinstance(item, RawContextItem) and item.anchor_evidence_id not in {
-            message.evidence_id for message in item.messages
-        }:
-            raise ValueError("missing raw anchor")
-
-
-async def _read(reader: Reader, kind: ContextKind, deadline: float) -> ContextLaneResult:
-    value = await reader(deadline)
-    # Revalidate even BaseModel instances: model_construct/model_copy bypass validation.
-    result = ContextLaneResult.model_validate(value.model_dump())
-    _validate_items(kind, result.items)
-    if result.status not in ("ok", "empty", "degraded", "unavailable"):
-        raise ValueError("reader cannot decide requested authority")
-    if result.status in ("empty", "unavailable") and result.items:
-        raise ValueError("non-result lane has items")
-    return result
-
-
-async def _finalize(
-    finalizer: Finalizer, kind: ContextKind, items: tuple[ContextItem, ...], deadline: float
-) -> tuple[ContextItem, ...]:
-    value = await finalizer(kind, items, deadline)
-    if not isinstance(value, tuple):
-        raise ValueError("invalid finalization result")
-    checked = _ITEMS.validate_python([item.model_dump() for item in value])
-    _validate_items(kind, checked)
-    if not {_identity(item) for item in checked} <= {_identity(item) for item in items}:
-        raise ValueError("finalizer introduced an unselected identity")
-    return checked
-
-
-async def _collect(
-    jobs: dict[ContextKind, Awaitable[object]], deadline: float
-) -> tuple[
-    dict[ContextKind, object],
-    dict[ContextKind, BaseException],
-    set[ContextKind],
-    dict[ContextKind, float],
-]:
-    """Cancel and await every owned task on deadline, failure or caller cancellation."""
-
-    durations: dict[ContextKind, float] = {}
-
-    async def measured(kind: ContextKind, job: Awaitable[object]) -> object:
-        started = time.monotonic()
-        try:
-            value = await job
-            if time.monotonic() >= deadline:
-                raise TimeoutError
-            return value
-        finally:
-            durations[kind] = (time.monotonic() - started) * 1000
-
-    tasks = {kind: asyncio.create_task(measured(kind, job)) for kind, job in jobs.items()}
-    values: dict[ContextKind, object] = {}
-    failed: dict[ContextKind, BaseException] = {}
-    timed_out: set[ContextKind] = set()
-    try:
-        if not tasks:
-            return values, failed, timed_out, durations
-        done, pending = await asyncio.wait(
-            tasks.values(), timeout=max(0, deadline - time.monotonic())
-        )
-        for kind, task in tasks.items():
-            if task in pending:
-                timed_out.add(kind)
-            elif task in done:
-                if not task.cancelled() and isinstance(task.exception(), TimeoutError):
-                    timed_out.add(kind)
-                elif task.cancelled() or task.exception() is not None:
-                    failed[kind] = task.exception() or asyncio.CancelledError()
-                else:
-                    values[kind] = task.result()
-        return values, failed, timed_out, durations
-    finally:
-        for task in tasks.values():
-            if not task.done():
-                task.cancel()
-        if tasks:
-            # Cooperative readers finish immediately and still get their
-            # normal cleanup. A bridge that suppresses cancellation must not
-            # hold a host response past its hard deadline while an underlying
-            # SDK thread winds down.
-            cleanup: asyncio.Future[list[object]] = asyncio.gather(
-                *tasks.values(), return_exceptions=True
-            )
-            current = asyncio.current_task()
-            if current is not None and current.cancelling():
-                await cleanup
-            else:
-                try:
-                    await asyncio.wait_for(asyncio.shield(cleanup), timeout=0.05)
-                except TimeoutError:
-                    cleanup.add_done_callback(_consume_cleanup)
-
-
-def _consume_cleanup(task: asyncio.Future[list[object]]) -> None:
-    if not task.cancelled():
-        task.exception()
-
-
-def _deduplicate(
-    items: tuple[ContextItem, ...], limits: list[ContextLimit]
-) -> tuple[ContextItem, ...]:
-    unique: dict[tuple[str, ...], ContextItem] = {}
-    for item in items:
-        key = _identity(item)
-        previous = unique.get(key)
-        if isinstance(previous, MemoryContextItem) and isinstance(item, MemoryContextItem):
-            if item.revision != previous.revision:
-                # Never graft older evidence onto a newer memory version.
-                unique[key] = item if item.revision > previous.revision else previous
-                continue
-            evidence = tuple(dict.fromkeys((*previous.evidence_ids, *item.evidence_ids)))
-            if len(evidence) > 128:
-                limits.append("metadata_budget")
-            unique[key] = previous.model_copy(
-                update={
-                    "evidence_ids": evidence[:128],
-                    "truncated": previous.truncated or item.truncated or len(evidence) > 128,
-                }
-            )
-        elif isinstance(previous, RawContextItem) and isinstance(item, RawContextItem):
-            messages = {message.evidence_id: message for message in previous.messages}
-            for message in item.messages:
-                if (
-                    message.evidence_id not in messages
-                    or message.revision > messages[message.evidence_id].revision
-                ):
-                    messages[message.evidence_id] = message
-            if len(messages) > 3:
-                limits.append("metadata_budget")
-            # The first window already contains the anchor; dict order preserves it.
-            unique[key] = previous.model_copy(
-                update={
-                    "messages": tuple(messages.values())[:3],
-                    "truncated": previous.truncated or item.truncated or len(messages) > 3,
-                }
-            )
-        else:
-            unique[key] = item
-    # Reserve each raw anchor for its own window before deduplicating context messages.
-    anchors = {
-        (item.source_id, item.conversation_id, item.anchor_evidence_id)
-        for item in unique.values()
-        if isinstance(item, RawContextItem)
-    }
-    seen: set[tuple[str, ...]] = set()
-    result: list[ContextItem] = []
-    for item in unique.values():
-        if isinstance(item, MemoryContextItem):
-            result.append(
-                item.model_copy(update={"evidence_ids": tuple(dict.fromkeys(item.evidence_ids))})
-            )
-            continue
-        retained_messages = []
-        for message in item.messages:
-            key = (item.source_id, item.conversation_id, message.evidence_id)
-            if key in seen or (key in anchors and message.evidence_id != item.anchor_evidence_id):
-                continue
-            seen.add(key)
-            retained_messages.append(message)
-        result.append(item.model_copy(update={"messages": tuple(retained_messages)}))
-    return tuple(result)
-
-
-def _characters(item: ContextItem) -> int:
-    if isinstance(item, MemoryContextItem):
-        return len(item.content)
-    return sum(len(message.text) for message in item.messages)
-
-
-def _shares(lengths: list[int], budget: int) -> list[int]:
-    """Water-fill allocations so a large first item cannot consume every character."""
-    allocations = [0] * len(lengths)
-    pending = list(range(len(lengths)))
-    while pending and budget:
-        share, remainder = divmod(budget, len(pending))
-        next_pending = []
-        for position, index in enumerate(pending):
-            added = min(lengths[index] - allocations[index], share + (position < remainder))
-            allocations[index] += added
-            budget -= added
-            if allocations[index] < lengths[index]:
-                next_pending.append(index)
-        pending = next_pending
-    return allocations
-
-
-def _clip(item: ContextItem, budget: int) -> ContextItem:
-    if _characters(item) <= budget:
-        return item
-    if isinstance(item, MemoryContextItem):
-        return item.model_copy(update={"content": item.content[:budget], "truncated": True})
-    # The first raw message is the lexical anchor. Give it the first share of
-    # the budget, then water-fill the adjacent context; otherwise a long
-    # neighbor can consume the whole window and hide the answer.
-    anchor = item.messages[0]
-    anchor_budget = min(len(anchor.text), budget)
-    remaining = budget - anchor_budget
-    adjacent = list(item.messages[1:])
-    shares = [anchor_budget, *_shares([len(message.text) for message in adjacent], remaining)]
-    return item.model_copy(
-        update={
-            "truncated": True,
-            "messages": tuple(
-                message.model_copy(
-                    update={
-                        "text": message.text[:share],
-                        "truncated": message.truncated or len(message.text) > share,
-                    }
-                )
-                for message, share in zip(item.messages, shares, strict=True)
-            ),
-        }
-    )
-
-
-async def search_context(
-    request: ContextSearchRequest,
-    *,
-    raw_reader: Reader | None,
-    memory_reader: Reader | None,
-    finalizer: Finalizer,
-    deadline: float | None = None,
-    timing_observer: TimingObserver | None = None,
-    failure_observer: FailureObserver | None = None,
-) -> ContextSearchResponse:
-    request = ContextSearchRequest.model_validate(request.model_dump())
-    started = time.monotonic()
-    deadline = min(
-        deadline if deadline is not None else float("inf"), started + request.timeout_ms / 1000
-    )
-    lanes: dict[ContextKind, _Lane] = {}
-    jobs: dict[ContextKind, Awaitable[object]] = {}
-    readers: dict[ContextKind, Reader | None] = {"raw": raw_reader, "memory": memory_reader}
-    for kind, reader in readers.items():
-        if kind not in request.kinds:
-            lanes[kind] = _Lane(ContextLaneResult(status="not_requested", reason="not_requested"))
-        elif reader is None:
-            lanes[kind] = _Lane(
-                ContextLaneResult(status="not_authorized", reason="permission_required")
-            )
-        elif time.monotonic() >= deadline:
-            lanes[kind] = _Lane(
-                ContextLaneResult(status="degraded", reason="timeout_budget", timed_out=True),
-                limits=["timeout_budget"],
-            )
-        else:
-            jobs[kind] = _read(reader, kind, deadline)
-    values, failed, timed_out, read_ms = await _collect(jobs, deadline)
-    for kind in jobs:
-        result = values.get(kind)
-        if kind in timed_out:
-            result = ContextLaneResult(
-                status="degraded",
-                reason="timeout_budget",
-                truncated_by=("timeout_budget",),
-                timed_out=True,
-            )
-        elif kind in failed or not isinstance(result, ContextLaneResult):
-            error = failed.get(kind)
-            if failure_observer is not None:
-                failure_observer(
-                    kind,
-                    "collect",
-                    type(error).__name__ if error is not None else "InvalidLaneResult",
-                )
-            result = ContextLaneResult(
-                status="unavailable",
-                reason="read_unavailable",
-                failure_site="collect",
-                error_class=type(error).__name__ if error is not None else "InvalidLaneResult",
-            )
-        lanes[kind] = _Lane(result, read_ms.get(kind, 0), list(dict.fromkeys(result.truncated_by)))
-
-    final_jobs: dict[ContextKind, Awaitable[object]] = {}
-    for kind in jobs:
-        lane = lanes[kind]
-        if lane.result.status not in ("ok", "empty", "degraded"):
-            continue
-        if time.monotonic() >= deadline:
-            lane.result = ContextLaneResult(
-                status="degraded", reason="timeout_budget", timed_out=True
-            )
-            lane.limits.append("timeout_budget")
-        else:
-            final_jobs[kind] = _finalize(finalizer, kind, lane.result.items, deadline)
-    final_values, final_failed, final_timed_out, revalidation_ms = await _collect(
-        final_jobs, deadline
-    )
-    for kind in final_jobs:
-        lane = lanes[kind]
-        lane.elapsed_ms += revalidation_ms.get(kind, 0)
-        if kind in final_timed_out:
-            lane.result = ContextLaneResult(
-                status="unavailable", reason="timeout_budget", timed_out=True
-            )
-            lane.limits.append("timeout_budget")
-        elif kind in final_failed:
-            error = final_failed[kind]
-            if failure_observer is not None:
-                failure_observer(kind, "finalize", type(error).__name__)
-            lane.result = ContextLaneResult(
-                status="unavailable",
-                reason="read_unavailable",
-                failure_site="finalize",
-                error_class=type(error).__name__,
-            )
-        else:
-            final_items = _ITEMS.validate_python(final_values[kind])
-            changed = {_identity(item): item for item in lane.result.items} != {
-                _identity(item): item for item in final_items
-            }
-            lane.result = lane.result.model_copy(
-                update={
-                    "items": final_items,
-                    "status": "degraded" if changed else lane.result.status,
-                    "reason": ("evidence_changed" if kind == "raw" else "memory_changed")
-                    if changed
-                    else lane.result.reason,
-                }
-            )
-
-    # Nothing previously verified may escape once the common release deadline expired.
-    if time.monotonic() >= deadline:
-        for kind in jobs:
-            if lanes[kind].result.status in ("ok", "empty", "degraded"):
-                lanes[kind].result = ContextLaneResult(
-                    status="degraded", reason="timeout_budget", timed_out=True
-                )
-                lanes[kind].limits.append("timeout_budget")
-    fusion_started = time.monotonic()
-    queues = {kind: _deduplicate(lanes[kind].result.items, lanes[kind].limits) for kind in _KINDS}
-    interleaved = [
-        queues[kind][index]
-        for index in range(max(map(len, queues.values()), default=0))
-        for kind in _KINDS
-        if index < len(queues[kind])
-    ]
-    selected = interleaved[: request.limit]
-    for item in interleaved[request.limit :]:
-        lanes[item.kind].limits.append("count_budget")
-    shares = _shares([_characters(item) for item in selected], request.character_budget)
-    items = tuple(_clip(item, share) for item, share in zip(selected, shares, strict=True))
-    for before, after in zip(selected, items, strict=True):
-        if _characters(before) != _characters(after):
-            lanes[after.kind].limits.append("character_budget")
-    if time.monotonic() >= deadline:
-        items = ()
-        for kind in jobs:
-            if lanes[kind].result.status in ("ok", "empty", "degraded"):
-                lanes[kind].result = ContextLaneResult(
-                    status="degraded", reason="timeout_budget", timed_out=True
-                )
-                lanes[kind].limits.append("timeout_budget")
-                lanes[kind].elapsed_ms = (time.monotonic() - started) * 1000
-    paths: dict[ContextKind, ContextPath] = {}
-    for kind in _KINDS:
-        lane = lanes[kind]
-        emitted = [item for item in items if item.kind == kind]
-        limits = tuple(dict.fromkeys(lane.limits))
-        truncated = bool(limits) or any(item.truncated for item in emitted)
-        status = lane.result.status
-        benign_limits = set(limits) <= {"count_budget", "character_budget"}
-        benign_degradation = (
-            not lane.result.timed_out
-            and benign_limits
-            and (
-                lane.result.reason is None
-                or (kind == "raw" and lane.result.reason == "lexical_only")
-            )
-        )
-        if status in ("ok", "empty") or (status == "degraded" and benign_degradation):
-            status = "ok" if emitted or lane.result.items else "empty"
-        paths[kind] = ContextPath(
-            status=status,
-            reason=lane.result.reason,
-            elapsed_ms=lane.elapsed_ms,
-            returned_count=len(emitted),
-            truncated=truncated,
-            truncated_by=limits,
-        )
-    requested_paths = [paths[kind] for kind in request.kinds]
-    completed = any(path.status in ("ok", "empty", "degraded") for path in requested_paths)
-    incomplete = any(path.status not in ("ok", "empty") for path in requested_paths)
-    response = ContextSearchResponse(
-        request_id=str(uuid4()),
-        state="unavailable"
-        if not completed
-        else "partial"
-        if incomplete
-        else "grounded"
-        if items
-        else "empty",
-        paths=ContextPaths(raw=paths["raw"], memory=paths["memory"]),
-        items=items,
-        used_characters=sum(map(_characters, items)),
-        truncated=any(path.truncated for path in paths.values()),
-        total_ms=(time.monotonic() - started) * 1000,
-    )
-    checked = ContextSearchResponse.model_validate(response.model_dump())
-    if timing_observer is not None:
-        timing_observer(
-            {
-                "raw_ms": read_ms.get("raw", 0),
-                "memory_ms": read_ms.get("memory", 0),
-                "raw_revalidation_ms": revalidation_ms.get("raw", 0),
-                "memory_revalidation_ms": revalidation_ms.get("memory", 0),
-                "fusion_ms": (time.monotonic() - fusion_started) * 1000,
-                "total_ms": checked.total_ms,
-            }
-        )
-    return checked

memhub/apps/core/src/one_memory/context_v2_coordinator.py

@@ -22,7 +22,7 @@ from dataclasses import dataclass
 from datetime import UTC, datetime
 from functools import partial
 from pathlib import Path
-from typing import Any, Literal, Protocol, cast
+from typing import Any, Literal, cast
 
 from one_memory.background_work import interactive_read_pool
 from one_memory.context_expand import ExpansionAuthority, ExpansionRefSigner
@@ -36,23 +36,8 @@ from one_memory.retrieval.models import (
     RawEvidence,
     RetrievalPath,
     RetrievalResponse,
-    TimeRange,
 )
 from one_memory.retrieval.query_plan import plan_local_query
-from one_memory.retrieval.raw_candidates import RawCandidateBatch
-from one_memory.retrieval.raw_evidence import materialize_raw_candidates
-
-
-class RawIndexLookup(Protocol):
-    def lookup_raw(
-        self,
-        query: str,
-        *,
-        source_ids: frozenset[str],
-        deadline: float,
-        time_range: TimeRange | None = None,
-    ) -> tuple[RawCandidateBatch, bool]: ...
-
 
 ExpandRefs = tuple[ExpansionRefSigner, ExpansionAuthority]
 
@@ -106,11 +91,6 @@ class LaneResult:
     coverage_limited: bool = False
 
 
-def _semantic_only_raw(item: RawEvidence) -> bool:
-    """Semantic overlap alone is a candidate, not a confirmed recall item."""
-    return set(item.matched_by) == {"semantic"}
-
-
 @dataclass(frozen=True)
 class StageTimings:
     raw_ms: float = 0.0
@@ -191,12 +171,6 @@ def _managed(
     return selected, truncated
 
 
-def _group_missing_requirements(item: RawEvidence | GovernedEvidence) -> list[str]:
-    if isinstance(item, RawEvidence) and _semantic_only_raw(item):
-        return ["relevance_confirmation"]
-    return []
-
-
 def _path(
     status: str,
     reason: str | None,
@@ -296,8 +270,7 @@ def read_lexical_raw_lane(
         ("lexical", "object") if plan.object_keys else ("lexical",),
         truncated,
         # Starvation means: this lane matched, then dropped the item whole. An
-        # ordinary no-match must stay empty, and an unconfigured semantic lane
-        # is not starvation.
+        # ordinary no-match must stay empty.
         starved and not items,
         probe_saturated,
     )
@@ -564,97 +537,6 @@ def warm_raw_read_path(
         return False
 
 
-def read_semantic_raw_lane(
-    index: RawIndexLookup | None,
-    database_path: Path,
-    query: CoordinatorQuery,
-    *,
-    source_ids: frozenset[str],
-    deadline: float,
-) -> LaneResult:
-    if not source_ids:
-        return LaneResult((), "unavailable", "permission_required", (), False)
-    # No derived index is the no-model baseline, not a failure: the lexical lane
-    # must still answer. Semantic is genuinely unsearched in that state, so it
-    # must not claim a channel or a coverage result it never produced.
-    if index is None:
-        return LaneResult((), "not_searched", None, (), False)
-    try:
-        batch, unpublished = index.lookup_raw(
-            query.query,
-            source_ids=source_ids,
-            deadline=deadline,
-            time_range=plan_local_query(query.query).time_range,
-        )
-    except Exception:
-        return LaneResult((), "unavailable", "index_unavailable", ("semantic",), False)
-    if not isinstance(batch, RawCandidateBatch):
-        return LaneResult((), "unavailable", "index_unavailable", ("semantic",), False)
-    if batch.reason == "not_authorized":
-        return LaneResult((), "unavailable", "permission_required", ("semantic",), False)
-    if batch.reason == "deadline":
-        return LaneResult((), "unavailable", "timeout_budget", ("semantic",), True)
-    if batch.reason in {"vector_unavailable", "index_unavailable"}:
-        return LaneResult((), "unavailable", batch.reason, ("semantic",), False)
-    store, generation = _index_state(index, database_path)
-    from one_memory.retrieval.index_store import RetrievalIndexStore
-
-    store = cast("RetrievalIndexStore | None", store)
-    if store is None or generation is None:
-        return LaneResult((), "unavailable", "index_unavailable", ("semantic",), False)
-    try:
-        materialized = materialize_raw_candidates(
-            store,
-            batch,
-            generation_id=generation,
-            source_ids=source_ids,
-            deadline=deadline,
-            character_budget=query.character_budget,
-        )
-    except Exception:
-        return LaneResult((), "unavailable", "index_unavailable", ("semantic",), False)
-    if materialized.reason == "deadline":
-        return LaneResult((), "unavailable", "timeout_budget", ("semantic",), True)
-    if materialized.reason in {"index_unavailable", "not_authorized"}:
-        return LaneResult((), "unavailable", materialized.reason, ("semantic",), False)
-    complete = materialized.complete and not unpublished
-    if materialized.reason == "evidence_changed":
-        status: Literal["ok", "empty", "unavailable", "not_searched"] = "unavailable"
-        reason = "evidence_changed"
-    elif not materialized.items and not complete:
-        status, reason = "unavailable", "index_incomplete"
-    elif materialized.reason == "character_budget":
-        status, reason = "ok", None
-    else:
-        status, reason = ("ok" if materialized.items else "empty"), None
-    return LaneResult(
-        tuple(materialized.items),
-        status,
-        reason,
-        ("semantic",),
-        materialized.reason == "character_budget",
-    )
-
-
-def _index_state(index: RawIndexLookup, database_path: Path) -> tuple[object | None, str | None]:
-    store = getattr(index, "_store", None)
-    generation = None
-    snapshot = getattr(index, "snapshot", None)
-    if snapshot is not None:
-        try:
-            generation = snapshot().generation_id
-        except Exception:
-            generation = None
-    if store is None:
-        try:
-            from one_memory.retrieval.index_store import RetrievalIndexStore
-
-            store = RetrievalIndexStore(database_path)
-        except Exception:
-            store = None
-    return store, generation
-
-
 def read_memory_lane(
     database_path: Path,
     query: CoordinatorQuery,
@@ -857,7 +739,6 @@ def coordinate_context_v2(
     query: CoordinatorQuery,
     *,
     database_path: Path,
-    index: RawIndexLookup | None = None,
     deadline: float,
     expand_refs: ExpandRefs | None = None,
 ) -> RetrievalResponse:
@@ -871,62 +752,29 @@ def coordinate_context_v2(
         lexical = read_lexical_raw_lane(
             database_path, query, source_ids=authority.raw_sources, deadline=deadline
         )
-        semantic = read_semantic_raw_lane(
-            index, database_path, query, source_ids=authority.raw_sources, deadline=deadline
-        )
         timings = StageTimings(raw_ms=(time.monotonic() - raw_started) * 1000)
         combined: dict[tuple[str, str], RawEvidence] = {}
-        for item in (*lexical.items, *semantic.items):
-            if not isinstance(item, RawEvidence):
-                continue
-            identity = _identity(item)
-            previous = combined.get(identity)
-            if previous is None or _semantic_only_raw(previous):
-                combined[identity] = item
-        # Semantic similarity is a candidate signal, not a verified recall
-        # result. Keep semantic-only candidates visible in coverage, but do not
-        # release their bodies for host injection unless the item is
-        # independently confirmed by the lexical/object lane. A global distance
-        # threshold is deliberately not used: the measured positive and
-        # negative distributions overlap.
-        semantic_only = {_identity(item) for item in combined.values() if _semantic_only_raw(item)}
-        confirmed = {_identity(item) for item in lexical.items if isinstance(item, RawEvidence)}
-        deferred_raw = semantic_only - confirmed
-        if deferred_raw:
-            combined = {
-                identity: item
-                for identity, item in combined.items()
-                if identity not in deferred_raw
-            }
-        channels = tuple(dict.fromkeys((*lexical.channels, *semantic.channels)))
+        for item in lexical.items:
+            if isinstance(item, RawEvidence):
+                combined.setdefault(_identity(item), item)
         if lexical.status == "unavailable":
             status: Literal["ok", "empty", "unavailable", "not_searched", "degraded"] = (
                 "unavailable"
             )
             reason = lexical.reason
-        elif semantic.status == "unavailable":
-            status = "unavailable"
-            reason = semantic.reason
-        elif combined:
-            status, reason = "ok", semantic.reason if semantic.status != "ok" else None
-        elif deferred_raw:
-            status, reason = "degraded", "relevance_confirmation"
-        elif lexical.status == "empty":
-            status, reason = ("empty" if semantic.status != "not_searched" else "ok"), None
+        elif combined or lexical.status == "empty":
+            status, reason = "ok", None
         else:
             status, reason = "empty", None
-        truncated = lexical.truncated or semantic.truncated
         raw = LaneResult(
             tuple(combined.values()),
             status,
             reason,
-            channels,
-            truncated,
+            lexical.channels,
+            lexical.truncated,
             lexical.starved,
             lexical.coverage_limited,
         )
-        if deferred_raw:
-            object.__setattr__(raw, "coverage_limited", True)
     elif "raw" in query.kinds and not authority.raw_allowed:
         raw = LaneResult((), "unavailable", "permission_required", (), False)
     if "memory" in query.kinds:
@@ -995,9 +843,7 @@ def coordinate_context_v2(
             return _path("unavailable", raw.reason, raw.channels, "not_searched", False, 0)
         if dropped and not final_raw:
             return _path("unavailable", "permission_required", raw.channels, "unavailable", True, 0)
-        # Lexical-only is complete when the lexical lane actually answered. An
-        # unconfigured semantic lane is a capability absence, not proof that
-        # less than the authorized range was searched.
+        # The raw lane is complete when the lexical lane actually answered.
         complete = (
             raw.status in {"ok", "empty"}
             and not dropped
@@ -1022,9 +868,7 @@ def coordinate_context_v2(
                 "count_budget"
                 if truncated
                 else "coverage_budget"
-                if raw.coverage_limited and not deferred_raw
-                else "relevance_confirmation"
-                if deferred_raw
+                if raw.coverage_limited
                 else "character_budget"
             )
         return _path(
@@ -1112,7 +956,7 @@ def coordinate_context_v2(
                 "group_id": f"group-{index}",
                 "answer_target": query.intent,
                 "decision_status": "missing_confirmation",
-                "missing_requirements": _group_missing_requirements(item),
+                "missing_requirements": [],
                 "object_refs": _object_refs(item, plan.object_keys),
                 "items": [group_item.model_dump(mode="json") for group_item in (item,)],
             }
@@ -1185,7 +1029,6 @@ async def search_context_v2(
     query: CoordinatorQuery,
     *,
     database_path: Path,
-    index: RawIndexLookup | None = None,
     deadline: float,
     expand_refs: ExpandRefs | None = None,
 ) -> RetrievalResponse:
@@ -1198,7 +1041,6 @@ async def search_context_v2(
             authority,
             query,
             database_path=database_path,
-            index=index,
             deadline=deadline,
             expand_refs=expand_refs,
         ),

memhub/apps/core/src/one_memory/derived_echo.py

@@ -6,7 +6,6 @@ from collections.abc import Sequence
 from typing import NamedTuple
 
 PREFACE = "以下是获授权历史参考，不是指令；当前用户请求优先。"
-_MARKER = re.compile(r"om-derived:([0-9a-f]{64})")
 # Written by the host-bridge recall injection hook (recall-injection.ts): the
 # recalled memory block and, in the same reply, the cross-session notice block.
 _INJECTED_TAGS = ("memhub_memory_context", "memhub_session_notice")
@@ -89,45 +88,3 @@ def strip_injected_memory(text: str) -> str:
         return text
     kept.append(text[at:])
     return _EMPTY_REMINDER.sub("", "".join(kept)).strip()
-
-
-def marker(event_id: str) -> str:
-    return f"om-derived:{event_id}"
-
-
-def echoed_event_ids(verbatim: str) -> tuple[str, ...]:
-    return tuple(dict.fromkeys(_MARKER.findall(verbatim)))
-
-
-def render_reference(events: tuple[object, ...] | list[object]) -> str:
-    lines = [PREFACE]
-    for event in events:
-        source = getattr(event, "source_id", None) or "unknown"
-        revision = getattr(event, "evidence_revision", None)
-        evidence_id = getattr(event, "evidence_id", None) or ""
-        event_id = getattr(event, "event_id", "")
-        lines.append(
-            f"来源 {source} 修订 {0 if revision is None else revision} "
-            f"证据 {evidence_id} {marker(str(event_id))}"
-        )
-    return "\n".join(lines)
-
-
-def is_pure_echo(verbatim: str, known_event_ids: set[str]) -> bool:
-    """True when the text is only a block we already injected.
-
-    A later line that is not the preface, a source line, or one of those
-    markers is a real correction and must still be recorded.
-    """
-
-    found = set(echoed_event_ids(verbatim))
-    if not found or not found & known_event_ids:
-        return False
-    for line in verbatim.splitlines():
-        stripped = line.strip()
-        if not stripped or stripped == PREFACE or stripped.startswith("来源 "):
-            continue
-        if _MARKER.search(stripped):
-            continue
-        return False
-    return True

memhub/apps/core/src/one_memory/diagnostic_log.py

@@ -804,7 +804,7 @@ def record_database_error(
     sqlite_code = getattr(error, "sqlite_errorcode", None)
     sqlite_name = getattr(error, "sqlite_errorname", None)
     details: dict[str, object] = {"phase": safe_component, "count": count}
-    if route_path is not None and route_path.startswith("/api/v1/"):
+    if route_path is not None and route_path.startswith(("/api/v1/", "/api/v2/")):
         details["route_path"] = route_path
     if isinstance(sqlite_code, int):
         details["sqlite_errorcode"] = sqlite_code

memhub/apps/core/src/one_memory/external_memory_access.py

@@ -23,13 +23,9 @@ _ENVELOPE_HEADERS = frozenset(
 )
 _BROKER_ROUTES = {
     ("POST", "/api/v1/recall"): "om_recall",
-    ("POST", "/api/v1/memories/ask"): "om_ask",
     ("POST", "/api/v2/memories/ask"): "om_ask",
     ("POST", "/api/v2/memories/ask/stream"): "om_ask",
-    ("GET", "/api/v1/conversations/search"): "om_conversations",
     ("POST", "/api/v1/diagnostics/trace"): "om_diagnostic_trace",
-    ("POST", "/api/v1/boundary/peek"): "om_recall",
-    ("POST", "/api/v1/boundary/ack"): "om_recall",
 }
 _CONCRETE_CALL_EVENT_DELIVERY = re.compile(
     r"/api/v1/call-events/[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-"
@@ -128,11 +124,9 @@ def require_external_endpoint(request: Request) -> None:
     access = external_access(request.headers)
     if access is None:
         return
-    if request.method == "POST" and request.url.path in {
-        "/api/v1/context/search",
-        "/api/v2/context/search",
-    }:
-        # The route resolves each requested lane against its original grant.
+    if request.method == "POST" and request.url.path == "/api/v2/context/search":
+        # om_conversations reaches Core only here, as the raw lane; the route
+        # resolves each requested lane against its original grant.
         # Passing this envelope gate does not authorize either lane by itself.
         if access.tools.isdisjoint({"om_recall", "om_conversations"}):
             raise HTTPException(403, "external_recall_scope_denied")
@@ -146,7 +140,3 @@ def require_external_endpoint(request: Request) -> None:
         raise HTTPException(403, "external_endpoint_denied")
     if tool not in access.tools:
         raise HTTPException(403, "external_recall_scope_denied")
-    if tool == "om_conversations":
-        access.require(tool, frozenset({"all-apps"}))
-        if not any(scope.startswith("source:") for scope in access.scopes):
-            raise HTTPException(403, "external_source_permission_required")

memhub/apps/core/src/one_memory/home_summary.py

@@ -1,127 +0,0 @@
-"""Bounded homepage projection without loading every memory into the renderer."""
-
-import sqlite3
-import time
-from datetime import UTC, datetime
-from pathlib import Path
-
-from pydantic import BaseModel, ConfigDict
-
-from one_memory.database_access import main_database
-from one_memory.memory_evidence_freshness import register_memory_freshness
-
-
-class HomeLatestMemory(BaseModel):
-    model_config = ConfigDict(frozen=True)
-
-    memory_id: str
-    content: str
-    truncated: bool
-    revision: int
-    action: str
-    updated_at: datetime
-    source_ids: tuple[str, ...]
-
-
-class HomeSummary(BaseModel):
-    model_config = ConfigDict(frozen=True)
-
-    memory_count: int
-    latest: HomeLatestMemory | None
-    observed_at: datetime
-    #: 2026-10-12: the read hit its deadline and the numbers below are not a
-    #: snapshot of reality. Callers should keep their previous summary on
-    #: screen instead of treating count=0 as "no memories".
-    stale: bool = False
-
-
-class HomeSummaryUnavailable(Exception):
-    """The homepage projection could not be read inside its own deadline.
-
-    Raised instead of letting SQLite's interrupt escape as a bare
-    `OperationalError`, so the route can answer with an empty projection
-    rather than a 500.
-    """
-
-
-def read_home_summary(database_path: Path, *, user_id: str = "local") -> HomeSummary:
-    # The exclusion mirrors SourceReadAccess: one revoked active citation hides
-    # the whole memory. Permission filtering precedes both count and LIMIT.
-    # `+link.active` keeps SQLite on the (memory_id, evidence_id) primary key.
-    # Without the unary plus it picks the (active, ...) index and walks every
-    # active link once per memory: 2.9 s instead of 0.07 s on a 1,810-memory
-    # library, enough to time the homepage out whenever the machine is busy.
-    readable = """
-        m.user_id = ? AND m.status = 'confirmed' AND m.deleted_at IS NULL
-        AND NOT EXISTS (
-            SELECT 1 FROM governed_memory_evidence link
-            JOIN evidence e ON e.evidence_id = link.evidence_id
-            JOIN source_grants g ON g.user_id=e.user_id AND g.source_id=e.source_id
-            WHERE link.memory_id=m.memory_id AND +link.active=1
-              AND g.revoked_at IS NOT NULL
-        )
-        AND NOT EXISTS (
-            SELECT 1 FROM governed_memory_evidence link
-            LEFT JOIN evidence e ON e.evidence_id = link.evidence_id
-            WHERE link.memory_id=m.memory_id AND +link.active=1
-              AND (e.evidence_id IS NULL OR e.user_id != m.user_id)
-        )
-    """
-    # The total counts with the cheap permission filters only: the per-row
-    # freshness UDF scales with the whole library and can burn the whole read
-    # budget on its own (D22). Product accepted a small drift here; the rows
-    # that are actually displayed are still checked row by row below.
-    with main_database(database_path).read() as db:
-        deadline = time.monotonic() + 5
-        db.set_progress_handler(lambda: int(time.monotonic() >= deadline), 1000)
-        db.row_factory = sqlite3.Row
-        try:
-            db.execute("BEGIN")
-            count = db.execute(
-                f"SELECT COUNT(*) FROM governed_memories m WHERE {readable}", (user_id,)
-            ).fetchone()[0]
-            readable += " AND " + register_memory_freshness(db)
-            row = db.execute(
-                f"""SELECT m.memory_id, substr(m.content,1,320) AS content,
-                    length(m.content)>320 AS truncated, m.revision,
-                    COALESCE(v.action, 'unknown') AS action, m.updated_at
-                    FROM governed_memories m
-                    LEFT JOIN governed_memory_versions v
-                      ON v.memory_id=m.memory_id AND v.revision=m.revision
-                    WHERE {readable}
-                    ORDER BY m.updated_at DESC, m.memory_id LIMIT 1""",
-                (user_id,),
-            ).fetchone()
-            latest = None
-            if row is not None:
-                sources = db.execute(
-                    """SELECT DISTINCT e.source_id FROM governed_memory_evidence link
-                    JOIN evidence e ON e.evidence_id=link.evidence_id
-                    WHERE link.memory_id=? AND +link.active=1 ORDER BY e.source_id""",
-                    (row["memory_id"],),
-                ).fetchall()
-                latest = HomeLatestMemory(
-                    memory_id=row["memory_id"],
-                    content=row["content"],
-                    truncated=bool(row["truncated"]),
-                    revision=row["revision"],
-                    action=row["action"],
-                    updated_at=row["updated_at"],
-                    source_ids=tuple(source[0] for source in sources),
-                )
-        except sqlite3.Error as error:
-            # The progress handler above is what interrupts this read, so a
-            # slow homepage surfaces as SQLITE_INTERRUPT (code 9) and used to
-            # escape as a 500. 2026-10-12: answer with a `stale` projection
-            # instead of raising: the caller keeps its last good summary on
-            # screen (the UI poll retries within 10s), and the homepage never
-            # zeroes out or errors just because the machine is busy importing.
-            if getattr(error, "sqlite_errorcode", None) != sqlite3.SQLITE_INTERRUPT:
-                raise
-            return HomeSummary(
-                memory_count=0,
-                latest=None,
-                observed_at=datetime.now(UTC),
-                stale=True,
-            )
-        return HomeSummary(memory_count=count, latest=latest, observed_at=datetime.now(UTC))

memhub/apps/core/src/one_memory/hy_sdk_migration.py

@@ -1,13 +1,20 @@
-"""Offline snapshot and restore of the HY SDK data plane for the App migration.
+"""Offline maintenance of the HY SDK data plane for App migrations.
 
 Runtime product code must use public ``HyMemoryClient`` methods.  The startup
-migration bundle is the isolated exception: all writers are stopped, so it may
-copy and restore the SDK-owned local stores as files.
+migration boundary is the isolated exception: all writers are stopped, so it
+may copy, restore and repair SDK-owned local stores.
 """
 
 from __future__ import annotations
 
+import json
+import sqlite3
+from collections.abc import Iterator
+from contextlib import closing
+from dataclasses import dataclass, field
+from datetime import UTC, datetime, timedelta
 from pathlib import Path
+from typing import Any
 
 from hy_memory import (  # type: ignore[import-untyped]
     DataPlaneRestore,
@@ -16,6 +23,28 @@ from hy_memory import (  # type: ignore[import-untyped]
     snapshot_local_data_plane,
 )
 
+from one_memory.database_access import main_database
+from one_memory.hy_runtime_config import HY_MEMORY_NAMESPACE
+
+# v2 reads the backfill's governed_memory_evidence links; v1 missed them.
+_METADATA_REPAIR_VERSION = 2
+_BATCH = 500
+
+
+@dataclass(frozen=True)
+class RepairMetadata:
+    source: str | None
+    memory_at: int | None
+    created_at: int | None
+
+
+@dataclass(frozen=True)
+class MetadataRepairResult:
+    migration_id: str | None
+    mapped: int
+    vector_rows: int
+    coding_rows: int
+
 
 def snapshot_data_plane(
     *,
@@ -45,3 +74,396 @@ def restore_data_plane(
         writers_stopped=writers_stopped,
         protective_root=protective_root,
     )
+
+
+def repair_sdk_metadata_from_bundle(
+    *,
+    data_dir: Path,
+    database_path: Path,
+    now: datetime | None = None,
+) -> MetadataRepairResult:
+    """Restore metadata lost by historical cutovers from their verified bundles."""
+    migration_id = _sdk_migration_id(database_path)
+    if migration_id is None:
+        return MetadataRepairResult(None, 0, 0, 0)
+    receipt = data_dir / f".sdk-metadata-repair-v{_METADATA_REPAIR_VERSION}-{migration_id}.json"
+    if receipt.is_file():
+        document = json.loads(receipt.read_text(encoding="utf-8"))
+        return MetadataRepairResult(
+            migration_id,
+            int(document.get("mapped", 0)),
+            int(document.get("vector_rows", 0)),
+            int(document.get("coding_rows", 0)),
+        )
+    # A home can carry several cutovers (v1 and then v2). A later bundle may
+    # have been taken after an earlier cutover had already retired the legacy
+    # tables, so every bundle is read and their links are pooled.
+    legacy = sorted(
+        (data_dir / "backups").glob("*-pre-cutover.sdk-bundle/management/one-memory.sqlite3")
+    )
+    if not legacy:
+        # No bundle yet is not a finished repair: try again on the next start.
+        return MetadataRepairResult(migration_id, 0, 0, 0)
+    current = now or datetime.now(UTC)
+    pools: dict[str, _Pool] = {}
+    for path in legacy:
+        _merge_pools(pools, _legacy_pools(path, now=current))
+    mapping = _decide(pools)
+    vector_rows = _repair_vector(data_dir, mapping, now=current)
+    coding_rows = _repair_coding(data_dir, mapping)
+    result = MetadataRepairResult(
+        migration_id,
+        len(mapping),
+        vector_rows,
+        coding_rows,
+    )
+    temporary = receipt.with_suffix(".tmp")
+    temporary.write_text(
+        json.dumps(
+            {
+                "schema_version": 1,
+                "migration_id": migration_id,
+                "mapped": result.mapped,
+                "vector_rows": vector_rows,
+                "coding_rows": coding_rows,
+            },
+            sort_keys=True,
+        )
+        + "\n",
+        encoding="utf-8",
+    )
+    temporary.replace(receipt)
+    return result
+
+
+def _sdk_migration_id(database_path: Path) -> str | None:
+    with main_database(database_path).read(row_factory=sqlite3.Row) as database:
+        row = database.execute(
+            "SELECT authority,migration_id FROM memory_authority_state WHERE singleton=1"
+        ).fetchone()
+    if row is None or row["authority"] != "sdk":
+        return None
+    value = row["migration_id"]
+    return str(value) if isinstance(value, str) and value else None
+
+
+@dataclass
+class _Pool:
+    """Everything the legacy library knew about one SDK memory."""
+
+    sources: set[str] = field(default_factory=set)
+    times: list[datetime] = field(default_factory=list)
+    created: list[datetime] = field(default_factory=list)
+
+
+def _legacy_metadata(path: Path, *, now: datetime) -> dict[str, RepairMetadata]:
+    return _decide(_legacy_pools(path, now=now))
+
+
+def _legacy_pools(path: Path, *, now: datetime) -> dict[str, _Pool]:
+    """Link each SDK memory id to the legacy evidence it was made from.
+
+    Three legacy paths wrote memories the SDK now holds:
+
+    - the cutover backfill (`import_exact`) copied every governed memory into the
+      SDK under its legacy id, or under the id `memory_task_outputs` recorded,
+      without a source or a conversation time; `governed_memory_evidence` is the
+      link from that memory to its evidence;
+    - extraction tasks recorded their evidence as `support_refs`;
+    - the write queue recorded the SDK ids each job produced.
+    """
+    with closing(sqlite3.connect(f"file:{path}?mode=ro", uri=True)) as database:
+        database.row_factory = sqlite3.Row
+        tables = {
+            str(row[0])
+            for row in database.execute("SELECT name FROM sqlite_master WHERE type='table'")
+        }
+        if "evidence" not in tables:
+            return {}
+        links: dict[str, set[str]] = {}
+        created: dict[str, list[datetime]] = {}
+        canonical: dict[str, str] = {}
+        if "memory_task_outputs" in tables:
+            for row in database.execute("SELECT body FROM memory_task_outputs"):
+                try:
+                    body = json.loads(str(row["body"]))
+                except (TypeError, ValueError):
+                    continue
+                legacy_id = body.get("memory_id")
+                canonical_id = body.get("hy_memory_id")
+                refs = body.get("support_refs")
+                if not isinstance(legacy_id, str) or not isinstance(canonical_id, str):
+                    continue
+                canonical[legacy_id] = canonical_id
+                links.setdefault(canonical_id, set()).update(
+                    str(ref["evidence_id"])
+                    for ref in (refs if isinstance(refs, list) else ())
+                    if isinstance(ref, dict) and isinstance(ref.get("evidence_id"), str)
+                )
+        if "governed_memories" in tables:
+            for row in database.execute(
+                "SELECT memory_id,created_at,updated_at FROM governed_memories"
+            ):
+                legacy_id = str(row["memory_id"])
+                canonical_id = canonical.get(legacy_id, legacy_id)
+                links.setdefault(canonical_id, set())
+                legacy_created = _plausible_time(
+                    row["created_at"], fallback=row["updated_at"], now=now
+                )
+                if legacy_created is not None:
+                    created.setdefault(canonical_id, []).append(legacy_created)
+            if "governed_memory_evidence" in tables:
+                for row in database.execute(
+                    "SELECT memory_id,evidence_id FROM governed_memory_evidence"
+                ):
+                    legacy_id = str(row["memory_id"])
+                    links.setdefault(canonical.get(legacy_id, legacy_id), set()).add(
+                        str(row["evidence_id"])
+                    )
+        if "memory_write_jobs" in tables and "sdk_memory_ids_json" in _columns(
+            database, "memory_write_jobs"
+        ):
+            job_evidence: dict[str, set[str]] = {}
+            if "memory_write_job_evidence" in tables:
+                for row in database.execute(
+                    "SELECT job_id,evidence_id FROM memory_write_job_evidence"
+                ):
+                    job_evidence.setdefault(str(row["job_id"]), set()).add(str(row["evidence_id"]))
+            for row in database.execute(
+                "SELECT job_id,sdk_memory_ids_json FROM memory_write_jobs "
+                "WHERE sdk_memory_ids_json IS NOT NULL"
+            ):
+                try:
+                    memory_ids = json.loads(str(row["sdk_memory_ids_json"]))
+                except (TypeError, ValueError):
+                    continue
+                for memory_id in memory_ids if isinstance(memory_ids, list) else ():
+                    if isinstance(memory_id, str) and memory_id:
+                        links.setdefault(memory_id, set()).update(
+                            job_evidence.get(str(row["job_id"]), ())
+                        )
+        evidence: dict[str, tuple[str, datetime | None]] = {}
+        wanted = sorted({identifier for refs in links.values() for identifier in refs})
+        for batch in _batches(wanted):
+            placeholders = ",".join("?" for _ in batch)
+            for row in database.execute(
+                "SELECT evidence_id,source_id,created_at,imported_at "
+                f"FROM evidence WHERE evidence_id IN ({placeholders})",
+                batch,
+            ):
+                evidence[str(row["evidence_id"])] = (
+                    str(row["source_id"]),
+                    _plausible_time(row["created_at"], fallback=row["imported_at"], now=now),
+                )
+    pools: dict[str, _Pool] = {}
+    for canonical_id, refs in links.items():
+        pool = pools.setdefault(canonical_id, _Pool())
+        for identifier in refs:
+            if identifier not in evidence:
+                continue
+            source, timestamp = evidence[identifier]
+            if source and source != "default":
+                pool.sources.add(source)
+            if timestamp is not None:
+                pool.times.append(timestamp)
+        pool.created.extend(created.get(canonical_id, ()))
+    return pools
+
+
+def _merge_pools(into: dict[str, _Pool], other: dict[str, _Pool]) -> None:
+    for canonical_id, pool in other.items():
+        merged = into.setdefault(canonical_id, _Pool())
+        merged.sources |= pool.sources
+        merged.times.extend(pool.times)
+        merged.created.extend(pool.created)
+
+
+def _decide(pools: dict[str, _Pool]) -> dict[str, RepairMetadata]:
+    # Several legacy memories can fold into one SDK memory. Their evidence is
+    # pooled before deciding, so a disagreeing source stays unknown instead of
+    # whichever link happened to come last.
+    return {
+        canonical_id: RepairMetadata(
+            source=next(iter(pool.sources)) if len(pool.sources) == 1 else None,
+            memory_at=int(max(pool.times).timestamp()) if pool.times else None,
+            created_at=int(min(pool.created).timestamp()) if pool.created else None,
+        )
+        for canonical_id, pool in pools.items()
+    }
+
+
+def _columns(database: sqlite3.Connection, table: str) -> set[str]:
+    return {str(row[1]) for row in database.execute(f"PRAGMA table_info({table})")}
+
+
+def _plausible_time(
+    value: object,
+    *,
+    fallback: object,
+    now: datetime,
+) -> datetime | None:
+    for candidate in (value, fallback):
+        if not isinstance(candidate, str) or not candidate:
+            continue
+        try:
+            parsed = datetime.fromisoformat(candidate)
+        except ValueError:
+            continue
+        if parsed.tzinfo is None:
+            parsed = parsed.replace(tzinfo=UTC)
+        parsed = parsed.astimezone(UTC)
+        if parsed <= now + timedelta(days=1):
+            return parsed
+    return None
+
+
+def _repair_vector(
+    data_dir: Path,
+    mapping: dict[str, RepairMetadata],
+    *,
+    now: datetime,
+) -> int:
+    directory = data_dir / "hy-memory" / HY_MEMORY_NAMESPACE / "vector"
+    if not (directory / "chroma.sqlite3").is_file():
+        return 0
+    from one_memory.sdk_vector_reattach import open_offline_chroma
+
+    client = open_offline_chroma(directory)
+    # The SDK client is not open yet (startup has not created its handle), so
+    # this is the only writer; release the store before the SDK takes it.
+    try:
+        repaired = 0
+        ids = tuple(mapping)
+        for collection in client.list_collections():
+            for batch in _batches(ids):
+                page = collection.get(ids=list(batch), include=["metadatas"])
+                updated_ids: list[str] = []
+                updated_metadata: list[dict[str, object]] = []
+                for memory_id, metadata in zip(
+                    page.get("ids") or (),
+                    page.get("metadatas") or (),
+                    strict=True,
+                ):
+                    if not isinstance(metadata, dict):
+                        continue
+                    desired = mapping.get(str(memory_id))
+                    if desired is None:
+                        continue
+                    next_metadata = dict(metadata)
+                    changed = False
+                    if desired.source and next_metadata.get("source") in {
+                        None,
+                        "",
+                        "default",
+                    }:
+                        next_metadata["source"] = desired.source
+                        changed = True
+                    if (
+                        desired.memory_at is not None
+                        and next_metadata.get("memory_at") != desired.memory_at
+                    ):
+                        next_metadata["memory_at"] = desired.memory_at
+                        changed = True
+                    if (
+                        desired.created_at is not None
+                        and next_metadata.get("gmt_created") != desired.created_at
+                    ):
+                        next_metadata["gmt_created"] = desired.created_at
+                        changed = True
+                    if changed:
+                        updated_ids.append(str(memory_id))
+                        updated_metadata.append(next_metadata)
+                if updated_ids:
+                    collection.update(ids=updated_ids, metadatas=updated_metadata)
+                    repaired += len(updated_ids)
+            repaired += _settle_future_times(collection, now=now)
+    finally:
+        client.close()
+    return repaired
+
+
+def _settle_future_times(collection: Any, *, now: datetime) -> int:
+    """Move conversation times that are still in the future back to the write time.
+
+    A historical Cursor bug stored a file hash as the message time (years like
+    2254). The SDK lists newest first by `memory_at`, so those rows hold the
+    first page. Rows the bundles could date were fixed above; for the rest the
+    write time is the closest true moment that is known.
+    """
+    cutoff = int((now + timedelta(days=1)).timestamp())
+    page = collection.get(where={"memory_at": {"$gt": cutoff}}, include=["metadatas"])
+    updated_ids: list[str] = []
+    updated_metadata: list[dict[str, object]] = []
+    for memory_id, metadata in zip(page.get("ids") or (), page.get("metadatas") or (), strict=True):
+        if not isinstance(metadata, dict):
+            continue
+        created = metadata.get("gmt_created")
+        settled = (
+            created
+            if isinstance(created, int) and not isinstance(created, bool) and created <= cutoff
+            else int(now.timestamp())
+        )
+        updated_ids.append(str(memory_id))
+        updated_metadata.append({**metadata, "memory_at": settled})
+    if updated_ids:
+        collection.update(ids=updated_ids, metadatas=updated_metadata)
+    return len(updated_ids)
+
+
+def _repair_coding(
+    data_dir: Path,
+    mapping: dict[str, RepairMetadata],
+) -> int:
+    root = data_dir / "hy-memory" / HY_MEMORY_NAMESPACE
+    repaired = 0
+    for name in ("coding.sqlite3", "coding_cv.sqlite3"):
+        path = root / name
+        if not path.is_file():
+            continue
+        with closing(sqlite3.connect(path)) as database:
+            tables = {
+                str(row[0])
+                for row in database.execute("SELECT name FROM sqlite_master WHERE type='table'")
+            }
+            for table, identifier in (
+                ("coding_memory_meta", "experience_id"),
+                ("working_fact", "fact_id"),
+            ):
+                if table not in tables:
+                    continue
+                rows = database.execute(
+                    f"SELECT {identifier},source,created_at FROM {table}"
+                ).fetchall()
+                for memory_id, source, created_at in rows:
+                    desired = mapping.get(str(memory_id))
+                    if desired is None:
+                        continue
+                    updates: list[str] = []
+                    values: list[object] = []
+                    if desired.source and source in {None, "", "default"}:
+                        updates.append("source=?")
+                        values.append(desired.source)
+                    if desired.created_at is not None:
+                        desired_created_at = (
+                            datetime.fromtimestamp(desired.created_at, tz=UTC)
+                            .replace(tzinfo=None)
+                            .isoformat()
+                        )
+                        if created_at != desired_created_at:
+                            updates.append("created_at=?")
+                            values.append(desired_created_at)
+                    if not updates:
+                        continue
+                    values.append(memory_id)
+                    database.execute(
+                        f"UPDATE {table} SET {','.join(updates)} WHERE {identifier}=?",
+                        values,
+                    )
+                    repaired += 1
+            database.commit()
+    return repaired
+
+
+def _batches[T](values: list[T] | tuple[T, ...]) -> Iterator[tuple[T, ...]]:
+    for start in range(0, len(values), _BATCH):
+        yield tuple(values[start : start + _BATCH])

memhub/apps/core/src/one_memory/hy_sdk_runtime.py

@@ -237,15 +237,9 @@ def build_sdk_config(
 
     root = data_dir.resolve() / "hy-memory" / "governed-v2"
     root.mkdir(parents=True, exist_ok=True)
-    collection_identity = "\0".join(
-        (
-            embedding_provider.value,
-            embedding_endpoint or "local",
-            embedding_model,
-            str(dimensions or "auto"),
-        )
+    collection = _collection_base(
+        embedding_provider, embedding_endpoint, embedding_model, dimensions
     )
-    collection = "memhub_" + hashlib.sha256(collection_identity.encode()).hexdigest()[:16]
 
     return MemoryConfig.from_dict(
         {
@@ -348,6 +342,49 @@ def _generation_access(
     return endpoint, api_key
 
 
+def _collection_base(
+    provider: ProviderKind,
+    endpoint: str | None,
+    model: str,
+    dimensions: int | None,
+) -> str:
+    identity = "\0".join((provider.value, endpoint or "local", model, str(dimensions or "auto")))
+    return "memhub_" + hashlib.sha256(identity.encode()).hexdigest()[:16]
+
+
+def vector_collection_bases(profile: ModelProfileSnapshot) -> tuple[str, tuple[str, ...]]:
+    """The SDK vector collection base for this embedding space, and the older ones.
+
+    The SDK derives every vector collection (chat, Coding keys, Working facts,
+    each variant) by suffixing this base. Builds before #145 named the same
+    embedding space `one_memory_<12 hex>`, with or without a declared width;
+    the offline migration renames those so their vectors stay readable.
+    """
+    provider = profile.embedding_provider_kind or profile.provider_kind
+    local = provider is ProviderKind.LOCAL_ONNX
+    model = profile.embedding_model or (BUILTIN_EMBEDDING_MODEL if local else None)
+    if not model:
+        raise HySdkRuntimeError("hy_sdk_embedding_model_required")
+    endpoint: str | None
+    dimensions: int | None
+    if local:
+        endpoint, dimensions = None, profile.embedding_dimensions or BUILTIN_EMBEDDING_DIMENSIONS
+        legacy_endpoint = "local-onnx"
+    else:
+        endpoint = _openai_endpoint(provider, profile.embedding_base_url or profile.base_url)
+        dimensions = profile.embedding_dimensions
+        legacy_endpoint = endpoint
+    legacy_model = profile.embedding_model or "bge-small-zh-v1.5"
+    legacy = tuple(
+        "one_memory_"
+        + hashlib.sha256(
+            ":".join((provider.value, legacy_endpoint, legacy_model, *declared)).encode()
+        ).hexdigest()[:12]
+        for declared in ((), ("auto",), (str(profile.embedding_dimensions or "auto"),))
+    )
+    return _collection_base(provider, endpoint, model, dimensions), tuple(dict.fromkeys(legacy))
+
+
 def _openai_endpoint(provider: ProviderKind, endpoint: str | None) -> str:
     value = (endpoint or "").rstrip("/")
     if not value:

memhub/apps/core/src/one_memory/hy_sdk_types.py

@@ -92,9 +92,35 @@ class HySdkMemoryPage(BaseModel):
     total: int = Field(ge=0)
     limit: int = Field(ge=1)
     offset: int = Field(ge=0)
+    # Set on a search whose relevance window was full: matches were looked for
+    # only among this many most relevant memories, so `total` may undercount.
+    search_window: int | None = None
 
     @classmethod
     def from_sdk(cls, raw: object, *, limit: int, offset: int) -> HySdkMemoryPage:
+        page, _skipped = cls._parse(raw, limit=limit, offset=offset, skip_invalid=False)
+        return page
+
+    @classmethod
+    def from_sdk_skipping_invalid(
+        cls, raw: object, *, limit: int, offset: int
+    ) -> tuple[HySdkMemoryPage, int]:
+        """Parse a page, leaving out rows outside the public record contract.
+
+        Returns the page and how many rows were left out, so the caller can
+        report them. The rows themselves are never touched.
+        """
+        return cls._parse(raw, limit=limit, offset=offset, skip_invalid=True)
+
+    @classmethod
+    def _parse(
+        cls,
+        raw: object,
+        *,
+        limit: int,
+        offset: int,
+        skip_invalid: bool,
+    ) -> tuple[HySdkMemoryPage, int]:
         if not isinstance(raw, Mapping):
             raise HySdkReadError("hy_memory_list_shape_unknown")
         rows: list[object] = []
@@ -115,15 +141,27 @@ class HySdkMemoryPage(BaseModel):
             total += bucket_total
             rows.extend(bucket[rows_name])
         deduplicated: dict[str, HySdkMemoryRecord] = {}
+        skipped = 0
         for row in rows:
-            record = HySdkMemoryRecord.from_sdk(row)
+            try:
+                record = HySdkMemoryRecord.from_sdk(row)
+            except HySdkReadError:
+                if not skip_invalid:
+                    raise
+                skipped += 1
+                continue
             deduplicated.setdefault(record.memory_id, record)
-        return cls(
+        page = cls(
             memories=tuple(deduplicated.values()),
+            # `total` is the SDK's stable result-set count. Subtracting only
+            # invalid rows observed on this page would make it change as the
+            # caller paged. Until the SDK exposes a quarantined count, keep the
+            # authoritative total and skip malformed rows only in this page.
             total=total,
             limit=limit,
             offset=offset,
         )
+        return page, skipped
 
 
 class HySdkRawRecord(BaseModel):
@@ -289,6 +327,38 @@ def parse_sdk_search(raw: object, *, error_code: str) -> tuple[SemanticMemoryHit
     return tuple(found)
 
 
+def library_keyword_hits(raw: object, query: str) -> tuple[tuple[str, ...], int]:
+    """Ids in an SDK search window whose text contains every query term.
+
+    The local SDK store has no keyword channel (Chroma's keyword search is
+    empty), so search is pure vector similarity: a word in the library can
+    score below the floor, and a word in none of it still scores above. The
+    library search asks the SDK for its most relevant window and keeps only the
+    rows that actually contain the words, most relevant first. Returns those ids
+    and how many distinct rows the window held.
+    """
+    rows = _reply_rows(raw, "hy_memory_search_shape_unknown")
+    terms = query.casefold().split()
+    seen: set[str] = set()
+    matched: list[str] = []
+    for item in sorted(rows, key=_score, reverse=True):
+        memory_id = item.get("memory_id") or item.get("id")
+        if not isinstance(memory_id, str) or not memory_id or memory_id in seen:
+            continue
+        seen.add(memory_id)
+        content = item.get("content")
+        tags = item.get("tags")
+        text = " ".join(
+            [
+                content if isinstance(content, str) else "",
+                *(tag for tag in (tags if isinstance(tags, list) else ()) if isinstance(tag, str)),
+            ]
+        ).casefold()
+        if all(term in text for term in terms):
+            matched.append(memory_id)
+    return tuple(matched), len(seen)
+
+
 def parse_sdk_raw_search(raw: object) -> tuple[HySdkRawHit, ...]:
     return tuple(
         HySdkRawHit.from_sdk_search(row)

memhub/apps/core/src/one_memory/imports/access.py

@@ -50,6 +50,10 @@ class AuthorizedSourceFile:
     size: int
     modified_ns: int
     changed_ns: int
+    # Source-specific change token (for example Cursor's WAL identity). It is
+    # cursor metadata only; modified_ns remains the real filesystem mtime used
+    # as a fallback conversation timestamp.
+    cursor_version: str | None = None
     root_identity: str | None = None
     requested_root: Path | None = None
     access_check: Callable[[], None] | None = field(default=None, repr=False, compare=False)

memhub/apps/core/src/one_memory/imports/sources/common.py

@@ -644,7 +644,7 @@ def is_unchanged(source_file: AuthorizedSourceFile, cursors: dict[str, SourceCur
     return (
         previous is not None
         and previous.read_to_end
-        and previous.file_identity == source_file.file_identity
+        and previous.file_identity == _cursor_file_identity(source_file)
         and previous.observed_size == source_file.size
         and previous.observed_modified_ns == source_file.modified_ns
         # Chmod alone leaves size, mtime and inode untouched, so a file that
@@ -691,7 +691,7 @@ def touched_cursor(
     previous = options.cursors.get(source_file.safe_id)
     keep = (
         previous is not None
-        and previous.file_identity == source_file.file_identity
+        and _same_file(previous, source_file)
         and previous.observed_size <= source_file.size
     )
     # A kept cursor means the next scan resumes exactly where this one ended:
@@ -871,7 +871,7 @@ def resume_checkpoint(
     previous = options.cursors.get(source_file.safe_id)
     if previous is None:
         return None
-    if previous.file_identity != source_file.file_identity:
+    if not _same_file(previous, source_file):
         return None
     if source_file.size < previous.observed_size:
         return None
@@ -1046,7 +1046,7 @@ def source_cursor(
 ) -> SourceCursor:
     return SourceCursor(
         file_key=source_file.safe_id,
-        file_identity=source_file.file_identity,
+        file_identity=_cursor_file_identity(source_file),
         checkpoint=checkpoint,
         checkpoint_anchor=checkpoint_anchor,
         observed_size=source_file.size,
@@ -1054,6 +1054,27 @@ def source_cursor(
     )
 
 
+def _cursor_file_identity(source_file: AuthorizedSourceFile) -> str:
+    return (
+        f"{source_file.file_identity}{_VERSION_SEPARATOR}{source_file.cursor_version}"
+        if source_file.cursor_version
+        else source_file.file_identity
+    )
+
+
+_VERSION_SEPARATOR = ":v:"
+
+
+def _same_file(previous: SourceCursor, source_file: AuthorizedSourceFile) -> bool:
+    """Whether a stored cursor still points into this file.
+
+    The stored identity may carry a change token (Cursor's WAL version). The
+    token says the file changed, which `is_unchanged` handles; it does not mean
+    the file was replaced, so resuming compares the bare `dev:ino` only.
+    """
+    return previous.file_identity.partition(_VERSION_SEPARATOR)[0] == source_file.file_identity
+
+
 _POSITION = re.compile(r"(?<=:)\d+(?=:|$)")
 
 

memhub/apps/core/src/one_memory/imports/sources/cursor_unified.py

@@ -533,8 +533,8 @@ def _with_write_ahead_log(database: AuthorizedSourceFile) -> AuthorizedSourceFil
     version = hashlib.blake2b(
         f"{database.modified_ns}:{journal.st_mtime_ns}:{journal.st_size}:{journal.st_ino}".encode(),
         digest_size=8,
-    ).digest()
-    return replace(database, modified_ns=int.from_bytes(version, "big") & ((1 << 63) - 1))
+    ).hexdigest()
+    return replace(database, cursor_version=version)
 
 
 def _live_baseline(listing: _CursorListing) -> dict[str, SourceCursor]:

memhub/apps/core/src/one_memory/live_capture.py

@@ -79,9 +79,9 @@ SDK_MIGRATION_CAPTURE_FENCE = ".sdk-migration-capture-fence.json"
 
 
 def database_path() -> Path:
-    from one_memory.workbuddy_boundary import database_path as boundary_database
+    from one_memory.config import load_settings
 
-    return boundary_database()
+    return load_settings().data_dir / "one-memory.sqlite3"
 
 
 def capture_stdio(source_id: str, stdin: TextIO, output: TextIO) -> int:

memhub/apps/core/src/one_memory/local_embedding.py

@@ -10,16 +10,12 @@ weights alone.
 from __future__ import annotations
 
 import threading
-from dataclasses import dataclass
-from hashlib import sha256
 from importlib import import_module
 from typing import TYPE_CHECKING, Any
 
 from one_memory.embedding_assets import (
     BUILTIN_EMBEDDING_DIMENSIONS,
     BUILTIN_EMBEDDING_MAX_TOKENS,
-    EMBEDDING_ASSETS,
-    AssetVerificationError,
     MissingEmbeddingAssetsError,
     assets_present,
     resolve_asset_dir,
@@ -34,28 +30,6 @@ _FETCH_HINT = (
 )
 
 
-@dataclass(frozen=True)
-class TokenOffset:
-    """Half-open Python Unicode code point offsets; synthetic specials use [0,0)."""
-
-    start_cp: int
-    end_cp: int
-    special: bool = False
-
-
-@dataclass(frozen=True)
-class TokenizedText:
-    """Untruncated, unpadded encoding, including tokenizer postprocessor specials."""
-
-    token_ids: tuple[int, ...]
-    offsets: tuple[TokenOffset, ...]
-
-    def __post_init__(self) -> None:
-        # Defensive copies also keep runtime callers from retaining mutable lists.
-        object.__setattr__(self, "token_ids", tuple(self.token_ids))
-        object.__setattr__(self, "offsets", tuple(self.offsets))
-
-
 class LocalEmbedder:
     """Encodes text with the built-in model, loading it on first use."""
 
@@ -68,43 +42,6 @@ class LocalEmbedder:
         self._session: Any | None = None
         self._tokenizer: Any | None = None
         self._input_names: frozenset[str] = frozenset()
-        self._offset_lock = threading.Lock()
-        self._offset_tokenizer: Any | None = None
-
-    def tokenize_with_offsets(self, text: str) -> TokenizedText:
-        """Tokenize original text without encode()'s truncation or batch padding.
-
-        The Python tokenizers binding returns code point offsets into the input,
-        even when its model normalizer changes spelling. This separate lazy
-        tokenizer uses the exact locked asset; it never loads an ONNX session or
-        mutates the tokenizer shared by encode(). Offsets are not UTF-16 indices.
-        """
-        if not isinstance(text, str):
-            raise TypeError("embedding_offsets_require_text")
-        with self._offset_lock:
-            if self._offset_tokenizer is None:
-                directory = resolve_asset_dir()
-                path = directory / "tokenizer.json"
-                if not path.is_file():
-                    raise MissingEmbeddingAssetsError(f"{_FETCH_HINT} Looked in {directory}.")
-                data = path.read_bytes()
-                expected = next(a.sha256 for a in EMBEDDING_ASSETS if a.filename == path.name)
-                if sha256(data).hexdigest() != expected:
-                    raise AssetVerificationError("tokenizer.json: locked digest mismatch")
-                from tokenizers import Tokenizer
-
-                tokenizer = Tokenizer.from_str(data.decode("utf-8"))
-                tokenizer.no_truncation()
-                tokenizer.no_padding()
-                self._offset_tokenizer = tokenizer
-            encoding = self._offset_tokenizer.encode(text, add_special_tokens=True)
-            offsets = tuple(
-                TokenOffset(start, end, bool(special))
-                for (start, end), special in zip(
-                    encoding.offsets, encoding.special_tokens_mask, strict=True
-                )
-            )
-            return TokenizedText(tuple(encoding.ids), offsets)
 
     def _load(self) -> tuple[Any, Any]:
         # Double-checked under a lock: memory processing encodes from worker

memhub/apps/core/src/one_memory/memory_library.py

@@ -1,342 +0,0 @@
-"""Read-only local library projection over the existing governed memory store."""
-
-import json
-import os
-import sqlite3
-import time
-from pathlib import Path
-from typing import Literal
-
-from pydantic import BaseModel, ConfigDict, Field
-
-from one_memory.database_access import main_database
-from one_memory.legacy_lifecycle_types import HyLifecycle
-from one_memory.memory_evidence_freshness import register_memory_freshness
-from one_memory.memory_governance import (
-    GovernedMemory,
-    MemoryGovernanceStore,
-    MemoryStatus,
-    lifecycle_predicate,
-)
-
-#: Read budget for one library page. 2026-10-12: raised from 5s (which starved
-#: under a concurrent history import and surfaced as 503) to 15s, still well
-#: under the 30s client timeout; past it the read degrades to a `stale` page.
-READ_BUDGET_SECONDS = 15
-
-
-class MemorySourceTime(BaseModel):
-    """When the conversation a memory came from happened (D96).
-
-    `basis` is `conversation` when the cited messages carry their own time,
-    `import` when only the import time is known; the UI words them apart.
-    """
-
-    model_config = ConfigDict(frozen=True, extra="forbid")
-
-    at: str
-    basis: Literal["conversation", "import"]
-
-
-class MemoryLibraryPage(BaseModel):
-    model_config = ConfigDict(frozen=True, extra="forbid")
-
-    items: list[GovernedMemory]
-    total: int = Field(ge=0)
-    offset: int = Field(ge=0)
-    limit: int = Field(ge=1, le=500)
-    source_ids_by_memory: dict[str, list[str]] = Field(default_factory=dict)
-    source_time_by_memory: dict[str, MemorySourceTime] = Field(default_factory=dict)
-    #: True when the read budget ran out mid-page (typically during a history
-    #: import): the counts and rows above are a partial snapshot, not an
-    #: authoritative view. Clients should show "importing" instead of an error.
-    stale: bool = False
-
-
-def _sort_by_conversation() -> bool:
-    """D99: the list reads as a timeline of the conversations, newest first.
-
-    A memory generated today from a three-week-old dialogue belongs next to
-    that week, not at the top. ONE_MEMORY_LIBRARY_SORT=updated brings back the
-    old "newest generated first" order without a code change.
-    """
-    return os.environ.get("ONE_MEMORY_LIBRARY_SORT", "").strip().lower() != "updated"
-
-
-def _origin_join() -> str:
-    """The newest cited message per memory, as one joined aggregate.
-
-    A correlated subquery would re-scan the link table for every candidate row;
-    this is a single pass. Memories with no readable citation keep their old
-    position through COALESCE.
-    """
-    if not _sort_by_conversation():
-        return ""
-    return """LEFT JOIN (
-        SELECT link.memory_id AS memory_id,
-               MAX(COALESCE(e.created_at, e.imported_at)) AS origin_at
-        FROM governed_memory_evidence link
-        JOIN evidence e ON e.evidence_id = link.evidence_id
-        WHERE link.active = 1
-        GROUP BY link.memory_id
-    ) origin ON origin.memory_id = m.memory_id"""
-
-
-def _order_by() -> str:
-    if not _sort_by_conversation():
-        return "m.updated_at DESC, m.memory_id ASC"
-    # Conversations that share a timestamp keep the generated order between
-    # themselves; ties would otherwise fall back to the id and look arbitrary.
-    return "COALESCE(origin.origin_at, m.updated_at) DESC, m.updated_at DESC, m.memory_id ASC"
-
-
-class _LibraryQuery(BaseModel):
-    model_config = ConfigDict(frozen=True, extra="forbid")
-
-    user_id: str = Field(min_length=1, max_length=256)
-    query: str | None = None
-    status: MemoryStatus | None = None
-    active_only: bool = False
-    source: str | None = Field(default=None, min_length=1)
-    offset: int = Field(default=0, ge=0, le=2**63 - 1, strict=True)
-    limit: int = Field(default=100, ge=1, le=500, strict=True)
-
-
-def read_conversation_memories(
-    database_path: Path,
-    *,
-    user_id: str,
-    source_id: str,
-    conversation_id: str,
-    workspace: str | None,
-    limit: int = 100,
-) -> list[GovernedMemory]:
-    """Current memories backed by any active Evidence in one conversation."""
-    with main_database(database_path).read() as db:
-        db.row_factory = sqlite3.Row
-        freshness = register_memory_freshness(db)
-        rows = db.execute(
-            f"""
-            SELECT DISTINCT m.* FROM governed_memories m
-            JOIN governed_memory_evidence link ON link.memory_id=m.memory_id AND link.active=1
-            JOIN evidence e ON e.evidence_id=link.evidence_id
-            WHERE m.user_id=? AND m.status='confirmed' AND m.deleted_at IS NULL
-              AND e.user_id=? AND e.source_id=? AND e.conversation_id=?
-              AND e.workspace IS ? AND {freshness}
-            ORDER BY m.updated_at DESC, m.memory_id
-            LIMIT ?
-            """,
-            (user_id, user_id, source_id, conversation_id, workspace, limit),
-        ).fetchall()
-        return MemoryGovernanceStore.memories_from_rows(db, rows)
-
-
-def read_memory_library(
-    database_path: Path,
-    *,
-    user_id: str = "local",
-    query: str | None = None,
-    status: MemoryStatus | None = None,
-    active_only: bool = False,
-    source: str | None = None,
-    offset: int = 0,
-    limit: int = 100,
-    lifecycle: HyLifecycle | None = None,
-) -> MemoryLibraryPage:
-    """Read one page and its exact readable total from the same SQLite snapshot.
-
-    This is the local UI policy, not an external agent authorization entry point.
-    Missing grants do not revoke already stored content; explicit revocations do.
-    Read/parse failures propagate rather than masquerading as an empty library.
-    Which memories are current is HY's `lifecycle` when given, as in
-    `MemoryGovernanceStore.list`.
-    """
-    request = _LibraryQuery(
-        user_id=user_id,
-        query=query,
-        status=status,
-        active_only=active_only,
-        source=source,
-        offset=offset,
-        limit=limit,
-    )
-    if request.active_only and request.status is not None:
-        raise ValueError("active_only_conflicts_with_status")
-    clauses = ["m.user_id = ?"]
-    values: list[str | int] = [request.user_id]
-    selected, selected_values = lifecycle_predicate(
-        lifecycle, MemoryStatus.CONFIRMED if request.active_only else request.status, alias="m"
-    )
-    if selected is not None:
-        clauses.append(selected)
-        values.extend(selected_values)
-    if request.status != MemoryStatus.DELETED:
-        clauses.append("m.deleted_at IS NULL")
-
-    # SourceReadAccess hides the whole memory if any active citation is revoked.
-    # Do this before COUNT/LIMIT; a readable citation cannot rescue a mixed memory.
-    clauses.append("""NOT EXISTS (
-        SELECT 1 FROM governed_memory_evidence link
-        JOIN evidence e ON e.evidence_id = link.evidence_id
-        JOIN source_grants g ON g.user_id = e.user_id AND g.source_id = e.source_id
-        WHERE link.memory_id = m.memory_id AND +link.active = 1
-          AND g.revoked_at IS NOT NULL
-    )""")
-    # Governance normally guarantees ownership and referential integrity. Fail
-    # closed for broken active links instead of exposing another user's citation.
-    clauses.append("""NOT EXISTS (
-        SELECT 1 FROM governed_memory_evidence link
-        LEFT JOIN evidence e ON e.evidence_id = link.evidence_id
-        WHERE link.memory_id = m.memory_id AND +link.active = 1
-          AND (e.evidence_id IS NULL OR e.user_id != m.user_id)
-    )""")
-    if request.query:
-        clauses.append("m.content LIKE ? ESCAPE '\\'")
-        escaped = request.query.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
-        values.append(f"%{escaped}%")
-    if request.source is not None:
-        # Start from the compact active-link index, then resolve each Evidence
-        # identity by primary key. The old correlated EXISTS let SQLite scan
-        # every Evidence row for every candidate memory on large libraries.
-        clauses.append("""m.memory_id IN (
-            SELECT link.memory_id FROM governed_memory_evidence link
-            JOIN evidence e ON e.evidence_id = link.evidence_id
-            WHERE link.active = 1 AND e.user_id = ? AND e.source_id = ?
-        )""")
-        values.extend((request.user_id, request.source))
-    predicate = " AND ".join(clauses)
-
-    def _interrupted(error: Exception) -> bool:
-        return isinstance(error, sqlite3.OperationalError) and "interrupted" in str(error).lower()
-
-    with main_database(database_path).read() as db:
-        # 2026-10-12: 5s starved the page whenever a history import saturated
-        # SQLite, and the caller turned the deadline abort into a 503, so the
-        # memory page read as broken for the whole import. 15s stays well under
-        # the 30s client timeout; past it we return a `stale` page instead of
-        # an error — an incomplete list is honest, an error is not.
-        deadline = time.monotonic() + READ_BUDGET_SECONDS
-        db.set_progress_handler(lambda: int(time.monotonic() >= deadline), 1000)
-        db.row_factory = sqlite3.Row
-        db.execute("BEGIN")
-        # The total counts with the cheap permission filters only: the per-row
-        # freshness UDF scales with the whole library and can burn the whole
-        # read budget on its own (D22). Product accepted a small drift here;
-        # the rows that are actually displayed are still checked row by row.
-        try:
-            total = db.execute(
-                f"SELECT COUNT(*) FROM governed_memories m WHERE {predicate}", values
-            ).fetchone()[0]
-        except sqlite3.OperationalError as error:
-            if not _interrupted(error):
-                raise
-            return MemoryLibraryPage(
-                items=[],
-                total=0,
-                offset=request.offset,
-                limit=request.limit,
-                stale=True,
-            )
-        predicate += " AND " + register_memory_freshness(db)
-        try:
-            if request.query:
-                current = db.execute(
-                    f"""SELECT m.* FROM governed_memories m {_origin_join()}
-                    WHERE {predicate}
-                    ORDER BY {_order_by()}""",
-                    values,
-                ).fetchall()
-                rows = current[request.offset : request.offset + request.limit]
-            else:
-                rows = db.execute(
-                    f"""SELECT m.* FROM governed_memories m {_origin_join()}
-                    WHERE {predicate}
-                    ORDER BY {_order_by()} LIMIT ? OFFSET ?""",
-                    [*values, request.limit, request.offset],
-                ).fetchall()
-        except sqlite3.OperationalError as error:
-            if not _interrupted(error):
-                raise
-            # The count already succeeded: report it, flag the page stale.
-            return MemoryLibraryPage(
-                items=[],
-                total=total,
-                offset=request.offset,
-                limit=request.limit,
-                stale=True,
-            )
-        # Static read helper only: constructing the Store would initialize schema.
-        items = MemoryGovernanceStore.memories_from_rows(db, rows, lifecycle=lifecycle)
-        # Only the authorized page participates; source filters select memories,
-        # not a subset of their provenance. Keep this in the count/page snapshot.
-        source_ids_by_memory: dict[str, list[str]] = {item.memory_id: [] for item in items}
-        # D96: the list shows when the cited conversation happened, not when
-        # the memory was generated (which is "today" for a fresh import). Read
-        # in the same query as the sources, so the page costs no extra round
-        # trip and only this page's IDs are looked at, never the whole library.
-        conversation_at: dict[str, str] = {}
-        imported_at: dict[str, str] = {}
-        if items:
-            try:
-                for link in db.execute(
-                    # D104: the conversation time is when the person spoke, not
-                    # when the turn ended. A memory's evidence covers the whole
-                    # round (question, tool calls, reply), so MAX() lands on the
-                    # reply and reads as a later, contradictory time next to the
-                    # cited source. Prefer the earliest person-side evidence; only
-                    # fall back to the earliest of any kind when the round has no
-                    # person-authored row at all.
-                    """SELECT link.memory_id, e.source_id,
-                           COALESCE(
-                               MIN(
-                                   CASE WHEN e.role = 'user'
-                                         AND e.role = 'user'
-                                        THEN e.created_at END
-                               ),
-                               MIN(e.created_at)
-                           ) AS conversation_at,
-                           MAX(e.imported_at) AS imported_at
-                    FROM governed_memory_evidence link
-                    JOIN evidence e ON e.evidence_id = link.evidence_id
-                    WHERE link.active = 1 AND e.user_id = ?
-                      AND link.memory_id IN (SELECT value FROM json_each(?))
-                    GROUP BY link.memory_id, e.source_id
-                    ORDER BY link.memory_id, e.source_id""",
-                    (request.user_id, json.dumps(list(source_ids_by_memory))),
-                ):
-                    memory_id = link["memory_id"]
-                    source_ids_by_memory[memory_id].append(link["source_id"])
-                    for seen, value in (
-                        (conversation_at, link["conversation_at"]),
-                        (imported_at, link["imported_at"]),
-                    ):
-                        if value and str(value) > seen.get(memory_id, ""):
-                            seen[memory_id] = str(value)
-            except sqlite3.OperationalError as error:
-                if not _interrupted(error):
-                    raise
-                # Page rows are already read; ship them without source maps
-                # rather than failing the whole request at the last step.
-                return MemoryLibraryPage(
-                    items=items,
-                    total=total,
-                    offset=request.offset,
-                    limit=request.limit,
-                    source_ids_by_memory=source_ids_by_memory,
-                    stale=True,
-                )
-        source_time_by_memory = {
-            memory_id: MemorySourceTime(at=conversation_at[memory_id], basis="conversation")
-            if memory_id in conversation_at
-            else MemorySourceTime(at=imported_at[memory_id], basis="import")
-            for memory_id in source_ids_by_memory
-            if memory_id in conversation_at or memory_id in imported_at
-        }
-        return MemoryLibraryPage(
-            items=items,
-            total=total,
-            offset=request.offset,
-            limit=request.limit,
-            source_ids_by_memory=source_ids_by_memory,
-            source_time_by_memory=source_time_by_memory,
-        )

memhub/apps/core/src/one_memory/memory_mutation_receipts.py

@@ -1,180 +0,0 @@
-"""Bounded, permission-aware receipt projection; never initialize a write store."""
-
-import sqlite3
-from pathlib import Path
-from typing import Literal
-
-from pydantic import BaseModel, ConfigDict
-
-from one_memory.database_access import main_database
-
-#: `legacy` is a confirmation recorded before memories stopped waiting for
-#: one; it changed nothing that still exists, and `migrated_from` says so.
-Operation = Literal["create", "correct", "set_scopes", "undo", "delete", "hy_reconcile", "legacy"]
-ResultStatus = Literal["confirmed", "deleted"]
-MigratedFrom = Literal["confirm", "reject"]
-OPERATIONS = {"create", "correct", "set_scopes", "undo", "delete", "hy_reconcile", "legacy"}
-STATUSES = {"confirmed", "deleted"}
-#: Which operation each pre-v2 one now reads as.
-MIGRATED_OPERATIONS = {"confirm": "legacy", "reject": "delete"}
-#: A memory may move on to these after an earlier receipt was written; the
-#: receipt still reports what that request committed, not the current status.
-CURRENT_STATUSES = STATUSES | {"superseded"}
-
-
-class MemoryMutationReceiptForbidden(RuntimeError):
-    def __init__(self) -> None:
-        super().__init__("memory_mutation_receipt_forbidden")
-
-
-class MemoryMutationReceiptUnavailable(RuntimeError):
-    def __init__(self) -> None:
-        super().__init__("memory_mutation_receipt_unavailable")
-
-
-class MemoryMutationReceipt(BaseModel):
-    model_config = ConfigDict(frozen=True, extra="forbid")
-    schema_version: Literal[2] = 2
-    request_id: str
-    state: Literal["not_found", "committed"]
-    operation: Operation | None = None
-    memory_id: str | None = None
-    result_revision: int | None = None
-    result_status: ResultStatus | None = None
-    memory_state: Literal["present", "deleted"] | None = None
-    #: The operation as it was stored before v2, when it has no v2 name of its own.
-    migrated_from: MigratedFrom | None = None
-
-
-def _identity(value: str, maximum: int) -> bool:
-    return isinstance(value, str) and 0 < len(value) <= maximum
-
-
-def _read_snapshot(
-    database_path: Path, request_id: str, user_id: str
-) -> tuple[MemoryMutationReceipt, tuple[object, ...]]:
-    with main_database(database_path).read(row_factory=sqlite3.Row) as db:
-        db.execute("PRAGMA query_only=ON")
-        db.execute("BEGIN")
-        rows = db.execute(
-            "SELECT user_id,request_id,memory_id,operation,result_revision "
-            "FROM governed_memory_mutations WHERE user_id=? AND request_id=? LIMIT 2",
-            (user_id, request_id),
-        ).fetchall()
-        if not rows:
-            return MemoryMutationReceipt(request_id=request_id, state="not_found"), ()
-        if len(rows) != 1:
-            raise MemoryMutationReceiptUnavailable()
-        mutation = rows[0]
-        memory_id, operation, revision = (
-            mutation["memory_id"],
-            mutation["operation"],
-            mutation["result_revision"],
-        )
-        if (
-            not _identity(memory_id, 512)
-            or operation not in OPERATIONS
-            or type(revision) is not int
-            or not 1 <= revision <= 2**53 - 1
-        ):
-            raise MemoryMutationReceiptUnavailable()
-        current = db.execute(
-            "SELECT user_id,revision,status,deleted_at FROM governed_memories WHERE memory_id=?",
-            (memory_id,),
-        ).fetchone()
-        if (
-            current is None
-            or current["user_id"] != user_id
-            or type(current["revision"]) is not int
-            or current["revision"] < revision
-            or current["status"] not in CURRENT_STATUSES
-            or (current["status"] == "deleted") != (current["deleted_at"] is not None)
-        ):
-            raise MemoryMutationReceiptUnavailable()
-
-        # Versions have no historical evidence snapshot. Check every retained link,
-        # not only active ones, before disclosing even operation/ID metadata.
-        links = db.execute(
-            "SELECT l.evidence_id,l.active,e.user_id,e.source_id,e.revision,"
-            "g.granted_at,g.revoked_at FROM governed_memory_evidence l "
-            "LEFT JOIN evidence e ON e.evidence_id=l.evidence_id "
-            "LEFT JOIN source_grants g ON g.user_id=e.user_id AND g.source_id=e.source_id "
-            "WHERE l.memory_id=? ORDER BY l.evidence_id LIMIT 10001",
-            (memory_id,),
-        ).fetchall()
-        if not links or len(links) > 10000:
-            raise MemoryMutationReceiptUnavailable()
-        for link in links:
-            if (
-                link["user_id"] != user_id
-                or link["source_id"] is None
-                or link["active"] not in (0, 1)
-            ):
-                raise MemoryMutationReceiptUnavailable()
-            if link["revoked_at"] is not None:
-                raise MemoryMutationReceiptForbidden()
-        versions = db.execute(
-            "SELECT memory_id,revision,action,status,migrated_from FROM governed_memory_versions "
-            "WHERE memory_id=? AND revision=? LIMIT 2",
-            (memory_id, revision),
-        ).fetchall()
-        if len(versions) != 1:
-            raise MemoryMutationReceiptUnavailable()
-        version = versions[0]
-        if version["action"] != operation or version["status"] not in STATUSES:
-            raise MemoryMutationReceiptUnavailable()
-        migrated_from = version["migrated_from"]
-        if migrated_from is not None and MIGRATED_OPERATIONS.get(migrated_from) != operation:
-            raise MemoryMutationReceiptUnavailable()
-        if (operation == "legacy") != (migrated_from == "confirm"):
-            raise MemoryMutationReceiptUnavailable()
-        required_status = {
-            "create": "confirmed",
-            "legacy": "confirmed",
-            "delete": "deleted",
-        }
-        if operation in required_status and version["status"] != required_status[operation]:
-            raise MemoryMutationReceiptUnavailable()
-        if (operation == "create") != (revision == 1):
-            raise MemoryMutationReceiptUnavailable()
-        if (
-            operation in {"correct", "set_scopes", "hy_reconcile", "undo"}
-            and version["status"] != "confirmed"
-        ):
-            raise MemoryMutationReceiptUnavailable()
-        receipt = MemoryMutationReceipt(
-            request_id=request_id,
-            state="committed",
-            operation=operation,
-            memory_id=memory_id,
-            result_revision=revision,
-            result_status=version["status"],
-            memory_state="deleted" if current["status"] == "deleted" else "present",
-            migrated_from=migrated_from,
-        )
-        return receipt, (
-            tuple(mutation),
-            tuple(current),
-            tuple(version),
-            tuple(tuple(link) for link in links),
-        )
-
-
-def read_memory_mutation_receipt(
-    database_path: Path, *, request_id: str, user_id: str = "local"
-) -> MemoryMutationReceipt:
-    """History only, never current authorization, HY cleanup or safe-retry proof."""
-    if not _identity(request_id, 256):
-        raise ValueError("invalid_memory_mutation_request_id")
-    if not _identity(user_id, 256):
-        raise ValueError("invalid_memory_mutation_user_id")
-    try:
-        first = _read_snapshot(database_path, request_id, user_id)
-        current = _read_snapshot(database_path, request_id, user_id)
-        if first != current:
-            raise MemoryMutationReceiptUnavailable()
-        return current[0]
-    except MemoryMutationReceiptForbidden:
-        raise
-    except (sqlite3.Error, ValueError, TypeError, KeyError, IndexError, OSError):
-        raise MemoryMutationReceiptUnavailable() from None

memhub/apps/core/src/one_memory/memory_notes.py

@@ -67,20 +67,6 @@ class MemoryNoteReceipt(BaseModel):
     error: str | None = None
 
 
-class SavedMemoryNoteEvidence(BaseModel):
-    model_config = ConfigDict(frozen=True, extra="forbid")
-
-    available: Literal[True] = True
-    evidence_id: str
-    source_id: str
-    revision: int
-    imported_at: datetime
-    role: str
-    written_by: WrittenBy
-    created_at: datetime | None
-    verbatim: str
-
-
 class LegacyMemoryNoteReader:
     """Read pre-cutover note receipts without retaining any write runtime."""
 
@@ -441,48 +427,6 @@ def memory_note_router(dependencies: Sequence[Depends]) -> APIRouter:
         except ValueError as error:
             raise HTTPException(409, str(error)) from error
 
-    @router.get("/{evidence_id}/evidence", response_model=SavedMemoryNoteEvidence)
-    def evidence(evidence_id: str, request: Request) -> SavedMemoryNoteEvidence:
-        try:
-            notes = store(request)
-            if notes.sdk_authority:
-                raise HTTPException(409, "memory_note_evidence_retired")
-            with notes.evidence._connect() as connection:
-                record = notes.evidence._get_with_connection(connection, evidence_id)
-                metadata = record.origin_meta.get(EvidenceOrigin.MANUAL_IMPORT) if record else None
-                if (
-                    record is None
-                    or record.user_id != "local"
-                    or record.source_id != SOURCE_ID
-                    or metadata is None
-                    or metadata.raw_meta.get("input_mode") != "direct_memory_note"
-                ):
-                    raise KeyError(evidence_id)
-                grant = connection.execute(
-                    "SELECT revoked_at FROM source_grants WHERE user_id='local' AND source_id=?",
-                    (SOURCE_ID,),
-                ).fetchone()
-                if grant is None or grant[0] is not None:
-                    raise ValueError("memory_note_source_revoked")
-                result = SavedMemoryNoteEvidence(
-                    evidence_id=record.evidence_id,
-                    source_id=record.source_id,
-                    revision=record.revision,
-                    imported_at=record.imported_at,
-                    role=record.role,
-                    written_by=record.written_by,
-                    created_at=record.created_at,
-                    verbatim=record.verbatim,
-                )
-            # The returned body and reference share one snapshot. Recheck authority
-            # after that read so a revoked source is not released from a stale view.
-            notes.require(evidence_id)
-            return result
-        except KeyError as error:
-            raise HTTPException(404, "memory_note_not_found") from error
-        except ValueError as error:
-            raise HTTPException(409, str(error)) from error
-
     @router.post("/{evidence_id}/process", response_model=MemoryNoteReceipt)
     async def process(evidence_id: str, request: Request) -> MemoryNoteReceipt:
         notes = store(request)

memhub/apps/core/src/one_memory/memory_server/durable_queue.py

@@ -316,6 +316,12 @@ LEGACY_MEMORY_WRITE_JOB_COLUMNS = (
 
 _FIFO_BLOCKING_STATES = (PENDING, RUNNING, WAITING_FOR_PERMISSION, WAITING_FOR_MODEL)
 EVENT_TIME_WINDOW = timedelta(minutes=10)
+#: Sources whose jobs are a person adding a memory by hand ("添加记忆"), not
+#: history. History is digested strictly old to new through the event-time
+#: window; a note is stamped "now", so inside that window it waited behind the
+#: whole unprocessed history. These jobs are claimed ahead of the window,
+#: still one at a time per source and in order within their session.
+DIRECT_WRITE_SOURCES = frozenset({"one-memory-manual"})
 
 
 @dataclass(frozen=True)
@@ -2601,6 +2607,39 @@ class DurableWriteDrain:
                 placeholders = ",".join("?" for _ in enabled_sources)
                 source_clause = f"AND candidate.source_key IN ({placeholders}) "
                 source_params = tuple(sorted(enabled_sources))
+            direct_sources = ",".join("?" for _ in DIRECT_WRITE_SOURCES)
+            # Same eligibility as the window claim below (free lease, no
+            # running job of its source, nothing earlier in its session), but
+            # not bound to the window: a note must not wait for history.
+            direct_rows = connection.execute(
+                "SELECT candidate.job_id,candidate.source_key "
+                "FROM memory_write_jobs AS candidate "
+                "WHERE candidate.state=? "
+                "AND (candidate.lease_expires_at IS NULL OR candidate.lease_expires_at < ?) "
+                + source_clause
+                + f"AND candidate.source_key IN ({direct_sources}) "
+                "AND NOT EXISTS ("
+                "SELECT 1 FROM memory_write_jobs AS held "
+                "WHERE held.source_key=candidate.source_key AND held.state=? "
+                "AND held.lease_owner IS NOT NULL AND held.lease_expires_at>=?) "
+                "AND NOT EXISTS ("
+                "SELECT 1 FROM memory_write_jobs AS earlier "
+                "WHERE earlier.session_key=candidate.session_key "
+                f"AND earlier.state IN ({blocking}) "
+                "AND (earlier.event_at<candidate.event_at OR "
+                "(earlier.event_at=candidate.event_at "
+                "AND earlier.queue_seq<candidate.queue_seq))) "
+                "ORDER BY candidate.queue_seq",
+                (
+                    PENDING,
+                    now.isoformat(),
+                    *source_params,
+                    *sorted(DIRECT_WRITE_SOURCES),
+                    RUNNING,
+                    now.isoformat(),
+                    *_FIFO_BLOCKING_STATES,
+                ),
+            ).fetchall()
             window = connection.execute(
                 "SELECT window_anchor,window_end FROM memory_write_schedule_state WHERE singleton=1"
             ).fetchone()
@@ -2654,6 +2693,7 @@ class DurableWriteDrain:
                 if active is None:
                     connection.execute("DELETE FROM memory_write_schedule_state WHERE singleton=1")
                     window = None
+            anchor: Any = None
             if window is None:
                 anchor = connection.execute(
                     "SELECT candidate.event_at "
@@ -2682,8 +2722,10 @@ class DurableWriteDrain:
                         *_FIFO_BLOCKING_STATES,
                     ),
                 ).fetchone()
-                if anchor is None:
+                if anchor is None and not direct_rows:
                     return ()
+            has_window = window is not None or anchor is not None
+            if window is None and anchor is not None:
                 anchor_at = datetime.fromisoformat(str(anchor[0]))
                 if anchor_at.tzinfo is None:
                     anchor_at = anchor_at.replace(tzinfo=UTC)
@@ -2695,39 +2737,41 @@ class DurableWriteDrain:
                     "VALUES (1,?,?,?)",
                     (anchor_text, end_text, now.isoformat()),
                 )
-            rows = connection.execute(
-                "SELECT candidate.job_id,candidate.source_key "
-                "FROM memory_write_jobs AS candidate "
-                "WHERE candidate.state=? "
-                "AND (candidate.lease_expires_at IS NULL OR candidate.lease_expires_at < ?) "
-                + source_clause
-                + "AND candidate.event_at>=? AND candidate.event_at<? "
-                "AND NOT EXISTS ("
-                "SELECT 1 FROM memory_write_jobs AS held "
-                "WHERE held.source_key=candidate.source_key AND held.state=? "
-                "AND held.lease_owner IS NOT NULL AND held.lease_expires_at>=?) "
-                "AND NOT EXISTS ("
-                "SELECT 1 FROM memory_write_jobs AS earlier "
-                "WHERE earlier.session_key=candidate.session_key "
-                f"AND earlier.state IN ({blocking}) "
-                "AND (earlier.event_at<candidate.event_at OR "
-                "(earlier.event_at=candidate.event_at "
-                "AND earlier.queue_seq<candidate.queue_seq))) "
-                "ORDER BY candidate.event_at,candidate.queue_seq",
-                (
-                    PENDING,
-                    now.isoformat(),
-                    *source_params,
-                    anchor_text,
-                    end_text,
-                    RUNNING,
-                    now.isoformat(),
-                    *_FIFO_BLOCKING_STATES,
-                ),
-            ).fetchall()
+            rows: list[Any] = []
+            if has_window:
+                rows = connection.execute(
+                    "SELECT candidate.job_id,candidate.source_key "
+                    "FROM memory_write_jobs AS candidate "
+                    "WHERE candidate.state=? "
+                    "AND (candidate.lease_expires_at IS NULL OR candidate.lease_expires_at < ?) "
+                    + source_clause
+                    + "AND candidate.event_at>=? AND candidate.event_at<? "
+                    "AND NOT EXISTS ("
+                    "SELECT 1 FROM memory_write_jobs AS held "
+                    "WHERE held.source_key=candidate.source_key AND held.state=? "
+                    "AND held.lease_owner IS NOT NULL AND held.lease_expires_at>=?) "
+                    "AND NOT EXISTS ("
+                    "SELECT 1 FROM memory_write_jobs AS earlier "
+                    "WHERE earlier.session_key=candidate.session_key "
+                    f"AND earlier.state IN ({blocking}) "
+                    "AND (earlier.event_at<candidate.event_at OR "
+                    "(earlier.event_at=candidate.event_at "
+                    "AND earlier.queue_seq<candidate.queue_seq))) "
+                    "ORDER BY candidate.event_at,candidate.queue_seq",
+                    (
+                        PENDING,
+                        now.isoformat(),
+                        *source_params,
+                        anchor_text,
+                        end_text,
+                        RUNNING,
+                        now.isoformat(),
+                        *_FIFO_BLOCKING_STATES,
+                    ),
+                ).fetchall()
             selected: list[str] = []
             selected_sources: set[str] = set()
-            for row in rows:
+            for row in (*direct_rows, *rows):
                 source_key = str(row["source_key"])
                 if source_key in selected_sources:
                     continue

memhub/apps/core/src/one_memory/memory_server/migrations.py

@@ -2217,34 +2217,6 @@ CREATE TABLE IF NOT EXISTS retrieval_chunks (
 """
 
 
-def retrieval_documents_v2_ddl(dialect: str = "mysql") -> str:
-    """The v2 documents table under its temporary `_v2` name.
-
-    `index_store.migrate_v2` creates this, copies rows from the v1 table, drops
-    the v1 table and renames. The rename is the only reason a `_v2` name exists
-    at all, and it is derived from the single definition so the copy-across
-    cannot drift from what fresh databases get.
-    """
-    documents = next(
-        statement
-        for statement in _split_statements(retrieval_index_ddl(dialect))
-        if "CREATE TABLE IF NOT EXISTS retrieval_documents (" in statement
-    )
-    return documents.replace(
-        "CREATE TABLE IF NOT EXISTS retrieval_documents (",
-        "CREATE TABLE retrieval_documents_v2 (",
-    )
-
-
-def retrieval_build_maps_ddl(dialect: str = "mysql") -> str:
-    """The build-maps table added by v2."""
-    return next(
-        statement
-        for statement in _split_statements(retrieval_index_ddl(dialect))
-        if "retrieval_build_maps" in statement
-    )
-
-
 async def _033_retrieval_index(cursor: Any) -> None:
     for statement in _split_statements(retrieval_index_ddl(_dialect(cursor))):
         await cursor.execute(statement)

memhub/apps/core/src/one_memory/memory_server/routes.py

@@ -1,7 +1,7 @@
 """A3-01: the HTTP entry to the unified write path.
 
-`POST /api/v1/memory-writes` accepts a write and returns a request id;
-`GET /api/v1/memory-writes/{id}` reports its outcome.
+`POST /api/v2/memory-writes` accepts OpenAI-style messages and returns a
+request id; `GET /api/v2/memory-writes/{id}` reports its outcome.
 
 Two rules shape this endpoint, both consequences of A0-03's measurement that HY
 has no idempotency key:
@@ -45,17 +45,6 @@ from one_memory.memory_server.registry import WriteRegistry, WriteState
 from one_memory.memory_server.submit import WriteConflictError
 
 
-class MemoryWriteInput(BaseModel):
-    model_config = ConfigDict(extra="forbid")
-
-    internal_session_id: str = Field(min_length=1, max_length=128)
-    first_round: int = Field(ge=1)
-    last_round: int = Field(ge=1)
-    evidence_ids: list[str] = Field(min_length=1)
-    priority: Literal["live", "normal"] = "normal"
-    idempotency_key: str | None = Field(default=None, max_length=256)
-
-
 class MemoryWriteReceipt(BaseModel):
     request_id: str
     state: WriteState
@@ -121,67 +110,6 @@ def _registry(
     return cast(WriteRegistry | DurableWriteRegistry, registry)
 
 
-def router(dependencies: list[Any] | None = None) -> APIRouter:
-    instance = APIRouter(
-        prefix="/api/v1/memory-writes",
-        tags=["memory-writes"],
-        dependencies=dependencies or [],
-    )
-
-    @instance.post("", response_model=MemoryWriteReceipt, status_code=202)
-    def submit(payload: MemoryWriteInput, request: Request) -> MemoryWriteReceipt:
-        registry = _registry(request)
-        batch = BatchIdentity(
-            internal_session_id=payload.internal_session_id,
-            first_round=payload.first_round,
-            last_round=payload.last_round,
-        )
-        request_contract = WriteRequest(
-            internal_session_id=payload.internal_session_id,
-            batch_identity=batch,
-            evidence_ids=payload.evidence_ids,
-            idempotency_key=payload.idempotency_key or batch.batch_id,
-            priority=payload.priority,
-        )
-        try:
-            record, enqueued = registry.submit(request_contract)
-        except WriteConflictError as error:
-            raise HTTPException(409, str(error)) from error
-        except LookupError as error:
-            # Evidence-first: the write points at Evidence the business
-            # database does not hold. Rejecting it here is a caller error, not
-            # a server fault, and it must not create a queue row.
-            raise HTTPException(422, str(error)) from error
-        return MemoryWriteReceipt(
-            request_id=record.request_id,
-            state=record.state,
-            created_at=record.created_at,
-            updated_at=record.updated_at,
-            detail="" if enqueued else "already accepted; not enqueued again",
-        )
-
-    @instance.get("/{request_id}", response_model=MemoryWriteReceipt)
-    def status(request_id: str, request: Request) -> MemoryWriteReceipt:
-        registry = _registry(request, write=False)
-        try:
-            record = registry.get(request_id)
-        except DurableQueueSchemaUnavailableError as error:
-            raise HTTPException(503, str(error)) from error
-        if record is None:
-            raise HTTPException(404, "unknown request id")
-        return MemoryWriteReceipt(
-            request_id=record.request_id,
-            state=record.state,
-            created_at=record.created_at,
-            updated_at=record.updated_at,
-            detail=record.detail,
-            raw_ids=record.raw_ids,
-            memory_ids=record.memory_ids,
-        )
-
-    return instance
-
-
 def sdk_router(dependencies: list[Any] | None = None) -> APIRouter:
     instance = APIRouter(
         prefix="/api/v2/memory-writes",

memhub/apps/core/src/one_memory/reader_app.py

@@ -1,623 +0,0 @@
-"""Read-only process: serves the same read routes as Core without write access.
-
-Opens the database in `mode=ro` with `PRAGMA query_only=ON`; every store
-operation here goes through `main_database().read()`, which already enforces
-this. No HY SDK, no Chroma, no ONNX runtime, no keychain: the imports that
-would pull them in are simply not reached, and the routes below never call
-into a write path.
-
-Reads that need HY (semantic search, graph overlay) are delegated to the
-Core's internal endpoints; the Core is the only process that owns the
-vector stores. Side effects (call events, feedback) are queued and sent
-asynchronously, never blocking the read response.
-"""
-
-from __future__ import annotations
-
-import asyncio
-import builtins
-import contextlib
-import logging
-import os
-import sqlite3
-import time
-from collections.abc import AsyncIterator, Collection, Mapping, Sequence
-from contextlib import asynccontextmanager
-from datetime import UTC, datetime
-from pathlib import Path
-from typing import Any, cast
-
-from fastapi import Depends, FastAPI, HTTPException, Query, Request
-from pydantic import BaseModel, ConfigDict, SecretStr
-
-from one_memory.database_access import main_database
-from one_memory.home_summary import (
-    HomeSummary,
-    HomeSummaryUnavailable,
-    read_home_summary,
-)
-from one_memory.memory_governance import GovernedMemory, MemoryStatus
-from one_memory.memory_library import MemoryLibraryPage, read_memory_library
-from one_memory.recall import RecallRequest, _KeywordCandidates
-from one_memory.semantic_deadline import SemanticMemoryHit
-from one_memory.source_read_access import SourceReadAccess
-
-logger = logging.getLogger(__name__)
-
-MAX_READER_RSS_BYTES = 250 * 1024 * 1024
-
-_PROBE_QUERY = "__om_probe__"
-
-
-def _check_imports() -> None:
-    """Fail fast if any forbidden module is already loaded."""
-    forbidden = ("hy_memory", "chromadb", "onnxruntime", "keyring")
-    import sys
-
-    loaded = [name for name in forbidden if name in sys.modules]
-    if loaded:
-        raise ImportError(f"reader_process_loaded_forbidden_modules: {', '.join(loaded)}")
-
-
-def _memory_readable_sql() -> str:
-    return """
-    m.user_id = ? AND m.status = 'confirmed' AND m.deleted_at IS NULL
-    AND NOT EXISTS (
-        SELECT 1 FROM governed_memory_evidence link
-        JOIN evidence e ON e.evidence_id = link.evidence_id
-        JOIN source_grants g ON g.user_id=e.user_id AND g.source_id=e.source_id
-        WHERE link.memory_id=m.memory_id AND +link.active=1
-          AND g.revoked_at IS NOT NULL
-    )
-    AND NOT EXISTS (
-        SELECT 1 FROM governed_memory_evidence link
-        LEFT JOIN evidence e ON e.evidence_id = link.evidence_id
-        WHERE link.memory_id=m.memory_id AND +link.active=1
-          AND (e.evidence_id IS NULL OR e.user_id != m.user_id)
-    )
-    """
-
-
-class ReaderSettings(BaseModel):
-    model_config = ConfigDict(frozen=True)
-
-    data_dir: Path
-    host: str = "127.0.0.1"
-    port: int = 0  # 0 = ephemeral
-    api_token: SecretStr
-    core_port: int
-    core_api_token: str
-
-
-class SideEffectForwarder:
-    """Queues read-path side effects and forwards them to Core.
-
-    Reads in the Reader must stay read-only: the database is opened with
-    `query_only`, so a call event cannot be written here. Instead each read
-    that would have recorded one enqueues it, and a background task posts it
-    to Core's internal endpoint. The response never waits for it; a Core that
-    is unavailable drops it and counts the drop.
-    """
-
-    def __init__(self, settings: ReaderSettings) -> None:
-        self.settings = settings
-        self.queue: asyncio.Queue[dict[str, object]] = asyncio.Queue(maxsize=256)
-        self.dropped = 0
-        self.task: asyncio.Task[None] | None = None
-
-    def enqueue(self, event: dict[str, object]) -> None:
-        try:
-            self.queue.put_nowait(event)
-        except asyncio.QueueFull:
-            self.dropped += 1
-
-    def start(self) -> None:
-        if self.task is None or self.task.done():
-            self.task = asyncio.ensure_future(self._drain())
-
-    def stop(self) -> None:
-        if self.task is not None and not self.task.done():
-            self.task.cancel()
-
-    async def _drain(self) -> None:
-        import httpx
-
-        while True:
-            event = await self.queue.get()
-            try:
-                async with httpx.AsyncClient(
-                    headers={
-                        "Authorization": f"Bearer {self.settings.core_api_token}",
-                        "Content-Type": "application/json",
-                    },
-                    timeout=5.0,
-                    proxy=None,
-                ) as client:
-                    await client.post(
-                        f"http://127.0.0.1:{self.settings.core_port}/internal/call-event",
-                        json=event,
-                    )
-            except Exception:
-                # A dropped side effect is never a failed read: recall already
-                # answered. Counted so a persistently unavailable Core is
-                # visible rather than silent.
-                self.dropped += 1
-
-
-async def _core_get(
-    settings: ReaderSettings,
-    path: str,
-    timeout_s: float = 5.0,
-    params: Mapping[
-        str, str | int | float | bool | None | Sequence[str | int | float | bool | None]
-    ]
-    | None = None,
-) -> Any:
-    """Call the Core's internal read endpoint for data only Core can serve.
-
-    `params` is passed to httpx rather than interpolated into the path: a
-    query containing `&`, `#` or a space would otherwise be cut short or
-    read as a fragment, silently searching for the wrong thing.
-    """
-    import httpx
-
-    url = f"http://127.0.0.1:{settings.core_port}{path}"
-    async with httpx.AsyncClient(
-        headers={"Authorization": f"Bearer {settings.core_api_token}"},
-        timeout=timeout_s,
-        proxy=None,
-    ) as client:
-        response = await client.get(url, params=params)
-        response.raise_for_status()
-        return response.json()
-
-
-class _ReaderGovernance:
-    """Minimal read interface over the governance store for recall."""
-
-    def __init__(self, database_path: Path) -> None:
-        self.database_path = database_path
-
-    def list(
-        self,
-        *,
-        user_id: str,
-        status: MemoryStatus | None = None,
-        query: str | None = None,
-        limit: int = 100,
-        offset: int = 0,
-    ) -> list[GovernedMemory]:
-        """One page of memories, read through the Core's own read function.
-
-        `MemoryGovernanceStore.list` cannot be used directly: constructing the
-        store runs schema DDL on the write connection, and the Reader opens
-        with `query_only`. `read_memory_library` is the same read expressed as
-        a static SQL read (revoked sources excluded, per-row freshness checked
-        for the rows it returns, cheap total for the rest), so the Reader and
-        the Core cannot drift on what "readable" means.
-        """
-        page = read_memory_library(
-            self.database_path,
-            user_id=user_id,
-            query=query,
-            status=status,
-            offset=offset,
-            limit=limit,
-        )
-        return list(page.items)
-
-    def find_confirmed_matching_terms(
-        self,
-        *,
-        user_id: str,
-        terms: Collection[str],
-        limit: int = 200,
-        scopes: Collection[str] | None = None,
-    ) -> tuple[builtins.list[GovernedMemory], bool]:
-        if not 1 <= limit <= 2_000:
-            raise ValueError("invalid candidate limit")
-        cleaned = tuple(dict.fromkeys(term.strip() for term in terms if term.strip()))
-        if not cleaned or scopes is not None and not scopes:
-            return [], False
-        clauses = ["m.user_id=?", "m.status='confirmed'", "m.deleted_at IS NULL"]
-        values: builtins.list[object] = [user_id]
-        matches = []
-        for term in cleaned[:32]:
-            matches.append("m.content LIKE ? ESCAPE '\\'")
-            escaped = term.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
-            values.append(f"%{escaped}%")
-        clauses.append(f"({' OR '.join(matches)})")
-        if scopes is not None:
-            clauses.append(
-                "EXISTS (SELECT 1 FROM json_each(m.scopes_json) "
-                f"WHERE json_each.value IN ({','.join('?' for _ in scopes)}))"
-            )
-            values.extend(scopes)
-        values.append(limit + 1)
-        with main_database(self.database_path).read(row_factory=sqlite3.Row) as db:
-            rows = db.execute(
-                f"SELECT m.* FROM governed_memories m WHERE {' AND '.join(clauses)} "
-                "ORDER BY m.updated_at DESC,m.memory_id LIMIT ?",
-                values,
-            ).fetchall()
-            items = self._memories_from_rows(db, rows[:limit])
-        return items, len(rows) > limit or len(cleaned) > 32
-
-    def get(self, memory_id: str, *, user_id: str) -> GovernedMemory | None:
-        memory = _get_memory_direct(self.database_path, memory_id, user_id)
-        return memory if isinstance(memory, GovernedMemory) else None
-
-    def sources_behind_memories(
-        self,
-        *,
-        user_id: str,
-        memory_ids: Collection[str],
-    ) -> dict[str, frozenset[str]]:
-        if not memory_ids:
-            return {}
-        identifiers = tuple(memory_ids)
-        placeholders = ",".join("?" for _ in identifiers)
-        with main_database(self.database_path).read(row_factory=sqlite3.Row) as db:
-            rows = db.execute(
-                "SELECT link.memory_id,e.source_id FROM governed_memory_evidence link "
-                "JOIN evidence e ON e.evidence_id=link.evidence_id "
-                f"WHERE link.active=1 AND e.user_id=? AND link.memory_id IN ({placeholders})",
-                (user_id, *identifiers),
-            ).fetchall()
-        found: dict[str, set[str]] = {}
-        for row in rows:
-            found.setdefault(str(row["memory_id"]), set()).add(str(row["source_id"]))
-        return {key: frozenset(values) for key, values in found.items()}
-
-    @staticmethod
-    def _memories_from_rows(
-        db: sqlite3.Connection, rows: Sequence[sqlite3.Row]
-    ) -> builtins.list[GovernedMemory]:
-        from one_memory.memory_governance import MemoryGovernanceStore
-
-        return MemoryGovernanceStore.memories_from_rows(db, builtins.list(rows))
-
-
-def _conversation_hit(row: Any) -> dict[str, Any]:
-    """One stored row as a search hit.
-
-    The author travels with the row. A client that is not told who wrote a row
-    has to invent an author, and the invention is always "the user", which
-    files an assistant turn under the person who was talking to it.
-    """
-    return {
-        "evidence_id": row["evidence_id"],
-        "conversation_id": row["conversation_id"],
-        "source_id": row["source_id"],
-        "workspace": row["workspace"],
-        "project": row["project"],
-        "created_at": row["created_at"],
-        "excerpt": row["verbatim"][:200] if row["verbatim"] else "",
-        # Both columns are NOT NULL on `evidence`, so a stored row always
-        # knows; a summary of a whole conversation has no single author and
-        # never reaches here.
-        "role": row["role"],
-        "written_by": row["written_by"],
-    }
-
-
-def create_reader_app(settings: ReaderSettings) -> FastAPI:
-    """A read-only FastAPI application for the Reader process."""
-    _check_imports()
-    database_path = settings.data_dir / "one-memory.sqlite3"
-    if not database_path.exists():
-        raise FileNotFoundError(f"reader_database_missing: {database_path}")
-
-    # Validate schema version without writing.
-    from one_memory.memory_server.migrations import SCHEMA_TABLE
-    from one_memory.schema_gate import BUILD_SCHEMA_VERSION
-
-    with main_database(database_path).read() as db:
-        tables = {
-            str(row[0]) for row in db.execute("SELECT name FROM sqlite_master WHERE type='table'")
-        }
-        if SCHEMA_TABLE in tables:
-            row = db.execute(f"SELECT MAX(version) FROM {SCHEMA_TABLE}").fetchone()
-            found = int(row[0]) if row and row[0] is not None else 0
-            if found > BUILD_SCHEMA_VERSION:
-                raise RuntimeError(f"reader_schema_too_new: {found} > {BUILD_SCHEMA_VERSION}")
-        elif not tables:
-            raise RuntimeError("reader_database_empty")
-
-    access = SourceReadAccess(database_path)
-    forwarder = SideEffectForwarder(settings)
-    governance = _ReaderGovernance(database_path)
-
-    @asynccontextmanager
-    async def lifespan(_: FastAPI) -> AsyncIterator[None]:
-        monitor = asyncio.get_running_loop().create_task(_memory_monitor())
-        forwarder.start()
-        yield
-        monitor.cancel()
-        forwarder.stop()
-
-    async def _memory_monitor() -> None:
-        import resource
-        import sys
-
-        while True:
-            await asyncio.sleep(30)
-            usage = resource.getrusage(resource.RUSAGE_SELF).ru_maxrss
-            rss_bytes = usage if sys.platform == "darwin" else usage * 1024
-            if rss_bytes > MAX_READER_RSS_BYTES:
-                logger.error(
-                    "reader_memory_limit_exceeded: %d bytes > %d",
-                    rss_bytes,
-                    MAX_READER_RSS_BYTES,
-                )
-                os._exit(1)
-
-    app = FastAPI(title="MemHub Reader", lifespan=lifespan)
-    app.state.settings = settings
-    app.state.database_path = database_path
-
-    expected_token = settings.api_token.get_secret_value()
-
-    def require_auth(request: Request) -> None:
-        import hmac
-
-        origin = request.headers.get("origin")
-        if origin is not None and origin not in (
-            "one-memory://app",
-            "http://localhost:5173",
-        ):
-            raise HTTPException(403, "origin_not_allowed")
-        authorization = request.headers.get("authorization", "")
-        scheme, _, token = authorization.partition(" ")
-        if not (scheme.lower() == "bearer" and hmac.compare_digest(token, expected_token)):
-            raise HTTPException(401, "invalid_local_token")
-
-    protected = [Depends(require_auth)]
-
-    @app.get("/api/v1/home-summary", response_model=HomeSummary, dependencies=protected)
-    def home_summary() -> HomeSummary:
-        try:
-            return read_home_summary(database_path)
-        except HomeSummaryUnavailable:
-            # Belt and braces: read_home_summary answers stale itself, but if
-            # that ever changes, never let the homepage 500.
-            return HomeSummary(
-                memory_count=0, latest=None, observed_at=datetime.now(UTC), stale=True
-            )
-
-    @app.get("/api/v1/memory-library", response_model=MemoryLibraryPage, dependencies=protected)
-    def memory_library(
-        query: str | None = Query(default=None, max_length=512),
-        status: str | None = None,
-        active_only: bool = False,
-        source: str | None = Query(default=None, min_length=1),
-        offset: int = Query(default=0, ge=0),
-        limit: int = Query(default=100, ge=1, le=500),
-    ) -> MemoryLibraryPage:
-        from one_memory.memory_governance import MemoryStatus as MS
-
-        ms = MS(status) if status else None
-        return read_memory_library(
-            database_path,
-            user_id="local",
-            query=query,
-            status=ms,
-            active_only=active_only,
-            source=source,
-            offset=offset,
-            limit=limit,
-        )
-
-    @app.get("/api/v1/memories", dependencies=protected)
-    def list_memories(
-        status: str | None = None,
-        query: str | None = None,
-        limit: int = Query(default=100, ge=1, le=500),
-        offset: int = Query(default=0, ge=0),
-    ) -> list[dict[str, Any]]:
-        from one_memory.memory_governance import MemoryStatus as MS
-
-        ms = MS(status) if status else None
-        memories = governance.list(
-            user_id="local", status=ms, query=query, limit=limit, offset=offset
-        )
-        visible = access.memories(memories)
-        return [m.model_dump(mode="json") for m in visible]
-
-    @app.get("/api/v1/memories/graph", dependencies=protected)
-    async def memory_graph(
-        limit: int = Query(default=160, ge=1, le=300),
-    ) -> dict[str, Any]:
-        memories = governance.list(user_id="local", status=MemoryStatus.CONFIRMED, limit=500)
-        projected = access.memories(memories[:limit])
-        nodes: dict[str, dict[str, Any]] = {}
-        edges: list[dict[str, Any]] = []
-        source_ids: set[str] = set()
-        with main_database(database_path).read(row_factory=sqlite3.Row) as db:
-            for memory in projected:
-                node_id = f"memory:{memory.memory_id}"
-                nodes[node_id] = {
-                    "node_id": node_id,
-                    "node_type": "memory",
-                    "label": memory.content,
-                    "memory_id": memory.memory_id,
-                    "kind": memory.kind.value
-                    if hasattr(memory.kind, "value")
-                    else str(memory.kind),
-                    "status": memory.status.value
-                    if hasattr(memory.status, "value")
-                    else str(memory.status),
-                }
-                evidence_ids = list(memory.evidence_ids)
-                if evidence_ids:
-                    placeholders = ",".join("?" for _ in evidence_ids)
-                    sql = (
-                        f"SELECT DISTINCT source_id FROM evidence"
-                        f" WHERE evidence_id IN ({placeholders})"
-                    )
-                    for row in db.execute(
-                        sql,
-                        evidence_ids,
-                    ):
-                        sid = str(row["source_id"])
-                        source_ids.add(sid)
-            for sid in sorted(source_ids):
-                source_node_id = f"source:{sid}"
-                nodes[source_node_id] = {
-                    "node_id": source_node_id,
-                    "node_type": "source",
-                    "label": sid,
-                    "source_id": sid,
-                }
-                for memory in projected:
-                    if any(_source_for_evidence(db, eid) == sid for eid in memory.evidence_ids):
-                        memory_node_id = f"memory:{memory.memory_id}"
-                        edges.append(
-                            {
-                                "edge_id": f"{source_node_id}->{memory_node_id}",
-                                "source_node_id": source_node_id,
-                                "target_node_id": memory_node_id,
-                            }
-                        )
-        # Fetch HY graph overlay from Core (not available in Reader).
-        hy_overlay = None
-        with contextlib.suppress(Exception):
-            hy_overlay = await _core_get(
-                settings,
-                "/internal/graph-snapshot",
-                timeout_s=5.0,
-                params={"limit": limit},
-            )
-        if hy_overlay and not hy_overlay.get("consulted", False):
-            hy_overlay = None
-        return {
-            "limit": limit,
-            "total": len(projected),
-            "nodes": tuple(nodes.values()),
-            "edges": edges,
-            **({"hy_overlay": hy_overlay} if hy_overlay else {}),
-        }
-
-    @app.get("/api/v1/memories/{memory_id}", dependencies=protected)
-    def get_memory(memory_id: str) -> dict[str, Any]:
-        memory = _get_memory_direct(database_path, memory_id, "local")
-        if memory is None:
-            raise HTTPException(404, "memory_not_found")
-        if not access.memories([memory]):
-            raise HTTPException(403, "memory_source_revoked")
-        return cast(dict[str, Any], memory.model_dump(mode="json"))
-
-    @app.post("/api/v1/recall", response_model=None, dependencies=protected)
-    async def recall(request: RecallRequest) -> dict[str, Any]:
-        from one_memory.recall import GovernedRecallTarget
-
-        started = time.monotonic()
-        target = GovernedRecallTarget(
-            governance=governance,
-            semantic_search=None,
-            resolve_workspace=None,
-            filter_memories=access.memories,
-        )
-
-        if request.query == _PROBE_QUERY:
-            return target.recall(request, user_id="local").model_dump(mode="json")
-        deadline = time.monotonic() + request.timeout_ms / 1_000
-        semantic_ids: tuple[str, ...] = ()
-        try:
-            remaining = max(0.1, deadline - time.monotonic())
-            result = await asyncio.wait_for(
-                _core_get(
-                    settings,
-                    "/internal/semantic-ids",
-                    timeout_s=remaining,
-                    params={"query": request.query, "limit": request.limit},
-                ),
-                timeout=remaining,
-            )
-            semantic_ids = tuple(str(value) for value in result.get("ids", []) if value)
-        except Exception:
-            pass
-        readable = target._readable_scopes(request)
-        # Keyword candidates from read-only SQL.
-        keywords = target._keyword_candidates(
-            request, user_id="local", readable=readable, deadline=deadline
-        )
-        receipt = target._rank(
-            request,
-            user_id="local",
-            readable=readable,
-            semantic_hits={
-                memory_id: SemanticMemoryHit(
-                    memory_id,
-                    1.0 - index / max(1, len(semantic_ids)),
-                )
-                for index, memory_id in enumerate(semantic_ids)
-            },
-            keywords=keywords
-            if isinstance(keywords, _KeywordCandidates)
-            else _KeywordCandidates((), False, False),
-            deadline=deadline,
-            timed_out=False,
-        )
-        forwarder.enqueue(
-            {
-                "tool": "om_recall",
-                "query": request.query,
-                "scope": request.scope,
-                "state": receipt.state.value,
-                "memory_count": len(receipt.hits),
-                "elapsed_ms": (time.monotonic() - started) * 1000,
-            }
-        )
-        return receipt.model_dump(mode="json")
-
-    @app.get("/api/v1/conversations/search", dependencies=protected)
-    def search_conversations(
-        query: str = Query(min_length=1, max_length=512),
-        limit: int = Query(default=20, ge=1, le=100),
-    ) -> dict[str, Any]:
-        if not database_path.exists():
-            raise HTTPException(503, "conversation_search_unavailable")
-        with main_database(database_path).read(row_factory=sqlite3.Row) as db:
-            try:
-                rows = db.execute(
-                    """SELECT * FROM evidence
-                    WHERE user_id = 'local' AND verbatim LIKE ? ESCAPE '\\'
-                    ORDER BY imported_at DESC LIMIT ?""",
-                    (f"%{query}%", limit),
-                ).fetchall()
-            except Exception:
-                raise HTTPException(503, "conversation_search_unavailable") from None
-        hits = [_conversation_hit(row) for row in rows]
-        return {
-            "hits": hits,
-            "empty_reason": None if hits else "no_matches",
-            "imported_messages": len(hits),
-        }
-
-    @app.get("/health")
-    def health() -> dict[str, str]:
-        return {"status": "ok", "service": "one-memory-reader"}
-
-    return app
-
-
-def _get_memory_direct(database_path: Path, memory_id: str, user_id: str) -> Any:
-    from one_memory.memory_governance import _memory_from_row, _memory_links
-
-    with main_database(database_path).read(row_factory=sqlite3.Row) as db:
-        row = db.execute(
-            "SELECT * FROM governed_memories WHERE memory_id = ? AND user_id = ?",
-            (memory_id, user_id),
-        ).fetchone()
-        if row is None:
-            return None
-        links = _memory_links(db, [memory_id])
-        return _memory_from_row(row, *(tuple(vals) for vals in links[memory_id]))
-
-
-def _source_for_evidence(db: sqlite3.Connection, evidence_id: str) -> str | None:
-    row = db.execute(
-        "SELECT source_id FROM evidence WHERE evidence_id = ?", (evidence_id,)
-    ).fetchone()
-    return str(row["source_id"]) if row else None

memhub/apps/core/src/one_memory/recall.py

@@ -81,7 +81,11 @@ class RecallHit(BaseModel):
     score: float = Field(ge=0, le=1)
     #: HY already rendered memory time/evolution/capsule context into content.
     #: Hosts must not append their own governance timestamp in this case.
-    content_format: Literal["plain", "hy-sdk"] = "plain"
+    #: "raw" is an excerpt of an imported conversation, not a memory.
+    content_format: Literal["plain", "hy-sdk", "raw"] = "plain"
+    #: Raw excerpts only: the app and conversation the excerpt came from.
+    source: str | None = None
+    session_id: str | None = None
 
 
 class RecallReceipt(BaseModel):
@@ -103,6 +107,11 @@ class RecallReceipt(BaseModel):
     #: whether the answer is that nothing was found or that reading was not
     #: allowed.
     excluded_sources: tuple[str, ...] = ()
+    #: "raw" when recall searched the imported conversations instead of
+    #: memories, because no generation model is configured or no memory
+    #: exists yet (`fallback_reason`). Raw hits are excerpts, not memories.
+    mode: Literal["memory", "raw"] = "memory"
+    fallback_reason: Literal["model_unavailable", "no_memories"] | None = None
 
 
 class RecallTarget(Protocol):

memhub/apps/core/src/one_memory/recall_fallback.py

@@ -0,0 +1,149 @@
+"""Recall that degrades to the original conversations instead of answering empty.
+
+MemHub_recall searches the memories the SDK distilled from conversations. That
+needs a configured generation model to have produced any, and a library that
+holds some. Without either, the memory search can only come back empty, so
+recall searches the SDK's raw layer (the imported conversations themselves)
+instead: plain retrieval over what was imported, the same lane
+`/api/v2/context/search` reads, under the same raw-source authority.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import Awaitable, Callable
+from datetime import UTC, datetime
+from typing import Literal
+
+from one_memory.hy_sdk_types import HySdkRawHit
+from one_memory.recall import (
+    PROBE_QUERY,
+    RecallHit,
+    RecallReceipt,
+    RecallRequest,
+    RecallState,
+    TruncationBudget,
+)
+
+FallbackReason = Literal["model_unavailable", "no_memories"]
+
+#: Raw sources this caller may read, or None for every source (a trusted local
+#: caller). An empty set means the caller may read no raw conversation.
+RawSources = frozenset[str] | None
+
+
+async def recall_with_fallback(
+    request: RecallRequest,
+    *,
+    model_ready: Callable[[], Awaitable[bool]],
+    recall_memories: Callable[[RecallRequest], Awaitable[RecallReceipt]],
+    has_memories: Callable[[], Awaitable[bool]],
+    raw_sources: Callable[[], Awaitable[RawSources]],
+    search_raw: Callable[[str, int, RawSources], Awaitable[tuple[HySdkRawHit, ...]]],
+) -> RecallReceipt:
+    """Memory recall when a model and memories exist, otherwise the raw layer.
+
+    The library check runs only after an empty memory search: with memories
+    present and nothing relevant, the answer stays an honest empty memory
+    result rather than a different kind of hit.
+    """
+    if request.query == PROBE_QUERY:
+        return await recall_memories(request)
+    started = time.monotonic()
+    if await model_ready():
+        receipt = await recall_memories(request)
+        if receipt.hits or await has_memories():
+            return receipt
+        reason: FallbackReason = "no_memories"
+    else:
+        reason = "model_unavailable"
+    remaining = request.timeout_ms / 1_000 - (time.monotonic() - started)
+    return await _raw_recall(
+        request,
+        reason=reason,
+        remaining_seconds=remaining,
+        raw_sources=raw_sources,
+        search_raw=search_raw,
+    )
+
+
+async def _raw_recall(
+    request: RecallRequest,
+    *,
+    reason: FallbackReason,
+    remaining_seconds: float,
+    raw_sources: Callable[[], Awaitable[RawSources]],
+    search_raw: Callable[[str, int, RawSources], Awaitable[tuple[HySdkRawHit, ...]]],
+) -> RecallReceipt:
+    def receipt(
+        hits: tuple[RecallHit, ...] = (),
+        *,
+        used: int = 0,
+        truncated_by: TruncationBudget | None = None,
+        unexamined: int = 0,
+    ) -> RecallReceipt:
+        return RecallReceipt(
+            state=RecallState.GROUNDED if hits else RecallState.EMPTY,
+            query=request.query,
+            scope=request.scope,
+            hits=hits,
+            used_characters=used,
+            truncated=truncated_by is not None,
+            truncated_by=truncated_by,
+            unexamined_count=unexamined,
+            mode="raw",
+            fallback_reason=reason,
+        )
+
+    sources = await raw_sources()
+    if sources is not None and not sources:
+        # The caller may read no original conversation: an empty answer, not
+        # a wider grant than recall had.
+        return receipt()
+    if remaining_seconds <= 0:
+        return receipt(truncated_by=TruncationBudget.TIMEOUT)
+    try:
+        found = await asyncio.wait_for(
+            search_raw(request.query, request.limit, sources),
+            timeout=remaining_seconds,
+        )
+    except TimeoutError:
+        return receipt(truncated_by=TruncationBudget.TIMEOUT)
+    hits: list[RecallHit] = []
+    used = 0
+    truncated_by: TruncationBudget | None = None
+    for index, hit in enumerate(found):
+        if sources is not None and hit.source not in sources:
+            continue
+        if len(hits) >= request.limit:
+            truncated_by = TruncationBudget.COUNT
+            return receipt(
+                tuple(hits),
+                used=used,
+                truncated_by=truncated_by,
+                unexamined=len(found) - index,
+            )
+        if used + len(hit.content) > request.character_budget:
+            truncated_by = TruncationBudget.CHARACTER
+            continue
+        hits.append(
+            RecallHit(
+                memory_id=hit.raw_id,
+                content=hit.content,
+                kind="raw",
+                scopes=(),
+                evidence_ids=(),
+                updated_at=(
+                    datetime.fromtimestamp(hit.memory_at, tz=UTC)
+                    if hit.memory_at is not None
+                    else datetime(1970, 1, 1, tzinfo=UTC)
+                ),
+                score=hit.score,
+                content_format="raw",
+                source=hit.source,
+                session_id=hit.session_id,
+            )
+        )
+        used += len(hit.content)
+    return receipt(tuple(hits), used=used, truncated_by=truncated_by)

memhub/apps/core/src/one_memory/retired_authority.py

@@ -22,6 +22,13 @@ class RetiredEvidenceStore:
         del limit
         return 0
 
+    def release_sdk_staging(self, evidence_ids: tuple[str, ...]) -> int:
+        # The write drain releases staged Evidence after every SDK write. On
+        # SDK authority nothing is staged; without this, `__getattr__` raised
+        # past `getattr(..., None)` and every completed write logged an error.
+        del evidence_ids
+        return 0
+
     def get(self, _identifier: str) -> None:
         return None
 

memhub/apps/core/src/one_memory/retrieval/chunking.py

@@ -1,167 +0,0 @@
-"""Single-Evidence identity chunking; no reads, persistence, normalization or grants.
-
-Callers must first establish eligibility/sanitization/permission. This module
-does not strip wrappers or secrets and must not be used as a content safety gate.
-"""
-
-from dataclasses import dataclass
-from typing import Protocol
-
-from one_memory.embedding_assets import BUILTIN_EMBEDDING_MAX_TOKENS
-from one_memory.local_embedding import TokenizedText, TokenOffset
-
-
-class OffsetTokenizer(Protocol):
-    def tokenize_with_offsets(self, text: str) -> TokenizedText: ...
-
-
-class ChunkingError(ValueError):
-    """Invalid offsets, uncovered text or insufficient encoding budget; never truncate."""
-
-
-@dataclass(frozen=True)
-class TextChunk:
-    ordinal: int
-    start_cp: int
-    end_cp: int
-    token_count: int
-    text: str
-
-
-@dataclass(frozen=True)
-class _Span:
-    start: int
-    end: int
-    tokens: int
-
-
-def _spans(text: str, encoded: TokenizedText) -> tuple[_Span, ...]:
-    if not isinstance(encoded, TokenizedText) or len(encoded.token_ids) != len(encoded.offsets):
-        raise ChunkingError("chunk_token_offset_count_mismatch")
-    spans: list[_Span] = []
-    previous_start = previous_end = 0
-    for token_id, offset in zip(encoded.token_ids, encoded.offsets, strict=True):
-        if type(token_id) is not int or token_id < 0 or not isinstance(offset, TokenOffset):
-            raise ChunkingError("chunk_invalid_token_offset")
-        if (
-            type(offset.start_cp) is not int
-            or type(offset.end_cp) is not int
-            or type(offset.special) is not bool
-        ):
-            raise ChunkingError("chunk_invalid_token_offset")
-        start, end = offset.start_cp, offset.end_cp
-        if offset.special:
-            if start != 0 or end != 0:
-                raise ChunkingError("chunk_invalid_special_offset")
-            continue
-        if not 0 <= start < end <= len(text) or start < previous_start or end < previous_end:
-            raise ChunkingError("chunk_invalid_offset_order_or_bounds")
-        if start > previous_end and not text[previous_end:start].isspace():
-            raise ChunkingError("chunk_uncovered_nonwhitespace")
-        # Overlapping subpieces (including several pieces for one code point)
-        # form an indivisible interval; slicing inside it loses token identity.
-        if spans and start < spans[-1].end:
-            prior = spans[-1]
-            spans[-1] = _Span(prior.start, end, prior.tokens + 1)
-        else:
-            spans.append(_Span(start, end, 1))
-        previous_start, previous_end = start, end
-    if text[previous_end:] and not text[previous_end:].isspace():
-        raise ChunkingError("chunk_uncovered_nonwhitespace")
-    return tuple(spans)
-
-
-def _encoding(text: str, tokenizer: OffsetTokenizer) -> tuple[TokenizedText, tuple[_Span, ...]]:
-    try:
-        result = tokenizer.tokenize_with_offsets(text)
-    except Exception as error:
-        raise ChunkingError("chunk_tokenization_failed") from error
-    return result, _spans(text, result)
-
-
-def chunk_evidence(
-    text: str,
-    tokenizer: OffsetTokenizer,
-    *,
-    prefix: str = "",
-    target_tokens: int = 384,
-    overlap_tokens: int = 64,
-    max_tokens: int = BUILTIN_EMBEDDING_MAX_TOKENS,
-) -> tuple[TextChunk, ...]:
-    """Chunk one original with code point [start,end), preserving exact slices.
-
-    target/overlap count original non-special tokens. Overlap is up to the
-    requested token count at indivisible offset boundaries; forward progress is
-    mandatory. token_count is re-tokenized prefix + chunk.text INCLUDING specials,
-    never an additive estimate. Prefix is caller-provided, unchanged, and omitted
-    from chunk.text/offsets. Empty/whitespace-only inputs have no index chunks.
-    """
-    if not isinstance(text, str) or not isinstance(prefix, str):
-        raise ChunkingError("chunk_requires_text")
-    if (
-        any(type(value) is not int for value in (target_tokens, overlap_tokens, max_tokens))
-        or not 0 <= overlap_tokens < target_tokens
-        or not 1 <= max_tokens <= BUILTIN_EMBEDDING_MAX_TOKENS
-        or target_tokens > max_tokens
-    ):
-        raise ChunkingError("chunk_invalid_token_budget")
-    if not text or text.isspace():
-        return ()
-    _, spans = _encoding(text, tokenizer)
-    if not spans:
-        raise ChunkingError("chunk_uncovered_nonwhitespace")
-    chunks: list[TextChunk] = []
-    start_index = 0
-    previous_end_cp = 0
-    while start_index < len(spans):
-        end_index = start_index
-        body_tokens = 0
-        while end_index < len(spans):
-            candidate = body_tokens + spans[end_index].tokens
-            if end_index > start_index and candidate > target_tokens:
-                break
-            body_tokens = candidate
-            end_index += 1
-        # Prefer the last paragraph boundary in the latter half of the target.
-        # Never trade away an entire overlap window or split a token interval.
-        if end_index < len(spans):
-            count = 0
-            preferred = None
-            for boundary in range(start_index + 1, end_index + 1):
-                count += spans[boundary - 1].tokens
-                if count >= max(target_tokens // 2, overlap_tokens + 1):
-                    left, right = spans[boundary - 1].end, spans[boundary].start
-                    if "\n" in text[max(spans[boundary - 1].start, left - 1) : right]:
-                        preferred = boundary
-            if preferred is not None:
-                end_index = preferred
-        start_cp = 0 if start_index == 0 else spans[start_index].start
-        while end_index > start_index:
-            # Include gaps verbatim, including whitespace and combining marks;
-            # source coverage is never reconstructed by joining decoded tokens.
-            end_cp = spans[end_index].start if end_index < len(spans) else len(text)
-            encoded, _ = _encoding(prefix + text[start_cp:end_cp], tokenizer)
-            token_count = len(encoded.token_ids)
-            if token_count <= max_tokens:
-                break
-            end_index -= 1
-        else:
-            raise ChunkingError("chunk_indivisible_span_exceeds_token_budget")
-        if end_cp <= previous_end_cp or start_cp > previous_end_cp:
-            raise ChunkingError("chunk_coverage_cannot_progress")
-        chunks.append(TextChunk(len(chunks), start_cp, end_cp, token_count, text[start_cp:end_cp]))
-        previous_end_cp = end_cp
-        if end_index == len(spans):
-            break
-        next_start = end_index
-        overlap = 0
-        while next_start > start_index + 1:
-            candidate = overlap + spans[next_start - 1].tokens
-            if candidate > overlap_tokens:
-                break
-            next_start -= 1
-            overlap = candidate
-        start_index = next_start
-    if previous_end_cp != len(text):
-        raise ChunkingError("chunk_incomplete_coverage")
-    return tuple(chunks)

memhub/apps/core/src/one_memory/retrieval/content.py

@@ -1,92 +0,0 @@
-"""Shared qualification for identity-mapped raw indexing and candidate reads."""
-
-from collections.abc import Sequence
-
-from one_memory.conversation_processing import _is_hy_input_turn
-from one_memory.imports.models import EvidenceContentKind, EvidenceRecord
-from one_memory.imports.sources.parsing import is_host_generated_user_turn, strip_host_wrappers
-from one_memory.input_sanitization import sanitize_model_input
-from one_memory.retrieval.chunking import TextChunk
-from one_memory.retrieval.mapped_content import PreparedMappedContent, prepare_mapped_content
-
-
-def identity_content_ready(record: EvidenceRecord) -> bool:
-    # Reuse pure existing hygiene checks, without invoking HY. Nonidentity
-    # cleaning requires a source map and remains explicitly uncovered for now.
-    return (
-        record.content_kind is EvidenceContentKind.RAW_CONVERSATION
-        and record.role in {"user", "assistant"}
-        and _is_hy_input_turn(record)
-        and not is_host_generated_user_turn(record.verbatim)
-        and strip_host_wrappers(record.verbatim) == record.verbatim.strip()
-        and sanitize_model_input(record.verbatim) == record.verbatim
-    )
-
-
-def index_content(
-    record: EvidenceRecord, *, normalizer_version: int, chunker_version: int
-) -> PreparedMappedContent | None:
-    """Generation-owned content semantics, never silently upgrade identity generations."""
-    if (normalizer_version, chunker_version) == (1, 1):
-        if not identity_content_ready(record):
-            raise ValueError("content_mapping_required")
-        return None
-    if (normalizer_version, chunker_version) == (2, 2):
-        return prepare_mapped_content(record)
-    raise ValueError("unsupported_content_generation")
-
-
-def validate_chunk_coverage(
-    record: EvidenceRecord, chunks: Sequence[TextChunk], prepared: PreparedMappedContent | None
-) -> None:
-    """Verify exact slices and complete citation-safe coverage without a tokenizer call."""
-    if len(chunks) > 8192 or (prepared is None and not chunks):
-        raise ValueError("invalid_chunk_manifest")
-    if prepared is None:
-        ranges = [(0, len(record.verbatim))]
-    else:
-        ranges = []
-        for span in prepared.metadata.segments:
-            if span.kind == "copy":
-                assert span.source_start_cp is not None and span.source_end_cp is not None
-                ranges.append((span.source_start_cp, span.source_end_cp))
-    range_index = 0
-    covered_end = ranges[0][0] if ranges else 0
-    previous_end = -1
-    for index, chunk in enumerate(chunks):
-        if not isinstance(chunk, TextChunk) or any(
-            type(value) is not int
-            for value in (chunk.ordinal, chunk.start_cp, chunk.end_cp, chunk.token_count)
-        ):
-            raise ValueError("invalid_chunk_manifest")
-        while range_index < len(ranges) and chunk.start_cp >= ranges[range_index][1]:
-            if record.verbatim[covered_end : ranges[range_index][1]].strip():
-                raise ValueError("incomplete_chunk_manifest")
-            range_index += 1
-            covered_end = ranges[range_index][0] if range_index < len(ranges) else 0
-        if range_index >= len(ranges):
-            raise ValueError("invalid_chunk_manifest")
-        left, right = ranges[range_index]
-        if (
-            chunk.ordinal != index
-            or not left <= chunk.start_cp < chunk.end_cp <= right
-            or chunk.end_cp <= previous_end
-            or not 1 <= chunk.token_count <= 512
-            or record.verbatim[chunk.start_cp : chunk.end_cp] != chunk.text
-            or (
-                chunk.start_cp > covered_end
-                and (prepared is None or record.verbatim[covered_end : chunk.start_cp].strip())
-            )
-        ):
-            raise ValueError("invalid_chunk_manifest")
-        covered_end = previous_end = chunk.end_cp
-    while range_index < len(ranges):
-        if prepared is None:
-            if covered_end != ranges[range_index][1]:
-                raise ValueError("incomplete_chunk_manifest")
-        elif record.verbatim[covered_end : ranges[range_index][1]].strip():
-            raise ValueError("incomplete_chunk_manifest")
-        range_index += 1
-        covered_end = ranges[range_index][0] if range_index < len(ranges) else 0
-    if prepared is not None and (not chunks) != (prepared.state == "no_indexable_content"):
-        raise ValueError("invalid_chunk_manifest")

memhub/apps/core/src/one_memory/retrieval/index_provisioning.py

@@ -1,96 +0,0 @@
-"""Publish one active generation for the built-in encoder, when asked to.
-
-The runtime deliberately only resumes an index somebody already initialized, so
-without this the feature could be switched on and still never index anything.
-Provisioning stays separate from `start()` for the same reason it exists: it is
-the one place allowed to create, and it creates only for a first enable.
-"""
-
-from __future__ import annotations
-
-import logging
-import sqlite3
-from pathlib import Path
-
-from one_memory.database_access import main_database
-from one_memory.embedding_assets import assets_present
-from one_memory.retrieval.index_store import RetrievalIndexStore
-from one_memory.retrieval.index_worker import LocalRetrievalEncoder
-from one_memory.retrieval.vector_store import RawVectorStore
-
-DATABASE_NAME = "one-memory.sqlite3"
-VECTOR_DIR_NAME = "retrieval-vectors"
-
-
-def provision_retrieval_index(data_dir: Path) -> str | None:
-    """The active generation id for the built-in encoder, creating it once.
-
-    Returns None whenever the right answer is to leave the data alone: no
-    built-in encoder, no database yet, an index from an older schema, or one
-    already published for a different encoder. None is not an error; the
-    lexical lane works without an index and says so through `degraded`.
-    """
-    database = data_dir / DATABASE_NAME
-    if not assets_present() or not database.is_file():
-        return None
-    identity = LocalRetrievalEncoder().identity
-    store = RetrievalIndexStore(database)
-    try:
-        with main_database(database).write() as db, db:
-            db.execute("BEGIN IMMEDIATE")
-            if (existing := _published(db)) is not None:
-                return existing if _matches(store, db, existing, identity) else None
-            version = _schema_version(db)
-            if version == 1:
-                # Someone's v1 index. Migrating it is maintenance, not startup.
-                return None
-            if version is None:
-                store.initialize_v2(db)
-            generation = store.create_generation(db, identity)
-        store.activate_generation(generation)
-        _ensure_vectors(data_dir / VECTOR_DIR_NAME, generation, identity.dimensions)
-    except Exception:
-        logging.getLogger(__name__).warning("retrieval_index_provision_failed", exc_info=True)
-        return None
-    return generation
-
-
-def _schema_version(db: sqlite3.Connection) -> int | None:
-    if not db.execute(
-        "SELECT 1 FROM sqlite_master WHERE type='table' AND name='retrieval_index_state'"
-    ).fetchone():
-        return None
-    row = db.execute(
-        "SELECT schema_version FROM retrieval_index_state WHERE singleton=1"
-    ).fetchone()
-    return None if row is None else int(row[0])
-
-
-def _published(db: sqlite3.Connection) -> str | None:
-    if not db.execute(
-        "SELECT 1 FROM sqlite_master WHERE type='table' AND name='retrieval_index_generations'"
-    ).fetchone():
-        return None
-    rows = db.execute(
-        "SELECT generation_id FROM retrieval_index_generations WHERE state='active' LIMIT 2"
-    ).fetchall()
-    return str(rows[0][0]) if len(rows) == 1 else None
-
-
-def _matches(
-    store: RetrievalIndexStore,
-    db: sqlite3.Connection,
-    generation: str,
-    identity: object,
-) -> bool:
-    try:
-        return store._identity(db, generation) == identity
-    except Exception:
-        return False
-
-
-def _ensure_vectors(directory: Path, generation: str, dimensions: int) -> None:
-    if directory.exists():
-        return
-    vectors = RawVectorStore.create(directory, generation_id=generation, dimensions=dimensions)
-    vectors.close()

memhub/apps/core/src/one_memory/retrieval/index_store.py

@@ -1,856 +0,0 @@
-"""Explicit derived-index transactions. No constructor migration or model invocation."""
-
-import hashlib
-import json
-import math
-import sqlite3
-import time
-from collections.abc import Callable, Iterator, Sequence
-from contextlib import contextmanager
-from dataclasses import asdict, dataclass, replace
-from datetime import UTC, datetime
-from pathlib import Path
-from uuid import uuid4
-
-from one_memory import ingest_journal as journal
-from one_memory.context_raw import _check, _connection
-from one_memory.database import take_the_write_lock_first
-from one_memory.database_access import main_database
-from one_memory.imports.models import EvidenceRecord
-from one_memory.imports.storage import EvidenceStore
-from one_memory.memory_server.migrations import (
-    _split_statements,
-    retrieval_build_maps_ddl,
-    retrieval_documents_v2_ddl,
-    retrieval_index_ddl,
-)
-from one_memory.retrieval.chunking import TextChunk
-from one_memory.retrieval.content import index_content, validate_chunk_coverage
-from one_memory.retrieval.mapped_content import ContentMap, PreparedMappedContent
-from one_memory.retrieval.models import TimeRange
-
-
-def digest(value: object) -> str:
-    return hashlib.sha256(
-        json.dumps(
-            value, sort_keys=True, ensure_ascii=False, separators=(",", ":"), allow_nan=False
-        ).encode()
-    ).hexdigest()
-
-
-@dataclass(frozen=True)
-class EncoderIdentity:
-    encoder_id: str
-    encoder_digest: str
-    tokenizer_digest: str
-    dimensions: int
-    chunker_version: int = 1
-    normalizer_version: int = 1
-    query_template_version: int = 1
-
-    def __post_init__(self) -> None:
-        if not self.encoder_id or len(self.encoder_id) > 128:
-            raise ValueError("invalid_encoder")
-        for value in (self.encoder_digest, self.tokenizer_digest):
-            if len(value) != 64 or any(c not in "0123456789abcdef" for c in value):
-                raise ValueError("invalid_encoder_digest")
-        for number in (
-            self.dimensions,
-            self.chunker_version,
-            self.normalizer_version,
-            self.query_template_version,
-        ):
-            if type(number) is not int or not 1 <= number <= 1000000:
-                raise ValueError("invalid_encoder_number")
-
-
-@dataclass(frozen=True)
-class IndexLease:
-    generation_id: str
-    evidence_id: str
-    build_id: str
-    event_seq: int
-    owner: str
-    token: str
-    expires_at: float
-    grant_fingerprint: str
-
-
-@dataclass(frozen=True)
-class PublishedChunk:
-    chunk_id: str
-    build_id: str
-    evidence_id: str
-    revision: int
-    start_cp: int
-    end_cp: int
-    ordinal: int
-    source_id: str
-    event_time: datetime | None
-
-
-def chunk_identity(lease: IndexLease, chunk: TextChunk, map_digest: str | None = None) -> str:
-    values = [lease.build_id, chunk.ordinal, chunk.start_cp, chunk.end_cp, digest(chunk.text)]
-    return digest(values if map_digest is None else [*values, map_digest])
-
-
-@contextmanager
-def transaction(db: sqlite3.Connection) -> Iterator[None]:
-    if not db.in_transaction:
-        raise RuntimeError("retrieval_requires_caller_transaction")
-    name = "retrieval_" + uuid4().hex
-    previous = db.row_factory
-    db.row_factory = sqlite3.Row
-    db.execute(f"SAVEPOINT {name}")
-    try:
-        yield
-    except BaseException:
-        db.execute(f"ROLLBACK TO {name}")
-        db.execute(f"RELEASE {name}")
-        raise
-    else:
-        db.execute(f"RELEASE {name}")
-    finally:
-        db.row_factory = previous
-
-
-class RetrievalIndexStore:
-    def __init__(self, database_path: Path):
-        self.database_path = database_path
-
-    @contextmanager
-    def _db(
-        self, *, write: bool = False, deadline: float | None = None
-    ) -> Iterator[sqlite3.Connection]:
-        if deadline is not None:
-            if write:
-                raise ValueError("deadline_connection_is_read_only")
-            with _connection(self.database_path, deadline) as db:
-                db.execute("PRAGMA query_only=ON")
-                yield db
-            return
-        database = main_database(self.database_path)
-        with (
-            database.write(create=False, foreign_keys=True, row_factory=sqlite3.Row)
-            if write
-            else database.read(foreign_keys=True, row_factory=sqlite3.Row)
-        ) as db:
-            try:
-                if write:
-                    take_the_write_lock_first(db)
-                else:
-                    db.execute("PRAGMA query_only=ON")
-                    db.execute("BEGIN")
-                yield db
-                if write:
-                    db.commit()
-            except BaseException:
-                db.rollback()
-                raise
-
-    def initialize(self, db: sqlite3.Connection) -> None:
-        """Caller owns maintenance/exclusive writer admission; rollback includes baseline."""
-        self._initialize(db, version=1)
-
-    def initialize_v2(self, db: sqlite3.Connection) -> None:
-        """Initialize a fresh store directly at the folded v2 schema.
-
-        Startup provisioning uses this path so a brand-new database does not
-        create a v1 schema and immediately migrate it. Explicit maintenance
-        callers keep `initialize()`'s v1 baseline contract instead.
-        """
-        self._initialize(db, version=2)
-
-    def _initialize(self, db: sqlite3.Connection, *, version: int) -> None:
-        with transaction(db):
-            exists = db.execute(
-                "SELECT 1 FROM sqlite_master WHERE name='retrieval_index_state'"
-            ).fetchone()
-            if exists:
-                self._store_id(db)
-            elif db.execute(
-                "SELECT 1 FROM sqlite_master WHERE name IN ('retrieval_documents',"
-                "'retrieval_chunks','retrieval_index_generations','retrieval_consumers')"
-            ).fetchone():
-                raise ValueError("retrieval_partial_initialization")
-            journal.initialize(db)
-            # Migration 33 owns the schema. Explicit initialization keeps the
-            # maintenance-facing v1 baseline so `migrate_v2` remains observable;
-            # startup provisioning may instead ask for the folded v2 directly.
-            for sql in _split_statements(retrieval_index_ddl("sqlite", version=version)):
-                db.execute(sql)
-            row = db.execute(
-                "SELECT schema_version FROM retrieval_index_state WHERE singleton=1"
-            ).fetchone()
-            if row is None:
-                db.execute(
-                    "INSERT INTO retrieval_index_state VALUES (1,?,?)",
-                    (version, uuid4().hex),
-                )
-            elif row[0] not in (1, 2):
-                raise ValueError("retrieval_schema_mismatch")
-
-    def migrate_v2(self, db: sqlite3.Connection) -> None:
-        """Explicit maintenance transaction only; readers/worker never invoke this."""
-        with transaction(db):
-            self._store_id(db)
-            version = db.execute("SELECT schema_version FROM retrieval_index_state").fetchone()[0]
-            if version == 2:
-                db.execute(
-                    "SELECT build_id,source_map_json,map_digest,coverage_state "
-                    "FROM retrieval_build_maps LIMIT 0"
-                )
-                return
-            if (
-                db.execute(
-                    "SELECT 1 FROM sqlite_master WHERE type='table' AND name='retrieval_build_maps'"
-                ).fetchone()
-                is not None
-            ):
-                # A v1 index must not already own a v2-only table. Treat this
-                # as a foreign/partial schema instead of letting `IF NOT
-                # EXISTS` silently accept a table with the wrong columns.
-                raise sqlite3.OperationalError("retrieval_build_maps already exists")
-            # Both tables come from migration 33, named/derived there so this
-            # module holds no DDL text of its own.
-            db.execute(retrieval_documents_v2_ddl("sqlite"))
-            db.execute("INSERT INTO retrieval_documents_v2 SELECT * FROM retrieval_documents")
-            db.execute("DROP TABLE retrieval_documents")
-            db.execute("ALTER TABLE retrieval_documents_v2 RENAME TO retrieval_documents")
-            db.execute(
-                "CREATE INDEX retrieval_jobs ON retrieval_documents(generation_id,state,event_seq)"
-            )
-            db.execute(retrieval_build_maps_ddl("sqlite"))
-            db.execute("UPDATE retrieval_index_state SET schema_version=2 WHERE singleton=1")
-
-    @staticmethod
-    def _store_id(db: sqlite3.Connection) -> str:
-        row = db.execute(
-            "SELECT schema_version,data_store_id FROM retrieval_index_state WHERE singleton=1"
-        ).fetchone()
-        if row is None or row[0] not in (1, 2) or not isinstance(row[1], str) or len(row[1]) != 32:
-            raise ValueError("retrieval_not_initialized")
-        return str(row[1])
-
-    def create_generation(self, db: sqlite3.Connection, identity: EncoderIdentity) -> str:
-        with transaction(db):
-            self._check_content_version(db, identity)
-            key = digest([self._store_id(db), asdict(identity)])
-            encoded = json.dumps(asdict(identity), sort_keys=True)
-            row = db.execute(
-                "SELECT identity_json FROM retrieval_index_generations WHERE generation_id=?",
-                (key,),
-            ).fetchone()
-            if row is not None and row[0] != encoded:
-                raise ValueError("generation_identity_changed")
-            if row is None:
-                db.execute(
-                    "INSERT INTO retrieval_index_generations VALUES (?,?,'building',?)",
-                    (key, encoded, time.time()),
-                )
-                db.execute("INSERT INTO retrieval_consumers VALUES (?,0,0)", (key,))
-            return key
-
-    def consume(self, db: sqlite3.Connection, generation_id: str, *, limit: int = 256) -> int:
-        if type(limit) is not int or not 1 <= limit <= 256:
-            raise ValueError("invalid_consume_limit")
-        with transaction(db):
-            store_id = self._store_id(db)
-            generation = db.execute(
-                "SELECT state FROM retrieval_index_generations WHERE generation_id=?",
-                (generation_id,),
-            ).fetchone()
-            if generation is None or generation[0] == "retired":
-                raise ValueError("generation_not_writable")
-            cursor = db.execute(
-                "SELECT after_seq FROM retrieval_consumers WHERE generation_id=?", (generation_id,)
-            ).fetchone()
-            if cursor is None:
-                raise ValueError("consumer_missing")
-            rows = db.execute(
-                "SELECT seq FROM evidence_ingest_events WHERE seq>? ORDER BY seq LIMIT ?",
-                (cursor[0], limit),
-            ).fetchall()
-            for row in rows:
-                event = journal.event(db, row[0])
-                if event is None:
-                    raise ValueError("journal_event_missing")
-                if event.user_id != "local":
-                    continue
-                build = digest(
-                    [
-                        store_id,
-                        generation_id,
-                        event.evidence_id,
-                        event.incarnation,
-                        event.evidence_revision,
-                        event.fingerprint,
-                    ]
-                )
-                state = "deleted" if event.kind == "delete" else "pending"
-                db.execute(
-                    """INSERT INTO retrieval_documents
-                    (generation_id,evidence_id,source_id,event_seq,build_id,state)
-                    VALUES (?,?,?,?,?,?) ON CONFLICT(generation_id,evidence_id) DO UPDATE SET
-                    source_id=excluded.source_id,event_seq=excluded.event_seq,build_id=excluded.build_id,
-                    state=excluded.state,active_build_id=NULL,lease_owner=NULL,lease_token=NULL,
-                    lease_until=NULL,grant_fingerprint=NULL
-                    WHERE excluded.event_seq>retrieval_documents.event_seq""",
-                    (generation_id, event.evidence_id, event.source_id, event.seq, build, state),
-                )
-            if rows:
-                db.execute(
-                    "UPDATE retrieval_consumers SET after_seq=? WHERE generation_id=?",
-                    (rows[-1][0], generation_id),
-                )
-            return len(rows)
-
-    def consume_pending(self, generation_id: str, *, limit: int = 256) -> int:
-        with self._db(write=True) as db:
-            return self.consume(db, generation_id, limit=limit)
-
-    def encoder_identity(self, generation_id: str) -> EncoderIdentity:
-        with self._db() as db:
-            return self._identity(db, generation_id)
-
-    @staticmethod
-    def _check_content_version(db: sqlite3.Connection, identity: EncoderIdentity) -> None:
-        versions = (identity.normalizer_version, identity.chunker_version)
-        if versions not in ((1, 1), (2, 2)):
-            raise ValueError("unsupported_content_generation")
-        if versions == (2, 2):
-            row = db.execute(
-                "SELECT schema_version FROM retrieval_index_state WHERE singleton=1"
-            ).fetchone()
-            if row is None or row[0] != 2:
-                raise ValueError("retrieval_schema2_required")
-
-    def _identity(self, db: sqlite3.Connection, generation_id: str) -> EncoderIdentity:
-        row = db.execute(
-            "SELECT identity_json FROM retrieval_index_generations WHERE generation_id=?",
-            (generation_id,),
-        ).fetchone()
-        if row is None:
-            raise ValueError("generation_missing")
-        identity = EncoderIdentity(**json.loads(row[0]))
-        if digest([self._store_id(db), asdict(identity)]) != generation_id:
-            raise ValueError("generation_identity_changed")
-        self._check_content_version(db, identity)
-        return identity
-
-    def _prepare(
-        self, db: sqlite3.Connection, generation_id: str, record: EvidenceRecord
-    ) -> PreparedMappedContent | None:
-        identity = self._identity(db, generation_id)
-        return index_content(
-            record,
-            normalizer_version=identity.normalizer_version,
-            chunker_version=identity.chunker_version,
-        )
-
-    @staticmethod
-    def _grant(db: sqlite3.Connection, source_id: str) -> str | None:
-        row = db.execute(
-            """SELECT root_path,candidate_kind,granted_at,root_identity,revision
-            FROM source_grants
-            WHERE user_id='local' AND source_id=? AND revoked_at IS NULL""",
-            (source_id,),
-        ).fetchone()
-        return digest(tuple(row)) if row and row[3] and row[4] > 0 else None
-
-    def claim(
-        self, generation_id: str, owner: str, *, now: float | None = None, lease_seconds: int = 60
-    ) -> IndexLease | None:
-        now = time.time() if now is None else now
-        if not owner or len(owner) > 128 or not math.isfinite(now) or not 1 <= lease_seconds <= 300:
-            raise ValueError("invalid_lease")
-        with self._db(write=True) as db:
-            generation = db.execute(
-                "SELECT state FROM retrieval_index_generations WHERE generation_id=?",
-                (generation_id,),
-            ).fetchone()
-            if generation is None or generation[0] == "retired":
-                raise ValueError("generation_not_writable")
-            rows = db.execute(
-                """SELECT * FROM retrieval_documents WHERE generation_id=? AND
-                (state='pending' OR (state='leased' AND lease_until<=?))
-                ORDER BY event_seq LIMIT 256""",
-                (generation_id, now),
-            ).fetchall()
-            for row in rows:
-                event = journal.event(db, row["event_seq"])
-                grant = self._grant(db, row["source_id"])
-                if event is None or grant is None or not journal.matches_current(db, event):
-                    db.execute(
-                        "UPDATE retrieval_documents SET state='blocked',active_build_id=NULL "
-                        "WHERE generation_id=? AND evidence_id=?",
-                        (generation_id, row["evidence_id"]),
-                    )
-                    continue
-                token = uuid4().hex
-                until = now + lease_seconds
-                db.execute(
-                    """UPDATE retrieval_documents SET state='leased',lease_owner=?,lease_token=?,
-                    lease_until=?,grant_fingerprint=?,attempts=attempts+1
-                    WHERE generation_id=? AND evidence_id=?""",
-                    (owner, token, until, grant, generation_id, row["evidence_id"]),
-                )
-                return IndexLease(
-                    generation_id,
-                    row["evidence_id"],
-                    row["build_id"],
-                    row["event_seq"],
-                    owner,
-                    token,
-                    until,
-                    grant,
-                )
-        return None
-
-    def _validate_lease(
-        self, db: sqlite3.Connection, lease: IndexLease, now: float
-    ) -> journal.IngestEvent:
-        if not math.isfinite(now):
-            raise ValueError("invalid_lease_time")
-        generation = db.execute(
-            "SELECT state FROM retrieval_index_generations WHERE generation_id=?",
-            (lease.generation_id,),
-        ).fetchone()
-        if generation is None or generation[0] == "retired":
-            raise ValueError("lease_generation_retired")
-        row = db.execute(
-            "SELECT * FROM retrieval_documents WHERE generation_id=? AND evidence_id=?",
-            (lease.generation_id, lease.evidence_id),
-        ).fetchone()
-        if (
-            row is None
-            or row["state"] != "leased"
-            or (
-                row["build_id"],
-                row["event_seq"],
-                row["lease_owner"],
-                row["lease_token"],
-                row["lease_until"],
-                row["grant_fingerprint"],
-            )
-            != (
-                lease.build_id,
-                lease.event_seq,
-                lease.owner,
-                lease.token,
-                lease.expires_at,
-                lease.grant_fingerprint,
-            )
-            or lease.expires_at <= now
-        ):
-            raise ValueError("lease_changed_or_expired")
-        event = journal.event(db, lease.event_seq)
-        if (
-            event is None
-            or event.user_id != "local"
-            or event.evidence_id != lease.evidence_id
-            or not journal.matches_current(db, event)
-        ):
-            raise ValueError("lease_evidence_changed")
-        if self._grant(db, event.source_id) != lease.grant_fingerprint:
-            raise ValueError("lease_source_authority_changed")
-        return event
-
-    def read_lease(self, lease: IndexLease, *, now: float | None = None) -> EvidenceRecord:
-        with self._db() as db:
-            self._validate_lease(db, lease, time.time() if now is None else now)
-            record = EvidenceStore._get_with_connection(db, lease.evidence_id)
-            if record is None or len(record.verbatim) > 2_000_000:
-                raise ValueError("lease_input_unavailable_or_too_large")
-            return record
-
-    def renew(
-        self, lease: IndexLease, *, now: float | None = None, lease_seconds: int = 60
-    ) -> IndexLease:
-        now = time.time() if now is None else now
-        if type(lease_seconds) is not int or not 1 <= lease_seconds <= 300:
-            raise ValueError("invalid_lease")
-        with self._db(write=True) as db:
-            self._validate_lease(db, lease, now)
-            expires = max(lease.expires_at, now + lease_seconds)
-            db.execute(
-                "UPDATE retrieval_documents SET lease_until=? "
-                "WHERE generation_id=? AND evidence_id=?",
-                (expires, lease.generation_id, lease.evidence_id),
-            )
-            return replace(lease, expires_at=expires)
-
-    def block(self, lease: IndexLease) -> None:
-        """Release only this claim; preserve uncertain derived vectors for later cleanup."""
-        with self._db(write=True) as db:
-            db.execute(
-                """UPDATE retrieval_documents SET state='blocked',active_build_id=NULL,
-                lease_owner=NULL,lease_token=NULL,lease_until=NULL
-                WHERE generation_id=? AND evidence_id=? AND state='leased'
-                AND build_id=? AND lease_token=? AND lease_owner=?""",
-                (lease.generation_id, lease.evidence_id, lease.build_id, lease.token, lease.owner),
-            )
-
-    def retry_blocked(self, generation_id: str) -> int:
-        """Bounded, durable round-robin retry/regrant pass; never creates grants."""
-        changed = 0
-        with self._db(write=True) as db:
-            generation = db.execute(
-                "SELECT g.state,c.retry_after_seq FROM retrieval_index_generations g "
-                "JOIN retrieval_consumers c USING(generation_id) WHERE generation_id=?",
-                (generation_id,),
-            ).fetchone()
-            if generation is None or generation[0] == "retired":
-                raise ValueError("generation_not_writable")
-            rows = db.execute(
-                "SELECT * FROM retrieval_documents WHERE generation_id=? "
-                "AND state IN ('blocked','ready','excluded') AND event_seq>? "
-                "ORDER BY event_seq LIMIT 256",
-                (generation_id, generation[1]),
-            ).fetchall()
-            for row in rows:
-                event = journal.event(db, row["event_seq"])
-                grant = self._grant(db, row["source_id"])
-                if row["state"] in ("ready", "excluded") and grant == row["grant_fingerprint"]:
-                    continue
-                if (
-                    event
-                    and event.source_id == row["source_id"]
-                    and grant
-                    and journal.matches_current(db, event)
-                ):
-                    db.execute(
-                        "UPDATE retrieval_documents SET state='pending',active_build_id=NULL,"
-                        "lease_owner=NULL,lease_token=NULL,lease_until=NULL,grant_fingerprint=NULL "
-                        "WHERE generation_id=? AND evidence_id=?",
-                        (generation_id, row["evidence_id"]),
-                    )
-                    changed += 1
-            db.execute(
-                "UPDATE retrieval_consumers SET retry_after_seq=? WHERE generation_id=?",
-                (rows[-1]["event_seq"] if len(rows) == 256 else 0, generation_id),
-            )
-        return changed
-
-    def publish(
-        self,
-        lease: IndexLease,
-        chunks: Sequence[TextChunk],
-        *,
-        vectors_verified: bool,
-        now: float | None = None,
-        source_map: ContentMap | None = None,
-        checkpoint: Callable[[], None] | None = None,
-    ) -> tuple[str, ...]:
-        """Caller verifies actual immutable vectors before entering this short transaction."""
-        if vectors_verified is not True:
-            raise ValueError("vectors_not_verified")
-        now = time.time() if now is None else now
-        if not math.isfinite(now):
-            raise ValueError("invalid_lease_time")
-        if len(chunks) > 8192:
-            raise ValueError("invalid_chunk_manifest")
-        with self._db(write=True) as db:
-            if checkpoint is not None:
-                checkpoint()
-            event = self._validate_lease(db, lease, now)
-            record = EvidenceStore._get_with_connection(db, lease.evidence_id)
-            if record is None or len(record.verbatim) > 2_000_000:
-                raise ValueError("lease_evidence_missing")
-            prepared = self._prepare(db, lease.generation_id, record)
-            if source_map != (prepared.metadata if prepared is not None else None):
-                raise ValueError("source_map_mismatch")
-            validate_chunk_coverage(record, chunks, prepared)
-            map_digest = source_map.digest if source_map is not None else None
-            keys = []
-            manifest = []
-            for index, chunk in enumerate(chunks):
-                text_hash = digest(chunk.text)
-                key = chunk_identity(lease, chunk, map_digest)
-                keys.append(key)
-                manifest.append(
-                    (
-                        key,
-                        lease.generation_id,
-                        lease.evidence_id,
-                        lease.build_id,
-                        index,
-                        chunk.start_cp,
-                        chunk.end_cp,
-                        chunk.token_count,
-                        text_hash,
-                    )
-                )
-            existing = db.execute(
-                "SELECT * FROM retrieval_chunks WHERE build_id=? ORDER BY ordinal",
-                (lease.build_id,),
-            ).fetchall()
-            if existing:
-                if [tuple(row) for row in existing] != manifest:
-                    raise ValueError("immutable_chunk_manifest_conflict")
-            else:
-                db.executemany("INSERT INTO retrieval_chunks VALUES (?,?,?,?,?,?,?,?,?)", manifest)
-            state = "ready" if chunks else "excluded"
-            if source_map is not None:
-                values = (
-                    lease.build_id,
-                    source_map.canonical_json(),
-                    map_digest,
-                    "indexable" if chunks else "excluded",
-                )
-                prior = db.execute(
-                    "SELECT * FROM retrieval_build_maps WHERE build_id=?", (lease.build_id,)
-                ).fetchone()
-                if prior is not None and tuple(prior) != values:
-                    raise ValueError("immutable_source_map_conflict")
-                if prior is None:
-                    db.execute("INSERT INTO retrieval_build_maps VALUES (?,?,?,?)", values)
-            if not journal.matches_current(db, event):
-                raise ValueError("lease_evidence_changed")
-            db.execute(
-                "UPDATE retrieval_documents SET state=?,active_build_id=build_id,"
-                "lease_owner=NULL,lease_token=NULL,lease_until=NULL "
-                "WHERE generation_id=? AND evidence_id=?",
-                (state, lease.generation_id, lease.evidence_id),
-            )
-            if checkpoint is not None:
-                checkpoint()
-            return tuple(keys)
-
-    def activate_generation(self, generation_id: str) -> None:
-        with self._db(write=True) as db:
-            row = db.execute(
-                "SELECT state FROM retrieval_index_generations WHERE generation_id=?",
-                (generation_id,),
-            ).fetchone()
-            cursor = db.execute(
-                "SELECT after_seq FROM retrieval_consumers WHERE generation_id=?", (generation_id,)
-            ).fetchone()
-            if (
-                row is None
-                or row[0] == "retired"
-                or cursor is None
-                or cursor[0] != journal.watermark(db)
-            ):
-                raise ValueError("generation_not_caught_up")
-            for document in db.execute(
-                "SELECT * FROM retrieval_documents WHERE generation_id=? "
-                "AND state NOT IN ('ready','excluded','deleted')",
-                (generation_id,),
-            ):
-                if self._grant(db, document["source_id"]) is not None:
-                    raise ValueError("generation_incomplete")
-            for document in db.execute(
-                "SELECT * FROM retrieval_documents WHERE generation_id=? "
-                "AND state IN ('ready','excluded')",
-                (generation_id,),
-            ):
-                if self._grant(db, document["source_id"]) is not None:
-                    event = journal.event(db, document["event_seq"])
-                    if (
-                        not event
-                        or not journal.matches_current(db, event)
-                        or self._grant(db, document["source_id"]) != document["grant_fingerprint"]
-                    ):
-                        raise ValueError("generation_stale")
-                    record = EvidenceStore._get_with_connection(db, document["evidence_id"])
-                    if record is None:
-                        raise ValueError("generation_stale")
-                    self.validate_document(db, document, record)
-            db.execute(
-                "UPDATE retrieval_index_generations SET state='retired' "
-                "WHERE state='active' AND generation_id!=?",
-                (generation_id,),
-            )
-            db.execute(
-                "UPDATE retrieval_index_generations SET state='active' WHERE generation_id=?",
-                (generation_id,),
-            )
-
-    def active_chunks(
-        self,
-        generation_id: str,
-        *,
-        source_ids: frozenset[str] | None = None,
-        time_range: TimeRange | None = None,
-        deadline: float | None = None,
-        require_active: bool = False,
-    ) -> tuple[PublishedChunk, ...]:
-        """Return current chunks after SQL-level source/time eligibility filtering.
-
-        Grant fingerprints, journal freshness, and manifests are still checked
-        below in the same snapshot. The SQL predicate keeps unauthorized rows
-        from filling an in-memory candidate set before those checks run.
-        """
-        if source_ids is not None and not source_ids:
-            return ()
-        with self._db(deadline=deadline) as db:
-            generation = db.execute(
-                "SELECT state FROM retrieval_index_generations WHERE generation_id=?",
-                (generation_id,),
-            ).fetchone()
-            if generation is None or generation[0] != "active":
-                if require_active:
-                    raise ValueError("active_generation_changed")
-                return ()
-            clauses = ["d.generation_id=?", "d.state IN ('ready','excluded')"]
-            parameters: list[object] = [generation_id]
-            join = ""
-            if source_ids is not None:
-                clauses.append("d.source_id IN (SELECT value FROM json_each(?))")
-                parameters.append(json.dumps(sorted(source_ids)))
-            if time_range is not None:
-                join = "JOIN evidence e ON e.evidence_id=d.evidence_id "
-                clauses.extend(
-                    (
-                        "e.created_at IS NOT NULL",
-                        "julianday(e.created_at) >= julianday(?)",
-                        "julianday(e.created_at) < julianday(?)",
-                    )
-                )
-                parameters.extend((time_range.start.isoformat(), time_range.end.isoformat()))
-            output = []
-            for row in db.execute(
-                "SELECT d.* FROM retrieval_documents d "
-                + join
-                + f"WHERE {' AND '.join(clauses)} ORDER BY d.event_seq,d.evidence_id",
-                parameters,
-            ):
-                if deadline is not None:
-                    _check(deadline)
-                grant = self._grant(db, row["source_id"])
-                if grant is None or grant != row["grant_fingerprint"]:
-                    continue
-                event = journal.event(db, row["event_seq"])
-                if (
-                    event is None
-                    or event.source_id != row["source_id"]
-                    or not journal.matches_current(db, event)
-                ):
-                    continue
-                record = EvidenceStore._get_with_connection(db, row["evidence_id"])
-                if (
-                    record is None
-                    or record.user_id != "local"
-                    or record.source_id != row["source_id"]
-                ):
-                    continue
-                event_time = record.created_at
-                if event_time is not None:
-                    event_time = event_time.astimezone(UTC) if event_time.tzinfo else None
-                if time_range is not None and (
-                    event_time is None or not time_range.start <= event_time < time_range.end
-                ):
-                    continue
-                chunks = self.validate_document(db, row, record, deadline=deadline)
-                for chunk in chunks:
-                    if deadline is not None:
-                        _check(deadline)
-                    output.append(
-                        PublishedChunk(
-                            chunk["chunk_id"],
-                            row["build_id"],
-                            row["evidence_id"],
-                            event.evidence_revision,
-                            chunk["start_cp"],
-                            chunk["end_cp"],
-                            chunk["ordinal"],
-                            record.source_id,
-                            event_time,
-                        )
-                    )
-            return tuple(output)
-
-    def validate_document(
-        self,
-        db: sqlite3.Connection,
-        document: sqlite3.Row,
-        record: EvidenceRecord,
-        *,
-        deadline: float | None = None,
-    ) -> tuple[sqlite3.Row, ...]:
-        """Same-snapshot complete manifest/map check shared by candidate and final read."""
-        if deadline is not None:
-            _check(deadline)
-        if document["active_build_id"] != document["build_id"]:
-            raise ValueError("published_build_binding_invalid")
-        prepared = self._prepare(db, document["generation_id"], record)
-        map_digest = None
-        if prepared is not None:
-            source_map = db.execute(
-                "SELECT source_map_json,map_digest,coverage_state FROM retrieval_build_maps "
-                "WHERE build_id=?",
-                (document["build_id"],),
-            ).fetchone()
-            expected_state = "excluded" if prepared.state == "no_indexable_content" else "ready"
-            if (
-                source_map is None
-                or tuple(source_map)
-                != (
-                    prepared.metadata.canonical_json(),
-                    prepared.metadata.digest,
-                    "excluded" if expected_state == "excluded" else "indexable",
-                )
-                or document["state"] != expected_state
-            ):
-                raise ValueError("published_source_map_invalid")
-            map_digest = prepared.metadata.digest
-        elif document["state"] != "ready":
-            raise ValueError("published_manifest_invalid")
-        rows = tuple(
-            db.execute(
-                "SELECT * FROM retrieval_chunks WHERE generation_id=? AND evidence_id=? "
-                "AND build_id=? ORDER BY ordinal LIMIT 8193",
-                (document["generation_id"], record.evidence_id, document["build_id"]),
-            ).fetchall()
-        )
-        chunks = []
-        for row in rows:
-            if deadline is not None:
-                _check(deadline)
-            start, end = row["start_cp"], row["end_cp"]
-            if (
-                type(start) is not int
-                or type(end) is not int
-                or not 0 <= start < end <= len(record.verbatim)
-            ):
-                raise ValueError("published_manifest_invalid")
-            text = record.verbatim[start:end]
-            text_hash = digest(text)
-            identity = [document["build_id"], row["ordinal"], start, end, text_hash]
-            if map_digest is not None:
-                identity.append(map_digest)
-            if row["text_hash"] != text_hash or row["chunk_id"] != digest(identity):
-                raise ValueError("published_manifest_invalid")
-            chunks.append(TextChunk(row["ordinal"], start, end, row["token_count"], text))
-        try:
-            validate_chunk_coverage(record, chunks, prepared)
-        except ValueError as error:
-            raise ValueError("published_manifest_incomplete_or_invalid") from error
-        if deadline is not None:
-            _check(deadline)
-        return rows
-
-    def status(self, generation_id: str) -> dict[str, int]:
-        with self._db() as db:
-            row = db.execute(
-                "SELECT after_seq FROM retrieval_consumers WHERE generation_id=?", (generation_id,)
-            ).fetchone()
-            if row is None:
-                raise ValueError("generation_missing")
-            result = {
-                "after_seq": int(row[0]),
-                "pending": 0,
-                "leased": 0,
-                "ready": 0,
-                "blocked": 0,
-                "deleted": 0,
-                "excluded": 0,
-            }
-            for state, count in db.execute(
-                "SELECT state,count(*) FROM retrieval_documents "
-                "WHERE generation_id=? GROUP BY state",
-                (generation_id,),
-            ):
-                result[state] = count
-            return result

memhub/apps/core/src/one_memory/retrieval/index_supervisor.py

@@ -1,200 +0,0 @@
-"""Explicit ownership of one admitted index worker; no migration or resource close."""
-
-import asyncio
-import math
-import threading
-import time
-from collections.abc import Callable
-from dataclasses import dataclass
-from typing import Literal, Protocol
-
-from one_memory.retrieval.index_worker import IndexWorkResult
-from one_memory.service_levels import ServiceLevel, service_level_context
-
-
-class IndexWorker(Protocol):
-    def run_once(self, *, cancel: threading.Event | None = None) -> IndexWorkResult: ...
-
-
-@dataclass(frozen=True)
-class IndexSupervisorSnapshot:
-    state: Literal["new", "running", "stopping", "stopped"]
-    last_result: str | None
-    error_code: str | None
-    slices: int
-    failures: int
-    thread_alive: bool
-
-
-class RetrievalIndexSupervisor:
-    """Single-use supervisor. Caller owns admission and closes vectors only after stop.
-
-    Cancellation is cooperative: stop/wait cannot finish until a blocking native
-    run_once returns. The lifecycle owner must drain before shutting its event loop.
-    """
-
-    def __init__(
-        self,
-        worker: IndexWorker,
-        *,
-        idle_wait_seconds: float = 5,
-        failure_wait_seconds: float = 5,
-        yield_wait_seconds: float = 0.05,
-        max_consecutive_slices: int = 8,
-        background_should_yield: Callable[[], bool] | None = None,
-    ):
-        for interval in (idle_wait_seconds, failure_wait_seconds, yield_wait_seconds):
-            if (
-                isinstance(interval, bool)
-                or not isinstance(interval, (int, float))
-                or not math.isfinite(interval)
-                or not 0.001 <= interval <= 300
-            ):
-                raise ValueError("index_supervisor_invalid_config")
-        if type(max_consecutive_slices) is not int or not 1 <= max_consecutive_slices <= 256:
-            raise ValueError("index_supervisor_invalid_config")
-        self._worker = worker
-        self._idle_wait = idle_wait_seconds
-        self._failure_wait = failure_wait_seconds
-        self._yield_wait = yield_wait_seconds
-        self._max_slices = max_consecutive_slices
-        self._background_should_yield = background_should_yield or (lambda: False)
-        self._condition = threading.Condition()
-        self._cancel = threading.Event()
-        self._wake = False
-        self._thread: threading.Thread | None = None
-        self._state: Literal["new", "running", "stopping", "stopped"] = "new"
-        self._last_result: str | None = None
-        self._error_code: str | None = None
-        self._slices = self._failures = 0
-
-    def start(self) -> None:
-        with self._condition:
-            if self._state != "new":
-                raise RuntimeError("index_supervisor_already_started")
-            thread = threading.Thread(target=self._run, name="retrieval-index", daemon=False)
-            self._thread = thread
-            self._state = "running"
-            try:
-                thread.start()
-            except Exception:
-                self._thread = None
-                self._state = "stopped"
-                self._error_code = "index_supervisor_start_failed"
-                raise RuntimeError("index_supervisor_start_failed") from None
-
-    def trigger(self) -> bool:
-        with self._condition:
-            if self._state != "running":
-                return False
-            self._wake = True
-            self._condition.notify_all()
-            return True
-
-    def snapshot(self) -> IndexSupervisorSnapshot:
-        with self._condition:
-            return IndexSupervisorSnapshot(
-                self._state,
-                self._last_result,
-                self._error_code,
-                self._slices,
-                self._failures,
-                self._thread is not None and self._thread.is_alive(),
-            )
-
-    def _request_stop(self) -> None:
-        with self._condition:
-            self._cancel.set()
-            self._wake = False
-            if self._state == "new":
-                self._state = "stopped"
-            elif self._state == "running":
-                self._state = "stopping"
-            self._condition.notify_all()
-
-    async def stop(self) -> None:
-        self._request_stop()
-        await self.wait()
-
-    async def wait(self) -> None:
-        """Cancellation requests shutdown, drains the real thread, then propagates."""
-        cancelled = False
-        while True:
-            with self._condition:
-                thread = self._thread
-            if thread is None or not thread.is_alive():
-                if thread is not None:
-                    thread.join()
-                break
-            try:
-                # No executor waiter or to_thread future to orphan on cancellation.
-                await asyncio.sleep(0.01)
-            except asyncio.CancelledError:
-                cancelled = True
-                self._request_stop()
-        if cancelled:
-            raise asyncio.CancelledError
-
-    def _pause(self, seconds: float, *, wakeable: bool) -> None:
-        deadline = time.monotonic() + seconds
-        with self._condition:
-            while not self._cancel.is_set():
-                if wakeable and self._wake:
-                    break
-                remaining = deadline - time.monotonic()
-                if remaining <= 0:
-                    break
-                self._condition.wait(remaining)
-            self._wake = False
-
-    def _run(self) -> None:
-        consecutive = 0
-        try:
-            while not self._cancel.is_set():
-                if self._background_should_yield():
-                    self._pause(self._yield_wait, wakeable=False)
-                    continue
-                result: str | None = None
-                error: str | None = None
-                try:
-                    with service_level_context(ServiceLevel.BACKGROUND):
-                        value = self._worker.run_once(cancel=self._cancel)
-                    if not isinstance(value, IndexWorkResult) or value.state not in {
-                        "idle",
-                        "ready",
-                        "excluded",
-                        "blocked",
-                        "cancelled",
-                        "deferred",
-                    }:
-                        error = "index_worker_invalid_result"
-                    else:
-                        result = value.state
-                        if result == "blocked":
-                            error = "index_worker_blocked"
-                except BaseException:
-                    # Worker/provider exceptions must never escape via thread stderr.
-                    error = "index_worker_failed"
-                with self._condition:
-                    self._last_result, self._error_code = result, error
-                    self._slices += 1
-                    if error is not None:
-                        self._failures += 1
-                if self._cancel.is_set():
-                    break
-                if error is not None:
-                    consecutive = 0
-                    self._pause(self._failure_wait, wakeable=False)
-                elif result in {"ready", "excluded"}:
-                    consecutive += 1
-                    if consecutive >= self._max_slices:
-                        consecutive = 0
-                        self._pause(self._yield_wait, wakeable=False)
-                else:
-                    consecutive = 0
-                    self._pause(self._idle_wait, wakeable=True)
-        finally:
-            with self._condition:
-                self._state = "stopped"
-                self._wake = False
-                self._condition.notify_all()

memhub/apps/core/src/one_memory/retrieval/index_worker.py

@@ -1,262 +0,0 @@
-"""Bounded raw-index work. No migration, scheduler, HY or remote model invocation.
-
-Runtime must admit a single worker, own its thread/process, and drain that owner
-before closing the vector client. Cancellation here is cooperative between
-native calls, not a claim that ONNX/Chroma can be preempted in a Python thread.
-"""
-
-import math
-import threading
-import time
-from collections.abc import Callable, Sequence
-from dataclasses import dataclass
-from typing import Literal, Protocol
-
-from one_memory.embedding_assets import (
-    BUILTIN_EMBEDDING_MODEL,
-    EMBEDDING_ASSETS,
-    verify_assets,
-)
-from one_memory.local_embedding import LocalEmbedder, TokenizedText
-from one_memory.retrieval.chunking import ChunkingError, chunk_evidence
-from one_memory.retrieval.content import index_content
-from one_memory.retrieval.index_store import (
-    EncoderIdentity,
-    IndexLease,
-    RetrievalIndexStore,
-    chunk_identity,
-)
-from one_memory.retrieval.mapped_content import MappedContentError, chunk_mapped_content
-from one_memory.retrieval.vector_store import RawVectorRecord, RawVectorStore, VectorStoreError
-
-
-class RetrievalEncoder(Protocol):
-    @property
-    def identity(self) -> EncoderIdentity: ...
-
-    def tokenize_with_offsets(self, text: str) -> TokenizedText: ...
-
-    def encode_documents(self, texts: list[str]) -> list[list[float]]: ...
-
-
-class LocalRetrievalEncoder:
-    """Pinned local assets; mapped content v2 by default, explicit v1 for old generations."""
-
-    def __init__(self, embedder: LocalEmbedder | None = None, *, content_version: int = 2):
-        if type(content_version) is not int or content_version not in (1, 2):
-            raise ValueError("unsupported_content_generation")
-        self._embedder = embedder if embedder is not None else LocalEmbedder()
-        digests = {asset.filename: asset.sha256 for asset in EMBEDDING_ASSETS}
-        self.identity = EncoderIdentity(
-            BUILTIN_EMBEDDING_MODEL,
-            digests["model_int8.onnx"],
-            digests["tokenizer.json"],
-            self._embedder.dimensions,
-            chunker_version=content_version,
-            normalizer_version=content_version,
-        )
-        self._verified = False
-        self._lock = threading.Lock()
-
-    def _verify(self) -> None:
-        with self._lock:
-            if not self._verified:
-                verify_assets()
-                self._verified = True
-
-    def tokenize_with_offsets(self, text: str) -> TokenizedText:
-        self._verify()
-        return self._embedder.tokenize_with_offsets(text)
-
-    def encode_documents(self, texts: list[str]) -> list[list[float]]:
-        self._verify()
-        if len(texts) > 8 or any(
-            not 1 <= len(self.tokenize_with_offsets(text).token_ids) <= 512 for text in texts
-        ):
-            raise ValueError("encoder_batch_or_token_budget")
-        with self._lock:
-            return self._embedder.encode(texts)
-
-
-@dataclass(frozen=True)
-class IndexWorkResult:
-    state: Literal["idle", "ready", "excluded", "blocked", "cancelled", "deferred"]
-    reason: str | None = None
-    chunk_count: int = 0
-
-
-class _Interrupted(Exception):
-    def __init__(self, state: Literal["cancelled", "deferred"]):
-        self.state = state
-
-
-class RetrievalIndexWorker:
-    def __init__(
-        self,
-        store: RetrievalIndexStore,
-        vectors: RawVectorStore,
-        encoder: RetrievalEncoder,
-        *,
-        generation_id: str,
-        owner: str,
-        clock: Callable[[], float] = time.monotonic,
-        wall_clock: Callable[[], float] = time.time,
-        max_job_seconds: float = 120,
-    ):
-        if (
-            not owner
-            or len(owner) > 128
-            or isinstance(max_job_seconds, bool)
-            or not math.isfinite(max_job_seconds)
-            or not 0 < max_job_seconds <= 300
-        ):
-            raise ValueError("invalid_worker_budget")
-        if store.encoder_identity(generation_id) != encoder.identity:
-            raise ValueError("worker_encoder_identity_mismatch")
-        if (
-            vectors.generation_id != generation_id
-            or vectors.dimensions != encoder.identity.dimensions
-        ):
-            raise ValueError("worker_vector_identity_mismatch")
-        self.store, self.vectors, self.encoder = store, vectors, encoder
-        self.generation_id, self.owner = generation_id, owner
-        self.clock, self.wall_clock = clock, wall_clock
-        self.max_job_seconds = max_job_seconds
-        self._run_lock = threading.Lock()
-
-    def run_once(self, *, cancel: threading.Event | None = None) -> IndexWorkResult:
-        """Consume <=256 events and handle <=1 document; never activate a generation.
-
-        Interrupted jobs retain their finite lease for restart recovery. Failed
-        jobs are blocked for explicit retry; arbitrary provider exceptions and
-        original text never enter the public result or a log.
-        """
-        if not self._run_lock.acquire(blocking=False):
-            raise RuntimeError("index_worker_already_running")
-        lease: IndexLease | None = None
-        deadline = self.clock() + self.max_job_seconds
-
-        def check() -> None:
-            if cancel is not None and cancel.is_set():
-                raise _Interrupted("cancelled")
-            now = self.clock()
-            if not math.isfinite(now) or now >= deadline:
-                raise _Interrupted("deferred")
-
-        def boundary() -> None:
-            nonlocal lease
-            check()
-            assert lease is not None
-            # This revalidates the original's current fingerprint and authority,
-            # not just a heartbeat on an otherwise stale claim.
-            lease = self.store.renew(lease, now=self.wall_clock())
-            check()
-
-        def publish_checkpoint() -> None:
-            check()
-            assert lease is not None
-            now = self.wall_clock()
-            if not math.isfinite(now) or now >= lease.expires_at:
-                raise ValueError("lease_changed_or_expired")
-
-        try:
-            check()
-            self.store.consume_pending(self.generation_id)
-            check()
-            lease = self.store.claim(self.generation_id, self.owner, now=self.wall_clock())
-            if lease is None:
-                return IndexWorkResult("idle")
-            record = self.store.read_lease(lease, now=self.wall_clock())
-            check()
-            identity = self.encoder.identity
-            try:
-                prepared = index_content(
-                    record,
-                    normalizer_version=identity.normalizer_version,
-                    chunker_version=identity.chunker_version,
-                )
-            except ValueError:
-                self.store.block(lease)
-                return IndexWorkResult("blocked", "content_mapping_required")
-
-            worker_encoder = self.encoder
-
-            class CheckedTokenizer:
-                def tokenize_with_offsets(self, text: str) -> TokenizedText:
-                    check()
-                    result = worker_encoder.tokenize_with_offsets(text)
-                    check()
-                    return result
-
-            chunks = (
-                chunk_mapped_content(prepared, CheckedTokenizer())
-                if prepared is not None
-                else chunk_evidence(record.verbatim, CheckedTokenizer())
-            )
-            if (not chunks and prepared is None) or len(chunks) > 8192:
-                raise ChunkingError("invalid_chunk_count")
-            source_map = prepared.metadata if prepared is not None else None
-            map_digest = source_map.digest if source_map is not None else None
-            boundary()
-            expected: list[RawVectorRecord] = []
-            for start in range(0, len(chunks), 8):
-                batch = chunks[start : start + 8]
-                boundary()
-                encoded = self.encoder.encode_documents([chunk.text for chunk in batch])
-                boundary()
-                if len(encoded) != len(batch):
-                    raise ValueError("encoder_count_mismatch")
-                records = [
-                    RawVectorRecord(
-                        chunk_identity(lease, chunk, map_digest),
-                        lease.build_id,
-                        lease.generation_id,
-                        tuple(vector),
-                    )
-                    for chunk, vector in zip(batch, encoded, strict=True)
-                ]
-                self.vectors.upsert(records)
-                boundary()
-                expected.extend(records)
-            self._verify(expected, boundary)
-            assert lease is not None
-            check()
-            self.store.publish(
-                lease,
-                chunks,
-                vectors_verified=True,
-                now=self.wall_clock(),
-                source_map=source_map,
-                checkpoint=publish_checkpoint,
-            )
-            return IndexWorkResult("ready" if chunks else "excluded", chunk_count=len(chunks))
-        except _Interrupted as error:
-            return IndexWorkResult(
-                error.state, "cancelled" if error.state == "cancelled" else "deadline"
-            )
-        except Exception as error:
-            cause: BaseException | None = error
-            while cause is not None:
-                if isinstance(cause, _Interrupted):
-                    return IndexWorkResult(
-                        cause.state, "cancelled" if cause.state == "cancelled" else "deadline"
-                    )
-                cause = cause.__cause__
-            if lease is None:
-                raise
-            self.store.block(lease)
-            reason = (
-                "chunking_unavailable"
-                if isinstance(error, (ChunkingError, MappedContentError))
-                else "vector_unavailable"
-                if isinstance(error, VectorStoreError)
-                else "index_build_unavailable"
-            )
-            return IndexWorkResult("blocked", reason)
-        finally:
-            self._run_lock.release()
-
-    def _verify(self, records: Sequence[RawVectorRecord], boundary: Callable[[], None]) -> None:
-        for start in range(0, len(records), 8):
-            self.vectors.verify(records[start : start + 8])
-            boundary()

memhub/apps/core/src/one_memory/retrieval/mapped_content.py

@@ -1,349 +0,0 @@
-"""Pure raw-content admission and exact source maps; no grants, writes or HY calls."""
-
-import hashlib
-import json
-from dataclasses import asdict, dataclass, field
-from typing import Literal
-
-from one_memory.conversation_processing import _is_hy_input_turn
-from one_memory.embedding_assets import BUILTIN_EMBEDDING_MAX_TOKENS
-from one_memory.imports.models import (
-    MAX_VERBATIM_CHARACTERS,
-    EvidenceContentKind,
-    EvidenceRecord,
-)
-from one_memory.imports.sources.parsing import (
-    is_host_generated_user_turn,
-    unwrap_host_envelope_with_positions,
-)
-from one_memory.input_sanitization import sanitize_model_input_with_spans
-from one_memory.local_embedding import TokenizedText
-from one_memory.retrieval.chunking import ChunkingError, OffsetTokenizer, TextChunk, chunk_evidence
-
-MAP_VERSION = "raw-content-map-v1"
-PARSER_VERSION = "host-envelope-positions-v1"
-SANITIZER_VERSION = "model-input-spans-v1"
-MAX_MAPPED_CHUNKS = 8192
-
-
-class MappedContentError(ValueError):
-    """Fixed reason only; never include original or sanitized content."""
-
-
-@dataclass(frozen=True)
-class MappedSegment:
-    kind: Literal["copy", "synthetic"]
-    start_cp: int
-    end_cp: int
-    source_start_cp: int | None
-    source_end_cp: int | None
-
-
-@dataclass(frozen=True)
-class ExcludedRange:
-    start_cp: int
-    end_cp: int
-    reason: Literal["envelope_or_trim", "sanitizer"]
-
-
-@dataclass(frozen=True)
-class ContentMap:
-    map_version: str
-    parser_version: str
-    sanitizer_version: str
-    source_length_cp: int
-    body_start_cp: int | None
-    body_end_cp: int | None
-    sanitized_length_cp: int
-    sanitized_sha256: str
-    segments: tuple[MappedSegment, ...]
-    excluded: tuple[ExcludedRange, ...]
-
-    def canonical_json(self) -> str:
-        return json.dumps(asdict(self), sort_keys=True, separators=(",", ":"), allow_nan=False)
-
-    @property
-    def digest(self) -> str:
-        return hashlib.sha256(self.canonical_json().encode()).hexdigest()
-
-
-@dataclass(frozen=True)
-class PreparedMappedContent:
-    actual_text: str = field(repr=False)
-    metadata: ContentMap
-    state: Literal["ready", "no_indexable_content"]
-
-
-def _validate(content: PreparedMappedContent, original: str | None = None) -> None:
-    meta, text = content.metadata, content.actual_text
-    invalid = "mapped_invalid_source_map"
-    if (
-        (meta.map_version, meta.parser_version, meta.sanitizer_version)
-        != (MAP_VERSION, PARSER_VERSION, SANITIZER_VERSION)
-        or type(meta.source_length_cp) is not int
-        or not 0 <= meta.source_length_cp <= MAX_VERBATIM_CHARACTERS
-        or type(meta.sanitized_length_cp) is not int
-        or meta.sanitized_length_cp != len(text)
-        or meta.sanitized_sha256 != hashlib.sha256(text.encode()).hexdigest()
-        or type(meta.segments) is not tuple
-        or type(meta.excluded) is not tuple
-    ):
-        raise MappedContentError(invalid)
-    body_start, body_end = meta.body_start_cp, meta.body_end_cp
-    if body_start is None or body_end is None:
-        if body_start is not None or body_end is not None or text or meta.segments:
-            raise MappedContentError(invalid)
-    elif (
-        type(body_start) is not int
-        or type(body_end) is not int
-        or not 0 <= body_start < body_end <= meta.source_length_cp
-    ):
-        raise MappedContentError(invalid)
-    cursor = source_cursor = 0
-    has_content = False
-    partition: list[tuple[int, int]] = []
-    for span in meta.segments:
-        if (
-            not isinstance(span, MappedSegment)
-            or type(span.start_cp) is not int
-            or type(span.end_cp) is not int
-            or not cursor == span.start_cp < span.end_cp <= len(text)
-        ):
-            raise MappedContentError(invalid)
-        cursor = span.end_cp
-        if span.kind == "synthetic":
-            if span.source_start_cp is not None or span.source_end_cp is not None:
-                raise MappedContentError(invalid)
-            continue
-        left, right = span.source_start_cp, span.source_end_cp
-        if (
-            span.kind != "copy"
-            or type(left) is not int
-            or type(right) is not int
-            or body_start is None
-            or body_end is None
-            or not body_start <= left < right <= body_end
-            or left < source_cursor
-            or right - left != span.end_cp - span.start_cp
-        ):
-            raise MappedContentError(invalid)
-        if original is not None and text[span.start_cp : span.end_cp] != original[left:right]:
-            raise MappedContentError(invalid)
-        has_content |= bool(text[span.start_cp : span.end_cp].strip())
-        source_cursor = right
-        partition.append((left, right))
-    if cursor != len(text):
-        raise MappedContentError(invalid)
-    excluded_end = 0
-    for excluded in meta.excluded:
-        if (
-            not isinstance(excluded, ExcludedRange)
-            or type(excluded.start_cp) is not int
-            or type(excluded.end_cp) is not int
-            or not excluded_end <= excluded.start_cp < excluded.end_cp <= meta.source_length_cp
-            or excluded.reason not in {"envelope_or_trim", "sanitizer"}
-        ):
-            raise MappedContentError(invalid)
-        excluded_end = excluded.end_cp
-        partition.append((excluded.start_cp, excluded.end_cp))
-    source_cursor = 0
-    for left, right in sorted(partition):
-        if left != source_cursor:
-            raise MappedContentError(invalid)
-        source_cursor = right
-    if source_cursor != meta.source_length_cp or content.state != (
-        "ready" if has_content else "no_indexable_content"
-    ):
-        raise MappedContentError(invalid)
-
-
-def prepare_mapped_content(record: EvidenceRecord) -> PreparedMappedContent:
-    """Map a qualified body to Evidence.verbatim code points, without modifying it.
-
-    The returned text is transient; only metadata is suitable for an outer manifest.
-    That manifest must independently bind Evidence identity/revision/hash and grants.
-    """
-    if record.content_kind is not EvidenceContentKind.RAW_CONVERSATION or record.role not in {
-        "user",
-        "assistant",
-    }:
-        raise MappedContentError("mapped_content_ineligible")
-    original = record.verbatim
-    if len(original) > MAX_VERBATIM_CHARACTERS:
-        raise MappedContentError("mapped_source_limit_exceeded")
-    envelope = unwrap_host_envelope_with_positions(original)
-    if envelope.status == "ambiguous":
-        raise MappedContentError("mapped_ambiguous_envelope")
-    body, start, end = envelope.text, envelope.start_cp, envelope.end_cp
-    segments: list[MappedSegment] = []
-    excluded: list[ExcludedRange] = []
-    text = ""
-    if body is None:
-        if start is not None or end is not None:
-            raise MappedContentError("mapped_invalid_envelope")
-        if original:
-            excluded.append(ExcludedRange(0, len(original), "envelope_or_trim"))
-    else:
-        if (
-            type(start) is not int
-            or type(end) is not int
-            or not 0 <= start < end <= len(original)
-            or original[start:end] != body
-        ):
-            raise MappedContentError("mapped_invalid_envelope")
-        if is_host_generated_user_turn(original) or is_host_generated_user_turn(body):
-            raise MappedContentError("mapped_generated_content")
-        if not _is_hy_input_turn(record.model_copy(update={"verbatim": body})):
-            raise MappedContentError("mapped_body_hygiene_rejected")
-        sanitized = sanitize_model_input_with_spans(body)
-        text = sanitized.text
-        cursor = 0
-        for span in sanitized.spans:
-            if span.start_cp > cursor:
-                segments.append(MappedSegment("synthetic", cursor, span.start_cp, None, None))
-            copied = MappedSegment(
-                "copy",
-                span.start_cp,
-                span.end_cp,
-                start + span.source_start_cp,
-                start + span.source_end_cp,
-            )
-            # Only source AND output adjacency can make one citation-safe interval.
-            if (
-                segments
-                and segments[-1].kind == "copy"
-                and (
-                    segments[-1].end_cp == copied.start_cp
-                    and segments[-1].source_end_cp == copied.source_start_cp
-                )
-            ):
-                previous = segments.pop()
-                copied = MappedSegment(
-                    "copy",
-                    previous.start_cp,
-                    copied.end_cp,
-                    previous.source_start_cp,
-                    copied.source_end_cp,
-                )
-            segments.append(copied)
-            cursor = span.end_cp
-        if cursor < len(text):
-            segments.append(MappedSegment("synthetic", cursor, len(text), None, None))
-        if start:
-            excluded.append(ExcludedRange(0, start, "envelope_or_trim"))
-        excluded.extend(
-            ExcludedRange(start + left, start + right, "sanitizer")
-            for left, right in sanitized.excluded
-        )
-        if end < len(original):
-            excluded.append(ExcludedRange(end, len(original), "envelope_or_trim"))
-    metadata = ContentMap(
-        MAP_VERSION,
-        PARSER_VERSION,
-        SANITIZER_VERSION,
-        len(original),
-        start,
-        end,
-        len(text),
-        hashlib.sha256(text.encode()).hexdigest(),
-        tuple(segments),
-        tuple(excluded),
-    )
-    prepared = PreparedMappedContent(
-        text,
-        metadata,
-        "ready"
-        if any(
-            span.kind == "copy" and text[span.start_cp : span.end_cp].strip() for span in segments
-        )
-        else "no_indexable_content",
-    )
-    _validate(prepared, original)
-    return prepared
-
-
-class _BoundedTokenizer:
-    """Count successful chunk re-encodings without copying the chunking algorithm."""
-
-    def __init__(self, tokenizer: OffsetTokenizer, remaining: int, max_tokens: int):
-        self.tokenizer = tokenizer
-        self.remaining = remaining
-        self.max_tokens = max_tokens
-        self.initial = True
-
-    def tokenize_with_offsets(self, text: str) -> TokenizedText:
-        if not self.initial and self.remaining == 0:
-            raise MappedContentError("mapped_chunk_limit_exceeded")
-        result = self.tokenizer.tokenize_with_offsets(text)
-        # chunk_evidence first encodes the whole copy span, then prefix+candidate;
-        # an in-budget candidate emits exactly one chunk. Shrink retries do not.
-        if (
-            not self.initial
-            and isinstance(result, TokenizedText)
-            and len(result.token_ids) <= self.max_tokens
-        ):
-            self.remaining -= 1
-        self.initial = False
-        return result
-
-
-def chunk_mapped_content(
-    content: PreparedMappedContent,
-    tokenizer: OffsetTokenizer,
-    *,
-    prefix: str = "",
-    target_tokens: int = 384,
-    overlap_tokens: int = 64,
-    max_tokens: int = BUILTIN_EMBEDDING_MAX_TOKENS,
-    max_chunks: int = MAX_MAPPED_CHUNKS,
-) -> tuple[TextChunk, ...]:
-    """Chunk each continuous copy independently; never encode synthetic placeholders."""
-    if type(max_chunks) is not int or not 1 <= max_chunks <= MAX_MAPPED_CHUNKS:
-        raise MappedContentError("mapped_invalid_chunk_limit")
-    _validate(content)
-    # Reuse budget validation even for an explicitly nonindexable record.
-    chunk_evidence(
-        "",
-        tokenizer,
-        prefix=prefix,
-        target_tokens=target_tokens,
-        overlap_tokens=overlap_tokens,
-        max_tokens=max_tokens,
-    )
-    chunks: list[TextChunk] = []
-    for span in content.metadata.segments:
-        if span.kind != "copy":
-            continue
-        text = content.actual_text[span.start_cp : span.end_cp]
-        if not text.strip():
-            continue
-        if len(chunks) == max_chunks:
-            raise MappedContentError("mapped_chunk_limit_exceeded")
-        try:
-            pieces = chunk_evidence(
-                text,
-                _BoundedTokenizer(tokenizer, max_chunks - len(chunks), max_tokens),
-                prefix=prefix,
-                target_tokens=target_tokens,
-                overlap_tokens=overlap_tokens,
-                max_tokens=max_tokens,
-            )
-        except ChunkingError as error:
-            if isinstance(error.__cause__, MappedContentError):
-                raise error.__cause__ from None
-            raise
-        if len(chunks) + len(pieces) > max_chunks:
-            raise MappedContentError("mapped_chunk_limit_exceeded")
-        assert span.source_start_cp is not None  # Validated copy span.
-        ordinal = len(chunks)
-        chunks.extend(
-            TextChunk(
-                ordinal + i,
-                span.source_start_cp + piece.start_cp,
-                span.source_start_cp + piece.end_cp,
-                piece.token_count,
-                piece.text,
-            )
-            for i, piece in enumerate(pieces)
-        )
-    return tuple(chunks)

memhub/apps/core/src/one_memory/retrieval/raw_candidates.py

@@ -1,147 +0,0 @@
-"""Internal raw semantic candidate lookup. No route, raw body release or full coverage claim."""
-
-import math
-import sqlite3
-from collections.abc import Sequence
-from dataclasses import dataclass
-from typing import Literal
-
-from one_memory.context_raw import _check
-from one_memory.retrieval.index_store import PublishedChunk, RetrievalIndexStore
-from one_memory.retrieval.models import RetrievalPath, TimeRange
-from one_memory.retrieval.vector_store import RawVectorStore, VectorStoreError
-
-
-@dataclass(frozen=True)
-class RawSemanticCandidate:
-    chunk: PublishedChunk
-    distance: float
-
-
-@dataclass(frozen=True)
-class RawCandidateBatch:
-    hits: tuple[RawSemanticCandidate, ...] = ()
-    complete: bool = False
-    reason: str | None = None
-    coverage: Literal["indexed_only"] = "indexed_only"
-    time_range: TimeRange | None = None
-
-
-def read_raw_semantic_candidates(
-    store: RetrievalIndexStore,
-    vectors: RawVectorStore,
-    query_vector: Sequence[float],
-    *,
-    generation_id: str,
-    source_ids: frozenset[str],
-    deadline: float,
-    limit: int = 64,
-    time_range: TimeRange | None = None,
-) -> RawCandidateBatch:
-    """Caller resolves host authority; explicit source IDs can only narrow it.
-
-    complete means the eligible published chunks were checked and searched, not
-    that every authorized original is indexed. The future coordinator must still
-    revalidate host identity and all raw/memory data together before body release.
-    """
-    if not isinstance(source_ids, frozenset) or any(
-        not isinstance(source, str) or not 1 <= len(source) <= 128 for source in source_ids
-    ):
-        raise ValueError("explicit_resolved_sources_required")
-    if type(limit) is not int or not 1 <= limit <= 64:
-        raise ValueError("invalid_candidate_limit")
-    if isinstance(deadline, bool) or not math.isfinite(deadline):
-        raise ValueError("invalid_candidate_deadline")
-    if not source_ids:
-        return RawCandidateBatch(reason="not_authorized")
-    if vectors.generation_id != generation_id:
-        raise ValueError("candidate_generation_mismatch")
-    try:
-        _check(deadline)
-        eligible = store.active_chunks(
-            generation_id, source_ids=source_ids, time_range=time_range, deadline=deadline
-        )
-        if not eligible:
-            return RawCandidateBatch(
-                complete=True, reason="no_eligible_chunks", time_range=time_range
-            )
-        before = {chunk.chunk_id: chunk for chunk in eligible}
-        expected_vectors = [(chunk.chunk_id, chunk.build_id) for chunk in eligible]
-        # When one query can return the entire allowlist, that response itself
-        # is the integrity check. Avoid a duplicate Chroma get-before-query on
-        # the hot small/medium-authority path. Larger allowlists still need the
-        # explicit complete verification because search returns only top-K.
-        verify_before_search = len(eligible) > limit
-        if verify_before_search and not vectors.verify_candidates(
-            expected_vectors, deadline=deadline
-        ):
-            return RawCandidateBatch(reason="deadline")
-        result = vectors.search(query_vector, tuple(before), limit, deadline)
-        if not verify_before_search and {hit.chunk_id for hit in result.hits} != set(before):
-            raise VectorStoreError("vector_record_missing")
-        _check(deadline)
-        current = {
-            chunk.chunk_id: chunk
-            for chunk in store.active_chunks(
-                generation_id, source_ids=source_ids, time_range=time_range, deadline=deadline
-            )
-        }
-        hits = []
-        for hit in result.hits:
-            if (
-                hit.chunk_id not in before
-                or hit.generation_id != generation_id
-                or hit.build_id != before[hit.chunk_id].build_id
-            ):
-                raise VectorStoreError("candidate_identity_mismatch")
-            if current.get(hit.chunk_id) == before[hit.chunk_id]:
-                hits.append(RawSemanticCandidate(before[hit.chunk_id], hit.distance))
-        _check(deadline)
-        unchanged = before == current
-        return RawCandidateBatch(
-            tuple(hits),
-            result.complete and unchanged,
-            "evidence_changed" if not unchanged else result.reason,
-            time_range=time_range,
-        )
-    except TimeoutError:
-        return RawCandidateBatch(reason="deadline")
-    except VectorStoreError:
-        return RawCandidateBatch(reason="vector_unavailable")
-    except (sqlite3.Error, OSError, ValueError):
-        return RawCandidateBatch(reason="index_unavailable")
-
-
-def compose_raw_retrieval_path(
-    batch: RawCandidateBatch,
-    *,
-    unpublished_authorized: bool,
-    lexical_hit_count: int,
-) -> RetrievalPath:
-    """Map channel results to a path. Indexed-only search is never complete empty."""
-    if type(lexical_hit_count) is not int or lexical_hit_count < 0:
-        raise ValueError("invalid_lexical_hit_count")
-    hits = len(batch.hits) + lexical_hit_count
-    incomplete = unpublished_authorized or not batch.complete
-    channels: tuple[Literal["lexical", "semantic"], ...] = ("lexical", "semantic")
-    if hits:
-        return RetrievalPath(
-            status="ok",
-            returned_count=min(hits, 32),
-            searched_channels=channels,
-            coverage="partial" if incomplete else "complete",
-        )
-    if incomplete:
-        return RetrievalPath(
-            status="degraded",
-            reason="indexed_only",
-            returned_count=0,
-            searched_channels=channels,
-            coverage="partial",
-        )
-    return RetrievalPath(
-        status="empty",
-        returned_count=0,
-        searched_channels=channels,
-        coverage="complete",
-    )

memhub/apps/core/src/one_memory/retrieval/raw_evidence.py

@@ -1,189 +0,0 @@
-"""Materialize internal semantic candidates from current authorized Evidence.
-
-Not an arbitrary-ID endpoint or signed expansion capability. The combined v2
-coordinator must revalidate this lane with memory and host identity at release.
-"""
-
-import json
-import sqlite3
-from dataclasses import dataclass
-from datetime import UTC
-
-from one_memory import ingest_journal as journal
-from one_memory.context_raw import _check, _connection
-from one_memory.imports.models import EvidenceRecord
-from one_memory.imports.storage import EvidenceStore
-from one_memory.retrieval.index_store import RetrievalIndexStore
-from one_memory.retrieval.models import EvidenceSpan, RawEvidence
-from one_memory.retrieval.raw_candidates import RawCandidateBatch
-
-
-@dataclass(frozen=True)
-class RawEvidenceBatch:
-    items: tuple[RawEvidence, ...] = ()
-    complete: bool = False
-    reason: str | None = None
-    used_characters: int = 0
-
-
-def _merge(intervals: list[tuple[int, int]]) -> list[tuple[int, int]]:
-    output: list[tuple[int, int]] = []
-    for start, end in sorted(intervals):
-        if output and start <= output[-1][1]:
-            output[-1] = (output[-1][0], max(end, output[-1][1]))
-        else:
-            output.append((start, end))
-    return output
-
-
-def materialize_raw_candidates(
-    store: RetrievalIndexStore,
-    candidates: RawCandidateBatch,
-    *,
-    generation_id: str,
-    source_ids: frozenset[str],
-    deadline: float,
-    character_budget: int = 6000,
-) -> RawEvidenceBatch:
-    if not isinstance(source_ids, frozenset) or any(
-        not isinstance(source, str) or not 1 <= len(source) <= 128 for source in source_ids
-    ):
-        raise ValueError("explicit_resolved_sources_required")
-    if type(character_budget) is not int or not 1 <= character_budget <= 20000:
-        raise ValueError("invalid_evidence_budget")
-    if len(candidates.hits) > 64:
-        raise ValueError("candidate_budget_exceeded")
-    if not source_ids:
-        return RawEvidenceBatch(reason="not_authorized")
-    try:
-        _check(deadline)
-        expected = {hit.chunk.chunk_id: hit.chunk for hit in candidates.hits}
-        if len(expected) != len(candidates.hits):
-            raise ValueError("duplicate_candidates")
-        if not expected:
-            # Empty/excluded builds still carry an integrity claim. Validate
-            # current authorized completed manifests, never only nonempty hits.
-            current_chunks = store.active_chunks(
-                generation_id,
-                source_ids=source_ids,
-                time_range=candidates.time_range,
-                deadline=deadline,
-                require_active=True,
-            )
-            _check(deadline)
-            if current_chunks and candidates.reason == "no_eligible_chunks":
-                return RawEvidenceBatch(reason="evidence_changed")
-            return RawEvidenceBatch(complete=candidates.complete, reason=candidates.reason)
-        changed = False
-        grouped: dict[str, tuple[EvidenceRecord, list[tuple[int, int]]]] = {}
-        with _connection(store.database_path, deadline) as db:
-            db.execute("PRAGMA query_only=ON")
-            rows = {
-                row["chunk_id"]: row
-                for row in db.execute(
-                    """SELECT c.*, d.event_seq,d.grant_fingerprint,d.source_id
-                    FROM retrieval_chunks c JOIN retrieval_documents d
-                      ON d.generation_id=c.generation_id AND d.evidence_id=c.evidence_id
-                      AND d.active_build_id=c.build_id AND d.build_id=c.build_id
-                    JOIN retrieval_index_generations g ON g.generation_id=c.generation_id
-                    WHERE c.generation_id=? AND g.state='active' AND d.state='ready'
-                      AND c.chunk_id IN (SELECT value FROM json_each(?))""",
-                    (generation_id, json.dumps(tuple(expected))),
-                )
-            }
-            for key, chunk in expected.items():
-                _check(deadline)
-                row = rows.get(key)
-                if row is None or row["source_id"] not in source_ids:
-                    changed = True
-                    continue
-                event = journal.event(db, row["event_seq"])
-                grant = store._grant(db, row["source_id"])
-                if (
-                    event is None
-                    or event.user_id != "local"
-                    or event.source_id != row["source_id"]
-                    or event.evidence_id != chunk.evidence_id
-                    or event.evidence_revision != chunk.revision
-                    or grant is None
-                    or grant != row["grant_fingerprint"]
-                    or not journal.matches_current(db, event)
-                ):
-                    changed = True
-                    continue
-                record = EvidenceStore._get_with_connection(db, chunk.evidence_id)
-                if (
-                    record is None
-                    or record.user_id != "local"
-                    or record.source_id != row["source_id"]
-                ):
-                    changed = True
-                    continue
-                event_time = record.created_at
-                if event_time is not None:
-                    event_time = event_time.astimezone(UTC) if event_time.tzinfo else None
-                if (
-                    (row["build_id"], row["ordinal"], row["start_cp"], row["end_cp"])
-                    != (chunk.build_id, chunk.ordinal, chunk.start_cp, chunk.end_cp)
-                    or (record.source_id, event_time) != (chunk.source_id, chunk.event_time)
-                    or not 0 <= chunk.start_cp < chunk.end_cp <= len(record.verbatim)
-                ):
-                    changed = True
-                    continue
-                if record.evidence_id not in grouped:
-                    document = db.execute(
-                        "SELECT * FROM retrieval_documents WHERE generation_id=? AND evidence_id=?",
-                        (generation_id, record.evidence_id),
-                    ).fetchone()
-                    if document is None:
-                        raise ValueError("published_document_missing")
-                    store.validate_document(db, document, record, deadline=deadline)
-                    grouped[record.evidence_id] = (record, [])
-                grouped[record.evidence_id][1].append((chunk.start_cp, chunk.end_cp))
-            items = []
-            used = 0
-            truncated = False
-            for record, intervals in grouped.values():
-                _check(deadline)
-                spans: list[EvidenceSpan] = []
-                for start, end in _merge(intervals):
-                    if len(spans) >= 4 or end - start > min(20000, character_budget - used):
-                        truncated = True
-                        continue
-                    spans.append(
-                        EvidenceSpan(start_cp=start, end_cp=end, text=record.verbatim[start:end])
-                    )
-                    used += end - start
-                if not spans:
-                    continue
-                event_time = record.created_at
-                if event_time is not None:
-                    event_time = event_time.astimezone(UTC) if event_time.tzinfo else None
-                items.append(
-                    RawEvidence(
-                        evidence_id=record.evidence_id,
-                        revision=record.revision,
-                        source_id=record.source_id,
-                        conversation_id=record.conversation_id,
-                        role=record.role,
-                        written_by="person" if record.role == "user" else "agent",
-                        event_time=event_time,
-                        spans=tuple(spans),
-                        matched_by=("semantic",),
-                    )
-                )
-            _check(deadline)
-        return RawEvidenceBatch(
-            tuple(items),
-            candidates.complete and not changed and not truncated,
-            "evidence_changed"
-            if changed
-            else "character_budget"
-            if truncated
-            else candidates.reason,
-            used,
-        )
-    except TimeoutError:
-        return RawEvidenceBatch(reason="deadline")
-    except (sqlite3.Error, OSError, ValueError):
-        return RawEvidenceBatch(reason="index_unavailable")

memhub/apps/core/src/one_memory/retrieval/raw_lane.py

@@ -1,181 +0,0 @@
-"""Fuse lexical raw context with an optional derived index. No new HTTP schema."""
-
-import sqlite3
-from collections.abc import Callable
-from pathlib import Path
-from typing import Protocol
-
-from pydantic import ValidationError
-
-from one_memory.context_models import (
-    ContextLaneResult,
-    ContextSearchRequest,
-    ContextSemanticStatus,
-    RawContextItem,
-)
-from one_memory.context_raw import (
-    _METADATA,
-    _check,
-    _connection,
-    _execute,
-    _message,
-    _readable,
-    read_raw_context,
-)
-from one_memory.retrieval.models import TimeRange
-from one_memory.retrieval.raw_candidates import RawCandidateBatch, compose_raw_retrieval_path
-
-
-class RawIndexLookup(Protocol):
-    def lookup_raw(
-        self,
-        query: str,
-        *,
-        source_ids: frozenset[str] | None,
-        deadline: float,
-        time_range: TimeRange | None = None,
-    ) -> tuple[RawCandidateBatch, bool]: ...
-
-
-def fuse_raw_lane(
-    lexical: ContextLaneResult,
-    batch: RawCandidateBatch,
-    *,
-    unpublished_authorized: bool,
-    extra_items: tuple[RawContextItem, ...] = (),
-) -> ContextLaneResult:
-    """v1 has no coverage field; degraded + lexical_only stands in for partial index."""
-    semantic_status: ContextSemanticStatus = (
-        "timed_out"
-        if batch.reason == "deadline"
-        else "failed"
-        if batch.reason in {"index_unavailable", "vector_unavailable"}
-        else "completed"
-    )
-    index_complete = batch.complete and not unpublished_authorized
-    timed_out = semantic_status == "timed_out"
-    if lexical.status not in {"ok", "empty", "degraded"}:
-        return lexical.model_copy(
-            update={
-                "searched_channels": ("lexical", "semantic"),
-                "semantic_status": semantic_status,
-                "index_complete": index_complete,
-                "timed_out": timed_out,
-            }
-        )
-    seen = {item.anchor_evidence_id for item in lexical.items if isinstance(item, RawContextItem)}
-    extras = tuple(item for item in extra_items if isinstance(item, RawContextItem))
-    # Semantic similarity is a candidate signal, not a verified recall result.
-    # Release only semantic items that the lexical lane independently confirmed
-    # for the same evidence identity. Unconfirmed semantic hits stay in the
-    # coverage receipt as partial/degraded and must not reach host injection.
-    unconfirmed_semantic = any(item.anchor_evidence_id not in seen for item in extras)
-    items = lexical.items
-    path = compose_raw_retrieval_path(
-        batch,
-        unpublished_authorized=unpublished_authorized,
-        lexical_hit_count=len(lexical.items),
-    )
-    status = path.status
-    if unconfirmed_semantic:
-        status = "degraded"
-    if lexical.status == "degraded" and status == "ok":
-        status = "degraded"
-    return ContextLaneResult(
-        status=status,
-        reason=(
-            "lexical_only" if unconfirmed_semantic and lexical.reason is None else lexical.reason
-        ),
-        items=items[:21],
-        truncated_by=lexical.truncated_by,
-        searched_channels=("lexical", "semantic"),
-        semantic_status=semantic_status,
-        index_complete=index_complete,
-        timed_out=timed_out,
-    )
-
-
-def load_raw_items_from_candidates(
-    database_path: Path,
-    batch: RawCandidateBatch,
-    *,
-    source_ids: frozenset[str] | None,
-    deadline: float,
-    character_budget: int = 6000,
-) -> tuple[RawContextItem, ...]:
-    """Release authorized Evidence bodies for semantic IDs. Not a vector dump."""
-    ids = tuple(dict.fromkeys(hit.chunk.evidence_id for hit in batch.hits))
-    if not ids or source_ids == frozenset():
-        return ()
-    readable, authority = _readable(source_ids)
-    body_limit = min(20000, max(1, character_budget))
-    items: list[RawContextItem] = []
-    try:
-        with _connection(database_path, deadline) as db:
-            for evidence_id in ids[:21]:
-                _check(deadline)
-                row = _execute(
-                    db,
-                    deadline,
-                    f"""
-                    SELECT {_METADATA}, substr(e.verbatim,1,?) AS text,
-                           length(e.verbatim)>? AS body_truncated
-                    FROM evidence e
-                    WHERE {readable} AND e.evidence_id=?
-                    """,
-                    [body_limit, body_limit, *authority, evidence_id],
-                ).fetchone()
-                if row is None:
-                    continue
-                try:
-                    message = _message(row)
-                    items.append(
-                        RawContextItem(
-                            source_id=row["source_id"],
-                            conversation_id=row["conversation_id"],
-                            anchor_evidence_id=message.evidence_id,
-                            messages=(message,),
-                            truncated=message.truncated,
-                        )
-                    )
-                except (ValidationError, ValueError, TypeError):
-                    continue
-    except TimeoutError:
-        raise
-    except (sqlite3.Error, OSError):
-        return ()
-    return tuple(items)
-
-
-def read_raw_indexed_context(
-    database_path: Path,
-    request: ContextSearchRequest,
-    *,
-    source_ids: frozenset[str] | None,
-    deadline: float,
-    index: RawIndexLookup | None = None,
-    load_semantic_items: Callable[..., tuple[RawContextItem, ...]] | None = None,
-) -> ContextLaneResult:
-    lexical = read_raw_context(database_path, request, source_ids=source_ids, deadline=deadline)
-    if index is None:
-        return lexical
-    try:
-        batch, unpublished = index.lookup_raw(
-            request.query, source_ids=source_ids, deadline=deadline
-        )
-    except Exception:
-        batch, unpublished = RawCandidateBatch(reason="index_unavailable"), True
-    extra: tuple[RawContextItem, ...] = ()
-    if batch.hits:
-        extra = (
-            load_semantic_items(database_path, batch, source_ids=source_ids, deadline=deadline)
-            if load_semantic_items is not None
-            else load_raw_items_from_candidates(
-                database_path,
-                batch,
-                source_ids=source_ids,
-                deadline=deadline,
-                character_budget=request.character_budget,
-            )
-        )
-    return fuse_raw_lane(lexical, batch, unpublished_authorized=unpublished, extra_items=extra)

memhub/apps/core/src/one_memory/retrieval/runtime.py

@@ -1,379 +0,0 @@
-"""Resume an explicitly configured local index; never create or migrate one."""
-
-import asyncio
-import json
-import os
-import shutil
-import sqlite3
-import stat
-import sys
-import threading
-from collections.abc import Callable
-from dataclasses import asdict, dataclass
-from pathlib import Path
-from typing import Literal
-
-from one_memory.database_access import main_database
-from one_memory.retrieval.index_store import EncoderIdentity, RetrievalIndexStore
-from one_memory.retrieval.index_supervisor import IndexSupervisorSnapshot, RetrievalIndexSupervisor
-from one_memory.retrieval.index_worker import LocalRetrievalEncoder, RetrievalIndexWorker
-from one_memory.retrieval.models import TimeRange
-from one_memory.retrieval.raw_candidates import RawCandidateBatch, read_raw_semantic_candidates
-from one_memory.retrieval.vector_store import RawVectorStore, VectorStoreError
-from one_memory.service_levels import ServiceLevel, ServiceLevelScheduler, ServiceResource
-
-type RuntimeState = Literal[
-    "new", "starting", "running", "not_initialized", "failed", "stopping", "stopped"
-]
-
-
-@dataclass(frozen=True)
-class ExistingRetrievalSnapshot:
-    state: RuntimeState
-    error_code: str | None
-    generation_id: str | None
-    supervisor: IndexSupervisorSnapshot | None
-
-
-class _AdmissionError(Exception):
-    def __init__(self, code: str, *, missing: bool = False):
-        self.code, self.missing = code, missing
-
-
-async def _native[T](operation: Callable[[], T]) -> T:
-    """Owned, joined native call. Only retained internal lifecycle tasks invoke this."""
-    result: list[T] = []
-    errors: list[BaseException] = []
-
-    def run() -> None:
-        try:
-            result.append(operation())
-        except BaseException as error:
-            errors.append(error)
-
-    thread = threading.Thread(target=run, name="retrieval-resource", daemon=False)
-    thread.start()
-    while thread.is_alive():
-        await asyncio.sleep(0.01)
-    thread.join()
-    if errors:
-        raise errors[0]
-    return result[0]
-
-
-class ExistingRetrievalRuntime:
-    """Caller guarantees managed Core single ownership and explicit configuration.
-
-    Construct without I/O; start and stop on the owning event loop. A retained
-    lifecycle task shields native work from caller cancellation until cleanup.
-    """
-
-    def __init__(
-        self,
-        data_dir: Path,
-        *,
-        minimum_free_bytes: int = 256 * 1024 * 1024,
-        service_levels: ServiceLevelScheduler | None = None,
-    ):
-        if type(minimum_free_bytes) is not int or minimum_free_bytes < 0:
-            raise ValueError("retrieval_runtime_invalid_disk_limit")
-        self._directory = Path(data_dir)
-        self._minimum_free = minimum_free_bytes
-        self._service_levels = service_levels or ServiceLevelScheduler()
-        self._state: ExistingRetrievalSnapshot = ExistingRetrievalSnapshot("new", None, None, None)
-        self._vectors: RawVectorStore | None = None
-        self._store: RetrievalIndexStore | None = None
-        self._encoder: LocalRetrievalEncoder | None = None
-        self._supervisor: RetrievalIndexSupervisor | None = None
-        self._last_supervisor_snapshot: IndexSupervisorSnapshot | None = None
-        self._start_task: asyncio.Task[bool] | None = None
-        self._stop_task: asyncio.Task[None] | None = None
-        self._stop_requested = False
-
-    def snapshot(self) -> ExistingRetrievalSnapshot:
-        return ExistingRetrievalSnapshot(
-            self._state.state,
-            self._state.error_code,
-            self._state.generation_id,
-            self._supervisor.snapshot()
-            if self._supervisor is not None
-            else self._last_supervisor_snapshot,
-        )
-
-    def _set(
-        self, state: RuntimeState, code: str | None = None, generation: str | None = None
-    ) -> None:
-        self._state = ExistingRetrievalSnapshot(
-            state,
-            code,
-            generation if generation is not None else self._state.generation_id,
-            None,
-        )
-
-    def trigger(self) -> bool:
-        return bool(
-            self._state.state == "running" and self._supervisor and self._supervisor.trigger()
-        )
-
-    def lookup_raw(
-        self,
-        query: str,
-        *,
-        source_ids: frozenset[str] | None,
-        deadline: float,
-        time_range: TimeRange | None = None,
-    ) -> tuple[RawCandidateBatch, bool]:
-        """Read-only candidate lookup. Does not release original bodies."""
-        store, encoder, vectors, generation = (
-            self._store,
-            self._encoder,
-            self._vectors,
-            self._state.generation_id,
-        )
-        if (
-            self._state.state != "running"
-            or store is None
-            or encoder is None
-            or vectors is None
-            or generation is None
-        ):
-            return RawCandidateBatch(reason="index_unavailable"), True
-        counts = store.status(generation)
-        unpublished = counts["pending"] + counts["leased"] + counts["blocked"] > 0
-        resolved = source_ids
-        if resolved is None:
-            resolved = frozenset(
-                chunk.source_id for chunk in store.active_chunks(generation, deadline=deadline)
-            )
-        if not resolved:
-            return (
-                RawCandidateBatch(complete=not unpublished, reason="no_eligible_chunks"),
-                unpublished,
-            )
-        try:
-            vector = encoder.encode_documents([query.strip()])[0]
-        except Exception:
-            return RawCandidateBatch(reason="index_unavailable"), True
-        batch = read_raw_semantic_candidates(
-            store,
-            vectors,
-            vector,
-            generation_id=generation,
-            source_ids=resolved,
-            deadline=deadline,
-            time_range=time_range,
-        )
-        return batch, unpublished
-
-    async def start(self) -> bool:
-        if self._state.state != "new" or self._stop_requested:
-            raise RuntimeError("retrieval_runtime_already_started")
-        self._set("starting")
-        self._start_task = asyncio.create_task(self._start())
-        try:
-            return await asyncio.shield(self._start_task)
-        except asyncio.CancelledError:
-            # Retain and drain opening resources, then release them, before cancellation escapes.
-            await self.stop()
-            raise
-
-    async def stop(self) -> None:
-        self._stop_requested = True
-        if self._stop_task is None:
-            self._stop_task = asyncio.create_task(self._stop())
-        cancelled = False
-        while not self._stop_task.done():
-            try:
-                await asyncio.shield(self._stop_task)
-            except asyncio.CancelledError:
-                cancelled = True
-        self._stop_task.result()
-        if cancelled:
-            raise asyncio.CancelledError
-
-    async def _start(self) -> bool:
-        try:
-            store, encoder, vectors, generation = await _native(self._open)
-            self._store = store
-            self._encoder = encoder
-            self._vectors = vectors
-            self._set("starting", generation=generation)
-            if self._stop_requested:
-                return False
-            worker = RetrievalIndexWorker(
-                store, vectors, encoder, generation_id=generation, owner="managed-core-retrieval"
-            )
-            self._supervisor = RetrievalIndexSupervisor(
-                worker,
-                background_should_yield=lambda: self._service_levels.should_yield(
-                    ServiceResource.INDEX,
-                    ServiceLevel.BACKGROUND,
-                ),
-            )
-            self._supervisor.start()
-            self._set("running")
-            return True
-        except _AdmissionError as error:
-            self._set("not_initialized" if error.missing else "failed", error.code)
-        except Exception:
-            self._set("failed", "retrieval_runtime_start_failed")
-        await self._release()
-        return False
-
-    async def _release(self) -> None:
-        stop_failed = False
-        if self._supervisor is not None:
-            try:
-                await self._supervisor.stop()
-            except Exception:
-                stop_failed = True
-            supervisor_snapshot = self._supervisor.snapshot()
-            if supervisor_snapshot.thread_alive:
-                self._set("failed", "retrieval_runtime_stop_failed")
-                raise RuntimeError("retrieval_runtime_stop_failed") from None
-            # The supervisor owns the worker, which owns the native vector
-            # client. Retain only the immutable receipt once its thread drains.
-            self._last_supervisor_snapshot = supervisor_snapshot
-            self._supervisor = None
-        if self._vectors is not None:
-            try:
-                await _native(self._vectors.close)
-            except Exception:
-                self._set("failed", "retrieval_runtime_close_failed")
-                raise RuntimeError("retrieval_runtime_close_failed") from None
-            self._vectors = None
-        self._store = None
-        self._encoder = None
-        if stop_failed:
-            self._set("failed", "retrieval_runtime_stop_failed")
-            raise RuntimeError("retrieval_runtime_stop_failed") from None
-
-    async def _stop(self) -> None:
-        if self._start_task is not None:
-            try:
-                await asyncio.shield(self._start_task)
-            except Exception:
-                # Startup can itself fail during cleanup. Do not lose resource ownership.
-                self._set("failed", "retrieval_runtime_start_failed")
-        self._set("stopping", self._state.error_code)
-        await self._release()
-        if self._state.error_code == "retrieval_runtime_close_failed":
-            return
-        self._set("stopped", self._state.error_code)
-
-    @staticmethod
-    def _path(path: Path, *, directory: bool) -> tuple[int, int]:
-        if any(part.is_symlink() for part in (path, *path.parents)):
-            raise _AdmissionError("retrieval_runtime_unsafe_path")
-        try:
-            info = path.stat()
-        except FileNotFoundError:
-            raise _AdmissionError("retrieval_runtime_not_initialized", missing=True) from None
-        if not (stat.S_ISDIR(info.st_mode) if directory else stat.S_ISREG(info.st_mode)):
-            raise _AdmissionError("retrieval_runtime_unsafe_path")
-        if not directory and info.st_nlink != 1:
-            raise _AdmissionError("retrieval_runtime_unsafe_path")
-        if info.st_uid != os.getuid() or stat.S_IMODE(info.st_mode) & 0o022:
-            raise _AdmissionError("retrieval_runtime_unsafe_path")
-        return info.st_dev, info.st_ino
-
-    def _sidecars(self, database: Path) -> None:
-        for suffix in ("-wal", "-shm", "-journal"):
-            path = database.with_name(database.name + suffix)
-            if path.is_symlink() or path.exists():
-                self._path(path, directory=False)
-
-    def _inspect(self, database: Path) -> tuple[RetrievalIndexStore, EncoderIdentity, str]:
-        with main_database(database.absolute()).read(busy_timeout_ms=1_000) as db:
-            db.row_factory = sqlite3.Row
-            db.execute("PRAGMA query_only=ON")
-            db.execute("BEGIN")
-            if not db.execute(
-                "SELECT 1 FROM sqlite_master WHERE name='retrieval_index_state'"
-            ).fetchone():
-                raise _AdmissionError("retrieval_runtime_not_initialized", missing=True)
-            state = db.execute(
-                "SELECT schema_version FROM retrieval_index_state WHERE singleton=1"
-            ).fetchone()
-            if state is not None and state[0] == 1:
-                raise _AdmissionError("retrieval_runtime_not_initialized", missing=True)
-            if state is None or state[0] != 2:
-                raise _AdmissionError("retrieval_runtime_invalid_index")
-            rows = db.execute(
-                "SELECT generation_id,identity_json FROM retrieval_index_generations "
-                "WHERE state='active' LIMIT 2"
-            ).fetchall()
-            if not rows:
-                raise _AdmissionError("retrieval_runtime_not_initialized", missing=True)
-            if len(rows) != 1:
-                raise _AdmissionError("retrieval_runtime_invalid_index")
-            store = RetrievalIndexStore(database)
-            generation = rows[0]["generation_id"]
-            identity = store._identity(db, generation)
-            raw = json.loads(rows[0]["identity_json"])
-            if raw != asdict(identity) or set(raw) != set(asdict(identity)):
-                raise _AdmissionError("retrieval_runtime_invalid_index")
-            # Check required schema shape without repairing it or reading original bodies.
-            db.execute(
-                "SELECT build_id,source_map_json,map_digest,coverage_state "
-                "FROM retrieval_build_maps LIMIT 0"
-            )
-            db.execute("SELECT after_seq,retry_after_seq FROM retrieval_consumers LIMIT 0")
-            db.execute("SELECT lease_token,active_build_id FROM retrieval_documents LIMIT 0")
-            db.execute("SELECT chunk_id,text_hash FROM retrieval_chunks LIMIT 0")
-            return store, identity, generation
-
-    def _open(self) -> tuple[RetrievalIndexStore, LocalRetrievalEncoder, RawVectorStore, str]:
-        if sys.platform == "win32" or not hasattr(os, "getuid"):
-            raise _AdmissionError("retrieval_runtime_platform_unsupported")
-        directory = self._directory.absolute()
-        database, vector_dir = directory / "one-memory.sqlite3", directory / "retrieval-vectors"
-        root_pin = self._path(directory, directory=True)
-        database_pin = self._path(database, directory=False)
-        self._sidecars(database)
-        try:
-            store, identity, generation = self._inspect(database)
-        except (ValueError, TypeError, sqlite3.Error):
-            raise _AdmissionError("retrieval_runtime_invalid_index") from None
-        vector_pin = self._path(vector_dir, directory=True)
-        vector_database = vector_dir / "chroma.sqlite3"
-        vector_db_pin = self._path(vector_database, directory=False)
-        self._sidecars(vector_database)
-
-        def recheck() -> None:
-            if (
-                self._path(directory, directory=True) != root_pin
-                or self._path(database, directory=False) != database_pin
-                or self._path(vector_dir, directory=True) != vector_pin
-                or self._path(vector_database, directory=False) != vector_db_pin
-            ):
-                raise _AdmissionError("retrieval_runtime_index_changed")
-            self._sidecars(database)
-            self._sidecars(vector_database)
-
-        if shutil.disk_usage(directory).free < self._minimum_free:
-            raise _AdmissionError("retrieval_runtime_low_disk")
-        encoder = LocalRetrievalEncoder(content_version=identity.normalizer_version)
-        if encoder.identity != identity:
-            raise _AdmissionError("retrieval_runtime_encoder_mismatch")
-        recheck()
-        try:
-            vectors = RawVectorStore.open_writer_existing(
-                vector_dir, generation_id=generation, dimensions=identity.dimensions
-            )
-            # Retain ownership immediately so all later failures use the same cleanup path.
-            self._vectors = vectors
-            # A generation change during the native open is not authorization to resume another.
-            recheck()
-            if self._inspect(database)[1:] != (identity, generation):
-                raise _AdmissionError("retrieval_runtime_index_changed")
-            recheck()
-            return store, encoder, vectors, generation
-        except BaseException as error:
-            if isinstance(error, VectorStoreError):
-                if str(error) in {"vector_store_not_found", "vector_collection_not_found"}:
-                    raise _AdmissionError(
-                        "retrieval_runtime_not_initialized", missing=True
-                    ) from None
-                raise _AdmissionError("retrieval_runtime_vector_unavailable") from None
-            raise

memhub/apps/core/src/one_memory/retrieval/vector_store.py

@@ -1,534 +0,0 @@
-"""Independent raw-vector adapter. Eligibility is supplied by Core's SQLite snapshot.
-
-No HY collection, document text, embedding function, migration/repair or authority
-store lives here. Chroma PersistentClient is NOT physically read-only: even the
-existing-collection handle can maintain backend metadata/index files. A caller
-requiring filesystem read-only operation must not use this backend.
-
-Scoring is an exact pass over the eligible vectors, not a global ANN top-K that
-is filtered afterwards. Chroma's filtered query does not score every candidate
-in its `where $in` allowlist: at 10k stored chunks an explicit 64-ID allowlist
-returned 26 of 64 while reporting the query as complete, and 0 of 64 after the
-writer handle was reopened. A post-filtered global search would be neither
-permission-correct nor recall-correct, so the eligible embeddings are read
-back and ranked here.
-"""
-
-from __future__ import annotations
-
-import math
-import re
-import sqlite3
-import struct
-import threading
-from collections.abc import Callable, Sequence
-from contextlib import closing
-from dataclasses import dataclass
-from hashlib import sha256
-from numbers import Real
-from pathlib import Path
-from time import monotonic
-from typing import Any, Literal
-
-ALLOWLIST_BATCH_SIZE = 2048
-
-
-class VectorStoreError(RuntimeError):
-    """Bounded failure code; callers must not treat corruption as complete empty search."""
-
-
-@dataclass(frozen=True)
-class RawVectorRecord:
-    chunk_id: str
-    build_id: str
-    generation_id: str
-    vector: tuple[float, ...]
-
-    def __post_init__(self) -> None:
-        object.__setattr__(self, "vector", tuple(self.vector))
-
-
-@dataclass(frozen=True)
-class VectorHit:
-    chunk_id: str
-    build_id: str
-    generation_id: str
-    distance: float
-
-
-@dataclass(frozen=True)
-class VectorSearchResult:
-    hits: tuple[VectorHit, ...]
-    complete: bool
-    eligible_count: int
-    searched_count: int
-    reason: Literal["deadline"] | None
-
-
-class RawVectorStore:
-    """Unopened constructor has no I/O. Use create/open_existing explicitly.
-
-    Directory must be a dedicated, trusted Runtime retrieval-vectors directory,
-    never the HY data directory. Only create/open_writer_existing enable upsert.
-    Core must serialize writers across handles/processes; this instance's lock
-    is not a persistent writer lease. close() releases only this Chroma client,
-    retaining other live clients' references.
-    """
-
-    def __init__(
-        self,
-        directory: Path,
-        *,
-        generation_id: str,
-        dimensions: int,
-        clock: Callable[[], float] = monotonic,
-    ) -> None:
-        _identifier(generation_id)
-        if type(dimensions) is not int or not 1 <= dimensions <= 65536:
-            raise VectorStoreError("vector_invalid_dimensions")
-        self.directory = Path(directory)
-        self.generation_id = generation_id
-        self.dimensions = dimensions
-        self.collection_name = "raw_" + sha256(generation_id.encode()).hexdigest()
-        self._clock = clock
-        self._client: Any = None
-        self._collection: Any = None
-        self._writable = False
-        self._closed = False
-        self._lock = threading.RLock()
-
-    @classmethod
-    def create(cls, directory: Path, *, generation_id: str, dimensions: int) -> RawVectorStore:
-        """Explicit writer initialization. Refuses to reuse an existing collection."""
-        value = cls(directory, generation_id=generation_id, dimensions=dimensions)
-        value._open(create=True)
-        return value
-
-    @classmethod
-    def open_existing(
-        cls,
-        directory: Path,
-        *,
-        generation_id: str,
-        dimensions: int,
-    ) -> RawVectorStore:
-        """No logical index writes; persistent Chroma may still write maintenance files."""
-        value = cls(directory, generation_id=generation_id, dimensions=dimensions)
-        value._open(create=False)
-        return value
-
-    @classmethod
-    def open_writer_existing(
-        cls,
-        directory: Path,
-        *,
-        generation_id: str,
-        dimensions: int,
-    ) -> RawVectorStore:
-        """Explicit worker recovery; verifies existing collection, never creates/repairs."""
-        value = cls(directory, generation_id=generation_id, dimensions=dimensions)
-        value._open(create=False, writable=True)
-        return value
-
-    def _metadata(self) -> dict[str, str | int]:
-        return {
-            "adapter": "one-memory-raw-v1",
-            "generation_id": self.generation_id,
-            "dimensions": self.dimensions,
-            "distance": "cosine",
-            "normalization": "l2-float32-v1",
-        }
-
-    def _preflight(self, create: bool) -> None:
-        if any(part.is_symlink() for part in (self.directory, *self.directory.parents)):
-            raise VectorStoreError("vector_unsafe_directory")
-        if not self.directory.exists():
-            if not create:
-                raise VectorStoreError("vector_store_not_found")
-            self.directory.mkdir(parents=True)
-        if not self.directory.is_dir():
-            raise VectorStoreError("vector_unsafe_directory")
-        database = self.directory / "chroma.sqlite3"
-        if database.is_symlink():
-            raise VectorStoreError("vector_unsafe_database")
-        if not database.is_file():
-            if not create:
-                raise VectorStoreError("vector_store_not_found")
-            if any(self.directory.iterdir()):
-                raise VectorStoreError("vector_unknown_directory")
-            return
-        if database.stat().st_nlink != 1:
-            raise VectorStoreError("vector_unsafe_database")
-        # Refuse missing/corrupt collections BEFORE PersistentClient can perform
-        # startup maintenance. This checks the installed Chroma 1.5.9 schema.
-        try:
-            with closing(sqlite3.connect(database.resolve().as_uri() + "?mode=ro", uri=True)) as db:
-                found = db.execute(
-                    "SELECT 1 FROM collections WHERE name=?", (self.collection_name,)
-                ).fetchone()
-                if not create and found is None:
-                    raise VectorStoreError("vector_collection_not_found")
-                if create and found is not None:
-                    raise VectorStoreError("vector_collection_exists")
-        except sqlite3.Error:
-            raise VectorStoreError("vector_store_unavailable") from None
-
-    def _open(self, *, create: bool, writable: bool = False) -> None:
-        self._preflight(create)
-        try:
-            import chromadb
-            from chromadb.config import Settings
-
-            self._client = chromadb.PersistentClient(
-                path=str(self.directory), settings=Settings(anonymized_telemetry=False)
-            )
-            if create:
-                self._collection = self._client.create_collection(
-                    self.collection_name,
-                    embedding_function=None,
-                    metadata=self._metadata(),
-                    # Unit vectors + inner product give cosine distance without
-                    # cosine HNSW's lossy normalization/de-normalization on get.
-                    configuration={"hnsw": {"space": "ip"}},
-                )
-            else:
-                self._collection = self._client.get_collection(
-                    self.collection_name, embedding_function=None
-                )
-            if (
-                self._collection.metadata != self._metadata()
-                or type(self._collection.metadata.get("dimensions")) is not int
-            ):
-                raise VectorStoreError("vector_collection_identity_mismatch")
-            config = self._collection.configuration
-            if (
-                config.get("hnsw", {}).get("space") != "ip"
-                or config.get("embedding_function") is not None
-            ):
-                raise VectorStoreError("vector_collection_configuration_mismatch")
-            self._writable = create or writable
-        except Exception as error:
-            self.close()
-            if isinstance(error, VectorStoreError):
-                raise
-            raise VectorStoreError("vector_store_unavailable") from None
-
-    def close(self) -> None:
-        with self._lock:
-            if self._closed:
-                return
-            self._closed = True
-            if self._client is not None:
-                self._client.close()
-            self._client = self._collection = None
-
-    def _require_open(self) -> Any:
-        if self._closed:
-            raise VectorStoreError("vector_store_closed")
-        if self._collection is None:
-            raise VectorStoreError("vector_store_not_open")
-        return self._collection
-
-    def _records(self, records: Sequence[RawVectorRecord]) -> tuple[RawVectorRecord, ...]:
-        result = []
-        seen: set[str] = set()
-        for record in records:
-            if not isinstance(record, RawVectorRecord):
-                raise VectorStoreError("vector_invalid_record")
-            for identifier in (record.chunk_id, record.build_id, record.generation_id):
-                _identifier(identifier)
-            if record.generation_id != self.generation_id or record.chunk_id in seen:
-                raise VectorStoreError("vector_invalid_record_identity")
-            seen.add(record.chunk_id)
-            result.append(
-                RawVectorRecord(
-                    record.chunk_id,
-                    record.build_id,
-                    record.generation_id,
-                    _vector(record.vector, self.dimensions),
-                )
-            )
-        return tuple(result)
-
-    def _read_records(self, ids: Sequence[str]) -> dict[str, tuple[RawVectorRecord, str]]:
-        if not ids:
-            return {}
-        collection = self._require_open()
-        result: dict[str, tuple[RawVectorRecord, str]] = {}
-        for start in range(0, len(ids), ALLOWLIST_BATCH_SIZE):
-            batch = ids[start : start + ALLOWLIST_BATCH_SIZE]
-            try:
-                data = collection.get(ids=list(batch), include=["embeddings", "metadatas"])
-                returned, vectors, metadatas = data["ids"], data["embeddings"], data["metadatas"]
-                if (
-                    vectors is None
-                    or metadatas is None
-                    or not len(returned) == len(vectors) == len(metadatas)
-                ):
-                    raise VectorStoreError("vector_invalid_record_response")
-                for key, vector, metadata in zip(returned, vectors, metadatas, strict=True):
-                    if key not in batch or key in result:
-                        raise VectorStoreError("vector_ineligible_record")
-                    result[key] = self._decode(key, vector, metadata)
-            except VectorStoreError:
-                raise
-            except Exception:
-                raise VectorStoreError("vector_read_unavailable") from None
-        return result
-
-    def _decode(
-        self, key: str, vector: Sequence[float], metadata: Any
-    ) -> tuple[RawVectorRecord, str]:
-        if not isinstance(metadata, dict) or set(metadata) != {
-            "chunk_id",
-            "build_id",
-            "generation_id",
-            "vector_sha256",
-            "input_sha256",
-        }:
-            raise VectorStoreError("vector_invalid_metadata")
-        if metadata["chunk_id"] != key or metadata["generation_id"] != self.generation_id:
-            raise VectorStoreError("vector_metadata_identity_mismatch")
-        _identifier(key)
-        _identifier(metadata["build_id"])
-        if not isinstance(metadata["input_sha256"], str) or not re.fullmatch(
-            r"[0-9a-f]{64}", metadata["input_sha256"]
-        ):
-            raise VectorStoreError("vector_invalid_input_digest")
-        normalized = _vector(vector, self.dimensions)
-        if metadata["vector_sha256"] != _digest(normalized):
-            raise VectorStoreError("vector_content_mismatch")
-        return RawVectorRecord(key, metadata["build_id"], self.generation_id, normalized), metadata[
-            "input_sha256"
-        ]
-
-    def upsert(self, records: Sequence[RawVectorRecord]) -> None:
-        """Idempotent immutable insertion; add-only at Chroma, never overwrite IDs.
-
-        Equality is canonical float32 input identity plus explicit normalized
-        storage identity. Conflict is checked before
-        any add. Backend failure may leave a partial new batch: caller must verify
-        the entire build before publication. Existing IDs are never modified.
-        """
-        with self._lock:
-            collection = self._require_open()
-            if not self._writable:
-                raise VectorStoreError("vector_store_read_only")
-            incoming = self._records(records)
-            existing = self._read_records([record.chunk_id for record in incoming])
-            for record in incoming:
-                if record.chunk_id in existing and not _matches(existing[record.chunk_id], record):
-                    raise VectorStoreError("vector_immutable_conflict")
-            new = [record for record in incoming if record.chunk_id not in existing]
-            for start in range(0, len(new), ALLOWLIST_BATCH_SIZE):
-                batch = new[start : start + ALLOWLIST_BATCH_SIZE]
-                try:
-                    collection.add(
-                        ids=[record.chunk_id for record in batch],
-                        embeddings=[list(_unit_vector(record.vector)) for record in batch],
-                        metadatas=[
-                            {
-                                "chunk_id": record.chunk_id,
-                                "build_id": record.build_id,
-                                "generation_id": record.generation_id,
-                                "vector_sha256": _digest(_unit_vector(record.vector)),
-                                "input_sha256": _digest(record.vector),
-                            }
-                            for record in batch
-                        ],
-                    )
-                except Exception:
-                    raise VectorStoreError("vector_write_unavailable") from None
-            self.verify(incoming)
-
-    def verify(self, records: Sequence[RawVectorRecord]) -> None:
-        """Verify every expected ID, metadata, dimensions and exact float32 vector."""
-        with self._lock:
-            self._require_open()
-            expected = self._records(records)
-            actual = self._read_records([record.chunk_id for record in expected])
-            for record in expected:
-                if record.chunk_id not in actual:
-                    raise VectorStoreError("vector_record_missing")
-                if not _matches(actual[record.chunk_id], record):
-                    raise VectorStoreError("vector_immutable_conflict")
-
-    def verify_candidates(
-        self,
-        candidates: Sequence[tuple[str, str]],
-        *,
-        deadline: float,
-    ) -> bool:
-        """Read-only presence/integrity check for (chunk_id, expected_build_id).
-
-        Costs O(candidates * dimensions), not a bounded top-K lookup. False means
-        deadline exhaustion, never proof of absence. Each read covers at most
-        2048 IDs; synchronous backend calls cannot be interrupted. This is not a
-        snapshot across Chroma and SQLite: Core still owns final eligibility
-        checks and writer serialization. Chroma may perform maintenance writes.
-        """
-        with self._lock:
-            self._require_open()
-            if (
-                isinstance(deadline, bool)
-                or not isinstance(deadline, Real)
-                or not math.isfinite(deadline)
-            ):
-                raise VectorStoreError("vector_invalid_deadline")
-            if not isinstance(candidates, Sequence) or isinstance(candidates, (str, bytes)):
-                raise VectorStoreError("vector_invalid_candidates")
-            expected: list[tuple[str, str]] = []
-            seen: set[str] = set()
-            for pair in candidates:
-                if (
-                    not isinstance(pair, Sequence)
-                    or isinstance(pair, (str, bytes))
-                    or len(pair) != 2
-                ):
-                    raise VectorStoreError("vector_invalid_candidates")
-                key, build = pair
-                _identifier(key)
-                _identifier(build)
-                if key in seen:
-                    raise VectorStoreError("vector_duplicate_candidates")
-                seen.add(key)
-                expected.append((key, build))
-            for start in range(0, len(expected), ALLOWLIST_BATCH_SIZE):
-                if self._clock() >= deadline:
-                    return False
-                batch = expected[start : start + ALLOWLIST_BATCH_SIZE]
-                # Bound this call to one batch so it cannot read past the next
-                # deadline checkpoint via _read_records' internal loop.
-                actual = self._read_records([key for key, _build in batch])
-                for key, build in batch:
-                    if key not in actual:
-                        raise VectorStoreError("vector_record_missing")
-                    if actual[key][0].build_id != build:
-                        raise VectorStoreError("vector_metadata_identity_mismatch")
-                if self._clock() >= deadline:
-                    return False
-            return True
-
-    def search(
-        self,
-        query_vector: Sequence[float],
-        eligible_ids: Sequence[str],
-        limit: int,
-        deadline: float,
-    ) -> VectorSearchResult:
-        """Rank exactly the eligible candidates; synchronous backend cannot be preempted.
-
-        deadline is absolute monotonic seconds. A late batch is discarded; prior
-        on-time batches may return partial. complete means every eligible
-        vector was scored, NOT complete index coverage: only chunks the caller
-        already resolved as eligible and published are searched.
-
-        The eligible embeddings are read back in bounded batches and ranked
-        here, because Chroma's own filtered query does not score every ID in
-        its allowlist. A global top-K filtered afterwards would rank
-        unauthorized vectors first and let them crowd the eligible ones out.
-        """
-        with self._lock:
-            self._require_open()
-            vector = _unit_vector(_vector(query_vector, self.dimensions))
-            if type(limit) is not int or not 1 <= limit <= ALLOWLIST_BATCH_SIZE:
-                raise VectorStoreError("vector_invalid_limit")
-            if (
-                isinstance(deadline, bool)
-                or not isinstance(deadline, Real)
-                or not math.isfinite(deadline)
-            ):
-                raise VectorStoreError("vector_invalid_deadline")
-            if isinstance(eligible_ids, (str, bytes)):
-                raise VectorStoreError("vector_invalid_allowlist")
-            ids = tuple(eligible_ids)
-            for key in ids:
-                _identifier(key)
-            if len(set(ids)) != len(ids):
-                raise VectorStoreError("vector_duplicate_allowlist")
-            hits: list[VectorHit] = []
-            searched = 0
-            for start in range(0, len(ids), ALLOWLIST_BATCH_SIZE):
-                if self._clock() >= deadline:
-                    break
-                batch = ids[start : start + ALLOWLIST_BATCH_SIZE]
-                try:
-                    read = self._read_records(batch)
-                except VectorStoreError as error:
-                    # A missing or corrupt eligible vector is not "no hits".
-                    raise VectorStoreError("vector_query_unavailable") from error
-                if self._clock() >= deadline:
-                    break
-                try:
-                    missing = [key for key in batch if key not in read]
-                    if missing:
-                        # The caller resolved these as eligible and published,
-                        # so an absent vector is a broken build, not a miss.
-                        raise VectorStoreError("vector_query_unavailable")
-                    validated = [
-                        VectorHit(
-                            key,
-                            read[key][0].build_id,
-                            read[key][0].generation_id,
-                            # Stored vectors are unit length, so the inner
-                            # product is the cosine similarity.
-                            1.0 - _dot(read[key][0].vector, vector),
-                        )
-                        for key in batch
-                    ]
-                except VectorStoreError:
-                    raise
-                except Exception:
-                    raise VectorStoreError("vector_invalid_query_response") from None
-                if self._clock() >= deadline:
-                    break
-                searched += len(batch)
-                hits.extend(validated)
-                hits.sort(key=lambda hit: (hit.distance, hit.chunk_id))
-                del hits[limit:]
-            complete = searched == len(ids)
-            return VectorSearchResult(
-                tuple(hits), complete, len(ids), searched, None if complete else "deadline"
-            )
-
-
-def _dot(left: Sequence[float], right: Sequence[float]) -> float:
-    return math.fsum(a * b for a, b in zip(left, right, strict=True))
-
-
-def _identifier(value: Any) -> None:
-    if not isinstance(value, str) or not re.fullmatch(r"[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,255}", value):
-        raise VectorStoreError("vector_invalid_identifier")
-
-
-def _vector(value: Sequence[float], dimensions: int) -> tuple[float, ...]:
-    try:
-        if len(value) != dimensions or any(
-            isinstance(v, bool) or not isinstance(v, Real) or not math.isfinite(v) for v in value
-        ):
-            raise VectorStoreError("vector_invalid_values_or_dimensions")
-        packed = struct.pack(f"<{dimensions}f", *value)
-        normalized = struct.unpack(f"<{dimensions}f", packed)
-        if not all(math.isfinite(v) for v in normalized) or not any(normalized):
-            raise VectorStoreError("vector_invalid_values_or_dimensions")
-        return normalized
-    except VectorStoreError:
-        raise
-    except (ValueError, TypeError, OverflowError, struct.error):
-        raise VectorStoreError("vector_invalid_values_or_dimensions") from None
-
-
-def _digest(vector: tuple[float, ...]) -> str:
-    return sha256(struct.pack(f"<{len(vector)}f", *vector)).hexdigest()
-
-
-def _unit_vector(vector: tuple[float, ...]) -> tuple[float, ...]:
-    length = math.sqrt(math.fsum(component * component for component in vector))
-    return _vector(tuple(component / length for component in vector), len(vector))
-
-
-def _matches(actual: tuple[RawVectorRecord, str], expected: RawVectorRecord) -> bool:
-    stored, input_digest = actual
-    return input_digest == _digest(expected.vector) and stored == RawVectorRecord(
-        expected.chunk_id, expected.build_id, expected.generation_id, _unit_vector(expected.vector)
-    )

memhub/apps/core/src/one_memory/sdk_data_plane_migration.py

@@ -41,6 +41,20 @@ class MigrationProgress:
     phase: str
 
 
+def _ledger_log(database_path: Path, event: str, migration_id: str, **details: object) -> None:
+    """Every ledger transition goes to `sdk-migration.log`; never raises."""
+    from one_memory.sdk_migration_log import write_migration_log
+
+    write_migration_log(
+        database_path.parent,
+        writer="core-sdk-migrate",
+        event=event,
+        outcome="succeeded",
+        migration_id=migration_id,
+        details=details,
+    )
+
+
 class SdkDataPlaneMigrationStore:
     def __init__(self, database_path: Path) -> None:
         self.database_path = database_path
@@ -50,18 +64,29 @@ class SdkDataPlaneMigrationStore:
         return datetime.now(UTC).isoformat()
 
     def authority(self) -> MemoryAuthority:
+        return self.authority_state()[0]
+
+    def authority_state(self) -> tuple[MemoryAuthority, str | None]:
+        """The surviving singleton: authority and the migration that set it.
+
+        This is the only source of authority. The detailed cutover receipt is
+        dropped after cleanup and never exists on a fresh home.
+        """
         try:
             with main_database(self.database_path).read() as connection:
                 row = connection.execute(
-                    "SELECT authority FROM memory_authority_state WHERE singleton=1"
+                    "SELECT authority,migration_id FROM memory_authority_state WHERE singleton=1"
                 ).fetchone()
         except sqlite3.OperationalError as error:
             if "no such table" not in str(error).lower():
                 raise
         else:
             if row is not None:
-                return MemoryAuthority(str(row[0]))
-        return MemoryAuthority.SDK if self.cutover() is not None else MemoryAuthority.LEGACY
+                return MemoryAuthority(str(row[0])), (str(row[1]) if row[1] else None)
+        marker = self.cutover()
+        if marker is not None:
+            return MemoryAuthority.SDK, marker.migration_id
+        return MemoryAuthority.LEGACY, None
 
     def cutover(self) -> CutoverMarker | None:
         try:
@@ -140,7 +165,16 @@ class SdkDataPlaneMigrationStore:
             elif backup_bundle_id and existing["backup_bundle_id"] != backup_bundle_id:
                 raise DataPlaneMigrationError("sdk_data_plane_migration_bundle_conflict")
             connection.execute("COMMIT")
-        return self.progress(migration_id)
+        progress = self.progress(migration_id)
+        _ledger_log(
+            self.database_path,
+            "ledger.started",
+            migration_id,
+            created=existing is None,
+            state=progress.state,
+            phase=progress.phase,
+        )
+        return progress
 
     def set_phase(self, migration_id: str, *, phase: str, state: str = "running") -> None:
         with main_database(self.database_path).write(autocommit=True) as connection:
@@ -153,6 +187,7 @@ class SdkDataPlaneMigrationStore:
             if cursor.rowcount != 1:
                 raise DataPlaneMigrationError("sdk_data_plane_migration_not_mutable")
             connection.execute("COMMIT")
+        _ledger_log(self.database_path, "ledger.phase_set", migration_id, phase=phase, state=state)
 
     def progress(self, migration_id: str) -> MigrationProgress:
         with main_database(self.database_path).read(row_factory=sqlite3.Row) as connection:
@@ -246,6 +281,7 @@ class SdkDataPlaneMigrationStore:
                 (migration_id, now),
             )
             connection.execute("COMMIT")
+        _ledger_log(self.database_path, "ledger.authority_committed", migration_id, authority="sdk")
         marker = self.cutover()
         if marker is None:
             raise DataPlaneMigrationError("sdk_data_plane_cutover_missing")

memhub/apps/core/src/one_memory/sdk_migration_log.py

@@ -0,0 +1,243 @@
+"""The one log support asks for when an upgrade did not reach SDK authority.
+
+`<data_dir>/logs/sdk-migration.log` is JSON Lines, shared with the TypeScript
+orchestrator (`packages/runtime-control/src/sdk-migration-log.ts`), which writes
+the same line shape. A person attaches this single file to a report, so every
+line says who wrote it, which build, which migration and what happened.
+
+It must never carry user content: no memory or conversation text, no provider
+response, no exception message (a message can quote either). Errors are logged
+as their type, a sanitised code and traceback frames as `file:line:function`.
+Detail values are numbers, booleans and short identifier-shaped strings only;
+anything else is dropped rather than escaped.
+
+Writing is synchronous and flushed: a migration is rare and the line that
+explains a failure is worth more than the milliseconds. A write failure is
+swallowed, because logging must never be the reason a migration or a startup
+fails.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import traceback
+from collections.abc import Iterator, Mapping
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+LOG_NAME = "sdk-migration.log"
+#: Rotated to `sdk-migration.log.1` beyond this; one generation is kept.
+MAX_BYTES = 4 * 1024 * 1024
+
+_SAFE_TEXT = re.compile(r"^[A-Za-z0-9_.:/@+\-]{0,160}$")
+_CODE = re.compile(r"^[a-z][a-z0-9]*(?:[._-][a-z0-9]+){0,15}$")
+_SUBJECT = re.compile(r"^[A-Za-z0-9_.\-]{1,96}$")
+_MAX_ITEMS = 32
+_MAX_DEPTH = 4
+_MAX_FRAMES = 24
+_FRAME = re.compile(r"^[A-Za-z0-9_.\-]{1,96}:\d{1,7}:<?[A-Za-z0-9_]{1,96}>?$")
+
+
+def log_path(data_dir: Path) -> Path:
+    return data_dir / "logs" / LOG_NAME
+
+
+def _safe(value: object, depth: int = 0) -> Any:
+    if value is None or isinstance(value, bool):
+        return value
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float):
+        return round(value, 3) if value == value and abs(value) != float("inf") else None
+    if isinstance(value, str):
+        return value if _SAFE_TEXT.fullmatch(value) else "<redacted>"
+    if depth >= _MAX_DEPTH:
+        return "<nested>"
+    if isinstance(value, Mapping):
+        result: dict[str, Any] = {}
+        for index, (key, item) in enumerate(value.items()):
+            if index >= _MAX_ITEMS:
+                result["<truncated>"] = len(value) - _MAX_ITEMS
+                break
+            if isinstance(key, str) and _SAFE_TEXT.fullmatch(key):
+                result[key] = _safe(item, depth + 1)
+        return result
+    if isinstance(value, (list, tuple, set, frozenset)):
+        items = list(value)
+        safe = [_safe(item, depth + 1) for item in items[:_MAX_ITEMS]]
+        if len(items) > _MAX_ITEMS:
+            safe.append(f"<+{len(items) - _MAX_ITEMS}>")
+        return safe
+    return "<unsupported>"
+
+
+def _chain(error: BaseException) -> Iterator[BaseException]:
+    seen: set[int] = set()
+    current: BaseException | None = error
+    while current is not None and id(current) not in seen:
+        seen.add(id(current))
+        yield current
+        current = current.__cause__ or current.__context__
+
+
+def describe_error(error: BaseException) -> dict[str, object]:
+    """Type, code and frames of an exception chain; never its message."""
+    chain: list[dict[str, object]] = []
+    for item in _chain(error):
+        name = type(item).__name__
+        entry: dict[str, object] = {"type": name if _SAFE_TEXT.fullmatch(name) else "<unknown>"}
+        code = getattr(item, "code", None)
+        if isinstance(code, str):
+            # `<code>:<opaque id>` names the row that failed, e.g. a write job.
+            name, _, subject = code.partition(":")
+            if _CODE.fullmatch(name):
+                entry["code"] = name
+                if subject and _SUBJECT.fullmatch(subject):
+                    entry["subject"] = subject
+        message = str(item)
+        # A message that is itself a stable code (the codebase's convention
+        # for domain errors) is safe to keep; anything else is content.
+        if _CODE.fullmatch(message):
+            entry["code"] = entry.get("code") or message
+        errno = getattr(item, "errno", None)
+        if isinstance(errno, int):
+            entry["errno"] = errno
+        if isinstance(item, OSError) and item.filename is not None:
+            # A path names a file, not its contents, but home directories can
+            # name a person: keep only the file name.
+            entry["file"] = Path(str(item.filename)).name
+        frames = traceback.extract_tb(item.__traceback__)[-_MAX_FRAMES:]
+        # Code locations, not content: built here from file names, line
+        # numbers and function names (`<module>`, `<lambda>` included).
+        entry["frames"] = [
+            location
+            for frame in frames
+            if _FRAME.fullmatch(
+                location := f"{Path(frame.filename).name}:{frame.lineno}:{frame.name}"
+            )
+        ]
+        chain.append(entry)
+        if len(chain) >= 6:
+            break
+    return {"chain": chain}
+
+
+def _build() -> dict[str, object]:
+    from one_memory import __version__
+
+    build: dict[str, object] = {"core_version": __version__}
+    for key, name in (
+        ("ONE_MEMORY_VERSION", "app_version"),
+        ("ONE_MEMORY_BUILD_NUMBER", "build_number"),
+        ("ONE_MEMORY_COMMIT", "build_commit"),
+        ("ONE_MEMORY_MIGRATION_CALLER", "caller"),
+        ("ONE_MEMORY_MIGRATION_RUNTIME_BUILD", "runtime_build"),
+    ):
+        value = os.environ.get(key, "").strip()
+        if value:
+            build[name] = value
+    return _safe(build)
+
+
+def write_migration_log(
+    data_dir: Path,
+    *,
+    writer: str,
+    event: str,
+    outcome: str,
+    migration_id: str | None = None,
+    details: Mapping[str, object] | None = None,
+    error: BaseException | None = None,
+    code: str | None = None,
+) -> None:
+    """Append one line. Never raises."""
+    try:
+        line: dict[str, object] = {
+            "schema_version": 1,
+            "ts": datetime.now(UTC).isoformat(),
+            "pid": os.getpid(),
+            "writer": writer,
+            "event": event,
+            "outcome": outcome,
+            **_build(),
+        }
+        if migration_id is not None:
+            line["migration_id"] = migration_id
+        if code is not None:
+            line["code"] = code
+        if details:
+            line["details"] = dict(details)
+        safe_line = _safe(line)
+        if not isinstance(safe_line, dict):
+            return
+        if error is not None:
+            # Already content-free by construction; `_safe` would redact the
+            # `<module>` frames.
+            safe_line["error"] = describe_error(error)
+        destination = log_path(data_dir)
+        destination.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+        try:
+            if destination.stat().st_size > MAX_BYTES:
+                os.replace(destination, destination.with_name(f"{LOG_NAME}.1"))
+        except FileNotFoundError:
+            pass
+        payload = (json.dumps(safe_line, ensure_ascii=False) + "\n").encode("utf-8")
+        descriptor = os.open(destination, os.O_WRONLY | os.O_APPEND | os.O_CREAT, 0o600)
+        try:
+            os.write(descriptor, payload)
+            os.fsync(descriptor)
+        finally:
+            os.close(descriptor)
+    except Exception:  # noqa: BLE001 - logging must never break a migration
+        return
+
+
+def migration_rows(database_path: Path) -> list[dict[str, object]]:
+    """The recorded migration attempts, newest first; ids, states and phases only."""
+    import sqlite3
+
+    try:
+        connection = sqlite3.connect(f"file:{database_path}?mode=ro", uri=True, timeout=1)
+    except sqlite3.Error:
+        return []
+    try:
+        rows = connection.execute(
+            "SELECT migration_id,state,phase,created_at,updated_at "
+            "FROM sdk_data_plane_migrations ORDER BY created_at DESC LIMIT 8"
+        ).fetchall()
+    except sqlite3.Error:
+        return []
+    finally:
+        connection.close()
+    return [
+        {
+            "migration_id": row[0],
+            "state": row[1],
+            "phase": row[2],
+            # Older builds stored `YYYY-MM-DD HH:MM:SS`; keep it identifier-shaped.
+            "created_at": str(row[3]).replace(" ", "T"),
+            "updated_at": str(row[4]).replace(" ", "T"),
+        }
+        for row in rows
+    ]
+
+
+def authority_snapshot(database_path: Path) -> dict[str, object]:
+    """Authority and recorded attempts, read without changing the database."""
+    if not database_path.is_file():
+        return {"database": "absent"}
+    snapshot: dict[str, object] = {"database": "present"}
+    try:
+        from one_memory.sdk_data_plane_migration import SdkDataPlaneMigrationStore
+
+        authority, authority_migration = SdkDataPlaneMigrationStore(database_path).authority_state()
+        snapshot["authority"] = authority.value
+        snapshot["authority_migration_id"] = authority_migration
+    except Exception as error:  # noqa: BLE001 - a snapshot must not fail its caller
+        snapshot["authority"] = "unreadable"
+        snapshot["authority_error"] = type(error).__name__
+    snapshot["migrations"] = migration_rows(database_path)
+    return snapshot

memhub/apps/core/src/one_memory/sdk_migration_runner.py

@@ -14,10 +14,12 @@ import json
 import os
 import shutil
 import sqlite3
+import time
 from collections.abc import Callable, Iterator
-from contextlib import contextmanager
+from contextlib import AbstractContextManager, contextmanager
 from dataclasses import dataclass
 from pathlib import Path
+from typing import Any
 
 from one_memory.database_access import main_database
 from one_memory.imports.models import EvidenceRecord
@@ -35,6 +37,7 @@ from one_memory.memory_server.durable_queue import (
     DurableWriteQueue,
 )
 from one_memory.memory_server.unified_entry import UnifiedWriteIntake
+from one_memory.model_profiles import ModelProfileSnapshot
 from one_memory.sdk_data_plane_migration import (
     CutoverMarker,
     DataPlaneMigrationError,
@@ -42,11 +45,90 @@ from one_memory.sdk_data_plane_migration import (
     SdkDataPlaneMigrationStore,
 )
 from one_memory.sdk_migration_bundle import inspect_sdk_migration_bundle
+from one_memory.sdk_migration_verify import (
+    MemoryReadbackFailed,
+    ReadbackReport,
+    legacy_memory_ids_from,
+    legacy_memory_ids_from_bundle,
+    read_active_profile,
+    runtime_sdk_client,
+    verify_readback,
+)
+from one_memory.sdk_vector_reattach import (
+    ReattachedCollection,
+    legacy_vector_collections,
+    reattach_legacy_vectors,
+)
 from one_memory.target_schema import drop_legacy_tables, legacy_tables_present
 
 PREPARED_PHASE = "prepared"
 
 
+class _StepLog:
+    """Each runner step, its duration, its counts and how it ended.
+
+    The CLI only sees the exception that escapes `run_startup_migration` and
+    names it with a generic code when it is not one of ours; these lines say
+    which step raised it. Content-free: only names, counts and codes.
+    """
+
+    def __init__(self, data_dir: Path) -> None:
+        self.data_dir = data_dir
+        self.migration_id: str | None = None
+
+    def check(self, step: str, code: str | None) -> None:
+        """One preflight check that is a decision, not a call: its result code."""
+        from one_memory.sdk_migration_log import write_migration_log
+
+        write_migration_log(
+            self.data_dir,
+            writer="core-sdk-migrate",
+            event="step.failed" if code else "step.finished",
+            outcome="failed" if code else "succeeded",
+            migration_id=self.migration_id,
+            code=code,
+            details={"step": step, "result": code or "passed"},
+        )
+
+    @contextmanager
+    def step(self, name: str) -> Iterator[dict[str, object]]:
+        from one_memory.sdk_migration_log import write_migration_log
+
+        started = time.monotonic()
+        details: dict[str, object] = {}
+        try:
+            yield details
+        except BaseException as error:
+            code = getattr(error, "code", None)
+            write_migration_log(
+                self.data_dir,
+                writer="core-sdk-migrate",
+                event="step.failed",
+                outcome="failed",
+                migration_id=self.migration_id,
+                code=code if isinstance(code, str) else None,
+                error=error,
+                details={
+                    "step": name,
+                    "duration_ms": (time.monotonic() - started) * 1000,
+                    **details,
+                },
+            )
+            raise
+        write_migration_log(
+            self.data_dir,
+            writer="core-sdk-migrate",
+            event="step.finished",
+            outcome="succeeded",
+            migration_id=self.migration_id,
+            details={
+                "step": name,
+                "duration_ms": (time.monotonic() - started) * 1000,
+                **details,
+            },
+        )
+
+
 @dataclass(frozen=True)
 class CutoverPreparation:
     """What the cutover did to legacy work, for the receipt and the dialog."""
@@ -67,8 +149,7 @@ class CutoverPreparation:
 
 def _tables(database: sqlite3.Connection) -> set[str]:
     return {
-        str(row[0])
-        for row in database.execute("SELECT name FROM sqlite_master WHERE type='table'")
+        str(row[0]) for row in database.execute("SELECT name FROM sqlite_master WHERE type='table'")
     }
 
 
@@ -112,9 +193,7 @@ def prepare_legacy_write_queue_for_cutover(database_path: Path) -> tuple[int, in
         if "evidence" not in tables:
             return (0, 0)
         jobs = (
-            tuple(
-                database.execute("SELECT job_id,state,payload_json FROM memory_write_jobs")
-            )
+            tuple(database.execute("SELECT job_id,state,payload_json FROM memory_write_jobs"))
             if "memory_write_jobs" in tables
             else ()
         )
@@ -265,15 +344,27 @@ def abandoned_legacy_work(database_path: Path) -> dict[str, int]:
     return abandoned
 
 
-def prepare_legacy_work_for_cutover(database_path: Path) -> CutoverPreparation:
-    """Make the surviving queue self-contained. Safe to repeat."""
+def prepare_legacy_work_for_cutover(
+    database_path: Path, trace: dict[str, object] | None = None
+) -> CutoverPreparation:
+    """Make the surviving queue self-contained. Safe to repeat.
+
+    `trace` (the migration log's step details) learns which sub-step is
+    running, so a failure names it.
+    """
+    trace = {} if trace is None else trace
+    trace["sub_step"] = "write_queue"
     frozen, moved = prepare_legacy_write_queue_for_cutover(database_path)
+    trace["sub_step"] = "pending_dispatches"
     dispatches = move_pending_dispatches(database_path)
+    trace["sub_step"] = "abandoned_work"
+    abandoned = abandoned_legacy_work(database_path)
+    trace.pop("sub_step", None)
     return CutoverPreparation(
         frozen_jobs=frozen,
         moved_tasks=moved,
         moved_dispatches=dispatches,
-        abandoned=abandoned_legacy_work(database_path),
+        abandoned=abandoned,
     )
 
 
@@ -341,6 +432,8 @@ class StartupMigrationResult:
     bundle_id: str | None = None
     preparation: CutoverPreparation | None = None
     dropped_tables: tuple[str, ...] = ()
+    reattached: tuple[ReattachedCollection, ...] = ()
+    readback: ReadbackReport | None = None
 
     def as_document(self) -> dict[str, object]:
         document: dict[str, object] = {"schema_version": 1, "state": self.state}
@@ -349,6 +442,18 @@ class StartupMigrationResult:
             document["bundle_id"] = self.bundle_id
         if self.preparation is not None:
             document.update(self.preparation.as_document())
+        if self.reattached:
+            document["reattached_vectors"] = [
+                {
+                    "collection": item.current,
+                    "legacy_count": item.legacy_count,
+                    "merged_count": item.merged_count,
+                    "final_count": item.final_count,
+                }
+                for item in self.reattached
+            ]
+        if self.readback is not None:
+            document["readback"] = self.readback.as_document()
         if self.dropped_tables:
             document["dropped_tables"] = list(self.dropped_tables)
         return document
@@ -415,6 +520,15 @@ def _ensure_bundle(*, data_dir: Path, bundle_id: str, runtime_build: str) -> dic
     return inspect_sdk_migration_bundle(data_dir=data_dir, bundle_id=bundle_id)
 
 
+def _vacuum(database_path: Path) -> None:
+    """Return the dropped tables' pages to the disk; a full disk only skips it."""
+    try:
+        with main_database(database_path).write(autocommit=True) as database:
+            database.execute("VACUUM")
+    except sqlite3.OperationalError:
+        return
+
+
 def run_startup_migration(
     *,
     data_dir: Path,
@@ -422,71 +536,173 @@ def run_startup_migration(
     sdk_version: str,
     namespace: str,
     progress: Callable[[str], None] = lambda _step: None,
+    open_client: Callable[[ModelProfileSnapshot], AbstractContextManager[Any]] | None = None,
 ) -> StartupMigrationResult:
     """Bring one stopped home to SDK authority. Safe to repeat after any failure.
 
     The caller must stop Runtime and keep its service from restarting.
+    `open_client` yields a public SDK client configured as the Runtime will be;
+    tests replace it.
     """
     database_path = data_dir / "one-memory.sqlite3"
     if not database_path.is_file():
         return StartupMigrationResult(state="not_required")
+
+    def client_for(profile: ModelProfileSnapshot) -> AbstractContextManager[Any]:
+        if open_client is not None:
+            return open_client(profile)
+        return runtime_sdk_client(database_path, data_dir, profile)
+
+    log = _StepLog(data_dir)
     store = SdkDataPlaneMigrationStore(database_path)
-    if store.authority() is MemoryAuthority.SDK:
-        if not legacy_tables_present(database_path) and not abandoned_staging_present(
-            data_dir=data_dir, namespace=namespace
-        ):
+    with log.step("preflight.authority_read") as step:
+        authority, authority_migration = store.authority_state()
+        step["authority"] = authority.value
+    log.migration_id = authority_migration
+    with log.step("preflight.profile_read") as step:
+        profile = read_active_profile(database_path)
+        step["profile_present"] = profile is not None
+    if authority is MemoryAuthority.SDK:
+        with log.step("preflight.leftovers_scan") as step:
+            vectors_waiting = profile is not None and bool(
+                legacy_vector_collections(data_dir, profile)
+            )
+            leftovers = bool(legacy_tables_present(database_path)) or abandoned_staging_present(
+                data_dir=data_dir, namespace=namespace
+            )
+            step["vectors_waiting"] = vectors_waiting
+            step["leftovers"] = leftovers
+        if not vectors_waiting and not leftovers:
             return StartupMigrationResult(state="not_required")
-        progress("cleanup")
+        reattached: tuple[ReattachedCollection, ...] = ()
+        readback: ReadbackReport | None = None
+        if vectors_waiting:
+            assert profile is not None
+            progress("vectors")
+            with log.step("vectors.reattach") as step:
+                reattached = reattach_legacy_vectors(data_dir, profile)
+                step["collections"] = len(reattached)
+            with log.step("verify.legacy_ids_from_bundle") as step:
+                legacy = legacy_memory_ids_from_bundle(data_dir, authority_migration)
+                step["bundle_ids_present"] = legacy is not None
+            if legacy is not None and not legacy.empty:
+                # Authority already moved, so nothing is left to protect by
+                # refusing; record what the repaired home reads back.
+                progress("verify")
+                with log.step("verify.readback") as step, client_for(profile) as client:
+                    readback = verify_readback(client, legacy)
+                    step.update(readback.as_document())
+        dropped: tuple[str, ...] = ()
+        if leftovers:
+            progress("cleanup")
+            with log.step("cleanup.drop_legacy_tables") as step:
+                dropped = resume_legacy_cleanup(data_dir=data_dir, database_path=database_path)
+                step["dropped_tables"] = len(dropped)
+            if dropped:
+                with log.step("cleanup.vacuum"):
+                    _vacuum(database_path)
         return StartupMigrationResult(
             state="complete",
-            dropped_tables=resume_legacy_cleanup(data_dir=data_dir, database_path=database_path),
+            migration_id=authority_migration,
+            bundle_id=f"{authority_migration}-pre-cutover" if authority_migration else None,
+            dropped_tables=dropped,
+            reattached=reattached,
+            readback=readback,
         )
 
     from one_memory.database_access import close_main_databases
     from one_memory.memory_server.migration_runner import SqliteMigrationStore, migrate
     from one_memory.memory_server.migrations import MIGRATIONS
 
-    migration_id, bundle_id = _resumable_identity(database_path)
+    with log.step("preflight.resumable_identity") as step:
+        migration_id, bundle_id = _resumable_identity(database_path)
+        step["resumed"] = migration_id != f"{MIGRATION_PREFIX}-{database_generation(database_path)}"
+    log.migration_id = migration_id
+    with log.step("preflight.legacy_ids_scan") as step:
+        legacy = legacy_memory_ids_from(database_path)
+        step["chat"] = len(legacy.chat)
+        step["productivity"] = len(legacy.productivity)
+        step["users"] = len(legacy.users)
+    if profile is None and not legacy.empty:
+        # Without the embedding profile the Runtime's collections cannot be
+        # named, so neither reattached nor read back. Legacy stays intact.
+        log.check("preflight.model_profile_check", "sdk_migration_model_profile_required")
+        raise DataPlaneMigrationError("sdk_migration_model_profile_required")
+    log.check("preflight.model_profile_check", None)
     with capture_fence(data_dir):
         progress("bundle")
-        manifest = _ensure_bundle(
-            data_dir=data_dir,
-            bundle_id=bundle_id,
-            runtime_build=runtime_build,
-        )
+        with log.step("bundle.ensure") as step:
+            manifest = _ensure_bundle(
+                data_dir=data_dir,
+                bundle_id=bundle_id,
+                runtime_build=runtime_build,
+            )
+            step["bundle_id"] = bundle_id
         progress("prepare")
-        asyncio.run(migrate(SqliteMigrationStore(database_path), MIGRATIONS))
-        close_main_databases()
-        recover_abandoned_staging(
-            data_dir=data_dir,
-            database_path=database_path,
-            namespace=namespace,
-        )
-        store.start(
-            migration_id=migration_id,
-            source_runtime_build=str(manifest.get("runtime_build") or ""),
-            target_sdk_version=sdk_version,
-            source_schema_version=MIGRATIONS[-1].version,
-            namespace_fingerprint=hashlib.sha256(namespace.encode()).hexdigest(),
-            backend_fingerprint=hashlib.sha256(b"chroma:kuzu:sqlite").hexdigest(),
-            backup_bundle_id=bundle_id,
-        )
-        preparation = prepare_legacy_work_for_cutover(database_path)
-        store.set_phase(migration_id, phase=PREPARED_PHASE, state="ready")
+        with log.step("prepare.schema_migrate") as step:
+            asyncio.run(migrate(SqliteMigrationStore(database_path), MIGRATIONS))
+            close_main_databases()
+            step["schema_version"] = MIGRATIONS[-1].version
+        with log.step("prepare.recover_abandoned_staging"):
+            recover_abandoned_staging(
+                data_dir=data_dir,
+                database_path=database_path,
+                namespace=namespace,
+            )
+        with log.step("prepare.ledger_start"):
+            store.start(
+                migration_id=migration_id,
+                source_runtime_build=str(manifest.get("runtime_build") or ""),
+                target_sdk_version=sdk_version,
+                source_schema_version=MIGRATIONS[-1].version,
+                namespace_fingerprint=hashlib.sha256(namespace.encode()).hexdigest(),
+                backend_fingerprint=hashlib.sha256(b"chroma:kuzu:sqlite").hexdigest(),
+                backup_bundle_id=bundle_id,
+            )
+        with log.step("prepare.legacy_work") as step:
+            preparation = prepare_legacy_work_for_cutover(database_path, step)
+            step.update(preparation.as_document())
+        reattached = ()
+        readback = None
+        if profile is not None:
+            progress("vectors")
+            with log.step("vectors.reattach") as step:
+                reattached = reattach_legacy_vectors(data_dir, profile)
+                step["collections"] = len(reattached)
+        if not legacy.empty:
+            assert profile is not None
+            progress("verify")
+            with log.step("verify.readback") as step:
+                with client_for(profile) as client:
+                    readback = verify_readback(client, legacy)
+                step.update(readback.as_document())
+                if not readback.passed:
+                    store.set_phase(migration_id, phase="readback_failed", state="blocked")
+                    raise MemoryReadbackFailed(readback)
+        with log.step("prepare.mark_prepared"):
+            store.set_phase(migration_id, phase=PREPARED_PHASE, state="ready")
         progress("cutover")
-        commit_sdk_cutover(
-            data_dir=data_dir,
-            database_path=database_path,
-            migration_id=migration_id,
-            bundle_id=bundle_id,
-            sdk_version=sdk_version,
-        )
+        with log.step("cutover.commit"):
+            commit_sdk_cutover(
+                data_dir=data_dir,
+                database_path=database_path,
+                migration_id=migration_id,
+                bundle_id=bundle_id,
+                sdk_version=sdk_version,
+            )
         progress("cleanup")
-        dropped = resume_legacy_cleanup(data_dir=data_dir, database_path=database_path)
+        with log.step("cleanup.drop_legacy_tables") as step:
+            dropped = resume_legacy_cleanup(data_dir=data_dir, database_path=database_path)
+            step["dropped_tables"] = len(dropped)
+        if dropped:
+            with log.step("cleanup.vacuum"):
+                _vacuum(database_path)
     return StartupMigrationResult(
         state="cutover",
         migration_id=migration_id,
         bundle_id=bundle_id,
         preparation=preparation,
         dropped_tables=dropped,
+        reattached=reattached,
+        readback=readback,
     )

memhub/apps/core/src/one_memory/sdk_migration_verify.py

@@ -0,0 +1,232 @@
+"""Read legacy memory IDs back through the SDK before (and after) the cutover.
+
+The cutover is only safe if the SDK, configured exactly as the new Runtime
+will configure it, returns the memories the legacy mirror lists. Checking that
+the backup bundle is complete says nothing about it: build 20 dropped the
+legacy tables while its Runtime read an empty vector collection.
+
+Reads go through the public `HyMemoryClient` (`list_memories`, `get`).
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+from collections.abc import Iterator
+from contextlib import closing, contextmanager
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from one_memory.database_access import main_database
+from one_memory.model_profiles import ModelProfileSnapshot
+from one_memory.sdk_data_plane_migration import DataPlaneMigrationError
+
+_PRODUCTIVITY_KINDS = frozenset({"coding", "working"})
+_PRODUCTIVITY_LAYERS = frozenset(
+    {"coding_experience", "working_experience", "coding_fact", "working_fact"}
+)
+_SDK_STATUSES = ("active", "superseded", "shadow", "negated", "conflicted", "archived")
+_PAGE = 500
+
+
+@dataclass(frozen=True)
+class LegacyMemoryIds:
+    chat: tuple[str, ...]
+    productivity: tuple[str, ...]
+    users: tuple[str, ...]
+
+    @property
+    def empty(self) -> bool:
+        return not self.chat and not self.productivity
+
+
+@dataclass(frozen=True)
+class ReadbackReport:
+    chat_expected: int
+    chat_readable: int
+    productivity_expected: int
+    productivity_readable: int
+
+    @property
+    def passed(self) -> bool:
+        # Every chat memory is an SDK node by construction, so all must read
+        # back. The SDK's Coding reconciler deletes experiences it retires, so
+        # a partial productivity count is normal; none at all is not.
+        return self.chat_readable == self.chat_expected and (
+            self.productivity_expected == 0 or self.productivity_readable > 0
+        )
+
+    def as_document(self) -> dict[str, object]:
+        return {
+            "chat_expected": self.chat_expected,
+            "chat_readable": self.chat_readable,
+            "productivity_expected": self.productivity_expected,
+            "productivity_readable": self.productivity_readable,
+            "passed": self.passed,
+        }
+
+
+class MemoryReadbackFailed(DataPlaneMigrationError):
+    def __init__(self, report: ReadbackReport) -> None:
+        super().__init__("sdk_migration_memory_unreadable")
+        self.report = report
+
+
+def _tables(connection: sqlite3.Connection) -> set[str]:
+    return {
+        str(row[0])
+        for row in connection.execute("SELECT name FROM sqlite_master WHERE type='table'")
+    }
+
+
+def read_legacy_memory_ids(connection: sqlite3.Connection) -> LegacyMemoryIds:
+    """Confirmed legacy memories, by the SDK id the old bridge recorded."""
+    tables = _tables(connection)
+    if "governed_memories" not in tables:
+        return LegacyMemoryIds(chat=(), productivity=(), users=())
+    mapped: dict[str, tuple[str, str | None]] = {}
+    if "memory_task_outputs" in tables:
+        for (body,) in connection.execute("SELECT body FROM memory_task_outputs"):
+            try:
+                document = json.loads(body)
+            except (TypeError, ValueError):
+                continue
+            legacy_id, sdk_id = document.get("memory_id"), document.get("hy_memory_id")
+            if isinstance(legacy_id, str) and isinstance(sdk_id, str):
+                layer = document.get("layer")
+                mapped[legacy_id] = (sdk_id, layer if isinstance(layer, str) else None)
+    chat: set[str] = set()
+    productivity: set[str] = set()
+    users: set[str] = set()
+    for memory_id, user_id, kind in connection.execute(
+        "SELECT memory_id,user_id,kind FROM governed_memories WHERE status='confirmed'"
+    ):
+        sdk_id, layer = mapped.get(str(memory_id), (str(memory_id), None))
+        users.add(str(user_id))
+        if str(kind) in _PRODUCTIVITY_KINDS or layer in _PRODUCTIVITY_LAYERS:
+            productivity.add(sdk_id)
+        else:
+            chat.add(sdk_id)
+    return LegacyMemoryIds(
+        chat=tuple(sorted(chat)),
+        productivity=tuple(sorted(productivity)),
+        users=tuple(sorted(users)),
+    )
+
+
+def legacy_memory_ids_from(database_path: Path) -> LegacyMemoryIds:
+    with main_database(database_path).read() as connection:
+        return read_legacy_memory_ids(connection)
+
+
+def legacy_memory_ids_from_bundle(
+    data_dir: Path, migration_id: str | None
+) -> LegacyMemoryIds | None:
+    """The same list from the pre-cutover bundle, for a home already migrated."""
+    if not migration_id:
+        return None
+    database = (
+        data_dir
+        / "backups"
+        / f"{migration_id}-pre-cutover.sdk-bundle"
+        / "management"
+        / "one-memory.sqlite3"
+    )
+    if not database.is_file():
+        return None
+    with closing(sqlite3.connect(f"file:{database}?mode=ro", uri=True)) as connection:
+        return read_legacy_memory_ids(connection)
+
+
+def read_active_profile(database_path: Path) -> ModelProfileSnapshot | None:
+    """The active model profile, read only; the status probe runs beside Core."""
+    with main_database(database_path).read(row_factory=sqlite3.Row) as connection:
+        if not {"model_profiles", "model_profile_versions"} <= _tables(connection):
+            return None
+        row = connection.execute(
+            "SELECT version.* FROM model_profiles profile "
+            "JOIN model_profile_versions version "
+            "ON version.profile_id=profile.profile_id AND version.revision=profile.revision "
+            "WHERE profile.is_active=1"
+        ).fetchone()
+    if row is None:
+        return None
+    return ModelProfileSnapshot(
+        profile_id=row["profile_id"],
+        revision=row["revision"],
+        provider_kind=row["provider_kind"],
+        base_url=row["base_url"],
+        model=row["model"],
+        embedding_model=row["embedding_model"],
+        embedding_provider_kind=row["embedding_provider_kind"],
+        embedding_base_url=row["embedding_base_url"],
+        embedding_dimensions=row["embedding_dimensions"],
+        timeout_seconds=row["timeout_seconds"],
+        max_concurrency=row["max_concurrency"],
+        context_window=row["context_window"],
+        has_api_key=row["secret_ref"] is not None,
+        disable_thinking=bool(row["disable_thinking"]),
+    )
+
+
+@contextmanager
+def runtime_sdk_client(
+    database_path: Path, data_dir: Path, profile: ModelProfileSnapshot
+) -> Iterator[Any]:
+    """A public SDK client configured exactly as the Runtime configures it."""
+    from one_memory.hy_sdk_runtime import acquire_client
+    from one_memory.model_profiles import ModelProfileStore
+    from one_memory.secrets import KeyringSecretStore, SecretStoreUnavailableError
+
+    try:
+        secret = ModelProfileStore(database_path).resolve_snapshot_secret(
+            profile.profile_id, profile.revision, KeyringSecretStore()
+        )
+    except SecretStoreUnavailableError:
+        raise DataPlaneMigrationError("sdk_migration_secure_storage_unavailable") from None
+    if profile.has_api_key and secret is None:
+        raise DataPlaneMigrationError("sdk_migration_model_secret_unavailable")
+    lease = acquire_client(profile, api_key=secret, data_dir=data_dir)
+    try:
+        yield lease.client
+    finally:
+        lease.close()
+
+
+def verify_readback(client: Any, legacy: LegacyMemoryIds) -> ReadbackReport:
+    listed: set[str] = set()
+    for user_id in legacy.users or ("local",):
+        offset = 0
+        while True:
+            raw = client.list_memories(
+                user_id=user_id,
+                statuses=list(_SDK_STATUSES),
+                limit=_PAGE,
+                offset=offset,
+                order="asc",
+            )
+            bucket = raw.get("vdb") if isinstance(raw, dict) else None
+            rows = bucket.get("memories") if isinstance(bucket, dict) else None
+            total = bucket.get("total") if isinstance(bucket, dict) else None
+            if not isinstance(rows, list) or not isinstance(total, int):
+                raise DataPlaneMigrationError("sdk_migration_memory_list_shape_unknown")
+            listed.update(
+                str(row["memory_id"])
+                for row in rows
+                if isinstance(row, dict) and row.get("memory_id")
+            )
+            offset += len(rows)
+            if not rows or offset >= total:
+                break
+
+    def readable(memory_id: str) -> bool:
+        return memory_id in listed or client.get(memory_id) is not None
+
+    return ReadbackReport(
+        chat_expected=len(legacy.chat),
+        chat_readable=sum(1 for memory_id in legacy.chat if readable(memory_id)),
+        productivity_expected=len(legacy.productivity),
+        productivity_readable=sum(1 for memory_id in legacy.productivity if readable(memory_id)),
+    )
+

memhub/apps/core/src/one_memory/sdk_vector_reattach.py

@@ -0,0 +1,165 @@
+"""Offline reattachment of SDK vector collections named by builds before #145.
+
+Those builds named a profile's embedding space `one_memory_<12 hex>`; #145
+renamed it `memhub_<16 hex>` and dropped the step that carried the old
+collections over, so every later Runtime opened an empty space beside the old
+one. Runtime code only reaches vectors through the SDK. This module runs from
+`sdk-migrate` while the Runtime is stopped, through Chroma's public client.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from collections.abc import Iterator
+from contextlib import closing
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from one_memory.hy_sdk_runtime import vector_collection_bases
+from one_memory.model_profiles import ModelProfileSnapshot
+from one_memory.sdk_data_plane_migration import DataPlaneMigrationError
+
+_BATCH = 500
+
+
+def open_offline_chroma(directory: Path) -> Any:
+    """A Chroma client on the SDK's vector store, configured as the SDK opens it.
+
+    Chroma refuses a second client on a directory whose shared instance was
+    created with different settings, so offline code must not pass its own.
+    Telemetry is turned off the way the Runtime turns it off, by environment.
+    """
+    import os
+
+    import chromadb
+
+    os.environ["ANONYMIZED_TELEMETRY"] = "False"
+    return chromadb.PersistentClient(path=str(directory))
+
+
+@dataclass(frozen=True)
+class ReattachedCollection:
+    legacy: str
+    current: str
+    legacy_count: int
+    merged_count: int
+    final_count: int
+
+
+def _vector_directory(data_dir: Path) -> Path:
+    return data_dir / "hy-memory" / "governed-v2" / "vector"
+
+
+def _stored_names(data_dir: Path) -> tuple[str, ...]:
+    database = _vector_directory(data_dir) / "chroma.sqlite3"
+    if not database.is_file():
+        return ()
+    with closing(sqlite3.connect(f"file:{database}?mode=ro", uri=True)) as connection:
+        try:
+            rows = connection.execute("SELECT name FROM collections").fetchall()
+        except sqlite3.Error:
+            return ()
+    return tuple(sorted(str(row[0]) for row in rows))
+
+
+def legacy_vector_collections(
+    data_dir: Path, profile: ModelProfileSnapshot
+) -> tuple[tuple[str, str], ...]:
+    """(legacy name, current name) pairs still waiting to be reattached.
+
+    Read-only, so `sdk-migration-status` can ask it.
+    """
+    current, legacy_bases = vector_collection_bases(profile)
+    pairs: list[tuple[str, str]] = []
+    for name in _stored_names(data_dir):
+        for base in legacy_bases:
+            if name == base or name.startswith(f"{base}_"):
+                pairs.append((name, current + name[len(base) :]))
+                break
+    return tuple(pairs)
+
+
+def _records(collection: Any) -> Iterator[dict[str, Any]]:
+    offset = 0
+    while True:
+        page = collection.get(
+            include=["embeddings", "documents", "metadatas"],
+            limit=_BATCH,
+            offset=offset,
+        )
+        ids = list(page["ids"])
+        if not ids:
+            return
+        yield {
+            "ids": ids,
+            "embeddings": page["embeddings"],
+            "documents": page["documents"],
+            "metadatas": page["metadatas"],
+        }
+        offset += len(ids)
+
+
+def reattach_legacy_vectors(
+    data_dir: Path, profile: ModelProfileSnapshot
+) -> tuple[ReattachedCollection, ...]:
+    """Rename legacy collections to the current names, keeping newer writes.
+
+    A current collection that already exists (written after the rename broke)
+    is merged into the legacy one first; on an id present in both, the newer
+    current record wins. Callers must have stopped every SDK writer.
+    """
+    pairs = legacy_vector_collections(data_dir, profile)
+    if not pairs:
+        return ()
+    client = open_offline_chroma(_vector_directory(data_dir))
+    # Closed, not left to the process: Chroma keeps one shared instance per
+    # directory, and the readback that follows opens the same directory
+    # through the SDK. A leaked instance failed that open on every 1.0.4 home
+    # with legacy vectors, so the first launch after upgrade always failed.
+    try:
+        existing = set(_stored_names(data_dir))
+        done: list[ReattachedCollection] = []
+        for legacy_name, current_name in pairs:
+            legacy = client.get_collection(legacy_name)
+            legacy_count = legacy.count()
+            merged = 0
+            if current_name in existing:
+                current = client.get_collection(current_name)
+                legacy_ids = set(_ids(legacy))
+                current_ids: set[str] = set()
+                for batch in _records(current):
+                    legacy.upsert(**batch)
+                    current_ids.update(batch["ids"])
+                merged = len(current_ids)
+                if legacy.count() != len(legacy_ids | current_ids):
+                    raise DataPlaneMigrationError("sdk_migration_vector_merge_incomplete")
+                client.delete_collection(current_name)
+            legacy.modify(name=current_name)
+            final = client.get_collection(current_name).count()
+            if final < legacy_count:
+                raise DataPlaneMigrationError("sdk_migration_vector_reattach_incomplete")
+            existing.discard(legacy_name)
+            existing.add(current_name)
+            done.append(
+                ReattachedCollection(
+                    legacy=legacy_name,
+                    current=current_name,
+                    legacy_count=legacy_count,
+                    merged_count=merged,
+                    final_count=final,
+                )
+            )
+    finally:
+        client.close()
+    return tuple(done)
+
+
+def _ids(collection: Any) -> Iterator[str]:
+    offset = 0
+    while True:
+        ids = list(collection.get(include=[], limit=_BATCH, offset=offset)["ids"])
+        if not ids:
+            return
+        yield from ids
+        offset += len(ids)

memhub/apps/core/src/one_memory/session_inbox.py

@@ -1,518 +0,0 @@
-"""Per-session incremental read. A pull or an ack is not adoption."""
-
-import json
-import secrets
-import sqlite3
-from collections.abc import Iterator
-from contextlib import contextmanager
-from dataclasses import dataclass
-from pathlib import Path
-
-#: Schema owned by `memory_server.migrations` (migration 11). No local copy.
-from one_memory.change_outbox import evidence_event_id
-from one_memory.database_access import main_database
-from one_memory.derived_echo import echoed_event_ids, is_pure_echo
-from one_memory.memory_server.migrations import session_inbox_ddl
-from one_memory.session_registry import SessionRegistry
-
-_SCHEMA = session_inbox_ddl("sqlite")
-
-
-class CursorRejected(Exception):
-    pass
-
-
-@dataclass(frozen=True)
-class InboxEvent:
-    event_id: str
-    evidence_id: str | None
-    evidence_revision: int | None
-    source_id: str | None
-
-
-@dataclass(frozen=True)
-class InboxPage:
-    batch_id: str
-    cursor: str
-    state: str
-    adoption: str
-    events: tuple[InboxEvent, ...]
-
-
-@dataclass(frozen=True)
-class InboxPosition:
-    """Where a cursor would stand once the events handed over are confirmed."""
-
-    event_id: str | None
-    permission_epoch: int
-    handed_event_ids: frozenset[str] = frozenset()
-    receipt_id: str | None = None
-
-
-@dataclass(frozen=True)
-class InboxPeek:
-    events: tuple[InboxEvent, ...]
-    position: InboxPosition
-
-
-@dataclass(frozen=True)
-class InboxAck:
-    batch_id: str
-    state: str
-    adoption: str
-
-
-@dataclass(frozen=True)
-class InboxSignal:
-    signal_id: str
-
-
-class SessionInbox:
-    def __init__(self, database_path: Path) -> None:
-        self._path = database_path
-        self._registry = SessionRegistry(database_path)
-
-    def initialize(self) -> None:
-        with main_database(self._path).write() as db, db:
-            db.executescript(_SCHEMA)
-
-    def subscribe(
-        self,
-        session_key: str,
-        sources: tuple[str, ...],
-        permission_epoch: int,
-    ) -> None:
-        self._registry.require(session_key)
-        with main_database(self._path).write() as db, db:
-            db.execute(
-                """
-                INSERT INTO session_subscriptions (
-                    session_key, granted_sources, permission_epoch
-                ) VALUES (?, ?, ?)
-                ON CONFLICT(session_key) DO UPDATE SET
-                    granted_sources = excluded.granted_sources,
-                    permission_epoch = excluded.permission_epoch
-                """,
-                (session_key, json.dumps(list(sources)), permission_epoch),
-            )
-
-    def pull(self, session_key: str, cursor: str | None, limit: int) -> InboxPage:
-        self._registry.require(session_key)
-        with self._snapshot() as db:
-            start_after, epoch = self._cursor_position(session_key, cursor, db)
-            granted = self._granted(session_key, db)
-            events = self._without_host_echo(self._events(db), db)
-            current = self._epoch(session_key, db)
-        selected, found = self._scan(granted, start_after, limit, events)
-        state = "delivered"
-        # A cursor whose event is gone, or whose permission epoch no longer
-        # matches, must not look like "nothing new". Rebuild from the start.
-        if cursor is not None and (not found or epoch != current):
-            selected, _found = self._scan(granted, None, limit, events)
-            state = "resync-required"
-            epoch = current
-        if selected:
-            scanned_id = selected[-1].event_id
-        elif state == "resync-required":
-            scanned_id = None
-        else:
-            scanned_id = start_after
-        return self._store_page(session_key, scanned_id, epoch, state, selected)
-
-    def peek(self, session_key: str, limit: int) -> InboxPeek:
-        """What the next pull from the latest cursor would return, without moving it."""
-
-        self._registry.require(session_key)
-        # Grants, epoch and events are read in one snapshot: a revoke landing
-        # between them would pair the old grants with the new epoch.
-        with self._snapshot() as db:
-            cursor = self._latest_cursor(session_key, db)
-            start_after, epoch = self._cursor_position(session_key, cursor, db)
-            granted = self._granted(session_key, db)
-            events = self._without_host_echo(self._events(db), db)
-            current = self._epoch(session_key, db)
-        selected, found = self._scan(granted, start_after, limit, events)
-        if cursor is not None and (not found or epoch != current):
-            selected, _found = self._scan(granted, None, limit, events)
-            start_after = None
-        end = selected[-1].event_id if selected else start_after
-        receipt_id = None
-        if selected:
-            receipt_id = secrets.token_hex(16)
-            receipt = self._new_receipt(
-                session_key,
-                position_event_id=str(end),
-                permission_epoch=current,
-                handed_event_ids=tuple(event.event_id for event in selected),
-            )
-            with main_database(self._path).write() as db, db:
-                db.execute(
-                    """
-                    INSERT INTO session_snapshots (
-                        snapshot_token, session_key, frozen_ids
-                    )
-                    VALUES (?, ?, ?)
-                    """,
-                    (receipt_id, session_key, receipt),
-                )
-        return InboxPeek(
-            tuple(selected),
-            InboxPosition(
-                end,
-                current,
-                frozenset(event.event_id for event in selected),
-                receipt_id,
-            ),
-        )
-
-    @staticmethod
-    def _new_receipt(
-        session_key: str,
-        *,
-        position_event_id: str,
-        permission_epoch: int,
-        handed_event_ids: tuple[str, ...],
-    ) -> str:
-        return json.dumps(
-            {
-                "kind": "peek",
-                "session_key": session_key,
-                "event_id": position_event_id,
-                "permission_epoch": permission_epoch,
-                "handed_event_ids": list(handed_event_ids),
-            },
-            separators=(",", ":"),
-        )
-
-    def advance_to(self, session_key: str, position: InboxPosition) -> bool | None:
-        """Move the latest cursor forward to a peeked position, never back.
-
-        Two rounds may peek overlapping pages and confirm in either order. The
-        cursor only ever moves to the furthest position actually handed over.
-        """
-
-        self._registry.require(session_key)
-        if position.event_id is None:
-            return False
-        if position.receipt_id is None:
-            raise CursorRejected("missing_peek_receipt")
-        # IMMEDIATE takes the file's write lock at once: the confirming process
-        # is not the one that peeked, so the in-process writer queue is not enough.
-        with main_database(self._path).write() as db, db:
-            db.execute("BEGIN IMMEDIATE")
-            events = self._without_host_echo(self._events(db), db)
-            order = [event.event_id for event in events]
-            by_id = {event.event_id: event for event in events}
-            receipt = self._peek_receipt(session_key, position, db)
-            row = db.execute(
-                "SELECT permission_epoch FROM session_subscriptions WHERE session_key = ?",
-                (session_key,),
-            ).fetchone()
-            epoch = int(row[0]) if row is not None else 0
-            handed = receipt
-            if any(event_id not in order for event_id in handed):
-                raise CursorRejected("handed_event_missing")
-            granted = self._granted(session_key, db)
-            target = by_id.get(position.event_id)
-            if target is None or target.source_id not in granted:
-                raise CursorRejected("target_not_selectable")
-            if any(by_id[event_id].source_id not in granted for event_id in handed):
-                raise CursorRejected("handed_event_not_selectable")
-            if position.permission_epoch != epoch:
-                return None
-            latest_token = self._latest_cursor(session_key, db)
-            cursor_position = -1
-            if latest_token is not None:
-                start_after, _cursor_epoch = self._cursor_position(session_key, latest_token, db)
-                if start_after in order:
-                    cursor_position = order.index(str(start_after))
-            target_position = order.index(position.event_id)
-            if cursor_position >= target_position:
-                return None
-            required = [
-                event.event_id
-                for event in events[cursor_position + 1 : target_position + 1]
-                if event.source_id in granted
-            ]
-            handed_after_cursor = [
-                event_id for event_id in handed if order.index(event_id) > cursor_position
-            ]
-            if handed_after_cursor != required:
-                raise CursorRejected("incomplete_handed_range")
-            latest = db.execute(
-                """
-                SELECT scanned_event_id, permission_epoch FROM session_inbox_cursors
-                WHERE session_key = ? ORDER BY rowid DESC LIMIT 1
-                """,
-                (session_key,),
-            ).fetchone()
-            if (
-                latest is not None
-                and int(latest[1]) == epoch
-                and latest[0] in order
-                and order.index(latest[0]) > order.index(position.event_id)
-            ):
-                return None
-            db.execute(
-                """
-                INSERT INTO session_inbox_cursors (
-                    cursor_token, session_key, scanned_event_id, permission_epoch
-                ) VALUES (?, ?, ?, ?)
-                """,
-                (secrets.token_hex(32), session_key, position.event_id, epoch),
-            )
-        return True
-
-    @staticmethod
-    def _peek_receipt(
-        session_key: str, position: InboxPosition, db: sqlite3.Connection
-    ) -> tuple[str, ...]:
-        row = db.execute(
-            """
-            SELECT frozen_ids FROM session_snapshots
-            WHERE snapshot_token = ? AND session_key = ?
-            """,
-            (position.receipt_id, session_key),
-        ).fetchone()
-        if row is None:
-            raise CursorRejected("invalid_peek_receipt")
-        try:
-            receipt = json.loads(str(row[0]))
-        except json.JSONDecodeError as error:
-            raise CursorRejected("invalid_peek_receipt") from error
-        if not isinstance(receipt, dict) or receipt.get("kind") != "peek":
-            raise CursorRejected("invalid_peek_receipt")
-        if receipt.get("session_key") != session_key:
-            raise CursorRejected("peek_receipt_session_mismatch")
-        if receipt.get("event_id") != position.event_id:
-            raise CursorRejected("peek_receipt_target_mismatch")
-        if receipt.get("permission_epoch") != position.permission_epoch:
-            raise CursorRejected("peek_receipt_epoch_mismatch")
-        handed = receipt.get("handed_event_ids")
-        if not isinstance(handed, list) or any(not isinstance(item, str) for item in handed):
-            raise CursorRejected("invalid_peek_receipt")
-        loaded = tuple(handed)
-        if frozenset(loaded) != position.handed_event_ids:
-            raise CursorRejected("peek_receipt_handed_mismatch")
-        return loaded
-
-    def latest_cursor(self, session_key: str) -> str | None:
-        self._registry.require(session_key)
-        with main_database(self._path).read() as db:
-            return self._latest_cursor(session_key, db)
-
-    @staticmethod
-    def _latest_cursor(session_key: str, db: sqlite3.Connection) -> str | None:
-        row = db.execute(
-            """
-            SELECT cursor_token FROM session_inbox_cursors
-            WHERE session_key = ? ORDER BY rowid DESC LIMIT 1
-            """,
-            (session_key,),
-        ).fetchone()
-        return None if row is None else str(row[0])
-
-    @contextmanager
-    def _snapshot(self) -> Iterator[sqlite3.Connection]:
-        """One read transaction; under WAL every read in it sees the same state."""
-
-        # A pooled reader does not open a transaction for a SELECT on its own;
-        # the transaction is rolled back when the connection is handed back.
-        with main_database(self._path).read() as db:
-            db.execute("BEGIN")
-            yield db
-
-    def ack(self, session_key: str, batch_id: str) -> InboxAck:
-        self._registry.require(session_key)
-        with main_database(self._path).write() as db, db:
-            row = db.execute(
-                "SELECT session_key FROM session_inbox_batches WHERE batch_id = ?",
-                (batch_id,),
-            ).fetchone()
-            if row is None or row[0] != session_key:
-                raise CursorRejected(batch_id)
-            db.execute(
-                """
-                UPDATE session_inbox_batches SET state = 'acknowledged'
-                WHERE batch_id = ?
-                """,
-                (batch_id,),
-            )
-        return InboxAck(batch_id, "acknowledged", "unknown")
-
-    def begin_snapshot(self, session_key: str) -> str:
-        self._registry.require(session_key)
-        frozen = json.dumps([event.event_id for event in self._events()])
-        token = secrets.token_hex(16)
-        with main_database(self._path).write() as db, db:
-            db.execute(
-                """
-                INSERT INTO session_snapshots (snapshot_token, session_key, frozen_ids)
-                VALUES (?, ?, ?)
-                """,
-                (token, session_key, frozen),
-            )
-        return token
-
-    def finish_snapshot(self, session_key: str, token: str) -> InboxPage:
-        self._registry.require(session_key)
-        with main_database(self._path).read() as db:
-            db.row_factory = sqlite3.Row
-            row = db.execute(
-                "SELECT session_key FROM session_snapshots WHERE snapshot_token = ?",
-                (token,),
-            ).fetchone()
-        if row is None or row["session_key"] != session_key:
-            raise CursorRejected(token)
-        # Events committed before finish belong in this page. The cursor stops
-        # at the last event actually returned, so a late insert is not skipped.
-        return self.pull(session_key, cursor=None, limit=128)
-
-    def signal(self, session_key: str) -> InboxSignal:
-        self._registry.require(session_key)
-        return InboxSignal(secrets.token_hex(16))
-
-    def _cursor_position(
-        self, session_key: str, cursor: str | None, db: sqlite3.Connection
-    ) -> tuple[str | None, int]:
-        if cursor is None:
-            return None, self._epoch(session_key, db)
-        row = db.execute(
-            """
-            SELECT session_key, scanned_event_id, permission_epoch
-            FROM session_inbox_cursors WHERE cursor_token = ?
-            """,
-            (cursor,),
-        ).fetchone()
-        if row is None or row[0] != session_key:
-            raise CursorRejected(cursor)
-        return row[1], int(row[2])
-
-    @staticmethod
-    def _scan(
-        granted: set[str],
-        start_after: str | None,
-        limit: int,
-        events: tuple[InboxEvent, ...],
-    ) -> tuple[list[InboxEvent], bool]:
-        found = start_after is None
-        selected: list[InboxEvent] = []
-        for event in events:
-            if not found:
-                if event.event_id == start_after:
-                    found = True
-                continue
-            if event.source_id not in granted:
-                continue
-            if len(selected) >= limit:
-                break
-            selected.append(event)
-        return selected, found
-
-    def _store_page(
-        self,
-        session_key: str,
-        scanned_id: str | None,
-        epoch: int,
-        state: str,
-        selected: list[InboxEvent],
-    ) -> InboxPage:
-        token = secrets.token_hex(32)
-        batch_id = secrets.token_hex(16)
-        with main_database(self._path).write() as db, db:
-            db.execute(
-                """
-                INSERT INTO session_inbox_cursors (
-                    cursor_token, session_key, scanned_event_id, permission_epoch
-                ) VALUES (?, ?, ?, ?)
-                """,
-                (token, session_key, scanned_id, epoch),
-            )
-            db.execute(
-                """
-                INSERT INTO session_inbox_batches (batch_id, session_key, state)
-                VALUES (?, ?, ?)
-                """,
-                (batch_id, session_key, state),
-            )
-        return InboxPage(batch_id, token, state, "unknown", tuple(selected))
-
-    @staticmethod
-    def _epoch(session_key: str, db: sqlite3.Connection) -> int:
-        row = db.execute(
-            "SELECT permission_epoch FROM session_subscriptions WHERE session_key = ?",
-            (session_key,),
-        ).fetchone()
-        return int(row[0]) if row is not None else 0
-
-    @staticmethod
-    def _granted(session_key: str, db: sqlite3.Connection) -> set[str]:
-        row = db.execute(
-            "SELECT granted_sources FROM session_subscriptions WHERE session_key = ?",
-            (session_key,),
-        ).fetchone()
-        if row is None:
-            return set()
-        loaded = json.loads(row[0])
-        return set(loaded) if isinstance(loaded, list) else set()
-
-    def _events(self, db: sqlite3.Connection | None = None) -> tuple[InboxEvent, ...]:
-        if db is None:
-            with main_database(self._path).read() as own:
-                return self._events(own)
-        events: dict[str, tuple[str, InboxEvent]] = {}
-        for evidence_id, revision, source_id, created_at in db.execute(
-            "SELECT evidence_id, revision, source_id, updated_at FROM evidence"
-        ):
-            event_id = evidence_event_id(str(evidence_id), int(revision))
-            events[event_id] = (
-                str(created_at),
-                InboxEvent(event_id, str(evidence_id), int(revision), str(source_id)),
-            )
-        for (
-            event_id,
-            evidence_id,
-            revision,
-            source_id,
-            created_at,
-        ) in db.execute(
-            """
-            SELECT o.event_id, o.evidence_id, o.evidence_revision, e.source_id, o.created_at
-            FROM change_outbox o
-            LEFT JOIN evidence e ON e.evidence_id = o.evidence_id
-            """
-        ):
-            events.setdefault(
-                str(event_id),
-                (str(created_at), InboxEvent(str(event_id), evidence_id, revision, source_id)),
-            )
-        return tuple(
-            event
-            for _occurred_at, event in sorted(
-                events.values(), key=lambda item: (item[0], item[1].event_id)
-            )
-        )
-
-    @staticmethod
-    def _without_host_echo(
-        events: tuple[InboxEvent, ...], db: sqlite3.Connection
-    ) -> tuple[InboxEvent, ...]:
-        """The host can save our notice back; that is not a new decision."""
-
-        known = {event.event_id for event in events}
-        delivered: set[str] = set()
-        kept: list[InboxEvent] = []
-        for event in events:
-            if event.evidence_id is None:
-                kept.append(event)
-                continue
-            row = db.execute(
-                "SELECT verbatim FROM evidence WHERE evidence_id = ?",
-                (event.evidence_id,),
-            ).fetchone()
-            verbatim = "" if row is None else str(row[0])
-            if is_pure_echo(verbatim, known):
-                delivered.update(echoed_event_ids(verbatim))
-                continue
-            kept.append(event)
-        return tuple(event for event in kept if event.event_id not in delivered)

memhub/apps/core/src/one_memory/session_lease.py

@@ -1,140 +0,0 @@
-"""Online means an unexpired lease, not a session file that is still on disk."""
-
-import sqlite3
-from collections.abc import Iterator
-from contextlib import contextmanager
-from datetime import datetime, timedelta
-from pathlib import Path
-from typing import Any
-
-from one_memory.database_access import main_database
-
-#: Schema owned by `memory_server.migrations` (migration 5). No local copy,
-#: so the migration cannot drift from what this module actually creates.
-from one_memory.memory_server.migrations import session_leases_ddl
-from one_memory.memory_server.sql_compat import (
-    execute,
-    execute_script,
-    is_mysql,
-    row_to_dict,
-)
-from one_memory.memory_server.store_binding import store_for
-from one_memory.session_registry import SessionRegistry
-
-#: Both renderings, chosen at use time (same reason as every migrated module:
-#: the sqlite rendering carries SQLite types and index forms MySQL rejects).
-SCHEMA_BY_ENGINE = {False: session_leases_ddl("sqlite"), True: session_leases_ddl("mysql")}
-
-
-def schema_for(mysql: bool) -> str:
-    return SCHEMA_BY_ENGINE[mysql]
-
-
-#: The heartbeat upsert, per engine.
-#:
-#: `ON CONFLICT ... DO UPDATE` (SQLite) vs `ON DUPLICATE KEY UPDATE` (MySQL).
-#: Wrong either way and a session's lease silently keeps its old expiry, which
-#: reads as "session went offline" rather than as a database error.
-BEAT_SQLITE = """
-    INSERT INTO session_leases (session_key, pid, generation, expires_at)
-    VALUES (?, ?, ?, ?)
-    ON CONFLICT(session_key) DO UPDATE SET
-        pid = excluded.pid,
-        generation = excluded.generation,
-        expires_at = excluded.expires_at
-"""
-BEAT_MYSQL = """
-    INSERT INTO session_leases (session_key, pid, generation, expires_at)
-    VALUES (%s, %s, %s, %s)
-    ON DUPLICATE KEY UPDATE
-        pid = VALUES(pid),
-        generation = VALUES(generation),
-        expires_at = VALUES(expires_at)
-"""
-SELECT_SQLITE = "SELECT generation, expires_at FROM session_leases WHERE session_key = ?"
-SELECT_MYSQL = "SELECT generation, expires_at FROM session_leases WHERE session_key = %s"
-
-
-class SessionLease:
-    def __init__(self, database_path: Path) -> None:
-        self._path = database_path
-        self._store: Any = store_for(database_path)
-        self._registry = SessionRegistry(database_path)
-
-    def initialize(self) -> None:
-        mysql = is_mysql(self._store)
-        with self._connect(writing=True) as db:
-            execute_script(db, mysql, schema_for(mysql))
-
-    def beat(
-        self,
-        session_key: str,
-        *,
-        pid: int,
-        generation: int,
-        now: datetime,
-        ttl_seconds: int,
-    ) -> None:
-        self._registry.require(session_key)
-        expires = (now + timedelta(seconds=ttl_seconds)).isoformat()
-        mysql = is_mysql(self._store)
-        with self._connect(writing=True) as db:
-            execute(
-                db,
-                mysql,
-                BEAT_MYSQL if mysql else BEAT_SQLITE,
-                (session_key, pid, generation, expires),
-            )
-
-    def online(
-        self,
-        session_key: str,
-        *,
-        now: datetime,
-        generation: int,
-        source_file: Path | None = None,
-    ) -> bool:
-        del source_file
-        self._registry.require(session_key)
-        mysql = is_mysql(self._store)
-        with self._connect() as db:
-            row = execute(
-                db, mysql, SELECT_MYSQL if mysql else SELECT_SQLITE, (session_key,)
-            ).fetchone()
-        if row is None:
-            return False
-        # Named access only works on `sqlite3.Row`; MySQL gives a tuple, so the
-        # row is normalised to a mapping on both engines first.
-        values = row_to_dict(row, ("generation", "expires_at"), mysql)
-        if int(values["generation"]) != generation:
-            return False
-        return now < _as_datetime(values["expires_at"], now)
-
-    @contextmanager
-    def _connect(self, *, writing: bool = False) -> Iterator[Any]:
-        """A checkout on whichever engine is in force."""
-        if is_mysql(self._store):
-            checkout = self._store.write() if writing else self._store.read()
-            with checkout as connection:
-                yield connection
-            return
-        database = main_database(self._path)
-        checkout = database.write() if writing else database.read(row_factory=sqlite3.Row)
-        with checkout as connection, connection:
-            yield connection
-
-
-def _as_datetime(value: object, reference: datetime) -> datetime:
-    """Parse the stored expiry, matching the caller's awareness.
-
-    SQLite returns the stored ISO string so it parses aware. MySQL `DATETIME`
-    returns a naive `datetime`, and comparing that with an aware `now` raises
-    `TypeError` — a crash on a perfectly ordinary read. The stored value is the
-    same instant, so the zone is taken from the caller's clock rather than
-    assumed, which keeps the comparison meaningful either way.
-    """
-    if isinstance(value, datetime):
-        if value.tzinfo is None and reference.tzinfo is not None:
-            return value.replace(tzinfo=reference.tzinfo)
-        return value
-    return datetime.fromisoformat(str(value))

memhub/apps/core/src/one_memory/session_registry.py

@@ -1,137 +0,0 @@
-"""Trusted host sessions. A directory is a relevance hint, not an identity."""
-
-import hashlib
-import sqlite3
-from dataclasses import dataclass
-from pathlib import Path
-
-from one_memory.call_event_store import HostId
-from one_memory.database_access import main_database
-
-#: Schema owned by `memory_server.migrations` (migration 6). No local copy,
-#: so the migration cannot drift from what this module actually creates.
-from one_memory.memory_server.migrations import trusted_sessions_ddl
-
-_SCHEMA = trusted_sessions_ddl("sqlite")
-
-
-class SessionIdentityError(Exception):
-    pass
-
-
-class AmbiguousWorkspace(SessionIdentityError):
-    pass
-
-
-class ForgedSession(SessionIdentityError):
-    pass
-
-
-@dataclass(frozen=True)
-class TrustedSession:
-    session_key: str
-    installation_id: str
-    host_id: HostId
-    native_session_id: str
-    runtime_instance: str
-    workspace: str | None
-
-
-class SessionRegistry:
-    def __init__(self, database_path: Path) -> None:
-        self._path = database_path
-
-    def initialize(self) -> None:
-        with main_database(self._path).write() as db, db:
-            db.execute(_SCHEMA)
-
-    def open(
-        self,
-        *,
-        installation_id: str,
-        host_id: HostId,
-        native_session_id: str,
-        runtime_instance: str,
-        workspace: str | None,
-    ) -> TrustedSession:
-        if not installation_id or not native_session_id or not runtime_instance:
-            raise SessionIdentityError("incomplete_session")
-        key = _identity_key(installation_id, host_id, native_session_id, runtime_instance)
-        with main_database(self._path).write() as db, db:
-            row = db.execute(
-                "SELECT session_key FROM trusted_sessions WHERE session_key = ?",
-                (key,),
-            ).fetchone()
-            if row is None:
-                db.execute(
-                    """
-                    INSERT INTO trusted_sessions (
-                        session_key, installation_id, host_id, native_session_id,
-                        runtime_instance, workspace
-                    ) VALUES (?, ?, ?, ?, ?, ?)
-                    """,
-                    (key, installation_id, host_id, native_session_id, runtime_instance, workspace),
-                )
-        return self.require(key)
-
-    def require(self, session_key: str) -> TrustedSession:
-        with main_database(self._path).read() as db:
-            db.row_factory = sqlite3.Row
-            row = db.execute(
-                "SELECT * FROM trusted_sessions WHERE session_key = ?",
-                (session_key,),
-            ).fetchone()
-        if row is None:
-            raise ForgedSession(session_key)
-        return _session(row)
-
-    def in_workspace(self, workspace: str) -> tuple[TrustedSession, ...]:
-        with main_database(self._path).read() as db:
-            db.row_factory = sqlite3.Row
-            rows = db.execute(
-                "SELECT * FROM trusted_sessions WHERE workspace = ? ORDER BY session_key",
-                (workspace,),
-            ).fetchall()
-        return tuple(_session(row) for row in rows)
-
-    def matching_native(
-        self, host_id: HostId, native_session_id: str
-    ) -> tuple[TrustedSession, ...]:
-        with main_database(self._path).read() as db:
-            db.row_factory = sqlite3.Row
-            rows = db.execute(
-                """
-                SELECT * FROM trusted_sessions
-                WHERE host_id = ? AND native_session_id = ?
-                ORDER BY session_key
-                """,
-                (host_id, native_session_id),
-            ).fetchall()
-        return tuple(_session(row) for row in rows)
-
-    def sole_session(self, workspace: str) -> TrustedSession:
-        found = self.in_workspace(workspace)
-        if len(found) == 1:
-            return found[0]
-        raise AmbiguousWorkspace(workspace)
-
-
-def _identity_key(
-    installation_id: str,
-    host_id: str,
-    native_session_id: str,
-    runtime_instance: str,
-) -> str:
-    material = "\n".join((installation_id, host_id, native_session_id, runtime_instance))
-    return hashlib.sha256(material.encode()).hexdigest()
-
-
-def _session(row: sqlite3.Row) -> TrustedSession:
-    return TrustedSession(
-        session_key=row["session_key"],
-        installation_id=row["installation_id"],
-        host_id=row["host_id"],
-        native_session_id=row["native_session_id"],
-        runtime_instance=row["runtime_instance"],
-        workspace=row["workspace"],
-    )

memhub/apps/core/src/one_memory/workbuddy_boundary.py

@@ -1,180 +0,0 @@
-"""WorkBuddy SessionStart and UserPromptSubmit. No idle turn is started.
-
-The notice stream is the current Evidence revision projection in
-`SessionInbox`; `change_outbox` is retained there only as a legacy event source.
-"""
-
-import base64
-import binascii
-import json
-import sqlite3
-from pathlib import Path
-from typing import TextIO
-
-from one_memory.derived_echo import render_reference
-from one_memory.session_inbox import CursorRejected, InboxPosition, SessionInbox
-from one_memory.session_registry import SessionIdentityError, SessionRegistry
-
-BOUNDARY_EVENTS = frozenset({"SessionStart", "UserPromptSubmit"})
-
-
-def database_path() -> Path:
-    from one_memory.config import load_settings
-
-    return load_settings().data_dir / "one-memory.sqlite3"
-
-
-PAGE_LIMIT = 8
-
-
-def _boundary_session(payload: object, database: Path) -> tuple[str, str] | None:
-    """The hook event and the one trusted session it belongs to.
-
-    Identity is the payload's own session id. A parent id is not a substitute.
-    More than one matching trusted session is ambiguous, so nothing is injected.
-    """
-
-    if not isinstance(payload, dict):
-        return None
-    event = payload.get("hook_event_name") or payload.get("hookEventName")
-    if event not in BOUNDARY_EVENTS:
-        return None
-    native = payload.get("session_id") or payload.get("sessionId")
-    if not isinstance(native, str) or not native or not database.is_file():
-        return None
-    matches = SessionRegistry(database).matching_native("workbuddy", native)
-    if len(matches) != 1:
-        return None
-    return str(event), matches[0].session_key
-
-
-def hook_output(payload: object, database: Path) -> dict[str, object]:
-    """The JSON WorkBuddy reads on the next session or prompt boundary.
-
-    Reading moves the cursor, so a notice lost before it reaches the host is
-    not sent again. Kept for installs whose hook predates `--peek`.
-    """
-
-    silent: dict[str, object] = {"continue": True}
-    found = _boundary_session(payload, database)
-    if found is None:
-        return silent
-    event, session_key = found
-    inbox = SessionInbox(database)
-    page = inbox.pull(session_key, inbox.latest_cursor(session_key), PAGE_LIMIT)
-    if not page.events:
-        return silent
-    return {
-        "continue": True,
-        "hookSpecificOutput": {
-            "hookEventName": event,
-            "additionalContext": render_reference(page.events),
-        },
-    }
-
-
-def peek_output(payload: object, database: Path) -> dict[str, object]:
-    """The same notice without moving the cursor, plus the token that confirms it.
-
-    Until `confirm` receives the token the notice is sent again next round.
-    """
-
-    found = _boundary_session(payload, database)
-    if found is None:
-        return {}
-    event, session_key = found
-    peeked = SessionInbox(database).peek(session_key, PAGE_LIMIT)
-    if not peeked.events:
-        return {}
-    return {
-        "hookSpecificOutput": {
-            "hookEventName": event,
-            "additionalContext": render_reference(peeked.events),
-        },
-        "one_memory_ack": _token(session_key, peeked.position),
-    }
-
-
-def confirm(token: str, database: Path) -> bool | None:
-    """Move the session's cursor up to what the token's peek handed over.
-
-    Raises ValueError for a token this module did not issue.
-    """
-
-    session_key, position = _untoken(token)
-    return SessionInbox(database).advance_to(session_key, position)
-
-
-def _token(session_key: str, position: InboxPosition) -> str:
-    body = json.dumps(
-        {
-            "s": session_key,
-            "e": position.event_id,
-            "p": position.permission_epoch,
-            "h": sorted(position.handed_event_ids),
-            "r": position.receipt_id,
-        },
-        separators=(",", ":"),
-    )
-    return base64.urlsafe_b64encode(body.encode()).decode().rstrip("=")
-
-
-def _untoken(token: str) -> tuple[str, InboxPosition]:
-    try:
-        raw = base64.urlsafe_b64decode(token + "=" * (-len(token) % 4))
-        body = json.loads(raw)
-    except (binascii.Error, ValueError) as error:
-        raise ValueError("not a boundary token") from error
-    if not isinstance(body, dict):
-        raise ValueError("not a boundary token")
-    session_key, event_id, epoch, handed, receipt_id = (
-        body.get("s"),
-        body.get("e"),
-        body.get("p"),
-        body.get("h", []),
-        body.get("r"),
-    )
-    if not isinstance(session_key, str) or not isinstance(event_id, str):
-        raise ValueError("not a boundary token")
-    if not isinstance(epoch, int) or isinstance(epoch, bool):
-        raise ValueError("not a boundary token")
-    if not isinstance(handed, list) or any(not isinstance(item, str) for item in handed):
-        raise ValueError("not a boundary token")
-    if not isinstance(receipt_id, str) or not receipt_id:
-        raise ValueError("not a boundary token")
-    return session_key, InboxPosition(event_id, epoch, frozenset(handed), receipt_id)
-
-
-def _payload(stdin: TextIO) -> object:
-    try:
-        return json.loads(stdin.read() or "{}")
-    except json.JSONDecodeError:
-        return {}
-
-
-def write_hook(stream: TextIO, stdin: TextIO) -> int:
-    """Print the reply only when it carries a notice.
-
-    WorkBuddy reads stdout without `hookSpecificOutput` as context text, so a
-    bare `{"continue": true}` would reach the model. Empty stdout also continues.
-    """
-
-    body = hook_output(_payload(stdin), database_path())
-    if "hookSpecificOutput" in body:
-        stream.write(f"{json.dumps(body, ensure_ascii=False)}\n")
-    return 0
-
-
-def write_peek(stream: TextIO, stdin: TextIO) -> int:
-    body = peek_output(_payload(stdin), database_path())
-    if body:
-        stream.write(f"{json.dumps(body, ensure_ascii=False)}\n")
-    return 0
-
-
-def run_confirm(token: str) -> int:
-    try:
-        confirm(token, database_path())
-    except (ValueError, CursorRejected, SessionIdentityError, sqlite3.Error):
-        return 1
-    return 0

memhub/apps/core/tests/TEST_INDEX.md

@@ -63,17 +63,15 @@
 | `test_context_memory.py` | `contract` | 覆盖 permissions precede candidate limit and do not leak counts、scope user status and active source isolation、denied scope does not open database 等 60 个场景。 |
 | `test_context_raw.py` | `contract` | 覆盖 empty authority and unrequested path do not open database、permissions precede candidate limit and no model needed、explicit source filter never broadens authority 等 37 个场景。 |
 | `test_context_raw_scale_benchmark.py` | `contract` | 覆盖 object scale probe has exact positive control and plan、raw scale probe uses fts and has a nonzero positive control 场景。 |
-| `test_context_search.py` | `contract` | 覆盖 authorization and requested paths never invoke other lane、empty partial zero unavailable and safe failures、parallel common deadline and finalizers wait for both reads 等 24 个场景。 |
-| `test_context_search_both_paths.py` | `integration` | The objective names 'recall' and requires BOTH paths: raw and memory. |
 | `test_context_v2_contract_parity.py` | `unit` | Mechanical parity checks for the shared v2 coverage receipt contract. |
 | `test_contract_parity.py` | `contract` | Python 的枚举和 TypeScript 里那份手写的联合类型必须一致。 |
 | `test_conversation_search.py` | `integration` | Searching imported conversations before any generation model is configured. |
 | `test_conversation_seed_ids.py` | `contract` | 覆盖 seed ids read metadata only without hydrating、seed eligibility keeps person and memory content only、latest activity includes nonseed turns and import time fallback 等 13 个场景。 |
 | `test_conversation_turn_grouping.py` | `contract` | A proposal and the turn that adopts it must reach HY as one turn. |
+| `test_core_ready_before_recovery.py` | `integration` | Readiness never waits for picking up work an earlier run left unfinished. |
 | `test_core_test_reporting.py` | `contract` | 覆盖 report writes sanitized machine readable views、file and marker aggregates are stable、classification suggestions never guess unit contract or integration 等 6 个场景。 |
 | `test_credential_responsiveness.py` | `integration` | 覆盖 credentials do not block the event loop、disabled automatic processing does not digest onboarding、answering reads credentials off loop 等 5 个场景。 |
 | `test_cursor_default_root_windows.py` | `contract` | R-29 剩余：Cursor 默认根路径不能写死成 macOS。 |
-| `test_d93_same_process_load.py` | `integration` | D93 test 2: read latency while pure-Python work holds the GIL. |
 | `test_daemon_contract.py` | `unit` | A5-01/A5-03: process ownership, and the three grants kept apart. |
 | `test_daemon_scheduler.py` | `contract` | A5-02/A5-04: the daemon's scan scheduler and composed health. |
 | `test_data_safety.py` | `contract` | A5-05: backup usability/rotation, crash recovery, log retention. |
@@ -108,7 +106,6 @@
 | `test_harness_contract_suite.py` | `contract` | A4-09: one contract, ten harnesses. |
 | `test_health.py` | `contract` | 覆盖 a backfill that fails says so rather than disappearing、a failed catch up leaves a traceback behind、configured model without content consent does not start backfill 等 15 个场景。 |
 | `test_history_listing_rotation.py` | `contract` | 覆盖 history listing alternates started and untouched files、history listing drains whichever cohort is longer 场景。 |
-| `test_home_summary.py` | `integration` | 覆盖 summary counts beyond page limit and excludes ineligible rows、summary revocation excludes whole mixed memory not only citation、latest is bounded and other users revocations do not hide local data 等 6 个场景。 |
 | `test_host_capabilities.py` | `unit` | A plugin does not become realtime on every host or every unknown version. |
 | `test_hourly_c1_peak_replay_contract.py` | `contract` | Guard the package peak-replay probe's error accounting. |
 | `test_hourly_c1_recall_stage_probe_contract.py` | `contract` | Guard the packaged recall stage probe's command and error semantics. |
@@ -139,7 +136,6 @@
 | `test_live_watch.py` | `contract` | 覆盖 a new turn lands well inside the ten second target、start prime catches a change that predates the watcher、a run that predates the change is followed by a fresh one 等 15 个场景。 |
 | `test_live_watch_grants.py` | `integration` | 覆盖 explicit sync grant starts watch without restart and revocation stops it 场景。 |
 | `test_local_embedding.py` | `contract` | Guards for the built-in embedding model. |
-| `test_local_embedding_offsets.py` | `contract` | 覆盖 real locked tokenizer offsets are unicode codepoints、known emoji and combining offsets are not utf8 or utf16 units、offsets are not truncated or padded and do not create onnx session 等 9 个场景。 |
 | `test_local_onnx_provider.py` | `contract` | Expect local ONNX embedding to be the default and to feed Hy Memory. |
 | `test_log_file.py` | `contract` | 覆盖 what the watchdog says survives a dock launch、the log lives where the data does、a machine left running for months does not fill up 等 4 个场景。 |
 | `test_log_privacy.py` | `integration` | The file log is shipped to us in bug reports; it must not carry originals. |
@@ -160,8 +156,6 @@
 | `test_memory_content_import.py` | `integration` | 覆盖 existing memory preview keeps unknown author and exact original、invalid existing memory records never leave a partial upload、memory content requires explicit mode and rejects vendor guessing 等 5 个场景。 |
 | `test_memory_evidence_freshness.py` | `contract` | 新鲜度拆除后：读路径恒为 current；证据修订 / 畸形 proof / segment ref 不再藏记忆或 503。 |
 | `test_memory_freshness_integration_review.py` | `integration` | Independent synthetic read-path review; no lifespan, model or user database. |
-| `test_memory_governance_api.py` | `integration` | 覆盖 memory governance api preserves evidence and reports cleanup、memory validation does not echo content 场景。 |
-| `test_memory_graph_api.py` | `integration` | 覆盖 graph labels where every edge came from、a created memory is on the map with its source links、drawing the map does not stop the app answering 等 12 个场景。 |
 | `test_memory_notes.py` | `integration` | 覆盖 empty library can save a note without a matter or configured model、note requires authentication explicit scope and nonempty content、saved note evidence returns raw and consent reference from same record 等 6 个场景。 |
 | `test_memory_qa.py` | `contract` | 覆盖 search terms keep meaningful single chinese character、streamed answer emits recall then incremental grounded text、governance change during generation stops the old answer 等 14 个场景。 |
 | `test_memory_qa_api.py` | `integration` | 覆盖 ask stream endpoint emits recall deltas and final、ask stream endpoint requires the local token 场景。 |
@@ -214,39 +208,23 @@
 | `test_probe_payment_required.py` | `contract` | 覆盖 http 402 without a useful body is still understood as unpaid、a wrong address is still a missing model not an unpaid one 场景。 |
 | `test_processing_requests.py` | `contract` | 覆盖 concurrent claim only one snapshot wins、concurrent create same grant has one id and profile、concurrent different profile never reuses another scope 等 14 个场景。 |
 | `test_quality_acceptance.py` | `contract` | 覆盖 acceptance pack is deterministic and scores personal boundary、acceptance score fails missing personal memory 场景。 |
-| `test_raw_search_without_model.py` | `integration` | Search imported conversations with no generative model configured at all. |
 | `test_raw_vector_scale_benchmark.py` | `contract` | 覆盖 vector scale probe uses real 512 dimension filtered search 场景。 |
 | `test_read_path_freshness_batch.py` | `contract` | The row-by-row read check must not scale its query count with the page. |
-| `test_reader_app.py` | `integration` | The Reader process stays read-only and never blocks a read on its side effects. |
-| `test_reader_conversation_hit.py` | `contract` | A search hit carries who wrote the row it matched. |
 | `test_real_load_metrics.py` | `contract` | Run the real access layer under a production-like combined load. |
 | `test_recall.py` | `contract` | 覆盖 recall is confirmed only grounded and scope bound、wildcard scope means every scope just like it does in qa、recall returns empty instead of unrelated fallback 等 10 个场景。 |
 | `test_recall_during_import_probe_contract.py` | `contract` | Guard the source-level recall-during-import probe's sampling semantics. |
 | `test_recall_excluded_sources.py` | `contract` | D94: an empty result names the sources this host may not read. |
-| `test_recall_fusion_live.py` | `integration` | RCL-04 against a real HY instance instead of a stand-in. |
 | `test_recall_library_scale.py` | `contract` | 覆盖 recall reaches a memory that is not among the newest 500、semantic recall reaches a memory outside the newest 500、recall still works just below the boundary 等 5 个场景。 |
 | `test_recall_log_probe_exclusion.py` | `contract` | A-21：R-10 一旦引入召回日志，「探针不污染」必须自动变红而不是静默失效。 |
 | `test_recall_probe.py` | `contract` | The self-check query, and what it must not touch on its way through. |
+| `test_recall_raw_fallback.py` | `integration` | MemHub_recall degrades to the imported conversations instead of answering empty. |
 | `test_recall_revoked_candidate_crowding.py` | `contract` | Revoked-source rows must not crowd a readable recall hit out of the page. |
 | `test_recall_scope_candidate_budget.py` | `contract` | 覆盖 other scopes cannot consume the recall candidate budget、internal wildcard still reports real candidate truncation、workspace resolution does not remove shared results 等 9 个场景。 |
 | `test_recall_scope_control.py` | `integration` | 覆盖 external scope cannot override shared or host workspace boundary、scope only mutation is versioned without changing status or reindexing 场景。 |
 | `test_recall_scope_off_loop.py` | `contract` | The workspace lookup behind an external recall must not run on the loop. |
 | `test_recent_first_import.py` | `contract` | Recent-file priority survives restart through a selection-bound frozen copy. |
-| `test_retrieval_chunking.py` | `contract` | 覆盖 default 384 body 64 overlap and exact source slices、all prefix and special tokens count toward strict 512 budget、real tokenizer covers long chinese middle and tail object locations 等 20 个场景。 |
-| `test_retrieval_eligibility_benchmark.py` | `contract` | 覆盖 scale probe proves composite authority index changes the plan 场景。 |
-| `test_retrieval_index_store.py` | `contract` | 覆盖 constructor and reads do not create database or schema、explicit initialization rolls back and never grants model policy、consumer and jobs commit together 等 19 个场景。 |
-| `test_retrieval_index_supervisor.py` | `contract` | 覆盖 stop waits for native exit and does not close resources、async cancellation repeatedly waits for native thread、idle no trigger no spin and duplicate start rejected 等 14 个场景。 |
-| `test_retrieval_index_worker.py` | `contract` | 覆盖 tick indexes complete original and reopen can search、change during native encoding never publishes、cancel after encode does not publish and is reclaimable 等 10 个场景。 |
 | `test_retrieval_lifespan.py` | `integration` | 覆盖 retrieval defaults off and does not create index、enabling retrieval requires runtime ownership、index enabled serve imports without building an unmanaged app 等 6 个场景。 |
-| `test_retrieval_mapped_content.py` | `contract` | 覆盖 raw authors keep exact body and do not mutate evidence、raw and author qualification rejects without tokenizing、ambiguous generated and body hygiene are not admitted 等 22 个场景。 |
-| `test_retrieval_mapped_integration.py` | `contract` | 覆盖 empty materialization rechecks excluded map、completed excluded missing active binding is not empty success、old empty completion is invalidated when a new indexed record arrives 等 24 个场景。 |
-| `test_retrieval_provisioning.py` | `contract` | The index has to come up through the product, not through a test helper. |
 | `test_retrieval_query_plan.py` | `contract` | Local QueryPlan: extract URL/path objects. |
-| `test_retrieval_raw_candidates.py` | `contract` | 覆盖 positive only current authorized published chunks are searched、empty authority never reads database or vector、unapproved source never enters vector query 等 15 个场景。 |
-| `test_retrieval_raw_evidence.py` | `contract` | 覆盖 materialized text is exact current original、stale candidates do not authorize original read、budget does not cut a chunk into fake partial object 等 6 个场景。 |
-| `test_retrieval_raw_lane.py` | `contract` | v1 raw lane must not claim complete empty when the derived index is partial. |
-| `test_retrieval_runtime.py` | `contract` | 覆盖 constructor and missing start create nothing、stop releases supervisor worker but preserves immutable snapshot、not initialized or invalid configuration never creates index 等 21 个场景。 |
-| `test_retrieval_vector_store.py` | `contract` | 覆盖 constructor does no io and unopened calls do not create、open existing missing store or collection never creates、real chroma collection has no embedding function or documents 等 32 个场景。 |
 | `test_runtime.py` | `integration` | 覆盖 runtime writes and removes ownership receipt、runtime rejects second owner for same data directory、nonpublishing maintenance owner still excludes a second core 等 4 个场景。 |
 | `test_runtime_client.py` | `contract` | 覆盖 runtime inspection authenticates the discovered instance、runtime inspection rejects untrusted receipts without probing、runtime inspection distinguishes stopped and identity mismatch 场景。 |
 | `test_sanitization_source_map.py` | `contract` | 覆盖 mapping matches existing sanitizer and exact original slices、synthetic replacements never claim original locations、repeated identical suffix is mapped by positions not string search 等 6 个场景。 |
@@ -268,6 +246,7 @@
 | `test_sdk_data_plane_migration.py` | `contract` | SDK-authority migration ledger, aliases and atomic cutover marker. |
 | `test_sdk_memory_qa.py` | `contract` | 覆盖 sdk ask propagates sdk search failure without legacy fallback、sdk ask revalidates memory before returning extract、sdk ask uses native sdk memory without governance fields 场景。 |
 | `test_sdk_migration_bundle.py` | `contract` | SDK-authority cutover requires a verified management + SDK data-plane bundle. |
+| `test_sdk_migration_log.py` | `integration` | `sdk-migration.log` explains an unfinished upgrade, and a legacy home is never served. |
 | `test_sdk_verbatim_fallback.py` | `contract` | D98: the SDK's verbatim fallback must stay off. |
 | `test_search_without_profile.py` | `contract` | What 'semantic_search' should do once the profile that filled the store is gone. |
 | `test_secondary_source_adapters.py` | `contract` | 覆盖 pi and qwenwork keep tool and sidechain content out of the persons words、qwen code reads only the transcript beside its bookkeeping、qwen native parts preserve visible text not reasoning or tools 等 22 个场景。 |
@@ -277,9 +256,6 @@
 | `test_sedimentation_switch.py` | `contract` | Stopping model-driven sedimentation without losing the configuration. |
 | `test_service_level_pressure_acceptance.py` | `contract` | 覆盖 workbuddy recall remains available during 100k import 场景。 |
 | `test_service_levels.py` | `contract` | 覆盖 background never consumes the realtime reservation、realtime is next for the same source after background yields、import history gets one slice after nine realtime admissions 等 8 个场景。 |
-| `test_session_inbox.py` | `contract` | A session inbox is not a shared mailbox and a pull is not adoption. |
-| `test_session_lease.py` | `contract` | A session file on disk is not proof that the session is online. |
-| `test_session_registry.py` | `contract` | Trusted session identity is not a workspace path. |
 | `test_snapshot_adapter.py` | `contract` | Selection-only binding reopens checksum-verified frozen copies. |
 | `test_snapshot_pool.py` | `contract` | A whole-directory snapshot must not hold a thread everything else is waiting for. |
 | `test_soak_probe_effectiveness.py` | `integration` | The soak probe must observe the load it reports on. |
@@ -319,13 +295,13 @@
 | `test_ui_session_api.py` | `integration` | 覆盖 ui session exchange sets httponly strict cookie、ui session requires bearer for exchange、ui session reports missing web assets 场景。 |
 | `test_unanswered_turn.py` | `contract` | BUG-06: which conversations end on a question nobody answered. |
 | `test_unified_write_entry_wiring.py` | `integration` | The composition root routes every Evidence-first entry through one queue. |
+| `test_v2_authority_and_call_events.py` | `integration` | v2 is the SDK data plane: one authority gate, and host calls are history. |
 | `test_vendor_sqlite_audit.py` | `contract` | A1-08: the audit that says which SQLite is MemHub's and which is a vendor's. |
 | `test_visibility_background.py` | `integration` | The visibility background task: when it runs, and that it says so. |
 | `test_whole_turn_hy_input.py` | `contract` | D74: a turn reaches HY whole; only what HY will read counts toward the ceiling. |
 | `test_windows_process_control.py` | `contract` | R-29：Windows 上 'os.kill' 不是发信号，是无条件杀进程。 |
-| `test_workbuddy_boundary.py` | `contract` | WorkBuddy only injects on SessionStart and UserPromptSubmit. |
 | `test_workbuddy_parsing.py` | `contract` | 覆盖 automation preserves query without claiming fresh human authorship、automation context attributes do not depend on order or quote style、quoted full automation envelope is not scheduled provenance 等 17 个场景。 |
 | `test_workspace_recall.py` | `contract` | Workspace memories were unreachable from every host; these pin the way in. |
 | `test_write_queue_lease_renewal.py` | `contract` | Rule 8: a lease must outlive the work it covers, and be renewed while it runs. |
 
-共 323 个测试文件。
+共 299 个测试文件。

memhub/apps/core/tests/core_test_classification.py

@@ -14,8 +14,8 @@ from pathlib import Path
 import pytest
 
 PRIMARY_MARKERS = ("unit", "contract", "integration", "performance", "live")
-EXPECTED_TEST_FILE_COUNT = 323
-EXPECTED_TEST_FILES_SHA256 = "10a2327bd047a281511980f5b558c1ea64d857f0fff550e4bd96cb53800205ba"
+EXPECTED_TEST_FILE_COUNT = 299
+EXPECTED_TEST_FILES_SHA256 = "7b6afc4f9da9d5ba2829639f38d964f89c78bb71d9cadae3dba9b4aad91e3a2c"
 
 # Pure transformations, validation models, parity checks and state machines.
 # This list is intentionally small: uncertain files default to contract.
@@ -51,23 +51,22 @@ INTEGRATION_FILES = frozenset(
     {
         "test_auth.py",
         "test_backup_endpoint.py",
+        "test_recall_raw_fallback.py",
+        "test_core_ready_before_recovery.py",
         "test_backup_restore_api.py",
         "test_c1_import_via_api_path.py",
         "test_capture_deadline.py",
         "test_chat_exports.py",
         "test_cli_lifecycle.py",
         "test_connection_lifetime.py",
-        "test_context_search_both_paths.py",
         "test_conversation_search.py",
         "test_credential_responsiveness.py",
-        "test_d93_same_process_load.py",
         "test_diagnostic_trace.py",
         "test_diagnostic_trace_api.py",
         "test_external_installation_permissions.py",
         "test_fault_matrix.py",
         "test_file_import_operations.py",
         "test_graph_width_endpoint.py",
-        "test_home_summary.py",
         "test_import_api.py",
         "test_live_capture.py",
         "test_live_watch_grants.py",
@@ -78,8 +77,6 @@ INTEGRATION_FILES = frozenset(
         "test_measure_c1_loop_blocking_contract.py",
         "test_memory_content_import.py",
         "test_memory_freshness_integration_review.py",
-        "test_memory_governance_api.py",
-        "test_memory_graph_api.py",
         "test_memory_notes.py",
         "test_memory_qa_api.py",
         "test_memory_server_durable_queue.py",
@@ -94,13 +91,11 @@ INTEGRATION_FILES = frozenset(
         "test_onboarding_profile.py",
         "test_parent_watchdog.py",
         "test_policy_api_wiring.py",
-        "test_raw_search_without_model.py",
-        "test_reader_app.py",
-        "test_recall_fusion_live.py",
         "test_recall_scope_control.py",
         "test_retrieval_lifespan.py",
         "test_runtime.py",
         "test_secret_store_error_code_api.py",
+        "test_sdk_migration_log.py",
         "test_secret_store_error_codes.py",
         "test_secure_storage.py",
         "test_soak_probe_effectiveness.py",
@@ -114,6 +109,7 @@ INTEGRATION_FILES = frozenset(
         "test_source_sync_permissions.py",
         "test_ui_session_api.py",
         "test_unified_write_entry_wiring.py",
+        "test_v2_authority_and_call_events.py",
         "test_visibility_background.py",
     }
 )

memhub/apps/core/tests/d93_side_effects_plugin.py

@@ -1,194 +0,0 @@
-"""D93 test 3: inventory every database write a Reader-bound read route makes.
-
-Plan `读写隔离方案-20261009.html` section 5 (B) and section 8 row 3. The Reader
-opens the library `mode=ro` + `query_only`, so any write a read route makes
-today will fail there. Instead of a manual audit, run the existing route tests
-with this plugin loaded; it records, per route, every INSERT / UPDATE / DELETE /
-DDL that happens while that route is being served, with the one_memory frames
-that issued it. Recording only, nothing is blocked, so one run lists them all.
-
-    bash /private/tmp/wb-d76-pytest.sh -p tests.d93_side_effects_plugin \
-        tests/test_home_summary.py tests/test_memory_library_api.py ...
-
-The report goes to $ONE_MEMORY_D93_SIDE_EFFECTS (default
-`d93-side-effects.json` in the pytest root) and a summary is printed at the end.
-Writes outside a request (fixture setup, background tasks) are not counted.
-"""
-
-from __future__ import annotations
-
-import contextlib
-import contextvars
-import json
-import os
-import sqlite3
-import traceback
-from collections import defaultdict
-from pathlib import Path
-
-#: The routes the Reader takes over (plan section 5, B, reader_app.py row).
-READER_ROUTES = {
-    ("GET", "/api/v1/home-summary"),
-    ("GET", "/api/v1/memory-library"),
-    ("GET", "/api/v1/memories"),
-    ("GET", "/api/v1/memories/{memory_id}"),
-    ("GET", "/api/v1/memories/graph"),
-    ("POST", "/api/v1/context/search"),
-    ("GET", "/api/v1/context/search"),
-    ("POST", "/api/v1/recall"),
-    ("GET", "/api/v1/conversations/search"),
-    ("POST", "/api/v1/conversations/search"),
-    ("GET", "/api/v1/health"),
-    ("GET", "/health"),
-}
-
-_WRITES = {
-    sqlite3.SQLITE_INSERT: "INSERT",
-    sqlite3.SQLITE_UPDATE: "UPDATE",
-    sqlite3.SQLITE_DELETE: "DELETE",
-    sqlite3.SQLITE_CREATE_TABLE: "CREATE TABLE",
-    sqlite3.SQLITE_CREATE_INDEX: "CREATE INDEX",
-    sqlite3.SQLITE_CREATE_TRIGGER: "CREATE TRIGGER",
-    sqlite3.SQLITE_DROP_TABLE: "DROP TABLE",
-    sqlite3.SQLITE_ALTER_TABLE: "ALTER TABLE",
-}
-
-_current: contextvars.ContextVar[tuple[str, str] | None] = contextvars.ContextVar(
-    "d93_route", default=None
-)
-_served: dict[tuple[str, str], dict[int, int]] = defaultdict(lambda: defaultdict(int))
-_found: dict[tuple, int] = defaultdict(int)
-
-
-def _frames() -> tuple[str, ...]:
-    """Last product frames; a leading `[test]` marks writes a test's stand-in made."""
-    kept = []
-    from_test = False
-    for frame in traceback.extract_stack()[:-2]:
-        name = frame.filename.replace(os.sep, "/")
-        if "/apps/core/tests/" in name and not name.endswith("d93_side_effects_plugin.py"):
-            from_test = True
-        if "/one_memory/" in name and "/tests/" not in name:
-            kept.append(f"{name.split('/one_memory/', 1)[1]}:{frame.lineno} {frame.name}")
-    return (("[test]",) if from_test else ()) + tuple(kept[-4:])
-
-
-#: Self-check: record every route, so a known write route (POST /api/v1/memories)
-#: proves the recorder sees writes at all.
-_ALL = os.environ.get("ONE_MEMORY_D93_ALL_ROUTES") == "1"
-
-
-def _authorizer(action, arg1, arg2, db_name, _trigger):
-    route = _current.get()
-    if route is not None and (_ALL or route in READER_ROUTES) and action in _WRITES:
-        table = arg1 if action != sqlite3.SQLITE_ALTER_TABLE else arg2
-        if db_name != "temp" and not str(table).startswith("sqlite_"):
-            _found[(route, _WRITES[action], str(table), _frames())] += 1
-    return sqlite3.SQLITE_OK
-
-
-_real_connect = sqlite3.connect
-
-
-def _connect(*args, **kwargs):
-    connection = _real_connect(*args, **kwargs)
-    with contextlib.suppress(Exception):
-        connection.set_authorizer(_authorizer)
-    return connection
-
-
-class _RouteTag:
-    def __init__(self, app):
-        self.app = app
-
-    async def __call__(self, scope, receive, send):
-        if scope.get("type") != "http":
-            return await self.app(scope, receive, send)
-        status = {"code": 0}
-
-        async def sending(message):
-            if message.get("type") == "http.response.start":
-                status["code"] = message.get("status", 0)
-            await send(message)
-
-        holder: dict[str, tuple[str, str]] = {}
-        token = _current.set(None)
-
-        # The route template is only known after routing; resolve it up front
-        # from the app's routes so writes made during the handler carry it.
-        for route in getattr(self._root(scope), "routes", ()):
-            match = getattr(route, "matches", None)
-            if match is None:
-                continue
-            kind, _ = match(scope)
-            if kind.name == "FULL":
-                holder["route"] = (scope["method"], getattr(route, "path", scope["path"]))
-                break
-        key = holder.get("route", (scope["method"], scope["path"]))
-        _current.set(key)
-        try:
-            await self.app(scope, receive, sending)
-        finally:
-            _current.reset(token)
-            if key in READER_ROUTES:
-                _served[key][status["code"]] += 1
-
-    def _root(self, scope):
-        return scope.get("app")
-
-
-def pytest_configure(config):
-    sqlite3.connect = _connect
-    # Pooled connections are handed back through `_reset`, which clears any
-    # authorizer; put ours back so the next checkout is still recorded.
-    from one_memory import database_access
-
-    real_reset = database_access._reset
-
-    def _reset(connection, *, reading):
-        clean = real_reset(connection, reading=reading)
-        with contextlib.suppress(Exception):
-            connection.set_authorizer(_authorizer)
-        return clean
-
-    database_access._reset = _reset
-    from one_memory import api
-
-    original = api.create_app
-
-    def create_app(*args, **kwargs):
-        application = original(*args, **kwargs)
-        application.add_middleware(_RouteTag)
-        return application
-
-    api.create_app = create_app
-
-
-def pytest_terminal_summary(terminalreporter):
-    report = {
-        "served": {
-            f"{method} {path}": dict(codes) for (method, path), codes in sorted(_served.items())
-        },
-        "writes": [
-            {
-                "route": f"{route[0]} {route[1]}",
-                "op": op,
-                "table": table,
-                "frames": list(frames),
-                "count": count,
-            }
-            for (route, op, table, frames), count in sorted(_found.items(), key=str)
-        ],
-    }
-    target = Path(
-        os.environ.get("ONE_MEMORY_D93_SIDE_EFFECTS", str(Path.cwd() / "d93-side-effects.json"))
-    )
-    target.write_text(json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8")
-    write = terminalreporter.write_line
-    write(f"D93 side effects: {len(report['writes'])} write sites -> {target}")
-    for name, codes in report["served"].items():
-        write(f"  served {name}: {codes}")
-    for item in report["writes"]:
-        write(f"  {item['route']}: {item['op']} {item['table']} x{item['count']}")
-        for frame in item["frames"]:
-            write(f"      {frame}")

memhub/apps/core/tests/test_auth.py

@@ -55,37 +55,3 @@ def test_browser_origin_is_checked_in_addition_to_token() -> None:
         )
         == 200
     )
-
-
-async def internal_request(
-    path: str,
-    *,
-    token: str | None,
-    method: str = "GET",
-) -> int:
-    settings = Settings(api_token=SecretStr("test-token"))
-    app = create_app(settings)
-    headers = {}
-    if token:
-        headers["Authorization"] = f"Bearer {token}"
-    async with AsyncClient(
-        transport=ASGITransport(app=app),
-        base_url="http://test",
-    ) as client:
-        response = await client.request(method, path, headers=headers, json={})
-    return response.status_code
-
-
-def test_reader_internal_endpoints_require_local_token() -> None:
-    for path in (
-        "/internal/semantic-ids?query=anything",
-        "/internal/graph-snapshot",
-    ):
-        assert asyncio.run(internal_request(path, token=None)) == 401
-        assert asyncio.run(internal_request(path, token="test-token")) == 200
-
-    assert asyncio.run(internal_request("/internal/call-event", token=None, method="POST")) == 401
-    assert (
-        asyncio.run(internal_request("/internal/call-event", token="test-token", method="POST"))
-        == 200
-    )

memhub/apps/core/tests/test_backup_restore_api.py

@@ -1,6 +1,7 @@
 import asyncio
 import sqlite3
 
+import pytest
 from httpx import ASGITransport, AsyncClient
 from pydantic import SecretStr
 
@@ -44,6 +45,8 @@ def _database(path, *, value: str) -> None:
     asyncio.run(SqliteMigrationStore(path).record(Migration(34, "synthetic", lambda _: None)))
 
 
+# A serving Core refuses a legacy home outright, so this one starts on SDK.
+@pytest.mark.fresh_sdk
 def test_restore_endpoint_refuses_when_runtime_owns_the_core(tmp_path) -> None:
     monkeypatch_app = create_app(_settings(tmp_path), manage_runtime=True)
 

memhub/apps/core/tests/test_call_event_recorder.py

@@ -1,104 +1,10 @@
 from datetime import UTC, datetime
 
-from one_memory.api import ConversationSearchHit, ConversationSearchResponse
-from one_memory.call_event_recorder import (
-    ask_call_event,
-    context_call_event,
-    conversation_call_event,
-)
-from one_memory.context_models import ContextPath, ContextPaths, ContextSearchResponse
-from one_memory.external_memory_access import ExternalMemoryAccess
+from one_memory.call_event_recorder import ask_call_event
 from one_memory.memory_governance import GovernedMemory, MemoryKind, MemoryOrigin, MemoryStatus
 from one_memory.memory_qa import MemoryAnswer
 
 
-def _paths(memory: str, raw: str) -> ContextPaths:
-    lane = dict(elapsed_ms=1.0, returned_count=0, truncated=False)
-    return ContextPaths(
-        raw=ContextPath(status=raw, **lane),
-        memory=ContextPath(status=memory, **lane),
-    )
-
-
-def _context(memory: str, raw: str) -> ContextSearchResponse:
-    return ContextSearchResponse(
-        request_id="11111111-1111-4111-8111-111111111111",
-        state="partial",
-        paths=_paths(memory, raw),
-        items=(),
-        used_characters=0,
-        truncated=False,
-        total_ms=3.5,
-    )
-
-
-def test_denied_memory_lane_is_attributed_to_conversations():
-    event = context_call_event(_context("not_authorized", "ok"), None)
-    assert event.tool == "om_conversations"
-
-
-def test_requested_memory_lane_stays_recall():
-    event = context_call_event(_context("empty", "not_authorized"), None)
-    assert event.tool == "om_recall"
-
-
-def test_zero_result_timeout_is_recorded_separately_from_unavailable() -> None:
-    lane = dict(elapsed_ms=750.0, returned_count=0)
-    result = ContextSearchResponse(
-        request_id="11111111-1111-4111-8111-111111111111",
-        state="partial",
-        paths=ContextPaths(
-            raw=ContextPath(
-                status="degraded",
-                reason="timeout_budget",
-                truncated=True,
-                truncated_by=("timeout_budget",),
-                **lane,
-            ),
-            memory=ContextPath(status="empty", truncated=False, **lane),
-        ),
-        items=(),
-        used_characters=0,
-        truncated=True,
-        total_ms=1500,
-    )
-
-    assert context_call_event(result, None).state == "timed_out"
-
-
-def test_conversation_search_records_counts_without_query_or_excerpt():
-    result = ConversationSearchResponse(
-        hits=(
-            ConversationSearchHit(
-                evidence_id="e1",
-                conversation_id="c1",
-                source_id="cursor",
-                excerpt="SECRET_EXCERPT",
-            ),
-            ConversationSearchHit(
-                evidence_id="e2",
-                conversation_id="c1",
-                source_id="cursor",
-                excerpt="SECRET_EXCERPT_2",
-            ),
-        )
-    )
-    access = ExternalMemoryAccess(
-        installation_id="00000000-0000-4000-8000-000000000001",
-        revision=1,
-        scopes=frozenset({"all-apps", "source:cursor"}),
-        tools=frozenset({"om_conversations"}),
-        host_id="codex",
-    )
-    event = conversation_call_event(result, access, 12.0)
-    encoded = event.model_dump_json()
-    assert event.tool == "om_conversations"
-    assert event.state == "grounded"
-    assert event.raw_count == 1 and event.memory_count == 0 and not event.references
-    assert event.host_id == "codex"
-    assert "SECRET" not in encoded
-
-
 def test_ask_records_memory_refs_without_answer():
     memory = GovernedMemory(
         memory_id="m1",

memhub/apps/core/tests/test_context_endpoint_guard.py

@@ -8,7 +8,7 @@ from one_memory.external_memory_access import require_external_endpoint
 
 
 def request(
-    tools, scopes=("all-apps", "source:cursor"), method="POST", path="/api/v1/context/search"
+    tools, scopes=("all-apps", "source:cursor"), method="POST", path="/api/v2/context/search"
 ):
     headers = {
         "x-one-memory-read-context": "external",
@@ -44,9 +44,13 @@ def test_other_capabilities_do_not_enable_composite_read(tools):
 @pytest.mark.parametrize(
     "method,path",
     [
-        ("GET", "/api/v1/context/search"),
+        ("GET", "/api/v2/context/search"),
+        ("POST", "/api/v1/context/search"),
         ("POST", "/api/v1/memory-library"),
+        ("GET", "/api/v1/conversations/search"),
         ("GET", "/api/v1/conversations/evidence-id"),
+        ("POST", "/api/v1/memories/ask"),
+        ("POST", "/api/v1/boundary/peek"),
     ],
 )
 def test_composite_read_does_not_open_other_routes(method, path):
@@ -59,15 +63,3 @@ def test_composite_read_does_not_open_other_routes(method, path):
 def test_legacy_recall_still_requires_its_own_tool():
     with pytest.raises(HTTPException):
         require_external_endpoint(request(["om_conversations"], path="/api/v1/recall"))
-
-
-def test_legacy_raw_route_still_requires_raw_source_authority():
-    with pytest.raises(HTTPException):
-        require_external_endpoint(
-            request(
-                ["om_conversations"],
-                scopes=("all-apps",),
-                method="GET",
-                path="/api/v1/conversations/search",
-            )
-        )

memhub/apps/core/tests/test_context_search.py

@@ -1,547 +0,0 @@
-import asyncio
-import time
-from datetime import UTC, datetime
-
-import pytest
-from pydantic import ValidationError
-
-from one_memory.context_models import (
-    ContextLaneResult,
-    ContextMessage,
-    ContextSearchRequest,
-    ContextSearchResponse,
-    MemoryContextItem,
-    RawContextItem,
-)
-from one_memory.context_search import search_context
-
-
-def memory(identity="m", text="memory", evidence=("e",)):
-    return MemoryContextItem(
-        memory_id=identity,
-        revision=1,
-        content=text,
-        memory_kind="chat",
-        updated_at=datetime.now(UTC),
-        evidence_ids=evidence,
-    )
-
-
-def raw(identity="e", text="raw"):
-    return RawContextItem(
-        source_id="cursor",
-        conversation_id="c",
-        anchor_evidence_id=identity,
-        messages=(
-            ContextMessage(
-                evidence_id=identity,
-                revision=2,
-                role="user",
-                written_by="person",
-                created_at=None,
-                text=text,
-            ),
-        ),
-    )
-
-
-def reader(*items, status="ok", reason=None, truncated_by=()):
-    async def read(deadline):
-        assert deadline > time.monotonic()
-        return ContextLaneResult(
-            items=items, status=status, reason=reason, truncated_by=truncated_by
-        )
-
-    return read
-
-
-async def finalize(kind, items, deadline):
-    assert deadline > time.monotonic()
-    assert all(item.kind == kind for item in items)
-    return items
-
-
-def run(request=None, raw_reader=None, memory_reader=None, finalizer=finalize):
-    return asyncio.run(
-        search_context(
-            request or ContextSearchRequest(query="q"),
-            raw_reader=raw_reader,
-            memory_reader=memory_reader,
-            finalizer=finalizer,
-        )
-    )
-
-
-def test_authorization_and_requested_paths_never_invoke_other_lane():
-    async def forbidden(deadline):
-        pytest.fail("unrequested lane invoked")
-
-    result = run(
-        ContextSearchRequest(query="q", kinds=("memory",)),
-        raw_reader=forbidden,
-        memory_reader=reader(memory()),
-    )
-    assert result.paths.raw.status == "not_requested"
-    assert result.state == "grounded"
-    denied = run(memory_reader=reader(status="empty"))
-    assert denied.paths.raw.status == "not_authorized"
-    assert denied.paths.raw.reason == "permission_required"
-    assert denied.state == "partial" and denied.items == ()
-
-
-def test_empty_partial_zero_unavailable_and_safe_failures():
-    assert (
-        run(raw_reader=reader(status="empty"), memory_reader=reader(status="empty")).state
-        == "empty"
-    )
-
-    async def fail(deadline):
-        raise RuntimeError("PRIVATE_SECRET_SQL_PATH")
-
-    result = run(raw_reader=fail, memory_reader=fail)
-    assert result.state == "unavailable"
-    assert "PRIVATE" not in result.model_dump_json()
-    assert result.paths.raw.reason == "read_unavailable"
-    partial = run(raw_reader=fail, memory_reader=reader(status="empty"))
-    assert partial.state == "partial" and partial.used_characters == 0
-    lexical_only = run(
-        raw_reader=reader(status="degraded", reason="lexical_only"),
-        memory_reader=reader(status="empty"),
-    )
-    assert lexical_only.state == "empty"
-    assert lexical_only.paths.raw.status == "empty"
-
-
-def test_parallel_common_deadline_and_finalizers_wait_for_both_reads():
-    async def scenario():
-        entered = set()
-        deadlines = []
-        finished = set()
-
-        async def read(kind, deadline):
-            entered.add(kind)
-            deadlines.append(deadline)
-            while len(entered) != 2:
-                await asyncio.sleep(0)
-            await asyncio.sleep(0.005 if kind == "raw" else 0.015)
-            finished.add(kind)
-            return ContextLaneResult(status="ok", items=(raw() if kind == "raw" else memory(),))
-
-        async def final(kind, items, deadline):
-            assert finished == {"raw", "memory"}
-            deadlines.append(deadline)
-            return () if kind == "raw" else items
-
-        result = await search_context(
-            ContextSearchRequest(query="q"),
-            raw_reader=lambda d: read("raw", d),
-            memory_reader=lambda d: read("memory", d),
-            finalizer=final,
-        )
-        assert len(set(deadlines)) == 1
-        assert [i.kind for i in result.items] == ["memory"]
-        assert result.paths.raw.reason == "evidence_changed"
-        assert result.state == "partial"
-
-    asyncio.run(scenario())
-
-
-def test_stage_timings_separate_lanes_revalidation_fusion_and_total():
-    async def scenario():
-        observed = []
-
-        async def delayed(item, delay):
-            await asyncio.sleep(delay)
-            return ContextLaneResult(status="ok", items=(item,))
-
-        async def delayed_final(kind, items, deadline):
-            await asyncio.sleep(0.004 if kind == "raw" else 0.008)
-            return items
-
-        result = await search_context(
-            ContextSearchRequest(query="q"),
-            raw_reader=lambda _deadline: delayed(raw(), 0.006),
-            memory_reader=lambda _deadline: delayed(memory(), 0.012),
-            finalizer=delayed_final,
-            timing_observer=observed.append,
-        )
-        assert result.state == "grounded" and len(observed) == 1
-        timing = observed[0]
-        assert set(timing) == {
-            "raw_ms",
-            "memory_ms",
-            "raw_revalidation_ms",
-            "memory_revalidation_ms",
-            "fusion_ms",
-            "total_ms",
-        }
-        assert 4 <= timing["raw_ms"] < timing["memory_ms"]
-        assert 2 <= timing["raw_revalidation_ms"] < timing["memory_revalidation_ms"]
-        assert timing["fusion_ms"] >= 0
-        assert timing["total_ms"] >= timing["memory_ms"] + timing["memory_revalidation_ms"]
-
-    asyncio.run(scenario())
-
-
-def test_finalizer_failure_never_releases_old_items():
-    async def fail(kind, items, deadline):
-        raise ValueError("PRIVATE")
-
-    result = run(raw_reader=reader(raw()), memory_reader=reader(memory()), finalizer=fail)
-    assert result.items == () and result.state == "unavailable"
-    assert "PRIVATE" not in result.model_dump_json()
-
-
-def test_shared_count_text_fairness_and_anchor_metadata():
-    result = run(
-        ContextSearchRequest(query="q", character_budget=200, limit=2),
-        raw_reader=reader(raw(text="R" * 1000), raw("e2")),
-        memory_reader=reader(memory(text="M" * 1000), memory("m2")),
-    )
-    assert [i.kind for i in result.items] == ["raw", "memory"]
-    assert result.used_characters == 200
-    assert len(result.items[0].messages[0].text) == 100
-    assert len(result.items[1].content) == 100
-    assert result.items[0].anchor_evidence_id == "e"
-    assert result.items[0].messages[0].revision == 2
-    assert result.items[0].messages[0].written_by == "person"
-    for path in (result.paths.raw, result.paths.memory):
-        assert path.returned_count == 1
-        assert set(path.truncated_by) == {"count_budget", "character_budget"}
-    assert all(i.truncated for i in result.items)
-    assert result.state == "grounded" and result.adoption == "unknown"
-    assert result.paths.raw.status == "ok"
-    assert result.paths.memory.status == "ok"
-    ContextSearchResponse.model_validate_json(result.model_dump_json())
-
-
-def test_dedup_preserves_cross_kind_evidence_relations():
-    item = raw()
-    result = run(
-        raw_reader=reader(item, item),
-        memory_reader=reader(memory(), memory(), memory("other", evidence=("e", "e"))),
-    )
-    assert len(result.items) == 3
-    assert result.paths.raw.returned_count == 1
-    assert result.paths.memory.returned_count == 2
-    assert result.items[-1].evidence_ids == ("e",)
-
-
-def test_timeout_cancels_tasks_and_late_results_are_not_released():
-    async def scenario():
-        cancelled = []
-
-        async def slow(deadline):
-            try:
-                await asyncio.sleep(10)
-            except asyncio.CancelledError:
-                cancelled.append(True)
-                return ContextLaneResult(status="ok", items=(raw(text="late"),))
-
-        result = await search_context(
-            ContextSearchRequest(query="q", timeout_ms=50),
-            raw_reader=slow,
-            memory_reader=reader(memory()),
-            finalizer=finalize,
-        )
-        assert cancelled == [True]
-        assert result.items == ()
-        assert result.paths.raw.reason == "timeout_budget"
-        assert result.paths.memory.reason == "timeout_budget"
-        assert not [t for t in asyncio.all_tasks() if t is not asyncio.current_task()]
-
-    asyncio.run(scenario())
-
-
-def test_caller_cancellation_propagates_and_cleans_readers():
-    async def scenario():
-        started = asyncio.Event()
-        exits = []
-
-        async def slow(deadline):
-            started.set()
-            try:
-                await asyncio.sleep(10)
-            finally:
-                exits.append(1)
-
-        task = asyncio.create_task(
-            search_context(
-                ContextSearchRequest(query="q"),
-                raw_reader=slow,
-                memory_reader=slow,
-                finalizer=finalize,
-            )
-        )
-        await started.wait()
-        task.cancel()
-        with pytest.raises(asyncio.CancelledError):
-            await task
-        assert len(exits) == 2
-        assert not [t for t in asyncio.all_tasks() if t is not asyncio.current_task()]
-
-    asyncio.run(scenario())
-
-
-def test_invalid_lane_shape_and_wrong_kind_fail_closed():
-    async def invalid(deadline):
-        return {"status": "ok", "items": [], "private_diagnostic": "secret"}
-
-    assert run(raw_reader=invalid, memory_reader=reader(memory())).paths.raw.status == "unavailable"
-    assert (
-        run(raw_reader=reader(memory()), memory_reader=reader(memory())).paths.raw.status
-        == "unavailable"
-    )
-    with pytest.raises(ValidationError):
-        ContextSearchRequest(query="q", limit=21)
-    with pytest.raises(ValidationError):
-        ContextSearchRequest(query="q", character_budget=20001)
-
-
-def test_expired_entry_deadline_never_reads_or_releases_content():
-    async def forbidden(*args):
-        pytest.fail("expired deadline must not invoke work")
-
-    result = asyncio.run(
-        search_context(
-            ContextSearchRequest(query="q"),
-            raw_reader=forbidden,
-            memory_reader=forbidden,
-            finalizer=forbidden,
-            deadline=time.monotonic() - 1,
-        )
-    )
-    assert result.state == "partial" and result.items == ()
-    assert result.paths.raw.reason == result.paths.memory.reason == "timeout_budget"
-
-
-def test_entry_deadline_is_not_reset_and_request_timeout_caps_it():
-    async def scenario():
-        observed = []
-
-        async def read(deadline):
-            observed.append(deadline)
-            return ContextLaneResult(status="ok", items=(memory(),))
-
-        entry = time.monotonic() + 0.1
-        await search_context(
-            ContextSearchRequest(query="q"),
-            raw_reader=None,
-            memory_reader=read,
-            finalizer=finalize,
-            deadline=entry,
-        )
-        assert observed == [entry]
-        started = time.monotonic()
-        await search_context(
-            ContextSearchRequest(query="q", timeout_ms=50),
-            raw_reader=None,
-            memory_reader=read,
-            finalizer=finalize,
-            deadline=started + 10,
-        )
-        assert observed[-1] < started + 0.1
-
-    asyncio.run(scenario())
-
-
-def test_finalizer_timeout_cannot_release_previously_read_items():
-    async def scenario():
-        cancelled = []
-
-        async def slow(kind, items, deadline):
-            try:
-                await asyncio.sleep(10)
-            except asyncio.CancelledError:
-                cancelled.append(kind)
-                return items
-
-        result = await search_context(
-            ContextSearchRequest(query="q", timeout_ms=50),
-            raw_reader=reader(raw()),
-            memory_reader=reader(memory()),
-            finalizer=slow,
-        )
-        assert set(cancelled) == {"raw", "memory"}
-        assert result.items == () and result.state == "unavailable"
-        assert result.paths.memory.truncated_by == ("timeout_budget",)
-        assert not [t for t in asyncio.all_tasks() if t is not asyncio.current_task()]
-
-    asyncio.run(scenario())
-
-
-def test_overlapping_raw_windows_keep_each_anchor_and_cross_kind_reference():
-    first = raw("e1")
-    second = raw("e2")
-    first = first.model_copy(update={"messages": first.messages + second.messages})
-    result = run(
-        raw_reader=reader(first, second), memory_reader=reader(memory(evidence=("e1", "e2")))
-    )
-    windows = [item for item in result.items if item.kind == "raw"]
-    assert [item.anchor_evidence_id for item in windows] == ["e1", "e2"]
-    assert [message.evidence_id for item in windows for message in item.messages] == ["e1", "e2"]
-    assert next(item for item in result.items if item.kind == "memory").evidence_ids == ("e1", "e2")
-
-
-def test_twenty_item_and_twenty_thousand_character_caps():
-    result = run(
-        ContextSearchRequest(query="q", limit=20, character_budget=20000),
-        raw_reader=reader(*(raw(f"e{i}", "r" * 20000) for i in range(21))),
-        memory_reader=reader(*(memory(f"m{i}", "m" * 20000) for i in range(21))),
-    )
-    assert len(result.items) == 20 and result.used_characters == 20000
-    assert result.paths.raw.returned_count == result.paths.memory.returned_count == 10
-    assert (
-        sum(
-            len(i.content) if i.kind == "memory" else sum(len(m.text) for m in i.messages)
-            for i in result.items
-        )
-        == 20000
-    )
-
-
-def test_caller_cancel_during_finalization_cleans_all_tasks():
-    async def scenario():
-        started = asyncio.Event()
-        finished = []
-
-        async def final(kind, items, deadline):
-            started.set()
-            try:
-                await asyncio.sleep(10)
-            finally:
-                finished.append(kind)
-
-        task = asyncio.create_task(
-            search_context(
-                ContextSearchRequest(query="q"),
-                raw_reader=reader(raw()),
-                memory_reader=reader(memory()),
-                finalizer=final,
-            )
-        )
-        await started.wait()
-        task.cancel()
-        with pytest.raises(asyncio.CancelledError):
-            await task
-        assert set(finished) == {"raw", "memory"}
-        assert not [t for t in asyncio.all_tasks() if t is not asyncio.current_task()]
-
-    asyncio.run(scenario())
-
-
-def test_invalid_finalizer_output_and_constructed_models_fail_closed():
-    async def wrong(kind, items, deadline):
-        return (memory("unselected"),)
-
-    assert run(memory_reader=reader(memory()), finalizer=wrong).items == ()
-    invalid = memory().model_copy(update={"content": "x" * 20001})
-    assert run(memory_reader=reader(invalid)).state == "unavailable"
-    with pytest.raises(ValidationError):
-        run(ContextSearchRequest.model_construct(query="q", limit=100))
-
-
-def test_duplicate_memory_identity_keeps_combined_evidence_relations():
-    result = run(memory_reader=reader(memory(evidence=("a",)), memory(evidence=("b",))))
-    assert result.items[0].evidence_ids == ("a", "b")
-
-
-def test_one_slow_finalizer_exhausts_release_deadline_for_both_lanes():
-    async def final(kind, items, deadline):
-        if kind == "raw":
-            await asyncio.sleep(10)
-        return items
-
-    result = run(
-        ContextSearchRequest(query="q", timeout_ms=50),
-        raw_reader=reader(raw()),
-        memory_reader=reader(memory()),
-        finalizer=final,
-    )
-    assert result.items == ()
-    assert result.state == "partial"
-
-
-def test_multiple_raw_messages_clipped_without_losing_anchor_or_authorship():
-    item = raw("anchor", "A" * 20000)
-    item = item.model_copy(
-        update={
-            "messages": (
-                raw("before", "B" * 20000).messages[0],
-                item.messages[0],
-                raw("after", "C" * 20000).messages[0],
-            )
-        }
-    )
-    result = run(
-        ContextSearchRequest(query="q", character_budget=200),
-        raw_reader=reader(item),
-        memory_reader=reader(memory(text="M" * 20000)),
-    )
-    emitted = result.items[0]
-    assert emitted.anchor_evidence_id == "anchor"
-    assert [m.evidence_id for m in emitted.messages] == ["before", "anchor", "after"]
-    assert all(
-        m.truncated and m.written_by == "person" and m.revision == 2 for m in emitted.messages
-    )
-    assert result.used_characters == 200
-
-
-def test_metadata_union_stays_bounded_and_reports_truncation():
-    result = run(
-        memory_reader=reader(
-            memory(evidence=tuple(f"a{i}" for i in range(128))), memory(evidence=("extra",))
-        )
-    )
-    assert len(result.items[0].evidence_ids) == 128
-    assert result.items[0].truncated
-    assert "metadata_budget" in result.paths.memory.truncated_by
-
-
-def test_finalizer_removed_context_message_reports_partial_not_complete():
-    item = raw()
-    item = item.model_copy(update={"messages": item.messages + raw("other").messages})
-
-    async def final(kind, items, deadline):
-        return tuple(i.model_copy(update={"messages": i.messages[:1]}) for i in items)
-
-    result = run(
-        ContextSearchRequest(query="q", kinds=("raw",)), raw_reader=reader(item), finalizer=final
-    )
-    assert result.state == "partial"
-    assert result.paths.raw.reason == "evidence_changed"
-
-
-def test_noncooperative_synchronous_reader_return_after_deadline_is_discarded():
-    async def late(deadline):
-        time.sleep(0.06)
-        return ContextLaneResult(status="ok", items=(raw(),))
-
-    result = run(ContextSearchRequest(query="q", kinds=("raw",), timeout_ms=50), raw_reader=late)
-    assert result.items == () and result.paths.raw.reason == "timeout_budget"
-
-
-def test_timeout_does_not_wait_for_a_reader_that_suppresses_cancellation():
-    async def scenario():
-        release = asyncio.Event()
-
-        async def stuck(_deadline):
-            try:
-                await asyncio.Event().wait()
-            except asyncio.CancelledError:
-                await release.wait()
-                return ContextLaneResult(status="empty")
-
-        started = time.monotonic()
-        result = await search_context(
-            ContextSearchRequest(query="q", kinds=("memory",), timeout_ms=50),
-            raw_reader=None,
-            memory_reader=stuck,
-            finalizer=finalize,
-        )
-        assert time.monotonic() - started < 0.2
-        assert result.paths.memory.reason == "timeout_budget"
-        release.set()
-        await asyncio.sleep(0)
-
-    asyncio.run(scenario())

memhub/apps/core/tests/test_context_search_both_paths.py

@@ -1,161 +0,0 @@
-"""The objective names `recall` and requires BOTH paths: raw and memory.
-
-Verified against a real Core with seeded evidence and one governed memory:
-asking for `raw` returns the stored verbatim and leaves `memory` as
-`not_requested`; asking for `memory` returns the governed memory and leaves
-`raw` as `not_requested`. That the unrequested side is marked, rather than
-silently empty, is what proves the filter is actually applied.
-"""
-
-from __future__ import annotations
-
-import sqlite3
-import uuid
-
-import pytest
-from httpx import ASGITransport, AsyncClient
-from pydantic import SecretStr
-
-from one_memory.api import create_app
-from one_memory.config import Settings
-
-
-def _seed(data_dir) -> tuple[str, str]:
-    """One evidence row and one governed memory; return their verbatim/content."""
-    verbatim = "帮我总结一下 SQLite 的写锁调优方法"
-    memory = "用户偏好：数据库调优时优先看写入批处理和读池容量，不要一上来就换引擎。"
-
-    connection = sqlite3.connect(data_dir / "one-memory.sqlite3")
-    try:
-        cursor = connection.cursor()
-        columns = [row[1] for row in cursor.execute("PRAGMA table_info(evidence)")]
-        row: dict[str, object] = {}
-        for column in columns:
-            if column == "evidence_id" or column == "idempotency_key":
-                row[column] = str(uuid.uuid4())
-            elif column in ("user_id", "source_id"):
-                row[column] = "local" if column == "user_id" else "codex"
-            elif column in ("conversation_id", "message_id"):
-                row[column] = str(uuid.uuid4())
-            elif column == "role":
-                row[column] = "user"
-            elif column == "written_by":
-                row[column] = "person"
-            elif column == "verbatim":
-                row[column] = verbatim
-            elif column in ("created_at", "updated_at", "imported_at", "recorded_at"):
-                row[column] = "2026-09-26T00:00:00Z"
-            elif column == "revision" or column == "source_ordinal":
-                row[column] = 1
-            elif column.endswith("_hash") or column == "fingerprint":
-                row[column] = str(uuid.uuid4())[:32]
-        names = ",".join(row)
-        markers = ",".join(["?"] * len(row))
-        cursor.execute(f"INSERT INTO evidence ({names}) VALUES ({markers})", list(row.values()))
-
-        memory_columns = [r[1] for r in cursor.execute("PRAGMA table_info(governed_memories)")]
-        memory_row: dict[str, object] = {}
-        for column in memory_columns:
-            if column == "memory_id":
-                memory_row[column] = str(uuid.uuid4())
-            elif column == "user_id":
-                memory_row[column] = "local"
-            elif column == "kind":
-                memory_row[column] = "working"
-            elif column == "status":
-                memory_row[column] = "confirmed"
-            elif column == "content":
-                memory_row[column] = memory
-            elif column in ("scopes_json", "tags_json"):
-                memory_row[column] = "[]"
-            elif column == "origin":
-                memory_row[column] = "manual"
-            elif column == "revision":
-                memory_row[column] = 1
-            elif column in ("created_at", "updated_at"):
-                memory_row[column] = "2026-09-26T00:00:00Z"
-        names = ",".join(memory_row)
-        markers = ",".join(["?"] * len(memory_row))
-        cursor.execute(
-            f"INSERT INTO governed_memories ({names}) VALUES ({markers})",
-            list(memory_row.values()),
-        )
-        connection.commit()
-    finally:
-        connection.close()
-    return verbatim, memory
-
-
-def _client(tmp_path):
-    data_dir = tmp_path / "data"
-    data_dir.mkdir(parents=True, exist_ok=True)
-    app = create_app(
-        Settings(
-            _env_file=None,
-            data_dir=data_dir,
-            source_home=tmp_path,
-            api_token=SecretStr("test-token"),
-        )
-    )
-    return (
-        app,
-        data_dir,
-        AsyncClient(
-            transport=ASGITransport(app=app),
-            base_url="http://test",
-            headers={
-                "Authorization": "Bearer test-token",
-                "Origin": "http://127.0.0.1:5173",
-            },
-        ),
-    )
-
-
-@pytest.mark.anyio
-async def test_raw_path_returns_verbatim_and_leaves_memory_unrequested(tmp_path) -> None:
-    app, data_dir, client = _client(tmp_path)
-    async with app.router.lifespan_context(app), client:
-        # Seed inside the lifespan: the schema is created on startup, so seeding
-        # before it yields no columns and an empty INSERT.
-        verbatim, _ = _seed(data_dir)
-        response = await client.post(
-            "/api/v1/context/search",
-            json={
-                "query": verbatim,
-                "kinds": ["raw"],
-                "limit": 5,
-                "character_budget": 2000,
-                "timeout_ms": 5000,
-            },
-        )
-
-    assert response.status_code == 200, response.text
-    document = response.json()
-    assert document["paths"]["raw"]["status"] == "ok"
-    assert document["paths"]["memory"]["status"] == "not_requested", "memory must not run"
-    texts = [message["text"] for item in document["items"] for message in item.get("messages", [])]
-    assert verbatim in texts, "raw path must return the stored verbatim"
-
-
-@pytest.mark.anyio
-async def test_memory_path_returns_governed_memory_and_leaves_raw_unrequested(tmp_path) -> None:
-    app, data_dir, client = _client(tmp_path)
-    async with app.router.lifespan_context(app), client:
-        _, memory = _seed(data_dir)
-        response = await client.post(
-            "/api/v1/context/search",
-            json={
-                "query": "数据库调优偏好",
-                "kinds": ["memory"],
-                "limit": 5,
-                "character_budget": 2000,
-                "timeout_ms": 5000,
-            },
-        )
-
-    assert response.status_code == 200, response.text
-    document = response.json()
-    assert document["paths"]["memory"]["status"] == "ok"
-    assert document["paths"]["raw"]["status"] == "not_requested", "raw must not run"
-    contents = [item["content"] for item in document["items"]]
-    assert memory in contents, "memory path must return the governed memory"

memhub/apps/core/tests/test_conversation_search.py

@@ -10,11 +10,7 @@ from contextlib import contextmanager
 from datetime import UTC, datetime
 
 import pytest
-from httpx import ASGITransport, AsyncClient
-from pydantic import SecretStr
 
-from one_memory.api import create_app
-from one_memory.config import Settings
 from one_memory.imports.models import (
     EvidenceInput,
     EvidenceOrigin,
@@ -22,7 +18,6 @@ from one_memory.imports.models import (
     WrittenBy,
 )
 from one_memory.imports.storage import ConversationSearchUnavailableError, EvidenceStore
-from one_memory.memory_governance import MemoryDraft, MemoryKind
 
 
 def message(
@@ -479,268 +474,3 @@ def test_a_missing_index_is_raised_rather_than_answered_as_no_matches(tmp_path)
 
     with pytest.raises(ConversationSearchUnavailableError):
         store.search_conversations("抽取终于", user_id="local", limit=10)
-
-
-def _client(tmp_path):
-    app = create_app(
-        Settings(
-            data_dir=tmp_path / "data",
-            source_home=tmp_path,
-            api_token=SecretStr("local-token"),
-        )
-    )
-    return app, AsyncClient(
-        transport=ASGITransport(app=app),
-        base_url="http://test",
-        headers={
-            "Authorization": "Bearer local-token",
-            "Origin": "http://127.0.0.1:5173",
-        },
-    )
-
-
-@pytest.mark.anyio
-async def test_recent_list_ignores_a_missing_search_index(tmp_path) -> None:
-    app, transport = _client(tmp_path)
-    async with app.router.lifespan_context(app), transport as client:
-        app.state.evidence_store.put(
-            message(verbatim="刚从 Cursor 同步进来的原话", message_id="live")
-        )
-        with sqlite3.connect(app.state.evidence_store.database_path) as connection:
-            connection.execute("DROP TABLE IF EXISTS evidence_search")
-
-        response = await client.get("/api/v1/conversations", params={"limit": 5})
-
-        assert response.status_code == 200
-        body = response.json()
-        assert body["total"] == 1
-        assert body["items"][0]["excerpt"] == "刚从 Cursor 同步进来的原话"
-        assert body["items"][0]["truncated"] is False
-        assert body["items"][0]["source_id"] == "cursor"
-
-
-@pytest.mark.anyio
-async def test_search_answers_with_no_model_profile_configured(tmp_path) -> None:
-    """The whole point of C-02: no generation model, and still an answer."""
-    app, transport = _client(tmp_path)
-    async with app.router.lifespan_context(app), transport as client:
-        app.state.evidence_store.put(message(verbatim="昨天晚上重新打了一个包，抽取终于跑通了"))
-
-        assert app.state.model_profile_store.active(app.state.secret_store) is None
-        response = await client.get("/api/v1/conversations/search", params={"query": "抽取终于"})
-
-        assert response.status_code == 200
-        body = response.json()
-        assert body["empty_reason"] is None
-        assert len(body["hits"]) == 1
-        assert "抽取终于跑通了" in body["hits"][0]["excerpt"]
-
-
-@pytest.mark.anyio
-async def test_search_groups_hits_and_keeps_title_separate_from_match(tmp_path) -> None:
-    app, transport = _client(tmp_path)
-    async with app.router.lifespan_context(app), transport as client:
-        app.state.evidence_store.put(message(verbatim="发布准备", message_id="title"))
-        app.state.evidence_store.put(
-            message(
-                verbatim="第一次提到公证",
-                message_id="match-1",
-                created_at=datetime(2026, 9, 3, 1, 18, tzinfo=UTC),
-            )
-        )
-        app.state.evidence_store.put(
-            message(
-                verbatim="第二次提到公证",
-                message_id="match-2",
-                created_at=datetime(2026, 9, 3, 1, 19, tzinfo=UTC),
-            )
-        )
-
-        response = await client.get("/api/v1/conversations/search", params={"query": "公证"})
-
-        assert response.status_code == 200
-        assert len(response.json()["hits"]) == 1
-        assert response.json()["hits"][0]["title"] == "发布准备"
-        assert response.json()["hits"][0]["excerpt"] == "第二次提到公证"
-        assert response.json()["hits"][0]["turn_count"] == 3
-        assert response.json()["hits"][0]["turn_offset"] == 0
-
-
-@pytest.mark.anyio
-async def test_nothing_imported_is_told_apart_from_nothing_matching(tmp_path) -> None:
-    app, transport = _client(tmp_path)
-    async with app.router.lifespan_context(app), transport as client:
-        empty = await client.get("/api/v1/conversations/search", params={"query": "抽取终于"})
-        assert empty.status_code == 200
-        assert empty.json()["empty_reason"] == "nothing_imported"
-
-        app.state.evidence_store.put(message(verbatim="周末想去爬山"))
-        unmatched = await client.get("/api/v1/conversations/search", params={"query": "量子纠缠"})
-
-        assert unmatched.status_code == 200
-        assert unmatched.json()["empty_reason"] == "no_matches"
-
-
-@pytest.mark.anyio
-async def test_a_broken_index_is_reported_rather_than_shown_as_no_matches(tmp_path) -> None:
-    app, transport = _client(tmp_path)
-    async with app.router.lifespan_context(app), transport as client:
-        app.state.evidence_store.put(message(verbatim="抽取终于跑通了"))
-        with sqlite3.connect(app.state.evidence_store.database_path) as connection:
-            connection.execute("DROP TABLE IF EXISTS evidence_search")
-
-        response = await client.get("/api/v1/conversations/search", params={"query": "抽取终于"})
-
-        assert response.status_code == 503
-        assert response.json()["detail"] == "conversation_search_unavailable"
-
-
-@pytest.mark.anyio
-async def test_a_hit_opens_the_conversation_it_came_from(tmp_path) -> None:
-    """Unverifiable facts read like invented ones, so the original has to open."""
-    app, transport = _client(tmp_path)
-    async with app.router.lifespan_context(app), transport as client:
-        app.state.evidence_store.put(
-            message(
-                verbatim="抽取终于跑通了",
-                message_id="m-1",
-                created_at=datetime(2026, 9, 3, 1, 17, tzinfo=UTC),
-            )
-        )
-        app.state.evidence_store.put(
-            message(
-                verbatim="那就先把包发出去",
-                message_id="m-2",
-                created_at=datetime(2026, 9, 3, 1, 19, tzinfo=UTC),
-            )
-        )
-
-        found = await client.get("/api/v1/conversations/search", params={"query": "抽取终于"})
-        evidence_id = found.json()["hits"][0]["evidence_id"]
-        transcript = await client.get(f"/api/v1/conversations/{evidence_id}")
-
-        assert transcript.status_code == 200
-        assert [item["verbatim"] for item in transcript.json()["messages"]] == [
-            "抽取终于跑通了",
-            "那就先把包发出去",
-        ]
-
-
-@pytest.mark.anyio
-async def test_assistant_only_conversation_opens_in_time_order(tmp_path) -> None:
-    app, transport = _client(tmp_path)
-    async with app.router.lifespan_context(app), transport as client:
-        first = app.state.evidence_store.put(
-            message(
-                verbatim="第一条助手回复",
-                message_id="assistant-only-1",
-                created_at=datetime(2026, 9, 3, 1, 17, tzinfo=UTC),
-            ).model_copy(update={"role": "assistant", "written_by": "agent"})
-        ).record
-        app.state.evidence_store.put(
-            message(
-                verbatim="第二条助手回复",
-                message_id="assistant-only-2",
-                created_at=datetime(2026, 9, 3, 1, 18, tzinfo=UTC),
-            ).model_copy(update={"role": "assistant", "written_by": "agent"})
-        )
-
-        transcript = await client.get(f"/api/v1/conversations/{first.evidence_id}")
-
-        assert transcript.status_code == 200
-        assert transcript.json()["total_turns"] == 1
-        assert [item["verbatim"] for item in transcript.json()["messages"]] == [
-            "第一条助手回复",
-            "第二条助手回复",
-        ]
-
-
-@pytest.mark.anyio
-async def test_conversation_browser_and_turn_pages_are_bounded(tmp_path) -> None:
-    app, transport = _client(tmp_path)
-    async with app.router.lifespan_context(app), transport as client:
-        first_id = ""
-        for turn in range(25):
-            stored = app.state.evidence_store.put(
-                message(
-                    verbatim=f"用户问题 {turn}",
-                    message_id=f"user-{turn:02d}",
-                    created_at=datetime(2026, 9, 3, 1, turn, tzinfo=UTC),
-                )
-            )
-            if turn == 0:
-                first_id = stored.record.evidence_id
-            assistant = message(
-                verbatim=f"助手回答 {turn}",
-                message_id=f"assistant-{turn:02d}",
-                created_at=datetime(2026, 9, 3, 1, turn, 30, tzinfo=UTC),
-            )
-            app.state.evidence_store.put(
-                assistant.model_copy(update={"role": "assistant", "written_by": "agent"})
-            )
-        app.state.evidence_store.put(
-            message(
-                verbatim="Codex 的同名会话",
-                source_id="codex",
-                conversation_id="conversation-1",
-                message_id="codex-1",
-            )
-        )
-
-        browser = await client.get("/api/v1/conversation-browser")
-        recent = await client.get(f"/api/v1/conversations/{first_id}", params={"limit": 20})
-        older = await client.get(
-            f"/api/v1/conversations/{first_id}", params={"offset": 20, "limit": 20}
-        )
-
-        assert browser.status_code == 200
-        assert browser.json()["total"] == 2
-        assert {
-            (item["source_id"], item["conversation_id"]) for item in browser.json()["items"]
-        } == {("cursor", "conversation-1"), ("codex", "conversation-1")}
-        assert recent.json()["total_turns"] == 25
-        assert recent.json()["has_more"] is True
-        assert len(recent.json()["messages"]) == 40
-        assert older.json()["has_more"] is False
-        assert len(older.json()["messages"]) == 10
-
-
-@pytest.mark.anyio
-async def test_conversation_memories_returns_only_linked_current_memories(tmp_path) -> None:
-    app, transport = _client(tmp_path)
-    async with app.router.lifespan_context(app), transport as client:
-        linked = app.state.evidence_store.put(
-            message(verbatim="发布前确认签名", message_id="linked")
-        ).record
-        other = app.state.evidence_store.put(
-            message(
-                verbatim="另一段会话",
-                conversation_id="other-conversation",
-                message_id="other",
-            )
-        ).record
-        app.state.person_writes.create(
-            MemoryDraft(
-                user_id="local",
-                kind=MemoryKind.WORKING,
-                content="发布前需要确认签名。",
-                scopes=("all-apps",),
-                evidence_ids=(linked.evidence_id,),
-            ),
-            request_id="linked-memory",
-        )
-        app.state.person_writes.create(
-            MemoryDraft(
-                user_id="local",
-                kind=MemoryKind.WORKING,
-                content="不属于这段对话。",
-                scopes=("all-apps",),
-                evidence_ids=(other.evidence_id,),
-            ),
-            request_id="other-memory",
-        )
-
-        response = await client.get(f"/api/v1/conversations/{linked.evidence_id}/memories")
-
-        assert response.status_code == 200
-        assert [item["content"] for item in response.json()["items"]] == ["发布前需要确认签名。"]

memhub/apps/core/tests/test_core_ready_before_recovery.py

@@ -0,0 +1,144 @@
+"""Readiness never waits for picking up work an earlier run left unfinished.
+
+A 1.0.4 home with pending imports and write jobs used to resume all of it
+before the lifespan yielded, so /health did not answer within the Runtime's
+60s budget and the Runtime killed a healthy Core, which then began the same
+recovery again. Recovery now runs after readiness.
+"""
+
+import asyncio
+import threading
+import time
+
+import pytest
+from httpx import ASGITransport, AsyncClient
+from pydantic import SecretStr
+
+from one_memory import hy_sdk_migration
+from one_memory.api import create_app
+from one_memory.config import Settings
+from one_memory.hy_sdk_migration import MetadataRepairResult
+from one_memory.secrets import InMemorySecretStore
+
+pytestmark = pytest.mark.fresh_sdk
+
+
+def application(tmp_path):
+    return create_app(
+        Settings(
+            data_dir=tmp_path / "data",
+            source_home=tmp_path,
+            api_token=SecretStr("ready-test"),
+            imports_enabled=False,
+            automatic_memory_processing=False,
+            live_sync_enabled=False,
+        ),
+        secret_store=InMemorySecretStore(),
+    )
+
+
+def client_for(app):
+    return AsyncClient(
+        transport=ASGITransport(app=app),
+        base_url="http://test",
+        headers={"Authorization": "Bearer ready-test"},
+    )
+
+
+async def health(client):
+    response = await client.get("/api/v1/health")
+    assert response.status_code == 200
+    return response.json()
+
+
+async def wait_for_recovery(client, *, seconds=10.0):
+    deadline = time.monotonic() + seconds
+    while time.monotonic() < deadline:
+        body = await health(client)
+        if body["recovery"] in {"done", "failed"}:
+            return body
+        await asyncio.sleep(0.01)
+    raise AssertionError("recovery did not finish")
+
+
+def test_core_is_ready_while_recovery_is_still_running(tmp_path, monkeypatch):
+    release = threading.Event()
+    entered = threading.Event()
+
+    def slow_repair(**_):
+        entered.set()
+        release.wait(10)
+        return MetadataRepairResult(None, 0, 0, 0)
+
+    monkeypatch.setattr(hy_sdk_migration, "repair_sdk_metadata_from_bundle", slow_repair)
+
+    async def scenario():
+        app = application(tmp_path)
+        try:
+            started = time.monotonic()
+            async with app.router.lifespan_context(app), client_for(app) as client:
+                # Startup finished although the first recovery step cannot.
+                assert time.monotonic() - started < 5
+                assert await asyncio.to_thread(entered.wait, 5)
+                body = await health(client)
+                assert body["status"] == "ok"
+                assert body["recovery"] == "running"
+                # Nothing after the blocked step has been started yet: the
+                # write drain in particular would hold the single writer.
+                assert app.state.memory_write_drain_task is None
+                # Reads answer during recovery.
+                assert (await client.get("/api/v1/sources")).status_code == 200
+                release.set()
+                body = await wait_for_recovery(client)
+                assert body["recovery"] == "done"
+                assert body["recovery_failed_steps"] == []
+                assert app.state.memory_write_drain_task is not None
+        finally:
+            release.set()
+
+    asyncio.run(scenario())
+
+
+def test_a_failed_recovery_step_does_not_stop_readiness_or_later_steps(tmp_path, monkeypatch):
+    def broken_repair(**_):
+        raise OSError("bundle unreadable")
+
+    monkeypatch.setattr(hy_sdk_migration, "repair_sdk_metadata_from_bundle", broken_repair)
+
+    async def scenario():
+        app = application(tmp_path)
+        async with app.router.lifespan_context(app), client_for(app) as client:
+            body = await wait_for_recovery(client)
+            assert body["status"] == "ok"
+            assert body["recovery"] == "failed"
+            assert body["recovery_failed_steps"] == ["sdk_metadata_repair"]
+            # The steps after the failed one still ran.
+            assert app.state.memory_write_drain_task is not None
+
+    asyncio.run(scenario())
+
+
+def test_shutdown_during_recovery_stops_it_without_starting_more(tmp_path, monkeypatch):
+    release = threading.Event()
+    entered = threading.Event()
+
+    def slow_repair(**_):
+        entered.set()
+        release.wait(10)
+        return MetadataRepairResult(None, 0, 0, 0)
+
+    monkeypatch.setattr(hy_sdk_migration, "repair_sdk_metadata_from_bundle", slow_repair)
+
+    async def scenario():
+        app = application(tmp_path)
+        try:
+            async with app.router.lifespan_context(app):
+                assert await asyncio.to_thread(entered.wait, 5)
+                recovery = app.state.recovery_task
+            # Shutdown cancelled recovery before it could start the drain.
+            assert recovery.done()
+            assert app.state.memory_write_drain_task is None
+        finally:
+            release.set()
+
+    asyncio.run(scenario())

memhub/apps/core/tests/test_credential_responsiveness.py

@@ -8,7 +8,6 @@ from test_onboarding_profile import _app, _client
 
 from one_memory.memory_qa import MemoryAnswerer
 from one_memory.model_probe import ModelProber
-from one_memory.secrets import SecretStoreUnavailableError
 
 
 def test_disabled_automatic_processing_does_not_digest_onboarding(tmp_path):
@@ -82,21 +81,3 @@ def test_model_probe_credential_lookup_is_off_loop(tmp_path, monkeypatch):
         transport=httpx.MockTransport(lambda request: httpx.Response(503)),
     )
     asyncio.run(prober.probe(profile.profile_id))
-
-
-def test_unavailable_credentials_keep_governed_graph_readable(tmp_path, monkeypatch):
-    async def scenario():
-        app = _app(tmp_path)
-        async with app.router.lifespan_context(app), _client(app) as client:
-
-            def denied(*args):
-                raise SecretStoreUnavailableError("private-system-error")
-
-            monkeypatch.setattr(app.state.model_profile_store, "active", denied)
-            response = await client.get("/api/v1/memories/graph")
-            assert response.status_code == 200
-            assert response.json()["hy_graph_available"] is False
-            assert "private-system-error" not in response.text
-            assert (await client.get("/api/v1/health")).status_code == 200
-
-    asyncio.run(scenario())

memhub/apps/core/tests/test_d93_same_process_load.py

@@ -1,314 +0,0 @@
-"""D93 test 2: read latency while pure-Python work holds the GIL.
-
-Plan `读写隔离方案-20261009.html` section 8 row 2, fixing the D92 experiment
-as a test. Three pure-Python busy threads stand in for Core's background work
-(scan, extraction bookkeeping, recompute). Meanwhile the home summary, the
-memory library page and the map are requested in a loop; every non-200 is an
-error and latencies give p95.
-
-Two targets:
-
-* `core` (default): the routes are served by `api.create_app` in this same
-  process, next to the busy threads. This is today's architecture and gives
-  the baseline. It is expected to be slow; it is measured, not gated, unless
-  `ONE_MEMORY_D93_GATE=1`.
-* `reader`: B's Reader is started as a separate process
-  (`one-memory serve --reader`) on the same library, the busy threads stay in
-  this process. This is the claim the plan makes: work in Core no longer
-  touches reads. Gated: 0 errors, home and library p95 below 1 second.
-
-Knobs: ONE_MEMORY_D93_LOAD_SECONDS (gate 600, default 20),
-ONE_MEMORY_D93_MEMORIES (default 600), ONE_MEMORY_D93_TARGET,
-ONE_MEMORY_D93_REPORT (JSON path for the numbers).
-Recall ("at least one hit on a known question") needs the HY supervisor and is
-not exercised here; it stays with acceptance item 7b.
-"""
-
-from __future__ import annotations
-
-import asyncio
-import json
-import os
-import socket
-import sqlite3
-import subprocess
-import sys
-import threading
-import time
-from pathlib import Path
-
-import httpx
-import pytest
-from pydantic import SecretStr
-
-from one_memory import api
-from one_memory.config import Settings
-from one_memory.imports.grants import GRANT_SCHEMA
-from one_memory.imports.models import EvidenceInput, EvidenceOrigin, OriginMetadata, WrittenBy
-from one_memory.imports.storage import EvidenceStore
-from one_memory.memory_governance import MemoryDraft, MemoryGovernanceStore, MemoryKind
-from one_memory.memory_tasks import MemoryTaskOutput, MemoryTaskStore, evidence_ref
-from tests.person_door import as_person
-
-SECONDS = float(os.environ.get("ONE_MEMORY_D93_LOAD_SECONDS", "20"))
-MEMORIES = int(os.environ.get("ONE_MEMORY_D93_MEMORIES", "600"))
-TARGET = os.environ.get("ONE_MEMORY_D93_TARGET", "core")
-GATE = os.environ.get("ONE_MEMORY_D93_GATE", "1" if TARGET == "reader" else "") == "1"
-TOKEN = "d93-load-token"
-AUTH = {"Authorization": f"Bearer {TOKEN}"}
-ROUTES = (
-    ("home", "/api/v1/home-summary", {}),
-    ("library", "/api/v1/memory-library", {"limit": 100, "active_only": "true"}),
-    ("map", "/api/v1/memories/graph", {"limit": 160}),
-)
-
-
-def _build_library(database: Path) -> None:
-    now = "2026-10-09T00:00:00+00:00"
-    with sqlite3.connect(database) as setup:
-        setup.executescript(GRANT_SCHEMA)
-        for source in ("cursor", "codex"):
-            setup.execute(
-                "INSERT INTO source_grants "
-                "(user_id,source_id,root_path,requested_path,root_identity,"
-                "candidate_kind,granted_at,revoked_at,revision) "
-                "VALUES ('local',?,?,?,'fixture','default',?,NULL,1)",
-                (source, f"/fixture/{source}", f"/fixture/{source}", now),
-            )
-    evidence = EvidenceStore(database)
-    tasks = MemoryTaskStore(database)
-    person = as_person(MemoryGovernanceStore(database))
-    for index in range(MEMORIES):
-        record = evidence.put(
-            EvidenceInput(
-                source_id=("cursor", "codex")[index % 2],
-                conversation_id=f"conversation-{index // 10}",
-                message_id=f"m-{index}",
-                correlation_id=f"m-{index}",
-                role="user",
-                written_by=WrittenBy.PERSON,
-                verbatim=f"第 {index} 条对话原文，讨论读写隔离和记忆页的加载速度。" * 4,
-                origin_meta={EvidenceOrigin.FILE: OriginMetadata()},
-            )
-        ).record
-        memory = person.create(
-            MemoryDraft(
-                user_id="local",
-                kind=MemoryKind.CHAT,
-                content=f"记忆 {index}：读写隔离要让记忆页在后台忙时也能打开。",
-                scopes=("all-apps",),
-                evidence_ids=(record.evidence_id,),
-            ),
-            request_id=f"create-{index}",
-        )
-        tasks.save_output(
-            MemoryTaskOutput(
-                task_id=f"task-{index}",
-                memory_id=memory.memory_id,
-                memory_revision=memory.revision,
-                hy_memory_id=f"hy-{index}",
-                owner="user",
-                layer="L2_FACT",
-                engine_version="fixture",
-                support_refs=(evidence_ref(record),),
-            )
-        )
-
-
-class _Busy:
-    """Three pure-Python threads: no I/O, no sleep, they only want the GIL."""
-
-    def __init__(self, count: int = 3) -> None:
-        self.stop = threading.Event()
-        self.loops = [0] * count
-        self.threads = [
-            threading.Thread(target=self._spin, args=(index,), daemon=True)
-            for index in range(count)
-        ]
-
-    def _spin(self, index: int) -> None:
-        while not self.stop.is_set():
-            total = 0
-            for value in range(20_000):
-                total += value * value % 7
-            self.loops[index] += 1
-
-    def __enter__(self):
-        for thread in self.threads:
-            thread.start()
-        return self
-
-    def __exit__(self, *_):
-        self.stop.set()
-        for thread in self.threads:
-            thread.join(timeout=5)
-
-
-_SPIN = """
-import threading
-def spin():
-    while True:
-        total = 0
-        for value in range(20_000):
-            total += value * value % 7
-for _ in range(3):
-    threading.Thread(target=spin, daemon=True).start()
-threading.Event().wait()
-"""
-
-
-def _p95(values: list[float]) -> float | None:
-    if not values:
-        return None
-    ordered = sorted(values)
-    return ordered[min(len(ordered) - 1, int(round(0.95 * (len(ordered) - 1))))]
-
-
-async def _drive(client: httpx.AsyncClient, deadline: float) -> dict:
-    stats = {name: {"ok": 0, "errors": {}, "latency": []} for name, _, _ in ROUTES}
-    while time.monotonic() < deadline:
-        for name, url, params in ROUTES:
-            started = time.monotonic()
-            try:
-                response = await client.get(url, params=params, headers=AUTH, timeout=30)
-                code = str(response.status_code)
-            except httpx.HTTPError as error:
-                code = type(error).__name__
-            elapsed = time.monotonic() - started
-            entry = stats[name]
-            entry["latency"].append(elapsed)
-            if code == "200":
-                entry["ok"] += 1
-            else:
-                entry["errors"][code] = entry["errors"].get(code, 0) + 1
-    return {
-        name: {
-            "requests": len(entry["latency"]),
-            "ok": entry["ok"],
-            "errors": entry["errors"],
-            "p95_seconds": _p95(entry["latency"]),
-            "max_seconds": max(entry["latency"], default=None),
-        }
-        for name, entry in stats.items()
-    }
-
-
-def _core_app(data_dir: Path, root: Path):
-    """Core as the app runs it (lifespan included), background processing off."""
-    return api.create_app(
-        Settings(
-            data_dir=data_dir,
-            source_home=root / "home",
-            api_token=SecretStr(TOKEN),
-            automatic_memory_processing=False,
-            live_sync_enabled=False,
-        ),
-        source_catalog={},
-    )
-
-
-def _free_port() -> int:
-    with socket.socket() as probe:
-        probe.bind(("127.0.0.1", 0))
-        return probe.getsockname()[1]
-
-
-def _start_reader(data_dir: Path) -> tuple[subprocess.Popen, str]:
-    pytest.importorskip("one_memory.reader_app", reason="B (Reader) not in this build")
-    port = _free_port()
-    env = {
-        **os.environ,
-        "ONE_MEMORY_DATA_DIR": str(data_dir),
-        "ONE_MEMORY_READER_PORT": str(port),
-        "ONE_MEMORY_API_TOKEN": TOKEN,
-        "ONE_MEMORY_CORE_PORT": str(_free_port()),  # nothing there: Core-only parts degrade
-    }
-    process = subprocess.Popen(
-        [sys.executable, "-m", "one_memory.cli", "serve", "--reader"],
-        env=env,
-        stdout=subprocess.DEVNULL,
-        stderr=subprocess.PIPE,
-    )
-    base = f"http://127.0.0.1:{port}"
-    for _ in range(100):
-        try:
-            if httpx.get(f"{base}/health", timeout=0.5).status_code < 500:
-                return process, base
-        except httpx.HTTPError:
-            pass
-        if process.poll() is not None:
-            raise AssertionError(f"Reader exited: {process.stderr.read()[-2000:]!r}")
-        time.sleep(0.1)
-    process.kill()
-    raise AssertionError("Reader did not answer /health within 10 seconds")
-
-
-def test_reads_stay_up_while_python_threads_hold_the_gil(tmp_path):
-    data_dir = tmp_path / "data"
-    data_dir.mkdir()
-    database = data_dir / "one-memory.sqlite3"
-    _build_library(database)
-
-    async def run(client):
-        # Warm once outside the measurement so lazy imports do not count.
-        for _, url, params in ROUTES:
-            await client.get(url, params=params, headers=AUTH, timeout=30)
-        idle = await _drive(client, time.monotonic() + min(5.0, SECONDS))
-        if TARGET == "reader":
-            # The busy threads belong to Core, not to this client: put them in
-            # a process of their own so the client does not queue for the GIL.
-            spinner = subprocess.Popen([sys.executable, "-c", _SPIN])
-            try:
-                loaded = await _drive(client, time.monotonic() + SECONDS)
-            finally:
-                spinner.terminate()
-                spinner.wait(timeout=10)
-            return idle, loaded, [1, 1, 1]
-        with _Busy() as busy:
-            loaded = await _drive(client, time.monotonic() + SECONDS)
-        return idle, loaded, busy.loops
-
-    reader = None
-    try:
-        if TARGET == "reader":
-            reader, base = _start_reader(data_dir)
-            transport = httpx.AsyncHTTPTransport()
-            application = None
-        else:
-            base = "http://test"
-            application = _core_app(data_dir, tmp_path)
-            transport = httpx.ASGITransport(app=application)
-
-        async def main():
-            async with httpx.AsyncClient(transport=transport, base_url=base) as client:
-                if application is None:
-                    return await run(client)
-                async with application.router.lifespan_context(application):
-                    return await run(client)
-
-        idle, loaded, loops = asyncio.run(main())
-    finally:
-        if reader is not None:
-            reader.terminate()
-            reader.wait(timeout=10)
-
-    report = {
-        "target": TARGET,
-        "memories": MEMORIES,
-        "seconds": SECONDS,
-        "busy_loops": loops,
-        "idle": idle,
-        "loaded": loaded,
-    }
-    path = os.environ.get("ONE_MEMORY_D93_REPORT")
-    if path:
-        Path(path).write_text(json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8")
-    print(json.dumps(report, ensure_ascii=False))
-
-    assert all(count > 0 for count in loops), "busy threads never ran"
-    assert all(entry["requests"] > 0 for entry in loaded.values())
-    if GATE:
-        for name, entry in loaded.items():
-            assert entry["errors"] == {}, f"{name}: {entry['errors']}"
-        for name in ("home", "library"):
-            assert loaded[name]["p95_seconds"] < 1.0, f"{name} p95 {loaded[name]['p95_seconds']}"

memhub/apps/core/tests/test_derived_echo.py

@@ -1,86 +1,5 @@
 """A host that saves our injection back must not mint a new user decision."""
 
-import sqlite3
-from contextlib import closing
-from uuid import uuid4
-
-from one_memory.change_outbox import ChangeOutbox, evidence_event_id
-from one_memory.derived_echo import render_reference
-from one_memory.imports.models import EvidenceInput, EvidenceOrigin, OriginMetadata, WrittenBy
-from one_memory.imports.storage import EvidenceStore
-from one_memory.session_inbox import SessionInbox
-from one_memory.session_registry import SessionRegistry
-
-
-def _evidence(message_id: str, verbatim: str) -> EvidenceInput:
-    return EvidenceInput(
-        source_id="workbuddy",
-        conversation_id="session-b",
-        message_id=message_id,
-        role="assistant",
-        written_by=WrittenBy.PERSON,
-        verbatim=verbatim,
-        origin_meta={EvidenceOrigin.FILE: OriginMetadata(raw_meta={"root": "proj"})},
-    )
-
-
-def test_a_restatement_is_not_broadcast_and_a_correction_still_is(tmp_path) -> None:
-    path = tmp_path / "one-memory.sqlite3"
-    store = EvidenceStore(path)
-    registry = SessionRegistry(path)
-    registry.initialize()
-    inbox = SessionInbox(path)
-    inbox.initialize()
-    opened = registry.open(
-        installation_id=str(uuid4()),
-        host_id="workbuddy",
-        native_session_id="session-b",
-        runtime_instance="runtime-1",
-        workspace="/work/same-project",
-    )
-    inbox.subscribe(opened.session_key, ("workbuddy",), permission_epoch=1)
-    with closing(sqlite3.connect(path)) as db:
-        db.row_factory = sqlite3.Row
-        db.execute("BEGIN IMMEDIATE")
-        decision = store.put(_evidence("decision", "周五前交一版"), connection=db)
-        ChangeOutbox(path).record(
-            db,
-            event_id=evidence_event_id(decision.record.evidence_id, decision.record.revision),
-            cause="import",
-            evidence_id=decision.record.evidence_id,
-            evidence_revision=decision.record.revision,
-            permission_epoch=0,
-        )
-        db.commit()
-    page = inbox.pull(opened.session_key, cursor=None, limit=8)
-    injected = render_reference(page.events)
-    with closing(sqlite3.connect(path)) as db:
-        db.row_factory = sqlite3.Row
-        db.execute("BEGIN IMMEDIATE")
-        store.put(_evidence("echo", injected), connection=db)
-        db.commit()
-    with closing(sqlite3.connect(path)) as db:
-        assert db.execute("SELECT COUNT(*) FROM change_outbox").fetchone()[0] == 1
-    echoed = inbox.pull(opened.session_key, cursor=page.cursor, limit=8)
-    assert echoed.events == ()
-    with closing(sqlite3.connect(path)) as db:
-        db.row_factory = sqlite3.Row
-        db.execute("BEGIN IMMEDIATE")
-        correction = store.put(
-            _evidence("correction", injected + "\n不对，改成下周三"), connection=db
-        )
-        ChangeOutbox(path).record(
-            db,
-            event_id=evidence_event_id(correction.record.evidence_id, correction.record.revision),
-            cause="import",
-            evidence_id=correction.record.evidence_id,
-            evidence_revision=correction.record.revision,
-            permission_epoch=0,
-        )
-        db.commit()
-    corrected = inbox.pull(opened.session_key, cursor=page.cursor, limit=8)
-    assert len(corrected.events) == 1
-
 
 def test_stripping_removes_the_notice_block_as_well_as_the_memory_block() -> None:
     from one_memory.derived_echo import strip_injected_memory

memhub/apps/core/tests/test_detailed_logging.py

@@ -110,11 +110,24 @@ def test_log_level_document_migrates_the_old_boolean_shape(tmp_path: Path) -> No
     assert json.loads(target.read_text()) == {"schema_version": 2, "level": "error"}
 
 
-def test_configure_environment_passes_debug_content_settings_to_sdk(tmp_path: Path) -> None:
+def test_configure_environment_passes_debug_content_settings_to_sdk(
+    tmp_path: Path, monkeypatch
+) -> None:
+    for name in (
+        "MEMORY_DATA_DIR",
+        "MEMORY_LOG_DIR",
+        "MEMORY_LOG_LEVEL",
+        "MEMORY_PIPELINE_TRACE_ENABLED",
+        "MEMORY_LOG_LLM_CONTENT",
+    ):
+        monkeypatch.delenv(name, raising=False)
     set_diagnostic_log_level(tmp_path, "debug")
     configure_hy_runtime_environment(tmp_path)
 
     environment = __import__("os").environ
+    memory_root = tmp_path / "hy-memory" / "governed-v2"
+    assert environment["MEMORY_DATA_DIR"] == str(memory_root)
+    assert environment["MEMORY_LOG_DIR"] == str(memory_root / "logs")
     assert environment["MEMORY_LOG_LEVEL"] == "DEBUG"
     assert environment["MEMORY_PIPELINE_TRACE_ENABLED"] == "true"
     assert environment["MEMORY_LOG_LLM_CONTENT"] == "true"

memhub/apps/core/tests/test_diagnostic_log.py

@@ -561,11 +561,11 @@ def test_database_error_records_safe_route_and_sqlite_code(tmp_path, monkeypatch
     error.sqlite_errorcode = sqlite3.SQLITE_BUSY
     error.sqlite_errorname = "SQLITE_BUSY"
     try:
-        record_database_error("core.api", error, route_path="/api/v1/context/search")
+        record_database_error("core.api", error, route_path="/api/v2/context/search")
     finally:
         reset_diagnostics()
     payload = json.loads(receipt.path.read_text().splitlines()[-1])
-    assert payload["details"]["route_path"] == "/api/v1/context/search"
+    assert payload["details"]["route_path"] == "/api/v2/context/search"
     assert payload["details"]["sqlite_errorcode"] == sqlite3.SQLITE_BUSY
     assert payload["details"]["sqlite_errorname"] == "SQLITE_BUSY"
 

memhub/apps/core/tests/test_external_installation_permissions.py

@@ -7,7 +7,6 @@ from pydantic import SecretStr
 
 from one_memory.api import create_app
 from one_memory.config import Settings
-from one_memory.imports.models import EvidenceInput, EvidenceOrigin, OriginMetadata, WrittenBy
 
 
 def headers(*, scopes=("all-apps",), tools=("om_recall",)):
@@ -51,12 +50,14 @@ def test_external_marker_is_not_an_installation_grant(tmp_path):
             )
             assert approved.status_code == 200
             denied_tool = await client.post(
-                "/api/v1/memories/ask", json={"question": "history"}, headers=headers()
+                "/api/v2/memories/ask", json={"question": "history"}, headers=headers()
             )
             assert denied_tool.status_code == 403
-            no_raw = await client.get(
-                "/api/v1/conversations/search",
-                params={"query": "history"},
+            # om_conversations reaches Core only as the v2 raw lane, and only
+            # with a source grant: all-apps alone opens no raw source.
+            no_raw = await client.post(
+                "/api/v2/context/search",
+                json={"query": "history", "kinds": ["raw"]},
                 headers=headers(tools=("om_conversations",)),
             )
             assert no_raw.status_code == 403
@@ -99,48 +100,3 @@ def test_external_diagnostic_trace_uses_its_own_read_only_tool(tmp_path):
             assert denied.status_code == 403
 
     asyncio.run(scenario())
-
-
-def test_raw_source_grants_filter_before_limit_and_private_body_loading(tmp_path):
-    async def scenario():
-        app = create_app(
-            Settings(
-                data_dir=tmp_path,
-                source_home=tmp_path,
-                api_token=SecretStr("test"),
-                automatic_memory_processing=False,
-                live_sync_enabled=False,
-            ),
-            source_catalog={},
-        )
-        async with (
-            app.router.lifespan_context(app),
-            AsyncClient(
-                transport=ASGITransport(app=app),
-                base_url="http://test",
-                headers={"Authorization": "Bearer test"},
-            ) as client,
-        ):
-            for source in ("allowed", "denied"):
-                app.state.evidence_store.put(
-                    EvidenceInput(
-                        source_id=source,
-                        conversation_id="one",
-                        message_id="one",
-                        role="user",
-                        written_by=WrittenBy.PERSON,
-                        verbatim="needle " + source,
-                        origin_meta={EvidenceOrigin.FILE: OriginMetadata()},
-                    )
-                )
-            result = await client.get(
-                "/api/v1/conversations/search",
-                params={"query": "needle", "limit": 1},
-                headers=headers(scopes=("all-apps", "source:allowed"), tools=("om_conversations",)),
-            )
-            assert result.status_code == 200
-            assert result.json()["imported_messages"] == 1
-            assert [hit["source_id"] for hit in result.json()["hits"]] == ["allowed"]
-            assert "needle denied" not in result.text
-
-    asyncio.run(scenario())

memhub/apps/core/tests/test_health.py

@@ -45,6 +45,9 @@ def test_health_reports_the_single_core() -> None:
         "memory_backfill_error": None,
         "content_candidate_backfill": "idle",
         "content_candidate_backfill_failure": None,
+        # No lifespan ran, so recovery has not begun.
+        "recovery": "pending",
+        "recovery_failed_steps": [],
     }
 
 
@@ -210,6 +213,8 @@ def test_lifespan_drains_committed_pending_dispatch_through_enqueue(tmp_path, mo
 
     async def scenario() -> None:
         async with app.router.lifespan_context(app):
+            # Replayed by the recovery that runs after readiness.
+            await app.state.recovery_task
             assert record.evidence_id in seen
             assert evidence.take_all_stable_records() == ()
 
@@ -434,6 +439,7 @@ def test_a_backfill_that_fails_says_so_rather_than_disappearing(tmp_path, monkey
             app.router.lifespan_context(app),
             AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as client,
         ):
+            await app.state.recovery_task
             await app.state.memory_backfill
 
             response = await client.get("/api/v1/health")
@@ -497,6 +503,7 @@ def test_a_failed_catch_up_leaves_a_traceback_behind(tmp_path, monkeypatch, capl
             app.router.lifespan_context(app),
             AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as client,
         ):
+            await app.state.recovery_task
             with suppress(BaseException):
                 await app.state.memory_backfill
             return (await client.get("/api/v1/health")).json()