Release TMCRA Agent Memory v2026.07.18

Publish the Apache-2.0 TMCRA Agent Memory release, LongMemEval S500 scorecard (82.2%), bilingual model card, reproducibility pipeline, and sanitized inference-only graph scoring weights. The previous default snapshot is preserved as legacy-2026.05.25.

AUTHORS.md

@@ -0,0 +1,25 @@
+# Developers and attribution
+
+## Core project
+
+- **Yu Haoxin** ([@reshuibuduo](https://github.com/reshuibuduo)) — project creator, lead developer, and TMCRA algorithm engineering.
+
+## Development assistance
+
+- **OpenAI Codex** — development and reproducibility engineering assistant, including code organization, benchmark packaging, documentation, and release validation support.
+
+OpenAI Codex is credited here as an AI development assistant; project ownership and release responsibility remain with Yu Haoxin.
+
+---
+
+# 开发者与署名
+
+## 核心项目
+
+- **Yu Haoxin**（[@reshuibuduo](https://github.com/reshuibuduo)）— 项目创建者、主要开发者与 TMCRA 算法工程。
+
+## 开发协助
+
+- **OpenAI Codex** — 开发与可复现性工程助手，协助完成代码整理、benchmark 封装、文档编写和发布校验。
+
+OpenAI Codex 在此作为 AI 开发助手署名；项目所有权与发布责任归 Yu Haoxin 所有。

CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 2026.07.18
+
+- Repositioned TMCRA as an Agent Memory Engine with a clear Source / Fast /
+  Slow layered architecture and scope isolation.
+- Added the maintained LongMemEval-S500 reproduction package.
+- Published the 82.2% scorecard with six task-level results.
+- Added the latest node scorer, path scorer, and retrieval reranker weights.
+- Hardened checkpoint loading with `weights_only=True`, published an
+  inference-only reranker checkpoint without training-machine paths, pinned
+  third-party model revisions, and added offline CI and gold-isolation checks.
+- Versioned the maintained answer contract as `evidence_operation_bound_v6`
+  and made compatible interrupted benchmark stages resumable.
+- Switched the project license to Apache-2.0.
+- Credited Yu Haoxin and OpenAI Codex for their respective development roles.

CITATION.cff

@@ -0,0 +1,27 @@
+cff-version: 1.2.0
+message: "If you use TMCRA, please cite this software. OpenAI Codex assisted with development and reproducibility engineering."
+title: "TMCRA — Agent Memory Engine"
+type: software
+version: "2026.07.18"
+date-released: 2026-07-18
+license: Apache-2.0
+authors:
+  - family-names: Yu
+    given-names: Haoxin
+    alias: reshuibuduo
+    website: "https://github.com/reshuibuduo"
+  - name: "OpenAI Codex"
+    website: "https://openai.com/codex/"
+repository-code: "https://github.com/reshuibuduo/TMCRA-Agent-Memory"
+url: "https://github.com/reshuibuduo/TMCRA-Agent-Memory"
+abstract: >-
+  TMCRA is an agent memory engine that builds scope-isolated, source-traceable
+  memory from long-running conversations and compiles relevant evidence for
+  downstream agents. This release includes the algorithm snapshot, learned
+  graph-scoring artifacts, and a reproducible LongMemEval pipeline.
+keywords:
+  - agent memory
+  - long-term memory
+  - memory graph
+  - retrieval
+  - LongMemEval

LICENSE

@@ -1,21 +1,201 @@
-MIT License
-
-Copyright (c) 2026 TMCRA contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Yu Haoxin and TMCRA contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

NOTICE

@@ -0,0 +1,9 @@
+TMCRA — Agent Memory Engine
+Copyright 2026 Yu Haoxin and TMCRA contributors
+
+Development and reproducibility engineering assistance was provided by
+OpenAI Codex. See AUTHORS.md for contributor roles.
+
+This product includes or adapts third-party software and model interfaces.
+The corresponding copyright notices and license terms are documented in
+benchmarks/longmemeval/THIRD_PARTY_NOTICES.md.

README.md

@@ -1,207 +1,115 @@
-# TMCRA Long-Memory Runtime
+---
+license: apache-2.0
+library_name: pytorch
+language:
+  - en
+  - zh
+tags:
+  - agent-memory
+  - long-term-memory
+  - memory-graph
+  - information-retrieval
+  - longmemeval
+  - pytorch
+---
+
+# TMCRA — Agent Memory Engine
 
 <p align="center">
   <img src="assets/tmcra-logo.png" alt="TMCRA logo" width="420">
 </p>
 
-[中文版本](README.zh-CN.md)
-
-TMCRA is a runtime layer that gives agent systems long-term memory. It helps an LLM retrieve, connect, and reason over long dialogue histories without exposing the full conversation context on every turn.
-
-This repository contains a frozen TMCRA baseline package with model weights, runtime code snapshots, training metadata, and LongMemEval S500 benchmark results.
-
-License: MIT.
-
-## What TMCRA Does
-
-TMCRA adds a dedicated memory runtime between an agent application and its answer model.
-
-At write time, TMCRA turns dialogue into memory nodes, event units, profile signals, and graph paths. This lets the system preserve not only isolated facts, but also relationships between facts across turns and sessions.
+<p align="center">
+  <a href="README.zh-CN.md">简体中文</a> ·
+  <a href="https://github.com/reshuibuduo/TMCRA-Agent-Memory">GitHub</a> ·
+  <a href="https://github.com/reshuibuduo/TMCRA-Agent-Memory/releases/tag/v2026.07.18">Release v2026.07.18</a>
+</p>
 
-At retrieval time, TMCRA scores graph nodes and paths, selects compact evidence, and injects only the most relevant memory context into the answer model. The answer model still performs natural-language reasoning, while TMCRA handles long-memory organization, recall, and evidence surfacing.
+TMCRA is a memory engine for long-running agents. It converts multi-turn and multi-session conversations into scope-isolated, source-traceable memory, then recalls compact evidence after the user's next question arrives.
 
-The current runtime focuses on:
+This Hugging Face repository contains the Apache-2.0 release of the TMCRA algorithm, its LongMemEval reproduction pipeline, and the inference-only graph scoring weights used by the released benchmark chain. Hosted APIs, accounts, billing, and production control-plane services are not included.
 
-- user fact memory
-- assistant-response memory
-- profile and preference memory
-- temporal memory
-- cross-session graph tunneling
-- learned node/path scoring
-- compact evidence selection for downstream LLMs
+## LongMemEval S500
 
-## Algorithm Structure
+TMCRA achieved **411 / 500 = 82.2%**.
 
-```mermaid
-flowchart LR
-    A["Dialogue Turns"] --> B["Writer Layer"]
-    B --> C["Memory Nodes"]
-    B --> D["Event Units"]
-    B --> E["Profile Signals"]
-    B --> F["Temporal Signals"]
+| Task category | Correct / Total | Accuracy |
+| --- | ---: | ---: |
+| Knowledge Update | 71 / 78 | 91.0% |
+| Multi-session | 90 / 133 | 67.7% |
+| Single-session Assistant | 55 / 56 | 98.2% |
+| Single-session Preference | 27 / 30 | 90.0% |
+| Single-session User | 67 / 70 | 95.7% |
+| Temporal Reasoning | 101 / 133 | 75.9% |
+| **Overall** | **411 / 500** | **82.2%** |
 
-    C --> G["Graph Memory Store"]
-    D --> G
-    E --> G
-    F --> G
+The machine-readable scorecard is [`results/latest_benchmark.json`](results/latest_benchmark.json). The maintained reproduction entrypoint is [`benchmarks/longmemeval/`](benchmarks/longmemeval/README.md). The benchmark answer layer is fixed to GPT-5.4; fresh runs that call external model services can vary slightly.
 
-    G --> H["Learned Node Scorer"]
-    G --> I["Learned Path Scorer"]
-    H --> J["Evidence Selection"]
-    I --> J
+## Architecture
 
-    J --> K["Compact Memory Context"]
-    K --> L["Answer Model"]
-    L --> M["Agent Response"]
+TMCRA separates memory construction from downstream answer generation.
 
-    N["User Query"] --> H
-    N --> I
-    N --> J
-    N --> L
+```text
+Conversation history
+        │
+        ▼
+      Writer ─────────────── subject / entity attribution
+        │
+        ├── Source layer ─── immutable, traceable evidence
+        ├── Fast layer ───── atomic current-state memory
+        └── Slow layer ───── durable semantic graph
+                 │
+                 └────────── scope-bound indexes
+
+New question
+        │
+        ▼
+Recall Planner → layered retrieval → node/path scoring → reranker
+        │
+        ▼
+Source-bound evidence packet → downstream agent
 ```
 
-The writer layer produces memory units from dialogue. The graph memory store preserves facts, events, profile signals, temporal signals, and cross-session links. The learned node/path scorers select relevant evidence for the current query, and the answer model uses that compact evidence to produce the final response.
+The TMCRA core ends at the evidence packet. The answer model and benchmark judge are harness components, not part of the online memory engine. User statements and assistant progress remain separately attributed, while both can be recalled when relevant.
 
-## Why TMCRA
+## Released weights
 
-Long-running agents need more than simple vector recall. They need to preserve user facts, preferences, timeline changes, cross-session events, and multi-step evidence chains.
+All three checkpoints contain only their public inference contracts and model state. Training state, machine paths, and private run metadata are excluded. Load them with `torch.load(..., weights_only=True)` through the repository runtime.
 
-TMCRA organizes memory into graph nodes and learned retrieval paths, then surfaces compact evidence to the answer model. The goal is to let external agents use long-term memory through a runtime/API layer while keeping the memory algorithm and model weights independently deployable.
+| File | Purpose | Size | SHA-256 |
+| --- | --- | ---: | --- |
+| `node_scorer.pt` | Graph node scoring | 207,356,243 bytes | `d2318aafb07f9a15a1d95e6eac1b3e09afa07c570dd9d15d3f75544c9950f201` |
+| `path_scorer.pt` | Graph path scoring | 207,356,243 bytes | `ecdc2bca51b7646a8a56c7db9cea4aeec581e64c3b61e6e06f7e9fa2a93b3bf5` |
+| `tmcra_v3_reranker.pt` | Learned retrieval reranking | 4,232,213 bytes | `09a285b484ca857b24b53ad19d5998302f16d224ca9e4fd73a4eb5a52f022942` |
 
-## How to Use
+The files and their machine-readable contract are under [`models/tmcra_v4_longmemeval_s500_20260715/`](models/tmcra_v4_longmemeval_s500_20260715/README.md).
 
-For inference/runtime use, load the graph scorer weights from:
-
-```text
-models/action_frame_tunnel_graph548_tunnel_fusion_train_20260524_042557/
-```
+## Download
 
-The main runtime files are:
-
-```text
-node_scorer.pt
-path_scorer.pt
-export_manifest.json
-```
-
-A typical runtime configuration points TMCRA to these weights:
+Install the current Hugging Face CLI and download only the released inference package:
 
 ```bash
-export TMCRA_NODE_MODEL_PATH="models/action_frame_tunnel_graph548_tunnel_fusion_train_20260524_042557/node_scorer.pt"
-export TMCRA_PATH_MODEL_PATH="models/action_frame_tunnel_graph548_tunnel_fusion_train_20260524_042557/path_scorer.pt"
-export TMCRA_RETRIEVAL_MODE="hybrid_node_scored"
-export TMCRA_REQUIRE_LEARNED_SCORER="1"
-```
-
-The evaluation entrypoint snapshot is:
+python -m pip install -U huggingface_hub
 
-```text
-code/run_lme_s10_native_tmcra.py
-```
-
-The core adapter snapshot is:
-
-```text
-code/memory_adapters.py
+hf download 2009YU/TMCRA-Agent-Memory \
+  --include "models/tmcra_v4_longmemeval_s500_20260715/*" \
+  --local-dir ./TMCRA-Agent-Memory
 ```
 
-For a deployment build, load the two scorer files into the TMCRA adapter and point the agent's memory middleware to the TMCRA retrieval API. The answer model can be any OpenAI-compatible or local LLM endpoint; TMCRA supplies the selected memory evidence, and the answer model produces the final response.
-
-## Dependency Environment
+For source, benchmark setup, environment examples, asset checksums, and stage validation, use the [GitHub release](https://github.com/reshuibuduo/TMCRA-Agent-Memory/releases/tag/v2026.07.18) or [`benchmarks/longmemeval/README.md`](benchmarks/longmemeval/README.md).
 
-The included code snapshot is Python-based. A practical runtime environment should include:
+## Version history
 
-- Python 3.10 or newer
-- PyTorch, with CUDA recommended for model inference
-- NumPy and standard Python data-processing libraries
-- an OpenAI-compatible or local LLM endpoint for the answer layer and writer layer
-- optional Git LFS support when pulling the full model package from GitHub
+- Current release: [`v2026.07.18`](https://huggingface.co/2009YU/TMCRA-Agent-Memory/tree/v2026.07.18)
+- Preserved pre-release snapshot: [`legacy-2026.05.25`](https://huggingface.co/2009YU/TMCRA-Agent-Memory/tree/legacy-2026.05.25)
 
-The benchmark scripts expect LongMemEval-format input data and write JSONL predictions and judge outputs. Runtime deployments can use the same model files without running the benchmark harness.
+## Developers
 
-## Optional Modules
+- **Yu Haoxin** — creator, lead developer, and TMCRA algorithm engineering.
+- **OpenAI Codex** — development and reproducibility engineering assistant.
 
-TMCRA also keeps optional extension points for retrieval and planning experiments. These modules can be enabled in deployment or evaluation builds when the target use case needs them.
+See [`AUTHORS.md`](AUTHORS.md) and [`CITATION.cff`](CITATION.cff) for attribution and citation details.
 
-- **Embedder interface**: an optional semantic embedding channel that can run alongside the graph-memory scorer. It is intended to provide additional dense semantic recall before or during graph evidence selection, without replacing the learned graph node/path scorers.
-- **LLM planner interface**: an optional planner hook that can use an external LLM to organize evidence, expand query intent, or create an answer plan before the final answer call. This is useful for experiments and higher-cost deployments, while the default baseline keeps the core graph scorer path independently measurable.
+## License
 
-These interfaces are integration points, not required dependencies for the frozen S500 baseline. They are designed so downstream deployments can decide whether to run a lighter scorer-only path or a heavier path with embedder/planner assistance.
-
-## Included Artifacts
-
-- `code/`: runtime and evaluation code snapshot for this baseline.
-- `models/action_frame_tunnel_graph548_tunnel_fusion_train_20260524_042557/`: full trained graph-model output directory.
-- `results/`: predictions, judge output, summary metrics, and compressed run artifacts.
-- `docs/`: baseline record and result notes.
-
-Additional documentation:
-
-- `docs/BASELINE_S500_20260525.md`: benchmark record and subtask metrics.
-- `docs/TRAINING.md`: model training direction and released training artifacts.
-- `docs/OPTIONAL_MODULES_AND_PARALLEL.md`: optional embedder/planner integration points and parallel evaluation plan.
-- `docs/OPTIONAL_MODULES_AND_PARALLEL.zh-CN.md`: Chinese version of the optional module and parallel evaluation guide.
-
-## Model Package
-
-The included model package preserves the full training output for the graph scorer stack:
-
-- `node_scorer.pt` and `path_scorer.pt`: runtime graph scoring weights.
-- `node_scorer_best.pt` and `path_scorer_best.pt`: best checkpoint aliases.
-- `node_scorer_last.pt` and `path_scorer_last.pt`: final training aliases.
-- `checkpoints/`: epoch and step checkpoints.
-- `export_manifest.json`, `train_summary.json`, and `train.log`: model metadata and training trace.
-
-## Current Strengths
-
-- Strong direct user-fact recall in single-session settings.
-- Strong assistant-detail recall.
-- Competitive knowledge-update behavior for changing facts.
-- Working temporal and preference retrieval layers with clear room for further specialization.
-
-## Active Improvement Areas
-
-- Multi-session aggregation and unit coverage.
-- Deeper time-graph reasoning.
-- Preference-profile abstraction and cross-session tunneling.
-- Query-graph to memory-graph matching for complex questions.
-
-## Intended Use
-
-This repository is a public-facing evidence package for TMCRA's long-memory runtime work. It is suitable for:
-
-- Benchmark review.
-- Model and result inspection.
-- Reproducing the frozen baseline.
-- Demonstrating how TMCRA can be packaged as an external memory runtime for agents.
-
-## Benchmark Result
-
-This package includes a full LongMemEval S500 run.
-
-- Benchmark: LongMemEval S set, 500 samples
-- Evaluation: official-compatible LongMemEval judge prompt
-- Judge model: `gpt-4o`, resolved as `gpt-4o-2024-08-06`
-- Writer layer used in this run: DeepSeek v4 Flash
-- Answer layer used in this run: GPT5.4-compatible API
-- Overall accuracy: `310 / 500 = 62.00%`
-
-## Results by Task Type
-
-| task type | accuracy | count |
-| --- | ---: | ---: |
-| single-session-user | 81.43% | 70 |
-| single-session-assistant | 78.57% | 56 |
-| knowledge-update | 70.51% | 78 |
-| temporal-reasoning | 63.16% | 133 |
-| single-session-preference | 56.67% | 30 |
-| multi-session | 39.85% | 133 |
-
-The benchmark outputs are available in:
-
-```text
-results/predictions.jsonl
-results/judge_gpt4o_alias_vectorengine.jsonl
-results/judge_gpt4o_alias_vectorengine.jsonl.summary.json
-results/lme_s500_frozen_baseline38_full10_20260525_results.tar.gz
-```
+TMCRA is released under the [Apache License 2.0](LICENSE). Third-party datasets, models, and components retain their own licenses.

README.zh-CN.md

@@ -1,207 +1,100 @@
-# TMCRA 长记忆运行时
+# TMCRA — 面向 Agent 的记忆引擎
 
 <p align="center">
   <img src="assets/tmcra-logo.png" alt="TMCRA logo" width="420">
 </p>
 
-[English version](README.md)
-
-TMCRA 是给 Agent 系统提供长期记忆能力的运行时层。它帮助大语言模型在长对话历史中检索、连接和推理相关记忆，而不需要在每一轮都暴露完整上下文。
-
-本仓库包含一个冻结的 TMCRA 基线包，包括模型权重、运行时代码快照、训练元数据和 LongMemEval S500 测评结果。
-
-许可证：MIT。
-
-## TMCRA 的作用
-
-TMCRA 在 Agent 应用和回答模型之间增加一层专门的记忆运行时。
-
-在写入阶段，TMCRA 会把对话转成记忆节点、事件单元、profile 信号和图路径。这让系统不仅能保存孤立事实，也能保存不同轮次、不同会话之间的事实关系。
+<p align="center">
+  <a href="README.md">English</a> ·
+  <a href="https://github.com/reshuibuduo/TMCRA-Agent-Memory">GitHub</a> ·
+  <a href="https://github.com/reshuibuduo/TMCRA-Agent-Memory/releases/tag/v2026.07.18">v2026.07.18 发布页</a>
+</p>
 
-在召回阶段，TMCRA 会对图节点和路径进行打分，选择紧凑的证据，并只把最相关的记忆上下文注入给回答模型。回答模型仍然负责自然语言推理和最终表达，TMCRA 负责长记忆组织、召回和证据呈现。
+TMCRA 是面向长期运行 Agent 的记忆引擎。它把多轮、跨会话的对话整理成作用域隔离、来源可追溯的记忆，并在用户提出下一轮问题后，召回与当前问题相关的紧凑证据。
 
-当前运行时重点覆盖：
+这个 Hugging Face 仓库包含采用 Apache-2.0 许可发布的 TMCRA 算法、LongMemEval 复现链路，以及本次 benchmark 使用的推理权重。线上 API、账号、计费和生产控制台不在本仓库的开源范围内。
 
-- 用户事实记忆
-- 助手回答细节记忆
-- profile 与偏好记忆
-- 时间记忆
-- 跨会话图隧穿
-- 学习式节点/路径打分
-- 面向下游 LLM 的紧凑证据选择
+## LongMemEval S500 成绩
 
-## 算法结构图
+TMCRA 的成绩为 **411 / 500 = 82.2%**。
 
-```mermaid
-flowchart LR
-    A["对话轮次"] --> B["写入层"]
-    B --> C["记忆节点"]
-    B --> D["事件单元"]
-    B --> E["Profile 信号"]
-    B --> F["时间信号"]
+| 任务类型 | 正确数 / 总数 | 准确率 |
+| --- | ---: | ---: |
+| 信息更新（Knowledge Update） | 71 / 78 | 91.0% |
+| 跨会话整合（Multi-session） | 90 / 133 | 67.7% |
+| 单会话助手信息（Single-session Assistant） | 55 / 56 | 98.2% |
+| 单会话偏好（Single-session Preference） | 27 / 30 | 90.0% |
+| 单会话用户信息（Single-session User） | 67 / 70 | 95.7% |
+| 时间推理（Temporal Reasoning） | 101 / 133 | 75.9% |
+| **总成绩** | **411 / 500** | **82.2%** |
 
-    C --> G["图记忆库"]
-    D --> G
-    E --> G
-    F --> G
+机器可读的成绩文件位于 [`results/latest_benchmark.json`](results/latest_benchmark.json)，完整复现入口位于 [`benchmarks/longmemeval/`](benchmarks/longmemeval/README.zh-CN.md)。复现链路固定使用 GPT-5.4 作为回答层；重新运行时如果调用外部模型服务，结果可能有小幅波动。
 
-    G --> H["学习式节点 Scorer"]
-    G --> I["学习式路径 Scorer"]
-    H --> J["证据选择"]
-    I --> J
+## 架构
 
-    J --> K["紧凑记忆上下文"]
-    K --> L["回答模型"]
-    L --> M["Agent 回复"]
+TMCRA 把记忆构建与最终回答生成明确分开。
 
-    N["用户问题"] --> H
-    N --> I
-    N --> J
-    N --> L
+```text
+历史对话
+   │
+   ▼
+ Writer ─────────────── 说话者与实体归因
+   │
+   ├── Source 层 ────── 不可变、可追溯的原始证据
+   ├── Fast 层 ──────── 反映当前状态的原子记忆
+   └── Slow 层 ──────── 可跨会话保留的语义图
+              │
+              └──────── 作用域内索引
+
+用户的新问题
+   │
+   ▼
+召回规划 → 分层检索 → 节点/路径打分 → 重排
+   │
+   ▼
+带来源绑定的证据包 → 下游 Agent
 ```
 
-写入层从对话中生成记忆单元。图记忆库保存事实、事件、profile 信号、时间信号和跨会话连接。学习式节点/路径 scorer 会根据当前问题选择相关证据，回答模型使用这些紧凑证据生成最终回复。
+TMCRA 的核心边界止于证据包；回答模型和 benchmark Judge 属于评测链路，不是在线记忆引擎本身。用户陈述和 Agent 完成的工作进度会分别保留各自的主体归属，同时都能在相关时被召回。
 
-## 为什么需要 TMCRA
+## 本次发布的权重
 
-长期运行的 Agent 不能只依赖简单向量召回。它需要保存用户事实、偏好、时间线变化、跨会话事件，以及多步证据链。
+三份权重只保留公开推理所需的结构定义和模型状态，不包含训练状态、训练机器路径或私有运行信息。请通过仓库运行时使用 `torch.load(..., weights_only=True)` 安全加载。
 
-TMCRA 将记忆组织成图节点和学习得到的召回路径，再把压缩后的证据提供给回答模型。目标是让外部 Agent 可以通过运行时/API 层使用长期记忆，同时保持记忆算法和模型权重可以独立部署。
+| 文件 | 用途 | 大小 | SHA-256 |
+| --- | --- | ---: | --- |
+| `node_scorer.pt` | 图节点打分 | 207,356,243 bytes | `d2318aafb07f9a15a1d95e6eac1b3e09afa07c570dd9d15d3f75544c9950f201` |
+| `path_scorer.pt` | 图路径打分 | 207,356,243 bytes | `ecdc2bca51b7646a8a56c7db9cea4aeec581e64c3b61e6e06f7e9fa2a93b3bf5` |
+| `tmcra_v3_reranker.pt` | 召回重排 | 4,232,213 bytes | `09a285b484ca857b24b53ad19d5998302f16d224ca9e4fd73a4eb5a52f022942` |
 
-## 如何使用
+权重和机器可读的发布清单位于 [`models/tmcra_v4_longmemeval_s500_20260715/`](models/tmcra_v4_longmemeval_s500_20260715/README.md)。
 
-推理或运行时使用时，加载下面目录中的图 scorer 权重：
-
-```text
-models/action_frame_tunnel_graph548_tunnel_fusion_train_20260524_042557/
-```
+## 下载
 
-主要运行时文件是：
-
-```text
-node_scorer.pt
-path_scorer.pt
-export_manifest.json
-```
-
-典型运行配置如下：
+安装最新版 Hugging Face CLI，然后只下载本次发布的推理包：
 
 ```bash
-export TMCRA_NODE_MODEL_PATH="models/action_frame_tunnel_graph548_tunnel_fusion_train_20260524_042557/node_scorer.pt"
-export TMCRA_PATH_MODEL_PATH="models/action_frame_tunnel_graph548_tunnel_fusion_train_20260524_042557/path_scorer.pt"
-export TMCRA_RETRIEVAL_MODE="hybrid_node_scored"
-export TMCRA_REQUIRE_LEARNED_SCORER="1"
-```
-
-测评入口代码快照：
+python -m pip install -U huggingface_hub
 
-```text
-code/run_lme_s10_native_tmcra.py
-```
-
-核心适配器代码快照：
-
-```text
-code/memory_adapters.py
+hf download 2009YU/TMCRA-Agent-Memory \
+  --include "models/tmcra_v4_longmemeval_s500_20260715/*" \
+  --local-dir ./TMCRA-Agent-Memory
 ```
 
-部署时，将两个 scorer 文件加载到 TMCRA adapter 中，并让 Agent 的记忆中间件调用 TMCRA 召回 API。回答模型可以是任意 OpenAI 兼容接口或本地 LLM；TMCRA 提供选中的记忆证据，回答模型生成最终回复。
-
-## 依赖环境
+源代码、benchmark 配置、环境示例、资源校验和分阶段检查说明可查看 [GitHub 发布页](https://github.com/reshuibuduo/TMCRA-Agent-Memory/releases/tag/v2026.07.18) 或 [`benchmarks/longmemeval/README.zh-CN.md`](benchmarks/longmemeval/README.zh-CN.md)。
 
-当前代码快照基于 Python。建议运行环境包括：
+## 版本记录
 
-- Python 3.10 或更高版本
-- PyTorch，推荐使用 CUDA 做模型推理
-- NumPy 及常见 Python 数据处理库
-- 用于回答层和写入层的 OpenAI 兼容接口或本地 LLM endpoint
-- 从 GitHub 拉取完整模型包时建议支持 Git LFS
+- 当前版本：[`v2026.07.18`](https://huggingface.co/2009YU/TMCRA-Agent-Memory/tree/v2026.07.18)
+- 更新前保留版本：[`legacy-2026.05.25`](https://huggingface.co/2009YU/TMCRA-Agent-Memory/tree/legacy-2026.05.25)
 
-benchmark 脚本使用 LongMemEval 格式输入数据，并输出 JSONL 格式的预测和 judge 结果。实际运行时部署可以直接使用同一套模型文件，不需要运行 benchmark harness。
+## 开发者
 
-## 可开启模块
+- **Yu Haoxin**：项目创建者、主要开发者与 TMCRA 算法工程。
+- **OpenAI Codex**：开发与可复现性工程协作。
 
-TMCRA 当前也保留了用于召回和规划实验的可选接入口。部署或评估时，如果目标场景需要，可以按需开启这些模块。
+署名与引用信息见 [`AUTHORS.md`](AUTHORS.md) 和 [`CITATION.cff`](CITATION.cff)。
 
-- **Embedder 接入口**：可选的语义 embedding 通道，可以和图记忆 scorer 并行工作。它用于在图证据选择前或选择过程中提供额外的稠密语义召回，但不替代学习式图节点/路径 scorer。
-- **LLM planner 接入口**：可选的规划 hook，可以调用外部 LLM 来整理证据、扩展 query intent，或在最终回答前生成 answer plan。它适合实验和更高成本的部署场景；默认基线仍保持核心图 scorer 链路可以独立测量。
+## 许可证
 
-这些接口是可集成的扩展点，不是冻结 S500 基线的必需依赖。下游部署可以根据成本和效果选择轻量的 scorer-only 路径，或开启 embedder/planner 辅助的增强路径。
-
-## 包含内容
-
-- `code/`：该基线使用的运行时和测评代码快照。
-- `models/action_frame_tunnel_graph548_tunnel_fusion_train_20260524_042557/`：完整训练后的图模型输出目录。
-- `results/`：预测结果、judge 输出、汇总指标和压缩后的运行结果。
-- `docs/`：基线记录和结果说明。
-
-补充文档：
-
-- `docs/BASELINE_S500_20260525.md`：benchmark 记录和子任务指标。
-- `docs/TRAINING.md`：模型训练方向和随包发布的训练产物说明。
-- `docs/OPTIONAL_MODULES_AND_PARALLEL.zh-CN.md`���embedder/planner 可选接入口和并行评估推进方案。
-- `docs/OPTIONAL_MODULES_AND_PARALLEL.md`：上述文档的英文版本。
-
-## 模型包
-
-随包发布的模型目录保留了图 scorer 栈的完整训练输出：
-
-- `node_scorer.pt` 和 `path_scorer.pt`：运行时图打分权重。
-- `node_scorer_best.pt` 和 `path_scorer_best.pt`：验证表现最好的 checkpoint 别名。
-- `node_scorer_last.pt` 和 `path_scorer_last.pt`：训练结束时的 checkpoint 别名。
-- `checkpoints/`：按 epoch 和 step 保存的中间 checkpoint。
-- `export_manifest.json`、`train_summary.json` 和 `train.log`：模型元数据和训练轨迹。
-
-## 当前优势
-
-- 单会话直接用户事实召回较强。
-- 助手细节召回较强。
-- 对变化事实的 knowledge-update 任务有较稳定表现。
-- 已具备可工作的时间记忆和偏好召回层，后续仍有专项优化空间。
-
-## 当前改进方向
-
-- multi-session 聚合和 unit coverage。
-- 更深的时间图推理。
-- 偏好 profile 抽象和跨会话隧穿。
-- query graph 与 memory graph 的复杂问题匹配。
-
-## 适用场景
-
-本仓库是 TMCRA 长记忆运行时工作的对外展示包，适合用于：
-
-- benchmark 审阅
-- 模型和结果检查
-- 复现冻结基线
-- 展示 TMCRA 如何作为外部 Agent 的记忆运行时进行封装
-
-## Benchmark 结果
-
-本包包含一次完整 LongMemEval S500 测试。
-
-- Benchmark：LongMemEval S set，500 条样本
-- Evaluation：official-compatible LongMemEval judge prompt
-- Judge 模型：`gpt-4o`，解析为 `gpt-4o-2024-08-06`
-- 本轮使用的写入层：DeepSeek v4 Flash
-- 本轮使用的回答层：GPT5.4-compatible API
-- 总准确率：`310 / 500 = 62.00%`
-
-## 各任务类型结果
-
-| 任务类型 | 准确率 | 数量 |
-| --- | ---: | ---: |
-| single-session-user | 81.43% | 70 |
-| single-session-assistant | 78.57% | 56 |
-| knowledge-update | 70.51% | 78 |
-| temporal-reasoning | 63.16% | 133 |
-| single-session-preference | 56.67% | 30 |
-| multi-session | 39.85% | 133 |
-
-benchmark 输出文件位于：
-
-```text
-results/predictions.jsonl
-results/judge_gpt4o_alias_vectorengine.jsonl
-results/judge_gpt4o_alias_vectorengine.jsonl.summary.json
-results/lme_s500_frozen_baseline38_full10_20260525_results.tar.gz
-```
+TMCRA 采用 [Apache License 2.0](LICENSE) 开源；第三方数据集、模型和组件仍遵循各自的许可证。

SECURITY.md

@@ -0,0 +1,12 @@
+# Security policy
+
+Do not open a public issue containing credentials, private memory data, or a
+working exploit. Use GitHub's private vulnerability reporting for this
+repository when available.
+
+TMCRA checkpoints must be loaded with `torch.load(..., weights_only=True)` and
+verified against the published SHA-256 manifest. The maintainers do not
+support disabling these checks for untrusted checkpoints.
+
+Provider API keys belong only in local `*.env` files. The example files contain
+placeholders and real environment files are excluded by `.gitignore`.

benchmarks/longmemeval/README.md

@@ -0,0 +1,216 @@
+# TMCRA Agent Memory System — LongMemEval Benchmark
+
+[简体中文](README.zh-CN.md)
+
+TMCRA is a scope-isolated, layered memory engine for agents. It keeps durable evidence outside the answer model and returns a compact, traceable memory context for each query. This directory contains the LongMemEval pipeline used to build memory, retrieve across multiple memory layers, compile evidence, generate answers, and evaluate the predictions.
+
+## Benchmark result
+
+TMCRA achieves **82.2%** on LongMemEval.
+
+| Task category | Correct / Total | Accuracy |
+| --- | ---: | ---: |
+| Knowledge Update | 71 / 78 | 91.0% |
+| Multi-session | 90 / 133 | 67.7% |
+| Single-session Assistant | 55 / 56 | 98.2% |
+| Single-session Preference | 27 / 30 | 90.0% |
+| Single-session User | 67 / 70 | 95.7% |
+| Temporal Reasoning | 101 / 133 | 75.9% |
+| **Overall** | **411 / 500** | **82.2%** |
+
+The machine-readable aggregate result is available in [`results/benchmark.json`](results/benchmark.json).
+
+## Architecture
+
+TMCRA separates immutable source evidence from two derived memory layers. The Writer stores conversation messages in Source and extracts normalized, current assertions into Fast. Subject Attribution prevents quoted or third-party facts from being promoted under the wrong identity. Eligible records are reorganized into the durable Slow semantic graph, while every derived memory remains traceable to Source.
+
+At query time, the Recall Planner resolves the question and assigns layer roles. Source, Fast, and Slow candidates are retrieved, graph-ranked, reranked, and packed into a bounded evidence set. The Evidence Compiler converts this set into a structured, provenance-bound packet. TMCRA's online memory boundary ends at prompt-ready evidence; answer generation and the official Judge belong to the benchmark harness.
+
+```mermaid
+flowchart LR
+  subgraph BENCH["Benchmark Adapter"]
+    D["LongMemEval Dataset"] --> H["Data Adapter / Harness"]
+    Q["Query"]
+    G["Gold Answer"]
+    D --> G
+  end
+
+  subgraph CORE["TMCRA Memory and Retrieval Core"]
+    W["Writer"]
+    S["Source Layer<br/>immutable records"]
+    W --> F["Fast Layer<br/>atomic current memory"]
+    W --> S
+    F --> A["Subject Attribution<br/>promotion gate"]
+    A --> L["Slow Layer<br/>durable semantic graph"]
+    S --> I["Index<br/>searchable snapshot"]
+    F --> I
+    L --> I
+    P["Recall Planner<br/>query and layer roles"]
+    P --> R["Layered Retrieval<br/>Source + Fast + Slow"]
+    I --> R
+    R --> K["Graph / Reranker<br/>Top-K evidence packing"]
+    K --> C["Evidence Compiler<br/>traceable evidence packet"]
+  end
+
+  subgraph EVAL["Benchmark Evaluation Only"]
+    C --> M["Answer Model"]
+    M --> J["Official Judge"]
+    J --> O["Overall and task-level scores"]
+  end
+
+  H -->|"conversation history"| W
+  H -->|"question only"| Q
+  Q --> P
+  G -->|"reference used only here"| J
+```
+
+### Component responsibilities
+
+- **Source** retains the immutable conversation record and is the final evidence authority.
+- **Fast** stores source-bound atomic facts, relations, updates, and current state.
+- **Subject Attribution** stops quoted or third-party information from being assigned to the wrong subject.
+- **Slow** organizes eligible cross-session information into a durable semantic graph; it supplements rather than replaces Source.
+- **Recall Planner** interprets the question and memory-layer roles without reading the gold answer.
+- **Layered Retrieval** searches Source, Fast, and Slow, then performs graph ranking, reranking, deduplication, temporal handling, and fixed Top-K packing.
+- **Evidence Compiler** produces a structured evidence packet whose claims remain bound to source IDs.
+- **Answer Model and Judge** are benchmark-only components and are not part of the TMCRA online recall service.
+
+Gold answers are isolated from Writer, Planner, Retrieval, Evidence Compiler, and Answer Model. They are only read by the final Judge.
+
+## Viewing and reproducing the benchmark
+
+- **View the published result:** [`results/benchmark.json`](results/benchmark.json) contains the public overall and task-level summary shown above.
+- **Rerun the pipeline:** the commands below execute memory construction, layered retrieval, evidence compilation, answer generation, and evaluation. The published 82.2% scorecard is a frozen v5 result; this release uses the security-hardened v6 answer protocol, and fresh external model calls can produce a different score.
+
+### Tested environment
+
+- Linux
+- Python 3.12.3
+- NVIDIA GPU with 24 GiB VRAM or more
+- CUDA 12.8
+- PyTorch 2.11.0 + cu128
+- Transformers 5.10.2
+
+The full S500 run also needs sufficient system memory and disk space for Writer journals, graphs, indexes, checkpoints, and intermediate evidence artifacts.
+
+### 1. Clone and install
+
+```bash
+git lfs install
+GIT_LFS_SKIP_SMUDGE=1 git clone https://github.com/reshuibuduo/TMCRA-Agent-Memory.git
+cd TMCRA-Agent-Memory/benchmarks/longmemeval
+git lfs pull --include="models/tmcra_v4_longmemeval_s500_20260715/*.pt"
+
+python3.12 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -r requirements.txt
+python -m pip install -e .
+```
+
+`GIT_LFS_SKIP_SMUDGE=1` prevents the clone from downloading unrelated historical LFS objects; the next command pulls only the three checkpoints required by this benchmark.
+
+### 2. Verify checkpoints and download external assets
+
+The three TMCRA checkpoints are tracked in the repository with Git LFS under `models/tmcra_v4_longmemeval_s500_20260715/`. The asset script verifies their byte sizes and SHA-256 hashes in place; it does not create a second copy. It then downloads the official cleaned LongMemEval-S dataset and the revision-pinned BGE models:
+
+```bash
+python scripts/fetch_assets.py --manifest configs/assets.lock.json --kind all
+```
+
+The dataset comes from the [official LongMemEval release](https://github.com/xiaowu0162/LongMemEval) and [cleaned dataset repository](https://huggingface.co/datasets/xiaowu0162/longmemeval-cleaned). BGE-M3 and the reranker are downloaded from the official [BAAI/bge-m3](https://huggingface.co/BAAI/bge-m3) and [BAAI/bge-reranker-v2-m3](https://huggingface.co/BAAI/bge-reranker-v2-m3) model pages.
+
+File assets are verified against `configs/assets.lock.json`. If the checkout contains only LFS pointer files, the script stops with the exact `git lfs pull` command required to fetch the weights.
+
+### 3. Configure model providers
+
+```bash
+cp configs/writer.env.example configs/writer.env
+cp configs/answer.env.example configs/answer.env
+cp configs/judge.env.example configs/judge.env
+cp configs/run.env.example configs/run.env
+```
+
+Edit the four generated files:
+
+- `writer.env` configures one OpenAI-compatible DeepSeek endpoint and a comma-separated key pool used by the Writer, subject-attribution pass, and evidence planner. The endpoint must accept `deepseek-v4-flash` and `deepseek-v4-pro`, or map those names to compatible deployments.
+- `answer.env` must expose the exact model identifier `gpt-5.4` through an OpenAI-compatible endpoint.
+- `judge.env` must expose `gpt-4o-2024-08-06`. The public command passes the `gpt-4o` alias, and the bundled evaluator resolves that alias to the fixed version.
+- `run.env` selects local paths, concurrency, and PyTorch devices.
+
+Keep API keys local; the repository `.gitignore` excludes the real configuration files.
+
+The default Judge wire format is OpenAI Chat Completions. Set `OPENAI_WIRE_API=responses` in `judge.env` only if the configured endpoint implements the Responses API.
+
+### 4. Run the offline smoke test
+
+This test uses a synthetic fixture and does not call external model providers:
+
+```bash
+bash scripts/reproduce_smoke.sh
+```
+
+### 5. Run LongMemEval-S500
+
+```bash
+bash scripts/reproduce_s500.sh
+```
+
+The script executes and validates the following stages:
+
+```text
+prepare data and ordered QIDs
+  -> build Writer journals, Source/Fast/Slow memory, and indexes
+  -> retrieve Source + Fast + Slow evidence
+  -> compile operation-bound evidence packets
+  -> generate answers with GPT-5.4
+  -> evaluate with the official GPT-4o Judge
+  -> export overall and task-level scores
+```
+
+Important outputs are written under `runs/longmemeval_s500/`:
+
+```text
+BUILD_COMPLETE
+retrieval_s500/evidence_windows.jsonl
+retrieval_s500/retrieval_debug.jsonl
+retrieval_s500_compiled/COMPILE_COMPLETE
+retrieval_s500_compiled/evidence_windows.jsonl
+answers_s500/answers.jsonl
+official_judge_gpt4o_20240806.jsonl
+scorecard.json
+```
+
+Before the next stage starts, the runner requires completion markers or reports, exact row counts, and the same ordered QID set. Judge rows are also checked for boolean labels from `gpt-4o-2024-08-06`. Compatible incomplete retrieval, compilation, answer, and judge artifacts are resumed. Build recovery is fail-closed and may require the explicit review flags printed by the build runner; an incompatible answer protocol requires a new answer output directory.
+
+## Repository layout
+
+```text
+configs/      provider examples and hash-pinned asset manifest
+fixtures/     synthetic offline test data
+results/      published aggregate score
+scripts/      asset download, validation, smoke, and S500 runners
+src/          TMCRA V4 benchmark core, LongMemEval harness, and minimal adapter
+tests/        offline schema, gold-isolation, and score aggregation tests
+../../models/tmcra_v4_longmemeval_s500_20260715/
+              Git LFS checkpoints used by this benchmark
+```
+
+Production HTTP APIs, account systems, billing, tenant authorization, deployment files, credentials, runtime databases, raw provider logs, and control-plane components are intentionally excluded.
+
+## Validation
+
+```bash
+python -m compileall -q src scripts tests
+python -m pytest
+```
+
+Before publishing a release, also run a secret scan, dependency vulnerability scan, SBOM generation, and a manual review of staged files and release assets.
+
+## Citation
+
+When reporting these results, identify the repository version and cite the [LongMemEval project](https://github.com/xiaowu0162/LongMemEval) and its paper.
+
+## License
+
+TMCRA benchmark code is released under the [Apache License 2.0](../../LICENSE). LongMemEval and the downloaded BGE models retain their own licenses; see [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md).

benchmarks/longmemeval/README.zh-CN.md

@@ -0,0 +1,216 @@
+# TMCRA 智能体记忆系统 — LongMemEval Benchmark
+
+[English](README.md)
+
+TMCRA 是面向智能体的作用域隔离、分层记忆引擎。它将可追溯的长期证据保存在回答模型之外，并在每次查询时返回紧凑、可核验的记忆上下文。本目录包含 TMCRA 的 LongMemEval benchmark 链路，覆盖记忆构建、多层召回、证据整理、回答生成与结果评测。
+
+## Benchmark 成绩
+
+TMCRA 在 LongMemEval benchmark 上取得 **82.2%**。
+
+| 任务类型 | 正确数 / 样本数 | 准确率 |
+| --- | ---: | ---: |
+| 信息更新（Knowledge Update） | 71 / 78 | 91.0% |
+| 跨会话信息整合（Multi-session） | 90 / 133 | 67.7% |
+| 单会话助手信息（Single-session Assistant） | 55 / 56 | 98.2% |
+| 单会话偏好理解（Single-session Preference） | 27 / 30 | 90.0% |
+| 单会话用户信息（Single-session User） | 67 / 70 | 95.7% |
+| 时间推理（Temporal Reasoning） | 101 / 133 | 75.9% |
+| **总成绩** | **411 / 500** | **82.2%** |
+
+机器可读的汇总成绩位于 [`results/benchmark.json`](results/benchmark.json)。
+
+## 架构
+
+TMCRA 将不可变证据与两类派生记忆分离。Writer 把对话消息保存到 Source，同时将可复用、反映当前状态的事实提取并规范化到 Fast。Subject Attribution 用于阻止引用内容或第三方事实被错误归属；通过门控的记录会进一步组织为稳定的 Slow 语义图，而所有派生记忆始终能够追溯到 Source。
+
+查询时，Recall Planner 先解析问题并为各记忆层分配职责。系统随后从 Source、Fast、Slow 生成候选，经过图排序、重排、去重、时间处理和有界 Top-K 打包，再由 Evidence Compiler 生成带来源绑定的结构化证据包。TMCRA 线上记忆服务的边界止于可注入提示词的证据；回答生成和 Official Judge 属于 benchmark harness。
+
+```mermaid
+flowchart LR
+  subgraph BENCH["Benchmark 适配层"]
+    D["LongMemEval 数据集"] --> H["数据适配器 / 测试框架"]
+    Q["查询问题"]
+    G["标准答案"]
+    D --> G
+  end
+
+  subgraph CORE["TMCRA 记忆与召回核心"]
+    W["记忆写入器（Writer）"]
+    S["原始证据层（Source）<br/>不可变记录"]
+    W --> F["快速记忆层（Fast）<br/>当前原子记忆"]
+    W --> S
+    F --> A["主体归属判断<br/>晋升门控"]
+    A --> L["慢速记忆层（Slow）<br/>持久语义图"]
+    S --> I["检索索引<br/>可搜索快照"]
+    F --> I
+    L --> I
+    P["召回规划器<br/>解析查询与各层职责"]
+    P --> R["分层召回<br/>Source + Fast + Slow"]
+    I --> R
+    R --> K["图排序 / 重排<br/>Top-K 证据打包"]
+    K --> C["证据编译器<br/>可追溯证据包"]
+  end
+
+  subgraph EVAL["仅用于 Benchmark 评测"]
+    C --> M["回答模型"]
+    M --> J["官方评测器（Judge）"]
+    J --> O["总成绩与分项成绩"]
+  end
+
+  H -->|"对话历史"| W
+  H -->|"仅问题"| Q
+  Q --> P
+  G -->|"只在此处作为评测参考"| J
+```
+
+### 核心组件职责
+
+- **Source** 保存不可变的对话原文，是最终证据来源。
+- **Fast** 保存与 Source 绑定的原子事实、关系、更新和当前状态。
+- **Subject Attribution** 防止引用内容或第三方信息被归属到错误主体。
+- **Slow** 把符合条件的跨会话信息组织为稳定的语义图；它补充 Source，但不能替代 Source。
+- **Recall Planner** 解析问题和各层职责，但不读取 gold answer。
+- **Layered Retrieval** 同时搜索 Source、Fast、Slow，并执行图排序、重排、去重、时间处理与固定 Top-K 打包。
+- **Evidence Compiler** 输出带 Source ID 绑定的结构化证据包。
+- **Answer Model 与 Judge** 只属于 benchmark，不属于 TMCRA 线上召回服务。
+
+Gold answer 与 Writer、Planner、Retrieval、Evidence Compiler、Answer Model 完全隔离，只允许最终 Judge 读取。
+
+## 查看与复现 benchmark
+
+- **查看公开成绩：** [`results/benchmark.json`](results/benchmark.json) 包含上表所示的总成绩与六类分项汇总。
+- **重跑完整链路：** 下面的命令会重新执行记忆构建、分层召回、证据整理、回答生成和评测。公开的 82.2% 是冻结的 v5 成绩；本次发布使用经过安全加固的 v6 回答协议，重新调用外部模型时成绩可能发生波动。
+
+### 已验证环境
+
+- Linux
+- Python 3.12.3
+- 24 GiB 或更高显存的 NVIDIA GPU
+- CUDA 12.8
+- PyTorch 2.11.0 + cu128
+- Transformers 5.10.2
+
+完整 S500 运行还需要足够的内存与磁盘空间，用于 Writer 日志、图、索引、checkpoint 和中间证据产物。
+
+### 1. 克隆并安装
+
+```bash
+git lfs install
+GIT_LFS_SKIP_SMUDGE=1 git clone https://github.com/reshuibuduo/TMCRA-Agent-Memory.git
+cd TMCRA-Agent-Memory/benchmarks/longmemeval
+git lfs pull --include="models/tmcra_v4_longmemeval_s500_20260715/*.pt"
+
+python3.12 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -r requirements.txt
+python -m pip install -e .
+```
+
+`GIT_LFS_SKIP_SMUDGE=1` 会阻止 clone 阶段下载无关的历史 LFS 对象；后续命令只拉取本 benchmark 所需的三个 checkpoint。
+
+### 2. 校验 checkpoint 并下载外部资产
+
+三个 TMCRA checkpoint 已通过 Git LFS 保存在仓库的 `models/tmcra_v4_longmemeval_s500_20260715/` 目录。资产脚本会直接校验这些文件的字节数与 SHA-256，不会重复复制；随后下载官方清洗版 LongMemEval-S 和固定 revision 的 BGE 模型：
+
+```bash
+python scripts/fetch_assets.py --manifest configs/assets.lock.json --kind all
+```
+
+数据来自 [LongMemEval 官方仓库](https://github.com/xiaowu0162/LongMemEval)和[清洗版数据集](https://huggingface.co/datasets/xiaowu0162/longmemeval-cleaned)。BGE-M3 与 reranker 来自官方 [BAAI/bge-m3](https://huggingface.co/BAAI/bge-m3) 和 [BAAI/bge-reranker-v2-m3](https://huggingface.co/BAAI/bge-reranker-v2-m3) 页面。
+
+文件类资产在启用前都会按照 `configs/assets.lock.json` 校验。如果当前检出只有 LFS 指针文件，脚本会停止并给出获取权重所需的完整 `git lfs pull` 命令。
+
+### 3. 配置模型服务
+
+```bash
+cp configs/writer.env.example configs/writer.env
+cp configs/answer.env.example configs/answer.env
+cp configs/judge.env.example configs/judge.env
+cp configs/run.env.example configs/run.env
+```
+
+编辑生成的四个文件：
+
+- `writer.env` 配置一个兼容 OpenAI API 格式的 DeepSeek 服务和逗号分隔的 key 池，供 Writer、主体归属判断和证据规划器共同使用。该服务需要接受 `deepseek-v4-flash` 与 `deepseek-v4-pro`，或者在网关中把这两个名称映射到兼容部署。
+- `answer.env` 的兼容 OpenAI API 服务必须以 `gpt-5.4` 这一精确名称提供回答模型。
+- `judge.env` 的服务必须提供 `gpt-4o-2024-08-06`。公开命令传入 `gpt-4o` 别名，内置评测器会将其固定解析为该版本。
+- `run.env` 配置本地路径、并发数与 PyTorch 设备。
+
+API key 只保留在本地，仓库的 `.gitignore` 已排除真实配置文件。
+
+Judge 默认使用 OpenAI Chat Completions 请求格式。只有当服务端实现了 Responses API 时，才在 `judge.env` 中设置 `OPENAI_WIRE_API=responses`。
+
+### 4. 运行离线 smoke test
+
+该测试只使用合成 fixture，不会调用外部模型服务：
+
+```bash
+bash scripts/reproduce_smoke.sh
+```
+
+### 5. 运行 LongMemEval-S500
+
+```bash
+bash scripts/reproduce_s500.sh
+```
+
+脚本会顺序执行并校验：
+
+```text
+准备数据与有序 QID
+  -> 构建 Writer 日志、Source/Fast/Slow 记忆和索引
+  -> 召回 Source + Fast + Slow 证据
+  -> 整理 operation-bound evidence packet
+  -> 使用 GPT-5.4 生成回答
+  -> 使用官方 GPT-4o Judge 评测
+  -> 导出总成绩与分项成绩
+```
+
+关键产物位于 `runs/longmemeval_s500/`：
+
+```text
+BUILD_COMPLETE
+retrieval_s500/evidence_windows.jsonl
+retrieval_s500/retrieval_debug.jsonl
+retrieval_s500_compiled/COMPILE_COMPLETE
+retrieval_s500_compiled/evidence_windows.jsonl
+answers_s500/answers.jsonl
+official_judge_gpt4o_20240806.jsonl
+scorecard.json
+```
+
+进入下一阶段前，脚本会检查完成标记或报告、准确的产物行数，以及与输入一致的有序 QID。Judge 产物还必须包含由 `gpt-4o-2024-08-06` 生成的布尔标签。兼容的召回、证据整理、回答和 Judge 产物会从断点继续；构建恢复采用故障关闭策略，必要时会要求使用构建脚本打印出的显式审查参数。回答协议不兼容时必须使用新的回答输出目录。
+
+## 仓库结构
+
+```text
+configs/      配置示例与 hash 固定的资产清单
+fixtures/     合成离线测试数据
+results/      公开的汇总成绩
+scripts/      资产下载、校验、smoke 与 S500 运行脚本
+src/          TMCRA V4 benchmark 核心、LongMemEval harness 与最小 adapter
+tests/        离线 schema、gold 隔离和成绩汇总测试
+../../models/tmcra_v4_longmemeval_s500_20260715/
+              本 benchmark 使用的 Git LFS checkpoint
+```
+
+线上 HTTP API、账户系统、计费、租户授权、部署文件、凭据、运行数据库、供应商原始日志和控制面均不在本仓库范围内。
+
+## 校验
+
+```bash
+python -m compileall -q src scripts tests
+python -m pytest
+```
+
+正式发布前还需要执行 secret scan、依赖漏洞扫描、SBOM，并人工审查暂存文件和 Release 资产。
+
+## 引用
+
+报告本结果时，请注明所使用的仓库版本，并引用 [LongMemEval 项目](https://github.com/xiaowu0162/LongMemEval)及其论文。
+
+## 许可证
+
+TMCRA benchmark 代码采用 [Apache License 2.0](../../LICENSE)。LongMemEval 与下载的 BGE 模型保留各自许可证，详见 [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md)。

benchmarks/longmemeval/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,52 @@
+# Third-Party Notices
+
+This benchmark runner downloads or adapts third-party material. Those components remain subject to their original licenses; the repository's Apache-2.0 license does not replace them.
+
+## LongMemEval
+
+- Project: <https://github.com/xiaowu0162/LongMemEval>
+- Cleaned dataset: <https://huggingface.co/datasets/xiaowu0162/longmemeval-cleaned>
+- License source: <https://github.com/xiaowu0162/LongMemEval/blob/main/LICENSE>
+- License: MIT
+
+The bundled evaluation wrapper follows the public LongMemEval evaluation prompt and rule. The dataset is downloaded separately by `scripts/fetch_assets.py`.
+
+The complete LongMemEval MIT license text follows:
+
+> MIT License
+>
+> Copyright (c) 2024 Di Wu
+>
+> Permission is hereby granted, free of charge, to any person obtaining a copy
+> of this software and associated documentation files (the "Software"), to deal
+> in the Software without restriction, including without limitation the rights
+> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+> copies of the Software, and to permit persons to whom the Software is
+> furnished to do so, subject to the following conditions:
+>
+> The above copyright notice and this permission notice shall be included in all
+> copies or substantial portions of the Software.
+>
+> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+> SOFTWARE.
+
+## BAAI/bge-m3
+
+- Model page: <https://huggingface.co/BAAI/bge-m3>
+- Locked revision: `5617a9f61b028005a4858fdac845db406aefb181`
+- License declared by the model repository: MIT
+
+The model files are downloaded from Hugging Face and are not relicensed by TMCRA. Review the model repository and its license before redistribution.
+
+## BAAI/bge-reranker-v2-m3
+
+- Model page: <https://huggingface.co/BAAI/bge-reranker-v2-m3>
+- Locked revision: `953dc6f6f85a1b2dbfca4c34a2796e7dde08d41e`
+- License declared by the model repository: Apache License 2.0
+
+The model files are downloaded from Hugging Face and are not relicensed by TMCRA. Review the model repository and its license before redistribution.

benchmarks/longmemeval/configs/answer.env.example

@@ -0,0 +1,6 @@
+# The answer runner requires this exact model identifier. The endpoint may be
+# an OpenAI-compatible gateway, but it must expose gpt-5.4 under this name.
+TMCRA_ANSWER_MODEL=gpt-5.4
+TMCRA_ANSWER_BASE_URL=https://your-answer-endpoint.example/v1
+TMCRA_ANSWER_API_KEY=replace_me
+TMCRA_ANSWER_MAX_TOKENS=1536

benchmarks/longmemeval/configs/assets.lock.json

@@ -0,0 +1,51 @@
+{
+  "schema_version": "tmcra.benchmark-assets.1",
+  "files": [
+    {
+      "id": "longmemeval_s_cleaned",
+      "kind": "dataset",
+      "destination": "data/longmemeval_s_cleaned.json",
+      "url": "https://huggingface.co/datasets/xiaowu0162/longmemeval-cleaned/resolve/main/longmemeval_s_cleaned.json",
+      "bytes": 277383467,
+      "sha256": "d6f21ea9d60a0d56f34a05b609c79c88a451d2ae03597821ea3d5a9678c3a442"
+    },
+    {
+      "id": "tmcra_node_scorer",
+      "kind": "checkpoint",
+      "storage": "git_lfs",
+      "destination": "../../models/tmcra_v4_longmemeval_s500_20260715/node_scorer.pt",
+      "bytes": 207356243,
+      "sha256": "d2318aafb07f9a15a1d95e6eac1b3e09afa07c570dd9d15d3f75544c9950f201"
+    },
+    {
+      "id": "tmcra_path_scorer",
+      "kind": "checkpoint",
+      "storage": "git_lfs",
+      "destination": "../../models/tmcra_v4_longmemeval_s500_20260715/path_scorer.pt",
+      "bytes": 207356243,
+      "sha256": "ecdc2bca51b7646a8a56c7db9cea4aeec581e64c3b61e6e06f7e9fa2a93b3bf5"
+    },
+    {
+      "id": "tmcra_v3_reranker",
+      "kind": "checkpoint",
+      "storage": "git_lfs",
+      "destination": "../../models/tmcra_v4_longmemeval_s500_20260715/tmcra_v3_reranker.pt",
+      "bytes": 4232213,
+      "sha256": "09a285b484ca857b24b53ad19d5998302f16d224ca9e4fd73a4eb5a52f022942"
+    }
+  ],
+  "huggingface_models": [
+    {
+      "id": "bge_m3",
+      "repo_id": "BAAI/bge-m3",
+      "revision": "5617a9f61b028005a4858fdac845db406aefb181",
+      "destination": "models/BAAI/bge-m3"
+    },
+    {
+      "id": "bge_reranker_v2_m3",
+      "repo_id": "BAAI/bge-reranker-v2-m3",
+      "revision": "953dc6f6f85a1b2dbfca4c34a2796e7dde08d41e",
+      "destination": "models/BAAI/bge-reranker-v2-m3"
+    }
+  ]
+}

benchmarks/longmemeval/configs/judge.env.example

@@ -0,0 +1,9 @@
+# OpenAI-compatible Judge endpoint. The public runner selects the gpt-4o alias;
+# the evaluator resolves it to the fixed gpt-4o-2024-08-06 model identifier.
+TMCRA_JUDGE_BASE_URL=https://your-judge-endpoint.example/v1
+TMCRA_JUDGE_API_KEY=replace_me
+TMCRA_OFFICIAL_JUDGE_WORKERS=8
+
+# The default wire format is POST /chat/completions. Uncomment this only when
+# the configured endpoint implements POST /responses instead.
+# OPENAI_WIRE_API=responses

benchmarks/longmemeval/configs/run.env.example

@@ -0,0 +1,18 @@
+# reproduce_s500.sh changes into benchmarks/longmemeval before loading this
+# file, so $PWD resolves to that directory.
+DATA="$PWD/data/longmemeval_s_cleaned.json"
+QIDS="$PWD/data/longmemeval_s500.qids.txt"
+RUN="$PWD/runs/longmemeval_s500"
+# TMCRA scorer weights are tracked by Git LFS in the repository-level model
+# package. BGE snapshots are downloaded locally under this benchmark directory.
+MODELS="$PWD/../../models/tmcra_v4_longmemeval_s500_20260715"
+BGE_MODELS="$PWD/models/BAAI"
+
+# Tune concurrency to provider rate limits and local memory. Device values are
+# passed directly to PyTorch and therefore require a matching local runtime.
+WRITER_CONCURRENCY=20
+SLOW_CONCURRENCY=20
+RETRIEVAL_DEVICE=cuda
+GRAPH_DEVICE=cuda
+ANSWER_WORKERS=12
+JUDGE_WORKERS=8

benchmarks/longmemeval/configs/writer.env.example

@@ -0,0 +1,12 @@
+# One OpenAI-compatible DeepSeek endpoint is used by the benchmark Writer,
+# subject-attribution pass, and evidence planner. The gateway must accept the
+# model names deepseek-v4-flash and deepseek-v4-pro, or alias them accordingly.
+TMCRA_WRITER_BASE_URL=https://your-writer-endpoint.example/v1
+TMCRA_WRITER_TIMEOUT_SECONDS=180
+TMCRA_WRITER_MAX_TOKENS=16384
+
+# Comma-separated, non-empty, unique API keys. For a single key, keep the
+# count at 1. If you add keys, update the count to the exact number of keys.
+TMCRA_DEEPSEEK_WRITER_BASE_URL=https://your-planner-endpoint.example/v1
+TMCRA_DEEPSEEK_WRITER_KEY_POOL=replace_me
+TMCRA_DEEPSEEK_WRITER_KEY_POOL_COUNT=1

benchmarks/longmemeval/fixtures/tiny_longmemeval.json

@@ -0,0 +1,22 @@
+[
+  {
+    "question_id": "tmcra_fixture_user",
+    "question_type": "single-session-user",
+    "question": "Which drink did the user choose?",
+    "answer": "Tea.",
+    "question_date": "2026-01-02",
+    "haystack_session_ids": ["fixture-session-1"],
+    "haystack_dates": ["2026-01-01"],
+    "haystack_sessions": [[{"role": "user", "content": "I chose tea."}]]
+  },
+  {
+    "question_id": "tmcra_fixture_update",
+    "question_type": "knowledge-update",
+    "question": "Where does the user live now?",
+    "answer": "Shanghai.",
+    "question_date": "2026-01-03",
+    "haystack_session_ids": ["fixture-session-2"],
+    "haystack_dates": ["2026-01-02"],
+    "haystack_sessions": [[{"role": "user", "content": "I moved from Suzhou to Shanghai."}]]
+  }
+]

benchmarks/longmemeval/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=80", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tmcra-agent-memory-longmemeval"
+version = "0.1.0"
+description = "TMCRA LongMemEval benchmark reproduction pipeline"
+readme = "README.md"
+requires-python = ">=3.12,<3.13"
+license = "Apache-2.0"
+authors = [{ name = "Yu Haoxin" }]
+dependencies = [
+  "huggingface-hub==1.23.0",
+  "numpy==2.4.3",
+  "safetensors==0.8.0",
+  "tokenizers==0.22.2",
+  "transformers==5.10.2",
+]
+
+[project.optional-dependencies]
+test = ["pytest==9.0.2"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+namespaces = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

benchmarks/longmemeval/requirements.txt

@@ -0,0 +1,8 @@
+--extra-index-url https://download.pytorch.org/whl/cu128
+torch==2.11.0+cu128
+huggingface-hub==1.23.0
+numpy==2.4.3
+safetensors==0.8.0
+tokenizers==0.22.2
+transformers==5.10.2
+pytest==9.0.2

benchmarks/longmemeval/results/benchmark.json

@@ -0,0 +1,16 @@
+{
+  "schema_version": "tmcra.benchmark-result.1",
+  "benchmark": "LongMemEval",
+  "metric": "accuracy",
+  "score_percent": 82.2,
+  "correct": 411,
+  "total": 500,
+  "by_question_type": {
+    "knowledge-update": {"correct": 71, "total": 78, "score_percent": 91.0},
+    "multi-session": {"correct": 90, "total": 133, "score_percent": 67.7},
+    "single-session-assistant": {"correct": 55, "total": 56, "score_percent": 98.2},
+    "single-session-preference": {"correct": 27, "total": 30, "score_percent": 90.0},
+    "single-session-user": {"correct": 67, "total": 70, "score_percent": 95.7},
+    "temporal-reasoning": {"correct": 101, "total": 133, "score_percent": 75.9}
+  }
+}

benchmarks/longmemeval/scripts/fetch_assets.py

@@ -0,0 +1,95 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import urllib.request
+from pathlib import Path
+
+LFS_INCLUDE = "models/tmcra_v4_longmemeval_s500_20260715/*.pt"
+
+
+def digest(path: Path) -> str:
+    hasher = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            hasher.update(chunk)
+    return hasher.hexdigest()
+
+
+def fetch_file(root: Path, row: dict[str, object]) -> None:
+    destination = (root / str(row["destination"])).resolve()
+    expected = str(row["sha256"])
+    expected_bytes = int(row["bytes"])
+    if destination.is_file() and destination.stat().st_size == expected_bytes and digest(destination) == expected:
+        print(f"verified {row['id']}: {destination}")
+        return
+    if row.get("storage") == "git_lfs":
+        detail = "file is missing"
+        if destination.is_file():
+            with destination.open("rb") as handle:
+                prefix = handle.read(128)
+            if prefix.startswith(b"version https://git-lfs.github.com/spec/v1"):
+                detail = "only a Git LFS pointer is present"
+            else:
+                detail = f"size or SHA-256 mismatch ({destination.stat().st_size} bytes)"
+        raise RuntimeError(
+            f"Git LFS checkpoint {row['id']} is unavailable: {detail}: {destination}\n"
+            f"run from the repository root: git lfs pull --include=\"{LFS_INCLUDE}\""
+        )
+    if not row.get("url"):
+        raise RuntimeError(f"asset {row['id']} has neither a valid local Git LFS file nor a download URL")
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    temporary = destination.with_suffix(destination.suffix + ".part")
+    temporary.unlink(missing_ok=True)
+    print(f"downloading {row['id']} -> {destination}")
+    urllib.request.urlretrieve(str(row["url"]), temporary)
+    if temporary.stat().st_size != expected_bytes:
+        raise RuntimeError(f"size mismatch for {row['id']}")
+    actual = digest(temporary)
+    if actual != expected:
+        raise RuntimeError(f"SHA-256 mismatch for {row['id']}: {actual}")
+    os.replace(temporary, destination)
+
+
+def fetch_model(root: Path, row: dict[str, object]) -> None:
+    from huggingface_hub import snapshot_download
+
+    destination = root / str(row["destination"])
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    print(f"downloading {row['repo_id']}@{row['revision']} -> {destination}")
+    snapshot_download(
+        repo_id=str(row["repo_id"]),
+        revision=str(row["revision"]),
+        local_dir=destination,
+    )
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--manifest", type=Path, default=Path("configs/assets.lock.json"))
+    parser.add_argument("--root", type=Path, default=Path.cwd())
+    parser.add_argument("--kind", choices=("all", "dataset", "checkpoint", "model"), default="all")
+    args = parser.parse_args()
+    payload = json.loads(args.manifest.read_text(encoding="utf-8"))
+    if args.kind in {"all", "dataset", "checkpoint"}:
+        selected = [
+            row
+            for row in payload["files"]
+            if args.kind == "all" or row["kind"] == args.kind
+        ]
+        # Validate repository-owned LFS files before starting any large network
+        # download, so an incomplete clone fails quickly and predictably.
+        selected.sort(key=lambda row: row.get("storage") != "git_lfs")
+        for row in selected:
+            fetch_file(args.root, row)
+    if args.kind in {"all", "model"}:
+        for row in payload["huggingface_models"]:
+            fetch_model(args.root, row)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

benchmarks/longmemeval/scripts/prepare_longmemeval.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+from collections import Counter
+from pathlib import Path
+
+
+QUESTION_TYPES = {
+    "knowledge-update",
+    "multi-session",
+    "single-session-assistant",
+    "single-session-preference",
+    "single-session-user",
+    "temporal-reasoning",
+}
+
+
+def load_and_validate(path: Path) -> list[dict[str, object]]:
+    rows = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(rows, list) or not rows:
+        raise ValueError("LongMemEval input must be a non-empty JSON array")
+    seen: set[str] = set()
+    for index, row in enumerate(rows):
+        if not isinstance(row, dict):
+            raise ValueError(f"row {index} is not an object")
+        qid = str(row.get("question_id") or "").strip()
+        if not qid or qid in seen:
+            raise ValueError(f"invalid or duplicate question_id at row {index}: {qid!r}")
+        seen.add(qid)
+        question_type = str(row.get("question_type") or "").strip()
+        if question_type not in QUESTION_TYPES:
+            raise ValueError(f"{qid}: unexpected question_type {question_type!r}")
+        for field in ("question", "answer", "haystack_sessions", "haystack_dates"):
+            if field not in row:
+                raise ValueError(f"{qid}: missing {field}")
+    return rows
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--data", required=True, type=Path)
+    parser.add_argument("--qid-output", required=True, type=Path)
+    parser.add_argument("--summary-output", type=Path)
+    parser.add_argument("--limit", type=int, default=0)
+    args = parser.parse_args()
+    rows = load_and_validate(args.data)
+    selected = rows[: args.limit] if args.limit else rows
+    qids = [str(row["question_id"]) for row in selected]
+    args.qid_output.parent.mkdir(parents=True, exist_ok=True)
+    args.qid_output.write_text("\n".join(qids) + "\n", encoding="utf-8")
+    summary = {
+        "schema_version": "tmcra.longmemeval-input.1",
+        "dataset_sha256": hashlib.sha256(args.data.read_bytes()).hexdigest(),
+        "source_count": len(rows),
+        "selected_count": len(selected),
+        "question_types": dict(sorted(Counter(str(row["question_type"]) for row in selected).items())),
+        "qid_output": str(args.qid_output),
+    }
+    if args.summary_output:
+        args.summary_output.parent.mkdir(parents=True, exist_ok=True)
+        args.summary_output.write_text(json.dumps(summary, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    print(json.dumps(summary, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

benchmarks/longmemeval/scripts/reproduce_s500.sh

@@ -0,0 +1,152 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT"
+
+for file in configs/writer.env configs/answer.env configs/judge.env configs/run.env; do
+  if [[ ! -f "$file" ]]; then
+    echo "missing $file; copy the matching .example file and fill in your values" >&2
+    exit 2
+  fi
+done
+
+set -a
+source configs/run.env
+set +a
+
+LEGACY="$ROOT/src/tmcra_benchmark/legacy"
+VENDOR="$ROOT/src/tmcra_benchmark/vendor/tmcra_integrated"
+HARNESS="$ROOT/src/tmcra_benchmark/harness/run_lme_s10_native_tmcra.py"
+JUDGE="$ROOT/src/tmcra_benchmark/harness/evaluate_qa_official_judge.py"
+export PYTHONPATH="$LEGACY:$VENDOR:$ROOT/src${PYTHONPATH:+:$PYTHONPATH}"
+
+: "${DATA:?DATA is required in configs/run.env}"
+: "${QIDS:?QIDS is required in configs/run.env}"
+: "${RUN:?RUN is required in configs/run.env}"
+: "${MODELS:?MODELS is required in configs/run.env}"
+: "${BGE_MODELS:?BGE_MODELS is required in configs/run.env}"
+
+python scripts/prepare_longmemeval.py \
+  --data "$DATA" \
+  --qid-output "$QIDS" \
+  --summary-output "$RUN.input_summary.json"
+
+if [[ ! -f "$RUN/BUILD_COMPLETE" ]]; then
+  build_resume_args=()
+  if [[ -d "$RUN" ]]; then
+    build_resume_args+=(--resume)
+  fi
+  python "$LEGACY/run_tmcra_v4_build.py" \
+    "${build_resume_args[@]}" \
+    --out-dir "$RUN" \
+    --qid-list "$QIDS" \
+    --data "$DATA" \
+    --repo "$VENDOR" \
+    --writer-env configs/writer.env \
+    --embedding-model "$BGE_MODELS/bge-m3" \
+    --writer-concurrency "${WRITER_CONCURRENCY:-20}" \
+    --slow-concurrency "${SLOW_CONCURRENCY:-20}" \
+    --index-batch-size 16 \
+    --device "${RETRIEVAL_DEVICE:-cuda}"
+fi
+python scripts/validate_stage.py build --run-dir "$RUN" --expected-qids "$QIDS"
+
+export TMCRA_NODE_MODEL_PATH="$MODELS/node_scorer.pt"
+export TMCRA_PATH_MODEL_PATH="$MODELS/path_scorer.pt"
+export TMCRA_BGE_M3_PATH="$BGE_MODELS/bge-m3"
+export TMCRA_BGE_RERANKER_PATH="$BGE_MODELS/bge-reranker-v2-m3"
+
+if [[ ! -f "$RUN/retrieval_s500/RETRIEVAL_COMPLETE" ]]; then
+  retrieval_resume_args=()
+  if [[ -d "$RUN/retrieval_s500" ]]; then
+    retrieval_resume_args+=(--resume)
+  fi
+  python "$LEGACY/run_tmcra_v4_retrieve.py" \
+    "${retrieval_resume_args[@]}" \
+    --run-dir "$RUN" \
+    --tag retrieval_s500 \
+    --qid-list "$QIDS" \
+    --writer-env configs/writer.env \
+    --repo "$VENDOR" \
+    --harness "$HARNESS" \
+    --node-model "$MODELS/node_scorer.pt" \
+    --path-model "$MODELS/path_scorer.pt" \
+    --checkpoint "$MODELS/tmcra_v3_reranker.pt" \
+    --embedding-model "$BGE_MODELS/bge-m3" \
+    --cross-model "$BGE_MODELS/bge-reranker-v2-m3" \
+    --device "${RETRIEVAL_DEVICE:-cuda}" \
+    --graph-device "${GRAPH_DEVICE:-cuda}" \
+    --dense-k 32 \
+    --slow-dense-k 24 \
+    --graph-k 24 \
+    --composition-mode layered \
+    --packing-budget-mode fixed \
+    --top-k 8 \
+    --cross-batch-size 24
+fi
+python scripts/validate_stage.py retrieve --run-dir "$RUN" --tag retrieval_s500 --expected-qids "$QIDS"
+
+if [[ ! -f "$RUN/retrieval_s500_compiled/COMPILE_COMPLETE" ]]; then
+  python "$LEGACY/run_tmcra_v4_compile_evidence.py" \
+    --evidence "$RUN/retrieval_s500/evidence_windows.jsonl" \
+    --retrieval-debug "$RUN/retrieval_s500/retrieval_debug.jsonl" \
+    --require-retrieval-debug \
+    --out-dir "$RUN/retrieval_s500_compiled" \
+    --qid-list "$QIDS" \
+    --writer-env configs/writer.env \
+    --planner-provider deepseek \
+    --planner-model deepseek-v4-pro \
+    --workers 4 \
+    --timeout 180
+fi
+python scripts/validate_stage.py compile --run-dir "$RUN/retrieval_s500_compiled" --expected-qids "$QIDS"
+
+set -a
+source configs/answer.env
+set +a
+# The answer runner resumes from its validated answers.jsonl. Running it again
+# also repairs an incomplete report without repeating completed provider calls.
+python "$LEGACY/run_tmcra_v4_gpt54_answers.py" \
+  --evidence "$RUN/retrieval_s500_compiled/evidence_windows.jsonl" \
+  --harness "$HARNESS" \
+  --out-dir "$RUN/answers_s500" \
+  --qid-list "$QIDS" \
+  --workers "${ANSWER_WORKERS:-12}" \
+  --attempts 3 \
+  --answer-window-limit 8 \
+  --lane production
+python scripts/validate_stage.py answer --run-dir "$RUN/answers_s500" --expected-qids "$QIDS"
+
+set -a
+source configs/judge.env
+set +a
+: "${TMCRA_JUDGE_BASE_URL:?TMCRA_JUDGE_BASE_URL is required}"
+: "${TMCRA_JUDGE_API_KEY:?TMCRA_JUDGE_API_KEY is required}"
+
+python "$LEGACY/run_tmcra_v4_parallel_official_judge.py" \
+  --judge "$JUDGE" \
+  --metric-model gpt-4o \
+  --hyp-file "$RUN/answers_s500/answers.jsonl" \
+  --ref-file "$DATA" \
+  --result-file "$RUN/official_judge_gpt4o_20240806.jsonl" \
+  --work-dir "$RUN/official_judge_work" \
+  --base-url "$TMCRA_JUDGE_BASE_URL" \
+  --api-key-env TMCRA_JUDGE_API_KEY \
+  --workers "${JUDGE_WORKERS:-8}" \
+  --timeout 180 \
+  --process-timeout 240 \
+  --max-retries 0 \
+  --resume
+
+python scripts/validate_stage.py judge \
+  --run-dir "$RUN" \
+  --expected-qids "$QIDS" \
+  --judge-results "$RUN/official_judge_gpt4o_20240806.jsonl"
+
+python scripts/summarize_official_judge.py \
+  --judge-results "$RUN/official_judge_gpt4o_20240806.jsonl" \
+  --dataset "$DATA" \
+  --output "$RUN/scorecard.json"
+
+echo "TMCRA LongMemEval run complete: $RUN/scorecard.json"

benchmarks/longmemeval/scripts/reproduce_smoke.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT"
+
+DATA="${DATA:-$ROOT/fixtures/tiny_longmemeval.json}"
+OUT="${OUT:-$ROOT/runs/offline_fixture_check}"
+mkdir -p "$OUT"
+
+python scripts/prepare_longmemeval.py \
+  --data "$DATA" \
+  --qid-output "$OUT/qids.txt" \
+  --summary-output "$OUT/input_summary.json"
+python -m pytest
+
+echo "Offline fixture and unit tests passed."
+echo "This smoke test does not call Writer, Answer, or Judge providers."

benchmarks/longmemeval/scripts/summarize_official_judge.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import json
+from collections import defaultdict
+from pathlib import Path
+from typing import Any
+
+
+def read_jsonl(path: Path) -> list[dict[str, Any]]:
+    return [json.loads(line) for line in path.read_text(encoding="utf-8").splitlines() if line.strip()]
+
+
+def label(row: dict[str, Any]) -> bool:
+    value = row.get("autoeval_label")
+    if isinstance(value, dict):
+        value = value.get("label")
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        normalized = value.strip().lower()
+        if normalized in {"true", "1", "yes"}:
+            return True
+        if normalized in {"false", "0", "no"}:
+            return False
+    raise ValueError(f"invalid autoeval label: {value!r}")
+
+
+def summarize(dataset: list[dict[str, Any]], judged: list[dict[str, Any]]) -> dict[str, Any]:
+    type_by_qid = {str(row["question_id"]): str(row["question_type"]) for row in dataset}
+    seen: set[str] = set()
+    buckets: dict[str, list[bool]] = defaultdict(list)
+    all_labels: list[bool] = []
+    for row in judged:
+        qid = str(row.get("question_id") or "")
+        if qid not in type_by_qid or qid in seen:
+            raise ValueError(f"unknown or duplicate question_id: {qid!r}")
+        seen.add(qid)
+        result = label(row)
+        buckets[type_by_qid[qid]].append(result)
+        all_labels.append(result)
+    if len(seen) != len(dataset):
+        missing = sorted(set(type_by_qid) - seen)
+        raise ValueError(f"judge results are incomplete: {len(seen)}/{len(dataset)}; first missing={missing[:5]}")
+    by_type = {}
+    for name, values in sorted(buckets.items()):
+        correct = sum(values)
+        by_type[name] = {
+            "correct": correct,
+            "total": len(values),
+            "accuracy": round(correct / len(values), 6),
+            "accuracy_percent": round(correct * 100 / len(values), 1),
+        }
+    correct = sum(all_labels)
+    return {
+        "schema_version": "tmcra.longmemeval-scorecard.1",
+        "benchmark": "LongMemEval",
+        "correct": correct,
+        "total": len(all_labels),
+        "accuracy": round(correct / len(all_labels), 6),
+        "accuracy_percent": round(correct * 100 / len(all_labels), 1),
+        "by_question_type": by_type,
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--judge-results", required=True, type=Path)
+    parser.add_argument("--dataset", required=True, type=Path)
+    parser.add_argument("--output", required=True, type=Path)
+    args = parser.parse_args()
+    dataset = json.loads(args.dataset.read_text(encoding="utf-8"))
+    scorecard = summarize(dataset, read_jsonl(args.judge_results))
+    args.output.parent.mkdir(parents=True, exist_ok=True)
+    args.output.write_text(json.dumps(scorecard, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    print(json.dumps(scorecard, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

benchmarks/longmemeval/scripts/validate_stage.py

@@ -0,0 +1,237 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import json
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+
+PRODUCTION_ANSWER_PROTOCOL = "evidence_operation_bound_v6"
+
+
+def fail(message: str) -> None:
+    raise SystemExit(message)
+
+
+def require(path: Path) -> Path:
+    if not path.is_file():
+        fail(f"missing required artifact: {path}")
+    return path
+
+
+def read_json(path: Path) -> dict[str, Any]:
+    require(path)
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        fail(f"invalid JSON artifact {path}: {exc}")
+    if not isinstance(value, dict):
+        fail(f"JSON artifact must be an object: {path}")
+    return value
+
+
+def read_jsonl(path: Path) -> list[dict[str, Any]]:
+    require(path)
+    rows: list[dict[str, Any]] = []
+    for line_number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
+        if not line.strip():
+            continue
+        try:
+            value = json.loads(line)
+        except json.JSONDecodeError as exc:
+            fail(f"invalid JSONL row {path}:{line_number}: {exc}")
+        if not isinstance(value, dict):
+            fail(f"JSONL row must be an object: {path}:{line_number}")
+        rows.append(value)
+    return rows
+
+
+def qids(path: Path) -> list[str]:
+    require(path)
+    values = [line.strip() for line in path.read_text(encoding="utf-8").splitlines() if line.strip()]
+    if not values:
+        fail(f"QID list is empty: {path}")
+    if len(values) != len(set(values)):
+        fail(f"QID list contains duplicates: {path}")
+    return values
+
+
+def row_qids(path: Path) -> list[str]:
+    values = [str(row.get("question_id") or row.get("qid") or "").strip() for row in read_jsonl(path)]
+    if any(not value for value in values):
+        fail(f"artifact contains an empty QID: {path}")
+    if len(values) != len(set(values)):
+        fail(f"artifact contains duplicate QIDs: {path}")
+    return values
+
+
+def assert_qid_order(path: Path, expected: list[str]) -> None:
+    actual = row_qids(path)
+    if actual != expected:
+        fail(f"QID mismatch in {path}: got {len(actual)} ordered rows, expected {len(expected)}")
+
+
+def assert_complete_report(
+    path: Path,
+    *,
+    expected_count: int,
+    count_field: str,
+) -> dict[str, Any]:
+    report = read_json(path)
+    if report.get("status") != "complete":
+        fail(f"report is not complete: {path}")
+    try:
+        actual_count = int(report.get(count_field, -1))
+    except (TypeError, ValueError):
+        fail(f"report has an invalid {count_field}: {path}")
+    if actual_count != expected_count:
+        fail(f"report {count_field} mismatch in {path}: {actual_count}/{expected_count}")
+    return report
+
+
+def validate_build(run_dir: Path, expected: list[str]) -> None:
+    require(run_dir / "BUILD_COMPLETE")
+    require(run_dir / "qids.txt")
+    if qids(run_dir / "qids.txt") != expected:
+        fail("build qids.txt does not match the requested QID order")
+
+    manifest = read_json(run_dir / "input_manifest.json")
+    if manifest.get("status") != "prepared":
+        fail("build input manifest is not in prepared state")
+    if list(manifest.get("qids") or []) != expected:
+        fail("build input manifest QIDs do not match the requested QID order")
+    if int(manifest.get("row_count", -1)) != len(expected):
+        fail("build input manifest row_count is inconsistent")
+    workers = manifest.get("workers")
+    if not isinstance(workers, list):
+        fail("build input manifest workers must be a list")
+    worker_qids = [str(row.get("question_id") or "").strip() for row in workers if isinstance(row, Mapping)]
+    if len(worker_qids) != len(workers) or worker_qids != expected:
+        fail("build worker QIDs do not match the requested QID order")
+
+    assert_qid_order(run_dir / "scope_manifest.jsonl", expected)
+    assert_qid_order(run_dir / "query_manifest.jsonl", expected)
+    assert_complete_report(
+        run_dir / "build_report.json",
+        expected_count=len(expected),
+        count_field="row_count",
+    )
+    assert_complete_report(
+        run_dir / "index_report.json",
+        expected_count=len(expected),
+        count_field="row_count",
+    )
+
+
+def validate_retrieve(run_dir: Path, tag: str, expected: list[str]) -> None:
+    directory = run_dir / tag
+    require(directory / "RETRIEVAL_COMPLETE")
+    assert_complete_report(
+        directory / "report.json",
+        expected_count=len(expected),
+        count_field="query_count",
+    )
+    run_report = assert_complete_report(
+        directory / "retrieval_run_report.json",
+        expected_count=len(expected),
+        count_field="query_count",
+    )
+    if str(run_report.get("tag") or "") != tag:
+        fail(f"retrieval tag mismatch in {directory / 'retrieval_run_report.json'}")
+    assert_qid_order(directory / "evidence_windows.jsonl", expected)
+    assert_qid_order(directory / "retrieval_debug.jsonl", expected)
+
+
+def validate_compile(run_dir: Path, expected: list[str]) -> None:
+    require(run_dir / "COMPILE_COMPLETE")
+    assert_complete_report(
+        run_dir / "report.json",
+        expected_count=len(expected),
+        count_field="row_count",
+    )
+    assert_qid_order(run_dir / "evidence_windows.jsonl", expected)
+    assert_qid_order(run_dir / "retrieval_debug.jsonl", expected)
+
+
+def validate_answer(run_dir: Path, expected: list[str]) -> None:
+    report = assert_complete_report(
+        run_dir / "report.json",
+        expected_count=len(expected),
+        count_field="requested",
+    )
+    if int(report.get("completed", -1)) != len(expected):
+        fail(f"answer report completed count mismatch: {report.get('completed')}/{len(expected)}")
+    if int(report.get("failure_count", -1)) != 0:
+        fail(f"answer report contains failures: {report.get('failure_count')}")
+    if report.get("answer_model") != "gpt-5.4":
+        fail(f"answer report used an unexpected model: {report.get('answer_model')!r}")
+    if report.get("answer_protocol") != PRODUCTION_ANSWER_PROTOCOL:
+        fail(f"answer report used an unexpected protocol: {report.get('answer_protocol')!r}")
+    if report.get("lane") != "production" or report.get("promotion_eligible") is not True:
+        fail("answer report is not a promotion-eligible production run")
+    if report.get("compiled_evidence_packet_required") is not True:
+        fail("answer report did not require compiled evidence packets")
+    answers_path = run_dir / "answers.jsonl"
+    assert_qid_order(answers_path, expected)
+    for row in read_jsonl(answers_path):
+        if row.get("answer_model") != "gpt-5.4":
+            fail(f"answer row used an unexpected model: {row.get('question_id')}")
+        if row.get("answer_protocol") != PRODUCTION_ANSWER_PROTOCOL:
+            fail(f"answer row used an unexpected protocol: {row.get('question_id')}")
+
+
+def validate_judge(results: Path, expected: list[str]) -> None:
+    assert_qid_order(results, expected)
+    rows = read_jsonl(results)
+    for row in rows:
+        label = row.get("autoeval_label")
+        if not isinstance(label, Mapping) or type(label.get("label")) is not bool:
+            fail(f"judge row has no valid boolean label: {row.get('question_id')}")
+        if label.get("model") != "gpt-4o-2024-08-06":
+            fail(f"judge row used an unexpected model: {label.get('model')!r}")
+
+    report_path = results.with_name(f"{results.name}.isolated_report.json")
+    report = read_json(report_path)
+    if report.get("status") != "complete":
+        fail(f"judge report is not complete: {report_path}")
+    if int(report.get("row_count", -1)) != len(expected):
+        fail(f"judge row_count mismatch in {report_path}")
+    if int(report.get("committed_count", -1)) != len(expected):
+        fail(f"judge committed_count mismatch in {report_path}")
+    if int(report.get("failure_count", -1)) != 0:
+        fail(f"judge report contains failures: {report_path}")
+    if report.get("metric_model") not in {"gpt-4o", "gpt-4o-2024-08-06"}:
+        fail(f"judge report used an unexpected model alias: {report.get('metric_model')!r}")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("stage", choices=("build", "retrieve", "compile", "answer", "judge"))
+    parser.add_argument("--run-dir", required=True, type=Path)
+    parser.add_argument("--expected-qids", required=True, type=Path)
+    parser.add_argument("--tag", default="retrieval_s500")
+    parser.add_argument("--judge-results", type=Path)
+    args = parser.parse_args()
+    expected = qids(args.expected_qids)
+
+    if args.stage == "build":
+        validate_build(args.run_dir, expected)
+    elif args.stage == "retrieve":
+        validate_retrieve(args.run_dir, args.tag, expected)
+    elif args.stage == "compile":
+        validate_compile(args.run_dir, expected)
+    elif args.stage == "answer":
+        validate_answer(args.run_dir, expected)
+    else:
+        if args.judge_results is None:
+            fail("--judge-results is required for the judge stage")
+        validate_judge(args.judge_results, expected)
+
+    print(f"{args.stage} validation: OK ({len(expected)} QIDs)")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

benchmarks/longmemeval/src/tmcra_benchmark/__init__.py

@@ -0,0 +1,3 @@
+"""TMCRA LongMemEval benchmark reproduction package."""
+
+__version__ = "0.1.0"

benchmarks/longmemeval/src/tmcra_benchmark/harness/__init__.py

@@ -0,0 +1 @@
+"""LongMemEval adapter and official judge integration."""

benchmarks/longmemeval/src/tmcra_benchmark/harness/evaluate_qa_official_judge.py

@@ -0,0 +1,295 @@
+#!/usr/bin/env python3
+"""LongMemEval official-prompt QA judge.
+
+This is an implementation-compatible wrapper around the public LongMemEval
+`src/evaluation/evaluate_qa.py` logic. The scoring prompt and yes/no rule are
+kept equivalent, while the runner adds resume support and avoids extra Python
+package dependencies by using urllib.
+
+For official reporting, use:
+  --metric-model gpt-4o
+with OPENAI_API_KEY set. The resolved model is gpt-4o-2024-08-06, matching the
+official evaluator's model alias.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+from statistics import mean
+from typing import Any
+
+
+MODEL_ZOO = {
+    "gpt5.4": ("gpt-5.4", "openai"),
+    "gpt-5.4": ("gpt-5.4", "openai"),
+    "gpt-4o-mini": ("gpt-4o-mini-2024-07-18", "openai"),
+    "gpt-4o": ("gpt-4o-2024-08-06", "openai"),
+    "gpt-4o-2024-08-06": ("gpt-4o-2024-08-06", "openai"),
+    "llama-3.1-70b-instruct": ("meta-llama/Meta-Llama-3.1-70B-Instruct", "local"),
+}
+
+
+def get_anscheck_prompt(task: str, question: str, answer: str, response: str, abstention: bool = False) -> str:
+    if not abstention:
+        if task in ["single-session-user", "single-session-assistant", "multi-session"]:
+            template = (
+                "I will give you a question, a correct answer, and a response from a model. "
+                "Please answer yes if the response contains the correct answer. Otherwise, answer no. "
+                "If the response is equivalent to the correct answer or contains all the intermediate steps to get the correct answer, you should also answer yes. "
+                "If the response only contains a subset of the information required by the answer, answer no. \n\n"
+                "Question: {}\n\nCorrect Answer: {}\n\nModel Response: {}\n\n"
+                "Is the model response correct? Answer yes or no only."
+            )
+            return template.format(question, answer, response)
+        if task == "temporal-reasoning":
+            template = (
+                "I will give you a question, a correct answer, and a response from a model. "
+                "Please answer yes if the response contains the correct answer. Otherwise, answer no. "
+                "If the response is equivalent to the correct answer or contains all the intermediate steps to get the correct answer, you should also answer yes. "
+                "If the response only contains a subset of the information required by the answer, answer no. "
+                "In addition, do not penalize off-by-one errors for the number of days. "
+                "If the question asks for the number of days/weeks/months, etc., and the model makes off-by-one errors (e.g., predicting 19 days when the answer is 18), the model's response is still correct. \n\n"
+                "Question: {}\n\nCorrect Answer: {}\n\nModel Response: {}\n\n"
+                "Is the model response correct? Answer yes or no only."
+            )
+            return template.format(question, answer, response)
+        if task == "knowledge-update":
+            template = (
+                "I will give you a question, a correct answer, and a response from a model. "
+                "Please answer yes if the response contains the correct answer. Otherwise, answer no. "
+                "If the response contains some previous information along with an updated answer, the response should be considered as correct as long as the updated answer is the required answer.\n\n"
+                "Question: {}\n\nCorrect Answer: {}\n\nModel Response: {}\n\n"
+                "Is the model response correct? Answer yes or no only."
+            )
+            return template.format(question, answer, response)
+        if task == "single-session-preference":
+            template = (
+                "I will give you a question, a rubric for desired personalized response, and a response from a model. "
+                "Please answer yes if the response satisfies the desired response. Otherwise, answer no. "
+                "The model does not need to reflect all the points in the rubric. "
+                "The response is correct as long as it recalls and utilizes the user's personal information correctly.\n\n"
+                "Question: {}\n\nRubric: {}\n\nModel Response: {}\n\n"
+                "Is the model response correct? Answer yes or no only."
+            )
+            return template.format(question, answer, response)
+        raise NotImplementedError(f"Unsupported question_type: {task}")
+
+    template = (
+        "I will give you an unanswerable question, an explanation, and a response from a model. "
+        "Please answer yes if the model correctly identifies the question as unanswerable. "
+        "The model could say that the information is incomplete, or some other information is given but the asked information is not.\n\n"
+        "Question: {}\n\nExplanation: {}\n\nModel Response: {}\n\n"
+        "Does the model correctly identify the question as unanswerable? Answer yes or no only."
+    )
+    return template.format(question, answer, response)
+
+
+def load_json_or_jsonl(path: Path) -> list[dict[str, Any]]:
+    text = path.read_text(encoding="utf-8")
+    try:
+        data = json.loads(text)
+        if isinstance(data, list):
+            return data
+        if isinstance(data, dict):
+            return [data]
+        raise ValueError(f"{path} JSON root is not a list")
+    except json.JSONDecodeError:
+        return [json.loads(line) for line in text.splitlines() if line.strip()]
+
+
+def call_chat_completion(
+    *,
+    base_url: str,
+    api_key: str,
+    model: str,
+    prompt: str,
+    timeout: int,
+    max_retries: int,
+) -> str:
+    wire_api = os.environ.get("OPENAI_WIRE_API", "").strip().lower()
+    if wire_api == "responses":
+        url = base_url.rstrip("/") + "/responses"
+        payload = {
+            "model": model,
+            "input": [{"role": "user", "content": prompt}],
+            "temperature": 0,
+            "max_output_tokens": 10,
+        }
+    else:
+        url = base_url.rstrip("/") + "/chat/completions"
+        payload = {
+            "model": model,
+            "messages": [{"role": "user", "content": prompt}],
+            "n": 1,
+            "temperature": 0,
+            "max_tokens": 10,
+        }
+    body = json.dumps(payload).encode("utf-8")
+    headers = {
+        "Content-Type": "application/json",
+        "Authorization": f"Bearer {api_key}",
+    }
+    last_error: Exception | None = None
+    for attempt in range(max_retries + 1):
+        req = urllib.request.Request(url, data=body, headers=headers, method="POST")
+        try:
+            with urllib.request.urlopen(req, timeout=timeout) as resp:
+                data = json.loads(resp.read().decode("utf-8"))
+            if wire_api == "responses":
+                output_text = str(data.get("output_text", "")).strip()
+                if output_text:
+                    return output_text
+                chunks: list[str] = []
+                for item in data.get("output", []) or []:
+                    for content in item.get("content", []) or []:
+                        text = content.get("text") or content.get("content") or ""
+                        if text:
+                            chunks.append(str(text))
+                return "\n".join(chunks).strip()
+            return data["choices"][0]["message"]["content"].strip()
+        except (urllib.error.HTTPError, urllib.error.URLError, TimeoutError) as exc:
+            last_error = exc
+            if attempt >= max_retries:
+                break
+            time.sleep(min(60, 2**attempt))
+    raise RuntimeError(f"chat completion failed after {max_retries + 1} attempts: {last_error}")
+
+
+def read_existing_labels(result_file: Path) -> dict[str, dict[str, Any]]:
+    done: dict[str, dict[str, Any]] = {}
+    if not result_file.exists():
+        return done
+    with result_file.open("r", encoding="utf-8") as f:
+        for line in f:
+            if not line.strip():
+                continue
+            item = json.loads(line)
+            qid = str(item.get("question_id", ""))
+            if qid:
+                done[qid] = item
+    return done
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--metric-model", default="gpt-4o", choices=sorted(MODEL_ZOO))
+    parser.add_argument("--hyp-file", required=True, type=Path)
+    parser.add_argument("--ref-file", required=True, type=Path)
+    parser.add_argument("--result-file", type=Path)
+    parser.add_argument("--base-url", default=None)
+    parser.add_argument("--api-key-env", default="OPENAI_API_KEY")
+    parser.add_argument("--limit", type=int, default=0)
+    parser.add_argument("--timeout", type=int, default=120)
+    parser.add_argument("--max-retries", type=int, default=6)
+    parser.add_argument("--resume", action="store_true")
+    parser.add_argument("--quiet", action="store_true")
+    args = parser.parse_args()
+
+    model, source = MODEL_ZOO[args.metric_model]
+    if source == "openai":
+        base_url = args.base_url or "https://api.openai.com/v1"
+    else:
+        base_url = args.base_url or "http://localhost:8001/v1"
+
+    api_key = os.getenv(args.api_key_env)
+    if not api_key:
+        print(f"Missing API key env: {args.api_key_env}", file=sys.stderr)
+        return 2
+
+    hypotheses = load_json_or_jsonl(args.hyp_file)
+    references = load_json_or_jsonl(args.ref_file)
+    qid2qdata = {str(entry["question_id"]): entry for entry in references}
+    qid2qtype = {str(entry["question_id"]): entry["question_type"] for entry in references}
+
+    if args.limit and args.limit > 0:
+        hypotheses = hypotheses[: args.limit]
+
+    result_file = args.result_file or Path(str(args.hyp_file) + f".eval-results-{args.metric_model}")
+    result_file.parent.mkdir(parents=True, exist_ok=True)
+    existing = read_existing_labels(result_file) if args.resume else {}
+
+    logs: list[dict[str, Any]] = list(existing.values())
+    qtype2acc: dict[str, list[int]] = {}
+    for item in logs:
+        qid = str(item.get("question_id"))
+        if qid in qid2qtype and item.get("autoeval_label"):
+            qtype2acc.setdefault(qid2qtype[qid], []).append(1 if item["autoeval_label"].get("label") else 0)
+
+    mode = "a" if args.resume and result_file.exists() else "w"
+    with result_file.open(mode, encoding="utf-8") as out_f:
+        for idx, entry in enumerate(hypotheses, 1):
+            qid = str(entry.get("question_id", ""))
+            if not qid or qid not in qid2qdata:
+                print(f"Warning: skipping unknown question_id={qid}", file=sys.stderr)
+                continue
+            if qid in existing:
+                continue
+            qtype = qid2qtype[qid]
+            qdata = qid2qdata[qid]
+            prompt = get_anscheck_prompt(
+                qtype,
+                str(qdata["question"]),
+                str(qdata["answer"]),
+                str(entry.get("hypothesis", "")),
+                abstention="_abs" in qid,
+            )
+            eval_response = call_chat_completion(
+                base_url=base_url,
+                api_key=api_key,
+                model=model,
+                prompt=prompt,
+                timeout=args.timeout,
+                max_retries=args.max_retries,
+            )
+            label = "yes" in eval_response.lower()
+            output = dict(entry)
+            output["autoeval_label"] = {"model": model, "label": label, "raw_response": eval_response}
+            print(json.dumps(output, ensure_ascii=False), file=out_f, flush=True)
+            logs.append(output)
+            qtype2acc.setdefault(qtype, []).append(1 if label else 0)
+            if not args.quiet:
+                print(
+                    json.dumps(
+                        {
+                            "index": idx,
+                            "question_id": qid,
+                            "label": label,
+                            "raw_response": eval_response,
+                            "question": qdata["question"],
+                            "answer": qdata["answer"],
+                            "hypothesis": entry.get("hypothesis", ""),
+                        },
+                        ensure_ascii=False,
+                    ),
+                    flush=True,
+                )
+
+    labels = [1 if x.get("autoeval_label", {}).get("label") else 0 for x in logs if x.get("autoeval_label")]
+    summary = {
+        "metric_model_alias": args.metric_model,
+        "metric_model": model,
+        "base_url": base_url,
+        "hyp_file": str(args.hyp_file),
+        "ref_file": str(args.ref_file),
+        "result_file": str(result_file),
+        "evaluated_count": len(labels),
+        "accuracy": round(mean(labels), 4) if labels else None,
+        "by_question_type": {
+            k: {"accuracy": round(mean(v), 4), "count": len(v)} for k, v in sorted(qtype2acc.items()) if v
+        },
+    }
+    summary_file = Path(str(result_file) + ".summary.json")
+    summary_file.write_text(json.dumps(summary, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    print(json.dumps(summary, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

benchmarks/longmemeval/src/tmcra_benchmark/legacy/__init__.py

@@ -0,0 +1 @@
+"""Hash-pinned TMCRA V4 benchmark implementation."""

benchmarks/longmemeval/src/tmcra_benchmark/legacy/build_v3_runtime_dataset.py

@@ -0,0 +1,791 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import re
+import time
+from collections import Counter
+from pathlib import Path
+from typing import Any, Iterable, Mapping, Sequence
+
+import torch
+
+from tmcra_v2_lme_pipeline import EmbeddingCacheVectorizer, session_text_chunks
+from tmcra_v3_schema import (
+    CHANNEL_NAMES,
+    SCHEMA_VERSION,
+    clean_text,
+    read_jsonl,
+    validate_sample,
+    validate_split_isolation,
+    write_jsonl,
+)
+
+
+EVENT_INDEX_RE = re.compile(
+    r"^event::longmemeval:(?P<qid>[^:]+):s(?P<session>\d+)_c(?P<parent>\d+)$"
+)
+TEACHER_EVENT_INDEX_RE = re.compile(r":s(?P<session>\d+)_c(?P<parent>\d+)$")
+RAW_TEACHER_EVENT_RE = re.compile(
+    r"^lme:[^:]+:session:(?P<session>[^:]+):turn:(?P<turn>\d+)$"
+)
+TURN_BOUNDARY_RE = re.compile(r"\n\[[^\]]+ turn=\d+ role=")
+
+
+def stable_int(value: str) -> int:
+    return int.from_bytes(hashlib.blake2b(value.encode("utf-8"), digest_size=8).digest(), "big")
+
+
+def normalized_question(value: Any) -> str:
+    return clean_text(value).casefold()
+
+
+def load_teacher_supervision(path: Path) -> dict[str, dict[str, Any]]:
+    output: dict[str, dict[str, Any]] = {}
+    for row in read_jsonl(path):
+        question_key = normalized_question(row.get("question"))
+        if not question_key:
+            raise RuntimeError("teacher row is missing question text")
+        if question_key in output:
+            raise RuntimeError(f"duplicate teacher question after exact normalization: {row.get('question')!r}")
+        if not bool(row.get("usable_for_training", False)):
+            continue
+        if not list(row.get("positive_event_ids") or []):
+            raise RuntimeError(f"teacher row has no positive events: {row.get('question_id')}")
+        output[question_key] = row
+    if not output:
+        raise RuntimeError(f"no usable teacher supervision rows: {path}")
+    return output
+
+
+def teacher_parent_locations(event_ids: Iterable[Any], valid_locations: set[tuple[int, int]], qid: str) -> list[tuple[int, int]]:
+    output: list[tuple[int, int]] = []
+    seen: set[tuple[int, int]] = set()
+    for raw in event_ids:
+        event_id = clean_text(raw)
+        match = TEACHER_EVENT_INDEX_RE.search(event_id)
+        if match is None:
+            raise RuntimeError(f"{qid}: teacher event is not a runtime parent event: {event_id}")
+        location = (int(match.group("session")), int(match.group("parent")))
+        if location not in valid_locations:
+            raise RuntimeError(f"{qid}: teacher event has no parent in the current inventory: {event_id}")
+        if location not in seen:
+            seen.add(location)
+            output.append(location)
+    return output
+
+
+def reconstruct_parent_text(candidates: Sequence[Mapping[str, Any]], indexes: Sequence[int], qid: str) -> str:
+    if not indexes:
+        raise RuntimeError(f"{qid}: cannot reconstruct an empty parent")
+    total = max(int(candidates[index]["source_char_end"]) for index in indexes)
+    characters: list[str | None] = [None] * total
+    for index in indexes:
+        candidate = candidates[index]
+        text = str(candidate["text"])
+        if "\n" not in text:
+            raise RuntimeError(f"{qid}: inventory candidate is missing its payload separator")
+        payload = text.split("\n", 1)[1]
+        start = int(candidate["source_char_start"])
+        end = int(candidate["source_char_end"])
+        if len(payload) != end - start:
+            raise RuntimeError(f"{qid}: inventory candidate payload length does not match its source span")
+        for offset, character in enumerate(payload, start=start):
+            existing = characters[offset]
+            if existing is not None and existing != character:
+                raise RuntimeError(f"{qid}: overlapping inventory subchunks disagree")
+            characters[offset] = character
+    if any(character is None for character in characters):
+        raise RuntimeError(f"{qid}: reconstructed parent contains a character coverage gap")
+    return "".join(character for character in characters if character is not None)
+
+
+def teacher_turn_candidate_indexes(
+    event_ids: Iterable[Any],
+    *,
+    candidates: Sequence[Mapping[str, Any]],
+    parent_candidates: Mapping[tuple[int, int], Sequence[int]],
+    qid: str,
+) -> set[int]:
+    output: set[int] = set()
+    session_locations: dict[str, list[tuple[int, int]]] = {}
+    for location, indexes in parent_candidates.items():
+        session_id = clean_text(candidates[indexes[0]].get("session_id"))
+        session_locations.setdefault(session_id, []).append(location)
+    parent_text_cache: dict[tuple[int, int], str] = {}
+    for raw in event_ids:
+        event_id = clean_text(raw)
+        match = RAW_TEACHER_EVENT_RE.match(event_id)
+        if match is None:
+            raise RuntimeError(f"{qid}: teacher raw event is malformed: {event_id}")
+        session_id = clean_text(match.group("session"))
+        turn = int(match.group("turn"))
+        marker = f"[{session_id} turn={turn} role="
+        matches: list[tuple[tuple[int, int], int, int]] = []
+        for location in session_locations.get(session_id, []):
+            if location not in parent_text_cache:
+                parent_text_cache[location] = reconstruct_parent_text(
+                    candidates, parent_candidates[location], qid
+                )
+            parent_text = parent_text_cache[location]
+            turn_start = parent_text.find(marker)
+            if turn_start < 0:
+                continue
+            next_turn = TURN_BOUNDARY_RE.search(parent_text, turn_start + len(marker))
+            turn_end = next_turn.start() if next_turn else len(parent_text)
+            matches.append((location, turn_start, turn_end))
+        if len(matches) != 1:
+            raise RuntimeError(
+                f"{qid}: teacher event must map to exactly one current parent turn, got {len(matches)}: {event_id}"
+            )
+        location, turn_start, turn_end = matches[0]
+        matched_subchunks = {
+            index
+            for index in parent_candidates[location]
+            if int(candidates[index]["source_char_start"]) < turn_end
+            and int(candidates[index]["source_char_end"]) > turn_start
+        }
+        if not matched_subchunks:
+            raise RuntimeError(f"{qid}: teacher turn has no overlapping subchunk: {event_id}")
+        output.update(matched_subchunks)
+    return output
+
+
+def covered_windows(text: str, max_chars: int, overlap: int) -> list[tuple[int, int]]:
+    if max_chars <= 0:
+        raise RuntimeError("subchunk payload size must be positive")
+    if overlap < 0 or overlap >= max_chars:
+        raise RuntimeError("subchunk overlap must be non-negative and smaller than the payload")
+    if not text:
+        return []
+    spans: list[tuple[int, int]] = []
+    start = 0
+    while start < len(text):
+        hard_end = min(len(text), start + max_chars)
+        end = hard_end
+        if hard_end < len(text):
+            floor = max(start + max_chars // 2, hard_end - 160)
+            split_at = text.rfind(" ", floor, hard_end)
+            if split_at > start:
+                end = split_at
+        if end <= start:
+            end = hard_end
+        spans.append((start, end))
+        if end >= len(text):
+            break
+        start = max(start + 1, end - overlap)
+    if spans[0][0] != 0 or spans[-1][1] != len(text):
+        raise AssertionError("subchunk coverage does not reach both text boundaries")
+    if any(right_start > left_end for (_, left_end), (right_start, _) in zip(spans, spans[1:])):
+        raise AssertionError("subchunk coverage contains a gap")
+    return spans
+
+
+def load_lme(path: Path) -> list[dict[str, Any]]:
+    value = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(value, list) or not value:
+        raise RuntimeError(f"LongMemEval data must be a non-empty list: {path}")
+    rows = [row for row in value if isinstance(row, dict)]
+    qids = [clean_text(row.get("question_id")) for row in rows]
+    if len(qids) != len(set(qids)):
+        raise RuntimeError("LongMemEval question_id values are not unique")
+    return rows
+
+
+def choose_holdout(rows: Sequence[Mapping[str, Any]], count: int) -> list[str]:
+    if count <= 0 or count >= len(rows):
+        raise RuntimeError(f"holdout count must be between 1 and {len(rows) - 1}")
+    by_type: dict[str, list[str]] = {}
+    for row in rows:
+        qid = clean_text(row.get("question_id"))
+        qtype = clean_text(row.get("question_type")) or "unknown"
+        by_type.setdefault(qtype, []).append(qid)
+    selected: list[str] = []
+    for qtype, qids in sorted(by_type.items()):
+        qids.sort(key=lambda qid: (stable_int(f"tmcra-v3-holdout:{qid}"), qid))
+        quota = int(len(qids) * count / len(rows))
+        selected.extend(qids[:quota])
+    selected_set = set(selected)
+    remaining = [clean_text(row.get("question_id")) for row in rows if clean_text(row.get("question_id")) not in selected_set]
+    remaining.sort(key=lambda qid: (stable_int(f"tmcra-v3-holdout-fill:{qid}"), qid))
+    selected.extend(remaining[: max(0, count - len(selected))])
+    selected = sorted(selected[:count])
+    if len(selected) != count or len(set(selected)) != count:
+        raise RuntimeError("failed to construct an exact unique holdout")
+    return selected
+
+
+def make_inventory_row(
+    row: Mapping[str, Any],
+    split: str,
+    parent_chars: int,
+    subchunk_chars: int,
+    subchunk_overlap: int,
+) -> dict[str, Any]:
+    qid = clean_text(row.get("question_id"))
+    question = clean_text(row.get("question"))
+    question_date = clean_text(row.get("question_date"))
+    query_text = f"{question}\nQuestion date: {question_date}" if question_date else question
+    sessions = list(row.get("haystack_sessions") or [])
+    session_ids = [clean_text(value) for value in list(row.get("haystack_session_ids") or [])]
+    dates = [clean_text(value) for value in list(row.get("haystack_dates") or [])]
+    answer_session_ids = {clean_text(value) for value in list(row.get("answer_session_ids") or []) if clean_text(value)}
+    if not sessions or len(sessions) != len(session_ids):
+        raise RuntimeError(f"{qid}: haystack session/id mismatch")
+    candidates: list[dict[str, Any]] = []
+    found_gold: set[str] = set()
+    parent_chunk_count = 0
+    source_parent_chars = 0
+    for index, session in enumerate(sessions):
+        session_id = session_ids[index]
+        date = dates[index] if index < len(dates) else ""
+        if not isinstance(session, Sequence) or isinstance(session, (str, bytes, bytearray)):
+            raise RuntimeError(f"{qid}: session {index} is not a turn list")
+        turns = list(session)
+        if any(not isinstance(turn, Mapping) for turn in turns):
+            raise RuntimeError(f"{qid}: session {index} contains a non-object turn")
+        parent_chunks = session_text_chunks(
+            session_id=session_id,
+            date=date,
+            turns=turns,
+            max_chars=parent_chars,
+            max_chunks=0,
+        )
+        if not parent_chunks:
+            parent_chunks = [f"LongMemEval session_id={session_id} date={date}"]
+        relevant = session_id in answer_session_ids
+        if relevant:
+            found_gold.add(session_id)
+        for parent_index, parent_text in enumerate(parent_chunks, start=1):
+            parent_chunk_count += 1
+            source_parent_chars += len(parent_text)
+            prefix = (
+                f"LongMemEval session_id={session_id} date={date} "
+                f"parent_chunk={parent_index:02d}"
+            )
+            payload_chars = subchunk_chars - len(prefix) - 1
+            spans = covered_windows(parent_text, payload_chars, subchunk_overlap)
+            for subchunk_index, (char_start, char_end) in enumerate(spans, start=1):
+                text = f"{prefix}\n{parent_text[char_start:char_end]}"
+                if len(text) > subchunk_chars:
+                    raise AssertionError(f"{qid}: generated subchunk exceeds configured character cap")
+                candidates.append(
+                    {
+                        "candidate_id": (
+                            f"chunk::longmemeval:{qid}:s{index:03d}_c{parent_index:02d}_p{subchunk_index:02d}"
+                        ),
+                        "text": text,
+                        "session_id": session_id,
+                        "session_index": index,
+                        "parent_chunk_index": parent_index,
+                        "subchunk_index": subchunk_index,
+                        "source_char_start": char_start,
+                        "source_char_end": char_end,
+                        "labels": {
+                            "relevance": relevant,
+                            "hard_negative": False,
+                            "evidence_role": "positive" if relevant else "negative",
+                            "target_scope": "answer_session_bag",
+                        },
+                    }
+                )
+    if found_gold != answer_session_ids:
+        raise RuntimeError(f"{qid}: answer sessions missing from haystack: {sorted(answer_session_ids - found_gold)}")
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "question_id": qid,
+        "question": question,
+        "question_date": question_date,
+        "query_text": query_text,
+        "question_type": clean_text(row.get("question_type")),
+        "split": split,
+        "gold_answer": clean_text(row.get("answer")),
+        "answer_session_ids": sorted(answer_session_ids),
+        "supervision": {
+            "target_type": "multi_instance_answer_session_bag",
+            "loss": "negative_log_positive_probability_mass",
+        },
+        "inventory_metadata": {
+            "session_count": len(sessions),
+            "parent_chunk_count": parent_chunk_count,
+            "candidate_subchunk_count": len(candidates),
+            "source_parent_chars": source_parent_chars,
+            "parent_chars": parent_chars,
+            "subchunk_chars": subchunk_chars,
+            "subchunk_overlap": subchunk_overlap,
+            "truncated": False,
+        },
+        "candidates": candidates,
+    }
+
+
+def command_inventory(args: argparse.Namespace) -> None:
+    out_dir = Path(args.out_dir)
+    out_dir.mkdir(parents=True, exist_ok=False)
+    rows = load_lme(Path(args.data))
+    holdout = set(choose_holdout(rows, args.holdout_count))
+    inventory_rows = [
+        make_inventory_row(
+            row,
+            "holdout" if clean_text(row.get("question_id")) in holdout else "train",
+            args.parent_chars,
+            args.subchunk_chars,
+            args.subchunk_overlap,
+        )
+        for row in rows
+    ]
+    holdout_rows = [row for row in inventory_rows if row["split"] == "holdout"]
+    train_rows = [row for row in inventory_rows if row["split"] == "train"]
+    isolation = validate_split_isolation(train_rows, holdout_rows)
+    write_jsonl(out_dir / "inventory.jsonl", inventory_rows)
+    (out_dir / "holdout_qids.txt").write_text("\n".join(sorted(holdout)) + "\n", encoding="utf-8")
+    report = {
+        "schema_version": SCHEMA_VERSION,
+        "created_at": time.strftime("%Y-%m-%dT%H:%M:%S%z"),
+        "data": str(Path(args.data).resolve()),
+        "row_count": len(inventory_rows),
+        "train_count": len(train_rows),
+        "holdout_count": len(holdout_rows),
+        "candidate_count": sum(len(row["candidates"]) for row in inventory_rows),
+        "candidate_count_avg": round(sum(len(row["candidates"]) for row in inventory_rows) / len(inventory_rows), 4),
+        "parent_chunk_count": sum(row["inventory_metadata"]["parent_chunk_count"] for row in inventory_rows),
+        "session_count": sum(row["inventory_metadata"]["session_count"] for row in inventory_rows),
+        "positive_bag_candidate_count": sum(
+            int(candidate["labels"]["relevance"])
+            for row in inventory_rows
+            for candidate in row["candidates"]
+        ),
+        "max_candidate_chars": max(len(candidate["text"]) for row in inventory_rows for candidate in row["candidates"]),
+        "truncated_candidate_count": 0,
+        "parent_chars": args.parent_chars,
+        "subchunk_chars": args.subchunk_chars,
+        "subchunk_overlap": args.subchunk_overlap,
+        "question_types": dict(Counter(row["question_type"] for row in inventory_rows)),
+        "holdout_question_types": dict(Counter(row["question_type"] for row in holdout_rows)),
+        "isolation": isolation,
+    }
+    (out_dir / "inventory_report.json").write_text(json.dumps(report, indent=2, sort_keys=True), encoding="utf-8")
+    print(json.dumps(report, indent=2, sort_keys=True))
+
+
+def load_graph_debug(run_dir: Path) -> dict[str, dict[str, Any]]:
+    output: dict[str, dict[str, Any]] = {}
+    paths = sorted(run_dir.glob("shard_*_out/samples_debug.jsonl"))
+    if not paths:
+        raise FileNotFoundError(f"no graph debug shards under {run_dir}")
+    for path in paths:
+        for row in read_jsonl(path):
+            qid = clean_text(row.get("question_id"))
+            if qid:
+                output[qid] = row
+    return output
+
+
+def ordered_parent_locations(
+    event_ids: Iterable[Any],
+    *,
+    qid: str,
+    valid_locations: set[tuple[int, int]],
+) -> list[tuple[int, int]]:
+    output: list[tuple[int, int]] = []
+    seen: set[tuple[int, int]] = set()
+    for raw in event_ids:
+        event_id = clean_text(raw)
+        match = EVENT_INDEX_RE.match(event_id)
+        if match is None:
+            continue
+        if clean_text(match.group("qid")) != qid:
+            raise RuntimeError(f"{qid}: graph debug contains an event for another question: {event_id}")
+        location = (int(match.group("session")), int(match.group("parent")))
+        if location not in valid_locations:
+            raise RuntimeError(f"{qid}: graph event has no exact parent chunk mapping: {event_id}")
+        if location in seen:
+            continue
+        seen.add(location)
+        output.append(location)
+    return output
+
+
+def expand_parent_locations(
+    locations: Iterable[tuple[int, int]],
+    parent_candidates: Mapping[tuple[int, int], Sequence[int]],
+) -> list[int]:
+    output: list[int] = []
+    seen: set[int] = set()
+    for location in locations:
+        for index in parent_candidates[location]:
+            if index not in seen:
+                seen.add(index)
+                output.append(index)
+    return output
+
+
+def rrank(rank: int | None) -> float:
+    return 0.0 if rank is None else 1.0 / float(rank + 1)
+
+
+def canonical_candidate(
+    raw: Mapping[str, Any],
+    *,
+    relevant: bool,
+    session_relevant: bool,
+    teacher_relevant: bool | None,
+    dense_score: float,
+    dense_rank: int,
+    graph_rank: int | None,
+    graph_selected: bool,
+    graph_final: bool,
+    session_count: int,
+    forced_positive: bool,
+    hard_negative: bool,
+) -> dict[str, Any]:
+    relevant = bool(relevant)
+    hard_negative = bool(hard_negative and not relevant)
+    channels = {
+        "dense_score": float(dense_score),
+        "dense_rank_rr": rrank(dense_rank),
+        "graph_rank_rr": rrank(graph_rank),
+        "graph_selected": float(bool(graph_selected)),
+        "graph_final": float(bool(graph_final)),
+        "recency_norm": float(raw["session_index"]) / float(max(1, session_count - 1)),
+    }
+    if tuple(channels.keys()) != CHANNEL_NAMES:
+        raise AssertionError("channel construction order changed")
+    return {
+        "candidate_id": raw["candidate_id"],
+        "text": raw["text"],
+        "session_id": raw["session_id"],
+        "session_index": int(raw["session_index"]),
+        "parent_chunk_index": int(raw["parent_chunk_index"]),
+        "subchunk_index": int(raw["subchunk_index"]),
+        "source_char_start": int(raw["source_char_start"]),
+        "source_char_end": int(raw["source_char_end"]),
+        "channels": channels,
+        "labels": {
+            "relevance": relevant,
+            "session_relevance": bool(session_relevant),
+            "teacher_evidence_relevance": teacher_relevant,
+            "hard_negative": hard_negative,
+            "evidence_role": "positive" if relevant else ("hard_negative" if hard_negative else "negative"),
+            "target_scope": "answer_session_bag",
+        },
+        "provenance": {
+            "dense_retrieved": dense_rank >= 0,
+            "graph_retrieved": graph_rank is not None,
+            "graph_selected": bool(graph_selected),
+            "graph_final": bool(graph_final),
+            "forced_positive_for_training": bool(forced_positive),
+        },
+    }
+
+
+def metric_hit(order: Sequence[int], positives: set[int], k: int) -> int:
+    return int(any(index in positives for index in order[:k]))
+
+
+def command_finalize(args: argparse.Namespace) -> None:
+    inventory_rows = read_jsonl(Path(args.inventory))
+    graph_debug = load_graph_debug(Path(args.graph_debug_run))
+    teacher_by_question = load_teacher_supervision(Path(args.teacher_labels))
+    vectorizer = EmbeddingCacheVectorizer(
+        cache_dir=args.embedding_cache,
+        dim=args.text_dim,
+        expected_backend="hf",
+        expected_model=args.embedding_model,
+    )
+    out_dir = Path(args.out_dir)
+    out_dir.mkdir(parents=True, exist_ok=False)
+    train_rows: list[dict[str, Any]] = []
+    holdout_rows: list[dict[str, Any]] = []
+    full_rows: list[dict[str, Any]] = []
+    full_inventory_rows: list[dict[str, Any]] = []
+    provider = Counter()
+    teacher_provider = Counter()
+    supervision_counts = Counter()
+    for source in inventory_rows:
+        qid = clean_text(source["question_id"])
+        candidates = list(source["candidates"])
+        session_count = int(source["inventory_metadata"]["session_count"])
+        candidate_count = len(candidates)
+        parent_candidates: dict[tuple[int, int], list[int]] = {}
+        for index, candidate in enumerate(candidates):
+            location = (int(candidate["session_index"]), int(candidate["parent_chunk_index"]))
+            parent_candidates.setdefault(location, []).append(index)
+        valid_parent_locations = set(parent_candidates)
+        qvec = vectorizer.encode_one(source["query_text"])
+        evec = torch.stack([vectorizer.encode_one(candidate["text"]) for candidate in candidates])
+        dense_scores = (evec @ qvec).tolist()
+        dense_order = sorted(range(candidate_count), key=lambda index: (-dense_scores[index], index))
+        dense_rank = {index: rank for rank, index in enumerate(dense_order)}
+        debug = graph_debug.get(qid, {})
+        retrieval = dict(debug.get("retrieval") or {})
+        selected_parents = ordered_parent_locations(
+            retrieval.get("selected_event_ids") or [], qid=qid, valid_locations=valid_parent_locations
+        )
+        final_parents = ordered_parent_locations(
+            retrieval.get("final_hit_event_ids") or [], qid=qid, valid_locations=valid_parent_locations
+        )
+        recall_parents = ordered_parent_locations(
+            retrieval.get("recall_event_ids") or [], qid=qid, valid_locations=valid_parent_locations
+        )
+        graph_parents: list[tuple[int, int]] = []
+        graph_parent_seen: set[tuple[int, int]] = set()
+        for location in [*selected_parents, *recall_parents]:
+            if location not in graph_parent_seen:
+                graph_parent_seen.add(location)
+                graph_parents.append(location)
+        graph_parent_rank = {location: rank for rank, location in enumerate(graph_parents)}
+        graph_order = expand_parent_locations(graph_parents, parent_candidates)
+        graph_rank = {
+            index: graph_parent_rank[(int(candidates[index]["session_index"]), int(candidates[index]["parent_chunk_index"]))]
+            for index in graph_order
+        }
+        selected_indexes = set(expand_parent_locations(selected_parents, parent_candidates))
+        final_indexes = set(expand_parent_locations(final_parents, parent_candidates))
+        session_positives = {index for index, candidate in enumerate(candidates) if candidate["labels"]["relevance"]}
+        teacher_row = teacher_by_question.get(normalized_question(source["question"]))
+        teacher_positives: set[int] | None = None
+        teacher_hard: set[int] = set()
+        if teacher_row is not None:
+            teacher_metadata = dict(teacher_row.get("metadata") or {})
+            raw_teacher_positive = list(teacher_metadata.get("raw_teacher_positive_event_ids") or [])
+            raw_teacher_hard = list(teacher_metadata.get("raw_teacher_hard_negative_event_ids") or [])
+            if not raw_teacher_positive:
+                raise RuntimeError(f"{qid}: aligned teacher row is missing raw positive turn ids")
+            teacher_positives = teacher_turn_candidate_indexes(
+                raw_teacher_positive,
+                candidates=candidates,
+                parent_candidates=parent_candidates,
+                qid=qid,
+            )
+            teacher_hard = teacher_turn_candidate_indexes(
+                raw_teacher_hard,
+                candidates=candidates,
+                parent_candidates=parent_candidates,
+                qid=qid,
+            )
+            if not teacher_positives:
+                raise RuntimeError(f"{qid}: teacher supervision produced no positive subchunks")
+            mixed_teacher_subchunks = teacher_positives & teacher_hard
+            if mixed_teacher_subchunks:
+                supervision_counts["teacher_mixed_positive_hard_subchunks"] += len(mixed_teacher_subchunks)
+                teacher_hard -= teacher_positives
+            positives = teacher_positives
+            supervision = {
+                "target_type": "teacher_aligned_turn_bag",
+                "loss": "negative_log_positive_probability_mass",
+                "training_weight": float(teacher_row.get("training_weight_hint", 1.0) or 1.0),
+                "teacher_label_model": clean_text((teacher_row.get("metadata") or {}).get("teacher_label_model")),
+                "teacher_verify_model": clean_text((teacher_row.get("metadata") or {}).get("teacher_verify_model")),
+                "teacher_confidence": clean_text(teacher_row.get("label_confidence")),
+            }
+        else:
+            positives = session_positives
+            supervision = {
+                "target_type": "multi_instance_answer_session_bag",
+                "loss": "negative_log_positive_probability_mass",
+                "training_weight": float(args.weak_supervision_weight),
+            }
+        supervision_counts[supervision["target_type"]] += 1
+        provider["n"] += 1
+        for k in (1, 5, 10, 20, 32):
+            provider[f"primary_dense_r@{k}"] += metric_hit(dense_order, positives, k)
+            provider[f"primary_graph_r@{k}"] += metric_hit(graph_order, positives, k)
+            provider[f"session_dense_r@{k}"] += metric_hit(dense_order, session_positives, k)
+            provider[f"session_graph_r@{k}"] += metric_hit(graph_order, session_positives, k)
+            if teacher_positives is not None:
+                teacher_provider[f"dense_r@{k}"] += metric_hit(dense_order, teacher_positives, k)
+                teacher_provider[f"graph_r@{k}"] += metric_hit(graph_order, teacher_positives, k)
+        if teacher_positives is not None:
+            teacher_provider["n"] += 1
+        runtime_indexes: list[int] = []
+        runtime_seen: set[int] = set()
+        graph_runtime_order = expand_parent_locations(graph_parents[: args.graph_k], parent_candidates)
+        for index in [*dense_order[: args.dense_k], *graph_runtime_order]:
+            if index not in runtime_seen:
+                runtime_seen.add(index)
+                runtime_indexes.append(index)
+        provider["union_gold_hit"] += int(bool(positives & runtime_seen))
+        provider["union_session_hit"] += int(bool(session_positives & runtime_seen))
+        if teacher_positives is not None:
+            teacher_provider["union_hit"] += int(bool(teacher_positives & runtime_seen))
+        pre_force_hit = bool(positives & runtime_seen)
+        training_indexes = list(runtime_indexes)
+        forced_indexes: set[int] = set()
+        if source["split"] == "train" and not pre_force_hit:
+            best_positive = next(index for index in dense_order if index in positives)
+            training_indexes.append(best_positive)
+            runtime_seen.add(best_positive)
+            forced_indexes.add(best_positive)
+        def build_row(indexes: Sequence[int], split: str, allow_forced: bool) -> dict[str, Any]:
+            output_candidates = []
+            for index in indexes:
+                hard = index not in positives and (
+                    index in teacher_hard
+                    or dense_rank[index] < args.hard_negative_k
+                    or graph_rank.get(index, 10**9) < args.hard_negative_k
+                )
+                output_candidates.append(
+                    canonical_candidate(
+                        candidates[index],
+                        relevant=index in positives,
+                        session_relevant=index in session_positives,
+                        teacher_relevant=None if teacher_positives is None else index in teacher_positives,
+                        dense_score=dense_scores[index],
+                        dense_rank=dense_rank[index],
+                        graph_rank=graph_rank.get(index),
+                        graph_selected=index in selected_indexes,
+                        graph_final=index in final_indexes,
+                        session_count=session_count,
+                        forced_positive=allow_forced and index in forced_indexes,
+                        hard_negative=hard,
+                    )
+                )
+            return {
+                "schema_version": SCHEMA_VERSION,
+                "question_id": qid,
+                "question": source["question"],
+                "question_date": source["question_date"],
+                "query_text": source["query_text"],
+                "question_type": source["question_type"],
+                "split": split,
+                "gold_answer": source["gold_answer"],
+                "answer_session_ids": source["answer_session_ids"],
+                "supervision": supervision,
+                "candidates": output_candidates,
+                "pool_metadata": {
+                    "session_count": session_count,
+                    "inventory_count": candidate_count,
+                    "graph_parent_event_count": len(graph_parents),
+                    "graph_runtime_candidate_count": len(graph_runtime_order),
+                    "runtime_pool_count": len(runtime_indexes),
+                    "pre_force_gold_hit": pre_force_hit,
+                    "pre_force_session_hit": bool(session_positives & set(runtime_indexes)),
+                    "pre_force_teacher_hit": None if teacher_positives is None else bool(teacher_positives & set(runtime_indexes)),
+                    "forced_positive_count": len(forced_indexes) if allow_forced else 0,
+                    "dense_k": args.dense_k,
+                    "graph_k": args.graph_k,
+                    "graph_debug_available": bool(debug),
+                    "graph_retrieval_mode": retrieval.get("retrieval_mode"),
+                },
+            }
+        runtime_row = build_row(runtime_indexes, "full_eval", False)
+        validate_sample(runtime_row, require_positive=False)
+        full_rows.append(runtime_row)
+        all_row = build_row(list(range(candidate_count)), "full_eval", False)
+        validate_sample(all_row, require_positive=True)
+        full_inventory_rows.append(all_row)
+        if source["split"] == "train":
+            train_row = build_row(training_indexes, "train", True)
+            validate_sample(train_row, require_positive=True)
+            train_rows.append(train_row)
+        else:
+            holdout_row = build_row(runtime_indexes, "holdout", False)
+            validate_sample(holdout_row, require_positive=False)
+            holdout_rows.append(holdout_row)
+    isolation = validate_split_isolation(train_rows, holdout_rows)
+    if len(train_rows) + len(holdout_rows) != len(inventory_rows):
+        raise RuntimeError("finalized row count mismatch")
+    write_jsonl(out_dir / "train.jsonl", train_rows)
+    write_jsonl(out_dir / "holdout.jsonl", holdout_rows)
+    write_jsonl(out_dir / "full_eval.jsonl", full_rows)
+    write_jsonl(out_dir / "full_inventory_eval.jsonl", full_inventory_rows)
+    if args.dev_count <= 0 or args.dev_count >= len(train_rows):
+        raise RuntimeError("dev_count must leave non-empty optimization train and dev sets")
+    ordered_train_qids = sorted(
+        (row["question_id"] for row in train_rows),
+        key=lambda qid: (stable_int(f"tmcra-v3-dev:{qid}"), qid),
+    )
+    dev_qids = set(ordered_train_qids[: args.dev_count])
+    model_train_rows = [row for row in train_rows if row["question_id"] not in dev_qids]
+    full_by_qid = {row["question_id"]: row for row in full_rows}
+    model_dev_rows = [full_by_qid[qid] for qid in ordered_train_qids[: args.dev_count]]
+    if any(row["pool_metadata"]["forced_positive_count"] for row in model_dev_rows):
+        raise RuntimeError("runtime dev rows must never contain forced positives")
+    write_jsonl(out_dir / "model_train.jsonl", model_train_rows)
+    write_jsonl(out_dir / "model_dev_runtime.jsonl", model_dev_rows)
+    (out_dir / "model_dev_qids.txt").write_text("\n".join(ordered_train_qids[: args.dev_count]) + "\n", encoding="utf-8")
+    cross_cache_rows = [*train_rows, *holdout_rows]
+    if len({row["question_id"] for row in cross_cache_rows}) != len(inventory_rows):
+        raise RuntimeError("cross-cache input must contain exactly one row per question")
+    write_jsonl(out_dir / "cross_cache_samples.jsonl", cross_cache_rows)
+    n = max(1, int(provider["n"]))
+    report = {
+        "schema_version": SCHEMA_VERSION,
+        "created_at": time.strftime("%Y-%m-%dT%H:%M:%S%z"),
+        "train_count": len(train_rows),
+        "holdout_count": len(holdout_rows),
+        "full_eval_count": len(full_rows),
+        "full_inventory_eval_count": len(full_inventory_rows),
+        "cross_cache_sample_count": len(cross_cache_rows),
+        "cross_cache_pair_count": sum(len(row["candidates"]) for row in cross_cache_rows),
+        "model_train_count": len(model_train_rows),
+        "model_dev_runtime_count": len(model_dev_rows),
+        "model_dev_runtime_candidate_miss_count": sum(
+            int(not any(candidate["labels"]["relevance"] for candidate in row["candidates"]))
+            for row in model_dev_rows
+        ),
+        "isolation": isolation,
+        "candidate_pool": {
+            "dense_k": args.dense_k,
+            "graph_k": args.graph_k,
+            "hard_negative_k": args.hard_negative_k,
+            "train_candidate_avg": round(sum(len(row["candidates"]) for row in train_rows) / max(1, len(train_rows)), 4),
+            "holdout_candidate_avg": round(sum(len(row["candidates"]) for row in holdout_rows) / max(1, len(holdout_rows)), 4),
+            "full_inventory_candidate_avg": round(sum(len(row["candidates"]) for row in full_inventory_rows) / max(1, len(full_inventory_rows)), 4),
+            "train_forced_positive_rows": sum(int(row["pool_metadata"]["forced_positive_count"] > 0) for row in train_rows),
+        },
+        "provider_metrics": {
+            key: round(value / n, 6) for key, value in sorted(provider.items()) if key != "n"
+        },
+        "teacher_provider_metrics": {
+            key: round(value / max(1, int(teacher_provider["n"])), 6)
+            for key, value in sorted(teacher_provider.items())
+            if key != "n"
+        },
+        "teacher_supervision_count": int(teacher_provider["n"]),
+        "supervision_counts": dict(supervision_counts),
+        "teacher_labels": str(Path(args.teacher_labels).resolve()),
+        "weak_supervision_weight": args.weak_supervision_weight,
+        "embedding_cache": str(Path(args.embedding_cache).resolve()),
+        "graph_debug_run": str(Path(args.graph_debug_run).resolve()),
+    }
+    (out_dir / "report.json").write_text(json.dumps(report, indent=2, sort_keys=True), encoding="utf-8")
+    print(json.dumps(report, indent=2, sort_keys=True))
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    sub = parser.add_subparsers(dest="command", required=True)
+    inventory = sub.add_parser("inventory")
+    inventory.add_argument("--data", required=True)
+    inventory.add_argument("--out-dir", required=True)
+    inventory.add_argument("--holdout-count", type=int, default=100)
+    inventory.add_argument("--parent-chars", type=int, default=7000)
+    inventory.add_argument("--subchunk-chars", type=int, default=1800)
+    inventory.add_argument("--subchunk-overlap", type=int, default=200)
+    finalize = sub.add_parser("finalize")
+    finalize.add_argument("--inventory", required=True)
+    finalize.add_argument("--embedding-cache", required=True)
+    finalize.add_argument("--embedding-model", required=True)
+    finalize.add_argument("--graph-debug-run", required=True)
+    finalize.add_argument("--teacher-labels", required=True)
+    finalize.add_argument("--out-dir", required=True)
+    finalize.add_argument("--text-dim", type=int, default=1024)
+    finalize.add_argument("--dense-k", type=int, default=32)
+    finalize.add_argument("--graph-k", type=int, default=24)
+    finalize.add_argument("--hard-negative-k", type=int, default=12)
+    finalize.add_argument("--dev-count", type=int, default=40)
+    finalize.add_argument("--weak-supervision-weight", type=float, default=0.35)
+    args = parser.parse_args()
+    if args.command == "inventory":
+        command_inventory(args)
+    else:
+        command_finalize(args)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

benchmarks/longmemeval/src/tmcra_benchmark/legacy/ops/audit_tmcra_v4_subject_attribution.py

@@ -0,0 +1,877 @@
+#!/usr/bin/env python3
+"""Audit user-memory ownership inside pasted or forwarded documents.
+
+The deterministic router only selects document-shaped source messages. DeepSeek
+Pro makes every semantic keep/quarantine decision from exact Source excerpts.
+Original Source records remain immutable; quarantined Fast records stay in the
+append-only graph but are excluded from current retrieval.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import re
+import sqlite3
+import sys
+from contextlib import closing
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Mapping, Protocol, Sequence
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+if str(REPO_ROOT) not in sys.path:
+    sys.path.insert(0, str(REPO_ROOT))
+
+from tmcra_v4_batch_writer import DeepSeekBatchClient
+
+
+PROMPT_VERSION = "tmcra-v4-subject-attribution-2026-07-14.3"
+MODEL = "deepseek-v4-pro"
+CURRENT_STATES = {"active", "parallel_active", "promoted", "challenged"}
+DECISIONS = {"keep_user", "quarantine_third_party", "quarantine_ambiguous"}
+
+SYSTEM_PROMPT = """You audit subject ownership for a production personal-memory system.
+Return exactly one JSON object and no prose:
+{"decisions":[{"memory_id":"exact supplied ID","decision":"keep_user|quarantine_third_party|quarantine_ambiguous","actual_subject":"chat_user for keep_user; named local subject for quarantine_third_party; otherwise empty","chat_user_bridge_quote":"exact outside-artifact identity bridge for keep_user; otherwise empty","reason":"concise source-grounded reason"}]}.
+Return every supplied candidate exactly once and never invent an ID.
+
+The chat user is the person who submitted the outer message to this memory system. An author, sender,
+signatory, quoted speaker, recipient, company, or document subject inside an embedded artifact is a separate
+identity and must never be equated with the chat user merely because the artifact appears in a user-role
+message. Text inside a pasted email thread, article, resume, log, transcript, or document is not the chat
+user's conversational voice. A sender or signatory inside the artifact is third party by default.
+
+keep_user is allowed only when text outside the embedded artifact explicitly bridges the chat user to the
+local author or subject, for example "I wrote the email below" or "this is my resume". A sender name,
+signature, first-person wording inside the artifact, or mailbox label is not an identity bridge. If the
+source starts directly with mailbox UI or document text and contains no outside bridge, do not use
+keep_user. A mailbox line such as "to me" identifies the mailbox owner as a recipient, not as the sender.
+For keep_user, actual_subject must be exactly "chat_user". Use quarantine_third_party when the source
+locally attributes the fact to a named author, sender, signatory, quoted speaker, company, or document
+subject. Use quarantine_ambiguous when no actual subject can be established. Useful document facts remain
+in immutable Source; do not force them into the chat user's Fast profile.
+Every keep_user decision must cite chat_user_bridge_quote as an exact Source substring outside the artifact.
+The candidate evidence quote itself cannot be used as that bridge. For both quarantine decisions,
+chat_user_bridge_quote must be empty. Candidate objects intentionally contain no Writer claim or slot;
+judge ownership from Source only.
+Do not use outside knowledge, model confidence, benchmark labels, or the assertion wording as authority.
+Judge against the exact source excerpts and offsets."""
+
+HEADER_RE = re.compile(
+    r"(?im)^(?:from|to|subject|sent|de|para|asunto|enviado):\s*\S"
+)
+MAILBOX_RE = re.compile(r"(?im)^\s*to\s+(?:me|[A-Z][^\n,]{0,40})(?:,|\s*$)")
+SIGNATURE_RE = re.compile(r"(?im)^\s*(?:regards|best regards|sincerely),?\s*$")
+LEGAL_RE = re.compile(r"(?i)confidentiality notice|electronic communications privacy act")
+THREAD_RE = re.compile(r"(?i)view entire message|scanned by gmail|\bon .{0,120} wrote:\s*$", re.M)
+
+
+class AttributionError(RuntimeError):
+    pass
+
+
+class AttributionClient(Protocol):
+    def complete(self, payload: Mapping[str, Any]) -> tuple[str, Mapping[str, Any]]:
+        ...
+
+
+class DeepSeekProAttributionClient:
+    def __init__(self) -> None:
+        base_url = (
+            os.getenv("TMCRA_DEEPSEEK_PRO_BASE_URL")
+            or os.getenv("TMCRA_WRITER_BASE_URL")
+            or "https://api.deepseek.com/v1"
+        )
+        raw_keys = (
+            os.getenv("TMCRA_DEEPSEEK_PRO_KEY_POOL")
+            or os.getenv("TMCRA_WRITER_API_KEY_POOL")
+            or os.getenv("TMCRA_DEEPSEEK_WRITER_KEY_POOL")
+            or ""
+        )
+        keys = [item.strip() for item in raw_keys.split(",") if item.strip()]
+        if not keys:
+            raise AttributionError("DeepSeek Pro key pool is empty; no fallback is allowed")
+        max_tokens = int(os.getenv("TMCRA_DEEPSEEK_PRO_MAX_TOKENS", "16384"))
+        self.client = DeepSeekBatchClient(
+            base_url=base_url,
+            model=MODEL,
+            api_keys=keys,
+            timeout=float(os.getenv("TMCRA_DEEPSEEK_PRO_TIMEOUT", "180")),
+            max_tokens=max_tokens,
+        )
+
+    def complete(self, payload: Mapping[str, Any]) -> tuple[str, Mapping[str, Any]]:
+        return self.client._complete(
+            model=MODEL,
+            system_prompt=SYSTEM_PROMPT,
+            payload=payload,
+            stage="subject_attribution_pro",
+        )
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="milliseconds")
+
+
+def _json(value: Any) -> str:
+    return json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+
+
+def _digest(value: Any) -> str:
+    return hashlib.sha256(_json(value).encode("utf-8")).hexdigest()
+
+
+def _text(value: Any) -> str:
+    return str(value).strip() if value is not None else ""
+
+
+def document_route_reasons(content: str) -> list[str]:
+    """Route only; these signals never decide whether an assertion is valid."""
+    reasons: list[str] = []
+    if HEADER_RE.search(content):
+        reasons.append("mail_header")
+    if MAILBOX_RE.search(content):
+        reasons.append("mailbox_recipient_line")
+    if SIGNATURE_RE.search(content):
+        reasons.append("signature_block")
+    if LEGAL_RE.search(content):
+        reasons.append("mail_legal_notice")
+    if THREAD_RE.search(content):
+        reasons.append("quoted_thread")
+    return reasons if len(reasons) >= 2 else []
+
+
+def _metadata(row: Mapping[str, Any]) -> dict[str, Any]:
+    try:
+        value = json.loads(str(row["metadata_json"]))
+    except (KeyError, TypeError, json.JSONDecodeError) as exc:
+        raise AttributionError("record metadata is invalid JSON") from exc
+    if not isinstance(value, dict):
+        raise AttributionError("record metadata must be an object")
+    return value
+
+
+def _initialize(connection: sqlite3.Connection) -> None:
+    connection.execute(
+        """
+        CREATE TABLE IF NOT EXISTS v4_subject_attribution_audits (
+          audit_id TEXT PRIMARY KEY,
+          scope_id TEXT NOT NULL,
+          message_id TEXT NOT NULL,
+          prompt_version TEXT NOT NULL,
+          model TEXT NOT NULL,
+          request_json TEXT NOT NULL,
+          request_sha256 TEXT NOT NULL,
+          status TEXT NOT NULL,
+          response_json TEXT NOT NULL DEFAULT '',
+          response_sha256 TEXT NOT NULL DEFAULT '',
+          call_metadata_json TEXT NOT NULL DEFAULT '{}',
+          decisions_json TEXT NOT NULL DEFAULT '[]',
+          error TEXT NOT NULL DEFAULT '',
+          created_at TEXT NOT NULL,
+          updated_at TEXT NOT NULL,
+          UNIQUE(scope_id,message_id,request_sha256)
+        )
+        """
+    )
+
+
+def _source_rows(connection: sqlite3.Connection, scope_id: str) -> list[sqlite3.Row]:
+    return connection.execute(
+        "SELECT scope_id,message_id,session_index,message_index,message_role,"
+        "source_turn_index,content,content_sha256 FROM v4_source_journal "
+        "WHERE scope_id=? AND message_role='user' AND status='enriched' "
+        "ORDER BY session_index,message_index",
+        (scope_id,),
+    ).fetchall()
+
+
+def _candidate_records(
+    connection: sqlite3.Connection, scope_id: str, source: Mapping[str, Any]
+) -> list[dict[str, Any]]:
+    output: list[dict[str, Any]] = []
+    rows = connection.execute(
+        "SELECT memory_id,value,slot_key,turn_index,state,metadata_json FROM records "
+        "WHERE scope_id=? AND turn_index=? ORDER BY memory_id",
+        (scope_id, int(source["source_turn_index"])),
+    ).fetchall()
+    for row in rows:
+        metadata = _metadata(row)
+        if (
+            metadata.get("content_variant") != "product_semantic_memory"
+            or metadata.get("memory_layer") != "fast"
+            or metadata.get("node_kind") != "atomic_user_assertion"
+            or _text(row["state"]) not in CURRENT_STATES
+            or _text(metadata.get("message_id")) != _text(source["message_id"])
+        ):
+            continue
+        start = metadata.get("evidence_char_start")
+        end = metadata.get("evidence_char_end")
+        if (
+            isinstance(start, bool)
+            or isinstance(end, bool)
+            or not isinstance(start, int)
+            or not isinstance(end, int)
+            or not 0 <= start < end <= len(str(source["content"]))
+        ):
+            raise AttributionError(f"{row['memory_id']}: evidence offsets are invalid")
+        quote = str(source["content"])[start:end]
+        expected_quote = _text(metadata.get("source_span") or metadata.get("raw_content"))
+        if quote != expected_quote:
+            raise AttributionError(f"{row['memory_id']}: Source quote drift")
+        output.append(
+            {
+                "memory_id": str(row["memory_id"]),
+                "claim_text": str(row["value"]),
+                "canonical_slot": _text(
+                    metadata.get("canonical_slot_key") or row["slot_key"]
+                ),
+                "evidence_quote": quote,
+                "evidence_char_start": start,
+                "evidence_char_end": end,
+            }
+        )
+    return output
+
+
+def _source_segments(content: str, candidates: Sequence[Mapping[str, Any]]) -> list[dict[str, Any]]:
+    ranges = [(0, min(len(content), 700))]
+    for candidate in candidates:
+        start = max(0, int(candidate["evidence_char_start"]) - 420)
+        end = min(len(content), int(candidate["evidence_char_end"]) + 420)
+        ranges.append((start, end))
+    ranges.sort()
+    merged: list[list[int]] = []
+    for start, end in ranges:
+        if merged and start <= merged[-1][1] + 80:
+            merged[-1][1] = max(merged[-1][1], end)
+        else:
+            merged.append([start, end])
+    return [
+        {"char_start": start, "char_end": end, "text": content[start:end]}
+        for start, end in merged
+    ]
+
+
+def scan_database(database: Path, scope_id: str) -> list[dict[str, Any]]:
+    with closing(sqlite3.connect(database)) as connection:
+        connection.row_factory = sqlite3.Row
+        jobs: list[dict[str, Any]] = []
+        for source in _source_rows(connection, scope_id):
+            reasons = document_route_reasons(str(source["content"]))
+            if not reasons:
+                continue
+            review_candidates = _candidate_records(connection, scope_id, source)
+            if not review_candidates:
+                continue
+            candidates = [
+                {
+                    "memory_id": item["memory_id"],
+                    "evidence_quote": item["evidence_quote"],
+                    "evidence_char_start": item["evidence_char_start"],
+                    "evidence_char_end": item["evidence_char_end"],
+                }
+                for item in review_candidates
+            ]
+            payload = {
+                "scope_id": scope_id,
+                "message_id": str(source["message_id"]),
+                "message_role": "user",
+                "route_reasons": reasons,
+                "source_segments": _source_segments(
+                    str(source["content"]), review_candidates
+                ),
+                "candidates": candidates,
+            }
+            jobs.append(
+                {
+                    "database": str(database),
+                    "scope_id": scope_id,
+                    "message_id": str(source["message_id"]),
+                    "session_index": int(source["session_index"]),
+                    "message_index": int(source["message_index"]),
+                    "source_turn_index": int(source["source_turn_index"]),
+                    "route_reasons": reasons,
+                    "payload": payload,
+                    "review_candidates": review_candidates,
+                    "request_sha256": _digest(
+                        {
+                            "prompt_version": PROMPT_VERSION,
+                            "model": MODEL,
+                            "payload": payload,
+                        }
+                    ),
+                }
+            )
+        return jobs
+
+
+def validate_decisions(
+    raw: Any, payload: Mapping[str, Any]
+) -> list[dict[str, str]]:
+    candidates = payload.get("candidates")
+    source_segments = payload.get("source_segments")
+    if not isinstance(candidates, list) or not isinstance(source_segments, list):
+        raise AttributionError("attribution request payload is malformed")
+    candidate_ids = [
+        _text(item.get("memory_id"))
+        for item in candidates
+        if isinstance(item, Mapping)
+    ]
+    if len(candidate_ids) != len(candidates) or not all(candidate_ids):
+        raise AttributionError("attribution request candidate identity is malformed")
+    candidate_by_id = {
+        _text(item["memory_id"]): item
+        for item in candidates
+        if isinstance(item, Mapping)
+    }
+    source_texts = [
+        _text(item.get("text"))
+        for item in source_segments
+        if isinstance(item, Mapping) and _text(item.get("text"))
+    ]
+    if not isinstance(raw, Mapping) or set(raw) != {"decisions"}:
+        raise AttributionError("attribution response must contain exactly decisions")
+    decisions = raw.get("decisions")
+    if not isinstance(decisions, list) or len(decisions) != len(candidate_ids):
+        raise AttributionError("attribution response decision count changed")
+    normalized: list[dict[str, str]] = []
+    seen: set[str] = set()
+    for index, item in enumerate(decisions):
+        if not isinstance(item, Mapping) or set(item) != {
+            "memory_id",
+            "decision",
+            "actual_subject",
+            "chat_user_bridge_quote",
+            "reason",
+        }:
+            raise AttributionError(f"decisions[{index}] has an invalid shape")
+        memory_id = _text(item.get("memory_id"))
+        decision = _text(item.get("decision"))
+        actual_subject = _text(item.get("actual_subject"))
+        bridge_quote = _text(item.get("chat_user_bridge_quote"))
+        reason = _text(item.get("reason"))
+        if memory_id not in candidate_ids or memory_id in seen:
+            raise AttributionError(f"decisions[{index}] changed candidate identity")
+        if decision not in DECISIONS or not reason:
+            raise AttributionError(f"decisions[{index}] has an invalid decision")
+        if decision == "keep_user" and actual_subject != "chat_user":
+            raise AttributionError(
+                f"decisions[{index}] keep_user must bind actual_subject to chat_user"
+            )
+        if decision == "keep_user":
+            evidence_quote = _text(candidate_by_id[memory_id].get("evidence_quote"))
+            if (
+                not bridge_quote
+                or bridge_quote == evidence_quote
+                or not any(bridge_quote in text for text in source_texts)
+            ):
+                raise AttributionError(
+                    f"decisions[{index}] keep_user lacks an exact outside-artifact bridge"
+                )
+        elif bridge_quote:
+            raise AttributionError(
+                f"decisions[{index}] quarantine decision cannot cite a chat-user bridge"
+            )
+        if decision == "quarantine_third_party" and not actual_subject:
+            raise AttributionError(
+                f"decisions[{index}] must identify the third-party subject"
+            )
+        if decision == "quarantine_ambiguous" and actual_subject:
+            raise AttributionError(
+                f"decisions[{index}] ambiguous subject must remain empty"
+            )
+        seen.add(memory_id)
+        normalized.append(
+            {
+                "memory_id": memory_id,
+                "decision": decision,
+                "actual_subject": actual_subject,
+                "chat_user_bridge_quote": bridge_quote,
+                "reason": reason,
+            }
+        )
+    if seen != set(candidate_ids):
+        raise AttributionError("attribution response omitted candidate identities")
+    normalized.sort(key=lambda item: candidate_ids.index(item["memory_id"]))
+    return normalized
+
+
+def _replacement_head(
+    connection: sqlite3.Connection,
+    scope_id: str,
+    slot_key: str,
+    excluded_ids: set[str],
+) -> str:
+    rows = connection.execute(
+        "SELECT h.memory_id,r.state FROM slot_history h JOIN records r "
+        "ON r.scope_id=h.scope_id AND r.memory_id=h.memory_id "
+        "WHERE h.scope_id=? AND h.slot_key=? ORDER BY h.ordinal DESC",
+        (scope_id, slot_key),
+    ).fetchall()
+    return next(
+        (
+            str(row["memory_id"])
+            for row in rows
+            if str(row["memory_id"]) not in excluded_ids
+            and _text(row["state"]) in CURRENT_STATES
+        ),
+        "",
+    )
+
+
+def _repair_slot_head(
+    connection: sqlite3.Connection,
+    scope_id: str,
+    slot_key: str,
+    memory_id: str,
+    excluded_ids: set[str],
+) -> None:
+    head = connection.execute(
+        "SELECT memory_id FROM slot_heads WHERE scope_id=? AND slot_key=?",
+        (scope_id, slot_key),
+    ).fetchone()
+    if head is None or str(head["memory_id"]) != memory_id:
+        return
+    replacement = _replacement_head(connection, scope_id, slot_key, excluded_ids)
+    if replacement:
+        connection.execute(
+            "UPDATE slot_heads SET memory_id=? WHERE scope_id=? AND slot_key=?",
+            (replacement, scope_id, slot_key),
+        )
+    else:
+        connection.execute(
+            "DELETE FROM slot_heads WHERE scope_id=? AND slot_key=?",
+            (scope_id, slot_key),
+        )
+
+
+def _apply_decisions(
+    connection: sqlite3.Connection,
+    job: Mapping[str, Any],
+    audit_id: str,
+    decisions: Sequence[Mapping[str, str]],
+) -> dict[str, Any]:
+    candidate_ids = [item["memory_id"] for item in job["payload"]["candidates"]]
+    rows = connection.execute(
+        "SELECT memory_id,slot_key,state,metadata_json FROM records WHERE scope_id=? "
+        f"AND memory_id IN ({','.join('?' for _ in candidate_ids)})",
+        (job["scope_id"], *candidate_ids),
+    ).fetchall()
+    if {str(row["memory_id"]) for row in rows} != set(candidate_ids):
+        raise AttributionError("candidate records changed before attribution commit")
+    decision_by_id = {item["memory_id"]: item for item in decisions}
+    quarantine_ids = {
+        item["memory_id"]
+        for item in decisions
+        if item["decision"] != "keep_user"
+    }
+    parent_signature_map: dict[str, tuple[str, Mapping[str, str]]] = {}
+    for row in rows:
+        memory_id = str(row["memory_id"])
+        if memory_id not in quarantine_ids:
+            continue
+        signature = _text(_metadata(row).get("event_signature"))
+        if not signature:
+            continue
+        if signature in parent_signature_map:
+            raise AttributionError("quarantined parent event signature is not unique")
+        parent_signature_map[signature] = (memory_id, decision_by_id[memory_id])
+
+    dependent_rows: list[sqlite3.Row] = []
+    if parent_signature_map:
+        for row in connection.execute(
+            "SELECT memory_id,slot_key,state,metadata_json FROM records WHERE scope_id=?",
+            (job["scope_id"],),
+        ).fetchall():
+            if str(row["memory_id"]) in candidate_ids:
+                continue
+            parent_signature = _text(
+                _metadata(row).get("facet_parent_event_signature")
+            )
+            if parent_signature in parent_signature_map:
+                dependent_rows.append(row)
+
+    dependent_ids = {str(row["memory_id"]) for row in dependent_rows}
+    all_quarantine_ids = quarantine_ids | dependent_ids
+    changed_ids: list[str] = []
+    for row in rows:
+        memory_id = str(row["memory_id"])
+        decision = decision_by_id[memory_id]
+        metadata = _metadata(row)
+        metadata["subject_attribution_audit_id"] = audit_id
+        metadata["subject_attribution_prompt_version"] = PROMPT_VERSION
+        metadata["subject_attribution_model"] = MODEL
+        metadata["subject_attribution_decision"] = decision["decision"]
+        metadata["subject_attribution_actual_subject"] = decision["actual_subject"]
+        metadata["subject_attribution_chat_user_bridge_quote"] = decision[
+            "chat_user_bridge_quote"
+        ]
+        metadata["subject_attribution_reason"] = decision["reason"]
+        state = str(row["state"])
+        if memory_id in quarantine_ids:
+            state = "quarantined"
+            metadata["excluded_from_retrieval"] = True
+            metadata["conflict_action"] = "subject_attribution_quarantine"
+        connection.execute(
+            "UPDATE records SET state=?,metadata_json=? WHERE scope_id=? AND memory_id=?",
+            (state, _json(metadata), job["scope_id"], memory_id),
+        )
+        changed_ids.append(memory_id)
+        if memory_id not in quarantine_ids:
+            continue
+        slot_key = str(row["slot_key"])
+        _repair_slot_head(
+            connection,
+            job["scope_id"],
+            slot_key,
+            memory_id,
+            all_quarantine_ids,
+        )
+
+    for row in dependent_rows:
+        memory_id = str(row["memory_id"])
+        metadata = _metadata(row)
+        parent_signature = _text(metadata.get("facet_parent_event_signature"))
+        parent_memory_id, parent_decision = parent_signature_map[parent_signature]
+        metadata["subject_attribution_audit_id"] = audit_id
+        metadata["subject_attribution_prompt_version"] = PROMPT_VERSION
+        metadata["subject_attribution_model"] = MODEL
+        metadata["subject_attribution_decision"] = "quarantine_with_parent"
+        metadata["subject_attribution_parent_memory_id"] = parent_memory_id
+        metadata["subject_attribution_parent_decision"] = parent_decision["decision"]
+        metadata["subject_attribution_actual_subject"] = parent_decision[
+            "actual_subject"
+        ]
+        metadata["subject_attribution_chat_user_bridge_quote"] = ""
+        metadata["subject_attribution_reason"] = (
+            "structural facet of quarantined parent assertion"
+        )
+        metadata["excluded_from_retrieval"] = True
+        metadata["conflict_action"] = "subject_attribution_parent_quarantine"
+        connection.execute(
+            "UPDATE records SET state='quarantined',metadata_json=? "
+            "WHERE scope_id=? AND memory_id=?",
+            (_json(metadata), job["scope_id"], memory_id),
+        )
+        changed_ids.append(memory_id)
+        _repair_slot_head(
+            connection,
+            job["scope_id"],
+            str(row["slot_key"]),
+            memory_id,
+            all_quarantine_ids,
+        )
+    return {
+        "changed_memory_ids": sorted(changed_ids),
+        "quarantined_memory_ids": sorted(quarantine_ids),
+        "cascaded_quarantined_memory_ids": sorted(dependent_ids),
+        "kept_memory_ids": sorted(set(candidate_ids) - quarantine_ids),
+    }
+
+
+def _reused_application_state(
+    connection: sqlite3.Connection,
+    job: Mapping[str, Any],
+    audit_id: str,
+    decisions: Sequence[Mapping[str, str]],
+) -> dict[str, Any]:
+    candidate_ids = {item["memory_id"] for item in job["payload"]["candidates"]}
+    quarantine_ids = {
+        item["memory_id"] for item in decisions if item["decision"] != "keep_user"
+    }
+    dependent_ids: set[str] = set()
+    for row in connection.execute(
+        "SELECT memory_id,metadata_json FROM records WHERE scope_id=?",
+        (job["scope_id"],),
+    ).fetchall():
+        metadata = _metadata(row)
+        if (
+            _text(metadata.get("subject_attribution_audit_id")) == audit_id
+            and _text(metadata.get("subject_attribution_decision"))
+            == "quarantine_with_parent"
+            and _text(metadata.get("subject_attribution_parent_memory_id"))
+            in quarantine_ids
+        ):
+            dependent_ids.add(str(row["memory_id"]))
+    return {
+        "changed_memory_ids": sorted(candidate_ids | dependent_ids),
+        "quarantined_memory_ids": sorted(quarantine_ids),
+        "cascaded_quarantined_memory_ids": sorted(dependent_ids),
+        "kept_memory_ids": sorted(candidate_ids - quarantine_ids),
+    }
+
+
+def _cost(metadata: Mapping[str, Any]) -> float:
+    usage = metadata.get("usage")
+    usage = usage if isinstance(usage, Mapping) else metadata
+    prompt = int(usage.get("prompt_tokens", 0) or 0)
+    completion = int(usage.get("completion_tokens", 0) or 0)
+    hit = int(usage.get("prompt_cache_hit_tokens", 0) or 0)
+    miss = int(usage.get("prompt_cache_miss_tokens", prompt - hit) or 0)
+    prompt_rate = float(os.getenv("TMCRA_DEEPSEEK_PRO_PROMPT_COST_PER_MILLION", "3"))
+    completion_rate = float(os.getenv("TMCRA_DEEPSEEK_PRO_COMPLETION_COST_PER_MILLION", "6"))
+    cache_rate = float(os.getenv("TMCRA_DEEPSEEK_PRO_CACHE_COST_PER_MILLION", "0.025"))
+    return (miss * prompt_rate + hit * cache_rate + completion * completion_rate) / 1_000_000
+
+
+def execute_job(
+    database: Path,
+    job: Mapping[str, Any],
+    client: AttributionClient,
+) -> dict[str, Any]:
+    audit_id = "saa_" + job["request_sha256"][:24]
+    request_json = _json(job["payload"])
+    with closing(sqlite3.connect(database, timeout=30)) as connection:
+        connection.row_factory = sqlite3.Row
+        _initialize(connection)
+        existing = connection.execute(
+            "SELECT status,decisions_json,call_metadata_json FROM "
+            "v4_subject_attribution_audits WHERE audit_id=?",
+            (audit_id,),
+        ).fetchone()
+        if existing is not None:
+            if str(existing["status"]) != "completed":
+                raise AttributionError(
+                    f"{audit_id}: prior attribution call is not safely reusable"
+                )
+            decisions = json.loads(str(existing["decisions_json"]))
+            applied = _reused_application_state(
+                connection, job, audit_id, decisions
+            )
+            return {
+                "audit_id": audit_id,
+                "status": "reused",
+                "physical_api_calls": 0,
+                "decisions": decisions,
+                "call_metadata": json.loads(str(existing["call_metadata_json"])),
+                **applied,
+            }
+        now = _now()
+        connection.execute(
+            "INSERT INTO v4_subject_attribution_audits VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)",
+            (
+                audit_id,
+                job["scope_id"],
+                job["message_id"],
+                PROMPT_VERSION,
+                MODEL,
+                request_json,
+                job["request_sha256"],
+                "api_started",
+                "",
+                "",
+                "{}",
+                "[]",
+                "",
+                now,
+                now,
+            ),
+        )
+        connection.commit()
+
+    try:
+        content, call_metadata = client.complete(job["payload"])
+    except Exception as exc:
+        with closing(sqlite3.connect(database, timeout=30)) as connection:
+            connection.execute(
+                "UPDATE v4_subject_attribution_audits SET status='failed',error=?,"
+                "call_metadata_json=?,updated_at=? "
+                "WHERE audit_id=? AND status='api_started'",
+                (
+                    str(exc),
+                    _json(dict(getattr(exc, "metadata", {}) or {})),
+                    _now(),
+                    audit_id,
+                ),
+            )
+            connection.commit()
+        raise
+
+    with closing(sqlite3.connect(database, timeout=30)) as connection:
+        received = connection.execute(
+            "UPDATE v4_subject_attribution_audits SET status='response_received',"
+            "response_json=?,response_sha256=?,call_metadata_json=?,updated_at=? "
+            "WHERE audit_id=? AND status='api_started'",
+            (
+                content,
+                hashlib.sha256(content.encode("utf-8")).hexdigest(),
+                _json(dict(call_metadata)),
+                _now(),
+                audit_id,
+            ),
+        )
+        if received.rowcount != 1:
+            raise AttributionError("attribution journal changed before response save")
+        connection.commit()
+    try:
+        raw = json.loads(content)
+        decisions = validate_decisions(raw, job["payload"])
+    except (json.JSONDecodeError, AttributionError) as exc:
+        error = (
+            "attribution response content is not JSON"
+            if isinstance(exc, json.JSONDecodeError)
+            else str(exc)
+        )
+        with closing(sqlite3.connect(database, timeout=30)) as connection:
+            connection.execute(
+                "UPDATE v4_subject_attribution_audits SET status='failed',error=?,"
+                "updated_at=? WHERE audit_id=? AND status='response_received'",
+                (error, _now(), audit_id),
+            )
+            connection.commit()
+        raise AttributionError(error) from exc
+    with closing(sqlite3.connect(database, timeout=30)) as connection:
+        connection.row_factory = sqlite3.Row
+        connection.execute("BEGIN IMMEDIATE")
+        applied = _apply_decisions(connection, job, audit_id, decisions)
+        superseded = connection.execute(
+            "UPDATE v4_subject_attribution_audits SET status='superseded',error=?,"
+            "updated_at=? WHERE scope_id=? AND message_id=? "
+            "AND status IN ('completed','superseded') "
+            "AND audit_id<>?",
+            (
+                f"superseded_by:{audit_id}",
+                _now(),
+                job["scope_id"],
+                job["message_id"],
+                audit_id,
+            ),
+        ).rowcount
+        updated = connection.execute(
+            "UPDATE v4_subject_attribution_audits SET status='completed',response_json=?,"
+            "response_sha256=?,call_metadata_json=?,decisions_json=?,updated_at=? "
+            "WHERE audit_id=? AND status='response_received'",
+            (
+                content,
+                hashlib.sha256(content.encode("utf-8")).hexdigest(),
+                _json(dict(call_metadata)),
+                _json(decisions),
+                _now(),
+                audit_id,
+            ),
+        )
+        if updated.rowcount != 1:
+            raise AttributionError("attribution journal changed before commit")
+        connection.commit()
+    return {
+        "audit_id": audit_id,
+        "status": "completed",
+        "physical_api_calls": 1,
+        "estimated_cost_cny": _cost(call_metadata),
+        "decisions": decisions,
+        "call_metadata": dict(call_metadata),
+        "superseded_audit_count": int(superseded),
+        **applied,
+    }
+
+
+def _worker_databases(run_dir: Path, workers: Sequence[str]) -> list[tuple[str, Path, str]]:
+    selected = set(workers)
+    output: list[tuple[str, Path, str]] = []
+    for database in sorted((run_dir / "writer").glob("worker_*/native_memory.sqlite3")):
+        worker = database.parent.name
+        if selected and worker not in selected:
+            continue
+        with closing(sqlite3.connect(database)) as connection:
+            row = connection.execute(
+                "SELECT scope_id FROM v4_source_journal LIMIT 1"
+            ).fetchone()
+        if row is None or not _text(row[0]):
+            raise AttributionError(f"{worker}: scope is missing")
+        output.append((worker, database, _text(row[0])))
+    if selected - {item[0] for item in output}:
+        raise AttributionError(
+            "unknown workers: " + ",".join(sorted(selected - {item[0] for item in output}))
+        )
+    return output
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--run-dir", type=Path, required=True)
+    parser.add_argument("--workers", default="")
+    parser.add_argument("--apply", action="store_true")
+    parser.add_argument("--output", type=Path, required=True)
+    args = parser.parse_args()
+    run_dir = args.run_dir.resolve()
+    workers = [item.strip() for item in args.workers.split(",") if item.strip()]
+    scanned: list[dict[str, Any]] = []
+    worker_by_database: dict[str, str] = {}
+    for worker, database, scope_id in _worker_databases(run_dir, workers):
+        worker_by_database[str(database)] = worker
+        for job in scan_database(database, scope_id):
+            scanned.append({"worker": worker, **job})
+    results: list[dict[str, Any]] = []
+    if args.apply and scanned:
+        client = DeepSeekProAttributionClient()
+        for job in scanned:
+            results.append(
+                {
+                    "worker": job["worker"],
+                    "message_id": job["message_id"],
+                    **execute_job(Path(job["database"]), job, client),
+                }
+            )
+    report = {
+        "schema_version": "tmcra.v4.subject-attribution-report.1",
+        "status": "complete",
+        "mode": "apply" if args.apply else "scan_only",
+        "prompt_version": PROMPT_VERSION,
+        "model": MODEL,
+        "run_dir": str(run_dir),
+        "scanned_worker_count": len(_worker_databases(run_dir, workers)),
+        "routed_message_count": len(scanned),
+        "routed_candidate_count": sum(
+            len(job["payload"]["candidates"]) for job in scanned
+        ),
+        "physical_api_calls": sum(
+            int(item.get("physical_api_calls", 0) or 0) for item in results
+        ),
+        "estimated_cost_cny": round(
+            sum(float(item.get("estimated_cost_cny", 0.0) or 0.0) for item in results),
+            8,
+        ),
+        "decision_quarantined_count": sum(
+            len(item.get("quarantined_memory_ids", [])) for item in results
+        ),
+        "cascaded_quarantined_count": sum(
+            len(item.get("cascaded_quarantined_memory_ids", []))
+            for item in results
+        ),
+        "quarantined_count": sum(
+            len(item.get("quarantined_memory_ids", []))
+            + len(item.get("cascaded_quarantined_memory_ids", []))
+            for item in results
+        ),
+        "routed": [
+            {
+                "worker": job["worker"],
+                "database": job["database"],
+                "scope_id": job["scope_id"],
+                "message_id": job["message_id"],
+                "session_index": job["session_index"],
+                "message_index": job["message_index"],
+                "source_turn_index": job["source_turn_index"],
+                "route_reasons": job["route_reasons"],
+                "request_sha256": job["request_sha256"],
+                "candidate_count": len(job["payload"]["candidates"]),
+                "candidates": job["review_candidates"],
+            }
+            for job in scanned
+        ],
+        "results": results,
+    }
+    args.output.parent.mkdir(parents=True, exist_ok=True)
+    args.output.write_text(
+        json.dumps(report, ensure_ascii=False, indent=2, sort_keys=True) + "\n",
+        encoding="utf-8",
+    )
+    print(json.dumps(report, ensure_ascii=False, sort_keys=True))
+
+
+if __name__ == "__main__":
+    main()

benchmarks/longmemeval/src/tmcra_benchmark/legacy/prepare_tmcra_v4_e2e_data.py

@@ -0,0 +1,261 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+from collections import Counter
+from pathlib import Path
+from typing import Any, Mapping, Sequence
+
+
+WRITER_FIELDS = (
+    "question_id",
+    "haystack_sessions",
+    "haystack_session_ids",
+    "haystack_dates",
+)
+FORBIDDEN_WRITER_FIELDS = frozenset(
+    {
+        "question",
+        "question_date",
+        "question_type",
+        "answer",
+        "gold_answer",
+        "answer_session_ids",
+        "labels",
+        "supervision",
+    }
+)
+
+
+class PreparationError(RuntimeError):
+    pass
+
+
+def clean_text(value: Any) -> str:
+    return " ".join(str(value or "").split())
+
+
+def sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def write_jsonl(path: Path, rows: Sequence[Mapping[str, Any]]) -> None:
+    with path.open("x", encoding="utf-8") as handle:
+        for row in rows:
+            handle.write(
+                json.dumps(dict(row), ensure_ascii=False, sort_keys=True) + "\n"
+            )
+
+
+def validate_source_row(row: Mapping[str, Any]) -> None:
+    qid = clean_text(row.get("question_id"))
+    sessions = row.get("haystack_sessions")
+    session_ids = row.get("haystack_session_ids")
+    dates = row.get("haystack_dates")
+    if not qid or not isinstance(sessions, list) or not sessions:
+        raise PreparationError(f"{qid or '<missing-qid>'}: missing history sessions")
+    if not isinstance(session_ids, list) or not isinstance(dates, list):
+        raise PreparationError(f"{qid}: session IDs and dates must be arrays")
+    if len(sessions) != len(session_ids) or len(sessions) != len(dates):
+        raise PreparationError(f"{qid}: history/session/date lengths differ")
+    for session_index, session in enumerate(sessions):
+        if not isinstance(session, list) or not session:
+            raise PreparationError(f"{qid}: session {session_index} is empty")
+        for message_index, message in enumerate(session):
+            if not isinstance(message, Mapping):
+                raise PreparationError(
+                    f"{qid}: session {session_index} message {message_index} is not an object"
+                )
+            role = clean_text(message.get("role")).lower()
+            if role not in {"user", "assistant", "system", "tool"}:
+                raise PreparationError(
+                    f"{qid}: session {session_index} message {message_index} is invalid"
+                )
+
+
+def prepare(
+    *, data_path: Path, qid_path: Path, out_dir: Path
+) -> dict[str, Any]:
+    qids = [
+        clean_text(value)
+        for value in qid_path.read_text(encoding="utf-8").splitlines()
+        if clean_text(value)
+    ]
+    if not qids or len(qids) != len(set(qids)):
+        raise PreparationError("qid list must be non-empty and unique")
+    source = json.loads(data_path.read_text(encoding="utf-8"))
+    if not isinstance(source, list):
+        raise PreparationError("source dataset must be a JSON array")
+    source_rows: dict[str, Mapping[str, Any]] = {}
+    for raw_row in source:
+        if not isinstance(raw_row, Mapping):
+            raise PreparationError("source dataset contains a non-object row")
+        validate_source_row(raw_row)
+        source_qid = clean_text(raw_row.get("question_id"))
+        if source_qid in source_rows:
+            raise PreparationError(f"duplicate source question_id: {source_qid}")
+        source_rows[source_qid] = raw_row
+    missing = [qid for qid in qids if qid not in source_rows]
+    if missing:
+        raise PreparationError(f"missing qids in source data: {missing}")
+
+    out_dir.mkdir(parents=True, exist_ok=False)
+    scope_manifest: list[dict[str, Any]] = []
+    query_manifest: list[dict[str, Any]] = []
+    evaluation_refs: list[dict[str, Any]] = []
+    workers: list[dict[str, Any]] = []
+    writer_rows: list[dict[str, Any]] = []
+    total_input_messages = 0
+    total_nonempty_messages = 0
+    total_empty_messages = 0
+    total_duplicate_session_id_occurrences = 0
+    duplicate_session_id_qids: list[str] = []
+    for worker_index, qid in enumerate(qids):
+        source_row = source_rows[qid]
+        session_id_counts = Counter(
+            clean_text(value)
+            for value in source_row.get("haystack_session_ids") or []
+            if clean_text(value)
+        )
+        duplicate_session_ids = {
+            session_id: count
+            for session_id, count in sorted(session_id_counts.items())
+            if count > 1
+        }
+        duplicate_occurrences = sum(
+            count - 1 for count in duplicate_session_ids.values()
+        )
+        if duplicate_occurrences:
+            duplicate_session_id_qids.append(qid)
+            total_duplicate_session_id_occurrences += duplicate_occurrences
+        writer_row = {field: source_row.get(field) for field in WRITER_FIELDS}
+        if FORBIDDEN_WRITER_FIELDS.intersection(writer_row):
+            raise AssertionError("writer sanitizer retained a forbidden field")
+        worker_dir = out_dir / "writer" / f"worker_{worker_index:03d}"
+        worker_dir.mkdir(parents=True, exist_ok=False)
+        writer_input = worker_dir / "input.json"
+        writer_input.write_text(
+            json.dumps([writer_row], ensure_ascii=False) + "\n", encoding="utf-8"
+        )
+        writer_rows.append(writer_row)
+        database = worker_dir / "native_memory.sqlite3"
+        scope_id = f"tmcra_v4:{qid}"
+        index_path = out_dir / "indexes" / f"{qid}.pt"
+        scope_manifest.append(
+            {
+                "question_id": qid,
+                "db_path": str(database),
+                "scope_id": scope_id,
+                "index_path": str(index_path),
+            }
+        )
+        query_manifest.append(
+            {
+                "question_id": qid,
+                "question": clean_text(source_row.get("question")),
+                "question_date": clean_text(source_row.get("question_date")),
+                "question_type": clean_text(source_row.get("question_type")),
+                "db_path": str(database),
+                "scope_id": scope_id,
+                "index_path": str(index_path),
+            }
+        )
+        evaluation_refs.append(
+            {
+                "question_id": qid,
+                "answer": source_row.get("answer"),
+                "answer_session_ids": source_row.get("answer_session_ids"),
+            }
+        )
+        workers.append(
+            {
+                "worker_index": worker_index,
+                "question_id": qid,
+                "worker_dir": str(worker_dir),
+                "input": str(writer_input),
+                "input_sha256": sha256_file(writer_input),
+                "scope_id": scope_id,
+                "session_count": len(source_row.get("haystack_sessions") or []),
+                "message_count": sum(
+                    len(session)
+                    for session in source_row.get("haystack_sessions") or []
+                ),
+                "nonempty_message_count": sum(
+                    1
+                    for session in source_row.get("haystack_sessions") or []
+                    for message in session
+                    if str(message.get("content") or "").strip()
+                ),
+                "empty_message_count": sum(
+                    1
+                    for session in source_row.get("haystack_sessions") or []
+                    for message in session
+                    if not str(message.get("content") or "").strip()
+                ),
+                "duplicate_session_ids": duplicate_session_ids,
+                "duplicate_session_id_occurrence_count": duplicate_occurrences,
+            }
+        )
+        total_input_messages += workers[-1]["message_count"]
+        total_nonempty_messages += workers[-1]["nonempty_message_count"]
+        total_empty_messages += workers[-1]["empty_message_count"]
+    (out_dir / "indexes").mkdir(parents=True, exist_ok=False)
+    (out_dir / "writer_input.json").write_text(
+        json.dumps(writer_rows, ensure_ascii=False) + "\n", encoding="utf-8"
+    )
+    write_jsonl(out_dir / "scope_manifest.jsonl", scope_manifest)
+    write_jsonl(out_dir / "query_manifest.jsonl", query_manifest)
+    evaluation_dir = out_dir / "evaluation_only"
+    evaluation_dir.mkdir(parents=True, exist_ok=False)
+    write_jsonl(evaluation_dir / "references.jsonl", evaluation_refs)
+    (out_dir / "qids.txt").write_text("\n".join(qids) + "\n", encoding="utf-8")
+    manifest = {
+        "schema_version": "tmcra.v4.e2e-input.1",
+        "status": "prepared",
+        "source_data": str(data_path.resolve()),
+        "source_data_sha256": sha256_file(data_path),
+        "row_count": len(qids),
+        "input_message_count": total_input_messages,
+        "nonempty_message_count": total_nonempty_messages,
+        "empty_message_count": total_empty_messages,
+        "duplicate_session_id_occurrence_count": total_duplicate_session_id_occurrences,
+        "duplicate_session_id_qids": duplicate_session_id_qids,
+        "qids": qids,
+        "writer_fields": list(WRITER_FIELDS),
+        "forbidden_writer_fields": sorted(FORBIDDEN_WRITER_FIELDS),
+        "writer_inputs_have_query_or_evaluation_fields": False,
+        "gold_isolation_dir": str(evaluation_dir),
+        "workers": workers,
+        "combined_writer_input": str(out_dir / "writer_input.json"),
+        "scope_manifest": str(out_dir / "scope_manifest.jsonl"),
+        "query_manifest": str(out_dir / "query_manifest.jsonl"),
+    }
+    (out_dir / "input_manifest.json").write_text(
+        json.dumps(manifest, indent=2, sort_keys=True) + "\n", encoding="utf-8"
+    )
+    return manifest
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Prepare gold-isolated TMCRA V4 E2E inputs")
+    parser.add_argument("--data", required=True, type=Path)
+    parser.add_argument("--qid-list", required=True, type=Path)
+    parser.add_argument("--out-dir", required=True, type=Path)
+    args = parser.parse_args()
+    report = prepare(
+        data_path=args.data.resolve(),
+        qid_path=args.qid_list.resolve(),
+        out_dir=args.out_dir.resolve(),
+    )
+    print(json.dumps(report, indent=2, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

benchmarks/longmemeval/src/tmcra_benchmark/legacy/run_tmcra_v4_build.py

@@ -0,0 +1,984 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sqlite3
+import subprocess
+import sys
+import time
+from contextlib import closing
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Mapping, Sequence
+
+from prepare_tmcra_v4_e2e_data import prepare
+from tmcra_v4_cost_report import build_report, collect_calls
+from tmcra_v4_slow_graph import (
+    PROCESS_LOSS_INTERRUPTION_ERROR,
+    SlowGraphStore,
+    load_graph_schema,
+)
+
+
+BASE = Path(__file__).resolve().parent
+PACKAGE_ROOT = BASE.parent
+PROJECT_ROOT = BASE.parents[2]
+DEFAULT_DATA = PROJECT_ROOT / "data" / "longmemeval_s_cleaned.json"
+DEFAULT_REPO = PACKAGE_ROOT / "vendor" / "tmcra_integrated"
+DEFAULT_WRITER_ENV = PROJECT_ROOT / "configs" / "writer.env"
+DEFAULT_EMBEDDING = PROJECT_ROOT / "models" / "BAAI" / "bge-m3"
+SUBJECT_ATTRIBUTION_PROMPT_VERSION = "tmcra-v4-subject-attribution-2026-07-14.3"
+
+
+class BuildError(RuntimeError):
+    pass
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+def _stage(root: Path, name: str, **values: Any) -> None:
+    record = {"at": _now(), "stage": name, **values}
+    with (root / "build.log.jsonl").open("a", encoding="utf-8") as handle:
+        handle.write(json.dumps(record, sort_keys=True) + "\n")
+    print(json.dumps(record, sort_keys=True), flush=True)
+
+
+def _load_shell_environment(path: Path) -> dict[str, str]:
+    if not path.is_file():
+        raise BuildError(f"writer environment file is missing: {path}")
+    command = 'set -a; source "$1"; env -0'
+    result = subprocess.run(
+        ["bash", "-c", command, "tmcra-v4-env", str(path)],
+        check=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+    )
+    loaded: dict[str, str] = {}
+    for entry in result.stdout.decode("utf-8").split("\0"):
+        if "=" in entry:
+            key, value = entry.split("=", 1)
+            loaded[key] = value
+    return loaded
+
+
+def _key_pool(environment: Mapping[str, str]) -> list[str]:
+    raw = environment.get("TMCRA_DEEPSEEK_WRITER_KEY_POOL", "")
+    keys = [item.strip() for item in raw.split(",") if item.strip()]
+    if not keys or len(keys) != len(set(keys)):
+        raise BuildError("DeepSeek writer key pool must be non-empty and unique")
+    configured_count = environment.get("TMCRA_DEEPSEEK_WRITER_KEY_POOL_COUNT", "")
+    if configured_count and int(configured_count) != len(keys):
+        raise BuildError("DeepSeek writer key pool count does not match actual keys")
+    return keys
+
+
+def _rotated(keys: Sequence[str], worker_index: int) -> str:
+    offset = worker_index % len(keys)
+    return ",".join([*keys[offset:], *keys[:offset]])
+
+
+def _worker_environment(base: Mapping[str, str], keys: Sequence[str], worker_index: int) -> dict[str, str]:
+    environment = dict(base)
+    pool = _rotated(keys, worker_index)
+    base_url = environment.get("TMCRA_DEEPSEEK_WRITER_BASE_URL") or environment.get("TMCRA_WRITER_BASE_URL") or "https://api.deepseek.com/v1"
+    max_tokens = environment.get("TMCRA_WRITER_MAX_TOKENS", "16384")
+    environment.update(
+        {
+            "TMCRA_WRITER_MAX_TOKENS": max_tokens,
+            "TMCRA_WRITER_BASE_URL": base_url,
+            "TMCRA_WRITER_MODEL": "deepseek-v4-flash",
+            "TMCRA_WRITER_API_KEY_POOL": pool,
+            "TMCRA_DEEPSEEK_FLASH_BASE_URL": base_url,
+            "TMCRA_DEEPSEEK_FLASH_KEY_POOL": pool,
+            "TMCRA_DEEPSEEK_FLASH_MAX_TOKENS": max_tokens,
+            "TMCRA_DEEPSEEK_FLASH_PROMPT_COST_PER_MILLION": "1",
+            "TMCRA_DEEPSEEK_FLASH_COMPLETION_COST_PER_MILLION": "2",
+            "TMCRA_DEEPSEEK_FLASH_CACHE_COST_PER_MILLION": "0.02",
+            "TMCRA_DEEPSEEK_PRO_BASE_URL": base_url,
+            "TMCRA_DEEPSEEK_PRO_KEY_POOL": pool,
+            "TMCRA_DEEPSEEK_PRO_MAX_TOKENS": max_tokens,
+            "TMCRA_DEEPSEEK_PRO_PROMPT_COST_PER_MILLION": "3",
+            "TMCRA_DEEPSEEK_PRO_COMPLETION_COST_PER_MILLION": "6",
+            "TMCRA_DEEPSEEK_PRO_CACHE_COST_PER_MILLION": "0.025",
+        }
+    )
+    return environment
+
+
+def _run(command: Sequence[str], log_path: Path, environment: Mapping[str, str]) -> None:
+    log_path.parent.mkdir(parents=True, exist_ok=True)
+    with log_path.open("x", encoding="utf-8") as log:
+        log.write(json.dumps({"command": list(command)}, sort_keys=True) + "\n")
+        log.flush()
+        subprocess.run(
+            list(command),
+            check=True,
+            stdout=log,
+            stderr=subprocess.STDOUT,
+            env=dict(environment),
+        )
+
+
+def _resume_log(directory: Path, stem: str) -> Path:
+    return directory / f"{stem}.resume.{time.time_ns()}.log"
+
+
+def _load_resume_manifest(out_dir: Path) -> dict[str, Any]:
+    manifest_path = out_dir / "input_manifest.json"
+    if not manifest_path.is_file():
+        raise BuildError("resume run has no input_manifest.json")
+    try:
+        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise BuildError("resume input manifest is unreadable") from exc
+    if not isinstance(manifest, Mapping):
+        raise BuildError("resume input manifest must be an object")
+    workers = manifest.get("workers")
+    if (
+        manifest.get("status") != "prepared"
+        or not isinstance(workers, list)
+        or not workers
+        or int(manifest.get("row_count", 0) or 0) != len(workers)
+    ):
+        raise BuildError("resume input manifest is incomplete or stale")
+    return dict(manifest)
+
+
+def _verify_resume_writer(worker: Mapping[str, Any]) -> None:
+    worker_dir = Path(str(worker["worker_dir"])).resolve()
+    database = worker_dir / "native_memory.sqlite3"
+    report_path = worker_dir / "product_writer_report.json"
+    audit_path = worker_dir / "writer_chain_audit.json"
+    if not all(path.is_file() for path in (database, report_path, audit_path)):
+        raise BuildError(f"resume writer artifacts are incomplete: {worker_dir}")
+    report = json.loads(report_path.read_text(encoding="utf-8"))
+    audit = json.loads(audit_path.read_text(encoding="utf-8"))
+    if report.get("completed") is not True or audit.get("passed") is not True:
+        raise BuildError(f"resume writer audit is not complete: {worker_dir}")
+    with closing(sqlite3.connect(database)) as con:
+        statuses = dict(
+            con.execute("SELECT status,count(*) FROM v4_batch_journal GROUP BY status")
+        )
+    if statuses != {"committed": int(report.get("batches", -1))}:
+        raise BuildError(
+            f"resume writer journal is not fully committed: {worker_dir}: {statuses}"
+        )
+
+
+def _interrupted_writer_calls(worker: Mapping[str, Any]) -> list[dict[str, str]]:
+    worker_dir = Path(str(worker["worker_dir"])).resolve()
+    database = worker_dir / "native_memory.sqlite3"
+    if not database.is_file():
+        return []
+    output: list[dict[str, str]] = []
+    with closing(sqlite3.connect(database)) as con:
+        con.row_factory = sqlite3.Row
+        for row in con.execute(
+            "SELECT batch_id FROM v4_batch_journal WHERE status='api_started' ORDER BY batch_index"
+        ):
+            output.append(
+                {
+                    "worker": str(worker["question_id"]),
+                    "stage": "batch_flash",
+                    "call_key": f"flash:{row['batch_id']}",
+                }
+            )
+        if con.execute(
+            "SELECT 1 FROM sqlite_master WHERE type='table' AND name='v4_reconciliation_jobs'"
+        ).fetchone():
+            for row in con.execute(
+                "SELECT job_id FROM v4_reconciliation_jobs WHERE status='pro_started' ORDER BY created_at,job_id"
+            ):
+                output.append(
+                    {
+                        "worker": str(worker["question_id"]),
+                        "stage": "reconciliation_pro",
+                        "call_key": f"pro:{row['job_id']}",
+                    }
+                )
+    return output
+
+
+def _interrupted_slow_calls(worker: Mapping[str, Any]) -> list[dict[str, Any]]:
+    worker_dir = Path(str(worker["worker_dir"])).resolve()
+    database = worker_dir / "native_memory.sqlite3"
+    if not database.is_file():
+        return []
+    output: list[dict[str, Any]] = []
+    with closing(sqlite3.connect(database)) as con:
+        con.row_factory = sqlite3.Row
+        tables = {
+            str(row[0])
+            for row in con.execute(
+                "SELECT name FROM sqlite_master WHERE type='table'"
+            )
+        }
+        if not {"slow_graph_jobs", "slow_graph_attempts"} <= tables:
+            return []
+        recovered_attempts: set[str] = set()
+        if "slow_graph_process_loss_recoveries" in tables:
+            recovered_attempts = {
+                str(row[0])
+                for row in con.execute(
+                    "SELECT attempt_id FROM slow_graph_process_loss_recoveries"
+                )
+            }
+        rows = con.execute(
+            "SELECT j.job_id,j.scope_id,j.region_key,j.status,j.claim_owner,"
+            "j.lease_expires_at,a.attempt_id,a.status AS attempt_status,"
+            "a.created_at FROM slow_graph_jobs j JOIN slow_graph_attempts a "
+            "ON a.job_id=j.job_id WHERE ("
+            "(j.status='pending' AND j.claim_token IS NOT NULL "
+            "AND a.status='started' AND a.claim_token=j.claim_token "
+            "AND a.claim_owner=j.claim_owner) OR "
+            "(j.status='failed' AND j.claim_token IS NULL AND j.last_error=? "
+            "AND a.status='expired' AND a.error=?)) "
+            "ORDER BY a.created_at,a.attempt_id",
+            (PROCESS_LOSS_INTERRUPTION_ERROR, PROCESS_LOSS_INTERRUPTION_ERROR),
+        ).fetchall()
+        for row in rows:
+            if str(row["attempt_id"]) in recovered_attempts:
+                continue
+            output.append(
+                {
+                    "worker": str(worker.get("question_id") or worker_dir.name),
+                    **dict(row),
+                }
+            )
+    return output
+
+
+def _recover_interrupted_slow_calls(
+    worker: Mapping[str, Any], *, repo: Path
+) -> list[dict[str, Any]]:
+    worker_dir = Path(str(worker["worker_dir"])).resolve()
+    database = worker_dir / "native_memory.sqlite3"
+    store = SlowGraphStore(database, schema=load_graph_schema(repo))
+    reviewed = store.interrupted_process_loss_attempts()
+    reports = [
+        store.recover_interrupted_process_loss(
+            str(item["job_id"]),
+            expected_attempt_id=str(item["attempt_id"]),
+        )
+        for item in reviewed
+    ]
+    if reports:
+        report_path = _resume_log(worker_dir, "slow_process_loss_recovery").with_suffix(
+            ".json"
+        )
+        report_path.write_text(
+            json.dumps(
+                {
+                    "schema_version": "tmcra.v4.slow-process-loss-worker-report.1",
+                    "worker": str(worker.get("question_id") or worker_dir.name),
+                    "physical_api_calls_during_recovery": 0,
+                    "recoveries": reports,
+                },
+                indent=2,
+                sort_keys=True,
+            )
+            + "\n",
+            encoding="utf-8",
+        )
+    return reports
+
+
+def _failed_slow_jobs(database: Path) -> list[dict[str, str]]:
+    with closing(sqlite3.connect(database)) as con:
+        con.row_factory = sqlite3.Row
+        if con.execute(
+            "SELECT 1 FROM sqlite_master WHERE type='table' AND name='slow_graph_jobs'"
+        ).fetchone() is None:
+            return []
+        return [
+            {
+                "job_id": str(row["job_id"]),
+                "region_key": str(row["region_key"]),
+                "last_error": str(row["last_error"]),
+            }
+            for row in con.execute(
+                "SELECT job_id,region_key,last_error FROM slow_graph_jobs "
+                "WHERE status IN ('failed','retryable') ORDER BY created_at,job_id"
+            )
+        ]
+
+
+def _slow_worker_resume(
+    worker: Mapping[str, Any],
+    *,
+    repo: Path,
+    environment: Mapping[str, str],
+    enqueue: bool = True,
+    recover_interrupted_slow_calls: bool = False,
+) -> None:
+    worker_dir = Path(str(worker["worker_dir"])).resolve()
+    database = worker_dir / "native_memory.sqlite3"
+    scope_id = str(worker["scope_id"])
+    prefix = [
+        sys.executable,
+        str(BASE / "tmcra_v4_slow_graph.py"),
+        str(database),
+        "--repo",
+        str(repo),
+    ]
+    interrupted = _interrupted_slow_calls(worker)
+    if interrupted and not recover_interrupted_slow_calls:
+        raise BuildError(
+            "resume has Slow calls without durable responses; explicit process-loss "
+            "recovery flag is required: " + json.dumps(interrupted, sort_keys=True)
+        )
+    if interrupted:
+        recovered = _recover_interrupted_slow_calls(worker, repo=repo)
+        if len(recovered) != len(interrupted):
+            raise BuildError(
+                "Slow process-loss recovery count drifted after preflight"
+            )
+    if enqueue:
+        _run(
+            [*prefix, "enqueue", scope_id],
+            _resume_log(worker_dir, "slow_enqueue"),
+            environment,
+        )
+    failed = _failed_slow_jobs(database)
+    if failed:
+        raise BuildError(
+            "resume requires explicit revalidation of failed slow jobs: "
+            + json.dumps(failed, sort_keys=True)
+        )
+    _run([*prefix, "drain"], _resume_log(worker_dir, "slow_drain"), environment)
+    _run(
+        [*prefix, "audit", scope_id, "--require-promotion-coverage"],
+        _resume_log(worker_dir, "slow_audit"),
+        environment,
+    )
+
+
+def _subject_attribution_stage(
+    out_dir: Path, environment: Mapping[str, str]
+) -> dict[str, Any]:
+    report_path = out_dir / "subject_attribution_report.json"
+    if not report_path.exists():
+        _run(
+            [
+                sys.executable,
+                str(BASE / "ops" / "audit_tmcra_v4_subject_attribution.py"),
+                "--run-dir",
+                str(out_dir),
+                "--apply",
+                "--output",
+                str(report_path),
+            ],
+            out_dir / "subject_attribution.log",
+            environment,
+        )
+    try:
+        report = json.loads(report_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise BuildError("subject-attribution report is unreadable") from exc
+    if (
+        not isinstance(report, Mapping)
+        or report.get("status") != "complete"
+        or report.get("mode") != "apply"
+        or report.get("prompt_version") != SUBJECT_ATTRIBUTION_PROMPT_VERSION
+        or report.get("model") != "deepseek-v4-pro"
+    ):
+        raise BuildError("subject-attribution stage is incomplete or drifted")
+    _stage(
+        out_dir,
+        "subject_attribution_complete",
+        routed_messages=int(report.get("routed_message_count", 0) or 0),
+        quarantined=int(report.get("quarantined_count", 0) or 0),
+        physical_api_calls=int(report.get("physical_api_calls", 0) or 0),
+    )
+    return dict(report)
+
+
+def _slow_process_loss_cost_uncertainty(
+    databases: Sequence[Path],
+) -> dict[str, int]:
+    recoveries = 0
+    potential_min = 0
+    potential_max = 0
+    for database in databases:
+        with closing(sqlite3.connect(database)) as con:
+            if con.execute(
+                "SELECT 1 FROM sqlite_master WHERE type='table' "
+                "AND name='slow_graph_process_loss_recoveries'"
+            ).fetchone() is None:
+                continue
+            row = con.execute(
+                "SELECT count(*),"
+                "coalesce(sum(potential_duplicate_physical_calls_min),0),"
+                "coalesce(sum(potential_duplicate_physical_calls_max),0) "
+                "FROM slow_graph_process_loss_recoveries"
+            ).fetchone()
+            recoveries += int(row[0])
+            potential_min += int(row[1])
+            potential_max += int(row[2])
+    return {
+        "unknown_external_call_outcomes": recoveries,
+        "potential_duplicate_physical_calls_min": potential_min,
+        "potential_duplicate_physical_calls_max": potential_max,
+    }
+
+
+def _finalize_build(
+    *,
+    out_dir: Path,
+    workers: Sequence[Mapping[str, Any]],
+    writer_concurrency: int,
+    slow_concurrency: int,
+    recovered: bool,
+) -> dict[str, Any]:
+    databases = [
+        Path(str(worker["worker_dir"])) / "native_memory.sqlite3"
+        for worker in workers
+    ]
+    interrupted_call_logs = [
+        path
+        for worker in workers
+        if (
+            path := Path(str(worker["worker_dir"]))
+            / "product_writer_interrupted_calls.jsonl"
+        ).is_file()
+    ]
+    cost = build_report(collect_calls(interrupted_call_logs, databases))
+    process_loss = _slow_process_loss_cost_uncertainty(databases)
+    cost["slow_process_loss_uncertainty"] = process_loss
+    cost["cost_is_fully_observed"] = (
+        process_loss["unknown_external_call_outcomes"] == 0
+    )
+    (out_dir / "build_cost_report.json").write_text(
+        json.dumps(cost, indent=2, sort_keys=True) + "\n", encoding="utf-8"
+    )
+    quality = _writer_quality_report(workers)
+    (out_dir / "writer_quality_report.json").write_text(
+        json.dumps(quality, indent=2, sort_keys=True) + "\n", encoding="utf-8"
+    )
+    report = {
+        "schema_version": "tmcra.v4.build.1",
+        "status": "complete",
+        "row_count": len(workers),
+        "writer_concurrency": writer_concurrency,
+        "slow_concurrency": slow_concurrency,
+        "physical_api_call_count": cost["physical_call_count"],
+        "exact_cost_cny": cost["exact_cost_cny"],
+        "min_cost_cny": cost["min_cost_cny"],
+        "max_cost_cny": cost["max_cost_cny"],
+        "cost_is_fully_observed": cost["cost_is_fully_observed"],
+        "slow_process_loss_unknown_external_outcomes": process_loss[
+            "unknown_external_call_outcomes"
+        ],
+        "slow_process_loss_potential_duplicate_physical_calls_min": (
+            process_loss["potential_duplicate_physical_calls_min"]
+        ),
+        "slow_process_loss_potential_duplicate_physical_calls_max": (
+            process_loss["potential_duplicate_physical_calls_max"]
+        ),
+        "interrupted_calls_without_usage": sum(
+            int(item.get("calls_without_usage") or 0)
+            for item in cost["by_stage_model"]
+            if str(item.get("stage") or "").endswith("_interrupted")
+        ),
+        "resumed": recovered,
+        "writer_quality_requires_review": quality["requires_review"],
+        "writer_quality_warning_count": quality["warning_count"],
+        "writer_quality_dropped_count": quality["dropped_count"],
+    }
+    (out_dir / "build_report.json").write_text(
+        json.dumps(report, indent=2, sort_keys=True) + "\n", encoding="utf-8"
+    )
+    failed = out_dir / "FAILED"
+    if failed.is_file():
+        history = {
+            "resolved_at": _now(),
+            "resolved_by_resume": recovered,
+            "failure": json.loads(failed.read_text(encoding="utf-8")),
+        }
+        with (out_dir / "build_failure_history.jsonl").open(
+            "a", encoding="utf-8"
+        ) as handle:
+            handle.write(json.dumps(history, sort_keys=True) + "\n")
+        failed.unlink()
+    (out_dir / "BUILD_COMPLETE").write_text(_now() + "\n", encoding="utf-8")
+    _stage(out_dir, "complete", resumed=recovered)
+    return report
+
+
+def _writer_quality_report(
+    workers: Sequence[Mapping[str, Any]],
+) -> dict[str, Any]:
+    warning_counts: dict[str, int] = {}
+    dropped_counts: dict[str, int] = {}
+    message_count = 0
+    messages_with_warnings = 0
+    semantic_proposals = 0
+    semantic_committed = 0
+    for worker in workers:
+        path = Path(str(worker["worker_dir"])) / "product_write_messages.jsonl"
+        if not path.is_file():
+            continue
+        for raw_line in path.read_text(encoding="utf-8").splitlines():
+            if not raw_line.strip():
+                continue
+            row = json.loads(raw_line)
+            message_count += 1
+            semantic_proposals += int(row.get("semantic_proposals") or 0)
+            semantic_committed += int(row.get("semantic_committed") or 0)
+            warnings = list(row.get("validation_warnings") or [])
+            if warnings:
+                messages_with_warnings += 1
+            for warning in warnings:
+                code = str(warning.get("code") or "unknown_warning")
+                warning_counts[code] = warning_counts.get(code, 0) + 1
+                dropped = int(warning.get("dropped_count") or 0)
+                if dropped:
+                    dropped_counts[code] = dropped_counts.get(code, 0) + dropped
+    review_codes = {
+        "assistant_assertions_dropped",
+        "invalid_assertion_quarantined",
+        "invalid_interaction_quarantined",
+        "invalid_item_collection_defaulted_empty",
+        "durability_defaulted_uncertain",
+        "temporal_durability_defaulted_uncertain",
+        "conflicting_durability_defaulted_uncertain",
+    }
+    review_events = sum(warning_counts.get(code, 0) for code in review_codes)
+    return {
+        "schema_version": "tmcra.v4.writer-quality.1",
+        "message_count": message_count,
+        "messages_with_warnings": messages_with_warnings,
+        "warning_count": sum(warning_counts.values()),
+        "warnings_by_code": dict(sorted(warning_counts.items())),
+        "dropped_count": sum(dropped_counts.values()),
+        "dropped_by_code": dict(sorted(dropped_counts.items())),
+        "review_event_count": review_events,
+        "review_codes": sorted(review_codes),
+        "requires_review": review_events > 0,
+        "semantic_proposals": semantic_proposals,
+        "semantic_committed": semantic_committed,
+    }
+
+
+def _record_failure(out_dir: Path, exc: Exception) -> None:
+    failed = out_dir / "FAILED"
+    if failed.is_file():
+        with (out_dir / "build_failure_history.jsonl").open(
+            "a", encoding="utf-8"
+        ) as handle:
+            handle.write(
+                json.dumps(
+                    {
+                        "superseded_at": _now(),
+                        "resolved": False,
+                        "failure": json.loads(failed.read_text(encoding="utf-8")),
+                    },
+                    sort_keys=True,
+                )
+                + "\n"
+            )
+    failed.write_text(
+        json.dumps({"at": _now(), "error": f"{exc.__class__.__name__}: {exc}"})
+        + "\n",
+        encoding="utf-8",
+    )
+
+
+def _writer_worker(worker: Mapping[str, Any], *, repo: Path, environment: Mapping[str, str]) -> None:
+    worker_dir = Path(str(worker["worker_dir"]))
+    _run(
+        [
+            sys.executable,
+            str(BASE / "tmcra_v4_batch_writer.py"),
+            "--input",
+            str(worker["input"]),
+            "--out-dir",
+            str(worker_dir),
+            "--repo",
+            str(repo),
+        ],
+        worker_dir / "writer.log",
+        environment,
+    )
+    _run(
+        [
+            sys.executable,
+            str(BASE / "audit_tmcra_v4_chain.py"),
+            "--run-dir",
+            str(worker_dir),
+            "--output",
+            str(worker_dir / "writer_chain_audit.json"),
+            "--worker-db",
+            f"worker={worker_dir / 'native_memory.sqlite3'}",
+        ],
+        worker_dir / "writer_audit.log",
+        environment,
+    )
+
+
+def _writer_worker_resume(
+    worker: Mapping[str, Any],
+    *,
+    repo: Path,
+    environment: Mapping[str, str],
+    recover_interrupted_api_calls: bool,
+) -> None:
+    worker_dir = Path(str(worker["worker_dir"])).resolve()
+    command = [
+        sys.executable,
+        str(BASE / "tmcra_v4_batch_writer.py"),
+        "--input",
+        str(worker["input"]),
+        "--out-dir",
+        str(worker_dir),
+        "--repo",
+        str(repo),
+        "--revalidate-failed-raw-response",
+    ]
+    if recover_interrupted_api_calls:
+        command.append("--recover-interrupted-api-calls")
+    _run(
+        command,
+        _resume_log(worker_dir, "writer"),
+        environment,
+    )
+    _run(
+        [
+            sys.executable,
+            str(BASE / "audit_tmcra_v4_chain.py"),
+            "--run-dir",
+            str(worker_dir),
+            "--output",
+            str(worker_dir / "writer_chain_audit.json"),
+            "--worker-db",
+            f"worker={worker_dir / 'native_memory.sqlite3'}",
+        ],
+        _resume_log(worker_dir, "writer_audit"),
+        environment,
+    )
+
+
+def _slow_worker(worker: Mapping[str, Any], *, repo: Path, environment: Mapping[str, str]) -> None:
+    worker_dir = Path(str(worker["worker_dir"]))
+    database = worker_dir / "native_memory.sqlite3"
+    scope_id = str(worker["scope_id"])
+    prefix = [sys.executable, str(BASE / "tmcra_v4_slow_graph.py"), str(database), "--repo", str(repo)]
+    _run([*prefix, "enqueue", scope_id], worker_dir / "slow_enqueue.log", environment)
+    _run([*prefix, "drain"], worker_dir / "slow_drain.log", environment)
+    _run(
+        [*prefix, "audit", scope_id, "--require-promotion-coverage"],
+        worker_dir / "slow_audit.log",
+        environment,
+    )
+
+
+def _parallel(
+    workers: Sequence[Mapping[str, Any]],
+    concurrency: int,
+    task: Any,
+    environments: Sequence[Mapping[str, str]],
+) -> None:
+    if concurrency <= 0:
+        raise BuildError("concurrency must be positive")
+    with ThreadPoolExecutor(max_workers=min(concurrency, len(workers))) as executor:
+        futures = {
+            executor.submit(task, worker, environment=environments[index]): str(worker["question_id"])
+            for index, worker in enumerate(workers)
+        }
+        for future in as_completed(futures):
+            future.result()
+
+
+def resume_build(args: argparse.Namespace) -> dict[str, Any]:
+    out_dir = args.out_dir.resolve()
+    if not out_dir.is_dir():
+        raise BuildError(f"resume output directory does not exist: {out_dir}")
+    if (out_dir / "BUILD_COMPLETE").exists():
+        raise BuildError("resume output is already complete")
+    manifest = _load_resume_manifest(out_dir)
+    expected_qids = [
+        line.strip()
+        for line in args.qid_list.resolve().read_text(encoding="utf-8").splitlines()
+        if line.strip()
+    ]
+    if expected_qids != list(manifest.get("qids") or []):
+        raise BuildError("resume qid list does not match the frozen input manifest")
+    shell_environment = _load_shell_environment(args.writer_env.resolve())
+    base_environment = {**os.environ, **shell_environment}
+    keys = _key_pool(base_environment)
+    workers = list(manifest["workers"])
+    environments = [
+        _worker_environment(base_environment, keys, index)
+        for index in range(len(workers))
+    ]
+    try:
+        incomplete_workers: list[Mapping[str, Any]] = []
+        for worker in workers:
+            try:
+                _verify_resume_writer(worker)
+            except BuildError:
+                incomplete_workers.append(worker)
+        if incomplete_workers:
+            if not getattr(args, "revalidate_failed_writer_raw_response", False):
+                raise BuildError(
+                    "resume has incomplete writer workers; explicit raw-response "
+                    "revalidation flag is required: "
+                    + json.dumps(
+                        [str(worker["question_id"]) for worker in incomplete_workers]
+                    )
+                )
+            interrupted = [
+                call
+                for worker in incomplete_workers
+                for call in _interrupted_writer_calls(worker)
+            ]
+            if interrupted and not getattr(
+                args, "recover_interrupted_api_calls", False
+            ):
+                raise BuildError(
+                    "resume has started calls without durable responses; explicit "
+                    "process-loss recovery flag is required: "
+                    + json.dumps(interrupted, sort_keys=True)
+                )
+            _stage(
+                out_dir,
+                "writer_resume_started",
+                workers=len(incomplete_workers),
+                interrupted_calls=len(interrupted),
+            )
+            selected_environments = [
+                environments[workers.index(worker)] for worker in incomplete_workers
+            ]
+            _parallel(
+                incomplete_workers,
+                args.writer_concurrency,
+                lambda worker, environment: _writer_worker_resume(
+                    worker,
+                    repo=args.repo.resolve(),
+                    environment=environment,
+                    recover_interrupted_api_calls=bool(interrupted),
+                ),
+                selected_environments,
+            )
+            for worker in workers:
+                _verify_resume_writer(worker)
+            _stage(out_dir, "writer_resume_complete")
+        _stage(out_dir, "subject_attribution_started", resumed=True)
+        _subject_attribution_stage(out_dir, base_environment)
+        interrupted_slow = [
+            call for worker in workers for call in _interrupted_slow_calls(worker)
+        ]
+        if interrupted_slow and not getattr(
+            args, "recover_interrupted_slow_calls", False
+        ):
+            raise BuildError(
+                "resume has Slow calls without durable responses; explicit "
+                "--recover-interrupted-slow-calls is required: "
+                + json.dumps(interrupted_slow, sort_keys=True)
+            )
+        _stage(
+            out_dir,
+            "resume_started",
+            row_count=len(workers),
+            interrupted_slow_calls=len(interrupted_slow),
+        )
+        _parallel(
+            workers,
+            args.slow_concurrency,
+            lambda worker, environment: _slow_worker_resume(
+                worker,
+                repo=args.repo.resolve(),
+                environment=environment,
+                recover_interrupted_slow_calls=bool(interrupted_slow),
+            ),
+            environments,
+        )
+        _stage(out_dir, "slow_graph_complete", resumed=True)
+        runtime_environment = dict(base_environment)
+        runtime_environment["TMCRA_NODE_MODEL_DEVICE"] = args.device
+        _run(
+            [
+                sys.executable,
+                str(BASE / "tmcra_v4_online_runtime.py"),
+                "build-index",
+                "--scope-manifest",
+                str(out_dir / "scope_manifest.jsonl"),
+                "--out-report",
+                str(out_dir / "index_report.json"),
+                "--embedding-model",
+                str(args.embedding_model.resolve()),
+                "--device",
+                args.device,
+                "--batch-size",
+                str(args.index_batch_size),
+            ],
+            _resume_log(out_dir, "index"),
+            runtime_environment,
+        )
+        _stage(out_dir, "index_complete", resumed=True)
+        _run(
+            [
+                sys.executable,
+                str(BASE / "audit_tmcra_v4_chain.py"),
+                "--run-dir",
+                str(out_dir),
+                "--output",
+                str(out_dir / "build_chain_audit.json"),
+                "--build-only",
+            ],
+            _resume_log(out_dir, "build_chain_audit"),
+            runtime_environment,
+        )
+        _stage(out_dir, "build_audit_complete", resumed=True)
+        return _finalize_build(
+            out_dir=out_dir,
+            workers=workers,
+            writer_concurrency=args.writer_concurrency,
+            slow_concurrency=args.slow_concurrency,
+            recovered=True,
+        )
+    except Exception as exc:
+        _record_failure(out_dir, exc)
+        raise
+
+
+def build(args: argparse.Namespace) -> dict[str, Any]:
+    if getattr(args, "resume", False):
+        return resume_build(args)
+    out_dir = args.out_dir.resolve()
+    if out_dir.exists():
+        raise BuildError(f"output directory already exists: {out_dir}")
+    manifest = prepare(
+        data_path=args.data.resolve(),
+        qid_path=args.qid_list.resolve(),
+        out_dir=out_dir,
+    )
+    _stage(out_dir, "prepared", rows=manifest["row_count"])
+    shell_environment = _load_shell_environment(args.writer_env.resolve())
+    base_environment = {**os.environ, **shell_environment}
+    keys = _key_pool(base_environment)
+    workers = list(manifest["workers"])
+    environments = [
+        _worker_environment(base_environment, keys, index) for index in range(len(workers))
+    ]
+    try:
+        _stage(out_dir, "writer_started", concurrency=args.writer_concurrency)
+        _parallel(
+            workers,
+            args.writer_concurrency,
+            lambda worker, environment: _writer_worker(
+                worker, repo=args.repo.resolve(), environment=environment
+            ),
+            environments,
+        )
+        _stage(out_dir, "writer_complete")
+        _stage(out_dir, "subject_attribution_started")
+        _subject_attribution_stage(out_dir, base_environment)
+        _stage(out_dir, "slow_graph_started", concurrency=args.slow_concurrency)
+        _parallel(
+            workers,
+            args.slow_concurrency,
+            lambda worker, environment: _slow_worker(
+                worker, repo=args.repo.resolve(), environment=environment
+            ),
+            environments,
+        )
+        _stage(out_dir, "slow_graph_complete")
+        runtime_environment = dict(base_environment)
+        runtime_environment["TMCRA_NODE_MODEL_DEVICE"] = args.device
+        _run(
+            [
+                sys.executable,
+                str(BASE / "tmcra_v4_online_runtime.py"),
+                "build-index",
+                "--scope-manifest",
+                str(out_dir / "scope_manifest.jsonl"),
+                "--out-report",
+                str(out_dir / "index_report.json"),
+                "--embedding-model",
+                str(args.embedding_model.resolve()),
+                "--device",
+                args.device,
+                "--batch-size",
+                str(args.index_batch_size),
+            ],
+            out_dir / "index.log",
+            runtime_environment,
+        )
+        _stage(out_dir, "index_complete")
+        _run(
+            [
+                sys.executable,
+                str(BASE / "audit_tmcra_v4_chain.py"),
+                "--run-dir",
+                str(out_dir),
+                "--output",
+                str(out_dir / "build_chain_audit.json"),
+                "--build-only",
+            ],
+            out_dir / "build_chain_audit.log",
+            runtime_environment,
+        )
+        return _finalize_build(
+            out_dir=out_dir,
+            workers=workers,
+            writer_concurrency=args.writer_concurrency,
+            slow_concurrency=args.slow_concurrency,
+            recovered=False,
+        )
+    except Exception as exc:
+        _record_failure(out_dir, exc)
+        raise
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Build a frozen TMCRA V4 memory corpus")
+    parser.add_argument("--out-dir", type=Path, required=True)
+    parser.add_argument("--qid-list", type=Path, required=True)
+    parser.add_argument("--data", type=Path, default=DEFAULT_DATA)
+    parser.add_argument("--repo", type=Path, default=DEFAULT_REPO)
+    parser.add_argument("--writer-env", type=Path, default=DEFAULT_WRITER_ENV)
+    parser.add_argument("--embedding-model", type=Path, default=DEFAULT_EMBEDDING)
+    parser.add_argument("--writer-concurrency", type=int, default=1)
+    parser.add_argument("--slow-concurrency", type=int, default=1)
+    parser.add_argument("--index-batch-size", type=int, default=16)
+    parser.add_argument("--device", default="cuda")
+    parser.add_argument(
+        "--resume",
+        action="store_true",
+        help="resume a frozen incomplete build after explicit failed-job review",
+    )
+    parser.add_argument(
+        "--revalidate-failed-writer-raw-response",
+        action="store_true",
+        help="explicitly revalidate one saved clean writer response per failed worker",
+    )
+    parser.add_argument(
+        "--recover-interrupted-api-calls",
+        action="store_true",
+        help=(
+            "after explicit process-loss review, replace started writer calls "
+            "that have no durable response using the same model"
+        ),
+    )
+    parser.add_argument(
+        "--recover-interrupted-slow-calls",
+        action="store_true",
+        help=(
+            "after explicit review, journal expired Slow attempts with unknown "
+            "external outcomes and reopen only those jobs"
+        ),
+    )
+    args = parser.parse_args()
+    report = build(args)
+    print(json.dumps(report, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

benchmarks/longmemeval/src/tmcra_benchmark/legacy/run_tmcra_v4_compile_evidence.py

@@ -0,0 +1,1015 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import re
+import threading
+import time
+from collections.abc import Mapping, Sequence
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from pathlib import Path
+from typing import Any
+
+from run_tmcra_v4_build import DEFAULT_WRITER_ENV, _key_pool, _load_shell_environment
+from tmcra_v4_evidence_operations import (
+    PACKET_COMPILER_VERSION,
+    PACKET_SCHEMA,
+    PLAN_SCHEMA,
+    build_evidence_catalog,
+    compile_evidence_packet,
+    operation_plan_structural_risks,
+    unbound_memory_requirement_ids,
+    validate_operation_plan,
+)
+from tmcra_v4_evidence_planner import (
+    DeepSeekEvidenceOperationPlanner,
+    EvidencePlannerError,
+    PROMPT_VERSION as EVIDENCE_PLANNER_PROMPT_VERSION,
+    normalize_planner_output,
+)
+from tmcra_v4_route_policy import (
+    RoutePolicyError,
+    validate_diagnostic_retrieval_rows,
+    validate_production_retrieval_rows,
+)
+
+
+class EvidenceCompileError(RuntimeError):
+    pass
+
+
+ARTIFACT_BINDING_SCHEMA = "tmcra.v4.evidence-compiler-artifact-binding.1"
+REVIEW_POLICY_VERSION = "tmcra.v4.evidence-review-policy.4"
+
+
+def _text(value: Any) -> str:
+    return value.strip() if isinstance(value, str) else ""
+
+
+def _read_jsonl(path: Path) -> list[dict[str, Any]]:
+    return [json.loads(line) for line in path.read_text(encoding="utf-8").splitlines() if line.strip()]
+
+
+def _retrieval_debug_report(
+    path: Path,
+    expected_qids: Sequence[str],
+) -> dict[str, Any]:
+    if not path.is_file():
+        raise EvidenceCompileError(f"retrieval debug is missing: {path}")
+    raw = path.read_bytes()
+    try:
+        rows = [
+            json.loads(line)
+            for line in raw.decode("utf-8").splitlines()
+            if line.strip()
+        ]
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise EvidenceCompileError(f"retrieval debug is invalid JSONL: {path}") from exc
+    actual_qids = [
+        _text(row.get("question_id") or row.get("qid"))
+        if isinstance(row, Mapping)
+        else ""
+        for row in rows
+    ]
+    if actual_qids != list(expected_qids):
+        raise EvidenceCompileError(
+            "retrieval debug rows do not match frozen evidence qid order"
+        )
+    return {
+        "schema_version": "tmcra.v4.compiled-retrieval-debug-binding.1",
+        "source_path": str(path),
+        "row_count": len(rows),
+        "source_sha256": hashlib.sha256(raw).hexdigest(),
+    }
+
+
+def _stage_retrieval_debug(
+    source: Path,
+    out_dir: Path,
+    expected_qids: Sequence[str],
+    *,
+    expected_sha256: str,
+) -> dict[str, Any]:
+    report = _retrieval_debug_report(source, expected_qids)
+    if report["source_sha256"] != expected_sha256:
+        raise EvidenceCompileError("retrieval debug changed during evidence compilation")
+    raw = source.read_bytes()
+    destination = out_dir / "retrieval_debug.jsonl"
+    temporary = destination.with_name(
+        f".{destination.name}.tmp.{os.getpid()}.{time.time_ns()}"
+    )
+    temporary.write_bytes(raw)
+    os.replace(temporary, destination)
+    artifact_sha256 = hashlib.sha256(destination.read_bytes()).hexdigest()
+    if artifact_sha256 != expected_sha256:
+        raise EvidenceCompileError("staged retrieval debug failed its integrity check")
+    return {
+        **report,
+        "artifact_path": destination.name,
+        "artifact_sha256": artifact_sha256,
+        "status": "staged",
+    }
+
+
+def _atomic_json(path: Path, value: Mapping[str, Any]) -> None:
+    temporary = path.with_name(f".{path.name}.tmp.{os.getpid()}.{time.time_ns()}")
+    temporary.write_text(json.dumps(dict(value), ensure_ascii=False, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    os.replace(temporary, path)
+
+
+def _atomic_jsonl(path: Path, rows: Sequence[Mapping[str, Any]]) -> None:
+    temporary = path.with_name(f".{path.name}.tmp.{os.getpid()}.{time.time_ns()}")
+    temporary.write_text("".join(json.dumps(dict(row), ensure_ascii=False, sort_keys=True) + "\n" for row in rows), encoding="utf-8")
+    os.replace(temporary, path)
+
+
+def _append_jsonl_atomic(path: Path, row: Mapping[str, Any]) -> None:
+    rows = _read_jsonl(path) if path.is_file() else []
+    rows.append(dict(row))
+    _atomic_jsonl(path, rows)
+
+
+def _identity(row: Mapping[str, Any]) -> str:
+    payload = {
+        "question_id": row.get("question_id"),
+        "question": row.get("question"),
+        "question_date": row.get("question_date"),
+        "evidence_windows": row.get("evidence_windows"),
+        # Retrieval is part of the compiler input. In particular, a diagnostic
+        # row must never collide with a production row for the same question.
+        "retrieval_contract": row.get("retrieval_contract"),
+    }
+    return hashlib.sha256(json.dumps(payload, ensure_ascii=False, sort_keys=True, separators=(",", ":")).encode("utf-8")).hexdigest()
+
+
+def _planner_contract(
+    *,
+    provider: str,
+    model: str,
+    review_policy_version: str = REVIEW_POLICY_VERSION,
+) -> dict[str, Any]:
+    return {
+        "provider": provider,
+        "model": model,
+        "prompt_version": EVIDENCE_PLANNER_PROMPT_VERSION,
+        "review_policy_version": review_policy_version,
+        "plan_schema": PLAN_SCHEMA,
+    }
+
+
+def _packet_compiler_contract(*, compiler_version: str = PACKET_COMPILER_VERSION) -> dict[str, Any]:
+    return {
+        "packet_schema": PACKET_SCHEMA,
+        "compiler_version": compiler_version,
+    }
+
+
+def _artifact_binding(
+    row: Mapping[str, Any],
+    *,
+    provider: str,
+    model: str,
+    compiler_version: str = PACKET_COMPILER_VERSION,
+    review_policy_version: str = REVIEW_POLICY_VERSION,
+) -> dict[str, Any]:
+    return {
+        "schema_version": ARTIFACT_BINDING_SCHEMA,
+        "input_sha256": _identity(row),
+        "input": {
+            "question_id": row.get("question_id"),
+            "question": row.get("question"),
+            "question_date": row.get("question_date"),
+            "evidence_windows": row.get("evidence_windows"),
+            "retrieval_route_contract": row.get("retrieval_contract"),
+        },
+        "planner": _planner_contract(
+            provider=provider,
+            model=model,
+            review_policy_version=review_policy_version,
+        ),
+        "packet_compiler": _packet_compiler_contract(compiler_version=compiler_version),
+    }
+
+
+def _binding_sha256(binding: Mapping[str, Any]) -> str:
+    return hashlib.sha256(
+        json.dumps(dict(binding), ensure_ascii=False, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    ).hexdigest()
+
+
+def _saved_binding(
+    saved: Mapping[str, Any],
+    saved_row: Mapping[str, Any],
+) -> dict[str, Any]:
+    binding = saved.get("artifact_binding")
+    if isinstance(binding, Mapping):
+        return dict(binding)
+    planner = saved.get("planner")
+    if not isinstance(planner, Mapping):
+        raise EvidenceCompileError("completed artifact lacks its planner contract")
+    provider = _text(planner.get("provider"))
+    model = _text(planner.get("model"))
+    if not provider or not model:
+        raise EvidenceCompileError("completed artifact lacks its planner provider/model binding")
+    packet = saved_row.get("compiled_evidence_packet")
+    persisted_plan_schema = (
+        packet.get("operation_plan", {}).get("schema_version")
+        if isinstance(packet, Mapping)
+        and isinstance(packet.get("operation_plan"), Mapping)
+        else None
+    )
+    if persisted_plan_schema != PLAN_SCHEMA:
+        raise EvidenceCompileError("completed artifact planner contract schema is stale")
+    # Legacy artifacts did not persist this envelope. Reconstructing it is
+    # safe only from the persisted row and planner metadata; both are checked
+    # against the current invocation before reuse.
+    packet_compiler_version = (
+        _text(packet.get("packet_compiler_version"))
+        if isinstance(packet, Mapping)
+        else ""
+    )
+    return _artifact_binding(
+        saved_row,
+        provider=provider,
+        model=model,
+        compiler_version=packet_compiler_version or "legacy-unknown",
+        review_policy_version=(
+            _text(planner.get("review_policy_version")) or "legacy-unknown"
+        ),
+    )
+
+
+def _assert_artifact_binding(
+    saved: Mapping[str, Any],
+    row: Mapping[str, Any],
+    *,
+    input_sha256: str,
+    expected_binding: Mapping[str, Any],
+) -> None:
+    saved_row = saved.get("row")
+    if not isinstance(saved_row, Mapping):
+        raise EvidenceCompileError("completed artifact lacks its persisted input row")
+    if _identity(saved_row) != input_sha256:
+        raise EvidenceCompileError("persisted compiler identity mismatch")
+    current_binding = dict(expected_binding)
+    persisted_binding = _saved_binding(saved, saved_row)
+    if persisted_binding.get("schema_version") not in {None, ARTIFACT_BINDING_SCHEMA}:
+        raise EvidenceCompileError("completed artifact binding schema is stale")
+    if persisted_binding.get("input_sha256") != input_sha256:
+        raise EvidenceCompileError("persisted compiler identity mismatch")
+    if persisted_binding.get("input") != current_binding.get("input"):
+        raise EvidenceCompileError("completed artifact input contract mismatch")
+    if persisted_binding.get("planner") != current_binding.get("planner"):
+        raise EvidenceCompileError("completed artifact planner contract/provider/model mismatch")
+    persisted_packet_contract = persisted_binding.get("packet_compiler")
+    current_packet_contract = current_binding.get("packet_compiler")
+    if not isinstance(persisted_packet_contract, Mapping) or not isinstance(current_packet_contract, Mapping):
+        raise EvidenceCompileError("completed artifact packet compiler contract is missing")
+    if persisted_packet_contract.get("packet_schema") != current_packet_contract.get("packet_schema"):
+        raise EvidenceCompileError("completed artifact packet schema contract mismatch")
+    if row.get("retrieval_contract") != saved_row.get("retrieval_contract"):
+        raise EvidenceCompileError("completed artifact retrieval route contract mismatch")
+
+    persisted_packet = saved_row.get("compiled_evidence_packet")
+    if isinstance(persisted_packet, Mapping) and persisted_packet.get("schema_version") != PACKET_SCHEMA:
+        raise EvidenceCompileError("completed artifact packet schema is stale")
+
+
+def _cost_cny(calls: Sequence[Mapping[str, Any]]) -> float | None:
+    if any(call.get("provider") != "deepseek" for call in calls):
+        return None
+    total = 0.0
+    for call in calls:
+        usage = dict(call.get("usage") or {})
+        total += (
+            int(usage.get("prompt_cache_miss_tokens", 0)) * 3.0
+            + int(usage.get("completion_tokens", 0)) * 6.0
+            + int(usage.get("prompt_cache_hit_tokens", 0)) * 0.025
+        ) / 1_000_000.0
+    return round(total, 8)
+
+
+def _physical_calls(values: Sequence[Mapping[str, Any]]) -> list[dict[str, Any]]:
+    calls: dict[str, dict[str, Any]] = {}
+
+    def visit(value: Any) -> None:
+        if not isinstance(value, Mapping):
+            return
+        for key in ("calls", "prior_calls"):
+            nested = value.get(key)
+            if isinstance(nested, Sequence) and not isinstance(nested, (str, bytes)):
+                for item in nested:
+                    visit(item)
+        call_id = _text(value.get("physical_call_id"))
+        if value.get("physical_api_call") is True and call_id:
+            calls.setdefault(call_id, dict(value))
+
+    for value in values:
+        visit(value)
+    return list(calls.values())
+
+
+def _aggregate_planner_calls(calls: Sequence[Mapping[str, Any]]) -> dict[str, Any]:
+    if not calls:
+        raise EvidenceCompileError("planner call list is empty")
+    usage_keys = ("prompt_tokens", "completion_tokens", "prompt_cache_hit_tokens", "prompt_cache_miss_tokens", "total_tokens")
+    usage = {key: sum(int((call.get("usage") or {}).get(key, 0)) for call in calls) for key in usage_keys}
+    return {
+        **dict(calls[-1]),
+        "physical_api_calls": len(calls),
+        "usage": usage,
+        "review_applied": len(calls) > 1,
+        "calls": [dict(call) for call in calls],
+    }
+
+
+RELATIVE_EVENT_REFERENCE_PATTERN = re.compile(
+    r"\b(?:when|before|after)\b", re.IGNORECASE
+)
+RELATIVE_DISTANCE_PATTERN = re.compile(
+    r"\b(?:ago|before|after)\b", re.IGNORECASE
+)
+
+
+def _relative_event_anchor_review_needed(
+    plan: Mapping[str, Any], catalog: Mapping[str, Any] | None
+) -> bool:
+    if not isinstance(catalog, Mapping):
+        return False
+    question = _text(catalog.get("question"))
+    if not (
+        RELATIVE_EVENT_REFERENCE_PATTERN.search(question)
+        and RELATIVE_DISTANCE_PATTERN.search(question)
+    ):
+        return False
+    evidence_by_id = {
+        _text(item.get("evidence_id")): item
+        for item in catalog.get("evidence") or []
+        if isinstance(item, Mapping)
+    }
+    anchor_ids = [
+        _text(value)
+        for value in catalog.get("lexical_anchor_ids") or []
+        if _text(value) in evidence_by_id
+    ]
+    anchor_sessions = {
+        _text(evidence_by_id[evidence_id].get("session_id"))
+        for evidence_id in anchor_ids
+    }
+    if len(anchor_sessions - {""}) < 2:
+        return False
+    question_atom_ids = {
+        _text(item.get("atom_id"))
+        for item in catalog.get("atoms") or []
+        if isinstance(item, Mapping) and item.get("evidence_id") == "QUESTION"
+    }
+    for operation in plan.get("operations") or []:
+        if (
+            not isinstance(operation, Mapping)
+            or operation.get("operation_type") != "date_difference"
+            or not question_atom_ids.intersection(operation.get("input_atom_ids") or [])
+        ):
+            continue
+        bound_ids = {
+            _text(value) for value in operation.get("input_evidence_ids") or []
+        }
+        bound_sessions = {
+            _text(evidence_by_id[value].get("session_id"))
+            for value in bound_ids
+            if value in evidence_by_id
+        }
+        if any(
+            evidence_id not in bound_ids
+            and _text(evidence_by_id[evidence_id].get("session_id"))
+            not in bound_sessions
+            for evidence_id in anchor_ids
+        ):
+            return True
+    return False
+
+
+def _required_memory_premise_binding(
+    plan: Mapping[str, Any], catalog: Mapping[str, Any] | None
+) -> dict[str, Any] | None:
+    if not isinstance(catalog, Mapping):
+        return None
+    anchor_ids = {
+        _text(value)
+        for value in catalog.get("lexical_anchor_ids") or []
+        if _text(value)
+    }
+    if not anchor_ids:
+        return None
+    required_memory_ids = {
+        _text(premise.get("premise_id"))
+        for premise in (plan.get("task_contract") or {}).get("premises") or []
+        if isinstance(premise, Mapping)
+        and premise.get("source") == "memory"
+        and premise.get("necessity") == "required"
+        and _text(premise.get("premise_id"))
+    }
+    if not required_memory_ids:
+        return None
+    bound_ids = {
+        _text(value)
+        for requirement in plan.get("requirements") or []
+        if isinstance(requirement, Mapping)
+        and _text(requirement.get("requirement_id")) in required_memory_ids
+        for value in requirement.get("evidence_ids") or []
+        if _text(value)
+    }
+    if not bound_ids or bound_ids.intersection(anchor_ids):
+        return None
+    return {
+        "required_memory_requirement_ids": sorted(required_memory_ids),
+        "bound_evidence_ids": sorted(bound_ids),
+        "lexical_anchor_ids": sorted(anchor_ids),
+    }
+
+
+def _review_context_for_plan(
+    plan: Mapping[str, Any], catalog: Mapping[str, Any] | None = None
+) -> dict[str, Any] | None:
+    missing_requirement_ids = unbound_memory_requirement_ids(plan)
+    structural_risks = operation_plan_structural_risks(plan)
+    relative_event_anchor_risk = _relative_event_anchor_review_needed(plan, catalog)
+    memory_relevance_signal = _required_memory_premise_binding(plan, catalog)
+    review_reasons = [
+        *structural_risks,
+        *(["unbound_required_memory_premises"] if missing_requirement_ids else []),
+        *(["relative_event_anchor_not_bound"] if relative_event_anchor_risk else []),
+        *(
+            ["required_memory_premise_outside_query_anchors"]
+            if memory_relevance_signal
+            else []
+        ),
+    ]
+    if not review_reasons:
+        return None
+    relative_anchor_instruction = (
+        " This review has already established that another remembered event "
+        "is the relative-time endpoint. QUESTION is forbidden as a "
+        "date_difference input; bind at least two distinct Source event dates."
+        if relative_event_anchor_risk
+        else ""
+    )
+    memory_relevance_instruction = (
+        " The required memory premise is currently bound only to evidence that "
+        "falls outside the query's lexical anchors. Do not satisfy the memory "
+        "contract with an unrelated remembered detail. Reinspect the candidate "
+        "evidence, including user-authored Source text and source-group context, "
+        "and bind memory that materially constrains the answer target. Lexical "
+        "anchors are review candidates rather than a hard allowlist, so an "
+        "implicitly related memory may remain only when the rebuilt plan changes "
+        "the evidence binding or adds relevant corroborating evidence."
+        if memory_relevance_signal
+        else ""
+    )
+    hard_constraints: dict[str, Any] = {}
+    if relative_event_anchor_risk:
+        hard_constraints.update(
+            {
+                "forbidden_date_difference_evidence_ids": ["QUESTION"],
+                "minimum_distinct_source_event_anchors": 2,
+            }
+        )
+    if memory_relevance_signal:
+        hard_constraints["forbidden_required_memory_evidence_ids"] = list(
+            memory_relevance_signal["bound_evidence_ids"]
+        )
+    return {
+        "initial_plan": dict(plan),
+        "review_reasons": review_reasons,
+        "missing_requirement_ids": missing_requirement_ids,
+        "memory_premise_relevance_signal": memory_relevance_signal or {},
+        "hard_constraints": hard_constraints,
+        "instruction": (
+            "Rebuild the complete plan. Treat a missing state as a hypothesis, "
+            "not proof of absence; for memory-conditioned generation, bind the "
+            "remembered constraints instead of searching for a ready-made answer. "
+            "When a relative-time question names another remembered event with "
+            "when, before, or after, compare the distinct event anchors and do not "
+            "default to the question date unless the wording explicitly makes it "
+            "the comparison endpoint."
+            + relative_anchor_instruction
+            + memory_relevance_instruction
+        ),
+    }
+
+
+def _review_resolution_failure(
+    plan: Mapping[str, Any],
+    catalog: Mapping[str, Any] | None,
+    review_context: Mapping[str, Any] | None,
+) -> str:
+    reasons = set((review_context or {}).get("review_reasons") or [])
+    if (
+        "relative_event_anchor_not_bound" in reasons
+        and _relative_event_anchor_review_needed(plan, catalog)
+    ):
+        return (
+            "relative event-anchor review still binds QUESTION instead of "
+            "two distinct Source event anchors"
+        )
+    if "required_memory_premise_outside_query_anchors" in reasons:
+        current_signal = _required_memory_premise_binding(plan, catalog)
+        initial_signal = (review_context or {}).get(
+            "memory_premise_relevance_signal"
+        ) or {}
+        if current_signal and set(current_signal.get("bound_evidence_ids") or []) == set(
+            initial_signal.get("bound_evidence_ids") or []
+        ):
+            return (
+                "required memory-premise relevance review kept the same "
+                "out-of-anchor evidence binding"
+            )
+    return ""
+
+
+def _recover_plan_from_failure(
+    failure_path: Path,
+    *,
+    question_id: str,
+    input_sha256: str,
+    catalog: Mapping[str, Any],
+    expected_binding: Mapping[str, Any] | None = None,
+) -> tuple[dict[str, Any], dict[str, Any]] | None:
+    if not failure_path.is_file():
+        return None
+    persisted = json.loads(failure_path.read_text(encoding="utf-8"))
+    if (
+        persisted.get("question_id") != question_id
+        or persisted.get("input_sha256") != input_sha256
+    ):
+        raise EvidenceCompileError(
+            f"{question_id}: persisted compiler failure identity mismatch"
+        )
+    metadata = dict(persisted.get("planner") or {})
+    if _text(metadata.get("prompt_version")) != EVIDENCE_PLANNER_PROMPT_VERSION:
+        return None
+    if _text(metadata.get("review_policy_version")) != REVIEW_POLICY_VERSION:
+        return None
+    if expected_binding is not None:
+        expected_planner = expected_binding.get("planner")
+        if not isinstance(expected_planner, Mapping) or any(
+            metadata.get(field) != expected_planner.get(field)
+            for field in ("provider", "model", "prompt_version")
+        ):
+            return None
+    raw_plan = metadata.get("raw_plan")
+    if not isinstance(raw_plan, Mapping) and metadata.get(
+        "review_resolution_failed"
+    ):
+        review_context = metadata.get("review_context")
+        if isinstance(review_context, Mapping):
+            raw_plan = review_context.get("initial_plan")
+    if not isinstance(raw_plan, Mapping):
+        return None
+    try:
+        plan, warnings = normalize_planner_output(raw_plan, catalog)
+    except Exception:
+        # The journal is an optimization, not a permanent failure latch. A raw
+        # response that cannot satisfy the current contract must be replanned.
+        return None
+    return plan, {
+        **metadata,
+        "raw_plan": dict(raw_plan),
+        "recovered_from_persisted_raw_plan": True,
+        "normalization_warnings": warnings,
+    }
+
+
+def _replan_context_from_failure(
+    failure_path: Path,
+    *,
+    question_id: str,
+    input_sha256: str,
+    expected_binding: Mapping[str, Any] | None = None,
+    catalog: Mapping[str, Any] | None = None,
+) -> dict[str, Any] | None:
+    if not failure_path.is_file():
+        return None
+    persisted = json.loads(failure_path.read_text(encoding="utf-8"))
+    if (
+        persisted.get("question_id") != question_id
+        or persisted.get("input_sha256") != input_sha256
+    ):
+        raise EvidenceCompileError(
+            f"{question_id}: persisted compiler failure identity mismatch"
+        )
+    metadata = dict(persisted.get("planner") or {})
+    if _text(metadata.get("prompt_version")) != EVIDENCE_PLANNER_PROMPT_VERSION:
+        return None
+    if expected_binding is not None:
+        expected_planner = expected_binding.get("planner")
+        if not isinstance(expected_planner, Mapping) or any(
+            metadata.get(field) != expected_planner.get(field)
+            for field in ("provider", "model", "prompt_version")
+        ):
+            return None
+    raw_plan = metadata.get("raw_plan")
+    error = _text(persisted.get("error"))
+    if not isinstance(raw_plan, Mapping) or not error:
+        return None
+    candidate_memory_evidence_ids = [
+        _text(value)
+        for value in (catalog or {}).get("lexical_anchor_ids") or []
+        if _text(value)
+    ]
+    return {
+        "initial_plan": dict(raw_plan),
+        "review_reasons": ["persisted_plan_validation_failure"],
+        "prior_validation_error": error,
+        "candidate_memory_evidence_ids": candidate_memory_evidence_ids,
+        "instruction": (
+            "Rebuild the complete plan and correct the prior runtime contract "
+            f"validation failure: {error}. Inspect the supplied evidence again. "
+            "For memory-conditioned generation, bind at least one relevant "
+            "required memory preference, constraint, owned tools, or resources. "
+            "For recommendation or advice, a previously mentioned owned tool or "
+            "accessory that can directly address the target problem is a valid "
+            "memory premise. Do not choose an unrelated preference merely because "
+            "it is more explicit; the premise must share the target domain or "
+            "intended action with the current question. Reinspect the listed "
+            "candidate_memory_evidence_ids plus their user-authored Source and "
+            "source-group context, and bind the relevant parent Evidence ID. "
+            "The candidate list is a review hint, not a hard allowlist. If no "
+            "relevant memory is supportable, "
+            "preserve an unbound memory requirement instead of relabeling query "
+            "context as remembered evidence."
+        ),
+    }
+
+
+def _refresh_completed_artifact(
+    saved: Mapping[str, Any],
+    row: Mapping[str, Any],
+    *,
+    question_id: str,
+    input_sha256: str,
+    expected_binding: Mapping[str, Any] | None = None,
+) -> tuple[dict[str, Any], bool]:
+    if (
+        saved.get("question_id") != question_id
+    ):
+        raise EvidenceCompileError(
+            f"{question_id}: persisted compiler identity mismatch"
+        )
+    saved_row = saved.get("row")
+    if saved.get("input_sha256") != input_sha256 and (
+        not isinstance(saved_row, Mapping) or _identity(saved_row) != input_sha256
+    ):
+        raise EvidenceCompileError(
+            f"{question_id}: persisted compiler identity mismatch"
+        )
+    output = dict(saved)
+    if expected_binding is None:
+        persisted_binding = saved.get("artifact_binding")
+        planner = (
+            persisted_binding.get("planner")
+            if isinstance(persisted_binding, Mapping)
+            else saved.get("planner")
+        )
+        if not isinstance(planner, Mapping):
+            raise EvidenceCompileError(
+                f"{question_id}: completed artifact lacks its planner contract"
+            )
+        expected_binding = _artifact_binding(
+            row,
+            provider=_text(planner.get("provider")),
+            model=_text(planner.get("model")),
+        )
+    _assert_artifact_binding(
+        saved,
+        row,
+        input_sha256=input_sha256,
+        expected_binding=expected_binding,
+    )
+    planner_metadata = output.get("planner")
+    if (
+        not isinstance(planner_metadata, Mapping)
+        or _text(planner_metadata.get("prompt_version"))
+        != EVIDENCE_PLANNER_PROMPT_VERSION
+    ):
+        raise EvidenceCompileError(
+            f"{question_id}: completed artifact uses a stale evidence planner contract"
+        )
+    saved_row = output.get("row")
+    packet = saved_row.get("compiled_evidence_packet") if isinstance(saved_row, Mapping) else None
+    if not isinstance(packet, Mapping):
+        raise EvidenceCompileError(
+            f"{question_id}: completed artifact lacks a compiled evidence packet"
+        )
+    binding_changed = output.get("artifact_binding") != dict(expected_binding)
+    if packet.get("packet_compiler_version") == PACKET_COMPILER_VERSION:
+        if binding_changed:
+            output["artifact_binding"] = dict(expected_binding)
+            output["compiler_binding_sha256"] = _binding_sha256(expected_binding)
+        return output, binding_changed
+    plan = packet.get("operation_plan")
+    if not isinstance(plan, Mapping):
+        raise EvidenceCompileError(
+            f"{question_id}: completed artifact lacks its persisted operation plan"
+        )
+    output_row = dict(row)
+    output_row["compiled_evidence_packet"] = compile_evidence_packet(row, plan)
+    output["row"] = output_row
+    output["packet_compiler_version"] = PACKET_COMPILER_VERSION
+    output["artifact_binding"] = dict(expected_binding)
+    output["compiler_binding_sha256"] = _binding_sha256(expected_binding)
+    output["local_packet_recompile_count"] = int(
+        output.get("local_packet_recompile_count", 0)
+    ) + 1
+    return output, True
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Compile immutable TMCRA evidence into operation-bound answer packets")
+    parser.add_argument("--evidence", type=Path, required=True)
+    parser.add_argument("--out-dir", type=Path, required=True)
+    parser.add_argument("--qid-list", type=Path)
+    parser.add_argument(
+        "--retrieval-debug",
+        type=Path,
+        help="retrieval_debug.jsonl to bind into the compiled evaluation artifact",
+    )
+    parser.add_argument(
+        "--require-retrieval-debug",
+        action="store_true",
+        help="fail before planner calls unless retrieval debug is present and qid-aligned",
+    )
+    parser.add_argument("--writer-env", type=Path, default=DEFAULT_WRITER_ENV)
+    parser.add_argument("--workers", type=int, default=4)
+    parser.add_argument("--timeout", type=float, default=180.0)
+    parser.add_argument("--planner-provider", choices=("deepseek", "xiaomi_mimo"), default="deepseek")
+    parser.add_argument("--planner-model")
+    parser.add_argument("--planner-base-url")
+    parser.add_argument("--planner-key-file", type=Path)
+    parser.add_argument(
+        "--diagnostic",
+        action="store_true",
+        help="explicitly compile a diagnostic retrieval lane that cannot enter production evaluation",
+    )
+    args = parser.parse_args()
+    if args.workers <= 0:
+        raise EvidenceCompileError("workers must be positive")
+    rows = _read_jsonl(args.evidence.resolve())
+    if args.qid_list:
+        qids = [line.strip() for line in args.qid_list.read_text(encoding="utf-8").splitlines() if line.strip()]
+        by_qid = {_text(row.get("question_id")): row for row in rows}
+        if not qids or len(qids) != len(set(qids)) or any(qid not in by_qid for qid in qids):
+            raise EvidenceCompileError("qid list is empty, duplicated, or absent from evidence")
+        rows = [by_qid[qid] for qid in qids]
+    try:
+        route_report = (
+            validate_diagnostic_retrieval_rows(rows)
+            if args.diagnostic
+            else validate_production_retrieval_rows(rows)
+        )
+    except RoutePolicyError as exc:
+        raise EvidenceCompileError(
+            f"retrieval route failed before evidence planner calls: {exc}"
+        ) from exc
+    expected_qids = [_text(row.get("question_id")) for row in rows]
+    retrieval_debug_source = (
+        args.retrieval_debug.resolve()
+        if args.retrieval_debug
+        else args.evidence.resolve().parent / "retrieval_debug.jsonl"
+    )
+    retrieval_debug_preflight: dict[str, Any] | None = None
+    if retrieval_debug_source.is_file():
+        retrieval_debug_preflight = _retrieval_debug_report(
+            retrieval_debug_source,
+            expected_qids,
+        )
+    elif args.require_retrieval_debug:
+        raise EvidenceCompileError(
+            f"retrieval debug is required before planner calls: {retrieval_debug_source}"
+        )
+    if args.planner_provider == "deepseek":
+        environment = _load_shell_environment(args.writer_env.resolve())
+        keys = _key_pool(environment)
+        base_url = args.planner_base_url or environment.get("TMCRA_DEEPSEEK_WRITER_BASE_URL") or environment.get("TMCRA_WRITER_BASE_URL") or "https://api.deepseek.com/v1"
+        planner_model = args.planner_model or "deepseek-v4-pro"
+    else:
+        if not args.planner_key_file or not args.planner_key_file.is_file():
+            raise EvidenceCompileError("xiaomi_mimo requires --planner-key-file")
+        key = args.planner_key_file.read_text(encoding="utf-8").strip()
+        if not key:
+            raise EvidenceCompileError("planner key file is empty")
+        keys = [key]
+        base_url = args.planner_base_url or "https://api.xiaomimimo.com/v1"
+        planner_model = args.planner_model or "mimo-v2.5"
+    out_dir = args.out_dir.resolve()
+    journal_dir = out_dir / "rows"
+    journal_dir.mkdir(parents=True, exist_ok=True)
+    failure_history_path = out_dir / "planner_failure_history.jsonl"
+    lock = threading.Lock()
+
+    def compile_one(index: int, row: Mapping[str, Any]) -> dict[str, Any]:
+        qid = _text(row.get("question_id"))
+        identity = _identity(row)
+        binding = _artifact_binding(
+            row,
+            provider=args.planner_provider,
+            model=planner_model,
+        )
+        artifact = journal_dir / f"{index:06d}_{qid}.json"
+        failure_path = journal_dir / f"{index:06d}_{qid}.failure.json"
+        if artifact.is_file():
+            saved = json.loads(artifact.read_text(encoding="utf-8"))
+            refreshed, changed = _refresh_completed_artifact(
+                saved,
+                row,
+                question_id=qid,
+                input_sha256=identity,
+                expected_binding=binding,
+            )
+            if changed:
+                with lock:
+                    _atomic_json(artifact, refreshed)
+            return refreshed
+        catalog = build_evidence_catalog(row)
+        planner = DeepSeekEvidenceOperationPlanner(
+            base_url=base_url,
+            api_keys=[keys[index % len(keys)]],
+            timeout=args.timeout,
+            model=planner_model,
+            provider=args.planner_provider,
+        )
+        planner_calls: list[dict[str, Any]] = []
+        recovered_from_persisted_raw_plan = False
+        try:
+            persisted_replan_context = _replan_context_from_failure(
+                failure_path,
+                question_id=qid,
+                input_sha256=identity,
+                expected_binding=binding,
+                catalog=catalog,
+            )
+            recovered = _recover_plan_from_failure(
+                failure_path,
+                question_id=qid,
+                input_sha256=identity,
+                catalog=catalog,
+                expected_binding=binding,
+            )
+            if recovered is not None:
+                plan, recovered_metadata = recovered
+                recovered_from_persisted_raw_plan = True
+                planner_calls.append(recovered_metadata)
+            if not recovered_from_persisted_raw_plan:
+                plan, metadata = planner.plan(
+                    catalog,
+                    review_context=persisted_replan_context,
+                )
+                planner_calls.append(metadata)
+            review_context = _review_context_for_plan(plan, catalog)
+            if review_context is not None:
+                plan, review_metadata = planner.plan(
+                    catalog,
+                    review_context=review_context,
+                )
+                planner_calls.append(review_metadata)
+                review_failure = _review_resolution_failure(
+                    plan,
+                    catalog,
+                    review_context,
+                )
+                if review_failure:
+                    raise EvidencePlannerError(
+                        review_failure,
+                        metadata={
+                            **review_metadata,
+                            "review_resolution_failed": True,
+                            "review_context": review_context,
+                        },
+                    )
+            metadata = _aggregate_planner_calls(planner_calls)
+            metadata["review_policy_version"] = REVIEW_POLICY_VERSION
+            metadata["recovered_from_persisted_raw_plan"] = (
+                recovered_from_persisted_raw_plan
+            )
+            metadata["new_physical_api_calls_this_resume"] = len(planner_calls) - int(
+                recovered_from_persisted_raw_plan
+            )
+        except EvidencePlannerError as exc:
+            failure = {
+                "failure_id": f"ecf_{time.time_ns()}",
+                "observed_at": time.strftime("%Y-%m-%dT%H:%M:%S%z"),
+                "question_id": qid,
+                "input_sha256": identity,
+                "artifact_binding": binding,
+                "compiler_binding_sha256": _binding_sha256(binding),
+                "status": "failed",
+                "error": str(exc),
+                "planner": {
+                    **exc.metadata,
+                    "review_policy_version": REVIEW_POLICY_VERSION,
+                    **({"prior_calls": planner_calls} if planner_calls else {}),
+                },
+            }
+            with lock:
+                _atomic_json(failure_path, failure)
+                _append_jsonl_atomic(failure_history_path, failure)
+            raise
+        plan = validate_operation_plan(plan, catalog)
+        packet = compile_evidence_packet(row, plan)
+        output_row = dict(row)
+        output_row["compiled_evidence_packet"] = packet
+        result = {
+            "question_id": qid,
+            "input_sha256": identity,
+            "artifact_binding": binding,
+            "compiler_binding_sha256": _binding_sha256(binding),
+            "status": "completed",
+            "planner": metadata,
+            "row": output_row,
+        }
+        with lock:
+            _atomic_json(artifact, result)
+            failure_path.unlink(missing_ok=True)
+        return result
+
+    results: dict[str, dict[str, Any]] = {}
+    failures: list[dict[str, str]] = []
+    with ThreadPoolExecutor(max_workers=args.workers) as executor:
+        futures = {executor.submit(compile_one, index, row): _text(row.get("question_id")) for index, row in enumerate(rows)}
+        for future in as_completed(futures):
+            qid = futures[future]
+            try:
+                result = future.result()
+            except Exception as exc:
+                failures.append({"question_id": qid, "error": f"{exc.__class__.__name__}: {exc}"})
+            else:
+                results[qid] = result
+    if failures:
+        _atomic_json(out_dir / "failures.json", {"failures": failures})
+        raise EvidenceCompileError(f"evidence compilation failed for {len(failures)} rows")
+    ordered_results = [results[_text(row.get("question_id"))] for row in rows]
+    (out_dir / "failures.json").unlink(missing_ok=True)
+    ordered_rows = [item["row"] for item in ordered_results]
+    calls = [item["planner"] for item in ordered_results]
+    failure_history = _read_jsonl(failure_history_path) if failure_history_path.is_file() else []
+    completed_physical_calls = _physical_calls(calls)
+    all_physical_calls = _physical_calls(
+        [*calls, *(dict(item.get("planner") or {}) for item in failure_history)]
+    )
+    _atomic_jsonl(out_dir / "evidence_windows.jsonl", ordered_rows)
+    retrieval_debug_report = (
+        _stage_retrieval_debug(
+            retrieval_debug_source,
+            out_dir,
+            expected_qids,
+            expected_sha256=retrieval_debug_preflight["source_sha256"],
+        )
+        if retrieval_debug_preflight is not None
+        else {
+            "schema_version": "tmcra.v4.compiled-retrieval-debug-binding.1",
+            "status": "not_provided",
+        }
+    )
+    _atomic_json(
+        out_dir / "report.json",
+        {
+            "schema_version": "tmcra.v4.evidence-compiler-run.1",
+            "status": "complete",
+            "row_count": len(ordered_rows),
+            "physical_call_count": len(all_physical_calls),
+            "completed_artifact_physical_call_count": len(completed_physical_calls),
+            "failure_history_record_count": len(failure_history),
+            "locally_recompiled_row_count": sum(
+                int(item.get("local_packet_recompile_count", 0) > 0)
+                for item in ordered_results
+            ),
+            "packet_compiler_version": PACKET_COMPILER_VERSION,
+            "planner_provider": args.planner_provider,
+            "planner_model": planner_model,
+            "retrieval_route_report": route_report,
+            "retrieval_debug": retrieval_debug_report,
+            "operation_count": sum(len(row["compiled_evidence_packet"]["operation_results"]) for row in ordered_rows),
+            "requirement_count": sum(len(row["compiled_evidence_packet"]["requirement_coverage"]) for row in ordered_rows),
+            "structural_risk_count": sum(
+                len(row["compiled_evidence_packet"].get("structural_risk_signals") or [])
+                for row in ordered_rows
+            ),
+            "typed_semantics_accepted_count": sum(
+                len((row["compiled_evidence_packet"].get("typed_semantics_report") or {}).get("accepted") or [])
+                for row in ordered_rows
+            ),
+            "typed_semantics_rejected_count": sum(
+                len((row["compiled_evidence_packet"].get("typed_semantics_report") or {}).get("rejected") or [])
+                for row in ordered_rows
+            ),
+            "exact_cost_cny": _cost_cny(all_physical_calls),
+        },
+    )
+    (out_dir / "COMPILE_COMPLETE").write_text(time.strftime("%Y-%m-%dT%H:%M:%S%z") + "\n", encoding="utf-8")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

benchmarks/longmemeval/src/tmcra_benchmark/legacy/run_tmcra_v4_evaluate.py

@@ -0,0 +1,725 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from run_tmcra_v4_build import BASE, DEFAULT_DATA, _now, _resume_log, _run
+from run_tmcra_v4_retrieve import DEFAULT_HARNESS
+from tmcra_v4_route_policy import (
+    POLICY_SCHEMA,
+    PRODUCTION_ANSWER_MODEL,
+    PRODUCTION_ANSWER_PROTOCOL,
+    PRODUCTION_ANSWER_RUNNER,
+    PRODUCTION_LANE,
+    SOURCE_COVERAGE_TRACE_K,
+    RoutePolicyError,
+    assert_production_answer_runner,
+    validate_production_answers,
+    validate_production_evidence,
+)
+from tmcra_v4_regression_gate import (
+    DEFAULT_CASES as DEFAULT_REGRESSION_CASES,
+    evaluate_gate as evaluate_regression_gate,
+)
+
+
+PROJECT_ROOT = BASE.parents[2]
+PACKAGE_ROOT = BASE.parent
+DEFAULT_ANSWER_ENV = PROJECT_ROOT / "configs" / "answer.env"
+DEFAULT_JUDGE = PACKAGE_ROOT / "harness" / "evaluate_qa_official_judge.py"
+DEFAULT_ANSWER_RUNNER = BASE / PRODUCTION_ANSWER_RUNNER
+
+
+class EvaluationError(RuntimeError):
+    pass
+
+
+def _load_environment(path: Path) -> dict[str, str]:
+    if not path.is_file():
+        raise EvaluationError(f"answer environment file is missing: {path}")
+    result = subprocess.run(
+        ["bash", "-c", 'set -a; source "$1"; env -0', "tmcra-v4-answer-env", str(path)],
+        check=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+    )
+    output: dict[str, str] = {}
+    for entry in result.stdout.decode("utf-8").split("\0"):
+        if "=" in entry:
+            key, value = entry.split("=", 1)
+            output[key] = value
+    return output
+
+
+def _read_jsonl(path: Path) -> list[dict[str, Any]]:
+    return [
+        json.loads(line)
+        for line in path.read_text(encoding="utf-8").splitlines()
+        if line.strip()
+    ]
+
+
+def _source_top24_session_ids(
+    debug_row: Mapping[str, Any], qid: str
+) -> list[str]:
+    trace = debug_row.get("source_top24_candidates")
+    pool = debug_row.get("source_candidate_pool_trace")
+    candidate_count = debug_row.get("source_candidate_count")
+    trace_k = debug_row.get("source_coverage_trace_k")
+    if type(candidate_count) is not int or candidate_count <= 0:
+        raise EvaluationError(f"{qid}: Source candidate count is invalid")
+    if trace_k != SOURCE_COVERAGE_TRACE_K:
+        raise EvaluationError(
+            f"{qid}: Source coverage trace contract is not Top{SOURCE_COVERAGE_TRACE_K}"
+        )
+    if not isinstance(trace, list) or not trace:
+        raise EvaluationError(f"{qid}: Source Top24 coverage trace is missing")
+    if not isinstance(pool, list):
+        raise EvaluationError(f"{qid}: Source candidate pool trace is missing")
+    expected_trace_count = min(SOURCE_COVERAGE_TRACE_K, candidate_count)
+    if len(trace) != expected_trace_count:
+        raise EvaluationError(
+            f"{qid}: Source Top24 coverage trace has {len(trace)} rows; "
+            f"expected {expected_trace_count}"
+        )
+    if len(pool) != candidate_count:
+        raise EvaluationError(
+            f"{qid}: Source candidate pool trace has {len(pool)} rows; "
+            f"expected {candidate_count}"
+        )
+
+    def validate_trace_rows(
+        rows: list[Any], *, label: str
+    ) -> list[tuple[str, str, int, int, int]]:
+        identities: list[tuple[str, str, int, int, int]] = []
+        locations: set[tuple[str, int, int, int]] = set()
+        for expected_rank, item in enumerate(rows, 1):
+            if not isinstance(item, Mapping):
+                raise EvaluationError(f"{qid}: {label} row must be an object")
+            rank = item.get("rank")
+            if type(rank) is not int or rank != expected_rank:
+                raise EvaluationError(f"{qid}: {label} is malformed")
+            candidate_id = str(item.get("candidate_id") or "").strip()
+            session_id = str(item.get("session_id") or "").strip()
+            coordinates = (
+                item.get("session_index"),
+                item.get("parent_chunk_index"),
+                item.get("subchunk_index"),
+            )
+            if (
+                not candidate_id
+                or not session_id
+                or any(type(value) is not int or value < 0 for value in coordinates)
+            ):
+                raise EvaluationError(f"{qid}: {label} has an invalid identity")
+            location = (session_id, *coordinates)
+            # Candidate IDs are content-derived and can collide when a dataset
+            # repeats the same session/chunk at a different session_index. The
+            # physical occurrence coordinates remain the authoritative identity.
+            if location in locations:
+                raise EvaluationError(f"{qid}: {label} contains duplicate evidence")
+            locations.add(location)
+            identities.append((candidate_id, session_id, *coordinates))
+        return identities
+
+    top_identities = validate_trace_rows(trace, label="Source Top24 coverage trace")
+    pool_identities = validate_trace_rows(pool, label="Source candidate pool trace")
+    if top_identities != pool_identities[:expected_trace_count]:
+        raise EvaluationError(
+            f"{qid}: Source Top24 trace is not the exact candidate-pool prefix"
+        )
+    session_ids: list[str] = []
+    for item in trace:
+        session_ids.append(str(item["session_id"]).strip())
+    return list(dict.fromkeys(session_ids))
+
+
+def _validate_retrieval_debug_rows(
+    expected_qids: list[str], retrieval_debug: list[dict[str, Any]]
+) -> None:
+    actual_qids = [
+        str(row.get("question_id") or row.get("qid") or "").strip()
+        if isinstance(row, Mapping)
+        else ""
+        for row in retrieval_debug
+    ]
+    if actual_qids != expected_qids:
+        raise EvaluationError("retrieval debug rows do not match frozen qid order")
+    for qid, row in zip(expected_qids, retrieval_debug, strict=True):
+        _source_top24_session_ids(row, qid)
+
+
+def _reference_rows(value: Any, source: str = "reference") -> list[dict[str, Any]]:
+    if isinstance(value, list):
+        raw_rows = value
+    elif isinstance(value, Mapping):
+        raw_rows: Any = None
+        for key in ("questions", "data", "rows", "references"):
+            if key in value:
+                raw_rows = value[key]
+                break
+        if raw_rows is None and value and all(isinstance(item, Mapping) for item in value.values()):
+            raw_rows = [dict(item, qid=key) for key, item in value.items()]
+        if raw_rows is None and ("qid" in value or "question_id" in value):
+            raw_rows = [value]
+        if not isinstance(raw_rows, list):
+            raise EvaluationError(f"{source} must contain a list of rows")
+    else:
+        raise EvaluationError(f"{source} must be a JSON object or list")
+
+    rows: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    for index, raw_row in enumerate(raw_rows, 1):
+        if not isinstance(raw_row, Mapping):
+            raise EvaluationError(f"{source} row {index} must be an object")
+        qid_value = raw_row.get("qid")
+        question_id = raw_row.get("question_id")
+        if qid_value is not None and question_id is not None and str(qid_value).strip() != str(question_id).strip():
+            raise EvaluationError(f"{source} row {index} has disagreeing qid and question_id")
+        qid = str(qid_value or question_id or "").strip()
+        if not qid:
+            raise EvaluationError(f"{source} row {index} is missing qid")
+        if qid in seen:
+            raise EvaluationError(f"{source} contains duplicate qid {qid}")
+        session_ids = raw_row.get("answer_session_ids")
+        if not isinstance(session_ids, list) or not session_ids:
+            raise EvaluationError(f"{source} row {index} ({qid}) lacks answer_session_ids")
+        normalized_sessions = [str(item).strip() for item in session_ids]
+        if any(not item for item in normalized_sessions) or len(set(normalized_sessions)) != len(normalized_sessions):
+            raise EvaluationError(
+                f"{source} row {index} ({qid}) has blank or duplicate answer_session_ids"
+            )
+        gold_key = next(
+            (key for key in ("gold_answer", "answer", "expected_answer") if key in raw_row),
+            None,
+        )
+        if gold_key is None:
+            raise EvaluationError(f"{source} row {index} ({qid}) lacks a gold answer")
+        rows.append(
+            {
+                "qid": qid,
+                "gold_answer": raw_row[gold_key],
+                "answer_session_ids": normalized_sessions,
+                "question_type": str(
+                    raw_row.get("question_type") or raw_row.get("type") or "unknown"
+                ).strip()
+                or "unknown",
+            }
+        )
+        seen.add(qid)
+    if not rows:
+        raise EvaluationError(f"{source} is empty")
+    return rows
+
+
+def _read_reference(path: Path) -> list[dict[str, Any]]:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except OSError as exc:
+        raise EvaluationError(f"cannot read reference data: {exc}") from exc
+    except json.JSONDecodeError as exc:
+        raise EvaluationError("reference data is not valid JSON") from exc
+    return _reference_rows(value)
+
+
+def _build_evaluation_audit(
+    expected_qids: list[str],
+    reference: list[dict[str, Any]],
+    evidence: list[dict[str, Any]],
+    retrieval_debug: list[dict[str, Any]],
+    judged: list[dict[str, Any]],
+) -> list[dict[str, Any]]:
+    _validate_retrieval_debug_rows(expected_qids, retrieval_debug)
+    reference_by_qid = {row["qid"]: row for row in reference}
+    evidence_by_qid = {str(row.get("question_id") or row.get("qid") or "").strip(): row for row in evidence}
+    judged_by_qid = {str(row.get("question_id") or row.get("qid") or "").strip(): row for row in judged}
+    debug_by_qid = {
+        str(row.get("question_id") or row.get("qid") or "").strip(): row
+        for row in retrieval_debug
+    }
+    missing_reference = [qid for qid in expected_qids if qid not in reference_by_qid]
+    missing_evidence = [qid for qid in expected_qids if qid not in evidence_by_qid]
+    missing_judged = [qid for qid in expected_qids if qid not in judged_by_qid]
+    missing_debug = [qid for qid in expected_qids if qid not in debug_by_qid]
+    if missing_reference:
+        raise EvaluationError(f"reference is missing evaluated qids: {missing_reference[:10]}")
+    if missing_evidence:
+        raise EvaluationError(f"evidence is missing evaluated qids: {missing_evidence[:10]}")
+    if missing_judged:
+        raise EvaluationError(f"judge is missing evaluated qids: {missing_judged[:10]}")
+    if missing_debug:
+        raise EvaluationError(
+            f"retrieval debug is missing evaluated qids: {missing_debug[:10]}"
+        )
+
+    audit: list[dict[str, Any]] = []
+    for qid in expected_qids:
+        reference_row = reference_by_qid[qid]
+        selected = evidence_by_qid[qid].get("selected_session_ids")
+        if not isinstance(selected, list):
+            raise EvaluationError(f"{qid}: selected_session_ids must be a list")
+        selected_ids = [str(item).strip() for item in selected]
+        if any(not item for item in selected_ids) or len(set(selected_ids)) != len(selected_ids):
+            raise EvaluationError(f"{qid}: selected_session_ids has blank or duplicate values")
+        answer_ids = list(reference_row["answer_session_ids"])
+        source_top24_session_ids = _source_top24_session_ids(debug_by_qid[qid], qid)
+
+        def coverage(candidate_session_ids: list[str]) -> dict[str, Any]:
+            missing_ids = [
+                session_id
+                for session_id in answer_ids
+                if session_id not in set(candidate_session_ids)
+            ]
+            return {
+                "complete": not missing_ids,
+                "expected_session_count": len(answer_ids),
+                "selected_session_count": len(candidate_session_ids),
+                "covered_session_count": len(answer_ids) - len(missing_ids),
+                "hit_rate": round(
+                    (len(answer_ids) - len(missing_ids)) / len(answer_ids), 6
+                ),
+                "missing_session_ids": missing_ids,
+            }
+
+        source_top24_coverage = coverage(source_top24_session_ids)
+        final_evidence_coverage = coverage(selected_ids)
+        official_label = official_judge_correct(judged_by_qid[qid])
+        audit.append(
+            {
+                "qid": qid,
+                "question_id": qid,
+                "question_type": reference_row["question_type"],
+                "gold_answer": reference_row["gold_answer"],
+                "gold_answer_session_ids": answer_ids,
+                "answer_session_ids": answer_ids,
+                "source_top24_session_ids": source_top24_session_ids,
+                "selected_session_ids": selected_ids,
+                "source_top24_coverage": source_top24_coverage,
+                "final_evidence_coverage": final_evidence_coverage,
+                "session_coverage": final_evidence_coverage,
+                "source_coverage_complete": source_top24_coverage["complete"],
+                "source_top24_coverage_complete": source_top24_coverage["complete"],
+                "final_evidence_coverage_complete": final_evidence_coverage["complete"],
+                "missing_source_top24_session_ids": source_top24_coverage[
+                    "missing_session_ids"
+                ],
+                "missing_session_ids": final_evidence_coverage["missing_session_ids"],
+                "missing_answer_session_ids": final_evidence_coverage[
+                    "missing_session_ids"
+                ],
+                "official_label": official_label,
+                "official_judge_label": official_label,
+                "official_correct": official_label,
+            }
+        )
+    return audit
+
+
+def _write_jsonl(path: Path, rows: list[Mapping[str, Any]]) -> None:
+    temporary = path.with_name(f".{path.name}.tmp.{os.getpid()}")
+    temporary.write_text(
+        "".join(json.dumps(dict(row), ensure_ascii=False, sort_keys=True) + "\n" for row in rows),
+        encoding="utf-8",
+    )
+    os.replace(temporary, path)
+
+
+def _validate_answer_facing_evidence(rows: list[dict[str, Any]]) -> None:
+    forbidden_fields = {
+        "answer",
+        "gold_answer",
+        "expected_answer",
+        "answer_session_ids",
+        "labels",
+        "supervision",
+    }
+    for row in rows:
+        qid = str(row.get("question_id") or "").strip() or "<unknown>"
+        leaked = sorted(forbidden_fields.intersection(row))
+        if leaked:
+            raise EvaluationError(
+                f"{qid}: answer-facing evidence contains benchmark fields: {', '.join(leaked)}"
+            )
+
+
+def official_judge_correct(row: Mapping[str, Any]) -> bool:
+    if str(row.get("error") or "").strip():
+        raise EvaluationError("official judge row contains an error")
+    autoeval = row.get("autoeval_label")
+    if not isinstance(autoeval, Mapping) or type(autoeval.get("label")) is not bool:
+        raise EvaluationError(
+            "official judge row lacks boolean autoeval_label.label"
+        )
+    return bool(autoeval["label"])
+
+
+def _validate_judge_resume_rows(
+    answers: list[dict[str, Any]], judged: list[dict[str, Any]]
+) -> None:
+    answer_qids = [str(row.get("question_id") or "").strip() for row in answers]
+    judged_qids = [str(row.get("question_id") or "").strip() for row in judged]
+    if judged_qids != answer_qids[: len(judged_qids)]:
+        raise EvaluationError("existing judge rows are not a frozen answer prefix")
+    answer_by_qid = {str(row["question_id"]): row for row in answers}
+    for row in judged:
+        qid = str(row.get("question_id") or "").strip()
+        answer = answer_by_qid[qid]
+        for key in ("question", "hypothesis", "evidence_sha256", "answer_model"):
+            if row.get(key) != answer.get(key):
+                raise EvaluationError(
+                    f"{qid}: existing judge row is bound to different answer evidence"
+                )
+
+
+def _archive_failure_marker(run_dir: Path, retrieval_tag: str) -> None:
+    marker = run_dir / f"FAILED.answer_{retrieval_tag}"
+    if not marker.is_file():
+        return
+    history = run_dir / f"answer_{retrieval_tag}.failure_history.jsonl"
+    with history.open("a", encoding="utf-8") as handle:
+        for line in marker.read_text(encoding="utf-8").splitlines():
+            if line.strip():
+                handle.write(line.rstrip() + "\n")
+    marker.unlink()
+
+
+def _record_failure(run_dir: Path, retrieval_tag: str, exc: Exception) -> None:
+    _archive_failure_marker(run_dir, retrieval_tag)
+    marker = run_dir / f"FAILED.answer_{retrieval_tag}"
+    temporary = marker.with_name(f".{marker.name}.tmp.{os.getpid()}")
+    temporary.write_text(
+        json.dumps({"at": _now(), "error": f"{exc.__class__.__name__}: {exc}"})
+        + "\n",
+        encoding="utf-8",
+    )
+    os.replace(temporary, marker)
+
+
+def evaluate(args: argparse.Namespace) -> dict[str, Any]:
+    run_dir = args.run_dir.resolve()
+    retrieval_dir = run_dir / args.retrieval_tag
+    if not any(
+        (retrieval_dir / marker).is_file()
+        for marker in ("RETRIEVAL_COMPLETE", "COMPILE_COMPLETE")
+    ):
+        raise EvaluationError("retrieval or evidence compilation run is incomplete")
+    answer_dir = run_dir / f"answer_{args.retrieval_tag}"
+    resume = bool(getattr(args, "resume", False))
+    failure_marker = run_dir / f"FAILED.answer_{args.retrieval_tag}"
+    judge_path = run_dir / f"{args.retrieval_tag}.official_judge.jsonl"
+    if answer_dir.exists() and not resume:
+        raise EvaluationError(f"answer output already exists: {answer_dir}")
+    if failure_marker.exists() and not resume:
+        raise EvaluationError("prior answer failure exists; use explicit --resume")
+    if resume and not (
+        answer_dir.exists() or failure_marker.exists() or judge_path.exists()
+    ):
+        raise EvaluationError("resume requested but no prior answer state exists")
+    try:
+        qid_list = Path(
+            getattr(args, "qid_list", None) or run_dir / "qids.txt"
+        ).resolve()
+        if not qid_list.is_file():
+            raise EvaluationError(f"answer qid list is missing: {qid_list}")
+        expected_qids = [
+            line.strip()
+            for line in qid_list.read_text(encoding="utf-8").splitlines()
+            if line.strip()
+        ]
+        if not expected_qids or len(expected_qids) != len(set(expected_qids)):
+            raise EvaluationError("answer qid list is empty or contains duplicates")
+        baseline_judge = getattr(args, "baseline_judge", None)
+        if baseline_judge is not None:
+            baseline_judge = Path(baseline_judge).resolve()
+            if not baseline_judge.is_file():
+                raise EvaluationError(
+                    f"frozen baseline judge is missing: {baseline_judge}"
+                )
+
+        try:
+            assert_production_answer_runner(args.answer_runner.resolve())
+            answer_facing_evidence = _read_jsonl(retrieval_dir / "evidence_windows.jsonl")
+            _validate_answer_facing_evidence(answer_facing_evidence)
+            route_report = validate_production_evidence(answer_facing_evidence)
+        except RoutePolicyError as exc:
+            raise EvaluationError(f"production route policy rejected the run: {exc}") from exc
+        if [item.get("question_id") for item in answer_facing_evidence] != expected_qids:
+            raise EvaluationError("evidence rows do not match frozen qid order")
+        retrieval_debug = _read_jsonl(retrieval_dir / "retrieval_debug.jsonl")
+        _validate_retrieval_debug_rows(expected_qids, retrieval_debug)
+
+        loaded = _load_environment(args.answer_env.resolve())
+        environment = {**os.environ, **loaded}
+        if environment.get("TMCRA_ANSWER_MODEL") != PRODUCTION_ANSWER_MODEL:
+            raise EvaluationError(
+                f"answer layer must remain fixed to {PRODUCTION_ANSWER_MODEL}"
+            )
+        _run(
+            [
+                sys.executable,
+                str(args.answer_runner.resolve()),
+                "--evidence",
+                str(retrieval_dir / "evidence_windows.jsonl"),
+                "--harness",
+                str(args.harness.resolve()),
+                "--out-dir",
+                str(answer_dir),
+                "--workers",
+                str(args.answer_workers),
+                "--attempts",
+                str(args.answer_attempts),
+                "--answer-window-limit",
+                str(args.answer_window_limit),
+                "--qid-list",
+                str(qid_list),
+                "--lane",
+                "production",
+            ],
+            (
+                _resume_log(run_dir, f"answer_{args.retrieval_tag}")
+                if resume
+                else run_dir / f"answer_{args.retrieval_tag}.log"
+            ),
+            environment,
+        )
+        answers = _read_jsonl(answer_dir / "answers.jsonl")
+        try:
+            validate_production_answers(answers)
+        except RoutePolicyError as exc:
+            raise EvaluationError(f"production route policy rejected answers: {exc}") from exc
+        if [item.get("question_id") for item in answers] != expected_qids:
+            raise EvaluationError("answer rows do not match frozen qid order")
+        judge_resume_options: list[str] = []
+        if judge_path.is_file():
+            if not resume:
+                raise EvaluationError("judge output already exists without --resume")
+            existing_judged = _read_jsonl(judge_path)
+            _validate_judge_resume_rows(answers, existing_judged)
+            judge_resume_options = ["--resume"]
+        _run(
+            [
+                sys.executable,
+                str(args.judge.resolve()),
+                "--metric-model",
+                "gpt-5.4",
+                "--hyp-file",
+                str(answer_dir / "answers.jsonl"),
+                "--ref-file",
+                str(args.data.resolve()),
+                "--result-file",
+                str(judge_path),
+                "--base-url",
+                environment["TMCRA_ANSWER_BASE_URL"],
+                "--api-key-env",
+                "TMCRA_ANSWER_API_KEY",
+                "--timeout",
+                "180",
+                "--max-retries",
+                "0",
+                *judge_resume_options,
+                "--quiet",
+            ],
+            (
+                _resume_log(run_dir, f"{args.retrieval_tag}.judge")
+                if resume
+                else run_dir / f"{args.retrieval_tag}.judge.log"
+            ),
+            environment,
+        )
+        judged = _read_jsonl(judge_path)
+        if [item.get("question_id") for item in answers] != expected_qids:
+            raise EvaluationError("answer rows do not match frozen qid order")
+        if [item.get("question_id") for item in judged] != expected_qids:
+            raise EvaluationError("judge rows do not match frozen qid order")
+        if any(item.get("answer_model") != PRODUCTION_ANSWER_MODEL for item in answers):
+            raise EvaluationError(f"answer output did not use {PRODUCTION_ANSWER_MODEL}")
+        labels = [official_judge_correct(item) for item in judged]
+        correct_count = sum(labels)
+        reference = _read_reference(args.data.resolve())
+        evaluation_audit = _build_evaluation_audit(
+            expected_qids,
+            reference,
+            answer_facing_evidence,
+            retrieval_debug,
+            judged,
+        )
+        evaluation_audit_path = answer_dir / "evaluation_audit.jsonl"
+        _write_jsonl(evaluation_audit_path, evaluation_audit)
+        source_complete_count = sum(
+            bool(row["source_top24_coverage_complete"]) for row in evaluation_audit
+        )
+        final_complete_count = sum(
+            bool(row["final_evidence_coverage_complete"]) for row in evaluation_audit
+        )
+        expected_gold_sessions = sum(
+            int(row["source_top24_coverage"]["expected_session_count"])
+            for row in evaluation_audit
+        )
+        source_covered_sessions = sum(
+            int(row["source_top24_coverage"]["covered_session_count"])
+            for row in evaluation_audit
+        )
+        final_covered_sessions = sum(
+            int(row["final_evidence_coverage"]["covered_session_count"])
+            for row in evaluation_audit
+        )
+        source_top24_hit_rate = (
+            source_covered_sessions / expected_gold_sessions
+            if expected_gold_sessions
+            else 0.0
+        )
+        final_evidence_hit_rate = (
+            final_covered_sessions / expected_gold_sessions
+            if expected_gold_sessions
+            else 0.0
+        )
+        accuracy = correct_count / len(judged) if judged else 0.0
+        evaluation_quality_gate_passed = (
+            source_top24_hit_rate == 1.0
+            and final_evidence_hit_rate >= 0.9
+            and accuracy >= 0.9
+        )
+        regression_gate_report: dict[str, Any] = {
+            "schema_version": "tmcra.v4.regression-gate-reference.1",
+            "status": "not_run",
+            "promotion_eligible": False,
+            "reason": "frozen baseline judge was not supplied",
+        }
+        if baseline_judge is not None:
+            regression_evidence_path = answer_dir / "source_top24_regression_evidence.jsonl"
+            _write_jsonl(
+                regression_evidence_path,
+                [
+                    {
+                        "qid": row["qid"],
+                        "question_id": row["question_id"],
+                        "selected_session_ids": row["source_top24_session_ids"],
+                    }
+                    for row in evaluation_audit
+                ],
+            )
+            regression_gate_report = evaluate_regression_gate(
+                baseline_judge,
+                judge_path,
+                regression_evidence_path,
+                args.data.resolve(),
+                cases_path=Path(
+                    getattr(args, "regression_cases", DEFAULT_REGRESSION_CASES)
+                ).resolve(),
+                min_candidate_accuracy=None,
+                max_regressions=0,
+                min_improvements=0,
+            )
+            (answer_dir / "v4_regression_gate_report.json").write_text(
+                json.dumps(regression_gate_report, indent=2, sort_keys=True) + "\n",
+                encoding="utf-8",
+            )
+        regression_gate_passed = bool(
+            regression_gate_report.get("promotion_eligible")
+        )
+        promotion_gate_passed = (
+            evaluation_quality_gate_passed and regression_gate_passed
+        )
+        summary = {
+            "schema_version": "tmcra.v4.evaluation.3",
+            "status": "complete",
+            "route_policy_schema": POLICY_SCHEMA,
+            "lane": PRODUCTION_LANE,
+            "answer_protocol": PRODUCTION_ANSWER_PROTOCOL,
+            "promotion_eligible": promotion_gate_passed,
+            "route_report": route_report,
+            "retrieval_tag": args.retrieval_tag,
+            "evaluated_count": len(judged),
+            "answer_model": PRODUCTION_ANSWER_MODEL,
+            "answer_attempt_limit": int(args.answer_attempts),
+            "judge_retry_limit": 0,
+            "judge_label_field": "autoeval_label.label",
+            "correct_count": correct_count,
+            "accuracy": round(accuracy, 6),
+            "evaluation_quality_gate_passed": evaluation_quality_gate_passed,
+            "promotion_gate": {
+                "passed": promotion_gate_passed,
+                "evaluation_quality_gate_passed": evaluation_quality_gate_passed,
+                "zero_api_regression_gate_passed": regression_gate_passed,
+                "source_top24_gold_session_hit_rate_min": 1.0,
+                "final_evidence_gold_session_hit_rate_min": 0.9,
+                "official_accuracy_min": 0.9,
+                "max_regressions": 0,
+            },
+            "regression_gate": regression_gate_report,
+            "evaluation_audit": {
+                "path": str(evaluation_audit_path),
+                "row_count": len(evaluation_audit),
+                "reference_row_count": len(reference),
+                "reference_is_superset": len(reference) >= len(expected_qids)
+                and set(expected_qids).issubset({row["qid"] for row in reference}),
+                "source_top24_coverage_complete_count": source_complete_count,
+                "source_top24_coverage_complete_rate": round(
+                    source_complete_count / len(evaluation_audit), 6
+                )
+                if evaluation_audit
+                else 0.0,
+                "source_top24_gold_session_hit_rate": round(
+                    source_top24_hit_rate, 6
+                ),
+                "final_evidence_coverage_complete_count": final_complete_count,
+                "final_evidence_coverage_complete_rate": round(
+                    final_complete_count / len(evaluation_audit), 6
+                )
+                if evaluation_audit
+                else 0.0,
+                "final_evidence_gold_session_hit_rate": round(
+                    final_evidence_hit_rate, 6
+                ),
+                "session_coverage_complete_count": final_complete_count,
+                "session_coverage_complete_rate": round(
+                    final_complete_count / len(evaluation_audit), 6
+                )
+                if evaluation_audit
+                else 0.0,
+            },
+        }
+        (answer_dir / "v4_evaluation_report.json").write_text(
+            json.dumps(summary, indent=2, sort_keys=True) + "\n", encoding="utf-8"
+        )
+        (answer_dir / "ANSWER_COMPLETE").write_text(_now() + "\n", encoding="utf-8")
+        _archive_failure_marker(run_dir, args.retrieval_tag)
+        return summary
+    except Exception as exc:
+        _record_failure(run_dir, args.retrieval_tag, exc)
+        raise
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Evaluate a completed TMCRA V4 retrieval run")
+    parser.add_argument("--run-dir", type=Path, required=True)
+    parser.add_argument("--retrieval-tag", default="retrieval_1")
+    parser.add_argument("--resume", action="store_true")
+    parser.add_argument("--answer-env", type=Path, default=DEFAULT_ANSWER_ENV)
+    parser.add_argument("--answer-runner", type=Path, default=DEFAULT_ANSWER_RUNNER)
+    parser.add_argument("--harness", type=Path, default=DEFAULT_HARNESS)
+    parser.add_argument("--judge", type=Path, default=DEFAULT_JUDGE)
+    parser.add_argument("--data", type=Path, default=DEFAULT_DATA)
+    parser.add_argument("--qid-list", type=Path)
+    parser.add_argument("--answer-workers", type=int, default=1)
+    parser.add_argument("--answer-attempts", type=int, choices=(1, 2, 3), default=1)
+    parser.add_argument("--answer-window-limit", type=int, default=8)
+    parser.add_argument("--baseline-judge", type=Path)
+    parser.add_argument(
+        "--regression-cases", type=Path, default=DEFAULT_REGRESSION_CASES
+    )
+    args = parser.parse_args()
+    summary = evaluate(args)
+    print(json.dumps(summary, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

benchmarks/longmemeval/src/tmcra_benchmark/legacy/run_tmcra_v4_gpt54_answers.py

@@ -0,0 +1,847 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import hashlib
+import importlib.util
+import json
+import os
+import sys
+import threading
+import time
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from pathlib import Path
+from typing import Any, Mapping
+
+from tmcra_v4_evidence_operations import (
+    ANSWER_SCHEMA,
+    PACKET_SCHEMA,
+    EvidenceOperationError,
+    validate_evidence_bound_answer,
+)
+from tmcra_v4_semantic_evidence import (
+    SEMANTIC_ANSWER_SCHEMA,
+    SEMANTIC_PACKET_SCHEMA,
+    SemanticEvidenceError,
+    normalize_semantic_answer_output,
+    semantic_packet_to_advisory_packet,
+    validate_semantic_answer,
+)
+from tmcra_v4_route_policy import (
+    PRODUCTION_ANSWER_PROTOCOL,
+    RoutePolicyError,
+    SHADOW_ANSWER_PROTOCOL,
+    validate_production_answers,
+    validate_production_evidence,
+)
+
+
+FORBIDDEN_EVALUATION_FIELDS = {
+    "answer",
+    "gold_answer",
+    "answer_session_ids",
+    "labels",
+    "supervision",
+}
+USER_MEMORY_CUE_LIMIT = 32
+USER_MEMORY_CUE_TEXT_LIMIT = 640
+
+
+def clean_text(value: Any) -> str:
+    return " ".join(str(value or "").split())
+
+
+def fixed_answer_environment(answer_window_limit: int) -> dict[str, str]:
+    return {
+        "TMCRA_ANSWER_WINDOW_PLANNER_MODE": "off",
+        "TMCRA_ANSWER_WINDOW_PLANNER_SEMANTIC_MODE": "off",
+        "TMCRA_LLM_EVIDENCE_SELECTOR_MODE": "off",
+        "TMCRA_EVIDENCE_UNIT_PLANNER_MODE": "off",
+        "TMCRA_UNIFIED_OPERATION_PLANNER_MODE": "off",
+        "TMCRA_LLM_CHANNEL_PLANNER_MODE": "off",
+        "TMCRA_FINAL_ANSWER_SURFACE_CHANNEL_MODE": "off",
+        "TMCRA_ANSWER_REASONING_ORGANIZER": "off",
+        "TMCRA_LLM_CACHE_MODE": "off",
+        "TMCRA_LME_FORCE_ANSWER": "1",
+        "TMCRA_HTTP_JSON_MAX_ATTEMPTS": "1",
+        "TMCRA_ANSWER_EVIDENCE_WINDOW_LIMIT": str(max(1, answer_window_limit)),
+    }
+
+
+def read_jsonl(path: Path) -> list[dict[str, Any]]:
+    rows: list[dict[str, Any]] = []
+    with path.open("r", encoding="utf-8", errors="strict") as handle:
+        for line_no, line in enumerate(handle, start=1):
+            if not line.strip():
+                continue
+            value = json.loads(line)
+            if not isinstance(value, dict):
+                raise RuntimeError(f"row is not an object at {path}:{line_no}")
+            rows.append(value)
+    if not rows:
+        raise RuntimeError(f"no rows: {path}")
+    return rows
+
+
+def evidence_sha256(row: Mapping[str, Any]) -> str:
+    return hashlib.sha256(
+        json.dumps(
+            dict(row), ensure_ascii=False, sort_keys=True, separators=(",", ":")
+        ).encode("utf-8")
+    ).hexdigest()
+
+
+def atomic_write_jsonl(path: Path, rows: list[Mapping[str, Any]]) -> None:
+    temporary = path.with_name(f".{path.name}.tmp.{os.getpid()}.{time.time_ns()}")
+    temporary.write_text(
+        "".join(json.dumps(dict(row), ensure_ascii=False, sort_keys=True) + "\n" for row in rows),
+        encoding="utf-8",
+    )
+    os.replace(temporary, path)
+
+
+def bind_existing_answers_to_evidence(
+    existing: dict[str, dict[str, Any]],
+    rows: list[dict[str, Any]],
+) -> tuple[dict[str, str], int]:
+    evidence_by_qid = {clean_text(row.get("question_id")): row for row in rows}
+    if not all(evidence_by_qid) or len(evidence_by_qid) != len(rows):
+        raise RuntimeError("answer evidence contains missing or duplicate question_id")
+    hashes = {qid: evidence_sha256(row) for qid, row in evidence_by_qid.items()}
+    backfills = 0
+    for qid, row in existing.items():
+        if qid not in evidence_by_qid:
+            continue
+        expected = evidence_by_qid[qid]
+        expected_hash = hashes[qid]
+        observed_hash = clean_text(row.get("evidence_sha256"))
+        if observed_hash and observed_hash != expected_hash:
+            raise RuntimeError(f"{qid}: existing answer is bound to different retrieval evidence")
+        if not observed_hash:
+            if (
+                clean_text(row.get("question")) != clean_text(expected.get("question"))
+                or list(row.get("selected_session_ids") or [])
+                != list(expected.get("selected_session_ids") or [])
+                or clean_text(row.get("answer_model")) != "gpt-5.4"
+            ):
+                raise RuntimeError(f"{qid}: legacy answer cannot be bound to current evidence")
+            row["evidence_sha256"] = expected_hash
+            backfills += 1
+    return hashes, backfills
+
+
+def ordered_completed_answers(
+    existing: Mapping[str, Mapping[str, Any]],
+    rows: list[Mapping[str, Any]],
+) -> list[dict[str, Any]]:
+    qids = [clean_text(row.get("question_id")) for row in rows]
+    if not all(qids) or len(qids) != len(set(qids)):
+        raise RuntimeError("answer evidence contains missing or duplicate question_id")
+    unexpected = sorted(set(existing) - set(qids))
+    if unexpected:
+        raise RuntimeError(
+            f"existing answer output contains qids outside the frozen request: {unexpected[:10]}"
+        )
+    return [dict(existing[qid]) for qid in qids if qid in existing]
+
+
+def load_harness(path: Path):
+    module_name = "tmcra_v3_answer_harness"
+    spec = importlib.util.spec_from_file_location(module_name, path)
+    if spec is None or spec.loader is None:
+        raise RuntimeError(f"cannot import answer harness: {path}")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[module_name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+def reject_evaluation_fields(rows: list[dict[str, Any]]) -> None:
+    for row in rows:
+        present = sorted(FORBIDDEN_EVALUATION_FIELDS.intersection(row))
+        if present:
+            qid = clean_text(row.get("question_id")) or "<missing-qid>"
+            raise RuntimeError(
+                f"{qid}: answer input contains evaluation-only fields: {present}"
+            )
+
+
+def render_hierarchical_evidence(window: Mapping[str, Any]) -> str:
+    source = clean_text(window.get("text"))
+    if not source:
+        raise RuntimeError("evidence window has empty source text")
+    blocks: list[str] = []
+    for context in list(window.get("memory_contexts") or []):
+        if not isinstance(context, Mapping):
+            raise RuntimeError("memory_context must be an object")
+        claim = clean_text(context.get("claim_text"))
+        slot = clean_text(context.get("canonical_slot"))
+        role = clean_text(context.get("role"))
+        if not claim or not slot or not role:
+            raise RuntimeError("memory_context lacks role, canonical_slot, or claim_text")
+        blocks.append(f"[TMCRA slow memory role={role} slot={slot}]\n{claim}")
+    for attachment in list(window.get("attachments") or []):
+        if not isinstance(attachment, Mapping):
+            raise RuntimeError("memory attachment must be an object")
+        role = clean_text(attachment.get("role"))
+        slot = clean_text(attachment.get("canonical_slot"))
+        if role == "context_only":
+            summary = clean_text(attachment.get("summary"))
+            if not summary or not slot:
+                raise RuntimeError("slow context attachment lacks slot or summary")
+            blocks.append(
+                f"[TMCRA slow memory role=context_only slot={slot}]\n{summary}"
+            )
+        elif role in {"fast_context", "override"}:
+            override_text = clean_text(attachment.get("text"))
+            if not override_text or not slot:
+                raise RuntimeError("fast memory attachment lacks slot or text")
+            if role == "override":
+                blocks.append(
+                    "[TMCRA fast memory role=override "
+                    f"precedence=newer_fast_evidence slot={slot}]\n"
+                    "This newer fast-layer evidence overrides conflicting slow-memory "
+                    f"claims.\n{override_text}"
+                )
+            else:
+                blocks.append(
+                    f"[TMCRA fast memory role=context slot={slot}]\n{override_text}"
+                )
+        else:
+            raise RuntimeError(f"unsupported memory attachment role: {role!r}")
+    blocks.append("[TMCRA immutable source evidence]\n" + source)
+    return "\n\n".join(blocks)
+
+
+def build_user_memory_cues(
+    evidence: list[Mapping[str, Any]],
+) -> list[dict[str, Any]]:
+    """Build a compact index of durable claims and user-authored evidence.
+
+    The index only points into the immutable Source reservoir. Round-robin
+    emission prevents an early, verbose source from hiding cues in later
+    retrieval windows.
+    """
+    cues_by_source: list[list[dict[str, Any]]] = []
+    for item in evidence:
+        evidence_id = clean_text(item.get("evidence_id"))
+        source_record_id = clean_text(item.get("source_record_id"))
+        source_cues: list[dict[str, Any]] = []
+
+        def add_cue(
+            kind: str,
+            text: Any,
+            *,
+            record_id: str = source_record_id,
+            historical_date: Any = None,
+            timestamp: Any = None,
+        ) -> None:
+            normalized = clean_text(text)
+            if not normalized:
+                return
+            source_cues.append(
+                {
+                    "evidence_id": evidence_id,
+                    "kind": kind,
+                    "source_record_id": record_id,
+                    "historical_date": clean_text(
+                        historical_date
+                        if historical_date is not None
+                        else item.get("historical_date")
+                    ),
+                    "timestamp": clean_text(
+                        timestamp if timestamp is not None else item.get("timestamp")
+                    ),
+                    "text": normalized[:USER_MEMORY_CUE_TEXT_LIMIT],
+                    "text_truncated": len(normalized) > USER_MEMORY_CUE_TEXT_LIMIT,
+                }
+            )
+
+        for context in list(item.get("memory_contexts") or []):
+            if isinstance(context, Mapping):
+                add_cue(
+                    "slow_claim",
+                    context.get("claim_text") or context.get("capsule_summary"),
+                )
+        for attachment in list(item.get("attachments") or []):
+            if isinstance(attachment, Mapping):
+                add_cue(
+                    "fast_memory",
+                    attachment.get("text") or attachment.get("summary"),
+                )
+        if clean_text(item.get("message_role")).lower() == "user":
+            add_cue("user_source", item.get("text"))
+        for context in list(item.get("source_group_context") or []):
+            if not isinstance(context, Mapping):
+                continue
+            role = clean_text(
+                context.get("message_role") or context.get("role")
+            ).lower()
+            if role == "user":
+                add_cue(
+                    "user_context",
+                    context.get("text"),
+                    record_id=clean_text(context.get("source_record_id")),
+                    historical_date=context.get("historical_date"),
+                    timestamp=context.get("timestamp"),
+                )
+        cues_by_source.append(source_cues)
+
+    output: list[dict[str, Any]] = []
+    seen_text: set[str] = set()
+    max_source_cues = max((len(items) for items in cues_by_source), default=0)
+    for cue_index in range(max_source_cues):
+        for source_cues in cues_by_source:
+            if cue_index >= len(source_cues):
+                continue
+            cue = source_cues[cue_index]
+            fingerprint = clean_text(cue["text"]).casefold()
+            if fingerprint in seen_text:
+                continue
+            seen_text.add(fingerprint)
+            output.append({"cue_order": len(output) + 1, **cue})
+            if len(output) >= USER_MEMORY_CUE_LIMIT:
+                return output
+    return output
+
+
+EVIDENCE_OPERATION_ANSWER_PROMPT = f"""You answer one memory question from a compiled, immutable evidence packet.
+Return exactly one JSON object and no prose using this schema:
+{{"schema_version":"{ANSWER_SCHEMA}","answerability":"sufficient|insufficient","claims":[{{"claim_id":"C01","text":"one factual claim","origin":"memory_fact|memory_inference|memory_derived|query_context|model_knowledge","support_ids":["E01"],"computation_ids":["O01"]}}],"missing_requirements":["R01"],"answer":"short complete answer"}}
+
+Read task_intent.output_origin before answering. task_intent and planner_source_groups are routing hints, not truth or answerability decisions. requirement_catalog lists the response requirement IDs but deliberately carries no planner missing/satisfied judgment. Determine support or absence yourself from the complete Source reservoir. user_memory_cues is a deterministic navigation index of slow-memory claims and user-authored Source or source-group context; it is not separate proof, so inspect the referenced Source before binding a remembered claim. For memory_conditioned_generation, first recover the user's grounded preferences or constraints and then generate the requested recommendation or advice; a ready-made historical answer is not required. Carry forward relevant prior choices, owned tools, resources, genres, constraints, and already-adopted solutions instead of defaulting to generic advice. When several relevant cues differ in specificity, preserve the narrower grounded detail rather than replacing it with a broad category. The final answer itself must explicitly show how at least one specific remembered constraint shaped the response; do not leave personalization only inside the claims array. Do not declare the task insufficient merely because the exact requested recommendation was not historical when grounded memory can personalize a new answer and model knowledge can fulfill the current target. Query context never requires Source evidence IDs. Model knowledge does not require Source evidence IDs when it is allowed for memory-conditioned generation. External-tool premises remain unresolved until a tool result exists.
+Source evidence is ordered by frozen retrieval priority and then by source order within each selected session; source_order is not an event date. Each Source item carries its immutable historical_date and timestamp when available. Resolve words such as today and yesterday against that Source item's timestamp, never against the question date. Inspect source_group_context as neighboring source context and use each neighbor's own timestamp. Before answering, internally build an exact evidence ledger for the requested entity: list every matching event or item, its event date or stated relative time, state (actual, planned, hypothetical, or mentioned), and Source ID. Deduplicate repeated mentions of the same event or item before counting. For latest/earliest/order/duration questions, compare event times grounded in Source text plus its timestamp, not source_order or database session_index. If a when, before, or after clause names another remembered event, treat that event as a candidate temporal endpoint and compare both Source dates before using the question date. Use the question date only when the wording actually asks for distance from the query time.
+Each Source item may include memory_contexts and attachments. A slow_context is the slow graph's durable interpretation and must retain its capsule, claim, and provenance identity. A fast_context is an atomic current-memory interpretation. An attachment marked override with precedence=newer_fast_evidence has controller-verified precedence over a conflicting slow claim in the same canonical slot. These graph views organize meaning but do not replace Source proof: support final remembered claims with the Source evidence ID carrying the context, and inspect its immutable text before relying on it.
+Use only supplied Source evidence IDs and verified computation IDs. memory_fact claims require direct support_ids. memory_inference claims require support_ids for every Source premise and represent source-grounded comparison or synthesis that has no verified operation result. memory_derived claims require computation_ids. query_context claims may have empty binding lists in every task when they state only information supplied by the current question, such as the question date or arithmetic derived solely from it. Only memory_conditioned_generation may use model_knowledge claims with empty binding lists; label their origin explicitly, and include at least one memory_fact, memory_inference, or memory_derived claim showing how remembered constraints shaped the answer. Never label remembered information as query_context or model_knowledge. planner_operation_candidates expose no result because their operand selection has not been semantically certified; independently inspect their Source supports. lexical_anchor_ids are deterministic search hints, not proof. Never transfer values between different entities, people, places, events, or activities. Preserve requested temporal order, distinct values, totals, and update precedence.
+For preferences, use the specific historical experiences in Source evidence. Treat named entities and activities exactly: a shorter, broader, or related term is not the requested multiword entity unless the source explicitly says they are equivalent. For false premises or entity mismatch, explicitly state that the requested target is not established, then optionally state related counterevidence. For count/list questions, enumerate distinct matching items before producing the total. For changing facts, apply latest update precedence using event time and source-group context. A sufficient answer must cover every requirement and have no missing_requirements. An insufficient answer must name supplied requirement IDs that remain unresolved after inspecting all Source evidence. Never use hidden supervision or outside facts for remembered claims."""
+
+
+SEMANTIC_EVIDENCE_ANSWER_PROMPT = f"""Execute one verified memory task contract.
+Return exactly one JSON object and no prose using this schema:
+{{"schema_version":"{SEMANTIC_ANSWER_SCHEMA}","response_status":"answered|partial|answered_with_context|requires_tool|clarification|not_answerable","claims":[{{"claim_id":"C01","text":"one final claim","origin":"memory_fact|memory_derived|model_knowledge|tool_result","premise_ids":["P01"],"source_claim_ids":["M01"],"computation_ids":["O01"]}}],"unresolved_premise_ids":[],"answer":"concise complete response"}}
+
+The task contract defines the requested target and output shape. The answerability certificate is authoritative; do not redo retrieval, invent missing memory, or change its answer policy.
+For memory_fact claims, use only Source claim IDs bound to the cited premises. For memory_derived claims, use only completed computation IDs bound to the cited premises. Preserve entity, time, polarity, modality, cardinality, ordering, and update state.
+When the policy is answer_with_memory_context, treat remembered claims as constraints or background. You may produce model_knowledge claims needed to fulfill the current request, but never describe them as remembered facts and never attach Source claim IDs to them.
+When the policy is answer_partial, answer only the supported portion, explicitly state the unresolved limitation, use response_status partial, and preserve the certificate's unresolved premise IDs. For a memory-conditioned task, the partial answer must explicitly use at least one bound memory claim rather than falling back to a generic response. Never turn a partial count or other incomplete derived aggregate into a final total.
+When the policy is call_tool, clarify, or abstain, use the matching response_status and explain the unresolved need without fabricating an answer. unresolved_premise_ids must exactly match the certificate.
+Do not cite raw evidence IDs directly. Do not use benchmark labels or hidden supervision."""
+
+
+def render_compiled_packet(packet: Mapping[str, Any]) -> dict[str, Any]:
+    if packet.get("schema_version") != PACKET_SCHEMA:
+        raise RuntimeError("compiled evidence packet schema is invalid")
+    evidence = list(packet.get("raw_evidence_reservoir") or [])
+    evidence_ids = {clean_text(item.get("evidence_id")) for item in evidence}
+    if not evidence or not all(evidence_ids):
+        raise RuntimeError("compiled evidence packet has no source reservoir")
+    bundles = []
+    for bundle in list(packet.get("evidence_bundles") or []):
+        ids = list(bundle.get("evidence_ids") or [])
+        if any(item not in evidence_ids for item in ids):
+            raise RuntimeError("compiled evidence bundle cites unknown source")
+        bundles.append(
+            {
+                "bundle_id": bundle.get("bundle_id"),
+                "role": bundle.get("role"),
+                "evidence_ids": ids,
+            }
+        )
+    question_contract = dict(packet.get("question_contract") or {})
+    task_contract = packet.get("task_contract")
+    if not isinstance(task_contract, Mapping):
+        task_contract = question_contract.get("task_contract")
+    question_contract.pop("task_contract", None)
+    requirements = list(packet.get("requirement_coverage") or [])
+    premise_by_id = {
+        clean_text(item.get("premise_id")): item
+        for item in (
+            task_contract.get("premises") or []
+            if isinstance(task_contract, Mapping)
+            else []
+        )
+        if isinstance(item, Mapping)
+    }
+    output_origin = (
+        clean_text(task_contract.get("output_origin"))
+        if isinstance(task_contract, Mapping)
+        else clean_text(question_contract.get("output_origin"))
+    )
+    requirement_catalog = []
+    bound_constraints = []
+    for requirement in requirements:
+        requirement_id = clean_text(requirement.get("requirement_id"))
+        evidence_ids_for_requirement = [
+            item
+            for item in list(requirement.get("evidence_ids") or [])
+            if item in evidence_ids
+        ]
+        premise = premise_by_id.get(requirement_id) or {}
+        description = clean_text(requirement.get("description"))
+        source_kind = clean_text(premise.get("source")) or "memory"
+        catalog_item = {
+            "requirement_id": requirement_id,
+            "description": (
+                "remembered personalization constraints; inspect all Source evidence"
+                if output_origin == "memory_conditioned_generation"
+                and source_kind == "memory"
+                and not evidence_ids_for_requirement
+                else description
+            ),
+            "source_kind": source_kind,
+        }
+        if evidence_ids_for_requirement:
+            catalog_item["candidate_source_ids"] = evidence_ids_for_requirement
+        requirement_catalog.append(catalog_item)
+        if evidence_ids_for_requirement and isinstance(premise, Mapping):
+            bound_constraints.append(
+                {
+                    "premise_id": requirement_id,
+                    "description": clean_text(premise.get("description")) or description,
+                    "source_kind": source_kind,
+                    "grounded_constraints": list(premise.get("grounded_constraints") or []),
+                    "candidate_source_ids": evidence_ids_for_requirement,
+                }
+            )
+    operation_results = list(packet.get("operation_results") or [])
+    verified_operations = [
+        dict(item)
+        for item in operation_results
+        if item.get("status") == "completed"
+        and item.get("answer_authoritative") is True
+    ]
+    planner_operation_candidates = [
+        {
+            "operation_id": item.get("operation_id"),
+            "operation_type": item.get("operation_type"),
+            "support_ids": list(item.get("support_ids") or []),
+            "semantic_status": "uncertified_operand_selection",
+        }
+        for item in operation_results
+        if item.get("status") == "completed"
+        and item.get("answer_authoritative") is not True
+    ]
+    task_intent: dict[str, Any] = {"output_origin": output_origin}
+    if isinstance(task_contract, Mapping):
+        task_intent["target"] = dict(task_contract.get("target") or {})
+        task_intent["output"] = dict(task_contract.get("output") or {})
+        task_intent["bound_constraints"] = bound_constraints
+    rendered = {
+        "answer_view_schema": "tmcra.v4.answer-evidence-view.5",
+        "question_contract": question_contract,
+        "task_intent": task_intent,
+        "user_memory_cues": build_user_memory_cues(evidence),
+        "requirement_catalog": requirement_catalog,
+        "verified_operation_results": verified_operations,
+        "planner_operation_candidates": planner_operation_candidates,
+        "planner_source_groups": bundles,
+        "lexical_anchor_ids": list(packet.get("lexical_anchor_ids") or []),
+        "source_evidence": [
+            {
+                "source_order": index,
+                "evidence_id": item.get("evidence_id"),
+                "session_id": item.get("session_id"),
+                "session_index": item.get("session_index"),
+                "parent_chunk_index": item.get("parent_chunk_index"),
+                "historical_date": item.get("historical_date"),
+                "timestamp": item.get("timestamp"),
+                "message_role": item.get("message_role"),
+                "question_overlap_terms": item.get("question_overlap_terms") or [],
+                "question_overlap_score": int(item.get("question_overlap_score", 0)),
+                "text": item.get("text"),
+                "source_group_id": item.get("source_group_id"),
+                "source_group_context": list(item.get("source_group_context") or []),
+                "memory_contexts": list(item.get("memory_contexts") or []),
+                "attachments": list(item.get("attachments") or []),
+                "provenance": list(item.get("provenance") or []),
+            }
+            for index, item in enumerate(evidence, start=1)
+        ],
+    }
+    if isinstance(packet.get("semantic_advisory"), Mapping):
+        rendered["semantic_advisory"] = dict(packet["semantic_advisory"])
+    return rendered
+
+
+def parse_operation_bound_answer(raw: str, packet: Mapping[str, Any]) -> dict[str, Any]:
+    try:
+        value = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise RuntimeError(f"operation-bound answer is not strict JSON: {exc}") from exc
+    try:
+        return validate_evidence_bound_answer(value, packet)
+    except EvidenceOperationError as exc:
+        raise RuntimeError(f"operation-bound answer failed validation: {exc}") from exc
+
+
+def render_semantic_packet(packet: Mapping[str, Any]) -> dict[str, Any]:
+    if packet.get("schema_version") != SEMANTIC_PACKET_SCHEMA:
+        raise RuntimeError("semantic evidence packet schema is invalid")
+    contract = packet.get("task_contract")
+    certificate = packet.get("answerability_certificate")
+    if not isinstance(contract, Mapping) or not isinstance(certificate, Mapping):
+        raise RuntimeError("semantic evidence packet lacks contract or certificate")
+    premise_by_id = {
+        clean_text(item.get("premise_id")): item
+        for item in contract.get("premises") or []
+        if isinstance(item, Mapping)
+    }
+    claims_by_id = {
+        clean_text(item.get("claim_id")): item
+        for item in packet.get("claim_ledger") or []
+        if isinstance(item, Mapping)
+    }
+    evidence_by_id = {
+        clean_text(item.get("evidence_id")): item
+        for item in packet.get("raw_evidence_reservoir") or []
+        if isinstance(item, Mapping)
+    }
+    operation_by_id = {
+        clean_text(item.get("operation_id")): item
+        for item in (packet.get("resolution_program") or {}).get("operation_results") or []
+        if isinstance(item, Mapping)
+    }
+    resolved_premises = []
+    for binding in packet.get("premise_bindings") or []:
+        if not isinstance(binding, Mapping):
+            raise RuntimeError("semantic premise binding must be an object")
+        premise_id = clean_text(binding.get("premise_id"))
+        if premise_id not in premise_by_id:
+            raise RuntimeError("semantic premise binding cites an unknown premise")
+        claim_ids = list(binding.get("claim_ids") or [])
+        evidence_ids = list(binding.get("evidence_ids") or [])
+        operation_ids = list(binding.get("operation_ids") or [])
+        if any(item not in claims_by_id for item in claim_ids):
+            raise RuntimeError("semantic premise binding cites an unknown Source claim")
+        if any(item not in evidence_by_id for item in evidence_ids):
+            raise RuntimeError("semantic premise binding cites unknown evidence")
+        if any(item not in operation_by_id for item in operation_ids):
+            raise RuntimeError("semantic premise binding cites an unknown operation")
+        resolved_premises.append(
+            {
+                "premise": premise_by_id[premise_id],
+                "coverage": binding.get("coverage"),
+                "relation": binding.get("relation"),
+                "source_claims": [claims_by_id[item] for item in claim_ids],
+                "operation_results": [operation_by_id[item] for item in operation_ids],
+                "source_evidence": [
+                    {
+                        "evidence_id": item,
+                        "session_id": evidence_by_id[item].get("session_id"),
+                        "session_index": evidence_by_id[item].get("session_index"),
+                        "text": evidence_by_id[item].get("text"),
+                    }
+                    for item in evidence_ids
+                ],
+            }
+        )
+    return {
+        "query_context": dict(packet.get("query_context") or {}),
+        "task_contract": dict(contract),
+        "answerability_certificate": dict(certificate),
+        "resolved_premises": resolved_premises,
+        "non_memory_premises": [
+            premise
+            for premise in contract.get("premises") or []
+            if isinstance(premise, Mapping) and premise.get("source") != "memory"
+        ],
+        "target_operation_results": [
+            operation_by_id[item]
+            for item in certificate.get("target_operation_ids") or []
+            if item in operation_by_id
+        ],
+    }
+
+
+def parse_semantic_bound_answer(raw: str, packet: Mapping[str, Any]) -> dict[str, Any]:
+    try:
+        value = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise RuntimeError(f"semantic-bound answer is not strict JSON: {exc}") from exc
+    try:
+        return validate_semantic_answer(normalize_semantic_answer_output(value, packet), packet)
+    except SemanticEvidenceError as exc:
+        raise RuntimeError(f"semantic-bound answer failed validation: {exc}") from exc
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--evidence", required=True)
+    parser.add_argument("--harness", required=True)
+    parser.add_argument("--out-dir", required=True)
+    parser.add_argument("--workers", type=int, default=12)
+    parser.add_argument("--attempts", type=int, default=3)
+    parser.add_argument("--answer-window-limit", type=int, default=8)
+    parser.add_argument("--limit", type=int, default=0)
+    parser.add_argument("--qid-list", default="")
+    parser.add_argument("--lane", choices=("production", "shadow"), default="production")
+    args = parser.parse_args()
+    answer_model = clean_text(os.getenv("TMCRA_ANSWER_MODEL"))
+    answer_base_url = clean_text(os.getenv("TMCRA_ANSWER_BASE_URL"))
+    answer_api_key = clean_text(os.getenv("TMCRA_ANSWER_API_KEY"))
+    if answer_model != "gpt-5.4":
+        raise RuntimeError(f"fixed answer model must be exactly gpt-5.4, got {answer_model!r}")
+    if not answer_base_url or not answer_api_key:
+        raise RuntimeError("TMCRA_ANSWER_BASE_URL and TMCRA_ANSWER_API_KEY are required")
+    fixed_answer_layer = fixed_answer_environment(args.answer_window_limit)
+    os.environ.update(fixed_answer_layer)
+    rows = read_jsonl(Path(args.evidence))
+    if args.qid_list:
+        requested = [
+            clean_text(value)
+            for value in Path(args.qid_list).read_text(encoding="utf-8").splitlines()
+            if clean_text(value)
+        ]
+        by_qid = {clean_text(row.get("question_id")): row for row in rows}
+        missing = [qid for qid in requested if qid not in by_qid]
+        if missing:
+            raise RuntimeError(f"requested qids are missing from evidence: {missing[:10]}")
+        rows = [by_qid[qid] for qid in requested]
+    if args.limit > 0:
+        rows = rows[: args.limit]
+    if not rows:
+        raise RuntimeError("no answer rows selected")
+    reject_evaluation_fields(rows)
+    if args.lane == "production":
+        try:
+            validate_production_evidence(rows)
+        except RoutePolicyError as exc:
+            raise RuntimeError(
+                f"production route failed before GPT-5.4 calls: {exc}"
+            ) from exc
+    harness = load_harness(Path(args.harness))
+    configured_base_url, configured_model, configured_api_key = harness.answer_llm_config()
+    if clean_text(configured_model) != "gpt-5.4":
+        raise RuntimeError(f"harness resolved unexpected model: {configured_model!r}")
+    if not clean_text(configured_base_url) or not clean_text(configured_api_key):
+        raise RuntimeError("harness did not resolve the required GPT5.4 endpoint")
+
+    # The legacy harness contains optional answer-side repair hooks. Keep its
+    # primary prompt, but make one logical GPT call the enforced contract.
+    harness.complete_profile_answer_from_evidence = lambda _question, answer, _windows: answer
+    call_state = threading.local()
+    original_chat_completion = harness.chat_completion
+
+    def counted_chat_completion(*call_args: Any, **call_kwargs: Any) -> str:
+        call_state.count = int(getattr(call_state, "count", 0)) + 1
+        return original_chat_completion(*call_args, **call_kwargs)
+
+    harness.chat_completion = counted_chat_completion
+    out_dir = Path(args.out_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    raw_attempt_dir = out_dir / "raw_attempts"
+    raw_attempt_dir.mkdir(exist_ok=True)
+    answers_path = out_dir / "answers.jsonl"
+    existing: dict[str, dict[str, Any]] = {}
+    if answers_path.exists():
+        for row in read_jsonl(answers_path):
+            qid = clean_text(row.get("question_id"))
+            if qid:
+                if qid in existing:
+                    raise RuntimeError(f"duplicate existing answer row: {qid}")
+                existing[qid] = row
+    if existing and args.lane == "production":
+        try:
+            validate_production_answers(list(existing.values()))
+        except RoutePolicyError as exc:
+            raise RuntimeError(
+                "existing answers use an incompatible production protocol; "
+                "start a new answer output directory"
+            ) from exc
+    evidence_hashes, legacy_evidence_hash_backfills = bind_existing_answers_to_evidence(
+        existing, rows
+    )
+    lock = threading.Lock()
+
+    def answer_one(row: Mapping[str, Any]) -> dict[str, Any]:
+        qid = clean_text(row.get("question_id"))
+        question = clean_text(row.get("question"))
+        question_date = clean_text(row.get("question_date"))
+        runtime_question = f"{question}\nQuestion date: {question_date}" if question_date else question
+        semantic_packet = row.get("semantic_evidence_packet")
+        operation_packet = row.get("compiled_evidence_packet")
+        if args.lane == "production":
+            if isinstance(semantic_packet, Mapping):
+                raise RuntimeError(f"{qid}: semantic packets are forbidden in the production lane")
+            if not isinstance(operation_packet, Mapping):
+                raise RuntimeError(f"{qid}: production lane requires a compiled evidence packet")
+            packet = operation_packet
+            rendered_packet = render_compiled_packet(packet)
+            answer_prompt = EVIDENCE_OPERATION_ANSWER_PROMPT
+            answer_parser = parse_operation_bound_answer
+            answer_protocol = PRODUCTION_ANSWER_PROTOCOL
+        else:
+            if not isinstance(semantic_packet, Mapping) or isinstance(operation_packet, Mapping):
+                raise RuntimeError(f"{qid}: shadow lane requires only a semantic evidence packet")
+            packet = semantic_packet_to_advisory_packet(semantic_packet)
+            rendered_packet = render_compiled_packet(packet)
+            answer_prompt = EVIDENCE_OPERATION_ANSWER_PROMPT
+            answer_parser = parse_operation_bound_answer
+            answer_protocol = SHADOW_ANSWER_PROTOCOL
+        messages = [
+            {"role": "system", "content": answer_prompt},
+            {
+                "role": "user",
+                "content": json.dumps(rendered_packet, ensure_ascii=False, separators=(",", ":")),
+            },
+        ]
+        started = time.time()
+        last_error: Exception | None = None
+        answer = ""
+        evidence_binding: dict[str, Any] = {}
+        attempts_used = 0
+        logical_answer_calls = 0
+        validation_error = ""
+        for attempt in range(1, max(1, args.attempts) + 1):
+            attempts_used = attempt
+            call_state.count = 0
+            try:
+                attempt_path = raw_attempt_dir / f"{qid}.attempt_{attempt}.json"
+                if attempt_path.is_file():
+                    persisted = json.loads(attempt_path.read_text(encoding="utf-8"))
+                    if persisted.get("question_id") != qid or persisted.get("evidence_sha256") != evidence_hashes[qid]:
+                        raise RuntimeError(f"{qid}: persisted raw answer identity mismatch")
+                    raw_answer = str(persisted["raw_answer"])
+                    attempt_call_count = 0
+                else:
+                    attempt_messages = list(messages)
+                    if validation_error:
+                        attempt_messages.append(
+                            {
+                                "role": "user",
+                                "content": (
+                                    "The previous JSON failed the deterministic validator: "
+                                    f"{validation_error}. Correct only the JSON structure or evidence bindings. "
+                                    "Use the same compiled packet and return the required schema."
+                                ),
+                            }
+                        )
+                    raw_answer = harness.chat_completion(
+                        configured_base_url,
+                        configured_model,
+                        attempt_messages,
+                        max_tokens=int(os.getenv("TMCRA_ANSWER_MAX_TOKENS", "1536")),
+                        temperature=0.0,
+                        api_key=configured_api_key,
+                    )
+                    attempt_call_count = int(getattr(call_state, "count", 0))
+                    if attempt_call_count != 1:
+                        raise RuntimeError(
+                            f"{qid}: answer attempt made {attempt_call_count} logical GPT calls; expected exactly 1"
+                        )
+                    temporary = attempt_path.with_name(f".{attempt_path.name}.tmp.{os.getpid()}.{time.time_ns()}")
+                    temporary.write_text(
+                        json.dumps(
+                            {
+                                "question_id": qid,
+                                "evidence_sha256": evidence_hashes[qid],
+                                "attempt": attempt,
+                                "raw_answer": raw_answer,
+                            },
+                            ensure_ascii=False,
+                            sort_keys=True,
+                        )
+                        + "\n",
+                        encoding="utf-8",
+                    )
+                    os.replace(temporary, attempt_path)
+                logical_answer_calls += attempt_call_count
+                if attempt_call_count not in {0, 1}:
+                    raise RuntimeError(
+                        f"{qid}: invalid physical call count for answer attempt"
+                    )
+                evidence_binding = answer_parser(raw_answer, packet)
+                answer = evidence_binding["answer"]
+                break
+            except Exception as exc:
+                last_error = exc
+                validation_error = f"{exc.__class__.__name__}: {exc}"
+                if attempt >= max(1, args.attempts):
+                    break
+                time.sleep(min(8.0, 1.5 * (2 ** (attempt - 1))))
+        if not answer:
+            assert last_error is not None
+            raise RuntimeError(
+                f"{qid}: GPT5.4 failed after {max(1, args.attempts)} same-model attempts: "
+                f"{last_error.__class__.__name__}:{last_error}"
+            )
+        return {
+            "question_id": qid,
+            "question_type": clean_text(row.get("question_type")),
+            "question": question,
+            "evidence_sha256": evidence_hashes[qid],
+            "hypothesis": answer,
+            "evidence_binding": evidence_binding,
+            "answer_protocol": answer_protocol,
+            "answer_model": configured_model,
+            "answer_attempt_limit": max(1, args.attempts),
+            "answer_attempts_used": attempts_used,
+            "logical_answer_calls": logical_answer_calls,
+            "selected_session_ids": list(row.get("selected_session_ids") or []),
+            "latency_sec": round(time.time() - started, 3),
+            "error": "",
+        }
+
+    pending = [row for row in rows if clean_text(row.get("question_id")) not in existing]
+    failures: list[dict[str, str]] = []
+    completed = 0
+    started = time.time()
+    with ThreadPoolExecutor(max_workers=max(1, args.workers)) as executor:
+        futures = {executor.submit(answer_one, row): clean_text(row.get("question_id")) for row in pending}
+        for future in as_completed(futures):
+            qid = futures[future]
+            try:
+                result = future.result()
+            except Exception as exc:
+                failures.append({"question_id": qid, "error": f"{exc.__class__.__name__}:{str(exc)[:500]}"})
+                continue
+            with lock:
+                with answers_path.open("a", encoding="utf-8") as handle:
+                    handle.write(json.dumps(result, ensure_ascii=False, sort_keys=True) + "\n")
+                existing[qid] = result
+                completed += 1
+                if completed % 10 == 0 or completed == len(pending):
+                    print(
+                        json.dumps(
+                            {
+                                "completed_this_run": completed,
+                                "pending_this_run": len(pending),
+                                "total_saved": len(existing),
+                                "failures": len(failures),
+                                "elapsed_sec": round(time.time() - started, 3),
+                            }
+                        ),
+                        flush=True,
+                    )
+    final_rows = ordered_completed_answers(existing, rows)
+    atomic_write_jsonl(answers_path, final_rows)
+    protocols = sorted({str(row.get("answer_protocol") or "") for row in final_rows})
+    report = {
+        "status": "complete" if len(final_rows) == len(rows) and not failures else "incomplete",
+        "created_at": time.strftime("%Y-%m-%dT%H:%M:%S%z"),
+        "answer_model": configured_model,
+        "lane": args.lane,
+        "promotion_eligible": args.lane == "production",
+        "fixed_answer_layer": fixed_answer_layer,
+        "disabled_harness_hooks": ["complete_profile_answer_from_evidence"],
+        "max_logical_answer_calls_per_success": max(1, args.attempts),
+        "hierarchical_memory_context_rendering": True,
+        "compiled_evidence_packet_required": True,
+        "answer_protocol": protocols[0] if len(protocols) == 1 else "mixed",
+        "evidence_binding_persisted": True,
+        "answers_bound_to_evidence_sha256": True,
+        "legacy_evidence_hash_backfills": legacy_evidence_hash_backfills,
+        "requested": len(rows),
+        "completed": len(final_rows),
+        "failure_count": len(failures),
+        "avg_latency_sec": round(sum(float(row["latency_sec"]) for row in final_rows) / max(1, len(final_rows)), 3),
+        "answers": str(answers_path),
+    }
+    (out_dir / "failures.json").write_text(json.dumps(failures, indent=2, sort_keys=True), encoding="utf-8")
+    (out_dir / "report.json").write_text(json.dumps(report, indent=2, sort_keys=True), encoding="utf-8")
+    print(json.dumps(report, indent=2, sort_keys=True))
+    return 0 if report["status"] == "complete" else 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

benchmarks/longmemeval/src/tmcra_benchmark/legacy/run_tmcra_v4_parallel_official_judge.py

@@ -0,0 +1,273 @@
+#!/usr/bin/env python3
+"""Run one isolated official LongMemEval judge process per question."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import subprocess
+import sys
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from pathlib import Path
+from typing import Any, Mapping
+
+
+DEFAULT_OFFICIAL_JUDGE = (
+    Path(__file__).resolve().parent.parent / "harness" / "evaluate_qa_official_judge.py"
+)
+METRIC_MODEL_ALIASES = {"gpt-4o-2024-08-06": "gpt-4o"}
+BOUND_FIELDS = ("question", "hypothesis", "evidence_sha256", "answer_model")
+
+
+class ParallelJudgeError(RuntimeError):
+    pass
+
+
+def _read_jsonl(path: Path) -> list[dict[str, Any]]:
+    if not path.is_file():
+        return []
+    return [
+        json.loads(line)
+        for line in path.read_text(encoding="utf-8").splitlines()
+        if line.strip()
+    ]
+
+
+def _write_jsonl_atomic(path: Path, rows: list[Mapping[str, Any]]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_name(f".{path.name}.tmp.{os.getpid()}")
+    with temporary.open("w", encoding="utf-8") as handle:
+        for row in rows:
+            handle.write(json.dumps(row, ensure_ascii=False) + "\n")
+        handle.flush()
+        os.fsync(handle.fileno())
+    os.replace(temporary, path)
+
+
+def _validate_result(row: Mapping[str, Any], answer: Mapping[str, Any]) -> None:
+    qid = str(answer.get("question_id") or "").strip()
+    if str(row.get("question_id") or "").strip() != qid:
+        raise ParallelJudgeError(f"{qid}: judge result has a different question ID")
+    for key in BOUND_FIELDS:
+        if row.get(key) != answer.get(key):
+            raise ParallelJudgeError(f"{qid}: judge result is bound to different {key}")
+    label = row.get("autoeval_label")
+    if (
+        not isinstance(label, Mapping)
+        or type(label.get("label")) is not bool
+        or not str(label.get("model") or "").strip()
+        or not str(label.get("raw_response") or "").strip()
+    ):
+        raise ParallelJudgeError(f"{qid}: judge result has no valid official label")
+
+
+def _question_dir(work_dir: Path, index: int, qid: str) -> Path:
+    digest = hashlib.sha256(qid.encode("utf-8")).hexdigest()[:16]
+    return work_dir / f"{index:04d}_{digest}"
+
+
+def _judge_one(
+    *,
+    index: int,
+    answer: Mapping[str, Any],
+    args: argparse.Namespace,
+    environment: Mapping[str, str],
+    work_dir: Path,
+) -> tuple[int, dict[str, Any], bool]:
+    qid = str(answer["question_id"])
+    question_dir = _question_dir(work_dir, index, qid)
+    question_dir.mkdir(parents=True, exist_ok=True)
+    hypothesis_path = question_dir / "hypothesis.jsonl"
+    result_path = question_dir / "official_judge.jsonl"
+    log_path = question_dir / "official_judge.log"
+    _write_jsonl_atomic(hypothesis_path, [answer])
+
+    cached = _read_jsonl(result_path)
+    if cached:
+        if len(cached) != 1:
+            raise ParallelJudgeError(f"{qid}: cached judge result is not one row")
+        _validate_result(cached[0], answer)
+        return index, cached[0], True
+
+    command = [
+        sys.executable,
+        str(args.judge.resolve()),
+        "--metric-model",
+        METRIC_MODEL_ALIASES.get(args.metric_model, args.metric_model),
+        "--hyp-file",
+        str(hypothesis_path),
+        "--ref-file",
+        str(args.ref_file.resolve()),
+        "--result-file",
+        str(result_path),
+        "--base-url",
+        args.base_url,
+        "--api-key-env",
+        args.api_key_env,
+        "--timeout",
+        str(args.timeout),
+        "--max-retries",
+        str(args.max_retries),
+        "--quiet",
+    ]
+    completed = subprocess.run(
+        command,
+        env=dict(environment),
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        text=True,
+        timeout=args.process_timeout,
+        check=False,
+    )
+    log_path.write_text(completed.stdout or "", encoding="utf-8")
+    if completed.returncode != 0:
+        raise ParallelJudgeError(
+            f"{qid}: official judge process exited {completed.returncode}; log={log_path}"
+        )
+    rows = _read_jsonl(result_path)
+    if len(rows) != 1:
+        raise ParallelJudgeError(f"{qid}: official judge process did not write one row")
+    _validate_result(rows[0], answer)
+    return index, rows[0], False
+
+
+def run_parallel_judge(
+    args: argparse.Namespace, *, environment: Mapping[str, str] | None = None
+) -> dict[str, Any]:
+    environment = dict(environment or os.environ)
+    if not environment.get(args.api_key_env):
+        raise ParallelJudgeError(f"missing API key env: {args.api_key_env}")
+    if not args.judge.is_file():
+        raise ParallelJudgeError(f"official judge is missing: {args.judge}")
+
+    hypotheses = _read_jsonl(args.hyp_file)
+    if args.limit and args.limit > 0:
+        hypotheses = hypotheses[: args.limit]
+    expected_qids = [str(item.get("question_id") or "").strip() for item in hypotheses]
+    if not expected_qids or any(not qid for qid in expected_qids):
+        raise ParallelJudgeError("hypotheses are empty or contain empty question IDs")
+    if len(expected_qids) != len(set(expected_qids)):
+        raise ParallelJudgeError("hypotheses contain duplicate question IDs")
+
+    result_file = args.result_file or Path(
+        str(args.hyp_file) + f".eval-results-{args.metric_model}"
+    )
+    if result_file.exists() and not args.resume:
+        raise ParallelJudgeError("judge result exists; use --resume")
+    existing = _read_jsonl(result_file)
+    if len(existing) > len(hypotheses):
+        raise ParallelJudgeError("existing judge result is longer than hypotheses")
+    for index, row in enumerate(existing):
+        _validate_result(row, hypotheses[index])
+
+    committed: dict[int, dict[str, Any]] = {
+        index: row for index, row in enumerate(existing)
+    }
+    work_dir = args.work_dir or result_file.with_name(f"{result_file.name}.work")
+    work_dir.mkdir(parents=True, exist_ok=True)
+    pending_indices = list(range(len(existing), len(hypotheses)))
+    failures: list[str] = []
+    cached_count = 0
+    called_count = 0
+
+    def commit_contiguous_prefix() -> int:
+        prefix: list[dict[str, Any]] = []
+        for index in range(len(hypotheses)):
+            if index not in committed:
+                break
+            prefix.append(committed[index])
+        _write_jsonl_atomic(result_file, prefix)
+        return len(prefix)
+
+    with ThreadPoolExecutor(max_workers=args.workers) as executor:
+        futures = {
+            executor.submit(
+                _judge_one,
+                index=index,
+                answer=hypotheses[index],
+                args=args,
+                environment=environment,
+                work_dir=work_dir,
+            ): index
+            for index in pending_indices
+        }
+        for future in as_completed(futures):
+            index = futures[future]
+            try:
+                completed_index, row, cached = future.result()
+                committed[completed_index] = row
+                cached_count += int(cached)
+                called_count += int(not cached)
+                commit_contiguous_prefix()
+            except Exception as exc:
+                failures.append(f"{expected_qids[index]}: {exc}")
+
+    committed_count = commit_contiguous_prefix()
+    report = {
+        "status": "complete" if committed_count == len(hypotheses) else "incomplete",
+        "metric_model": args.metric_model,
+        "row_count": len(hypotheses),
+        "committed_count": committed_count,
+        "existing_count": len(existing),
+        "cached_count": cached_count,
+        "physical_call_count": called_count,
+        "failure_count": len(failures),
+        "failures": failures,
+        "workers": args.workers,
+        "work_dir": str(work_dir),
+    }
+    if failures or committed_count != len(hypotheses):
+        report_path = result_file.with_name(f"{result_file.name}.isolated_report.json")
+        temporary = report_path.with_name(f".{report_path.name}.tmp.{os.getpid()}")
+        temporary.write_text(json.dumps(report, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+        os.replace(temporary, report_path)
+        raise ParallelJudgeError(
+            f"official judge incomplete: committed={committed_count}/{len(hypotheses)}, "
+            f"failures={len(failures)}; report={report_path}"
+        )
+    labels = [bool((committed[index]["autoeval_label"])["label"]) for index in range(len(hypotheses))]
+    report["correct_count"] = sum(labels)
+    report["accuracy"] = round(sum(labels) / len(labels), 6)
+    report_path = result_file.with_name(f"{result_file.name}.isolated_report.json")
+    temporary = report_path.with_name(f".{report_path.name}.tmp.{os.getpid()}")
+    temporary.write_text(json.dumps(report, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    os.replace(temporary, report_path)
+    return report
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--judge", type=Path, default=DEFAULT_OFFICIAL_JUDGE)
+    parser.add_argument("--metric-model", default="gpt-4o")
+    parser.add_argument("--hyp-file", required=True, type=Path)
+    parser.add_argument("--ref-file", required=True, type=Path)
+    parser.add_argument("--result-file", type=Path)
+    parser.add_argument("--work-dir", type=Path)
+    parser.add_argument("--base-url", required=True)
+    parser.add_argument("--api-key-env", default="OPENAI_API_KEY")
+    parser.add_argument("--limit", type=int, default=0)
+    parser.add_argument("--timeout", type=int, default=180)
+    parser.add_argument("--process-timeout", type=int, default=240)
+    parser.add_argument("--max-retries", type=int, default=0)
+    parser.add_argument("--resume", action="store_true")
+    parser.add_argument("--quiet", action="store_true")
+    parser.add_argument(
+        "--workers",
+        type=int,
+        default=int(os.environ.get("TMCRA_OFFICIAL_JUDGE_WORKERS", "8")),
+    )
+    args = parser.parse_args()
+    if args.workers <= 0:
+        raise ParallelJudgeError("workers must be positive")
+    if args.process_timeout <= args.timeout:
+        raise ParallelJudgeError("process timeout must exceed request timeout")
+    summary = run_parallel_judge(args)
+    if not args.quiet:
+        print(json.dumps(summary, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

benchmarks/longmemeval/src/tmcra_benchmark/legacy/run_tmcra_v4_retrieve.py

@@ -0,0 +1,524 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+import tmcra_v4_online_runtime as online
+from run_tmcra_v4_build import (
+    BASE,
+    DEFAULT_REPO,
+    DEFAULT_WRITER_ENV,
+    _key_pool,
+    _load_shell_environment,
+    _now,
+    _resume_log,
+    _run,
+)
+from tmcra_v4_cost_report import build_report, collect_calls
+from tmcra_v4_route_policy import (
+    RoutePolicyError,
+    validate_diagnostic_retrieval_rows,
+    validate_production_packing_budget,
+    validate_production_retrieval_mode,
+    validate_production_retrieval_rows,
+)
+
+
+PROJECT_ROOT = BASE.parents[2]
+PACKAGE_ROOT = BASE.parent
+DEFAULT_HARNESS = PACKAGE_ROOT / "harness" / "run_lme_s10_native_tmcra.py"
+DEFAULT_NODE = PROJECT_ROOT / "models" / "tmcra" / "node_scorer.pt"
+DEFAULT_PATH_MODEL = PROJECT_ROOT / "models" / "tmcra" / "path_scorer.pt"
+DEFAULT_CHECKPOINT = PROJECT_ROOT / "models" / "tmcra" / "tmcra_v3_reranker.pt"
+DEFAULT_EMBEDDING = PROJECT_ROOT / "models" / "BAAI" / "bge-m3"
+DEFAULT_CROSS = PROJECT_ROOT / "models" / "BAAI" / "bge-reranker-v2-m3"
+
+
+class RetrievalError(RuntimeError):
+    pass
+
+
+def _jsonl(path: Path) -> list[dict[str, Any]]:
+    return [
+        json.loads(line)
+        for line in path.read_text(encoding="utf-8").splitlines()
+        if line.strip()
+    ]
+
+
+def _fingerprints(rows: list[dict[str, Any]]) -> dict[str, str]:
+    return {
+        str(row["question_id"]): online.scope_fingerprint(
+            Path(str(row["db_path"])).resolve(), str(row["scope_id"])
+        )
+        for row in rows
+    }
+
+
+def _file_sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _atomic_write_text(path: Path, text: str) -> None:
+    temporary = path.with_name(f".{path.name}.tmp.{os.getpid()}")
+    temporary.write_text(text, encoding="utf-8")
+    os.replace(temporary, path)
+
+
+def _prepare_graph_boundary(
+    *,
+    run_dir: Path,
+    tag: str,
+    fingerprints: dict[str, str],
+    resume: bool,
+) -> None:
+    before_path = run_dir / f"{tag}.graph_before.json"
+    failed_path = run_dir / f"FAILED.{tag}"
+    staging_path = run_dir / f".{tag}.staging"
+    if resume:
+        if not failed_path.is_file():
+            raise RetrievalError("resume requires the existing FAILED marker")
+        if not before_path.is_file():
+            raise RetrievalError("resume requires the original graph_before boundary")
+        try:
+            original = json.loads(before_path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as exc:
+            raise RetrievalError("original graph_before boundary is unreadable") from exc
+        if original != fingerprints:
+            raise RetrievalError("graph changed since the failed retrieval began")
+        return
+    if failed_path.exists() or before_path.exists() or staging_path.exists():
+        raise RetrievalError(
+            "prior retrieval state exists; inspect it and use explicit --resume"
+        )
+    _atomic_write_text(
+        before_path,
+        json.dumps(fingerprints, indent=2, sort_keys=True) + "\n",
+    )
+
+
+def _archive_failed_marker(run_dir: Path, tag: str) -> None:
+    failed_path = run_dir / f"FAILED.{tag}"
+    if not failed_path.is_file():
+        return
+    history_path = run_dir / f"{tag}.failure_history.jsonl"
+    content = failed_path.read_text(encoding="utf-8")
+    with history_path.open("a", encoding="utf-8") as handle:
+        for line in content.splitlines():
+            if line.strip():
+                handle.write(line.rstrip() + "\n")
+    failed_path.unlink()
+
+
+def _record_failure(run_dir: Path, tag: str, exc: Exception) -> None:
+    _archive_failed_marker(run_dir, tag)
+    _atomic_write_text(
+        run_dir / f"FAILED.{tag}",
+        json.dumps(
+            {"at": _now(), "error": f"{exc.__class__.__name__}: {exc}"}
+        )
+        + "\n",
+    )
+
+
+def _validate_manifest_pair(
+    scope_rows: list[dict[str, Any]], query_rows: list[dict[str, Any]]
+) -> None:
+    def inventory(rows: list[dict[str, Any]], label: str) -> dict[str, tuple[str, str, str]]:
+        result: dict[str, tuple[str, str, str]] = {}
+        for row in rows:
+            qid = str(row.get("question_id") or "").strip()
+            identity = tuple(
+                str(Path(str(row[key])).resolve()) if key != "scope_id" else str(row[key]).strip()
+                for key in ("db_path", "scope_id", "index_path")
+            )
+            if not qid or qid in result or not all(identity):
+                raise RetrievalError(f"{label} has a missing or duplicate retrieval identity")
+            result[qid] = identity
+        return result
+
+    scope_inventory = inventory(scope_rows, "scope manifest")
+    query_inventory = inventory(query_rows, "query manifest")
+    if scope_inventory != query_inventory:
+        raise RetrievalError("scope/query manifests do not reference the same frozen indexes")
+
+
+def _select_manifest_rows(
+    scope_rows: list[dict[str, Any]],
+    query_rows: list[dict[str, Any]],
+    qid_path: Path,
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    qids = [
+        line.strip()
+        for line in qid_path.read_text(encoding="utf-8").splitlines()
+        if line.strip()
+    ]
+    if not qids or len(qids) != len(set(qids)):
+        raise RetrievalError("qid list is empty or duplicated")
+    scope_by_qid = {str(row.get("question_id") or "").strip(): row for row in scope_rows}
+    query_by_qid = {str(row.get("question_id") or "").strip(): row for row in query_rows}
+    missing = [
+        qid
+        for qid in qids
+        if qid not in scope_by_qid or qid not in query_by_qid
+    ]
+    if missing:
+        raise RetrievalError(f"qid list contains unknown questions: {missing[:10]}")
+    return (
+        [scope_by_qid[qid] for qid in qids],
+        [query_by_qid[qid] for qid in qids],
+    )
+
+
+def _write_jsonl(path: Path, rows: list[dict[str, Any]]) -> None:
+    _atomic_write_text(
+        path,
+        "".join(json.dumps(row, ensure_ascii=False, sort_keys=True) + "\n" for row in rows),
+    )
+
+
+def _run_production_build_preflight(
+    run_dir: Path, tag: str, *, resume: bool
+) -> dict[str, Any]:
+    output = run_dir / f"{tag}.production_build_preflight.json"
+    _run(
+        [
+            sys.executable,
+            str(BASE / "audit_tmcra_v4_chain.py"),
+            "--run-dir",
+            str(run_dir),
+            "--output",
+            str(output),
+            "--build-only",
+        ],
+        (
+            _resume_log(run_dir, f"{tag}.production_build_preflight")
+            if resume
+            else run_dir / f"{tag}.production_build_preflight.log"
+        ),
+        dict(os.environ),
+    )
+    if not output.is_file():
+        raise RetrievalError("production build preflight did not emit an audit report")
+    try:
+        report = json.loads(output.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise RetrievalError("production build preflight report is unreadable") from exc
+    if report.get("passed") is not True:
+        raise RetrievalError("production build preflight did not pass")
+    return report
+
+
+def _validate_committed_retrieval_output(
+    out_dir: Path,
+    *,
+    expected_qids: list[str],
+    execution_lane: str,
+) -> dict[str, Any]:
+    evidence_rows = _jsonl(out_dir / "evidence_windows.jsonl")
+    debug_rows = _jsonl(out_dir / "retrieval_debug.jsonl")
+    try:
+        route_report = (
+            validate_production_retrieval_rows(evidence_rows)
+            if execution_lane == "production"
+            else validate_diagnostic_retrieval_rows(evidence_rows)
+        )
+    except RoutePolicyError as exc:
+        raise RetrievalError(
+            f"committed retrieval output does not match the requested lane: {exc}"
+        ) from exc
+    evidence_qids = [str(row.get("question_id") or "").strip() for row in evidence_rows]
+    debug_qids = [
+        str(row.get("question_id") or row.get("qid") or "").strip()
+        for row in debug_rows
+    ]
+    if evidence_qids != expected_qids or debug_qids != expected_qids:
+        raise RetrievalError(
+            "committed retrieval output does not match the selected query manifest"
+        )
+    try:
+        report = json.loads((out_dir / "report.json").read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise RetrievalError("committed retrieval report is unreadable") from exc
+    if report.get("query_count") != len(expected_qids):
+        raise RetrievalError("committed retrieval report query count is inconsistent")
+    return route_report
+
+
+def retrieve(args: argparse.Namespace) -> dict[str, Any]:
+    # The logical run path is part of durable retrieval identity. Following a
+    # storage symlink here would invalidate resumable checkpoints after a move.
+    run_dir = args.run_dir.absolute()
+    execution_lane = "diagnostic" if bool(getattr(args, "diagnostic", False)) else "production"
+    try:
+        validate_production_retrieval_mode(
+            getattr(args, "composition_mode", None), execution_lane=execution_lane
+        )
+        validate_production_packing_budget(
+            getattr(args, "packing_budget_mode", "fixed"),
+            getattr(args, "top_k", 8),
+            execution_lane=execution_lane,
+        )
+    except RoutePolicyError as exc:
+        raise RetrievalError(f"retrieval route policy rejected the run: {exc}") from exc
+    if not (run_dir / "BUILD_COMPLETE").is_file():
+        raise RetrievalError("frozen V4 build is incomplete")
+    if not re.fullmatch(r"[A-Za-z0-9_.-]+", args.tag):
+        raise RetrievalError("tag contains unsupported characters")
+    out_dir = run_dir / args.tag
+    resume = bool(getattr(args, "resume", False))
+    reuse_committed_output = False
+    if out_dir.exists():
+        required = (
+            out_dir / "evidence_windows.jsonl",
+            out_dir / "retrieval_debug.jsonl",
+            out_dir / "report.json",
+        )
+        if not resume:
+            raise RetrievalError(f"retrieval output already exists: {out_dir}")
+        if not out_dir.is_dir() or not all(path.is_file() for path in required):
+            raise RetrievalError(
+                f"resume found an incomplete committed retrieval output: {out_dir}"
+            )
+        reuse_committed_output = True
+    query_manifest = Path(
+        getattr(args, "query_manifest", None) or run_dir / "query_manifest.jsonl"
+    ).resolve()
+    scope_manifest = Path(
+        getattr(args, "scope_manifest", None) or run_dir / "scope_manifest.jsonl"
+    ).resolve()
+    if not query_manifest.is_file() or not scope_manifest.is_file():
+        raise RetrievalError("scope/query manifest is missing")
+    rows = _jsonl(scope_manifest)
+    query_rows = _jsonl(query_manifest)
+    if not rows or not query_rows:
+        raise RetrievalError("scope/query manifest is empty")
+    _validate_manifest_pair(rows, query_rows)
+    qid_list = getattr(args, "qid_list", None)
+    if qid_list is not None:
+        if not Path(qid_list).resolve().is_file():
+            raise RetrievalError("qid list is missing")
+        rows, query_rows = _select_manifest_rows(
+            rows, query_rows, Path(qid_list).resolve()
+        )
+        scope_manifest = run_dir / f"{args.tag}.scope_manifest.selected.jsonl"
+        query_manifest = run_dir / f"{args.tag}.query_manifest.selected.jsonl"
+        _write_jsonl(scope_manifest, rows)
+        _write_jsonl(query_manifest, query_rows)
+        _validate_manifest_pair(rows, query_rows)
+
+    if reuse_committed_output:
+        _validate_committed_retrieval_output(
+            out_dir,
+            expected_qids=[str(row["question_id"]).strip() for row in query_rows],
+            execution_lane=execution_lane,
+        )
+
+    if execution_lane == "production":
+        _run_production_build_preflight(run_dir, args.tag, resume=resume)
+
+    shell_environment = _load_shell_environment(args.writer_env.resolve())
+    environment = {**os.environ, **shell_environment}
+    keys = _key_pool(environment)
+    base_url = environment.get("TMCRA_DEEPSEEK_WRITER_BASE_URL") or environment.get("TMCRA_WRITER_BASE_URL") or "https://api.deepseek.com/v1"
+    environment.update(
+        {
+            "TMCRA_RECALL_PLANNER_BASE_URL": base_url,
+            "TMCRA_RECALL_PLANNER_MODEL": "deepseek-v4-flash",
+            "TMCRA_RECALL_PLANNER_API_KEY_POOL": ",".join(keys),
+            "TMCRA_NODE_MODEL_PATH": str(args.node_model.resolve()),
+            "TMCRA_PATH_MODEL_PATH": str(args.path_model.resolve()),
+            "TMCRA_NODE_MODEL_DEVICE": args.graph_device,
+        }
+    )
+    before = _fingerprints(rows)
+    _prepare_graph_boundary(
+        run_dir=run_dir,
+        tag=args.tag,
+        fingerprints=before,
+        resume=resume,
+    )
+    try:
+        if not reuse_committed_output:
+            runtime_options = ["--resume"] if resume else []
+            if args.planner_replay_dir is not None:
+                runtime_options.extend(
+                    ["--planner-replay-dir", str(args.planner_replay_dir.resolve())]
+                )
+            _run(
+                [
+                    sys.executable,
+                    str(BASE / "tmcra_v4_online_runtime.py"),
+                    "retrieve",
+                    *runtime_options,
+                    "--query-manifest",
+                    str(query_manifest),
+                    "--out-dir",
+                    str(out_dir),
+                    "--checkpoint",
+                    str(args.checkpoint.resolve()),
+                    "--cross-model",
+                    str(args.cross_model.resolve()),
+                    "--repo",
+                    str(args.repo.resolve()),
+                    "--harness",
+                    str(args.harness.resolve()),
+                    "--node-model",
+                    str(args.node_model.resolve()),
+                    "--path-model",
+                    str(args.path_model.resolve()),
+                    "--graph-device",
+                    args.graph_device,
+                    "--embedding-model",
+                    str(args.embedding_model.resolve()),
+                    "--slow-dense-k",
+                    str(args.slow_dense_k),
+                    "--dense-k",
+                    str(args.dense_k),
+                    "--graph-k",
+                    str(args.graph_k),
+                    "--composition-mode",
+                    str(args.composition_mode),
+                    "--execution-lane",
+                    execution_lane,
+                    "--packing-budget-mode",
+                    str(args.packing_budget_mode),
+                    "--top-k",
+                    str(args.top_k),
+                    "--adaptive-simple-k",
+                    str(args.adaptive_simple_k),
+                    "--adaptive-standard-k",
+                    str(args.adaptive_standard_k),
+                    "--adaptive-complex-k",
+                    str(args.adaptive_complex_k),
+                    "--cross-batch-size",
+                    str(args.cross_batch_size),
+                    "--device",
+                    args.device,
+                ],
+                (
+                    _resume_log(run_dir, args.tag)
+                    if resume
+                    else run_dir / f"{args.tag}.log"
+                ),
+                environment,
+            )
+        after = _fingerprints(rows)
+        _atomic_write_text(
+            run_dir / f"{args.tag}.graph_after.json",
+            json.dumps(after, indent=2, sort_keys=True) + "\n",
+        )
+        if after != before:
+            raise RetrievalError("retrieval changed graph structure or graph records")
+        _run(
+            [
+                sys.executable,
+                str(BASE / "audit_tmcra_v4_chain.py"),
+                "--run-dir",
+                str(run_dir),
+                "--retrieval-dir",
+                str(out_dir),
+                "--output",
+                str(run_dir / f"{args.tag}.chain_audit.json"),
+            ],
+            (
+                _resume_log(run_dir, f"{args.tag}.chain_audit")
+                if resume
+                else run_dir / f"{args.tag}.chain_audit.log"
+            ),
+            environment,
+        )
+        # Retrieval cost is incremental. Frozen graph databases contain the
+        # historical writer ledger and must not be charged to every query run.
+        calls = collect_calls([out_dir / "retrieval_debug.jsonl"], [])
+        cost = build_report(calls)
+        (run_dir / f"{args.tag}.cost_report.json").write_text(
+            json.dumps(cost, indent=2, sort_keys=True) + "\n", encoding="utf-8"
+        )
+        report = json.loads((out_dir / "report.json").read_text(encoding="utf-8"))
+        summary = {
+            "schema_version": "tmcra.v4.retrieval-run.1",
+            "status": "complete",
+            "tag": args.tag,
+            "execution_lane": execution_lane,
+            "composition_mode": str(args.composition_mode),
+            "query_count": report["query_count"],
+            "selected_output": str(out_dir / "evidence_windows.jsonl"),
+            "scope_manifest": str(scope_manifest),
+            "scope_manifest_sha256": _file_sha256(scope_manifest),
+            "query_manifest": str(query_manifest),
+            "query_manifest_sha256": _file_sha256(query_manifest),
+            "qid_list": str(Path(qid_list).resolve()) if qid_list is not None else None,
+            "qid_list_sha256": _file_sha256(Path(qid_list).resolve()) if qid_list is not None else None,
+            "graph_structure_unchanged": True,
+            "resumed": resume,
+            "reused_committed_retrieval_output": reuse_committed_output,
+            "physical_api_call_count_total": cost["physical_call_count"],
+            "exact_cost_cny_total": cost["exact_cost_cny"],
+            "min_cost_cny_total": cost["min_cost_cny"],
+            "max_cost_cny_total": cost["max_cost_cny"],
+        }
+        (out_dir / "retrieval_run_report.json").write_text(
+            json.dumps(summary, indent=2, sort_keys=True) + "\n", encoding="utf-8"
+        )
+        (out_dir / "RETRIEVAL_COMPLETE").write_text(_now() + "\n", encoding="utf-8")
+        _archive_failed_marker(run_dir, args.tag)
+        return summary
+    except Exception as exc:
+        _record_failure(run_dir, args.tag, exc)
+        raise
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Run one TMCRA V4 retrieval pass over a frozen build")
+    parser.add_argument("--run-dir", type=Path, required=True)
+    parser.add_argument("--tag", default="retrieval_1")
+    parser.add_argument("--resume", action="store_true")
+    parser.add_argument("--scope-manifest", type=Path)
+    parser.add_argument("--query-manifest", type=Path)
+    parser.add_argument("--qid-list", type=Path)
+    parser.add_argument("--planner-replay-dir", type=Path)
+    parser.add_argument("--writer-env", type=Path, default=DEFAULT_WRITER_ENV)
+    parser.add_argument("--repo", type=Path, default=DEFAULT_REPO)
+    parser.add_argument("--harness", type=Path, default=DEFAULT_HARNESS)
+    parser.add_argument("--node-model", type=Path, default=DEFAULT_NODE)
+    parser.add_argument("--path-model", type=Path, default=DEFAULT_PATH_MODEL)
+    parser.add_argument("--checkpoint", type=Path, default=DEFAULT_CHECKPOINT)
+    parser.add_argument("--embedding-model", type=Path, default=DEFAULT_EMBEDDING)
+    parser.add_argument("--cross-model", type=Path, default=DEFAULT_CROSS)
+    parser.add_argument("--device", default="cuda")
+    parser.add_argument("--graph-device", default="cuda")
+    parser.add_argument("--dense-k", type=int, default=32)
+    parser.add_argument("--slow-dense-k", type=int, default=24)
+    parser.add_argument("--graph-k", type=int, default=24)
+    parser.add_argument("--composition-mode", choices=("layered", "source-only-diagnostic"), default="layered")
+    parser.add_argument(
+        "--diagnostic",
+        action="store_true",
+        help="explicitly allow a non-production retrieval composition",
+    )
+    parser.add_argument("--packing-budget-mode", choices=("fixed", "adaptive"), default="fixed")
+    parser.add_argument("--top-k", type=int, default=8)
+    parser.add_argument("--adaptive-simple-k", type=int, default=8)
+    parser.add_argument("--adaptive-standard-k", type=int, default=12)
+    parser.add_argument("--adaptive-complex-k", type=int, default=16)
+    parser.add_argument("--cross-batch-size", type=int, default=24)
+    args = parser.parse_args()
+    summary = retrieve(args)
+    print(json.dumps(summary, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

benchmarks/longmemeval/src/tmcra_benchmark/legacy/tmcra_model_assets.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+
+def load_optional_hf_model_manifest(model_dir: str | Path) -> dict[str, Any]:
+    """Read optional provenance metadata for a locally cached Hugging Face model.
+
+    ``TMCRA_MODEL_MANIFEST.json`` is a TMCRA sidecar, not part of the Hugging
+    Face model layout.  Official BGE snapshots therefore remain valid without
+    it.  When a sidecar is supplied, validate it before using its provenance
+    fields in reports.
+    """
+
+    path = Path(model_dir) / "TMCRA_MODEL_MANIFEST.json"
+    if not path.exists():
+        return {}
+    if not path.is_file():
+        raise ValueError(f"model manifest must be a file: {path}")
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        raise ValueError(f"invalid model manifest: {path}") from exc
+    if not isinstance(payload, Mapping):
+        raise ValueError(f"model manifest must contain a JSON object: {path}")
+    return dict(payload)

benchmarks/longmemeval/src/tmcra_benchmark/legacy/tmcra_v2_lme_pipeline.py

@@ -0,0 +1,855 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import math
+import os
+import random
+import re
+import time
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Mapping, Sequence
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+TOKEN_RE = re.compile(r"[a-zA-Z0-9]+")
+EVENT_RE = re.compile(r"^event::longmemeval:(?P<qid>[^:]+):s(?P<session>\d+)_c(?P<chunk>\d+)$")
+
+
+def clean_text(value: Any) -> str:
+    return " ".join(str(value or "").split())
+
+
+def norm_tokens(text: Any) -> list[str]:
+    return [m.group(0).lower() for m in TOKEN_RE.finditer(clean_text(text))]
+
+
+def stable_hash(value: str) -> int:
+    return int.from_bytes(hashlib.blake2b(value.encode("utf-8"), digest_size=8).digest(), "big")
+
+
+def embedding_text_key(text: Any) -> str:
+    cleaned = clean_text(text)
+    return hashlib.sha256(cleaned.encode("utf-8")).hexdigest()
+
+
+def iter_sample_texts(samples: Sequence[Mapping[str, Any]]) -> list[dict[str, Any]]:
+    items: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    for sample in samples:
+        qid = clean_text(sample.get("question_id"))
+        question = clean_text(sample.get("question", ""))
+        if question:
+            key = embedding_text_key(question)
+            if key not in seen:
+                seen.add(key)
+                items.append({"key": key, "kind": "question", "question_id": qid, "text": question})
+        for cand in list(sample.get("candidates") or []):
+            text = clean_text(cand.get("text", ""))
+            if not text:
+                continue
+            key = embedding_text_key(text)
+            if key not in seen:
+                seen.add(key)
+                items.append({
+                    "key": key,
+                    "kind": "candidate",
+                    "question_id": qid,
+                    "event_id": clean_text(cand.get("event_id", "")),
+                    "text": text,
+                })
+    if not items:
+        raise RuntimeError("no texts found for embedding precompute")
+    return items
+
+
+def split_name(qid: str, val_ratio: float = 0.2) -> str:
+    bucket = stable_hash(qid) % 10000
+    return "val" if bucket < int(val_ratio * 10000) else "train"
+
+
+def read_jsonl(path: Path) -> list[dict[str, Any]]:
+    if not path.exists():
+        raise FileNotFoundError(f"required jsonl file not found: {path}")
+    rows=[]
+    with path.open("r", encoding="utf-8", errors="replace") as f:
+        for lineno, line in enumerate(f, start=1):
+            if line.strip():
+                try:
+                    rows.append(json.loads(line))
+                except json.JSONDecodeError as exc:
+                    raise RuntimeError(f"invalid jsonl at {path}:{lineno}: {exc}") from exc
+    if not rows:
+        raise RuntimeError(f"required jsonl file is empty: {path}")
+    return rows
+
+
+def write_jsonl(path: Path, rows: Sequence[Mapping[str, Any]]) -> None:
+    with path.open("w", encoding="utf-8") as f:
+        for row in rows:
+            f.write(json.dumps(row, ensure_ascii=False, sort_keys=True) + "\n")
+
+
+def load_shard_rows(shard_glob: str) -> dict[str, list[dict[str, Any]]]:
+    base = Path("/") if shard_glob.startswith("/") else Path()
+    pattern = shard_glob[1:] if shard_glob.startswith("/") else shard_glob
+    shard_paths = sorted(base.glob(pattern))
+    if not shard_paths:
+        raise FileNotFoundError(f"no shard files matched --shard-glob: {shard_glob}")
+    rows_by_qid: dict[str, list[dict[str, Any]]] = {}
+    for shard in shard_paths:
+        data = json.loads(shard.read_text(encoding="utf-8", errors="replace"))
+        if not isinstance(data, list):
+            raise RuntimeError(f"shard is not a JSON list: {shard}")
+        for idx, row in enumerate(data):
+            if not isinstance(row, dict):
+                raise RuntimeError(f"shard row is not an object: {shard}[{idx}]")
+            qid = clean_text(row.get("question_id"))
+            if qid.endswith("_abs"):
+                qid = qid[:-4]
+            if not qid:
+                raise RuntimeError(f"shard row missing question_id: {shard}[{idx}]")
+            rows_by_qid.setdefault(qid, []).append(row)
+    if not rows_by_qid:
+        raise RuntimeError(f"no usable rows loaded from --shard-glob: {shard_glob}")
+    return rows_by_qid
+
+
+def session_text_chunks(*, session_id: str, date: str, turns: list[Mapping[str, Any]], max_chars: int = 7000, max_chunks: int = 0) -> list[str]:
+    chunks: list[str] = []
+    current: list[str] = [f"LongMemEval session_id={session_id} date={date}"]
+    current_len = len(current[0])
+    for index, turn in enumerate(turns, start=1):
+        role = clean_text(turn.get("role", "unknown"))
+        content = clean_text(turn.get("content", ""))
+        if not content:
+            continue
+        part = f"[{session_id} turn={index} role={role}] {content}"
+        if current_len + len(part) + 2 > max_chars and len(current) > 1:
+            chunks.append("\n".join(current))
+            if max_chunks > 0 and len(chunks) >= max_chunks:
+                return chunks
+            current = [f"LongMemEval session_id={session_id} date={date} continued=true"]
+            current_len = len(current[0])
+        current.append(part)
+        current_len += len(part) + 1
+    if len(current) > 1 and (max_chunks <= 0 or len(chunks) < max_chunks):
+        chunks.append("\n".join(current))
+    return chunks
+
+
+def event_text_map_for_row(row: Mapping[str, Any], qid: str) -> dict[str, dict[str, Any]]:
+    sessions = list(row.get("haystack_sessions") or [])
+    session_ids = [clean_text(x) for x in list(row.get("haystack_session_ids") or [])]
+    dates = [clean_text(x) for x in list(row.get("haystack_dates") or [])]
+    out: dict[str, dict[str, Any]] = {}
+    for sidx, sid in enumerate(session_ids):
+        if sidx >= len(sessions):
+            continue
+        chunks = session_text_chunks(
+            session_id=sid,
+            date=dates[sidx] if sidx < len(dates) else "",
+            turns=list(sessions[sidx] or []),
+            max_chars=7000,
+            max_chunks=0,
+        )
+        for cidx, text in enumerate(chunks, start=1):
+            eid = f"event::longmemeval:{qid}:s{sidx:03d}_c{cidx:02d}"
+            out[eid] = {
+                "event_id": eid,
+                "text": text,
+                "session_id": sid,
+                "session_index": sidx,
+                "chunk_index": cidx,
+                "date": dates[sidx] if sidx < len(dates) else "",
+            }
+    return out
+
+
+def choose_row_for_query(rows: list[dict[str, Any]], candidate_ids: Sequence[str], positive_ids: Sequence[str]) -> dict[str, Any] | None:
+    if not rows:
+        return None
+    wanted = set(candidate_ids or []) | set(positive_ids or [])
+    if not wanted:
+        return None
+    qid = clean_text(rows[0].get("question_id"))
+    if qid.endswith("_abs"):
+        qid = qid[:-4]
+    best = None
+    best_hits = -1
+    for row in rows:
+        rqid = clean_text(row.get("question_id"))
+        if rqid.endswith("_abs"):
+            rqid = rqid[:-4]
+        events = set(event_text_map_for_row(row, rqid))
+        hits = len(wanted & events)
+        if hits > best_hits:
+            best = row
+            best_hits = hits
+    return best
+
+
+def token_overlap(a: str, b: str) -> float:
+    at, bt = set(norm_tokens(a)), set(norm_tokens(b))
+    if not at or not bt:
+        return 0.0
+    return len(at & bt) / max(1, len(at | bt))
+
+
+def contains_number_overlap(a: str, b: str) -> float:
+    nums_a = {t for t in norm_tokens(a) if any(ch.isdigit() for ch in t)}
+    nums_b = {t for t in norm_tokens(b) if any(ch.isdigit() for ch in t)}
+    if not nums_a or not nums_b:
+        return 0.0
+    return len(nums_a & nums_b) / max(1, len(nums_a | nums_b))
+
+
+def build_dataset(args: argparse.Namespace) -> None:
+    label_path = Path(args.aligned_queries)
+    out_dir = Path(args.out_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    labels = read_jsonl(label_path)
+    rows_by_qid = load_shard_rows(args.shard_glob)
+    samples=[]; rejected=[]
+    for row in labels:
+        qid = clean_text(row.get("question_id"))
+        if qid.endswith("_abs"):
+            qid = qid[:-4]
+        question = clean_text(row.get("question"))
+        positives = list(row.get("positive_event_ids") or [])
+        hard_negs = set(row.get("hard_negative_event_ids") or [])
+        candidate_ids = list(row.get("candidate_event_ids") or [])
+        source_rows = rows_by_qid.get(qid, [])
+        source_row = choose_row_for_query(source_rows, candidate_ids, positives)
+        if not source_row:
+            rejected.append({"question_id": qid, "reason": "missing_source_row"})
+            continue
+        event_map = event_text_map_for_row(source_row, qid)
+        if not candidate_ids:
+            rejected.append({"question_id": qid, "reason": "missing_candidate_event_ids"})
+            continue
+        before_filter_count = len(candidate_ids)
+        candidate_ids = [eid for eid in candidate_ids if eid in event_map]
+        if len(candidate_ids) != before_filter_count:
+            rejected.append({"question_id": qid, "reason": "candidate_ids_not_in_event_map", "candidate_count": before_filter_count, "mapped_count": len(candidate_ids)})
+            continue
+        if not candidate_ids:
+            rejected.append({"question_id": qid, "reason": "no_candidate_events"})
+            continue
+        if not any(eid in event_map for eid in positives):
+            rejected.append({"question_id": qid, "reason": "positive_not_in_event_map", "positive_event_ids": positives[:10]})
+            continue
+        q_tokens = set(norm_tokens(question))
+        candidates=[]
+        max_session = max(1, len(source_row.get("haystack_session_ids") or []))
+        for eid in candidate_ids:
+            info = event_map[eid]
+            text = clean_text(info["text"])
+            pos = eid in positives
+            hard = eid in hard_negs
+            candidates.append({
+                "event_id": eid,
+                "text": text,
+                "session_id": info.get("session_id", ""),
+                "session_index": int(info.get("session_index", 0)),
+                "chunk_index": int(info.get("chunk_index", 0)),
+                "features": [
+                    token_overlap(question, text),
+                    contains_number_overlap(question, text),
+                    min(1.0, len(set(norm_tokens(text)) & q_tokens) / max(1, len(q_tokens))),
+                    float(info.get("session_index", 0)) / float(max_session),
+                    float(info.get("chunk_index", 0)) / 10.0,
+                    1.0 if hard else 0.0,
+                ],
+                "label": 1 if pos else 0,
+                "role_label": 1 if pos else (2 if hard else 0),
+            })
+        if not any(c["label"] for c in candidates):
+            rejected.append({"question_id": qid, "reason": "positive_filtered_out", "positive_event_ids": positives[:10]})
+            continue
+        metadata = dict(row.get("metadata") or {})
+        metadata.setdefault("question_type", clean_text(source_row.get("question_type", "")))
+        metadata.setdefault("gold_answer", clean_text(source_row.get("answer", "")))
+        metadata.setdefault("answer_session_ids", list(source_row.get("answer_session_ids") or []))
+        samples.append({
+            "question_id": qid,
+            "question": question,
+            "question_type": clean_text(source_row.get("question_type", "")),
+            "split": split_name(qid, args.val_ratio),
+            "positive_event_ids": positives,
+            "positive_path_ids": list(row.get("positive_path_ids") or []),
+            "metadata": metadata,
+            "candidates": candidates,
+        })
+    write_jsonl(out_dir / "samples.jsonl", samples)
+    write_jsonl(out_dir / "rejected.jsonl", rejected)
+    report = {
+        "created_at": time.strftime("%Y-%m-%dT%H:%M:%S%z"),
+        "aligned_queries": str(label_path),
+        "sample_count": len(samples),
+        "rejected_count": len(rejected),
+        "train_count": sum(1 for s in samples if s["split"] == "train"),
+        "val_count": sum(1 for s in samples if s["split"] == "val"),
+        "candidate_count_avg": round(sum(len(s["candidates"]) for s in samples) / max(1, len(samples)), 3),
+        "positive_count_avg": round(sum(sum(c["label"] for c in s["candidates"]) for s in samples) / max(1, len(samples)), 3),
+        "outputs": {"samples": str(out_dir / "samples.jsonl"), "rejected": str(out_dir / "rejected.jsonl")},
+    }
+    (out_dir / "dataset_report.json").write_text(json.dumps(report, ensure_ascii=False, indent=2, sort_keys=True), encoding="utf-8")
+    print(json.dumps(report, ensure_ascii=False, indent=2, sort_keys=True))
+
+
+class OpenAIEmbeddingVectorizer:
+    def __init__(self, *, dim: int, base_url: str, model: str, api_key: str = ""):
+        self.dim = int(dim)
+        self.base_url = base_url.rstrip("/")
+        self.model = model
+        self.api_key = api_key
+        self.cache: dict[str, torch.Tensor] = {}
+
+    def encode_one(self, text: str) -> torch.Tensor:
+        text = clean_text(text)
+        cached = self.cache.get(text)
+        if cached is not None:
+            return cached
+        payload = json.dumps({"model": self.model, "input": text}, ensure_ascii=False).encode("utf-8")
+        headers = {"Content-Type": "application/json"}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        req = urllib.request.Request(self.base_url + "/embeddings", data=payload, method="POST", headers=headers)
+        with urllib.request.urlopen(req, timeout=120) as resp:
+            body = json.loads(resp.read().decode("utf-8", "replace"))
+        data = body.get("data") or []
+        if not data or "embedding" not in data[0]:
+            raise RuntimeError(f"embedding response missing data[0].embedding from {self.base_url}")
+        vec = torch.tensor(list(data[0]["embedding"]), dtype=torch.float32)
+        if vec.numel() != self.dim:
+            raise RuntimeError(f"embedding dim mismatch: got {vec.numel()} expected {self.dim}")
+        vec = vec / vec.norm().clamp_min(1e-6)
+        self.cache[text] = vec
+        return vec
+
+
+class BgeM3DenseVectorizer:
+    def __init__(
+        self,
+        *,
+        dim: int,
+        model_path: str,
+        device: str = "cpu",
+        max_length: int = 8192,
+        strict_max_length: bool = False,
+    ):
+        from transformers import AutoModel, AutoTokenizer
+        self.dim = int(dim)
+        self.cache: dict[str, torch.Tensor] = {}
+        self.device = torch.device(device)
+        self.max_length = int(max_length)
+        self.strict_max_length = bool(strict_max_length)
+        if self.max_length <= 0:
+            raise RuntimeError("--embedding-max-length must be positive")
+        resolved = Path(model_path).resolve()
+        if "bge-m3" not in resolved.name.lower() and "bge-m3" not in str(resolved).lower():
+            raise RuntimeError(f"hf backend is currently wired only for local BAAI/bge-m3, got: {model_path}")
+        self.model_path = str(resolved)
+        self.tokenizer = AutoTokenizer.from_pretrained(
+            str(resolved),
+            local_files_only=True,
+            trust_remote_code=False,
+        )
+        self.model = AutoModel.from_pretrained(
+            str(resolved),
+            local_files_only=True,
+            trust_remote_code=False,
+        ).to(self.device)
+        self.model.eval()
+        hidden_size = int(getattr(self.model.config, "hidden_size", 0) or 0)
+        if hidden_size != self.dim:
+            raise RuntimeError(f"bge-m3 hidden_size mismatch: model has {hidden_size}, --text-dim is {self.dim}")
+
+    def encode_batch(self, texts: Sequence[str], batch_size: int = 4) -> torch.Tensor:
+        cleaned = [clean_text(t) for t in texts]
+        if not cleaned:
+            raise RuntimeError("encode_batch got no texts")
+        out_chunks: list[torch.Tensor] = []
+        with torch.no_grad():
+            for start in range(0, len(cleaned), max(1, int(batch_size))):
+                batch_texts = cleaned[start:start + max(1, int(batch_size))]
+                encoded = self.tokenizer(
+                    batch_texts,
+                    return_tensors="pt",
+                    padding=True,
+                    truncation=not self.strict_max_length,
+                    max_length=self.max_length if not self.strict_max_length else None,
+                )
+                if self.strict_max_length:
+                    token_lengths = encoded["attention_mask"].sum(dim=1)
+                    longest = int(token_lengths.max())
+                    if longest > self.max_length:
+                        offending = int(torch.argmax(token_lengths))
+                        raise RuntimeError(
+                            f"BGE input has {longest} tokens, exceeding strict max_length={self.max_length}; "
+                            f"batch_index={offending} chars={len(batch_texts[offending])}"
+                        )
+                encoded = {k: v.to(self.device) for k, v in encoded.items()}
+                with torch.autocast(
+                    device_type=self.device.type,
+                    dtype=torch.float16,
+                    enabled=self.device.type == "cuda",
+                ):
+                    model_out = self.model(**encoded)
+                if not hasattr(model_out, "last_hidden_state"):
+                    raise RuntimeError("bge-m3 model output missing last_hidden_state")
+                vecs = model_out.last_hidden_state[:, 0].detach().cpu().float()
+                if vecs.shape[1] != self.dim:
+                    raise RuntimeError(f"bge-m3 embedding dim mismatch: got {vecs.shape[1]} expected {self.dim}")
+                vecs = vecs / vecs.norm(dim=1, keepdim=True).clamp_min(1e-6)
+                out_chunks.append(vecs)
+        return torch.cat(out_chunks, dim=0)
+
+    def encode_one(self, text: str) -> torch.Tensor:
+        text = clean_text(text)
+        cached = self.cache.get(text)
+        if cached is not None:
+            return cached
+        vec = self.encode_batch([text], batch_size=1)[0]
+        self.cache[text] = vec
+        return vec
+
+
+class EmbeddingCacheVectorizer:
+    def __init__(self, *, cache_dir: str, dim: int, expected_backend: str = "", expected_model: str = ""):
+        root = Path(cache_dir)
+        manifest_path = root / "manifest.json"
+        tensor_path = root / "embeddings.pt"
+        if not manifest_path.exists():
+            raise FileNotFoundError(f"embedding cache manifest not found: {manifest_path}")
+        if not tensor_path.exists():
+            raise FileNotFoundError(f"embedding cache tensor not found: {tensor_path}")
+        self.manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+        self.dim = int(dim)
+        if int(self.manifest.get("text_dim", 0) or 0) != self.dim:
+            raise RuntimeError(f"embedding cache dim mismatch: cache has {self.manifest.get('text_dim')} expected {self.dim}")
+        backend = clean_text(self.manifest.get("embedding_backend", ""))
+        model = clean_text(self.manifest.get("embedding_model", ""))
+        if expected_backend and backend != expected_backend:
+            raise RuntimeError(f"embedding cache backend mismatch: cache has {backend} expected {expected_backend}")
+        if expected_model and model != expected_model:
+            raise RuntimeError(f"embedding cache model mismatch: cache has {model} expected {expected_model}")
+        payload = torch.load(tensor_path, map_location="cpu", weights_only=True)
+        keys = list(payload.get("keys") or [])
+        vectors = payload.get("vectors")
+        if not keys or vectors is None:
+            raise RuntimeError(f"invalid embedding cache payload: {tensor_path}")
+        if len(keys) != int(vectors.shape[0]):
+            raise RuntimeError(f"embedding cache row mismatch: {len(keys)} keys vs {vectors.shape[0]} vectors")
+        if int(vectors.shape[1]) != self.dim:
+            raise RuntimeError(f"embedding cache tensor dim mismatch: {vectors.shape[1]} expected {self.dim}")
+        self.keys = keys
+        self.index = {k: i for i, k in enumerate(keys)}
+        if len(self.index) != len(keys):
+            raise RuntimeError("embedding cache contains duplicate keys")
+        self.vectors = vectors.float().contiguous()
+
+    def encode_one(self, text: str) -> torch.Tensor:
+        key = embedding_text_key(text)
+        idx = self.index.get(key)
+        if idx is None:
+            preview = clean_text(text)[:120]
+            raise RuntimeError(f"embedding cache miss: key={key} preview={preview!r}")
+        return self.vectors[idx]
+
+
+def build_vectorizer(args: argparse.Namespace, device: torch.device):
+    backend = clean_text(getattr(args, "embedding_backend", ""))
+    cache_dir = clean_text(getattr(args, "embedding_cache", ""))
+    if not backend:
+        raise RuntimeError("embedding backend is required; pass --embedding-backend openai or --embedding-backend hf")
+    if cache_dir:
+        return EmbeddingCacheVectorizer(
+            cache_dir=cache_dir,
+            dim=args.text_dim,
+            expected_backend=backend,
+            expected_model=clean_text(getattr(args, "embedding_model", "")),
+        )
+    if backend == "openai":
+        base_url = clean_text(getattr(args, "embedding_base_url", ""))
+        model = clean_text(getattr(args, "embedding_model", ""))
+        api_key = clean_text(getattr(args, "embedding_api_key", ""))
+        if not base_url or not model:
+            raise RuntimeError("openai embedding backend requires explicit --embedding-base-url and --embedding-model")
+        return OpenAIEmbeddingVectorizer(dim=args.text_dim, base_url=base_url, model=model, api_key=api_key)
+    if backend == "hf":
+        model_path = clean_text(getattr(args, "embedding_model", ""))
+        if not model_path:
+            raise RuntimeError("hf embedding backend requires explicit --embedding-model local path")
+        if not os.path.exists(model_path):
+            raise RuntimeError(f"hf embedding backend requires a local model path; not found: {model_path}")
+        return BgeM3DenseVectorizer(dim=args.text_dim, model_path=model_path, device=str(device), max_length=args.embedding_max_length)
+    raise RuntimeError(f"unsupported embedding backend: {backend}")
+
+
+class V2EvidenceScorer(nn.Module):
+    def __init__(self, text_dim: int, feature_dim: int, hidden_dim: int = 256, layers: int = 2, roles: int = 3):
+        super().__init__()
+        self.query_proj = nn.Sequential(nn.LayerNorm(text_dim), nn.Linear(text_dim, hidden_dim), nn.SiLU())
+        self.event_proj = nn.Sequential(nn.LayerNorm(text_dim), nn.Linear(text_dim, hidden_dim), nn.SiLU())
+        self.feature_proj = nn.Sequential(nn.LayerNorm(feature_dim), nn.Linear(feature_dim, hidden_dim // 2), nn.SiLU())
+        self.session_embedding = nn.Embedding(256, hidden_dim)
+        self.chunk_embedding = nn.Embedding(32, hidden_dim)
+        encoder_layer = nn.TransformerEncoderLayer(
+            d_model=hidden_dim,
+            nhead=8,
+            dim_feedforward=hidden_dim * 4,
+            dropout=0.1,
+            activation="gelu",
+            batch_first=True,
+            norm_first=True,
+        )
+        self.graph_encoder = nn.TransformerEncoder(encoder_layer, num_layers=max(1, int(layers)))
+        pair_dim = hidden_dim * 4 + hidden_dim // 2
+        self.event_head = nn.Sequential(nn.LayerNorm(pair_dim), nn.Linear(pair_dim, hidden_dim), nn.SiLU(), nn.Linear(hidden_dim, 1))
+        self.pack_head = nn.Sequential(nn.LayerNorm(pair_dim), nn.Linear(pair_dim, hidden_dim), nn.SiLU(), nn.Linear(hidden_dim, 1))
+        self.role_head = nn.Sequential(nn.LayerNorm(pair_dim), nn.Linear(pair_dim, hidden_dim), nn.SiLU(), nn.Linear(hidden_dim, roles))
+
+    def forward(self, q_vec: torch.Tensor, e_vec: torch.Tensor, features: torch.Tensor, session_idx: torch.Tensor, chunk_idx: torch.Tensor, mask: torch.Tensor) -> dict[str, torch.Tensor]:
+        q = self.query_proj(q_vec)
+        e = self.event_proj(e_vec)
+        f = self.feature_proj(features)
+        session_idx = session_idx.clamp_min(0).clamp_max(255)
+        chunk_idx = chunk_idx.clamp_min(0).clamp_max(31)
+        h = e + self.session_embedding(session_idx) + self.chunk_embedding(chunk_idx)
+        h = self.graph_encoder(h, src_key_padding_mask=~mask)
+        qx = q.unsqueeze(1).expand_as(h)
+        pair = torch.cat([qx, h, qx * h, torch.abs(qx - h), f], dim=-1)
+        event_logits = self.event_head(pair).squeeze(-1).masked_fill(~mask, -1e4)
+        pack_logits = self.pack_head(pair).squeeze(-1).masked_fill(~mask, -1e4)
+        role_logits = self.role_head(pair).masked_fill(~mask.unsqueeze(-1), 0.0)
+        return {"event_logits": event_logits, "pack_logits": pack_logits, "role_logits": role_logits}
+
+
+@dataclass
+class Batch:
+    q_vec: torch.Tensor
+    e_vec: torch.Tensor
+    features: torch.Tensor
+    session_idx: torch.Tensor
+    chunk_idx: torch.Tensor
+    mask: torch.Tensor
+    labels: torch.Tensor
+    role_labels: torch.Tensor
+    qids: list[str]
+    event_ids: list[list[str]]
+
+
+def make_batch(samples: Sequence[Mapping[str, Any]], vectorizer: Any, text_dim: int, feature_dim: int, device: torch.device) -> Batch:
+    max_c = max(len(s["candidates"]) for s in samples)
+    b = len(samples)
+    q_vec = torch.zeros((b, text_dim), dtype=torch.float32)
+    e_vec = torch.zeros((b, max_c, text_dim), dtype=torch.float32)
+    features = torch.zeros((b, max_c, feature_dim), dtype=torch.float32)
+    session_idx = torch.zeros((b, max_c), dtype=torch.long)
+    chunk_idx = torch.zeros((b, max_c), dtype=torch.long)
+    mask = torch.zeros((b, max_c), dtype=torch.bool)
+    labels = torch.zeros((b, max_c), dtype=torch.float32)
+    role_labels = torch.zeros((b, max_c), dtype=torch.long)
+    qids=[]; event_ids=[]
+    for i, sample in enumerate(samples):
+        qids.append(str(sample["question_id"])); event_ids.append([])
+        q_vec[i] = vectorizer.encode_one(str(sample.get("question", "")))
+        for j, cand in enumerate(sample["candidates"]):
+            e_vec[i, j] = vectorizer.encode_one(str(cand.get("text", "")))
+            feat = list(cand.get("features") or [])
+            features[i, j, : min(feature_dim, len(feat))] = torch.tensor(feat[:feature_dim], dtype=torch.float32)
+            session_idx[i, j] = int(cand.get("session_index", 0) or 0)
+            chunk_idx[i, j] = int(cand.get("chunk_index", 0) or 0)
+            mask[i, j] = True
+            labels[i, j] = float(cand.get("label", 0) or 0)
+            role_labels[i, j] = int(cand.get("role_label", 0) or 0)
+            event_ids[-1].append(str(cand.get("event_id", "")))
+    return Batch(q_vec.to(device), e_vec.to(device), features.to(device), session_idx.to(device), chunk_idx.to(device), mask.to(device), labels.to(device), role_labels.to(device), qids, event_ids)
+
+
+def ranking_loss(event_logits: torch.Tensor, labels: torch.Tensor, mask: torch.Tensor) -> torch.Tensor:
+    losses=[]
+    for logits, y, m in zip(event_logits, labels, mask):
+        valid_logits = logits[m]
+        valid_y = y[m]
+        pos = valid_y > 0.5
+        if not bool(pos.any()):
+            continue
+        log_probs = F.log_softmax(valid_logits, dim=0)
+        target = valid_y / valid_y.sum().clamp_min(1.0)
+        losses.append(-(target * log_probs).sum())
+    if not losses:
+        return event_logits.sum() * 0.0
+    return torch.stack(losses).mean()
+
+
+def eval_model(model: V2EvidenceScorer, samples: Sequence[Mapping[str, Any]], vectorizer: Any, args: argparse.Namespace, device: torch.device) -> dict[str, Any]:
+    model.eval()
+    totals={"n":0,"event_recall_at_1":0,"event_recall_at_5":0,"event_recall_at_10":0,"pack_recall_at_10":0,"mrr":0.0}
+    with torch.no_grad():
+        for start in range(0, len(samples), args.batch_size):
+            batch_samples=samples[start:start+args.batch_size]
+            batch=make_batch(batch_samples, vectorizer, args.text_dim, args.feature_dim, device)
+            out=model(batch.q_vec,batch.e_vec,batch.features,batch.session_idx,batch.chunk_idx,batch.mask)
+            event_scores=out["event_logits"].detach().cpu()
+            pack_scores=out["pack_logits"].detach().cpu()
+            labels=batch.labels.detach().cpu()
+            mask=batch.mask.detach().cpu()
+            for i in range(len(batch_samples)):
+                valid=torch.nonzero(mask[i], as_tuple=False).squeeze(-1)
+                if valid.numel()==0: continue
+                pos=set(torch.nonzero(labels[i][valid]>0.5, as_tuple=False).squeeze(-1).tolist())
+                if not pos: continue
+                order=torch.argsort(event_scores[i][valid], descending=True).tolist()
+                pack_order=torch.argsort(pack_scores[i][valid], descending=True).tolist()
+                totals["n"]+=1
+                totals["event_recall_at_1"] += int(any(idx in pos for idx in order[:1]))
+                totals["event_recall_at_5"] += int(any(idx in pos for idx in order[:5]))
+                totals["event_recall_at_10"] += int(any(idx in pos for idx in order[:10]))
+                totals["pack_recall_at_10"] += int(any(idx in pos for idx in pack_order[:10]))
+                first_rank=next((r+1 for r,idx in enumerate(order) if idx in pos), None)
+                totals["mrr"] += 0.0 if first_rank is None else 1.0/first_rank
+    n=max(1, totals["n"])
+    return {k:(round(v/n,6) if k!="n" else v) for k,v in totals.items()}
+
+
+def precompute_embeddings(args: argparse.Namespace) -> None:
+    out_dir = Path(args.out_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    tensor_path = out_dir / "embeddings.pt"
+    manifest_path = out_dir / "manifest.json"
+    items_path = out_dir / "items.jsonl"
+    if (tensor_path.exists() or manifest_path.exists() or items_path.exists()) and not args.overwrite:
+        raise RuntimeError(f"embedding cache output already exists; pass --overwrite explicitly: {out_dir}")
+    samples = read_jsonl(Path(args.samples))
+    if args.limit > 0:
+        samples = samples[: args.limit]
+    if not samples:
+        raise RuntimeError("no samples for embedding precompute")
+    if not args.cpu and not torch.cuda.is_available():
+        raise RuntimeError("CUDA is unavailable; pass --cpu explicitly for CPU precompute")
+    if args.embedding_backend != "hf":
+        raise RuntimeError("precompute currently supports only --embedding-backend hf for local bge-m3")
+    device = torch.device("cpu" if args.cpu else "cuda")
+    vectorizer = BgeM3DenseVectorizer(
+        dim=args.text_dim,
+        model_path=args.embedding_model,
+        device=str(device),
+        max_length=args.embedding_max_length,
+    )
+    items = iter_sample_texts(samples)
+    keys = [item["key"] for item in items]
+    texts = [item["text"] for item in items]
+    vectors: list[torch.Tensor] = []
+    total = len(texts)
+    started = time.time()
+    for start in range(0, total, args.batch_size):
+        batch_texts = texts[start:start + args.batch_size]
+        vecs = vectorizer.encode_batch(batch_texts, batch_size=args.batch_size)
+        vectors.append(vecs.to(dtype=torch.float16 if args.dtype == "float16" else torch.float32))
+        done = min(total, start + len(batch_texts))
+        if done == total or done % max(1, args.log_every) == 0:
+            elapsed = time.time() - started
+            print(json.dumps({"done": done, "total": total, "elapsed_sec": round(elapsed, 3)}, ensure_ascii=False), flush=True)
+    matrix = torch.cat(vectors, dim=0).contiguous()
+    if matrix.shape != (len(keys), args.text_dim):
+        raise RuntimeError(f"embedding matrix shape mismatch: got {tuple(matrix.shape)} expected {(len(keys), args.text_dim)}")
+    torch.save({"keys": keys, "vectors": matrix}, tensor_path)
+    item_rows=[]
+    for item in items:
+        item_rows.append({
+            "key": item["key"],
+            "kind": item.get("kind", ""),
+            "question_id": item.get("question_id", ""),
+            "event_id": item.get("event_id", ""),
+            "text_len": len(item.get("text", "")),
+            "preview": clean_text(item.get("text", ""))[:200],
+        })
+    write_jsonl(items_path, item_rows)
+    manifest = {
+        "created_at": time.strftime("%Y-%m-%dT%H:%M:%S%z"),
+        "samples": str(Path(args.samples).resolve()),
+        "sample_count": len(samples),
+        "unique_text_count": len(keys),
+        "text_dim": int(args.text_dim),
+        "dtype": args.dtype,
+        "embedding_backend": args.embedding_backend,
+        "embedding_model": clean_text(args.embedding_model),
+        "embedding_max_length": int(args.embedding_max_length),
+        "device": str(device),
+        "outputs": {"tensor": str(tensor_path), "items": str(items_path), "manifest": str(manifest_path)},
+    }
+    manifest_path.write_text(json.dumps(manifest, ensure_ascii=False, indent=2, sort_keys=True), encoding="utf-8")
+    print(json.dumps(manifest, ensure_ascii=False, indent=2, sort_keys=True))
+
+
+def smoke(args: argparse.Namespace) -> None:
+    out_dir = Path(args.out_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    samples = read_jsonl(Path(args.samples))
+    if args.limit > 0:
+        samples = samples[: args.limit]
+    if not samples:
+        raise RuntimeError("no samples for smoke")
+    if not args.cpu and not torch.cuda.is_available():
+        raise RuntimeError("CUDA is unavailable; pass --cpu explicitly for CPU smoke")
+    device = torch.device("cpu" if args.cpu else "cuda")
+    vectorizer = build_vectorizer(args, device)
+    model = V2EvidenceScorer(args.text_dim, args.feature_dim, args.hidden_dim, args.layers).to(device)
+    model.eval()
+    batch = make_batch(samples, vectorizer, args.text_dim, args.feature_dim, device)
+    with torch.no_grad():
+        out = model(batch.q_vec, batch.e_vec, batch.features, batch.session_idx, batch.chunk_idx, batch.mask)
+        loss_rank = ranking_loss(out["event_logits"], batch.labels, batch.mask)
+        pack_loss = F.binary_cross_entropy_with_logits(out["pack_logits"][batch.mask], batch.labels[batch.mask])
+        role_loss = F.cross_entropy(out["role_logits"][batch.mask], batch.role_labels[batch.mask])
+    metrics = eval_model(model, samples, vectorizer, args, device)
+    report = {
+        "status": "ok",
+        "mode": "forward_only_no_optimizer_step",
+        "device": str(device),
+        "sample_count": len(samples),
+        "candidate_count_max": max(len(s.get("candidates", [])) for s in samples),
+        "candidate_count_avg": round(sum(len(s.get("candidates", [])) for s in samples) / max(1, len(samples)), 3),
+        "losses": {
+            "ranking_loss": round(float(loss_rank.detach().cpu()), 6),
+            "pack_loss": round(float(pack_loss.detach().cpu()), 6),
+            "role_loss": round(float(role_loss.detach().cpu()), 6),
+        },
+        "metrics": metrics,
+        "embedding_backend": clean_text(getattr(args, "embedding_backend", "")),
+        "embedding_model": clean_text(getattr(args, "embedding_model", "")),
+        "embedding_cache": clean_text(getattr(args, "embedding_cache", "")),
+        "embedding_max_length": int(getattr(args, "embedding_max_length", 0) or 0),
+        "text_dim": int(args.text_dim),
+        "hidden_dim": int(args.hidden_dim),
+        "layers": int(args.layers),
+    }
+    (out_dir / "smoke_report.json").write_text(json.dumps(report, ensure_ascii=False, indent=2, sort_keys=True), encoding="utf-8")
+    print(json.dumps(report, ensure_ascii=False, indent=2, sort_keys=True))
+
+
+def train(args: argparse.Namespace) -> None:
+    out_dir=Path(args.out_dir); out_dir.mkdir(parents=True, exist_ok=True)
+    samples=read_jsonl(Path(args.samples))
+    if args.limit>0:
+        samples=samples[:args.limit]
+    train_samples=[s for s in samples if s.get("split") == "train"]
+    val_samples=[s for s in samples if s.get("split") == "val"]
+    if not train_samples:
+        raise RuntimeError("no train samples")
+    if not val_samples:
+        raise RuntimeError("no val samples; rebuild dataset with a non-empty validation split")
+    if not args.cpu and not torch.cuda.is_available():
+        raise RuntimeError("CUDA is unavailable; pass --cpu explicitly for CPU train")
+    device=torch.device("cpu" if args.cpu else "cuda")
+    vectorizer=build_vectorizer(args, device)
+    model=V2EvidenceScorer(args.text_dim,args.feature_dim,args.hidden_dim,args.layers).to(device)
+    opt=torch.optim.AdamW(model.parameters(), lr=args.lr, weight_decay=args.weight_decay)
+    best=None
+    history=[]
+    rng=random.Random(args.seed)
+    for epoch in range(1,args.epochs+1):
+        model.train(); rng.shuffle(train_samples)
+        losses=[]
+        for start in range(0,len(train_samples),args.batch_size):
+            batch_samples=train_samples[start:start+args.batch_size]
+            batch=make_batch(batch_samples, vectorizer, args.text_dim, args.feature_dim, device)
+            out=model(batch.q_vec,batch.e_vec,batch.features,batch.session_idx,batch.chunk_idx,batch.mask)
+            loss_rank=ranking_loss(out["event_logits"],batch.labels,batch.mask)
+            bce=F.binary_cross_entropy_with_logits(out["pack_logits"][batch.mask], batch.labels[batch.mask])
+            role=F.cross_entropy(out["role_logits"][batch.mask], batch.role_labels[batch.mask])
+            loss=loss_rank + args.pack_loss_weight*bce + args.role_loss_weight*role
+            opt.zero_grad(set_to_none=True); loss.backward(); nn.utils.clip_grad_norm_(model.parameters(), 1.0); opt.step()
+            losses.append(float(loss.detach().cpu()))
+        val=eval_model(model,val_samples,vectorizer,args,device)
+        train_eval=eval_model(model,train_samples[:min(len(train_samples),100)],vectorizer,args,device)
+        summary={"epoch":epoch,"loss":round(sum(losses)/max(1,len(losses)),6),"train":train_eval,"val":val}
+        history.append(summary)
+        print(json.dumps(summary,ensure_ascii=False), flush=True)
+        score=val.get("event_recall_at_5",0.0)+0.1*val.get("mrr",0.0)
+        if best is None or score > best[0]:
+            best=(score,epoch)
+            torch.save({"model_state":model.state_dict(),"args":vars(args),"epoch":epoch,"val":val}, out_dir/"tmcra_v2_scorer.pt")
+    (out_dir/"train_history.json").write_text(json.dumps(history,ensure_ascii=False,indent=2),encoding="utf-8")
+    report={"best": {"score": best[0] if best else None, "epoch": best[1] if best else None}, "final": history[-1] if history else {}, "checkpoint": str(out_dir/"tmcra_v2_scorer.pt")}
+    (out_dir/"train_report.json").write_text(json.dumps(report,ensure_ascii=False,indent=2,sort_keys=True),encoding="utf-8")
+    print(json.dumps(report,ensure_ascii=False,indent=2,sort_keys=True))
+
+
+def main() -> int:
+    p=argparse.ArgumentParser(description="TMCRA v2 LongMemEval semantic-graph scorer pipeline")
+    sub=p.add_subparsers(dest="cmd", required=True)
+    b=sub.add_parser("build")
+    b.add_argument("--aligned-queries", required=True)
+    b.add_argument("--shard-glob", default=os.getenv("TMCRA_SHARD_GLOB", "runs/shard_*.json"))
+    b.add_argument("--out-dir", required=True)
+    b.add_argument("--val-ratio", type=float, default=0.2)
+    pc=sub.add_parser("precompute")
+    pc.add_argument("--samples", required=True)
+    pc.add_argument("--out-dir", required=True)
+    pc.add_argument("--text-dim", type=int, default=1024)
+    pc.add_argument("--embedding-backend", choices=["hf"], required=True)
+    pc.add_argument("--embedding-model", required=True)
+    pc.add_argument("--embedding-max-length", type=int, default=8192)
+    pc.add_argument("--batch-size", type=int, default=2)
+    pc.add_argument("--log-every", type=int, default=100)
+    pc.add_argument("--dtype", choices=["float16", "float32"], default="float16")
+    pc.add_argument("--limit", type=int, default=0)
+    pc.add_argument("--overwrite", action="store_true")
+    pc.add_argument("--cpu", action="store_true")
+    t=sub.add_parser("train")
+    t.add_argument("--samples", required=True)
+    t.add_argument("--out-dir", required=True)
+    t.add_argument("--text-dim", type=int, default=1024)
+    t.add_argument("--embedding-backend", choices=["openai", "hf"], required=True)
+    t.add_argument("--embedding-base-url", default="")
+    t.add_argument("--embedding-model", default="")
+    t.add_argument("--embedding-cache", default="")
+    t.add_argument("--embedding-api-key", default="")
+    t.add_argument("--embedding-max-length", type=int, default=8192)
+    t.add_argument("--feature-dim", type=int, default=6)
+    t.add_argument("--hidden-dim", type=int, default=256)
+    t.add_argument("--layers", type=int, default=2)
+    t.add_argument("--batch-size", type=int, default=8)
+    t.add_argument("--epochs", type=int, default=8)
+    t.add_argument("--lr", type=float, default=2e-4)
+    t.add_argument("--weight-decay", type=float, default=0.01)
+    t.add_argument("--pack-loss-weight", type=float, default=0.3)
+    t.add_argument("--role-loss-weight", type=float, default=0.15)
+    t.add_argument("--seed", type=int, default=13)
+    t.add_argument("--limit", type=int, default=0)
+    t.add_argument("--cpu", action="store_true")
+    sm=sub.add_parser("smoke")
+    sm.add_argument("--samples", required=True)
+    sm.add_argument("--out-dir", required=True)
+    sm.add_argument("--text-dim", type=int, default=1024)
+    sm.add_argument("--embedding-backend", choices=["openai", "hf"], required=True)
+    sm.add_argument("--embedding-base-url", default="")
+    sm.add_argument("--embedding-model", default="")
+    sm.add_argument("--embedding-cache", default="")
+    sm.add_argument("--embedding-api-key", default="")
+    sm.add_argument("--embedding-max-length", type=int, default=8192)
+    sm.add_argument("--feature-dim", type=int, default=6)
+    sm.add_argument("--hidden-dim", type=int, default=96)
+    sm.add_argument("--layers", type=int, default=1)
+    sm.add_argument("--batch-size", type=int, default=8)
+    sm.add_argument("--limit", type=int, default=4)
+    sm.add_argument("--cpu", action="store_true")
+    args=p.parse_args()
+    if args.cmd == "build": build_dataset(args)
+    elif args.cmd == "precompute": precompute_embeddings(args)
+    elif args.cmd == "train": train(args)
+    elif args.cmd == "smoke": smoke(args)
+    return 0
+
+if __name__ == "__main__":
+    raise SystemExit(main())

benchmarks/longmemeval/src/tmcra_benchmark/legacy/tmcra_v3_online_runtime.py

@@ -0,0 +1,1867 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import hashlib
+import importlib.util
+import json
+import os
+import re
+import sqlite3
+import sys
+import time
+from collections import Counter
+from pathlib import Path
+from typing import Any, Iterable, Mapping, Sequence
+
+import torch
+
+from build_v3_runtime_dataset import covered_windows, rrank
+from tmcra_v2_lme_pipeline import BgeM3DenseVectorizer
+from tmcra_v3_reranker import ChannelAwareMemoryReranker
+from tmcra_model_assets import load_optional_hf_model_manifest
+from tmcra_v3_schema import CHANNEL_NAMES, SCHEMA_VERSION, clean_text, write_jsonl
+from tmcra_v3_recall_planner import (
+    DEEPSEEK_FLASH_MODEL,
+    DeepSeekFlashRecallPlanner,
+    RecallPlannerError,
+    apply_recall_plan,
+)
+
+
+LEGACY_CHUNK_ID_RE = re.compile(r"^s(?P<session>\d+)_c(?P<parent>\d+)$")
+MESSAGE_ID_RE = re.compile(r"^s(?P<session>\d+)_m(?P<parent>\d+)$")
+EVENT_PARENT_RE = re.compile(r":s(?P<session>\d+)_[cm](?P<parent>\d+)$")
+CURRENT_FAST_STATES = frozenset(
+    {"active", "parallel_active", "promoted", "challenged"}
+)
+ONLINE_INDEX_SCHEMA_VERSION = "tmcra.v3.online-index.3"
+FAST_SEMANTIC_STATE_POLICY = (
+    "current-fast-states-v1:" + ",".join(sorted(CURRENT_FAST_STATES))
+)
+INGEST_PREFIX_RE = re.compile(r"^\[[^\]\n]+\]\s+user:\s*", flags=re.IGNORECASE)
+SESSION_HEADER_RE = re.compile(
+    r"^LongMemEval session_id=(?P<session_id>\S+) date=(?P<date>.+?)(?: continued=true)? \[",
+    flags=re.DOTALL,
+)
+
+
+def read_jsonl(path: Path) -> list[dict[str, Any]]:
+    rows: list[dict[str, Any]] = []
+    with path.open("r", encoding="utf-8", errors="strict") as handle:
+        for line_no, line in enumerate(handle, start=1):
+            if not line.strip():
+                continue
+            value = json.loads(line)
+            if not isinstance(value, dict):
+                raise RuntimeError(f"row is not an object at {path}:{line_no}")
+            rows.append(value)
+    if not rows:
+        raise RuntimeError(f"no rows: {path}")
+    return rows
+
+
+def atomic_torch_save(payload: Mapping[str, Any], target: Path) -> None:
+    target.parent.mkdir(parents=True, exist_ok=True)
+    temporary = target.with_suffix(target.suffix + ".tmp")
+    torch.save(dict(payload), temporary)
+    os.replace(temporary, target)
+
+
+def sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def load_native_harness(path: Path, repo: Path):
+    resolved_repo = str(repo.resolve())
+    if resolved_repo not in sys.path:
+        sys.path.insert(0, resolved_repo)
+    module_name = "tmcra_v3_native_runtime_harness"
+    spec = importlib.util.spec_from_file_location(module_name, path)
+    if spec is None or spec.loader is None:
+        raise RuntimeError(f"cannot import native TMCRA harness: {path}")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[module_name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+def graph_runtime_env(args: argparse.Namespace) -> dict[str, str]:
+    values = {
+        "TMCRA_RETRIEVAL_MODE": "hybrid_node_scored",
+        "TMCRA_NODE_MODEL_PATH": str(Path(args.node_model).resolve()),
+        "TMCRA_PATH_MODEL_PATH": str(Path(args.path_model).resolve()),
+        "TMCRA_NODE_MODEL_DEVICE": args.graph_device,
+        "TMCRA_SUPPORT_PATH_K": str(args.support_path_k),
+        "TMCRA_PATH_TUNNEL_RESCUE_K": str(args.path_tunnel_rescue_k),
+        "TMCRA_CANDIDATE_EVENT_K": str(args.candidate_event_k),
+        "TMCRA_DEEPSEEK_GRAPH_MODEL_MODE": "off",
+        "TMCRA_TOPIC_BUCKET_MODE": "off",
+        "TMCRA_LLM_CHANNEL_PLANNER_MODE": "off",
+        "TMCRA_LLM_EVIDENCE_SELECTOR_MODE": "off",
+        "TMCRA_EVIDENCE_UNIT_PLANNER_MODE": "off",
+        "TMCRA_UNIFIED_OPERATION_PLANNER_MODE": "off",
+    }
+    for name, value in values.items():
+        os.environ[name] = value
+    return values
+
+
+def scope_counts(db_path: Path, scope_id: str) -> dict[str, int]:
+    with sqlite3.connect(db_path) as connection:
+        output = {}
+        for table in ("records", "memory_edges", "audit_turn_log", "audit_retrieval_log"):
+            output[table] = int(
+                connection.execute(f'SELECT COUNT(*) FROM "{table}" WHERE scope_id=?', (scope_id,)).fetchone()[0]
+            )
+    return output
+
+
+def scope_fingerprint(db_path: Path, scope_id: str) -> str:
+    relevant_tables = ("records", "memory_edges", "slot_heads", "slot_history")
+    snapshot: dict[str, Any] = {}
+    with sqlite3.connect(db_path) as connection:
+        connection.row_factory = sqlite3.Row
+        for table in relevant_tables:
+            exists = connection.execute(
+                "SELECT 1 FROM sqlite_master WHERE type='table' AND name=?", (table,)
+            ).fetchone()
+            if exists is None:
+                snapshot[table] = None
+                continue
+            rows = []
+            for row in connection.execute(
+                f'SELECT * FROM "{table}" WHERE scope_id=?', (scope_id,)
+            ):
+                normalized: dict[str, Any] = {}
+                for key in row.keys():
+                    value = row[key]
+                    if key.endswith("_json") and isinstance(value, str):
+                        try:
+                            value = json.loads(value)
+                        except json.JSONDecodeError as exc:
+                            raise RuntimeError(
+                                f"invalid JSON in {table}.{key} while fingerprinting scope"
+                            ) from exc
+                    normalized[key] = value
+                rows.append(normalized)
+            snapshot[table] = sorted(
+                rows,
+                key=lambda item: json.dumps(
+                    item, ensure_ascii=False, sort_keys=True, separators=(",", ":")
+                ),
+            )
+    return hashlib.sha256(
+        json.dumps(
+            snapshot, ensure_ascii=False, sort_keys=True, separators=(",", ":")
+        ).encode("utf-8")
+    ).hexdigest()
+
+
+def load_recent_dialogue_context(
+    db_path: Path,
+    scope_id: str,
+    *,
+    current_query: str,
+    limit: int = 8,
+) -> list[dict[str, Any]]:
+    """Load a small, metadata-free dialogue tail for planner reference resolution."""
+    if limit <= 0 or limit > 8:
+        raise RuntimeError("recent dialogue limit must be between 1 and 8")
+    with sqlite3.connect(db_path) as connection:
+        columns = {
+            str(row[1]) for row in connection.execute('PRAGMA table_info("audit_turn_log")')
+        }
+        required = {"scope_id", "event_index", "payload_json"}
+        if not required.issubset(columns):
+            raise RuntimeError(
+                "audit_turn_log lacks required production dialogue columns: "
+                + ",".join(sorted(required - columns))
+            )
+        rows = connection.execute(
+            'SELECT event_index,payload_json FROM "audit_turn_log" '
+            "WHERE scope_id=? ORDER BY event_index DESC LIMIT ?",
+            (scope_id, limit + 1),
+        ).fetchall()
+    dialogue: list[dict[str, Any]] = []
+    for event_index, raw_payload in reversed(rows):
+        try:
+            payload = json.loads(raw_payload)
+        except (TypeError, json.JSONDecodeError) as exc:
+            raise RuntimeError(f"invalid audit_turn_log payload at event_index={event_index}") from exc
+        if not isinstance(payload, Mapping):
+            raise RuntimeError(f"audit_turn_log payload is not an object at event_index={event_index}")
+        speaker = clean_text(payload.get("speaker")).lower()
+        text = clean_text(payload.get("text"))
+        if speaker not in {"user", "assistant"} or not text:
+            raise RuntimeError(f"audit_turn_log turn is not planner-safe at event_index={event_index}")
+        dialogue.append(
+            {"turn_index": int(event_index), "speaker": speaker, "text": text}
+        )
+    current = clean_text(current_query)
+    if dialogue and dialogue[-1]["speaker"] == "user" and dialogue[-1]["text"] == current:
+        dialogue.pop()
+    return dialogue[-limit:]
+
+
+def append_layered_retrieval_audit(
+    *,
+    repo: Path,
+    db_path: Path,
+    scope_id: str,
+    operation_id: str,
+    evidence: Mapping[str, Any],
+    debug: Mapping[str, Any],
+) -> dict[str, Any]:
+    """Persist the final layered retrieval decision without rewriting graph state."""
+    resolved_repo = str(repo.resolve())
+    if resolved_repo not in sys.path:
+        sys.path.insert(0, resolved_repo)
+    from experiments.replacement.memory_graph import SQLiteSessionMemoryStore
+
+    with sqlite3.connect(db_path) as connection:
+        row = connection.execute(
+            "SELECT value_json FROM meta WHERE scope_id=? AND key='audit_retention'",
+            (scope_id,),
+        ).fetchone()
+    if row is None:
+        raise RuntimeError(f"{scope_id}: missing audit_retention metadata")
+    audit_retention = int(json.loads(row[0]) or 0)
+    if audit_retention <= 0:
+        raise RuntimeError(f"{scope_id}: invalid audit_retention metadata: {audit_retention}")
+
+    windows = list(evidence.get("evidence_windows") or [])
+    memory_contexts = [
+        context
+        for window in windows
+        for context in list(window.get("memory_contexts") or [])
+    ]
+    graph = dict(debug.get("graph") or {})
+    payload = {
+        "event_kind": "tmcra.v3.layered_retrieval",
+        "schema_version": "tmcra.v3.layered-retrieval-audit.1",
+        "operation_id": clean_text(operation_id),
+        "question_id": clean_text(evidence.get("question_id")),
+        "query": clean_text(evidence.get("question")),
+        "question_date": clean_text(evidence.get("question_date")),
+        "recall_plan": dict(evidence.get("recall_plan") or {}),
+        "selected_memory_ids": [
+            clean_text(window.get("memory_id"))
+            for window in windows
+            if clean_text(window.get("memory_id"))
+        ],
+        "selected_session_ids": list(evidence.get("selected_session_ids") or []),
+        "selected_capsule_ids": sorted(
+            {
+                clean_text(context.get("capsule_id"))
+                for context in memory_contexts
+                if clean_text(context.get("capsule_id"))
+            }
+        ),
+        "selected_claim_ids": sorted(
+            {
+                clean_text(dict(context.get("provenance") or {}).get("claim_id"))
+                for context in memory_contexts
+                if clean_text(dict(context.get("provenance") or {}).get("claim_id"))
+            }
+        ),
+        "selected_graph_event_ids": list(graph.get("selected_event_ids") or []),
+        "runtime_input_has_gold": bool(debug.get("runtime_input_has_gold")),
+        "graph_fingerprint": clean_text(debug.get("graph_fingerprint")),
+        "evidence_sha256": hashlib.sha256(
+            json.dumps(
+                dict(evidence),
+                ensure_ascii=False,
+                sort_keys=True,
+                separators=(",", ":"),
+            ).encode("utf-8")
+        ).hexdigest(),
+    }
+    if payload["runtime_input_has_gold"]:
+        raise RuntimeError(f"{scope_id}: refusing to audit retrieval with evaluation labels")
+    if not payload["operation_id"]:
+        raise RuntimeError(f"{scope_id}: layered retrieval audit lacks operation_id")
+    store = SQLiteSessionMemoryStore(str(db_path), audit_retention=audit_retention)
+    return dict(
+        store.append_audit_event(
+            scope_id,
+            "retrieval_log",
+            payload,
+            idempotency_key=payload["operation_id"],
+        )
+    )
+
+
+def load_persisted_parent_chunks(db_path: Path, scope_id: str) -> list[dict[str, Any]]:
+    if not db_path.exists():
+        raise FileNotFoundError(db_path)
+    with sqlite3.connect(db_path) as connection:
+        record_rows = connection.execute(
+            "SELECT memory_id, turn_index, metadata_json FROM records WHERE scope_id=?",
+            (scope_id,),
+        ).fetchall()
+        if not record_rows:
+            raise RuntimeError(f"scope has no graph records: {scope_id}")
+        product_parents: list[dict[str, Any]] = []
+        product_message_ids: set[str] = set()
+        for memory_id, turn_index, raw_metadata in record_rows:
+            metadata = json.loads(raw_metadata)
+            if clean_text(metadata.get("content_variant")) != "source_message":
+                continue
+            message_id = clean_text(metadata.get("message_id"))
+            match = MESSAGE_ID_RE.fullmatch(message_id)
+            if match is None:
+                raise RuntimeError(f"{scope_id}: malformed persisted product message id: {message_id!r}")
+            session_index = int(metadata.get("session_index", -1))
+            message_index = int(metadata.get("message_index", -1))
+            if session_index != int(match.group("session")) or message_index != int(match.group("parent")):
+                raise RuntimeError(f"{scope_id}: product message location metadata disagrees with {message_id}")
+            raw_content = metadata.get("raw_content")
+            if not isinstance(raw_content, str) or not raw_content:
+                raise RuntimeError(f"{scope_id}: product source {message_id} has no persisted raw content")
+            if message_id in product_message_ids:
+                raise RuntimeError(f"{scope_id}: duplicate immutable product source message: {message_id}")
+            product_message_ids.add(message_id)
+            role = clean_text(metadata.get("speaker") or dict(metadata.get("sidecar_hint_metadata") or {}).get("role"))
+            session_id = clean_text(metadata.get("session_id") or dict(metadata.get("sidecar_hint_metadata") or {}).get("session_id"))
+            date = clean_text(metadata.get("historical_date") or dict(metadata.get("sidecar_hint_metadata") or {}).get("historical_date"))
+            timestamp = clean_text(metadata.get("timestamp"))
+            if role not in {"user", "assistant", "system", "tool"} or not session_id or not date or not timestamp:
+                raise RuntimeError(f"{scope_id}: incomplete product source metadata for {message_id}")
+            product_parents.append(
+                {
+                    "chunk_id": message_id,
+                    "parent_kind": "message",
+                    "session_index": session_index,
+                    "parent_chunk_index": message_index,
+                    "message_index": message_index,
+                    "session_id": session_id,
+                    "date": date,
+                    "timestamp": timestamp,
+                    "role": role,
+                    "text": raw_content,
+                    "turn_index": int(turn_index),
+                    "source_record_id": clean_text(memory_id),
+                }
+            )
+
+        audit_rows = connection.execute(
+            "SELECT event_index, payload_json FROM audit_turn_log WHERE scope_id=? ORDER BY event_index",
+            (scope_id,),
+        ).fetchall()
+        if product_parents:
+            audit_message_ids = {
+                clean_text(dict(json.loads(raw_payload).get("metadata") or {}).get("message_id"))
+                for _, raw_payload in audit_rows
+                if clean_text(dict(json.loads(raw_payload).get("metadata") or {}).get("message_id"))
+            }
+            if audit_message_ids != product_message_ids:
+                raise RuntimeError(
+                    f"{scope_id}: immutable source/audit message sets differ: "
+                    f"source={len(product_message_ids)} audit={len(audit_message_ids)}"
+                )
+            product_parents.sort(key=lambda row: (row["session_index"], row["message_index"]))
+            return product_parents
+
+        chunk_by_record: dict[str, str] = {}
+        chunks_by_turn: dict[int, set[str]] = {}
+        for memory_id, turn_index, raw_metadata in record_rows:
+            metadata = json.loads(raw_metadata)
+            sidecar = dict(metadata.get("sidecar_hint_metadata") or {})
+            chunk_id = clean_text(sidecar.get("chunk_id"))
+            if not chunk_id:
+                dia_id = clean_text(metadata.get("dia_id"))
+                chunk_id = dia_id.rsplit(":", 1)[-1] if dia_id else ""
+            if not LEGACY_CHUNK_ID_RE.match(chunk_id):
+                continue
+            chunk_by_record[clean_text(memory_id)] = chunk_id
+            chunks_by_turn.setdefault(int(turn_index), set()).add(chunk_id)
+
+    if not audit_rows:
+        raise RuntimeError(f"scope has no persisted write audit: {scope_id}")
+
+    parents: list[dict[str, Any]] = []
+    seen_locations: set[tuple[int, int]] = set()
+    for event_index, raw_payload in audit_rows:
+        payload = json.loads(raw_payload)
+        if clean_text(payload.get("kind")) != "memory_write":
+            continue
+        turn_index = int(payload.get("turn_index", 0) or 0)
+        record_ids = [clean_text(value) for value in list(payload.get("record_ids") or [])]
+        candidate_chunks = {chunk_by_record[value] for value in record_ids if value in chunk_by_record}
+        candidate_chunks.update(chunks_by_turn.get(turn_index, set()))
+        if len(candidate_chunks) != 1:
+            raise RuntimeError(
+                f"{scope_id}: persisted turn {turn_index} maps to {len(candidate_chunks)} chunk ids: {sorted(candidate_chunks)}"
+            )
+        chunk_id = next(iter(candidate_chunks))
+        match = LEGACY_CHUNK_ID_RE.match(chunk_id)
+        assert match is not None
+        session_index = int(match.group("session"))
+        parent_index = int(match.group("parent"))
+        location = (session_index, parent_index)
+        if location in seen_locations:
+            raise RuntimeError(f"{scope_id}: duplicate persisted parent location: {location}")
+        seen_locations.add(location)
+        persisted_text = str(payload.get("text", ""))
+        parent_text = INGEST_PREFIX_RE.sub("", persisted_text, count=1)
+        if parent_text == persisted_text or not parent_text:
+            raise RuntimeError(f"{scope_id}: cannot recover raw parent text from audit turn {turn_index}")
+        header = SESSION_HEADER_RE.match(parent_text)
+        if header is None:
+            raise RuntimeError(f"{scope_id}: malformed persisted LongMemEval parent header at {chunk_id}")
+        parents.append(
+            {
+                "chunk_id": chunk_id,
+                "parent_kind": "legacy_chunk",
+                "session_index": session_index,
+                "parent_chunk_index": parent_index,
+                "session_id": clean_text(header.group("session_id")),
+                "date": clean_text(header.group("date")),
+                "text": parent_text,
+                "turn_index": turn_index,
+                "audit_event_index": int(event_index),
+            }
+        )
+    parents.sort(key=lambda row: (row["session_index"], row["parent_chunk_index"]))
+    if len(parents) != len(audit_rows):
+        raise RuntimeError(
+            f"{scope_id}: not every persisted audit turn became a parent chunk: parents={len(parents)} audit={len(audit_rows)}"
+        )
+    return parents
+
+
+def parent_subchunks(
+    parents: Sequence[Mapping[str, Any]],
+    *,
+    scope_id: str,
+    subchunk_chars: int,
+    subchunk_overlap: int,
+) -> list[dict[str, Any]]:
+    candidates: list[dict[str, Any]] = []
+    for parent in parents:
+        if clean_text(parent.get("parent_kind")) == "message":
+            prefix = (
+                f"TMCRA conversation_id={parent['session_id']} timestamp={parent['timestamp']} "
+                f"message={int(parent['message_index']):03d} role={parent['role']}"
+            )
+        else:
+            prefix = (
+                f"LongMemEval session_id={parent['session_id']} date={parent['date']} "
+                f"parent_chunk={int(parent['parent_chunk_index']):02d}"
+            )
+        payload_chars = int(subchunk_chars) - len(prefix) - 1
+        spans = covered_windows(str(parent["text"]), payload_chars, int(subchunk_overlap))
+        for subchunk_index, (char_start, char_end) in enumerate(spans, start=1):
+            text = f"{prefix}\n{str(parent['text'])[char_start:char_end]}"
+            if len(text) > subchunk_chars:
+                raise RuntimeError("generated online subchunk exceeds the strict character limit")
+            candidates.append(
+                {
+                    "candidate_id": f"chunk::{scope_id}:{parent['chunk_id']}_p{subchunk_index:02d}",
+                    "text": text,
+                    "session_id": parent["session_id"],
+                    "session_index": int(parent["session_index"]),
+                    "parent_chunk_index": int(parent["parent_chunk_index"]),
+                    "parent_kind": clean_text(parent.get("parent_kind")) or "legacy_chunk",
+                    "role": clean_text(parent.get("role")),
+                    "message_role": clean_text(parent.get("role")),
+                    "historical_date": clean_text(parent.get("date")),
+                    "timestamp": clean_text(parent.get("timestamp")),
+                    "subchunk_index": subchunk_index,
+                    "source_char_start": char_start,
+                    "source_char_end": char_end,
+                    "source_record_id": clean_text(parent.get("source_record_id")),
+                }
+            )
+    if not candidates:
+        raise RuntimeError(f"no online candidates from persisted scope: {scope_id}")
+    return candidates
+
+
+def _metadata_json(value: Any, *, label: str) -> dict[str, Any]:
+    try:
+        parsed = json.loads(value)
+    except (TypeError, json.JSONDecodeError) as exc:
+        raise RuntimeError(f"invalid {label} metadata JSON") from exc
+    if not isinstance(parsed, dict):
+        raise RuntimeError(f"invalid {label} metadata object")
+    return parsed
+
+
+def _canonical_slot(value: Any, *, label: str) -> str:
+    slot = clean_text(value)
+    if not slot:
+        raise RuntimeError(f"{label} lacks canonical_slot")
+    return slot
+
+
+def _normalize_source_parents(value: Any, *, valid_locations: set[tuple[int, int]], label: str) -> list[dict[str, Any]]:
+    if not isinstance(value, Sequence) or isinstance(value, (str, bytes)) or not value:
+        raise RuntimeError(f"{label} lacks structured source_parents")
+    output: list[dict[str, Any]] = []
+    seen: set[tuple[int, int, int, int, str]] = set()
+    for raw in value:
+        if not isinstance(raw, Mapping):
+            raise RuntimeError(f"{label} source_parent is not an object")
+        try:
+            session = int(raw["session_index"])
+            parent = int(raw.get("parent_chunk_index", raw.get("message_index")))
+        except (KeyError, TypeError, ValueError) as exc:
+            raise RuntimeError(f"{label} source_parent lacks integer session/parent coordinates") from exc
+        message_index: int | None = None
+        if "message_index" in raw:
+            try:
+                message_index = int(raw["message_index"])
+            except (TypeError, ValueError) as exc:
+                raise RuntimeError(
+                    f"{label} source_parent has a non-integer message_index"
+                ) from exc
+            if message_index != parent:
+                raise RuntimeError(
+                    f"{label} source_parent message_index differs from parent_chunk_index"
+                )
+        location = (session, parent)
+        if location not in valid_locations:
+            raise RuntimeError(f"{label} source_parent cannot map to a persisted parent: {location}")
+        try:
+            char_start = int(raw["evidence_char_start"])
+            char_end = int(raw["evidence_char_end"])
+        except (KeyError, TypeError, ValueError) as exc:
+            raise RuntimeError(
+                f"{label} source_parent lacks integer evidence character span"
+            ) from exc
+        source_record_id = clean_text(raw.get("source_record_id"))
+        if char_start < 0 or char_end <= char_start or not source_record_id:
+            raise RuntimeError(f"{label} source_parent has invalid evidence provenance")
+        identity = (session, parent, char_start, char_end, source_record_id)
+        if identity not in seen:
+            seen.add(identity)
+            item = dict(raw)
+            item["session_index"] = session
+            item["parent_chunk_index"] = parent
+            item["evidence_char_start"] = char_start
+            item["evidence_char_end"] = char_end
+            item["source_record_id"] = source_record_id
+            if message_index is not None:
+                item["message_index"] = message_index
+            output.append(item)
+    if not output:
+        raise RuntimeError(f"{label} has no mapped source_parents")
+    return output
+
+
+def load_layered_inventory(
+    db_path: Path, scope_id: str, parents: Sequence[Mapping[str, Any]]
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    """Load current slow heads and map immutable fast semantic leaves to parents."""
+    valid_locations = {(int(item["session_index"]), int(item["parent_chunk_index"])) for item in parents}
+    slow_rows: dict[str, list[tuple[str, str, dict[str, Any]]]] = {}
+    semantic: list[dict[str, Any]] = []
+    with sqlite3.connect(db_path) as con:
+        rows = con.execute(
+            "SELECT memory_id, value, state, metadata_json FROM records WHERE scope_id=?", (scope_id,)
+        ).fetchall()
+    for memory_id, value, state, raw_metadata in rows:
+        metadata = _metadata_json(raw_metadata, label=str(memory_id))
+        layer = clean_text(metadata.get("memory_layer"))
+        variant = clean_text(metadata.get("content_variant"))
+        if layer == "slow" or variant == "slow_memory_capsule":
+            if layer != "slow" or variant != "slow_memory_capsule":
+                raise RuntimeError(f"{memory_id}: malformed slow capsule layer/variant")
+            capsule_id = clean_text(metadata.get("capsule_id"))
+            revision = metadata.get("revision")
+            if not capsule_id or not isinstance(revision, int) or revision < 1:
+                raise RuntimeError(f"{memory_id}: invalid capsule_id or revision")
+            slow_rows.setdefault(capsule_id, []).append((str(memory_id), str(state), {**metadata, "value": str(value)}))
+            continue
+        if layer != "fast" or variant != "product_semantic_memory":
+            continue
+        if clean_text(state) not in CURRENT_FAST_STATES:
+            continue
+        if (
+            clean_text(metadata.get("node_kind")) != "atomic_user_assertion"
+            or metadata.get("atomic_evidence_leaf") is not True
+            or clean_text(metadata.get("authority")) != "user_assertion"
+        ):
+            raise RuntimeError(f"{memory_id}: malformed fast semantic evidence leaf")
+        slot = clean_text(metadata.get("canonical_slot") or metadata.get("canonical_slot_key"))
+        if not slot:
+            # Non-slot fast leaves still remain retrievable through their source parent.
+            continue
+        try:
+            location = (int(metadata["session_index"]), int(metadata.get("parent_chunk_index", metadata.get("message_index"))))
+        except (KeyError, TypeError, ValueError) as exc:
+            raise RuntimeError(f"{memory_id}: fast semantic record lacks source parent location") from exc
+        if location not in valid_locations:
+            raise RuntimeError(f"{memory_id}: fast semantic record cannot map to persisted parent {location}")
+        source_record_id = clean_text(metadata.get("source_record_id"))
+        if not source_record_id:
+            raise RuntimeError(f"{memory_id}: fast semantic leaf lacks metadata.source_record_id")
+        try:
+            evidence_char_start = int(metadata["evidence_char_start"])
+            evidence_char_end = int(metadata["evidence_char_end"])
+        except (KeyError, TypeError, ValueError) as exc:
+            raise RuntimeError(
+                f"{memory_id}: fast semantic leaf lacks evidence character span"
+            ) from exc
+        if evidence_char_start < 0 or evidence_char_end <= evidence_char_start:
+            raise RuntimeError(f"{memory_id}: fast semantic leaf has invalid evidence character span")
+        semantic.append({
+            "memory_id": str(memory_id), "record_state": clean_text(state), "canonical_slot": slot, "source_parent": {
+                "session_index": location[0], "parent_chunk_index": location[1],
+                "source_record_id": source_record_id,
+                "evidence_char_start": evidence_char_start,
+                "evidence_char_end": evidence_char_end,
+            }, "provenance": {"memory_layer": "fast", "content_variant": variant, "source_record_id": source_record_id, "semantic_memory_id": str(memory_id)},
+        })
+    capsules: list[dict[str, Any]] = []
+    for capsule_id, revisions in slow_rows.items():
+        max_revision = max(int(meta["revision"]) for _, _, meta in revisions)
+        current = [(memory_id, state, meta) for memory_id, state, meta in revisions if int(meta["revision"]) == max_revision]
+        if len(current) != 1:
+            raise RuntimeError(f"{scope_id}: capsule {capsule_id} lacks a unique latest active/challenged revision")
+        memory_id, state, meta = current[0]
+        if state != "active" or clean_text(meta.get("status")) not in {"active", "challenged"}:
+            continue
+        claims = meta.get("claims")
+        if not isinstance(claims, Sequence) or isinstance(claims, (str, bytes)) or not claims:
+            raise RuntimeError(f"{memory_id}: capsule lacks claims")
+        capsule_parents = meta.get("source_parents")
+        for claim_index, claim in enumerate(claims):
+            if not isinstance(claim, Mapping):
+                raise RuntimeError(f"{memory_id}: claim {claim_index} is not an object")
+            slot = _canonical_slot(claim.get("canonical_slot"), label=f"{memory_id}: claim {claim_index}")
+            source_parents = _normalize_source_parents(
+                claim.get("source_parents", capsule_parents), valid_locations=valid_locations,
+                label=f"{memory_id}: claim {claim_index}",
+            )
+            claim_text = clean_text(claim.get("text"))
+            claim_id = clean_text(claim.get("claim_id"))
+            if not claim_text or not claim_id:
+                raise RuntimeError(f"{memory_id}: claim {claim_index} lacks claim_id or text")
+            capsules.append({
+                "candidate_id": f"capsule::{capsule_id}:r{meta['revision']}:c{claim_index}",
+                "memory_id": memory_id, "capsule_id": capsule_id, "revision": int(meta["revision"]),
+                "status": clean_text(meta.get("status")), "canonical_slot": slot, "claims": [dict(claim)],
+                "source_parents": source_parents, "text": claim_text,
+                "provenance": {"memory_layer": "slow", "content_variant": "slow_memory_capsule", "capsule_id": capsule_id, "revision": int(meta["revision"]), "claim_id": claim_id, "canonical_slot": slot, "patch_id": clean_text(meta.get("patch_id")), "source_parents": source_parents},
+            })
+    return capsules, semantic
+
+
+def command_build_index(args: argparse.Namespace) -> None:
+    rows = read_jsonl(Path(args.scope_manifest))
+    device = torch.device(args.device)
+    if device.type == "cuda" and not torch.cuda.is_available():
+        raise RuntimeError("CUDA is unavailable")
+    vectorizer: BgeM3DenseVectorizer | None = None
+    started = time.time()
+    report_rows: list[dict[str, Any]] = []
+    reused_index_count = 0
+    for row_index, row in enumerate(rows, start=1):
+        db_path = Path(row["db_path"]).resolve()
+        scope_id = clean_text(row.get("scope_id"))
+        index_path = Path(row["index_path"]).resolve()
+        if index_path.exists():
+            payload = torch.load(index_path, map_location="cpu", weights_only=True)
+            if not isinstance(payload, Mapping):
+                raise RuntimeError(f"existing online index is not an object: {index_path}")
+            expected = {
+                "schema_version": ONLINE_INDEX_SCHEMA_VERSION,
+                "fast_semantic_state_policy": FAST_SEMANTIC_STATE_POLICY,
+                "scope_id": scope_id,
+                "db_path": str(db_path),
+                "subchunk_chars": int(args.subchunk_chars),
+                "subchunk_overlap": int(args.subchunk_overlap),
+                "embedding_model": str(Path(args.embedding_model).resolve()),
+                "embedding_max_length": int(args.embedding_max_length),
+                "strict_no_truncation": True,
+            }
+            mismatches = {
+                key: {"expected": value, "actual": payload.get(key)}
+                for key, value in expected.items()
+                if payload.get(key) != value
+            }
+            current_fingerprint = scope_fingerprint(db_path, scope_id)
+            if clean_text(payload.get("graph_fingerprint")) != current_fingerprint:
+                mismatches["graph_fingerprint"] = {
+                    "expected": current_fingerprint,
+                    "actual": payload.get("graph_fingerprint"),
+                }
+            if mismatches:
+                raise RuntimeError(
+                    f"existing online index is incompatible with current scope: "
+                    f"{index_path} mismatches={json.dumps(mismatches, sort_keys=True)}"
+                )
+            report_row = {
+                "question_id": clean_text(row.get("question_id")),
+                "scope_id": scope_id,
+                "db_path": str(db_path),
+                "index_path": str(index_path),
+                "parent_count": int(payload["parent_count"]),
+                "candidate_count": int(payload["candidate_count"]),
+                "slow_capsule_count": int(payload["slow_capsule_count"]),
+                "fast_semantic_record_count": int(payload["fast_semantic_record_count"]),
+                "fast_semantic_state_policy": payload["fast_semantic_state_policy"],
+                "graph_counts": dict(payload["graph_counts_at_index"]),
+                "graph_fingerprint": current_fingerprint,
+                "reused_existing_index": True,
+            }
+            reused_index_count += 1
+            report_rows.append(report_row)
+            print(
+                json.dumps(
+                    {"status": "index_reused", "row": row_index, "total": len(rows), **report_row}
+                ),
+                flush=True,
+            )
+            continue
+        if vectorizer is None:
+            vectorizer = BgeM3DenseVectorizer(
+                dim=args.text_dim,
+                model_path=args.embedding_model,
+                device=str(device),
+                max_length=args.embedding_max_length,
+                strict_max_length=True,
+            )
+        graph_fingerprint = scope_fingerprint(db_path, scope_id)
+        parents = load_persisted_parent_chunks(db_path, scope_id)
+        candidates = parent_subchunks(
+            parents,
+            scope_id=scope_id,
+            subchunk_chars=args.subchunk_chars,
+            subchunk_overlap=args.subchunk_overlap,
+        )
+        slow_capsules, fast_semantic_records = load_layered_inventory(db_path, scope_id, parents)
+        fast_vectors = vectorizer.encode_batch([candidate["text"] for candidate in candidates], batch_size=args.batch_size)
+        slow_vectors = (
+            vectorizer.encode_batch([capsule["text"] for capsule in slow_capsules], batch_size=args.batch_size)
+            if slow_capsules else torch.empty((0, args.text_dim), dtype=torch.float32)
+        )
+        fast_vectors = fast_vectors.to(torch.float16).contiguous()
+        slow_vectors = slow_vectors.to(torch.float16).contiguous()
+        counts = scope_counts(db_path, scope_id)
+        if scope_fingerprint(db_path, scope_id) != graph_fingerprint:
+            raise RuntimeError(
+                f"{scope_id}: graph changed while the online index was being built"
+            )
+        payload = {
+            "schema_version": ONLINE_INDEX_SCHEMA_VERSION,
+            "fast_semantic_state_policy": FAST_SEMANTIC_STATE_POLICY,
+            "created_at": time.strftime("%Y-%m-%dT%H:%M:%S%z"),
+            "scope_id": scope_id,
+            "db_path": str(db_path),
+            "graph_counts_at_index": counts,
+            "graph_fingerprint": graph_fingerprint,
+            "parent_count": len(parents),
+            "candidate_count": len(candidates),
+            "slow_capsule_count": len(slow_capsules),
+            "fast_semantic_record_count": len(fast_semantic_records),
+            "subchunk_chars": args.subchunk_chars,
+            "subchunk_overlap": args.subchunk_overlap,
+            "embedding_model": str(Path(args.embedding_model).resolve()),
+            "embedding_max_length": args.embedding_max_length,
+            "strict_no_truncation": True,
+            "fast_candidates": candidates,
+            "fast_vectors": fast_vectors,
+            "slow_capsules": slow_capsules,
+            "slow_vectors": slow_vectors,
+            "fast_semantic_records": fast_semantic_records,
+        }
+        atomic_torch_save(payload, index_path)
+        report_row = {
+            "question_id": clean_text(row.get("question_id")),
+            "scope_id": scope_id,
+            "db_path": str(db_path),
+            "index_path": str(index_path),
+            "parent_count": len(parents),
+            "candidate_count": len(candidates),
+            "slow_capsule_count": len(slow_capsules),
+            "fast_semantic_record_count": len(fast_semantic_records),
+            "fast_semantic_state_policy": FAST_SEMANTIC_STATE_POLICY,
+            "graph_counts": counts,
+            "graph_fingerprint": graph_fingerprint,
+            "reused_existing_index": False,
+        }
+        report_rows.append(report_row)
+        print(json.dumps({"status": "indexed", "row": row_index, "total": len(rows), **report_row}), flush=True)
+    report = {
+        "status": "complete",
+        "schema_version": "tmcra.v3.online-index-report.2",
+        "row_count": len(report_rows),
+        "parent_count": sum(row["parent_count"] for row in report_rows),
+        "candidate_count": sum(row["candidate_count"] for row in report_rows),
+        "slow_capsule_count": sum(row["slow_capsule_count"] for row in report_rows),
+        "reused_index_count": reused_index_count,
+        "elapsed_sec": round(time.time() - started, 3),
+        "rows": report_rows,
+    }
+    out_report = Path(args.out_report)
+    out_report.parent.mkdir(parents=True, exist_ok=True)
+    _atomic_write_text(out_report, json.dumps(report, indent=2, sort_keys=True) + "\n")
+
+
+def ordered_graph_parents(
+    event_ids: Iterable[Any],
+    *,
+    valid_locations: set[tuple[int, int]],
+    strict_prefix: bool = False,
+) -> tuple[list[tuple[int, int]], list[str]]:
+    output: list[tuple[int, int]] = []
+    seen: set[tuple[int, int]] = set()
+    unmapped: list[str] = []
+    for raw in event_ids:
+        event_id = clean_text(raw)
+        match = EVENT_PARENT_RE.search(event_id)
+        if match is None:
+            if strict_prefix and event_id.startswith(("event::longmemeval:", "event::tmcra:")):
+                unmapped.append(event_id)
+            continue
+        location = (int(match.group("session")), int(match.group("parent")))
+        if location not in valid_locations:
+            unmapped.append(event_id)
+            continue
+        if location not in seen:
+            seen.add(location)
+            output.append(location)
+    return output, unmapped
+
+
+def expand_parent_locations(
+    locations: Iterable[tuple[int, int]],
+    parent_candidates: Mapping[tuple[int, int], Sequence[int]],
+) -> list[int]:
+    output: list[int] = []
+    seen: set[int] = set()
+    for location in locations:
+        for candidate_index in parent_candidates[location]:
+            if candidate_index not in seen:
+                seen.add(candidate_index)
+                output.append(candidate_index)
+    return output
+
+
+class OnlineModels:
+    def __init__(self, args: argparse.Namespace):
+        from transformers import AutoModelForSequenceClassification, AutoTokenizer
+
+        self.device = torch.device(args.device)
+        if self.device.type == "cuda" and not torch.cuda.is_available():
+            raise RuntimeError("CUDA is unavailable")
+        self.dense = BgeM3DenseVectorizer(
+            dim=args.text_dim,
+            model_path=args.embedding_model,
+            device=str(self.device),
+            max_length=args.embedding_max_length,
+            strict_max_length=True,
+        )
+        cross_path = Path(args.cross_model).resolve()
+        self.cross_manifest = load_optional_hf_model_manifest(cross_path)
+        self.cross_tokenizer = AutoTokenizer.from_pretrained(
+            str(cross_path),
+            local_files_only=True,
+            trust_remote_code=False,
+        )
+        self.cross_model = AutoModelForSequenceClassification.from_pretrained(
+            str(cross_path),
+            local_files_only=True,
+            trust_remote_code=False,
+            torch_dtype=torch.float16 if self.device.type == "cuda" else torch.float32,
+        ).to(self.device)
+        self.cross_model.eval()
+        hidden_size = int(getattr(self.cross_model.config, "hidden_size", 0) or 0)
+        if hidden_size <= 0:
+            raise RuntimeError("cross encoder hidden size is unavailable")
+        checkpoint_path = Path(args.checkpoint).resolve()
+        checkpoint = torch.load(checkpoint_path, map_location=self.device, weights_only=True)
+        if checkpoint.get("schema_version") != SCHEMA_VERSION:
+            raise RuntimeError("online checkpoint schema mismatch")
+        if tuple(checkpoint.get("channel_names") or ()) != CHANNEL_NAMES:
+            raise RuntimeError("online checkpoint channel mismatch")
+        config = dict(checkpoint.get("model_config") or {})
+        self.fusion = ChannelAwareMemoryReranker(
+            representation_dim=hidden_size,
+            channel_dim=len(CHANNEL_NAMES),
+            hidden_dim=int(config["hidden_dim"]),
+            layers=int(config["layers"]),
+        ).to(self.device)
+        self.fusion.load_state_dict(checkpoint["model_state"])
+        self.fusion.eval()
+        self.checkpoint = checkpoint
+        self.checkpoint_path = checkpoint_path
+        self.checkpoint_sha256 = sha256_file(checkpoint_path)
+        self.cross_max_length = int(args.cross_max_length)
+        self.cross_batch_size = int(args.cross_batch_size)
+
+    def encode_cross(self, query: str, texts: Sequence[str]) -> tuple[torch.Tensor, torch.Tensor]:
+        representations: list[torch.Tensor] = []
+        logits: list[torch.Tensor] = []
+        with torch.inference_mode():
+            for start in range(0, len(texts), self.cross_batch_size):
+                batch_texts = list(texts[start : start + self.cross_batch_size])
+                encoded = self.cross_tokenizer(
+                    [query] * len(batch_texts),
+                    batch_texts,
+                    padding=True,
+                    truncation=False,
+                    return_tensors="pt",
+                )
+                token_lengths = encoded["attention_mask"].sum(dim=1)
+                longest = int(token_lengths.max())
+                if longest > self.cross_max_length:
+                    offending = int(torch.argmax(token_lengths))
+                    raise RuntimeError(
+                        f"online cross pair has {longest} tokens, exceeding strict max={self.cross_max_length}; "
+                        f"candidate_batch_index={offending}"
+                    )
+                encoded = {key: value.to(self.device) for key, value in encoded.items()}
+                output = self.cross_model(**encoded, output_hidden_states=True, return_dict=True)
+                if output.hidden_states is None:
+                    raise RuntimeError("online cross encoder returned no hidden states")
+                representations.append(output.hidden_states[-1][:, 0].float())
+                semantic = output.logits.float()
+                if semantic.ndim == 2 and semantic.shape[1] == 1:
+                    semantic = semantic[:, 0]
+                elif semantic.ndim != 1:
+                    raise RuntimeError(f"online cross logits have invalid shape: {tuple(semantic.shape)}")
+                logits.append(semantic)
+        return torch.cat(representations, dim=0), torch.cat(logits, dim=0)
+
+
+def load_online_index(path: Path, expected_db: Path, expected_scope: str) -> tuple[list[dict[str, Any]], torch.Tensor, list[dict[str, Any]], torch.Tensor, list[dict[str, Any]], dict[str, Any]]:
+    payload = torch.load(path, map_location="cpu", weights_only=True)
+    if payload.get("schema_version") != ONLINE_INDEX_SCHEMA_VERSION:
+        raise RuntimeError(f"online index schema mismatch: {path}")
+    if payload.get("fast_semantic_state_policy") != FAST_SEMANTIC_STATE_POLICY:
+        raise RuntimeError(f"online index fast semantic state policy mismatch: {path}")
+    if clean_text(payload.get("scope_id")) != expected_scope:
+        raise RuntimeError(f"online index scope mismatch: {path}")
+    if Path(payload.get("db_path", "")).resolve() != expected_db.resolve():
+        raise RuntimeError(f"online index database mismatch: {path}")
+    candidates = list(payload.get("fast_candidates") or [])
+    vectors = payload.get("fast_vectors")
+    slow_capsules = list(payload.get("slow_capsules") or [])
+    slow_vectors = payload.get("slow_vectors")
+    semantic_records = list(payload.get("fast_semantic_records") or [])
+    if not candidates or vectors is None or tuple(vectors.shape) != (len(candidates), 1024):
+        raise RuntimeError(f"online index payload is incomplete: {path}")
+    if slow_vectors is None or tuple(slow_vectors.shape) != (len(slow_capsules), 1024):
+        raise RuntimeError(f"online slow index payload is incomplete: {path}")
+    if any("labels" in candidate for candidate in candidates):
+        raise RuntimeError("runtime index must not contain benchmark labels")
+    return candidates, vectors.float().contiguous(), slow_capsules, slow_vectors.float().contiguous(), semantic_records, payload
+
+
+def choose_diverse(
+    candidates: Sequence[Mapping[str, Any]],
+    scores: torch.Tensor,
+    *,
+    top_k: int,
+    max_per_parent: int,
+    max_per_session: int,
+) -> list[int]:
+    order = torch.argsort(scores, descending=True).tolist()
+    selected: list[int] = []
+    parent_counts: Counter[tuple[int, int]] = Counter()
+    session_counts: Counter[str] = Counter()
+    for index in order:
+        candidate = candidates[index]
+        parent = (int(candidate["session_index"]), int(candidate["parent_chunk_index"]))
+        session_id = clean_text(candidate.get("session_id"))
+        if max_per_parent > 0 and parent_counts[parent] >= max_per_parent:
+            continue
+        if max_per_session > 0 and session_counts[session_id] >= max_per_session:
+            continue
+        selected.append(index)
+        parent_counts[parent] += 1
+        session_counts[session_id] += 1
+        if len(selected) >= top_k:
+            break
+    if len(selected) != top_k:
+        raise RuntimeError(f"online diversity policy produced only {len(selected)} of {top_k} required windows")
+    return selected
+
+
+def _deprecated_legacy_retrieve_one_v1(
+    row: Mapping[str, Any],
+    *,
+    args: argparse.Namespace,
+    harness: Any,
+    models: OnlineModels,
+) -> tuple[dict[str, Any], dict[str, Any]]:
+    """Retained only for forensic comparison; the v2 command never calls this schema .1 path."""
+    started = time.time()
+    qid = clean_text(row.get("question_id"))
+    question = clean_text(row.get("question"))
+    question_date = clean_text(row.get("question_date"))
+    runtime_question = f"{question}\nQuestion date: {question_date}" if question_date else question
+    db_path = Path(row["db_path"]).resolve()
+    scope_id = clean_text(row.get("scope_id"))
+    index_path = Path(row["index_path"]).resolve()
+    if not qid or not question or not scope_id:
+        raise RuntimeError("online retrieval manifest row lacks qid, question, or scope")
+    candidates, dense_vectors, index_payload = load_online_index(index_path, db_path, scope_id)
+    counts_before = scope_counts(db_path, scope_id)
+    if counts_before["records"] != int(index_payload["graph_counts_at_index"]["records"]):
+        raise RuntimeError(f"{qid}: graph records changed after online index creation")
+
+    adapter = harness.build_adapter(scope_id, db_path)
+    graph_started = time.time()
+    retrieval = adapter.retrieve(runtime_question, top_k=args.graph_top_k)
+    graph_elapsed = time.time() - graph_started
+    metadata = dict(getattr(retrieval, "metadata", {}) or {})
+    if clean_text(metadata.get("retrieval_mode")) != "hybrid_node_scored":
+        raise RuntimeError(f"{qid}: graph retrieval did not use hybrid_node_scored")
+    if not bool(metadata.get("hybrid_enabled")):
+        raise RuntimeError(f"{qid}: graph hybrid model path is not active")
+    selected_event_ids = list(metadata.get("selected_event_ids") or [])
+    recall_event_ids = list(metadata.get("recall_event_ids") or [])
+    final_event_ids = list(metadata.get("final_hit_event_ids") or [])
+    if not selected_event_ids:
+        raise RuntimeError(f"{qid}: graph model selected no events")
+
+    parent_candidates: dict[tuple[int, int], list[int]] = {}
+    for index, candidate in enumerate(candidates):
+        location = (int(candidate["session_index"]), int(candidate["parent_chunk_index"]))
+        parent_candidates.setdefault(location, []).append(index)
+    valid_locations = set(parent_candidates)
+    selected_parents, selected_unmapped = ordered_graph_parents(
+        selected_event_ids, valid_locations=valid_locations, strict_prefix=True
+    )
+    recall_parents, recall_unmapped = ordered_graph_parents(recall_event_ids, valid_locations=valid_locations)
+    final_parents, final_unmapped = ordered_graph_parents(final_event_ids, valid_locations=valid_locations)
+    critical_unmapped = [*selected_unmapped, *final_unmapped]
+    if critical_unmapped:
+        raise RuntimeError(f"{qid}: selected/final graph events cannot map to persisted chunks: {critical_unmapped[:8]}")
+    graph_parents: list[tuple[int, int]] = []
+    graph_parent_seen: set[tuple[int, int]] = set()
+    for location in [*selected_parents, *recall_parents]:
+        if location not in graph_parent_seen:
+            graph_parent_seen.add(location)
+            graph_parents.append(location)
+    graph_parents = graph_parents[: args.graph_k]
+    graph_parent_rank = {location: rank for rank, location in enumerate(graph_parents)}
+    graph_runtime_order = expand_parent_locations(graph_parents, parent_candidates)
+    graph_rank = {
+        index: graph_parent_rank[(int(candidates[index]["session_index"]), int(candidates[index]["parent_chunk_index"]))]
+        for index in graph_runtime_order
+    }
+    selected_indexes = set(expand_parent_locations(selected_parents, parent_candidates))
+    final_indexes = set(expand_parent_locations(final_parents, parent_candidates))
+
+    dense_started = time.time()
+    query_vector = models.dense.encode_one(runtime_question)
+    dense_scores = dense_vectors @ query_vector
+    dense_order = sorted(range(len(candidates)), key=lambda index: (-float(dense_scores[index]), index))
+    dense_rank = {index: rank for rank, index in enumerate(dense_order)}
+    dense_elapsed = time.time() - dense_started
+    runtime_indexes: list[int] = []
+    runtime_seen: set[int] = set()
+    for index in [*dense_order[: args.dense_k], *graph_runtime_order]:
+        if index not in runtime_seen:
+            runtime_seen.add(index)
+            runtime_indexes.append(index)
+    if not runtime_indexes:
+        raise RuntimeError(f"{qid}: graph+dense union is empty")
+
+    session_count = max(int(candidate["session_index"]) for candidate in candidates) + 1
+    runtime_candidates: list[dict[str, Any]] = []
+    for index in runtime_indexes:
+        source = dict(candidates[index])
+        channels = {
+            "dense_score": float(dense_scores[index]),
+            "dense_rank_rr": rrank(dense_rank[index]),
+            "graph_rank_rr": rrank(graph_rank.get(index)),
+            "graph_selected": float(index in selected_indexes),
+            "graph_final": float(index in final_indexes),
+            "recency_norm": float(source["session_index"]) / float(max(1, session_count - 1)),
+        }
+        if tuple(channels) != CHANNEL_NAMES:
+            raise AssertionError("online channel order changed")
+        source["channels"] = channels
+        runtime_candidates.append(source)
+
+    cross_started = time.time()
+    representations, semantic_logits = models.encode_cross(
+        runtime_question, [candidate["text"] for candidate in runtime_candidates]
+    )
+    channel_tensor = torch.tensor(
+        [[candidate["channels"][name] for name in CHANNEL_NAMES] for candidate in runtime_candidates],
+        dtype=torch.float32,
+        device=models.device,
+    )
+    mask = torch.ones((1, len(runtime_candidates)), dtype=torch.bool, device=models.device)
+    with torch.inference_mode():
+        fusion_scores = models.fusion(
+            representations.unsqueeze(0),
+            semantic_logits.unsqueeze(0),
+            channel_tensor.unsqueeze(0),
+            mask,
+            ablation="full",
+        )[0].detach().cpu()
+    semantic_cpu = semantic_logits.detach().cpu()
+    cross_elapsed = time.time() - cross_started
+    selected = choose_diverse(
+        runtime_candidates,
+        fusion_scores,
+        top_k=args.top_k,
+        max_per_parent=args.max_per_parent,
+        max_per_session=args.max_per_session,
+    )
+    evidence_windows = []
+    for rank, index in enumerate(selected, start=1):
+        candidate = runtime_candidates[index]
+        evidence_windows.append(
+            {
+                "memory_id": candidate["candidate_id"],
+                "session_id": candidate["session_id"],
+                "session_index": candidate["session_index"],
+                "parent_chunk_index": candidate["parent_chunk_index"],
+                "subchunk_index": candidate["subchunk_index"],
+                "rank": rank,
+                "score": round(float(fusion_scores[index]), 6),
+                "semantic_logit": round(float(semantic_cpu[index]), 6),
+                "channels": candidate["channels"],
+                "text": candidate["text"],
+            }
+        )
+    evidence_row = {
+        "schema_version": SCHEMA_VERSION,
+        "runtime_schema_version": "tmcra.v3.online-retrieval.1",
+        "question_id": qid,
+        "question": question,
+        "question_date": question_date,
+        "question_type": clean_text(row.get("question_type")),
+        "selected_session_ids": [window["session_id"] for window in evidence_windows],
+        "evidence_windows": evidence_windows,
+    }
+    debug_row = {
+        "question_id": qid,
+        "scope_id": scope_id,
+        "db_path": str(db_path),
+        "index_path": str(index_path),
+        "runtime_input_has_gold": any(
+            key in row for key in ("answer", "gold_answer", "answer_session_ids", "labels", "supervision")
+        ),
+        "graph": {
+            "retrieval_mode": metadata.get("retrieval_mode"),
+            "hybrid_enabled": metadata.get("hybrid_enabled"),
+            "decision_score_source": metadata.get("decision_score_source"),
+            "selected_event_count": len(selected_event_ids),
+            "recall_event_count": len(recall_event_ids),
+            "final_event_count": len(final_event_ids),
+            "selected_parent_count": len(selected_parents),
+            "recall_parent_count": len(recall_parents),
+            "final_parent_count": len(final_parents),
+            "unmapped_recall_event_ids": recall_unmapped,
+            "selected_event_ids": selected_event_ids,
+            "recall_event_ids": recall_event_ids,
+            "final_hit_event_ids": final_event_ids,
+        },
+        "inventory_count": len(candidates),
+        "dense_k": args.dense_k,
+        "graph_k": args.graph_k,
+        "union_count": len(runtime_candidates),
+        "selected_count": len(evidence_windows),
+        "checkpoint": str(models.checkpoint_path),
+        "checkpoint_sha256": models.checkpoint_sha256,
+        "cross_model_revision": models.cross_manifest.get("revision"),
+        "strict_no_truncation": True,
+        "restart_boundary_verified": True,
+        "graph_counts_before_query": counts_before,
+        "latency_sec": {
+            "graph": round(graph_elapsed, 4),
+            "dense": round(dense_elapsed, 4),
+            "cross_and_fusion": round(cross_elapsed, 4),
+            "total": round(time.time() - started, 4),
+        },
+        "ranked_union": [
+            {
+                "candidate_id": runtime_candidates[index]["candidate_id"],
+                "session_id": runtime_candidates[index]["session_id"],
+                "parent_chunk_index": runtime_candidates[index]["parent_chunk_index"],
+                "subchunk_index": runtime_candidates[index]["subchunk_index"],
+                "fusion_score": round(float(fusion_scores[index]), 6),
+                "semantic_logit": round(float(semantic_cpu[index]), 6),
+                "channels": runtime_candidates[index]["channels"],
+            }
+            for index in torch.argsort(fusion_scores, descending=True).tolist()
+        ],
+    }
+    if debug_row["runtime_input_has_gold"]:
+        raise RuntimeError(f"{qid}: runtime retrieval manifest contains forbidden evaluation labels")
+    return evidence_row, debug_row
+
+
+def planner_from_env() -> DeepSeekFlashRecallPlanner:
+    pool = [part.strip() for part in os.environ.get("TMCRA_RECALL_PLANNER_API_KEY_POOL", "").split(",") if part.strip()]
+    return DeepSeekFlashRecallPlanner(
+        base_url=os.environ.get("TMCRA_RECALL_PLANNER_BASE_URL", ""),
+        model=os.environ.get("TMCRA_RECALL_PLANNER_MODEL", DEEPSEEK_FLASH_MODEL), api_keys=pool,
+    )
+
+
+def _fast_candidates_with_slots(candidates: Sequence[Mapping[str, Any]], semantic_records: Sequence[Mapping[str, Any]]) -> list[dict[str, Any]]:
+    by_parent: dict[tuple[int, int], list[Mapping[str, Any]]] = {}
+    for record in semantic_records:
+        parent = dict(record["source_parent"])
+        by_parent.setdefault((int(parent["session_index"]), int(parent["parent_chunk_index"])), []).append(record)
+    output: list[dict[str, Any]] = []
+    for candidate in candidates:
+        location = (int(candidate["session_index"]), int(candidate["parent_chunk_index"]))
+        records = [
+            record
+            for record in by_parent.get(location, [])
+            if int(candidate["source_char_end"])
+            > int(record["source_parent"]["evidence_char_start"])
+            and int(candidate["source_char_start"])
+            < int(record["source_parent"]["evidence_char_end"])
+        ]
+        by_slot: dict[str, list[Mapping[str, Any]]] = {}
+        for record in records:
+            by_slot.setdefault(_canonical_slot(record.get("canonical_slot"), label="fast semantic record"), []).append(record)
+        if not by_slot:
+            by_slot[f"fast.parent.s{location[0]}.p{location[1]}"] = []
+        for slot, slot_records in by_slot.items():
+            item = dict(candidate)
+            item["canonical_slot"] = slot
+            item["semantic_record_ids"] = [str(record["memory_id"]) for record in slot_records]
+            item["provenance"] = {
+                "memory_layer": "fast",
+                "content_variant": "source_subchunk",
+                "source_parent": {
+                    "session_index": location[0],
+                    "parent_chunk_index": location[1],
+                    "source_record_ids": sorted(
+                        {
+                            clean_text(record["source_parent"].get("source_record_id"))
+                            for record in slot_records
+                            if clean_text(record["source_parent"].get("source_record_id"))
+                        }
+                    )
+                    or ([clean_text(candidate.get("source_record_id"))] if clean_text(candidate.get("source_record_id")) else []),
+                },
+            }
+            output.append(item)
+    return output
+
+
+def _unit_windows(unit: Mapping[str, Any], fast_candidates: Sequence[Mapping[str, Any]], *, qid: str) -> list[dict[str, Any]]:
+    """Fully descend one composed unit, merging duplicate physical source windows."""
+    by_parent: dict[tuple[int, int], list[Mapping[str, Any]]] = {}
+    for candidate in fast_candidates:
+        by_parent.setdefault((int(candidate["session_index"]), int(candidate["parent_chunk_index"])), []).append(candidate)
+    output: dict[tuple[int, int, int], dict[str, Any]] = {}
+
+    def add(candidate: Mapping[str, Any], *, role: str, capsule: Mapping[str, Any] | None = None) -> None:
+        key = (int(candidate["session_index"]), int(candidate["parent_chunk_index"]), int(candidate["subchunk_index"]))
+        item = output.setdefault(key, {**dict(candidate), "roles": [], "capsules": []})
+        if role not in item["roles"]:
+            item["roles"].append(role)
+        if capsule is not None and capsule not in item["capsules"]:
+            item["capsules"].append(dict(capsule))
+
+    def descend(capsule: Mapping[str, Any], role: str) -> None:
+        for parent in capsule["source_parents"]:
+            location = (int(parent["session_index"]), int(parent["parent_chunk_index"]))
+            char_start = int(parent["evidence_char_start"])
+            char_end = int(parent["evidence_char_end"])
+            matches = [
+                candidate
+                for candidate in by_parent.get(location, [])
+                if int(candidate["source_char_end"]) > char_start
+                and int(candidate["source_char_start"]) < char_end
+            ]
+            if not matches:
+                raise RuntimeError(f"{qid}: slow source_parent is unmapped during descent: {location}")
+            for candidate in matches:
+                add(candidate, role=role, capsule=capsule)
+
+    kind = str(unit["unit_type"])
+    if kind.startswith("fast_primary"):
+        add(unit["fast_candidate"], role="primary")
+    elif kind == "slow_primary_with_fast_override":
+        descend(unit["slow_capsule"], "primary")
+        for candidate in unit.get("fast_overrides", []):
+            add(candidate, role="override")
+    elif kind.startswith("slow_primary"):
+        descend(unit["slow_capsule"], "primary")
+    elif kind == "conflict_group":
+        for capsule in unit["slow_capsules"]:
+            descend(capsule, "slow_conflict_candidate")
+        for candidate in unit["fast_candidates"]:
+            add(candidate, role="fast_conflict_candidate")
+    else:
+        raise RuntimeError(f"{qid}: unsupported planned unit type {kind}")
+    return list(output.values())
+
+
+def _unit_attachments(unit: Mapping[str, Any]) -> list[dict[str, Any]]:
+    if unit.get("slow_context"):
+        return [{"role": "context_only", "capsule_id": item["capsule_id"], "canonical_slot": item["canonical_slot"], "summary": item["text"], "source_parents": item["source_parents"], "provenance": item["provenance"]} for item in unit["slow_context"]]
+    if unit.get("fast_overrides"):
+        return [{"role": "override", "memory_id": item["candidate_id"], "canonical_slot": item["canonical_slot"], "text": item["text"], "provenance": item["provenance"]} for item in unit["fast_overrides"]]
+    return []
+
+
+def pack_recall_units(units: Sequence[Mapping[str, Any]], fast_candidates: Sequence[Mapping[str, Any]], *, top_k: int, qid: str) -> list[tuple[Mapping[str, Any], list[dict[str, Any]]]]:
+    if top_k <= 0:
+        raise RuntimeError("top_k must be positive")
+    packed: list[tuple[Mapping[str, Any], list[dict[str, Any]]]] = []
+    used: set[tuple[int, int, int]] = set()
+    for unit in units:
+        windows = _unit_windows(unit, fast_candidates, qid=qid)
+        unique = [item for item in windows if (int(item["session_index"]), int(item["parent_chunk_index"]), int(item["subchunk_index"])) not in used]
+        if not unique:
+            if windows:
+                packed.append((unit, windows))
+            continue
+        if len(unique) > top_k and not packed:
+            raise RuntimeError(f"{qid}: first atomic recall unit requires {len(unique)} windows, exceeding strict packing budget {top_k}")
+        if len(used) + len(unique) > top_k:
+            break
+        packed.append((unit, windows))
+        used.update((int(item["session_index"]), int(item["parent_chunk_index"]), int(item["subchunk_index"])) for item in unique)
+    if not packed:
+        raise RuntimeError(f"{qid}: recall plan produced no packable evidence units")
+    return packed
+
+
+def retrieve_one(
+    row: Mapping[str, Any], *, args: argparse.Namespace, harness: Any, models: OnlineModels,
+    planner: DeepSeekFlashRecallPlanner,
+    graph_adapter_cache: dict[tuple[str, str], Any] | None = None,
+) -> tuple[dict[str, Any], dict[str, Any]]:
+    started = time.time()
+    qid, question, question_date = clean_text(row.get("question_id")), clean_text(row.get("question")), clean_text(row.get("question_date"))
+    if not qid or not question:
+        raise RuntimeError("online retrieval manifest row lacks qid or question")
+    if int(args.slow_dense_k) <= 0:
+        raise RuntimeError("slow_dense_k must be positive")
+    db_path, scope_id, index_path = Path(row["db_path"]).resolve(), clean_text(row.get("scope_id")), Path(row["index_path"]).resolve()
+    fast, fast_vectors, slow, slow_vectors, semantic_records, payload = load_online_index(index_path, db_path, scope_id)
+    counts_before = scope_counts(db_path, scope_id)
+    if counts_before["records"] != int(payload["graph_counts_at_index"]["records"]):
+        raise RuntimeError(f"{qid}: graph records changed after online index creation")
+    graph_fingerprint = scope_fingerprint(db_path, scope_id)
+    if graph_fingerprint != clean_text(payload.get("graph_fingerprint")):
+        raise RuntimeError(f"{qid}: graph fingerprint changed after online index creation")
+    recent_dialogue = load_recent_dialogue_context(
+        db_path, scope_id, current_query=question, limit=8
+    )
+    raw_plan, planner_metadata = planner.plan(
+        query=question, question_date=question_date or "unknown",
+        recent_dialogue=recent_dialogue,
+        available_layers={"fast": {"available": bool(fast), "candidate_count": len(fast)}, "slow": {"available": bool(slow), "capsule_count": len(slow)}},
+    )
+    plan = dict(raw_plan)
+    planner_decision_reason = clean_text(plan.get("decision_reason"))
+    if not planner_decision_reason:
+        raise RuntimeError(f"{qid}: Flash recall plan lacks a decision reason")
+    resolved_query = clean_text(plan.get("resolved_query"))
+    if not resolved_query:
+        raise RuntimeError(f"{qid}: Flash recall plan lacks a resolved query")
+    runtime_question = (
+        f"{resolved_query}\nQuestion date: {question_date}"
+        if question_date
+        else resolved_query
+    )
+    authoritative_plan = dict(plan)
+    authoritative_plan.pop("decision_reason", None)
+    if not slow and plan["mode"] != "FAST_ONLY":
+        raise RuntimeError(f"{qid}: Flash must select FAST_ONLY when no slow capsules are available")
+
+    graph_metadata: dict[str, Any] = {"skipped": plan["mode"] == "SLOW_ONLY"}
+    graph_elapsed = 0.0
+    graph_runtime_order: list[int] = []
+    selected_indexes: set[int] = set()
+    final_indexes: set[int] = set()
+    graph_rank: dict[int, int] = {}
+    parent_candidates: dict[tuple[int, int], list[int]] = {}
+    graph_adapter_reused = False
+    for index, candidate in enumerate(fast):
+        parent_candidates.setdefault((int(candidate["session_index"]), int(candidate["parent_chunk_index"])), []).append(index)
+    if plan["mode"] != "SLOW_ONLY":
+        adapter_key = (scope_id, str(db_path))
+        adapter = graph_adapter_cache.get(adapter_key) if graph_adapter_cache is not None else None
+        if adapter is None:
+            adapter = harness.build_adapter(scope_id, db_path)
+            if graph_adapter_cache is not None:
+                graph_adapter_cache[adapter_key] = adapter
+        else:
+            graph_adapter_reused = True
+        graph_started = time.time()
+        retrieval = adapter.retrieve(runtime_question, top_k=args.graph_top_k)
+        graph_elapsed = time.time() - graph_started
+        metadata = dict(getattr(retrieval, "metadata", {}) or {})
+        if clean_text(metadata.get("retrieval_mode")) != "hybrid_node_scored" or not bool(metadata.get("hybrid_enabled")):
+            raise RuntimeError(f"{qid}: graph hybrid_node_scored path is not active")
+        selected_events, recall_events, final_events = list(metadata.get("selected_event_ids") or []), list(metadata.get("recall_event_ids") or []), list(metadata.get("final_hit_event_ids") or [])
+        slow_graph_events = [str(event_id) for event_id in [*selected_events, *recall_events, *final_events] if str(event_id).startswith("slow.")]
+        if slow_graph_events:
+            raise RuntimeError(f"{qid}: fast graph execution crossed the slow-layer boundary: " + ",".join(dict.fromkeys(slow_graph_events)))
+        if not selected_events:
+            raise RuntimeError(f"{qid}: graph model selected no events")
+        valid_locations = set(parent_candidates)
+        selected_parents, selected_unmapped = ordered_graph_parents(selected_events, valid_locations=valid_locations, strict_prefix=True)
+        recall_parents, recall_unmapped = ordered_graph_parents(recall_events, valid_locations=valid_locations)
+        final_parents, final_unmapped = ordered_graph_parents(final_events, valid_locations=valid_locations)
+        if [*selected_unmapped, *final_unmapped]:
+            raise RuntimeError(f"{qid}: graph events cannot map to persisted chunks")
+        graph_parents = list(dict.fromkeys([*selected_parents, *recall_parents]))[:args.graph_k]
+        graph_runtime_order = expand_parent_locations(graph_parents, parent_candidates)
+        graph_rank = {index: rank for rank, location in enumerate(graph_parents) for index in parent_candidates[location]}
+        selected_indexes, final_indexes = set(expand_parent_locations(selected_parents, parent_candidates)), set(expand_parent_locations(final_parents, parent_candidates))
+        graph_metadata = {"skipped": False, "adapter_reused": graph_adapter_reused, "selected_event_ids": selected_events, "recall_event_ids": recall_events, "final_hit_event_ids": final_events, "unmapped_recall_event_ids": recall_unmapped, "retrieval_mode": metadata.get("retrieval_mode"), "runtime_graph_cache_hit": bool(metadata.get("runtime_graph_cache_hit", False)), "hybrid_candidate_union_rescored": bool(metadata.get("hybrid_candidate_union_rescored", False)), "node_runtime_profile": dict(metadata.get("node_runtime_profile", {}) or {}), "hybrid_runtime_profile": dict(metadata.get("hybrid_runtime_profile", {}) or {}), "adapter_runtime_profile": dict(metadata.get("adapter_runtime_profile", {}) or {})}
+
+    fast_ranked: list[dict[str, Any]] = []
+    fast_scores: dict[str, float] = {}
+    dense_elapsed = 0.0
+    cross_elapsed = 0.0
+    if plan["mode"] != "SLOW_ONLY":
+        dense_started = time.time()
+        dense_scores = fast_vectors @ models.dense.encode_one(runtime_question)
+        dense_order = sorted(range(len(fast)), key=lambda i: (-float(dense_scores[i]), i))
+        dense_rank = {index: rank for rank, index in enumerate(dense_order)}
+        dense_elapsed = time.time() - dense_started
+        indexes = list(dict.fromkeys([*dense_order[:args.dense_k], *graph_runtime_order]))
+        if not indexes:
+            raise RuntimeError(f"{qid}: graph+dense union is empty")
+        session_count = max(int(candidate["session_index"]) for candidate in fast) + 1
+        runtime = []
+        for index in indexes:
+            item = dict(fast[index])
+            item["channels"] = {"dense_score": float(dense_scores[index]), "dense_rank_rr": rrank(dense_rank[index]), "graph_rank_rr": rrank(graph_rank.get(index)), "graph_selected": float(index in selected_indexes), "graph_final": float(index in final_indexes), "recency_norm": float(item["session_index"]) / max(1, session_count - 1)}
+            runtime.append(item)
+        cross_started = time.time()
+        reps, logits = models.encode_cross(runtime_question, [item["text"] for item in runtime])
+        channel_tensor = torch.tensor([[item["channels"][name] for name in CHANNEL_NAMES] for item in runtime], dtype=torch.float32, device=models.device)
+        with torch.inference_mode():
+            scores = models.fusion(reps.unsqueeze(0), logits.unsqueeze(0), channel_tensor.unsqueeze(0), torch.ones((1, len(runtime)), dtype=torch.bool, device=models.device), ablation="full")[0].detach().cpu()
+        cross_elapsed += time.time() - cross_started
+        for item, score, semantic in zip(runtime, scores.tolist(), logits.detach().cpu().tolist()):
+            item["score"], item["semantic_logit"] = float(score), float(semantic)
+        fast_ranked = _fast_candidates_with_slots(sorted(runtime, key=lambda item: -float(item["score"])), semantic_records)
+        fast_scores = {str(item["candidate_id"]): float(item["score"]) for item in fast_ranked}
+
+    slow_ranked: list[dict[str, Any]] = []
+    slow_dense_elapsed = 0.0
+    if slow and plan["mode"] != "FAST_ONLY":
+        slow_dense_started = time.time()
+        slow_dense_scores = slow_vectors @ models.dense.encode_one(runtime_question)
+        slow_dense_order = sorted(range(len(slow)), key=lambda i: (-float(slow_dense_scores[i]), i))
+        slow_dense_elapsed = time.time() - slow_dense_started
+        slow_indexes = slow_dense_order[: min(len(slow_dense_order), int(args.slow_dense_k))]
+        if not slow_indexes:
+            raise RuntimeError(f"{qid}: slow inventory is nonempty but dense shortlist is empty")
+        slow_ranked = [dict(slow[index]) for index in slow_indexes]
+        for index, item in zip(slow_indexes, slow_ranked):
+            item["slow_dense_score"] = float(slow_dense_scores[index])
+            item["slow_dense_rank"] = int(slow_dense_order.index(index))
+        cross_started = time.time()
+        _, logits = models.encode_cross(runtime_question, [item["text"] for item in slow_ranked])
+        cross_elapsed += time.time() - cross_started
+        for item, score in zip(slow_ranked, logits.detach().cpu().tolist()):
+            item["semantic_logit"] = float(score)
+        slow_ranked.sort(key=lambda item: -float(item["semantic_logit"]))
+    try:
+        units = apply_recall_plan(plan, fast_ranked, slow_ranked)
+    except RecallPlannerError as exc:
+        raise RuntimeError(f"{qid}: invalid planned evidence composition: {exc}") from exc
+    if plan["mode"] == "CONFLICT_COMPARE":
+        units.sort(
+            key=lambda item: (
+                -max(
+                    (
+                        fast_scores.get(str(candidate.get("candidate_id", "")), float("-inf"))
+                        for candidate in item.get("fast_candidates", [])
+                    ),
+                    default=float("-inf"),
+                ),
+                str(item["canonical_slot"]),
+            )
+        )
+    elif plan["primary_layer"] == "fast":
+        units.sort(key=lambda item: -fast_scores.get(str(item.get("fast_candidate", {}).get("candidate_id", "")), float("-inf")))
+    else:
+        units.sort(key=lambda item: -float(item.get("slow_capsule", {}).get("semantic_logit", float("-inf"))))
+
+    packed_units = pack_recall_units(units, fast, top_k=args.top_k, qid=qid)
+    evidence_by_location: dict[tuple[int, int, int], dict[str, Any]] = {}
+    for unit_rank, (unit, entries) in enumerate(packed_units, start=1):
+        attachments = _unit_attachments(unit)
+        for entry in entries:
+            capsules = list(entry.get("capsules") or [])
+            memory_contexts = [
+                {
+                    "role": next(
+                        (
+                            role
+                            for role in entry["roles"]
+                            if role in {"primary", "slow_conflict_candidate"}
+                        ),
+                        "slow_context",
+                    ),
+                    "capsule_id": item["capsule_id"],
+                    "canonical_slot": item["canonical_slot"],
+                    "claim_text": item["text"],
+                    "provenance": item["provenance"],
+                }
+                for item in capsules
+            ]
+            location = (
+                int(entry["session_index"]),
+                int(entry["parent_chunk_index"]),
+                int(entry["subchunk_index"]),
+            )
+            candidate = {
+                "memory_id": entry.get("candidate_id"),
+                "session_id": entry["session_id"],
+                "session_index": entry["session_index"],
+                "parent_chunk_index": entry["parent_chunk_index"],
+                "subchunk_index": entry["subchunk_index"],
+                "score": entry.get("score", entry.get("semantic_logit")),
+                "semantic_logit": entry.get("semantic_logit"),
+                "channels": entry.get("channels"),
+                "text": entry["text"],
+                "unit_type": unit["unit_type"],
+                "unit_types": [unit["unit_type"]],
+                "canonical_slot": unit["canonical_slot"],
+                "canonical_slots": [unit["canonical_slot"]],
+                "capsule_id": [item["capsule_id"] for item in capsules],
+                "role": list(entry["roles"]),
+                "provenance": [item["provenance"] for item in capsules]
+                or [entry.get("provenance")],
+                "memory_contexts": memory_contexts,
+                "attachments": attachments,
+            }
+            existing = evidence_by_location.get(location)
+            if existing is None:
+                evidence_by_location[location] = candidate
+                continue
+            for field in (
+                "unit_types",
+                "canonical_slots",
+                "capsule_id",
+                "role",
+                "provenance",
+                "memory_contexts",
+                "attachments",
+            ):
+                for item in candidate[field]:
+                    if item not in existing[field]:
+                        existing[field].append(item)
+    evidence_windows = list(evidence_by_location.values())
+    for rank, item in enumerate(evidence_windows, start=1):
+        item["rank"] = rank
+    selected_session_ids = list(
+        dict.fromkeys(str(item["session_id"]) for item in evidence_windows)
+    )
+    evidence = {"schema_version": SCHEMA_VERSION, "runtime_schema_version": "tmcra.v3.online-retrieval.3", "question_id": qid, "question": question, "question_date": question_date, "question_type": clean_text(row.get("question_type")), "selected_session_ids": selected_session_ids, "recall_plan": authoritative_plan, "evidence_windows": evidence_windows}
+    runtime_input_has_gold = any(key in row for key in ("answer", "gold_answer", "answer_session_ids", "labels", "supervision"))
+    debug = {"question_id": qid, "scope_id": scope_id, "db_path": str(db_path), "index_path": str(index_path), "recall_plan": authoritative_plan, "planner_decision_reason": planner_decision_reason, "planner_resolved_query": resolved_query, "recent_dialogue_count": len(recent_dialogue), "planner": planner_metadata, "cross_layer_weighted_fusion": False, "graph": graph_metadata, "runtime_input_has_gold": runtime_input_has_gold, "inventory_count": len(fast) + len(slow), "union_count": len(fast_ranked) + len(slow_ranked), "fast_inventory_count": len(fast), "fast_shortlist_count": len(fast_ranked), "slow_capsule_count": len(slow), "slow_shortlist_count": len(slow_ranked), "slow_dense_k": int(args.slow_dense_k), "fast_semantic_record_count": len(semantic_records), "planned_unit_count": len(units), "packed_unit_count": len(packed_units), "budget_excluded_unit_count": max(0, len(units) - len(packed_units)), "selected_count": len(evidence_windows), "atomic_unit_packing": True, "strict_no_truncation": True, "restart_boundary_verified": True, "graph_counts_before_query": counts_before, "graph_fingerprint": graph_fingerprint, "latency_sec": {"graph": round(graph_elapsed, 4), "dense": round(dense_elapsed, 4), "slow_dense": round(slow_dense_elapsed, 4), "cross": round(cross_elapsed, 4), "total": round(time.time() - started, 4)}}
+    if any(key in row for key in ("answer", "gold_answer", "answer_session_ids", "labels", "supervision")):
+        raise RuntimeError(f"{qid}: runtime retrieval manifest contains forbidden evaluation labels")
+    return evidence, debug
+
+
+def layered_retrieval_operation_id(out_dir: Path, scope_id: str, question_id: str) -> str:
+    identity = "\n".join(
+        (
+            "tmcra.v3.layered-retrieval",
+            str(out_dir.absolute()),
+            clean_text(scope_id),
+            clean_text(question_id),
+        )
+    )
+    return hashlib.sha256(identity.encode("utf-8")).hexdigest()
+
+
+def _atomic_write_text(path: Path, text: str) -> None:
+    temporary = path.with_name(f".{path.name}.tmp.{os.getpid()}.{time.time_ns()}")
+    temporary.write_text(text, encoding="utf-8")
+    os.replace(temporary, path)
+
+
+def _reconcile_completed_retrieval_output(
+    *,
+    out_dir: Path,
+    rows: Sequence[Mapping[str, Any]],
+    repo: Path,
+) -> dict[str, Any] | None:
+    """Reuse a committed retrieval directory and repair only missing idempotent audit state."""
+    if not out_dir.exists():
+        return None
+    required = {
+        "evidence": out_dir / "evidence_windows.jsonl",
+        "debug": out_dir / "retrieval_debug.jsonl",
+        "report": out_dir / "report.json",
+    }
+    missing = [name for name, path in required.items() if not path.is_file()]
+    if missing:
+        raise RuntimeError(
+            f"retrieval output directory is incomplete and will not be overwritten: "
+            f"{out_dir} missing={','.join(missing)}"
+        )
+    evidence_rows = read_jsonl(required["evidence"])
+    debug_rows = read_jsonl(required["debug"])
+    report = json.loads(required["report"].read_text(encoding="utf-8"))
+    expected_qids = [clean_text(row.get("question_id")) for row in rows]
+    evidence_qids = [clean_text(row.get("question_id")) for row in evidence_rows]
+    debug_qids = [clean_text(row.get("question_id")) for row in debug_rows]
+    if (
+        report.get("status") != "complete"
+        or evidence_qids != expected_qids
+        or debug_qids != expected_qids
+    ):
+        raise RuntimeError(f"existing retrieval output does not match its query manifest: {out_dir}")
+
+    newly_appended = 0
+    query_ids: list[str] = []
+    for evidence, debug in zip(evidence_rows, debug_rows):
+        plan = dict(evidence.get("recall_plan") or {})
+        legacy_reason = clean_text(plan.pop("decision_reason", ""))
+        if legacy_reason:
+            observed_reason = clean_text(debug.get("planner_decision_reason"))
+            if observed_reason and observed_reason != legacy_reason:
+                raise RuntimeError(
+                    f"{evidence['question_id']}: persisted planner reason disagrees with debug output"
+                )
+            debug["planner_decision_reason"] = legacy_reason
+            evidence["recall_plan"] = plan
+        operation_id = layered_retrieval_operation_id(
+            out_dir,
+            str(debug["scope_id"]),
+            str(evidence["question_id"]),
+        )
+        persisted = append_layered_retrieval_audit(
+            repo=repo,
+            db_path=Path(debug["db_path"]),
+            scope_id=str(debug["scope_id"]),
+            operation_id=operation_id,
+            evidence=evidence,
+            debug=debug,
+        )
+        audit_payload = dict(persisted.get("payload") or {})
+        query_id = clean_text(audit_payload.get("query_id"))
+        if not query_id:
+            raise RuntimeError(f"{evidence['question_id']}: persisted retrieval audit lacks query_id")
+        newly_appended += int(bool(persisted.get("appended")))
+        query_ids.append(query_id)
+        debug["layered_retrieval_audit"] = {
+            "operation_id": operation_id,
+            "query_id": query_id,
+            "event_total": int(persisted.get("event_total") or 0),
+            "trimmed_total": int(persisted.get("trimmed_total") or 0),
+            "newly_appended": bool(persisted.get("appended")),
+        }
+
+    report["layered_retrieval_audit_confirmed_count"] = len(query_ids)
+    report["layered_retrieval_audit_newly_appended_count"] = newly_appended
+    report["layered_retrieval_audit_query_ids"] = query_ids
+    report["reused_completed_output"] = True
+    _atomic_write_text(
+        required["evidence"],
+        "".join(json.dumps(row, ensure_ascii=False, sort_keys=True) + "\n" for row in evidence_rows),
+    )
+    _atomic_write_text(
+        required["debug"],
+        "".join(json.dumps(row, ensure_ascii=False, sort_keys=True) + "\n" for row in debug_rows),
+    )
+    _atomic_write_text(
+        required["report"], json.dumps(report, indent=2, sort_keys=True) + "\n"
+    )
+    return report
+
+
+def command_retrieve(args: argparse.Namespace) -> None:
+    query_manifest = Path(args.query_manifest)
+    try:
+        rows = read_jsonl(query_manifest)
+    except RuntimeError as exc:
+        if str(exc) == f"no rows: {query_manifest}":
+            raise RuntimeError(f"query manifest is empty: {query_manifest}") from exc
+        raise
+    out_dir = Path(args.out_dir).absolute()
+    completed_report = _reconcile_completed_retrieval_output(
+        out_dir=out_dir,
+        rows=rows,
+        repo=Path(args.repo),
+    )
+    if completed_report is not None:
+        print(json.dumps(completed_report, indent=2, sort_keys=True))
+        return
+    runtime_env = graph_runtime_env(args)
+    for path in (Path(args.node_model), Path(args.path_model), Path(args.checkpoint)):
+        if not path.exists():
+            raise FileNotFoundError(path)
+    planner = planner_from_env()
+    harness = load_native_harness(Path(args.harness), Path(args.repo))
+    harness.disable_topic_bucket_runtime()
+    models = OnlineModels(args)
+    started = time.time()
+    evidence_rows: list[dict[str, Any]] = []
+    debug_rows: list[dict[str, Any]] = []
+    graph_adapter_cache: dict[tuple[str, str], Any] = {}
+    newly_appended_audits = 0
+    for row_index, row in enumerate(rows, start=1):
+        evidence, debug = retrieve_one(
+            row,
+            args=args,
+            harness=harness,
+            models=models,
+            planner=planner,
+            graph_adapter_cache=graph_adapter_cache,
+        )
+        operation_id = layered_retrieval_operation_id(
+            out_dir,
+            str(debug["scope_id"]),
+            str(evidence["question_id"]),
+        )
+        persisted_audit = append_layered_retrieval_audit(
+            repo=Path(args.repo),
+            db_path=Path(debug["db_path"]),
+            scope_id=str(debug["scope_id"]),
+            operation_id=operation_id,
+            evidence=evidence,
+            debug=debug,
+        )
+        newly_appended_audits += int(bool(persisted_audit.get("appended")))
+        debug["layered_retrieval_audit"] = {
+            "operation_id": operation_id,
+            "query_id": clean_text(dict(persisted_audit.get("payload") or {}).get("query_id")),
+            "event_total": int(persisted_audit.get("event_total") or 0),
+            "trimmed_total": int(persisted_audit.get("trimmed_total") or 0),
+            "newly_appended": bool(persisted_audit.get("appended")),
+        }
+        evidence_rows.append(evidence)
+        debug_rows.append(debug)
+        print(
+            json.dumps(
+                {
+                    "status": "retrieved",
+                    "row": row_index,
+                    "total": len(rows),
+                    "question_id": evidence["question_id"],
+                    "inventory": debug["inventory_count"],
+                    "union": debug["union_count"],
+                    "selected": debug["selected_count"],
+                    "latency_sec": debug["latency_sec"]["total"],
+                }
+            ),
+            flush=True,
+        )
+    latency = [float(row["latency_sec"]["total"]) for row in debug_rows]
+    report = {
+        "status": "complete",
+        "schema_version": "tmcra.v3.online-retrieval-report.2",
+        "created_at": time.strftime("%Y-%m-%dT%H:%M:%S%z"),
+        "query_count": len(rows),
+        "runtime_input_with_gold_count": sum(int(row["runtime_input_has_gold"]) for row in debug_rows),
+        "restart_boundary_verified_count": sum(int(row["restart_boundary_verified"]) for row in debug_rows),
+        "layered_retrieval_audit_confirmed_count": sum(
+            int(bool(row.get("layered_retrieval_audit"))) for row in debug_rows
+        ),
+        "layered_retrieval_audit_newly_appended_count": newly_appended_audits,
+        "layered_retrieval_audit_query_ids": [
+            row["layered_retrieval_audit"]["query_id"] for row in debug_rows
+        ],
+        "checkpoint": str(models.checkpoint_path),
+        "checkpoint_sha256": models.checkpoint_sha256,
+        "cross_model_revision": models.cross_manifest.get("revision"),
+        "graph_runtime_env": runtime_env,
+        "strict_no_truncation": True,
+        "cross_layer_weighted_fusion": False,
+        "graph_adapter_cache_size": len(graph_adapter_cache),
+        "planner": {
+            "base_url_configured": bool(os.environ.get("TMCRA_RECALL_PLANNER_BASE_URL")),
+            "model": os.environ.get("TMCRA_RECALL_PLANNER_MODEL", DEEPSEEK_FLASH_MODEL),
+            "api_key_pool_size": len(planner.api_keys),
+        },
+        "top_k": args.top_k,
+        "dense_k": args.dense_k,
+        "graph_k": args.graph_k,
+        "slow_dense_k": args.slow_dense_k,
+        "atomic_unit_packing": True,
+        "avg_planned_unit_count": round(sum(row["planned_unit_count"] for row in debug_rows) / len(debug_rows), 4),
+        "avg_packed_unit_count": round(sum(row["packed_unit_count"] for row in debug_rows) / len(debug_rows), 4),
+        "avg_budget_excluded_unit_count": round(sum(row["budget_excluded_unit_count"] for row in debug_rows) / len(debug_rows), 4),
+        "avg_inventory_count": round(sum(row["inventory_count"] for row in debug_rows) / len(debug_rows), 4),
+        "avg_union_count": round(sum(row["union_count"] for row in debug_rows) / len(debug_rows), 4),
+        "avg_latency_sec": round(sum(latency) / len(latency), 4),
+        "max_latency_sec": round(max(latency), 4),
+        "elapsed_sec": round(time.time() - started, 3),
+        "evidence": str(out_dir / "evidence_windows.jsonl"),
+        "debug": str(out_dir / "retrieval_debug.jsonl"),
+        "reused_completed_output": False,
+    }
+    out_dir.parent.mkdir(parents=True, exist_ok=True)
+    staging = out_dir.with_name(
+        f".{out_dir.name}.staging.{os.getpid()}.{time.time_ns()}"
+    )
+    staging.mkdir(parents=False, exist_ok=False)
+    write_jsonl(staging / "evidence_windows.jsonl", evidence_rows)
+    write_jsonl(staging / "retrieval_debug.jsonl", debug_rows)
+    (staging / "report.json").write_text(
+        json.dumps(report, indent=2, sort_keys=True) + "\n", encoding="utf-8"
+    )
+    os.replace(staging, out_dir)
+    print(json.dumps(report, indent=2, sort_keys=True))
+
+
+def add_common_model_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--embedding-model", default=os.getenv("TMCRA_BGE_M3_PATH", "BAAI/bge-m3"))
+    parser.add_argument("--text-dim", type=int, default=1024)
+    parser.add_argument("--embedding-max-length", type=int, default=8192)
+    parser.add_argument("--device", default="cuda")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="TMCRA V3 production online index and retrieval runtime")
+    sub = parser.add_subparsers(dest="command", required=True)
+    index = sub.add_parser("build-index")
+    index.add_argument("--scope-manifest", required=True)
+    index.add_argument("--out-report", required=True)
+    index.add_argument("--subchunk-chars", type=int, default=1800)
+    index.add_argument("--subchunk-overlap", type=int, default=200)
+    index.add_argument("--batch-size", type=int, default=16)
+    add_common_model_args(index)
+
+    retrieve = sub.add_parser("retrieve")
+    retrieve.add_argument("--query-manifest", required=True)
+    retrieve.add_argument("--out-dir", required=True)
+    retrieve.add_argument("--checkpoint", required=True)
+    retrieve.add_argument("--cross-model", default=os.getenv("TMCRA_BGE_RERANKER_PATH", "BAAI/bge-reranker-v2-m3"))
+    retrieve.add_argument("--cross-max-length", type=int, default=1280)
+    retrieve.add_argument("--cross-batch-size", type=int, default=24)
+    retrieve.add_argument("--repo", required=True)
+    retrieve.add_argument("--harness", required=True)
+    retrieve.add_argument("--node-model", required=True)
+    retrieve.add_argument("--path-model", required=True)
+    retrieve.add_argument("--graph-device", default="cuda")
+    retrieve.add_argument("--candidate-event-k", type=int, default=24)
+    retrieve.add_argument("--support-path-k", type=int, default=3)
+    retrieve.add_argument("--path-tunnel-rescue-k", type=int, default=2)
+    retrieve.add_argument("--graph-top-k", type=int, default=12)
+    retrieve.add_argument("--dense-k", type=int, default=32)
+    retrieve.add_argument("--slow-dense-k", type=int, default=24)
+    retrieve.add_argument("--graph-k", type=int, default=24)
+    retrieve.add_argument("--top-k", type=int, default=8)
+    retrieve.add_argument("--max-per-parent", type=int, default=2)
+    retrieve.add_argument("--max-per-session", type=int, default=4)
+    add_common_model_args(retrieve)
+    args = parser.parse_args()
+    if args.command == "build-index":
+        command_build_index(args)
+    else:
+        command_retrieve(args)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

benchmarks/longmemeval/src/tmcra_benchmark/legacy/tmcra_v3_recall_planner.py

@@ -0,0 +1,406 @@
+"""Strict DeepSeek Flash control plane for recall composition."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import time
+import urllib.error
+import urllib.request
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+
+PLANNER_VERSION = "tmcra.recall-plan.v4"
+PLANNER_PROMPT_VERSION = "tmcra-recall-planner-2026-07-11.1"
+DEEPSEEK_FLASH_MODEL = "deepseek-v4-flash"
+MODES = frozenset(
+    {
+        "FAST_ONLY",
+        "SLOW_ONLY",
+        "SLOW_WITH_FAST_OVERRIDE",
+        "FAST_WITH_SLOW_CONTEXT",
+        "CONFLICT_COMPARE",
+    }
+)
+PLAN_FIELDS = frozenset(
+    {
+        "mode",
+        "primary_layer",
+        "fast_role",
+        "slow_role",
+        "requires_conflict_pairs",
+        "decision_code",
+        "resolved_query",
+        "decision_reason",
+        "planner_version",
+    }
+)
+_EXPECTED_POLICIES = {
+    "FAST_ONLY": ("fast", "primary", "excluded", False),
+    "SLOW_ONLY": ("slow", "excluded", "primary", False),
+    "SLOW_WITH_FAST_OVERRIDE": ("slow", "override", "primary", False),
+    "FAST_WITH_SLOW_CONTEXT": ("fast", "primary", "context_only", False),
+    "CONFLICT_COMPARE": ("fast", "conflict_candidate", "conflict_candidate", True),
+}
+_EXPECTED_DECISION_CODES = {
+    "FAST_ONLY": "recent_event",
+    "SLOW_ONLY": "stable_or_historical_durable",
+    "SLOW_WITH_FAST_OVERRIDE": "current_durable",
+    "FAST_WITH_SLOW_CONTEXT": "current_task_with_durable_context",
+    "CONFLICT_COMPARE": "explicit_conflict_or_comparison",
+}
+
+SYSTEM_PROMPT = f"""You are the retrieval control plane of a production hierarchical memory graph.
+Return exactly one JSON object with these fields and no others:
+{{"mode":"FAST_ONLY|SLOW_ONLY|SLOW_WITH_FAST_OVERRIDE|FAST_WITH_SLOW_CONTEXT|CONFLICT_COMPARE",
+  "primary_layer":"fast|slow",
+  "fast_role":"primary|excluded|override|conflict_candidate",
+  "slow_role":"primary|excluded|context_only|conflict_candidate",
+  "requires_conflict_pairs":true|false,
+  "decision_code":"recent_event|stable_or_historical_durable|current_durable|current_task_with_durable_context|explicit_conflict_or_comparison",
+  "resolved_query":"standalone retrieval query in the user's language",
+  "decision_reason":"concise reason grounded only in the query and recent dialogue",
+  "planner_version":"{PLANNER_VERSION}"}}
+
+Mode contracts are exact:
+- FAST_ONLY: explicitly recent episodic event, current task, or interaction lookup that needs no durable user background.
+- SLOW_ONLY: explicitly historical baseline, long-term background, or stable summary where the current effective value is not requested.
+- SLOW_WITH_FAST_OVERRIDE: the default for a present/current durable identity, preference, relationship, constraint, or state. Slow is primary and fast must check for recent corrections even when the query does not say "latest".
+- FAST_WITH_SLOW_CONTEXT: a current event/task is primary and durable user context is background-only.
+- CONFLICT_COMPARE: the query explicitly asks about change, contradiction, before/after, or competing states.
+
+Hard routing order:
+1. Explicit comparison, contradiction, or before/after change -> CONFLICT_COMPARE.
+2. A present/current/latest/still standing fact -> SLOW_WITH_FAST_OVERRIDE, never SLOW_ONLY.
+3. A current task or event that needs durable personalization -> FAST_WITH_SLOW_CONTEXT.
+4. An isolated recent event, task, or exact recent-turn lookup -> FAST_ONLY.
+5. SLOW_ONLY is allowed only for an explicitly historical baseline or stable long-term summary.
+6. An unresolved or uncertain follow-up must never use SLOW_ONLY; resolve it from recent_dialogue first.
+
+Resolve references using recent_dialogue only when needed. resolved_query must preserve the user's language and intent,
+be independently searchable without recent_dialogue, and must not answer the query or invent a memory fact. If the query
+is already standalone or the dialogue is unrelated, copy the query unchanged. The current query always overrides stale
+or unrelated dialogue.
+
+Never emit scores, weights, candidate IDs, benchmark labels, or an answer to the query. Never use a layer marked
+unavailable. Choose exactly one mode. This planner chooses roles only; it does not rank or fuse evidence."""
+
+
+class RecallPlannerError(RuntimeError):
+    pass
+
+
+class RecallPlannerResponseError(RecallPlannerError):
+    def __init__(self, message: str, *, response_content: str = "", request_metadata: Mapping[str, Any] | None = None) -> None:
+        super().__init__(message)
+        self.response_content = response_content
+        self.request_metadata = dict(request_metadata or {})
+
+
+def _text(value: Any) -> str:
+    return value.strip() if isinstance(value, str) else ""
+
+
+def _sha256(value: str) -> str:
+    return hashlib.sha256(value.encode("utf-8")).hexdigest()
+
+
+def _metadata(*, key_index: int, started: float, finish_reason: str, content: str = "", usage: Mapping[str, Any] | None = None, http_status: int | None = None, error_type: str | None = None, request_sha256: str = "") -> dict[str, Any]:
+    usage = usage or {}
+    result = {
+        "provider": "deepseek",
+        "model": DEEPSEEK_FLASH_MODEL,
+        "api_key_index": key_index,
+        "physical_call_count": 1,
+        "latency_seconds": round(time.time() - started, 3),
+        "response_sha256": _sha256(content),
+        "finish_reason": finish_reason,
+        "planner_version": PLANNER_VERSION,
+        "prompt_version": PLANNER_PROMPT_VERSION,
+        "request_sha256": request_sha256,
+        "prompt_tokens": int(usage.get("prompt_tokens", 0) or 0),
+        "completion_tokens": int(usage.get("completion_tokens", 0) or 0),
+        "total_tokens": int(usage.get("total_tokens", 0) or 0),
+    }
+    if http_status is not None:
+        result["http_status"] = int(http_status)
+    if error_type:
+        result["error_type"] = error_type
+    return result
+
+
+def _reject_gold(value: Any, path: str = "input") -> None:
+    if isinstance(value, Mapping):
+        for key, item in value.items():
+            key_text = str(key).lower()
+            if "gold" in key_text or "benchmark" in key_text or "expected_answer" in key_text:
+                raise RecallPlannerError(f"{path}.{key} is not permitted in planner input")
+            _reject_gold(item, f"{path}.{key}")
+    elif isinstance(value, list):
+        for index, item in enumerate(value):
+            _reject_gold(item, f"{path}[{index}]")
+
+
+def validate_recall_plan(value: Mapping[str, Any]) -> dict[str, Any]:
+    if not isinstance(value, Mapping) or set(value) != PLAN_FIELDS:
+        raise RecallPlannerError("RecallPlan root must contain exactly the required schema fields")
+    mode = _text(value.get("mode"))
+    if mode not in MODES:
+        raise RecallPlannerError(f"unsupported RecallPlan mode: {mode!r}")
+    primary_layer, fast_role, slow_role, requires_pairs = _EXPECTED_POLICIES[mode]
+    if (
+        value.get("primary_layer") != primary_layer
+        or value.get("fast_role") != fast_role
+        or value.get("slow_role") != slow_role
+        or value.get("requires_conflict_pairs") is not requires_pairs
+    ):
+        raise RecallPlannerError(f"RecallPlan role policy does not match mode {mode}")
+    if value.get("decision_code") != _EXPECTED_DECISION_CODES[mode]:
+        raise RecallPlannerError(f"RecallPlan decision_code does not match mode {mode}")
+    reason = _text(value.get("decision_reason"))
+    if not reason:
+        raise RecallPlannerError("RecallPlan decision_reason is required")
+    resolved_query = _text(value.get("resolved_query"))
+    if not resolved_query:
+        raise RecallPlannerError("RecallPlan resolved_query is required")
+    if len(resolved_query) > 2000:
+        raise RecallPlannerError("RecallPlan resolved_query exceeds 2000 characters")
+    if value.get("planner_version") != PLANNER_VERSION:
+        raise RecallPlannerError(f"RecallPlan planner_version must be {PLANNER_VERSION!r}")
+    return {field: value[field] for field in PLAN_FIELDS}
+
+
+def _validate_recent_dialogue(value: Any) -> list[dict[str, Any]]:
+    if value is None:
+        return []
+    if not isinstance(value, Sequence) or isinstance(value, (str, bytes)):
+        raise RecallPlannerError("recent_dialogue must be a sequence of turn objects")
+    if len(value) > 8:
+        raise RecallPlannerError("recent_dialogue may contain at most 8 turns")
+    output: list[dict[str, Any]] = []
+    for index, item in enumerate(value):
+        if not isinstance(item, Mapping) or set(item) != {"turn_index", "speaker", "text"}:
+            raise RecallPlannerError(f"recent_dialogue[{index}] must contain exactly turn_index, speaker, and text")
+        try:
+            turn_index = int(item["turn_index"])
+        except (TypeError, ValueError) as exc:
+            raise RecallPlannerError(f"recent_dialogue[{index}].turn_index must be an integer") from exc
+        speaker = _text(item.get("speaker")).lower()
+        text = _text(item.get("text"))
+        if speaker not in {"user", "assistant"} or not text:
+            raise RecallPlannerError(f"recent_dialogue[{index}] has an invalid speaker or empty text")
+        if len(text) > 4000:
+            raise RecallPlannerError(f"recent_dialogue[{index}].text exceeds 4000 characters")
+        output.append({"turn_index": turn_index, "speaker": speaker, "text": text})
+    if any(left["turn_index"] >= right["turn_index"] for left, right in zip(output, output[1:])):
+        raise RecallPlannerError("recent_dialogue must be in strictly increasing turn order")
+    _reject_gold(output, "recent_dialogue")
+    return output
+
+
+def _layer_available(value: Any) -> bool:
+    if isinstance(value, Mapping) and "available" in value:
+        return value.get("available") is True
+    if isinstance(value, Sequence) and not isinstance(value, (str, bytes)):
+        return bool(value)
+    return bool(value)
+
+
+def validate_plan_availability(plan: Mapping[str, Any], available_layers: Mapping[str, Any]) -> None:
+    fast_available = _layer_available(available_layers.get("fast"))
+    slow_available = _layer_available(available_layers.get("slow"))
+    mode = plan["mode"]
+    if mode in {"FAST_ONLY", "SLOW_WITH_FAST_OVERRIDE", "FAST_WITH_SLOW_CONTEXT", "CONFLICT_COMPARE"} and not fast_available:
+        raise RecallPlannerError(f"RecallPlan mode {mode} requires an unavailable fast layer")
+    if mode in {"SLOW_ONLY", "SLOW_WITH_FAST_OVERRIDE", "FAST_WITH_SLOW_CONTEXT", "CONFLICT_COMPARE"} and not slow_available:
+        raise RecallPlannerError(f"RecallPlan mode {mode} requires an unavailable slow layer")
+
+
+class DeepSeekFlashRecallPlanner:
+    """One physical Flash call per plan request; errors are never retried or routed."""
+
+    def __init__(self, *, base_url: str, model: str, api_keys: Sequence[str], timeout: float = 30, max_tokens: int = 512) -> None:
+        self.base_url = _text(base_url).rstrip("/")
+        self.model = model
+        self.api_keys = list(dict.fromkeys(_text(key) for key in api_keys if _text(key)))
+        self.timeout = max(1.0, float(timeout))
+        self.max_tokens = max(128, int(max_tokens))
+        self.request_index = 0
+        if not self.base_url or not self.api_keys:
+            raise RecallPlannerError("planner base_url and API key pool are required")
+        if self.model != DEEPSEEK_FLASH_MODEL:
+            raise RecallPlannerError(f"recall planner requires {DEEPSEEK_FLASH_MODEL}, got {self.model!r}")
+
+    def plan(self, *, query: str, question_date: str, available_layers: Mapping[str, Any], recent_dialogue: Sequence[Mapping[str, Any]] | None = None) -> tuple[dict[str, Any], dict[str, Any]]:
+        if not _text(query) or not _text(question_date):
+            raise RecallPlannerError("query and question_date are required")
+        if not isinstance(available_layers, Mapping) or set(available_layers) - {"fast", "slow"}:
+            raise RecallPlannerError("available_layers may contain only fast and slow summaries")
+        _reject_gold(available_layers, "available_layers")
+        dialogue = _validate_recent_dialogue(recent_dialogue)
+        payload = {"query": query, "question_date": question_date, "recent_dialogue": dialogue, "available_layers": dict(available_layers)}
+        key_index = self.request_index % len(self.api_keys)
+        self.request_index += 1
+        request_body = {
+            "model": DEEPSEEK_FLASH_MODEL,
+            "messages": [{"role": "system", "content": SYSTEM_PROMPT}, {"role": "user", "content": json.dumps(payload, ensure_ascii=False, separators=(",", ":"))}],
+            "temperature": 0,
+            "max_tokens": self.max_tokens,
+            "response_format": {"type": "json_object"},
+            "thinking": {"type": "disabled"},
+        }
+        request_sha256 = _sha256(json.dumps(request_body, ensure_ascii=False, sort_keys=True))
+        request = urllib.request.Request(
+            f"{self.base_url}/chat/completions",
+            data=json.dumps(request_body, ensure_ascii=False).encode("utf-8"),
+            headers={"Content-Type": "application/json", "Authorization": f"Bearer {self.api_keys[key_index]}"},
+            method="POST",
+        )
+        started = time.time()
+        try:
+            with urllib.request.urlopen(request, timeout=self.timeout) as response:
+                raw_http = response.read().decode("utf-8")
+                response_payload = json.loads(raw_http)
+        except urllib.error.HTTPError as exc:
+            detail = exc.read().decode("utf-8", errors="replace")[:1000]
+            raise RecallPlannerResponseError(f"recall planner HTTP {exc.code}: {detail}", response_content=detail, request_metadata=_metadata(key_index=key_index, started=started, finish_reason="http_error", content=detail, http_status=exc.code, request_sha256=request_sha256)) from exc
+        except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+            raw = locals().get("raw_http", "")
+            raise RecallPlannerResponseError("recall planner returned invalid HTTP JSON", response_content=raw, request_metadata=_metadata(key_index=key_index, started=started, finish_reason="invalid_http_json", content=raw, error_type=exc.__class__.__name__, request_sha256=request_sha256)) from exc
+        except Exception as exc:
+            raise RecallPlannerResponseError(f"recall planner request failed: {exc.__class__.__name__}: {exc}", request_metadata=_metadata(key_index=key_index, started=started, finish_reason="request_error", error_type=exc.__class__.__name__, request_sha256=request_sha256)) from exc
+        usage = response_payload.get("usage") if isinstance(response_payload, Mapping) else {}
+        choices = response_payload.get("choices") if isinstance(response_payload, Mapping) else None
+        if not isinstance(choices, list) or len(choices) != 1 or not isinstance(choices[0], Mapping):
+            raise RecallPlannerResponseError("recall planner response must contain exactly one choice", response_content=raw_http, request_metadata=_metadata(key_index=key_index, started=started, finish_reason="invalid_response", content=raw_http, usage=usage if isinstance(usage, Mapping) else {}, request_sha256=request_sha256))
+        choice = choices[0]
+        content = (choice.get("message") or {}).get("content") if isinstance(choice.get("message"), Mapping) else None
+        finish_reason = _text(choice.get("finish_reason"))
+        metadata = _metadata(key_index=key_index, started=started, finish_reason=finish_reason, content=content if isinstance(content, str) else raw_http, usage=usage if isinstance(usage, Mapping) else {}, request_sha256=request_sha256)
+        if finish_reason != "stop" or not isinstance(content, str):
+            raise RecallPlannerResponseError("recall planner response did not finish with a JSON string", response_content=raw_http, request_metadata=metadata)
+        try:
+            plan = validate_recall_plan(json.loads(content))
+        except (json.JSONDecodeError, RecallPlannerError) as exc:
+            raise RecallPlannerResponseError(f"recall planner returned invalid RecallPlan: {exc}", response_content=content, request_metadata=metadata) from exc
+        try:
+            validate_plan_availability(plan, available_layers)
+        except RecallPlannerError as exc:
+            raise RecallPlannerResponseError(
+                f"recall planner selected an unavailable layer: {exc}",
+                response_content=content,
+                request_metadata=metadata,
+            ) from exc
+        return plan, metadata
+
+
+def _source_parents(item: Mapping[str, Any]) -> list[dict[str, Any]]:
+    raw_values: list[Any] = []
+    if isinstance(item.get("source_parent"), Mapping):
+        raw_values.append(item["source_parent"])
+    if isinstance(item.get("source_parents"), Sequence) and not isinstance(item.get("source_parents"), (str, bytes)):
+        raw_values.extend(item["source_parents"])
+    parents: list[dict[str, Any]] = []
+    seen: set[tuple[int, int]] = set()
+    for raw in raw_values:
+        if not isinstance(raw, Mapping):
+            raise RecallPlannerError("slow capsule source parent must be an object")
+        try:
+            location = (int(raw["session_index"]), int(raw["parent_chunk_index"]))
+        except (KeyError, TypeError, ValueError) as exc:
+            raise RecallPlannerError("slow capsule source parent lacks integer session/parent coordinates") from exc
+        if location in seen:
+            continue
+        seen.add(location)
+        parents.append(dict(raw))
+    return parents
+
+
+def _group_by_slot(items: Sequence[Mapping[str, Any]], *, layer: str, require_parent: bool) -> dict[str, list[Mapping[str, Any]]]:
+    grouped: dict[str, list[Mapping[str, Any]]] = {}
+    for item in items:
+        if not isinstance(item, Mapping):
+            raise RecallPlannerError(f"{layer} candidate must be a mapping")
+        slot = _text(item.get("canonical_slot"))
+        if not slot:
+            raise RecallPlannerError(f"{layer} candidate lacks canonical_slot")
+        if require_parent and not _source_parents(item):
+            raise RecallPlannerError(f"slow capsule {slot!r} lacks source_parent mapping")
+        grouped.setdefault(slot, []).append(item)
+    return grouped
+
+
+def apply_recall_plan(plan: Mapping[str, Any], fast_candidates: Sequence[Mapping[str, Any]], slow_capsules: Sequence[Mapping[str, Any]]) -> list[dict[str, Any]]:
+    """Compose evidence units by role, without combining or recalculating layer scores."""
+    normalized = validate_recall_plan(plan)
+    fast = _group_by_slot(fast_candidates, layer="fast", require_parent=False)
+    slow = _group_by_slot(slow_capsules, layer="slow", require_parent=True)
+    mode = normalized["mode"]
+    units: list[dict[str, Any]] = []
+    if mode == "FAST_ONLY":
+        return [
+            {"unit_type": "fast_primary", "canonical_slot": slot, "primary_layer": "fast", "fast_candidate": candidate}
+            for slot, candidates in fast.items()
+            for candidate in candidates
+        ]
+    if mode == "SLOW_ONLY":
+        return [
+            {"unit_type": "slow_primary", "canonical_slot": slot, "primary_layer": "slow", "slow_capsule": capsule}
+            for slot, capsules in slow.items()
+            for capsule in capsules
+        ]
+    if mode == "SLOW_WITH_FAST_OVERRIDE":
+        for slot, capsules in slow.items():
+            for capsule in capsules:
+                units.append(
+                    {
+                        "unit_type": "slow_primary_with_fast_override",
+                        "canonical_slot": slot,
+                        "primary_layer": "slow",
+                        "slow_capsule": capsule,
+                        "fast_overrides": list(fast.get(slot, [])),
+                    }
+                )
+        return units
+    if mode == "FAST_WITH_SLOW_CONTEXT":
+        all_slow_context = [capsule for capsules in slow.values() for capsule in capsules]
+        for slot, candidates in fast.items():
+            for candidate in candidates:
+                units.append(
+                    {
+                        "unit_type": "fast_primary_with_slow_context",
+                        "canonical_slot": slot,
+                        "primary_layer": "fast",
+                        "fast_candidate": candidate,
+                        "slow_context": list(all_slow_context),
+                    }
+                )
+        return units
+    for slot in fast.keys() & slow.keys():
+        units.append(
+            {
+                "unit_type": "conflict_group",
+                "canonical_slot": slot,
+                "primary_layer": "fast",
+                "fast_candidates": list(fast[slot]),
+                "slow_capsules": list(slow[slot]),
+            }
+        )
+    if not units and fast and slow:
+        ranked_fast = [candidate for candidates in fast.values() for candidate in candidates]
+        ranked_slow = [capsule for capsules in slow.values() for capsule in capsules]
+        pair_count = max(len(ranked_fast), len(ranked_slow))
+        for index in range(pair_count):
+            units.append(
+                {
+                    "unit_type": "conflict_group",
+                    "canonical_slot": f"semantic_conflict.{index}",
+                    "primary_layer": "fast",
+                    "fast_candidates": [ranked_fast[min(index, len(ranked_fast) - 1)]],
+                    "slow_capsules": [ranked_slow[min(index, len(ranked_slow) - 1)]],
+                }
+            )
+    if not units:
+        raise RecallPlannerError("CONFLICT_COMPARE produced no semantic conflict pairs")
+    return units

benchmarks/longmemeval/src/tmcra_benchmark/legacy/tmcra_v3_reranker.py

@@ -0,0 +1,1014 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import random
+import time
+from collections import Counter, defaultdict
+from pathlib import Path
+from typing import Any, Mapping, Sequence
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+from tmcra_v3_schema import (
+    CHANNEL_NAMES,
+    SCHEMA_VERSION,
+    channel_vector,
+    clean_text,
+    read_jsonl,
+    validate_sample,
+    write_jsonl,
+)
+from tmcra_model_assets import load_optional_hf_model_manifest
+
+
+def pair_key(sample: Mapping[str, Any], candidate: Mapping[str, Any]) -> str:
+    payload = "\0".join(
+        (
+            clean_text(sample.get("question_id")),
+            clean_text(candidate.get("candidate_id")),
+            clean_text(sample.get("query_text")),
+            clean_text(candidate.get("text")),
+        )
+    )
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+def stable_int(value: str) -> int:
+    return int.from_bytes(hashlib.blake2b(value.encode("utf-8"), digest_size=8).digest(), "big")
+
+
+def atomic_torch_save(payload: Mapping[str, Any], target: Path) -> None:
+    temporary = target.with_suffix(target.suffix + ".tmp")
+    torch.save(dict(payload), temporary)
+    os.replace(temporary, target)
+
+
+def command_precompute_cross(args: argparse.Namespace) -> None:
+    if not torch.cuda.is_available() and not args.cpu:
+        raise RuntimeError("CUDA is unavailable; pass --cpu explicitly")
+    from transformers import AutoModelForSequenceClassification, AutoTokenizer
+
+    sample_paths = [Path(value) for value in args.samples]
+    rows = [row for path in sample_paths for row in read_jsonl(path)]
+    for row in rows:
+        validate_sample(
+            row,
+            require_positive=False,
+            allowed_splits=("full_eval", "train", "holdout", "aux_train", "aux_dev"),
+        )
+    model_dir = Path(args.model).resolve()
+    model_manifest = load_optional_hf_model_manifest(model_dir)
+    out_dir = Path(args.out_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    shard_dir = out_dir / "shards"
+    shard_dir.mkdir(parents=True, exist_ok=True)
+    items: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    raw_pair_count = 0
+    duplicate_pair_count = 0
+    for row in rows:
+        for candidate in row["candidates"]:
+            raw_pair_count += 1
+            key = pair_key(row, candidate)
+            if key in seen:
+                duplicate_pair_count += 1
+                continue
+            seen.add(key)
+            items.append(
+                {
+                    "key": key,
+                    "question_id": row["question_id"],
+                    "candidate_id": candidate["candidate_id"],
+                    "query_text": row["query_text"],
+                    "candidate_text": candidate["text"],
+                }
+            )
+    write_jsonl(
+        out_dir / "items.jsonl",
+        [
+            {
+                "key": item["key"],
+                "question_id": item["question_id"],
+                "candidate_id": item["candidate_id"],
+                "query_len": len(item["query_text"]),
+                "candidate_len": len(item["candidate_text"]),
+            }
+            for item in items
+        ],
+    )
+    device = torch.device("cpu" if args.cpu else "cuda")
+    tokenizer = AutoTokenizer.from_pretrained(
+        str(model_dir),
+        local_files_only=True,
+        trust_remote_code=False,
+    )
+    model = AutoModelForSequenceClassification.from_pretrained(
+        str(model_dir),
+        local_files_only=True,
+        trust_remote_code=False,
+        torch_dtype=torch.float32 if args.cpu else torch.float16,
+    ).to(device)
+    model.eval()
+    hidden_size = int(getattr(model.config, "hidden_size", 0) or 0)
+    if hidden_size <= 0:
+        raise RuntimeError("reranker config.hidden_size is missing")
+    started = time.time()
+    shard_paths: list[Path] = []
+    for start in range(0, len(items), args.shard_size):
+        stop = min(len(items), start + args.shard_size)
+        shard_index = start // args.shard_size
+        shard_path = shard_dir / f"shard_{shard_index:05d}.pt"
+        expected_keys = [item["key"] for item in items[start:stop]]
+        if shard_path.exists():
+            cached = torch.load(shard_path, map_location="cpu", weights_only=True)
+            if list(cached.get("keys") or []) != expected_keys:
+                raise RuntimeError(f"cross-cache resume key mismatch: {shard_path}")
+            representations = cached.get("representations")
+            logits = cached.get("semantic_logits")
+            if representations is None or logits is None:
+                raise RuntimeError(f"cross-cache resume payload invalid: {shard_path}")
+            if tuple(representations.shape) != (len(expected_keys), hidden_size):
+                raise RuntimeError(f"cross-cache resume representation shape mismatch: {shard_path}")
+            print(json.dumps({"status": "resume", "shard": shard_index, "done": stop, "total": len(items)}), flush=True)
+            shard_paths.append(shard_path)
+            continue
+        rep_chunks: list[torch.Tensor] = []
+        logit_chunks: list[torch.Tensor] = []
+        shard_items = items[start:stop]
+        with torch.inference_mode():
+            for batch_start in range(0, len(shard_items), args.batch_size):
+                batch = shard_items[batch_start : batch_start + args.batch_size]
+                encoded = tokenizer(
+                    [item["query_text"] for item in batch],
+                    [item["candidate_text"] for item in batch],
+                    padding=True,
+                    truncation=False,
+                    return_tensors="pt",
+                )
+                token_lengths = encoded["attention_mask"].sum(dim=1)
+                longest = int(token_lengths.max())
+                if longest > args.max_length:
+                    offending = int(torch.argmax(token_lengths))
+                    raise RuntimeError(
+                        f"cross-encoder pair has {longest} tokens, exceeding strict max_length={args.max_length}; "
+                        f"qid={batch[offending]['question_id']} candidate={batch[offending]['candidate_id']}"
+                    )
+                encoded = {key: value.to(device) for key, value in encoded.items()}
+                output = model(**encoded, output_hidden_states=True, return_dict=True)
+                if output.hidden_states is None:
+                    raise RuntimeError("reranker did not return hidden states")
+                representation = output.hidden_states[-1][:, 0].detach().cpu().float()
+                semantic = output.logits.detach().cpu().float()
+                if semantic.ndim == 2 and semantic.shape[1] == 1:
+                    semantic = semantic[:, 0]
+                elif semantic.ndim != 1:
+                    raise RuntimeError(f"expected one reranker logit per pair, got {tuple(semantic.shape)}")
+                rep_chunks.append(representation.to(torch.float16))
+                logit_chunks.append(semantic)
+        representations = torch.cat(rep_chunks, dim=0).contiguous()
+        logits = torch.cat(logit_chunks, dim=0).contiguous()
+        atomic_torch_save(
+            {"keys": expected_keys, "representations": representations, "semantic_logits": logits},
+            shard_path,
+        )
+        print(
+            json.dumps(
+                {
+                    "status": "encoded",
+                    "shard": shard_index,
+                    "done": stop,
+                    "total": len(items),
+                    "elapsed_sec": round(time.time() - started, 3),
+                }
+            ),
+            flush=True,
+        )
+        shard_paths.append(shard_path)
+    all_keys: list[str] = []
+    all_representations: list[torch.Tensor] = []
+    all_logits: list[torch.Tensor] = []
+    for path in shard_paths:
+        payload = torch.load(path, map_location="cpu", weights_only=True)
+        all_keys.extend(list(payload["keys"]))
+        all_representations.append(payload["representations"])
+        all_logits.append(payload["semantic_logits"])
+    expected_all_keys = [item["key"] for item in items]
+    representations = torch.cat(all_representations, dim=0).contiguous()
+    logits = torch.cat(all_logits, dim=0).contiguous()
+    if all_keys != expected_all_keys:
+        raise RuntimeError("cross-cache final key order mismatch")
+    if tuple(representations.shape) != (len(items), hidden_size) or tuple(logits.shape) != (len(items),):
+        raise RuntimeError("cross-cache final tensor shape mismatch")
+    atomic_torch_save(
+        {"keys": all_keys, "representations": representations, "semantic_logits": logits},
+        out_dir / "cross_cache.pt",
+    )
+    manifest = {
+        "created_at": time.strftime("%Y-%m-%dT%H:%M:%S%z"),
+        "schema_version": SCHEMA_VERSION,
+        "samples": [str(path.resolve()) for path in sample_paths],
+        "sample_count": len(rows),
+        "pair_count": len(items),
+        "raw_pair_count": raw_pair_count,
+        "duplicate_pair_count": duplicate_pair_count,
+        "hidden_size": hidden_size,
+        "max_length": args.max_length,
+        "strict_no_truncation": True,
+        "dtype": "float16",
+        "model": str(model_dir),
+        "model_repo_id": model_manifest.get("repo_id"),
+        "model_revision": model_manifest.get("revision"),
+        "elapsed_sec": round(time.time() - started, 3),
+    }
+    (out_dir / "manifest.json").write_text(json.dumps(manifest, indent=2, sort_keys=True), encoding="utf-8")
+    print(json.dumps(manifest, indent=2, sort_keys=True))
+
+
+class CrossRepresentationCache:
+    def __init__(self, root: str):
+        directory = Path(root)
+        manifest_path = directory / "manifest.json"
+        cache_path = directory / "cross_cache.pt"
+        if not manifest_path.exists() or not cache_path.exists():
+            raise FileNotFoundError(f"complete cross cache is required: {directory}")
+        self.manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+        payload = torch.load(cache_path, map_location="cpu", weights_only=True)
+        keys = list(payload.get("keys") or [])
+        representations = payload.get("representations")
+        semantic_logits = payload.get("semantic_logits")
+        if not keys or representations is None or semantic_logits is None:
+            raise RuntimeError(f"invalid cross cache: {cache_path}")
+        if len(keys) != len(set(keys)) or len(keys) != representations.shape[0] or len(keys) != semantic_logits.shape[0]:
+            raise RuntimeError(f"cross cache row mismatch: {cache_path}")
+        self.index = {key: index for index, key in enumerate(keys)}
+        self.representations = representations.float().contiguous()
+        self.semantic_logits = semantic_logits.float().contiguous()
+        self.hidden_size = int(representations.shape[1])
+
+    def get(self, sample: Mapping[str, Any], candidate: Mapping[str, Any]) -> tuple[torch.Tensor, torch.Tensor]:
+        key = pair_key(sample, candidate)
+        index = self.index.get(key)
+        if index is None:
+            raise RuntimeError(
+                f"cross cache miss: qid={sample.get('question_id')} candidate={candidate.get('candidate_id')} key={key}"
+            )
+        return self.representations[index], self.semantic_logits[index]
+
+
+class ChannelAwareMemoryReranker(nn.Module):
+    def __init__(
+        self,
+        representation_dim: int,
+        channel_dim: int,
+        hidden_dim: int = 256,
+        layers: int = 2,
+        channel_mean: torch.Tensor | None = None,
+        channel_scale: torch.Tensor | None = None,
+    ):
+        super().__init__()
+        mean = torch.zeros(channel_dim, dtype=torch.float32) if channel_mean is None else channel_mean.float()
+        scale = torch.ones(channel_dim, dtype=torch.float32) if channel_scale is None else channel_scale.float()
+        if tuple(mean.shape) != (channel_dim,) or tuple(scale.shape) != (channel_dim,):
+            raise RuntimeError("channel normalization tensors have the wrong shape")
+        self.register_buffer("channel_mean", mean.contiguous())
+        self.register_buffer("channel_scale", scale.clamp_min(1e-4).contiguous())
+        self.representation_proj = nn.Sequential(
+            nn.LayerNorm(representation_dim),
+            nn.Linear(representation_dim, hidden_dim),
+            nn.GELU(),
+        )
+        self.semantic_proj = nn.Sequential(nn.Linear(1, hidden_dim), nn.GELU())
+        self.channel_proj = nn.Sequential(nn.Linear(channel_dim, hidden_dim), nn.GELU())
+        self.channel_gate = nn.Sequential(nn.Linear(hidden_dim * 2, hidden_dim), nn.Sigmoid())
+        encoder_layer = nn.TransformerEncoderLayer(
+            d_model=hidden_dim,
+            nhead=8,
+            dim_feedforward=hidden_dim * 3,
+            dropout=0.1,
+            activation="gelu",
+            batch_first=True,
+            norm_first=True,
+        )
+        self.set_encoder = nn.TransformerEncoder(encoder_layer, num_layers=max(1, int(layers)))
+        self.delta_head = nn.Sequential(
+            nn.LayerNorm(hidden_dim),
+            nn.Linear(hidden_dim, hidden_dim),
+            nn.GELU(),
+            nn.Dropout(0.1),
+            nn.Linear(hidden_dim, 1),
+        )
+        nn.init.zeros_(self.delta_head[-1].weight)
+        nn.init.zeros_(self.delta_head[-1].bias)
+
+    def forward(
+        self,
+        representations: torch.Tensor,
+        semantic_logits: torch.Tensor,
+        channels: torch.Tensor,
+        mask: torch.Tensor,
+        *,
+        ablation: str = "full",
+    ) -> torch.Tensor:
+        if ablation not in {"full", "no_language", "no_channels", "no_graph"}:
+            raise RuntimeError(f"unknown ablation: {ablation}")
+        reps = representations
+        semantic = semantic_logits
+        feature_values = (channels - self.channel_mean) / self.channel_scale
+        if ablation == "no_language":
+            reps = torch.zeros_like(reps)
+            semantic = torch.zeros_like(semantic)
+        if ablation == "no_channels":
+            feature_values = torch.zeros_like(feature_values)
+        elif ablation == "no_graph":
+            feature_values = feature_values.clone()
+            feature_values[..., 2:5] = 0.0
+        rep_hidden = self.representation_proj(reps)
+        semantic_hidden = self.semantic_proj(semantic.unsqueeze(-1))
+        channel_hidden = self.channel_proj(feature_values)
+        gate = self.channel_gate(torch.cat((rep_hidden, semantic_hidden), dim=-1))
+        hidden = rep_hidden + semantic_hidden + gate * channel_hidden
+        hidden = self.set_encoder(hidden, src_key_padding_mask=~mask)
+        delta = self.delta_head(hidden).squeeze(-1)
+        scores = semantic + delta
+        return scores.masked_fill(~mask, -1e4)
+
+
+def select_training_candidates(sample: Mapping[str, Any], max_candidates: int, epoch: int) -> list[dict[str, Any]]:
+    candidates = list(sample["candidates"])
+    positives = [candidate for candidate in candidates if candidate["labels"]["relevance"]]
+    negatives = [candidate for candidate in candidates if not candidate["labels"]["relevance"]]
+    if not positives:
+        raise RuntimeError(f"training sample has no positive: {sample.get('question_id')}")
+    if max_candidates < 2:
+        raise RuntimeError("max_train_candidates must be at least 2")
+    positive_budget = min(len(positives), max(1, max_candidates // 2))
+    positives.sort(
+        key=lambda candidate: (
+            -float(candidate["channels"]["graph_rank_rr"]),
+            -float(candidate["channels"]["dense_score"]),
+            clean_text(candidate["candidate_id"]),
+        )
+    )
+    if len(positives) > positive_budget:
+        anchor_count = min(2, positive_budget)
+        anchors = positives[:anchor_count]
+        rotating = positives[anchor_count:]
+        rng = random.Random(stable_int(f"positive-bag:{epoch}:{sample['question_id']}"))
+        rng.shuffle(rotating)
+        positives = anchors + rotating[: positive_budget - anchor_count]
+    negatives.sort(
+        key=lambda candidate: (
+            -int(bool(candidate["labels"]["hard_negative"])),
+            -float(candidate["channels"]["graph_rank_rr"]),
+            -float(candidate["channels"]["dense_score"]),
+            clean_text(candidate["candidate_id"]),
+        )
+    )
+    selected = positives + negatives[: max(0, max_candidates - len(positives))]
+    rng = random.Random(stable_int(f"candidate-shuffle:{epoch}:{sample['question_id']}"))
+    rng.shuffle(selected)
+    return selected
+
+
+def make_batch(
+    samples: Sequence[Mapping[str, Any]],
+    cache: CrossRepresentationCache,
+    device: torch.device,
+    *,
+    training: bool,
+    max_candidates: int,
+    epoch: int,
+) -> dict[str, Any]:
+    selected_by_sample = [
+        select_training_candidates(sample, max_candidates, epoch) if training else list(sample["candidates"])
+        for sample in samples
+    ]
+    max_count = max(len(candidates) for candidates in selected_by_sample)
+    batch_size = len(samples)
+    representations = torch.zeros((batch_size, max_count, cache.hidden_size), dtype=torch.float32)
+    semantic = torch.zeros((batch_size, max_count), dtype=torch.float32)
+    channels = torch.zeros((batch_size, max_count, len(CHANNEL_NAMES)), dtype=torch.float32)
+    labels = torch.zeros((batch_size, max_count), dtype=torch.float32)
+    mask = torch.zeros((batch_size, max_count), dtype=torch.bool)
+    candidate_ids: list[list[str]] = []
+    sample_weights = torch.tensor(
+        [float((sample.get("supervision") or {}).get("training_weight", 1.0) or 1.0) for sample in samples],
+        dtype=torch.float32,
+    )
+    for row_index, (sample, candidates) in enumerate(zip(samples, selected_by_sample)):
+        ids: list[str] = []
+        for candidate_index, candidate in enumerate(candidates):
+            representation, semantic_logit = cache.get(sample, candidate)
+            representations[row_index, candidate_index] = representation
+            semantic[row_index, candidate_index] = semantic_logit
+            channels[row_index, candidate_index] = torch.tensor(channel_vector(candidate), dtype=torch.float32)
+            labels[row_index, candidate_index] = float(bool(candidate["labels"]["relevance"]))
+            mask[row_index, candidate_index] = True
+            ids.append(clean_text(candidate["candidate_id"]))
+        candidate_ids.append(ids)
+    return {
+        "representations": representations.to(device),
+        "semantic_logits": semantic.to(device),
+        "channels": channels.to(device),
+        "labels": labels.to(device),
+        "mask": mask.to(device),
+        "candidate_ids": candidate_ids,
+        "sample_weights": sample_weights.to(device),
+    }
+
+
+def listwise_loss(
+    scores: torch.Tensor,
+    labels: torch.Tensor,
+    mask: torch.Tensor,
+    sample_weights: torch.Tensor | None = None,
+) -> torch.Tensor:
+    losses: list[torch.Tensor] = []
+    weights: list[torch.Tensor] = []
+    if sample_weights is None:
+        sample_weights = torch.ones(scores.shape[0], dtype=scores.dtype, device=scores.device)
+    for row_scores, row_labels, row_mask, row_weight in zip(scores, labels, mask, sample_weights):
+        valid_scores = row_scores[row_mask]
+        valid_labels = row_labels[row_mask]
+        if not bool((valid_labels > 0.5).any()):
+            continue
+        log_probabilities = F.log_softmax(valid_scores, dim=0)
+        positive_mask = valid_labels > 0.5
+        losses.append(-torch.logsumexp(log_probabilities[positive_mask], dim=0))
+        weights.append(row_weight)
+    if not losses:
+        return scores.sum() * 0.0
+    loss_tensor = torch.stack(losses)
+    weight_tensor = torch.stack(weights).to(dtype=loss_tensor.dtype).clamp_min(1e-6)
+    return (loss_tensor * weight_tensor).sum() / weight_tensor.sum()
+
+
+def rank_metrics_update(target: dict[str, float], scores: torch.Tensor, labels: torch.Tensor, valid: torch.Tensor) -> None:
+    valid_scores = scores[valid]
+    valid_labels = labels[valid]
+    positives = set(torch.nonzero(valid_labels > 0.5, as_tuple=False).squeeze(-1).tolist())
+    target["n"] += 1
+    if not positives:
+        target["candidate_miss"] += 1
+        return
+    order = torch.argsort(valid_scores, descending=True).tolist()
+    rank = next((position + 1 for position, index in enumerate(order) if index in positives), None)
+    for cutoff in (1, 3, 5, 10, 20):
+        target[f"recall@{cutoff}"] += int(rank is not None and rank <= cutoff)
+    target["mrr"] += 0.0 if rank is None else 1.0 / rank
+
+
+def finalize_metrics(values: Mapping[str, float]) -> dict[str, Any]:
+    n = max(1.0, float(values.get("n", 0.0)))
+    output: dict[str, Any] = {"n": int(values.get("n", 0.0))}
+    for key, value in sorted(values.items()):
+        if key == "n":
+            continue
+        output[key] = round(float(value) / n, 6)
+    return output
+
+
+def evaluate_model(
+    model: ChannelAwareMemoryReranker,
+    rows: Sequence[Mapping[str, Any]],
+    cache: CrossRepresentationCache,
+    device: torch.device,
+    *,
+    batch_size: int,
+    ablation: str,
+) -> dict[str, Any]:
+    model.eval()
+    totals: dict[str, float] = defaultdict(float)
+    with torch.no_grad():
+        for start in range(0, len(rows), batch_size):
+            samples = rows[start : start + batch_size]
+            batch = make_batch(samples, cache, device, training=False, max_candidates=0, epoch=0)
+            scores = model(
+                batch["representations"],
+                batch["semantic_logits"],
+                batch["channels"],
+                batch["mask"],
+                ablation=ablation,
+            ).cpu()
+            labels = batch["labels"].cpu()
+            mask = batch["mask"].cpu()
+            for index in range(len(samples)):
+                rank_metrics_update(totals, scores[index], labels[index], mask[index])
+    return finalize_metrics(totals)
+
+
+def split_train_dev(rows: Sequence[Mapping[str, Any]], dev_count: int) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    ordered = sorted(rows, key=lambda row: (stable_int(f"tmcra-v3-dev:{row['question_id']}"), row["question_id"]))
+    if dev_count <= 0 or dev_count >= len(ordered):
+        raise RuntimeError("dev_count must leave non-empty train and dev sets")
+    dev = list(ordered[:dev_count])
+    train = list(ordered[dev_count:])
+    return train, dev
+
+
+def compute_channel_statistics(rows: Sequence[Mapping[str, Any]]) -> tuple[torch.Tensor, torch.Tensor]:
+    values = [channel_vector(candidate) for row in rows for candidate in row["candidates"]]
+    if not values:
+        raise RuntimeError("cannot compute channel statistics from an empty candidate set")
+    matrix = torch.tensor(values, dtype=torch.float32)
+    mean = matrix.mean(dim=0)
+    scale = matrix.std(dim=0, unbiased=False)
+    scale = torch.where(scale < 1e-4, torch.ones_like(scale), scale)
+    return mean, scale
+
+
+def load_model_checkpoint(path: Path, cache: CrossRepresentationCache, device: torch.device) -> tuple[ChannelAwareMemoryReranker, dict[str, Any]]:
+    checkpoint = torch.load(path, map_location=device, weights_only=True)
+    if checkpoint.get("schema_version") != SCHEMA_VERSION:
+        raise RuntimeError("checkpoint schema version mismatch")
+    if tuple(checkpoint.get("channel_names") or ()) != CHANNEL_NAMES:
+        raise RuntimeError("checkpoint channel contract mismatch")
+    config = checkpoint["model_config"]
+    model = ChannelAwareMemoryReranker(
+        representation_dim=cache.hidden_size,
+        channel_dim=len(CHANNEL_NAMES),
+        hidden_dim=int(config["hidden_dim"]),
+        layers=int(config["layers"]),
+    ).to(device)
+    model.load_state_dict(checkpoint["model_state"])
+    return model, checkpoint
+
+
+def command_train(args: argparse.Namespace) -> None:
+    rows = read_jsonl(Path(args.train_samples))
+    for row in rows:
+        validate_sample(row, require_positive=True, allowed_splits=("train", "aux_train"))
+    if args.dev_samples:
+        train_rows = list(rows)
+        dev_rows = read_jsonl(Path(args.dev_samples))
+        for row in dev_rows:
+            validate_sample(row, require_positive=False, allowed_splits=("train", "full_eval", "aux_dev"))
+    else:
+        train_rows, dev_rows = split_train_dev(rows, args.dev_count)
+    cache = CrossRepresentationCache(args.cross_cache)
+    device = torch.device("cpu" if args.cpu else "cuda")
+    if device.type == "cuda" and not torch.cuda.is_available():
+        raise RuntimeError("CUDA is unavailable; pass --cpu explicitly")
+    channel_mean, channel_scale = compute_channel_statistics(train_rows)
+    model = ChannelAwareMemoryReranker(
+        representation_dim=cache.hidden_size,
+        channel_dim=len(CHANNEL_NAMES),
+        hidden_dim=args.hidden_dim,
+        layers=args.layers,
+        channel_mean=channel_mean,
+        channel_scale=channel_scale,
+    ).to(device)
+    if args.init_checkpoint:
+        initial = torch.load(Path(args.init_checkpoint), map_location="cpu", weights_only=True)
+        if initial.get("schema_version") != SCHEMA_VERSION:
+            raise RuntimeError("initial checkpoint schema version mismatch")
+        if tuple(initial.get("channel_names") or ()) != CHANNEL_NAMES:
+            raise RuntimeError("initial checkpoint channel contract mismatch")
+        initial_config = initial.get("model_config") or {}
+        if int(initial_config.get("hidden_dim", -1)) != args.hidden_dim or int(initial_config.get("layers", -1)) != args.layers:
+            raise RuntimeError("initial checkpoint architecture does not match requested hidden_dim/layers")
+        transferable = {
+            key: value
+            for key, value in initial["model_state"].items()
+            if key not in {"channel_mean", "channel_scale"}
+        }
+        missing, unexpected = model.load_state_dict(transferable, strict=False)
+        if set(missing) != {"channel_mean", "channel_scale"} or unexpected:
+            raise RuntimeError(f"unexpected initial checkpoint keys: missing={missing} unexpected={unexpected}")
+    optimizer = torch.optim.AdamW(model.parameters(), lr=args.lr, weight_decay=args.weight_decay)
+    rng = random.Random(args.seed)
+    out_dir = Path(args.out_dir)
+    out_dir.mkdir(parents=True, exist_ok=False)
+    best_score: float | None = None
+    best_epoch = 0
+    stale_epochs = 0
+    history: list[dict[str, Any]] = []
+    for epoch in range(1, args.epochs + 1):
+        model.train()
+        rng.shuffle(train_rows)
+        losses: list[float] = []
+        for start in range(0, len(train_rows), args.batch_size):
+            samples = train_rows[start : start + args.batch_size]
+            batch = make_batch(
+                samples,
+                cache,
+                device,
+                training=True,
+                max_candidates=args.max_train_candidates,
+                epoch=epoch,
+            )
+            scores = model(
+                batch["representations"],
+                batch["semantic_logits"],
+                batch["channels"],
+                batch["mask"],
+            )
+            ranking_loss = listwise_loss(scores, batch["labels"], batch["mask"], batch["sample_weights"])
+            valid_delta = (scores - batch["semantic_logits"])[batch["mask"]]
+            regularization = valid_delta.square().mean() if valid_delta.numel() else scores.sum() * 0.0
+            loss = ranking_loss + args.delta_l2 * regularization
+            optimizer.zero_grad(set_to_none=True)
+            loss.backward()
+            nn.utils.clip_grad_norm_(model.parameters(), 1.0)
+            optimizer.step()
+            losses.append(float(loss.detach().cpu()))
+        dev_metrics = evaluate_model(
+            model,
+            dev_rows,
+            cache,
+            device,
+            batch_size=args.batch_size,
+            ablation="full",
+        )
+        teacher_dev_rows = [
+            row
+            for row in dev_rows
+            if clean_text((row.get("supervision") or {}).get("target_type")) == "teacher_aligned_turn_bag"
+        ]
+        dev_teacher_metrics = (
+            evaluate_model(
+                model,
+                teacher_dev_rows,
+                cache,
+                device,
+                batch_size=args.batch_size,
+                ablation="full",
+            )
+            if teacher_dev_rows
+            else {"n": 0}
+        )
+        summary = {
+            "epoch": epoch,
+            "loss": round(sum(losses) / max(1, len(losses)), 6),
+            "dev": dev_metrics,
+            "dev_teacher_aligned": dev_teacher_metrics,
+        }
+        history.append(summary)
+        print(json.dumps(summary), flush=True)
+        score_metrics = dev_teacher_metrics if int(dev_teacher_metrics.get("n", 0)) >= 10 else dev_metrics
+        score = (
+            float(score_metrics.get("recall@1", 0.0))
+            + 0.25 * float(score_metrics.get("mrr", 0.0))
+            + 0.05 * float(score_metrics.get("recall@5", 0.0))
+        )
+        if best_score is None or score > best_score:
+            best_score = score
+            best_epoch = epoch
+            stale_epochs = 0
+            atomic_torch_save(
+                {
+                    "schema_version": SCHEMA_VERSION,
+                    "channel_names": CHANNEL_NAMES,
+                    "model_config": {"hidden_dim": args.hidden_dim, "layers": args.layers},
+                    "model_state": model.state_dict(),
+                    "channel_statistics": {
+                        "mean": channel_mean.tolist(),
+                        "scale": channel_scale.tolist(),
+                    },
+                    "epoch": epoch,
+                    "dev_metrics": dev_metrics,
+                    "dev_teacher_aligned_metrics": dev_teacher_metrics,
+                    "cross_cache_manifest": cache.manifest,
+                    "train_args": vars(args),
+                },
+                out_dir / "tmcra_v3_reranker.pt",
+            )
+        else:
+            stale_epochs += 1
+        if args.patience > 0 and stale_epochs >= args.patience:
+            print(json.dumps({"status": "early_stop", "epoch": epoch, "best_epoch": best_epoch}), flush=True)
+            break
+    report = {
+        "status": "complete",
+        "schema_version": SCHEMA_VERSION,
+        "train_count": len(train_rows),
+        "dev_count": len(dev_rows),
+        "best_epoch": best_epoch,
+        "best_score": best_score,
+        "init_checkpoint": str(Path(args.init_checkpoint).resolve()) if args.init_checkpoint else "",
+        "channel_statistics": {"mean": channel_mean.tolist(), "scale": channel_scale.tolist()},
+        "selection_metric_scope": "teacher_aligned_dev" if any(
+            int(item.get("dev_teacher_aligned", {}).get("n", 0)) >= 10 for item in history
+        ) else "all_dev",
+        "checkpoint": str(out_dir / "tmcra_v3_reranker.pt"),
+        "history": history,
+    }
+    (out_dir / "train_report.json").write_text(json.dumps(report, indent=2, sort_keys=True), encoding="utf-8")
+    print(json.dumps(report, indent=2, sort_keys=True))
+
+
+def direct_scores(sample: Mapping[str, Any], method: str) -> list[float]:
+    candidates = list(sample["candidates"])
+    if method == "dense":
+        return [float(candidate["channels"]["dense_score"]) for candidate in candidates]
+    if method == "graph":
+        return [float(candidate["channels"]["graph_rank_rr"]) for candidate in candidates]
+    raise RuntimeError(method)
+
+
+def command_eval(args: argparse.Namespace) -> None:
+    rows = read_jsonl(Path(args.samples))
+    if args.qid_list:
+        qids = {clean_text(value) for value in Path(args.qid_list).read_text(encoding="utf-8").splitlines() if clean_text(value)}
+        rows = [row for row in rows if clean_text(row.get("question_id")) in qids]
+    if args.limit > 0:
+        rows = rows[: args.limit]
+    if not rows:
+        raise RuntimeError("no evaluation rows")
+    for row in rows:
+        validate_sample(row, require_positive=False)
+    cache = CrossRepresentationCache(args.cross_cache)
+    device = torch.device("cpu" if args.cpu else "cuda")
+    if device.type == "cuda" and not torch.cuda.is_available():
+        raise RuntimeError("CUDA is unavailable; pass --cpu explicitly")
+    model, checkpoint = load_model_checkpoint(Path(args.checkpoint), cache, device)
+    methods = ("dense", "graph", "base_cross", "fusion", "no_language", "no_channels", "no_graph")
+    totals = {method: defaultdict(float) for method in methods}
+    by_type: dict[str, dict[str, dict[str, float]]] = {
+        method: defaultdict(lambda: defaultdict(float)) for method in methods
+    }
+    by_supervision: dict[str, dict[str, dict[str, float]]] = {
+        method: defaultdict(lambda: defaultdict(float)) for method in methods
+    }
+    predictions: list[dict[str, Any]] = []
+    model.eval()
+    with torch.no_grad():
+        for start in range(0, len(rows), args.batch_size):
+            samples = rows[start : start + args.batch_size]
+            batch = make_batch(samples, cache, device, training=False, max_candidates=0, epoch=0)
+            model_scores = {
+                "base_cross": batch["semantic_logits"].cpu(),
+                "fusion": model(batch["representations"], batch["semantic_logits"], batch["channels"], batch["mask"], ablation="full").cpu(),
+                "no_language": model(batch["representations"], batch["semantic_logits"], batch["channels"], batch["mask"], ablation="no_language").cpu(),
+                "no_channels": model(batch["representations"], batch["semantic_logits"], batch["channels"], batch["mask"], ablation="no_channels").cpu(),
+                "no_graph": model(batch["representations"], batch["semantic_logits"], batch["channels"], batch["mask"], ablation="no_graph").cpu(),
+            }
+            labels = batch["labels"].cpu()
+            mask = batch["mask"].cpu()
+            for row_index, sample in enumerate(samples):
+                qtype = clean_text(sample.get("question_type")) or "unknown"
+                supervision_type = clean_text((sample.get("supervision") or {}).get("target_type")) or "unspecified"
+                valid = mask[row_index]
+                score_map: dict[str, torch.Tensor] = {
+                    "dense": torch.tensor(direct_scores(sample, "dense"), dtype=torch.float32),
+                    "graph": torch.tensor(direct_scores(sample, "graph"), dtype=torch.float32),
+                }
+                score_map.update({method: values[row_index][valid] for method, values in model_scores.items()})
+                ranks: dict[str, int | None] = {}
+                top_ids: dict[str, list[str]] = {}
+                valid_labels = labels[row_index][valid]
+                positives = set(torch.nonzero(valid_labels > 0.5, as_tuple=False).squeeze(-1).tolist())
+                for method in methods:
+                    scores = score_map[method]
+                    method_valid = torch.ones_like(scores, dtype=torch.bool)
+                    rank_metrics_update(totals[method], scores, valid_labels, method_valid)
+                    rank_metrics_update(by_type[method][qtype], scores, valid_labels, method_valid)
+                    rank_metrics_update(by_supervision[method][supervision_type], scores, valid_labels, method_valid)
+                    order = torch.argsort(scores, descending=True).tolist()
+                    ranks[method] = next((position + 1 for position, index in enumerate(order) if index in positives), None)
+                    top_ids[method] = [batch["candidate_ids"][row_index][index] for index in order[:10]]
+                predictions.append(
+                    {
+                        "question_id": sample["question_id"],
+                        "question_type": qtype,
+                        "supervision_type": supervision_type,
+                        "candidate_count": int(valid.sum()),
+                        "gold_candidate_count": len(positives),
+                        "ranks": ranks,
+                        "top10": top_ids,
+                    }
+                )
+    out_dir = Path(args.out_dir)
+    out_dir.mkdir(parents=True, exist_ok=False)
+    write_jsonl(out_dir / "predictions.jsonl", predictions)
+    report = {
+        "status": "complete",
+        "created_at": time.strftime("%Y-%m-%dT%H:%M:%S%z"),
+        "schema_version": SCHEMA_VERSION,
+        "samples": str(Path(args.samples).resolve()),
+        "sample_count": len(rows),
+        "checkpoint": str(Path(args.checkpoint).resolve()),
+        "checkpoint_epoch": checkpoint.get("epoch"),
+        "cross_cache": str(Path(args.cross_cache).resolve()),
+        "metrics": {method: finalize_metrics(totals[method]) for method in methods},
+        "metrics_by_question_type": {
+            method: {qtype: finalize_metrics(values) for qtype, values in sorted(by_type[method].items())}
+            for method in methods
+        },
+        "metrics_by_supervision": {
+            method: {name: finalize_metrics(values) for name, values in sorted(by_supervision[method].items())}
+            for method in methods
+        },
+    }
+    (out_dir / "report.json").write_text(json.dumps(report, indent=2, sort_keys=True), encoding="utf-8")
+    print(json.dumps(report, indent=2, sort_keys=True))
+
+
+def command_export_evidence(args: argparse.Namespace) -> None:
+    rows = read_jsonl(Path(args.samples))
+    if args.qid_list:
+        requested = [
+            clean_text(value)
+            for value in Path(args.qid_list).read_text(encoding="utf-8").splitlines()
+            if clean_text(value)
+        ]
+        by_qid = {clean_text(row.get("question_id")): row for row in rows}
+        missing = [qid for qid in requested if qid not in by_qid]
+        if missing:
+            raise RuntimeError(f"requested qids are missing from samples: {missing[:10]}")
+        rows = [by_qid[qid] for qid in requested]
+    if args.limit > 0:
+        rows = rows[: args.limit]
+    if not rows:
+        raise RuntimeError("no rows for evidence export")
+    for row in rows:
+        validate_sample(row, require_positive=False)
+    cache = CrossRepresentationCache(args.cross_cache)
+    device = torch.device("cpu" if args.cpu else "cuda")
+    if device.type == "cuda" and not torch.cuda.is_available():
+        raise RuntimeError("CUDA is unavailable; pass --cpu explicitly")
+    model, checkpoint = load_model_checkpoint(Path(args.checkpoint), cache, device)
+    model.eval()
+    output_rows: list[dict[str, Any]] = []
+    recall = Counter()
+    with torch.no_grad():
+        for start in range(0, len(rows), args.batch_size):
+            samples = rows[start : start + args.batch_size]
+            batch = make_batch(samples, cache, device, training=False, max_candidates=0, epoch=0)
+            if args.method == "fusion":
+                scores = model(
+                    batch["representations"],
+                    batch["semantic_logits"],
+                    batch["channels"],
+                    batch["mask"],
+                    ablation="full",
+                ).cpu()
+            elif args.method == "base_cross":
+                scores = batch["semantic_logits"].cpu().masked_fill(~batch["mask"].cpu(), -1e4)
+            elif args.method in {"dense", "graph"}:
+                channel_name = "dense_score" if args.method == "dense" else "graph_rank_rr"
+                scores = torch.full(batch["mask"].shape, -1e4, dtype=torch.float32)
+                for row_index, sample in enumerate(samples):
+                    values = [float(candidate["channels"][channel_name]) for candidate in sample["candidates"]]
+                    scores[row_index, : len(values)] = torch.tensor(values, dtype=torch.float32)
+            else:
+                raise RuntimeError(f"unsupported evidence method: {args.method}")
+            labels = batch["labels"].cpu()
+            mask = batch["mask"].cpu()
+            for row_index, sample in enumerate(samples):
+                candidates = list(sample["candidates"])
+                valid_count = int(mask[row_index].sum())
+                order = torch.argsort(scores[row_index, :valid_count], descending=True).tolist()
+                selected_indexes: list[int] = []
+                parent_counts: Counter[tuple[int, int]] = Counter()
+                session_counts: Counter[str] = Counter()
+                for candidate_index in order:
+                    candidate = candidates[candidate_index]
+                    parent_key = (int(candidate["session_index"]), int(candidate.get("parent_chunk_index", 0)))
+                    session_id = clean_text(candidate.get("session_id"))
+                    if args.max_per_parent > 0 and parent_counts[parent_key] >= args.max_per_parent:
+                        continue
+                    if args.max_per_session > 0 and session_counts[session_id] >= args.max_per_session:
+                        continue
+                    selected_indexes.append(candidate_index)
+                    parent_counts[parent_key] += 1
+                    session_counts[session_id] += 1
+                    if len(selected_indexes) >= args.top_k:
+                        break
+                positives = set(
+                    torch.nonzero(labels[row_index, :valid_count] > 0.5, as_tuple=False).squeeze(-1).tolist()
+                )
+                recall["n"] += 1
+                recall["hit"] += int(any(index in positives for index in selected_indexes))
+                supervision_type = clean_text((sample.get("supervision") or {}).get("target_type")) or "unspecified"
+                recall[f"n:{supervision_type}"] += 1
+                recall[f"hit:{supervision_type}"] += int(any(index in positives for index in selected_indexes))
+                evidence_windows = []
+                for rank, candidate_index in enumerate(selected_indexes, start=1):
+                    candidate = candidates[candidate_index]
+                    evidence_windows.append(
+                        {
+                            "memory_id": candidate["candidate_id"],
+                            "session_id": candidate["session_id"],
+                            "session_index": candidate["session_index"],
+                            "parent_chunk_index": candidate.get("parent_chunk_index", 0),
+                            "subchunk_index": candidate.get("subchunk_index", 0),
+                            "score": round(float(scores[row_index, candidate_index]), 6),
+                            "rank": rank,
+                            "text": candidate["text"],
+                            "channels": candidate["channels"],
+                        }
+                    )
+                output_rows.append(
+                    {
+                        "schema_version": SCHEMA_VERSION,
+                        "question_id": sample["question_id"],
+                        "question": sample["question"],
+                        "question_date": sample.get("question_date", ""),
+                        "question_type": sample.get("question_type", ""),
+                        "gold_answer": sample.get("gold_answer", ""),
+                        "answer_session_ids": sample.get("answer_session_ids", []),
+                        "selected_session_ids": [window["session_id"] for window in evidence_windows],
+                        "evidence_windows": evidence_windows,
+                    }
+                )
+    out_dir = Path(args.out_dir)
+    out_dir.mkdir(parents=True, exist_ok=False)
+    write_jsonl(out_dir / "evidence_windows.jsonl", output_rows)
+    report = {
+        "status": "complete",
+        "created_at": time.strftime("%Y-%m-%dT%H:%M:%S%z"),
+        "schema_version": SCHEMA_VERSION,
+        "samples": str(Path(args.samples).resolve()),
+        "sample_count": len(output_rows),
+        "top_k": args.top_k,
+        "method": args.method,
+        "max_per_parent": args.max_per_parent,
+        "max_per_session": args.max_per_session,
+        "evidence_recall": round(float(recall["hit"]) / max(1, int(recall["n"])), 6),
+        "evidence_recall_by_supervision": {
+            name.removeprefix("n:"): round(
+                float(recall[f"hit:{name.removeprefix('n:')}"]) / max(1, int(count)), 6
+            )
+            for name, count in sorted(recall.items())
+            if name.startswith("n:")
+        },
+        "checkpoint": str(Path(args.checkpoint).resolve()),
+        "checkpoint_epoch": checkpoint.get("epoch"),
+        "output": str(out_dir / "evidence_windows.jsonl"),
+    }
+    (out_dir / "report.json").write_text(json.dumps(report, indent=2, sort_keys=True), encoding="utf-8")
+    print(json.dumps(report, indent=2, sort_keys=True))
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    sub = parser.add_subparsers(dest="command", required=True)
+    precompute = sub.add_parser("precompute-cross")
+    precompute.add_argument("--samples", required=True, nargs="+")
+    precompute.add_argument("--model", required=True)
+    precompute.add_argument("--out-dir", required=True)
+    precompute.add_argument("--max-length", type=int, default=1280)
+    precompute.add_argument("--batch-size", type=int, default=4)
+    precompute.add_argument("--shard-size", type=int, default=500)
+    precompute.add_argument("--cpu", action="store_true")
+    train = sub.add_parser("train")
+    train.add_argument("--train-samples", required=True)
+    train.add_argument("--dev-samples", default="")
+    train.add_argument("--cross-cache", required=True)
+    train.add_argument("--out-dir", required=True)
+    train.add_argument("--init-checkpoint", default="")
+    train.add_argument("--hidden-dim", type=int, default=256)
+    train.add_argument("--layers", type=int, default=2)
+    train.add_argument("--batch-size", type=int, default=8)
+    train.add_argument("--max-train-candidates", type=int, default=32)
+    train.add_argument("--dev-count", type=int, default=40)
+    train.add_argument("--epochs", type=int, default=16)
+    train.add_argument("--lr", type=float, default=2e-4)
+    train.add_argument("--weight-decay", type=float, default=0.01)
+    train.add_argument("--delta-l2", type=float, default=0.002)
+    train.add_argument("--patience", type=int, default=4)
+    train.add_argument("--seed", type=int, default=31)
+    train.add_argument("--cpu", action="store_true")
+    evaluate = sub.add_parser("eval")
+    evaluate.add_argument("--samples", required=True)
+    evaluate.add_argument("--cross-cache", required=True)
+    evaluate.add_argument("--checkpoint", required=True)
+    evaluate.add_argument("--out-dir", required=True)
+    evaluate.add_argument("--batch-size", type=int, default=8)
+    evaluate.add_argument("--limit", type=int, default=0)
+    evaluate.add_argument("--qid-list", default="")
+    evaluate.add_argument("--cpu", action="store_true")
+    export = sub.add_parser("export-evidence")
+    export.add_argument("--samples", required=True)
+    export.add_argument("--cross-cache", required=True)
+    export.add_argument("--checkpoint", required=True)
+    export.add_argument("--out-dir", required=True)
+    export.add_argument("--top-k", type=int, default=8)
+    export.add_argument("--method", choices=("dense", "graph", "base_cross", "fusion"), default="fusion")
+    export.add_argument("--max-per-parent", type=int, default=0)
+    export.add_argument("--max-per-session", type=int, default=0)
+    export.add_argument("--batch-size", type=int, default=8)
+    export.add_argument("--limit", type=int, default=0)
+    export.add_argument("--qid-list", default="")
+    export.add_argument("--cpu", action="store_true")
+    args = parser.parse_args()
+    if args.command == "precompute-cross":
+        command_precompute_cross(args)
+    elif args.command == "train":
+        command_train(args)
+    elif args.command == "eval":
+        command_eval(args)
+    else:
+        command_export_evidence(args)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

benchmarks/longmemeval/src/tmcra_benchmark/legacy/tmcra_v3_schema.py

@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import json
+import math
+from pathlib import Path
+from typing import Any, Mapping, Sequence
+
+
+SCHEMA_VERSION = "tmcra.memory_recall.v3.0"
+CHANNEL_NAMES = (
+    "dense_score",
+    "dense_rank_rr",
+    "graph_rank_rr",
+    "graph_selected",
+    "graph_final",
+    "recency_norm",
+)
+FORBIDDEN_CHANNEL_TOKENS = ("label", "positive", "negative", "hard", "gold", "answer")
+
+
+def clean_text(value: Any) -> str:
+    return " ".join(str(value or "").split())
+
+
+def read_jsonl(path: Path) -> list[dict[str, Any]]:
+    if not path.exists():
+        raise FileNotFoundError(path)
+    rows: list[dict[str, Any]] = []
+    with path.open("r", encoding="utf-8", errors="strict") as handle:
+        for line_no, line in enumerate(handle, start=1):
+            if not line.strip():
+                continue
+            try:
+                value = json.loads(line)
+            except json.JSONDecodeError as exc:
+                raise RuntimeError(f"invalid jsonl at {path}:{line_no}: {exc}") from exc
+            if not isinstance(value, dict):
+                raise RuntimeError(f"jsonl row is not an object at {path}:{line_no}")
+            rows.append(value)
+    if not rows:
+        raise RuntimeError(f"jsonl is empty: {path}")
+    return rows
+
+
+def write_jsonl(path: Path, rows: Sequence[Mapping[str, Any]]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", encoding="utf-8") as handle:
+        for row in rows:
+            handle.write(json.dumps(row, ensure_ascii=False, sort_keys=True) + "\n")
+
+
+def channel_vector(candidate: Mapping[str, Any]) -> list[float]:
+    channels = candidate.get("channels")
+    if not isinstance(channels, Mapping):
+        raise RuntimeError("candidate.channels must be an object")
+    return [float(channels[name]) for name in CHANNEL_NAMES]
+
+
+def _require_finite(value: Any, context: str) -> float:
+    try:
+        number = float(value)
+    except (TypeError, ValueError) as exc:
+        raise RuntimeError(f"{context} is not numeric: {value!r}") from exc
+    if not math.isfinite(number):
+        raise RuntimeError(f"{context} is not finite: {number!r}")
+    return number
+
+
+def validate_candidate(candidate: Mapping[str, Any], *, context: str) -> None:
+    candidate_id = clean_text(candidate.get("candidate_id"))
+    text = clean_text(candidate.get("text"))
+    if not candidate_id:
+        raise RuntimeError(f"{context}: candidate_id is required")
+    if not text:
+        raise RuntimeError(f"{context}: text is required")
+    channels = candidate.get("channels")
+    if not isinstance(channels, Mapping):
+        raise RuntimeError(f"{context}: channels must be an object")
+    if len(channels) != len(CHANNEL_NAMES) or set(channels) != set(CHANNEL_NAMES):
+        raise RuntimeError(
+            f"{context}: channel keys must exactly equal {CHANNEL_NAMES}, got {tuple(channels.keys())}"
+        )
+    for name, value in channels.items():
+        lowered = name.lower()
+        if any(token in lowered for token in FORBIDDEN_CHANNEL_TOKENS):
+            raise RuntimeError(f"{context}: label-derived channel name is forbidden: {name}")
+        _require_finite(value, f"{context}.channels.{name}")
+    labels = candidate.get("labels")
+    if not isinstance(labels, Mapping):
+        raise RuntimeError(f"{context}: labels must be an object")
+    relevance = bool(labels.get("relevance", False))
+    hard_negative = bool(labels.get("hard_negative", False))
+    if relevance and hard_negative:
+        raise RuntimeError(f"{context}: a positive candidate cannot be a hard negative")
+    role = clean_text(labels.get("evidence_role"))
+    expected_role = "positive" if relevance else ("hard_negative" if hard_negative else "negative")
+    if role != expected_role:
+        raise RuntimeError(f"{context}: evidence_role={role!r}, expected {expected_role!r}")
+    target_scope = clean_text(labels.get("target_scope"))
+    if target_scope and target_scope != "answer_session_bag":
+        raise RuntimeError(f"{context}: unsupported target_scope={target_scope!r}")
+
+
+def validate_sample(
+    sample: Mapping[str, Any],
+    *,
+    require_positive: bool,
+    allowed_splits: Sequence[str] = ("train", "holdout", "full_eval"),
+) -> None:
+    if clean_text(sample.get("schema_version")) != SCHEMA_VERSION:
+        raise RuntimeError(f"unsupported schema_version: {sample.get('schema_version')!r}")
+    qid = clean_text(sample.get("question_id"))
+    query = clean_text(sample.get("query_text"))
+    split = clean_text(sample.get("split"))
+    if not qid or not query:
+        raise RuntimeError("question_id and query_text are required")
+    if split not in set(allowed_splits):
+        raise RuntimeError(f"invalid split for {qid}: {split!r}")
+    supervision = sample.get("supervision")
+    if supervision is not None:
+        if not isinstance(supervision, Mapping):
+            raise RuntimeError(f"{qid}: supervision must be an object")
+        if clean_text(supervision.get("target_type")) not in {
+            "multi_instance_answer_session_bag",
+            "teacher_aligned_turn_bag",
+        }:
+            raise RuntimeError(f"{qid}: unsupported supervision target_type")
+        if clean_text(supervision.get("loss")) != "negative_log_positive_probability_mass":
+            raise RuntimeError(f"{qid}: unsupported supervision loss")
+        weight = _require_finite(supervision.get("training_weight", 1.0), f"{qid}.supervision.training_weight")
+        if weight <= 0.0 or weight > 1.0:
+            raise RuntimeError(f"{qid}: supervision training_weight must be in (0, 1]")
+    candidates = sample.get("candidates")
+    if not isinstance(candidates, list) or not candidates:
+        raise RuntimeError(f"{qid}: candidates must be a non-empty list")
+    seen: set[str] = set()
+    positive_count = 0
+    for index, candidate in enumerate(candidates):
+        if not isinstance(candidate, Mapping):
+            raise RuntimeError(f"{qid}: candidate {index} is not an object")
+        validate_candidate(candidate, context=f"{qid}.candidates[{index}]")
+        candidate_id = clean_text(candidate.get("candidate_id"))
+        if candidate_id in seen:
+            raise RuntimeError(f"{qid}: duplicate candidate_id: {candidate_id}")
+        seen.add(candidate_id)
+        positive_count += int(bool(candidate["labels"].get("relevance", False)))
+    if require_positive and positive_count == 0:
+        raise RuntimeError(f"{qid}: no positive candidate")
+
+
+def validate_split_isolation(train_rows: Sequence[Mapping[str, Any]], holdout_rows: Sequence[Mapping[str, Any]]) -> dict[str, int]:
+    train_qids = {clean_text(row.get("question_id")) for row in train_rows}
+    holdout_qids = {clean_text(row.get("question_id")) for row in holdout_rows}
+    train_queries = {clean_text(row.get("query_text")) for row in train_rows}
+    holdout_queries = {clean_text(row.get("query_text")) for row in holdout_rows}
+    qid_overlap = train_qids & holdout_qids
+    query_overlap = train_queries & holdout_queries
+    if qid_overlap:
+        raise RuntimeError(f"train/holdout qid overlap: {sorted(qid_overlap)[:10]}")
+    if query_overlap:
+        raise RuntimeError(f"train/holdout query overlap: {sorted(query_overlap)[:3]}")
+    return {
+        "train_qids": len(train_qids),
+        "holdout_qids": len(holdout_qids),
+        "qid_overlap": 0,
+        "query_text_overlap": 0,
+    }

benchmarks/longmemeval/src/tmcra_benchmark/legacy/tmcra_v3_slow_graph.py

@@ -0,0 +1,2138 @@
+#!/usr/bin/env python3
+"""Strict, append-only slow-memory graph controller."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import importlib
+import json
+import os
+import sqlite3
+import sys
+import threading
+import time
+import urllib.error
+import urllib.request
+import uuid
+from contextlib import contextmanager
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Iterable, Mapping, Protocol
+
+LEAF_VARIANT = "product_semantic_memory"
+CAPSULE_VARIANT = "slow_memory_capsule"
+PATCH_ACTIONS = frozenset(
+    {
+        "create",
+        "revise",
+        "challenge",
+        "resolve_challenge",
+        "retire",
+        "noop",
+    }
+)
+EDGE_TYPES = frozenset(
+    {
+        "supports",
+        "contradicts",
+        "derived_from",
+        "supersedes",
+        "challenges",
+        "invalidates",
+    }
+)
+SCHEMA_VERSION = "slow-graph-patch/v4"
+SLOW_EDGE_SOURCE = "slow_graph_control_plane"
+DEFAULT_CLAIM_LEASE_SECONDS = 15 * 60
+
+
+class SlowGraphError(RuntimeError):
+    pass
+
+
+class PatchValidationError(SlowGraphError):
+    pass
+
+
+class EvidencePolicyError(SlowGraphError):
+    pass
+
+
+class StaleRevisionError(SlowGraphError):
+    pass
+
+
+class AuditError(SlowGraphError):
+    pass
+
+
+class DeepSeekCallError(SlowGraphError):
+    def __init__(self, message: str, *, retryable: bool) -> None:
+        super().__init__(message)
+        self.retryable = retryable
+
+
+@dataclass(frozen=True)
+class JobClaim:
+    job_id: str
+    attempt_id: str
+    token: str
+    owner: str
+
+
+def _now() -> int:
+    return int(time.time())
+
+
+def _clean(value: Any) -> str:
+    return str(value).strip() if value is not None else ""
+
+
+def _json(value: Any) -> str:
+    return json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+
+
+def _digest(value: Any) -> str:
+    return hashlib.sha256(_json(value).encode("utf-8")).hexdigest()
+
+
+def _strict_json(value: str, *, label: str, expected: type) -> Any:
+    try:
+        result = json.loads(value)
+    except (TypeError, json.JSONDecodeError) as exc:
+        raise SlowGraphError(f"invalid {label} JSON") from exc
+    if not isinstance(result, expected):
+        raise SlowGraphError(f"{label} JSON must be {expected.__name__}")
+    return result
+
+
+def _required_text(value: Any, label: str) -> str:
+    text = _clean(value)
+    if not text:
+        raise PatchValidationError(f"{label} is required")
+    return text
+
+
+def load_graph_schema(repo: str | Path) -> tuple[type[Any], type[Any]]:
+    """Load the real graph record and edge types from an explicit TMCRA repo."""
+    root = Path(repo).resolve()
+    candidates = [root, root / "tmcra_code"]
+    package_roots = [
+        candidate
+        for candidate in candidates
+        if (candidate / "experiments" / "replacement" / "memory_graph.py").is_file()
+    ]
+    if len(package_roots) != 1:
+        raise SlowGraphError(
+            "--repo must resolve exactly one experiments/replacement/memory_graph.py "
+            f"at the repo root or repo/tmcra_code: {root}"
+        )
+    package_root = package_roots[0]
+    module_path = package_root / "experiments" / "replacement" / "memory_graph.py"
+    if str(package_root) not in sys.path:
+        sys.path.insert(0, str(package_root))
+    importlib.invalidate_caches()
+    try:
+        module = importlib.import_module("experiments.replacement.memory_graph")
+        return module.SessionMemoryRecordV2, module.SessionMemoryEdgeV2
+    except (ImportError, AttributeError) as exc:
+        raise SlowGraphError(
+            "unable to import real SessionMemoryRecordV2/SessionMemoryEdgeV2"
+        ) from exc
+
+
+class PatchManager(Protocol):
+    model_config: Mapping[str, Any]
+    prompt_hash: str
+    last_call_metadata: Mapping[str, Any]
+
+    def propose(
+        self, region: Mapping[str, Any], capsules: list[Mapping[str, Any]]
+    ) -> Mapping[str, Any]: ...
+
+
+@dataclass(frozen=True)
+class DeepSeekProConfig:
+    base_url: str
+    key_pool: tuple[str, ...]
+    max_tokens: int
+    model: str = "deepseek-v4-pro"
+
+    @classmethod
+    def from_env(cls) -> "DeepSeekProConfig":
+        base_url = _clean(os.getenv("TMCRA_DEEPSEEK_PRO_BASE_URL"))
+        keys = tuple(
+            item.strip()
+            for item in _clean(os.getenv("TMCRA_DEEPSEEK_PRO_KEY_POOL")).split(",")
+            if item.strip()
+        )
+        try:
+            max_tokens = int(_clean(os.getenv("TMCRA_DEEPSEEK_PRO_MAX_TOKENS")))
+        except ValueError as exc:
+            raise SlowGraphError(
+                "TMCRA_DEEPSEEK_PRO_MAX_TOKENS must be an integer"
+            ) from exc
+        if not base_url or not keys or max_tokens <= 0:
+            raise SlowGraphError(
+                "DeepSeek requires BASE_URL, KEY_POOL, and positive MAX_TOKENS"
+            )
+        return cls(base_url.rstrip("/"), keys, max_tokens)
+
+
+class DeepSeekProGraphPatchManager:
+    """The only production patch manager: no fallback and no hidden defaults."""
+
+    def __init__(self, config: DeepSeekProConfig) -> None:
+        if config.model != "deepseek-v4-pro":
+            raise SlowGraphError("DeepSeek model must be deepseek-v4-pro")
+        self.config = config
+        self._key_index = 0
+        self.model_config = {
+            "model": config.model,
+            "temperature": 0,
+            "thinking": "disabled",
+            "max_tokens": config.max_tokens,
+        }
+        self.prompt_hash = _digest(self._messages("<region>", []))
+        self.last_call_metadata: Mapping[str, Any] = {}
+
+    def _messages(self, region: Any, capsules: Any) -> list[dict[str, str]]:
+        schema = {
+            "operations": [
+                {
+                    "action": "create|revise|challenge|resolve_challenge|retire|noop",
+                    "capsule_id": "required for non-create operations; omit for create because controller derives it from region_key",
+                    "base_revision": "required for mutations of an existing capsule",
+                    "claims": [
+                        {
+                            "canonical_slot": "stable semantic slot shared by corrections of the same durable fact",
+                            "text": "string",
+                            "support": ["fast id"],
+                            "counterevidence": ["fast id"],
+                        }
+                    ],
+                }
+            ]
+        }
+        return [
+            {
+                "role": "system",
+                "content": (
+                    "You manage only the slow durable layer above immutable fast evidence leaves. "
+                    "Return exactly one JSON GraphPatch and no prose. Create or revise a capsule only for "
+                    "a durable preference, identity fact, routine, relationship, standing constraint, or stable "
+                    "long-running state. A single explicit durable assertion is sufficient; never require an "
+                    "arbitrary repetition count. Transient events, one-off tasks, quoted third-party claims, "
+                    "and evidence that does not establish durable memory must produce an empty operations list. "
+                    "Use challenge when new fast evidence conflicts but does not resolve the old claim; use "
+                    "resolve_challenge when the supplied evidence resolves an existing challenge; use retire only "
+                    "when evidence establishes that a capsule is no longer applicable. Topology merge and split "
+                    "are not part of this regional V1 controller. canonical_slot must remain identical across corrections "
+                    "of the same fact. Every claim canonical_slot must exactly copy canonical_slot_key from at "
+                    "least one fast evidence leaf cited by that claim. Do not invent evidence IDs, capsule IDs "
+                    "for create, confidence, source "
+                    "parents, claim_id, or fields outside the supplied schema. The controller assigns claim_id. "
+                    "Always emit support and counterevidence arrays, using [] for the empty side; the controller "
+                    "also accepts an omitted empty side as a transport-level normalization. Every non-noop claim "
+                    "must cite supplied fast leaf evidence. record_state and slow_graph_evidence_role are "
+                    "controller-owned. Never promote historical_noncurrent evidence as a current claim when "
+                    "current_authoritative evidence exists for the same canonical_slot; use noncurrent evidence "
+                    "only as history or counterevidence. Each region has exactly one controller-owned capsule: "
+                    "emit create only when "
+                    "capsules is empty; otherwise mutate the supplied capsule_id or emit an empty operations list. "
+                    "Return at most one operation. Empty operations is the canonical region-level noop."
+                ),
+            },
+            {
+                "role": "user",
+                "content": _json(
+                    {
+                        "schema_version": SCHEMA_VERSION,
+                        "schema": schema,
+                        "region": region,
+                        "capsules": capsules,
+                    }
+                ),
+            },
+        ]
+
+    def propose(
+        self, region: Mapping[str, Any], capsules: list[Mapping[str, Any]]
+    ) -> Mapping[str, Any]:
+        key_index = self._key_index % len(self.config.key_pool)
+        key = self.config.key_pool[key_index]
+        self._key_index += 1
+        body = {
+            "model": "deepseek-v4-pro",
+            "temperature": 0,
+            "max_tokens": self.config.max_tokens,
+            "thinking": {"type": "disabled"},
+            "enable_thinking": False,
+            "response_format": {"type": "json_object"},
+            "messages": self._messages(region, capsules),
+        }
+        request = urllib.request.Request(
+            self.config.base_url + "/chat/completions",
+            data=_json(body).encode("utf-8"),
+            headers={
+                "Authorization": "Bearer " + key,
+                "Content-Type": "application/json",
+            },
+            method="POST",
+        )
+        physical_call_id = "dsc_" + uuid.uuid4().hex
+        started_at = _now()
+        self.last_call_metadata = {
+            "request": body,
+            "key_index": key_index,
+            "started_at": started_at,
+            "physical_call_id": physical_call_id,
+            "status": "started",
+        }
+        try:
+            with urllib.request.urlopen(request, timeout=90) as response:  # nosec B310
+                status = response.getcode()
+                raw_text = response.read().decode("utf-8")
+        except urllib.error.HTTPError as exc:
+            try:
+                detail = exc.read().decode("utf-8", "replace")
+            except (AttributeError, OSError):
+                detail = ""
+            self.last_call_metadata = {
+                **self.last_call_metadata,
+                "status": "http_error",
+                "http_status": exc.code,
+                "error": detail,
+                "completed_at": _now(),
+            }
+            raise DeepSeekCallError(
+                f"DeepSeek HTTP {exc.code}: {detail}",
+                retryable=exc.code == 429 or exc.code >= 500,
+            ) from exc
+        except (urllib.error.URLError, TimeoutError, OSError) as exc:
+            self.last_call_metadata = {
+                **self.last_call_metadata,
+                "status": "request_error",
+                "error": f"{exc.__class__.__name__}: {exc}",
+                "completed_at": _now(),
+            }
+            raise DeepSeekCallError(
+                f"DeepSeek transport failure: {exc}", retryable=True
+            ) from exc
+        if status < 200 or status >= 300:
+            self.last_call_metadata = {
+                **self.last_call_metadata,
+                "status": "unexpected_http_status",
+                "http_status": status,
+                "raw_response": raw_text,
+                "completed_at": _now(),
+            }
+            raise DeepSeekCallError(
+                f"DeepSeek returned HTTP {status}", retryable=status >= 500
+            )
+        self.last_call_metadata = {
+            **self.last_call_metadata,
+            "status": "response_received",
+            "http_status": status,
+            "raw_response": raw_text,
+            "completed_at": _now(),
+        }
+        raw = _strict_json(raw_text, label="DeepSeek response", expected=dict)
+        choices = raw.get("choices")
+        usage = raw.get("usage")
+        if (
+            not isinstance(choices, list)
+            or len(choices) != 1
+            or not isinstance(usage, Mapping)
+        ):
+            raise DeepSeekCallError(
+                "DeepSeek response missing strict choices/usage", retryable=False
+            )
+        choice = choices[0]
+        if not isinstance(choice, Mapping) or not _clean(choice.get("finish_reason")):
+            raise DeepSeekCallError(
+                "DeepSeek response missing finish_reason", retryable=False
+            )
+        message = choice.get("message")
+        if not isinstance(message, Mapping) or not _clean(message.get("content")):
+            raise DeepSeekCallError(
+                "DeepSeek response missing choices[0].message.content", retryable=False
+            )
+        finish_reason = _clean(choice["finish_reason"])
+        self.last_call_metadata = {
+            **self.last_call_metadata,
+            "finish_reason": finish_reason,
+            "content": _clean(message["content"]),
+            "usage": dict(usage),
+        }
+        if finish_reason != "stop":
+            self.last_call_metadata = {
+                **self.last_call_metadata,
+                "status": "incomplete_response",
+            }
+            raise DeepSeekCallError(
+                f"DeepSeek response finish_reason must be stop, got {finish_reason!r}",
+                retryable=False,
+            )
+        self.last_call_metadata = {
+            **self.last_call_metadata,
+            "request": body,
+            "response_id": _required_text(raw.get("id"), "DeepSeek response id"),
+            "finish_reason": finish_reason,
+            "choices": choices,
+            "content": _clean(message["content"]),
+            "usage": dict(usage),
+            "http_status": status,
+            "physical_call_id": physical_call_id,
+            "status": "completed",
+            "completed_at": _now(),
+        }
+        patch = _strict_json(
+            _clean(message["content"]), label="DeepSeek content", expected=dict
+        )
+        transport_normalizations = []
+        for operation in patch.get("operations", []):
+            if (
+                isinstance(operation, Mapping)
+                and operation.get("action") == "create"
+                and "capsule_id" in operation
+                and operation.get("capsule_id") is None
+            ):
+                transport_normalizations.append(
+                    {
+                        "code": "create_null_capsule_id_ignored",
+                        "field": "capsule_id",
+                    }
+                )
+        if transport_normalizations:
+            self.last_call_metadata = {
+                **self.last_call_metadata,
+                "transport_normalizations": transport_normalizations,
+            }
+        validate_patch(patch)
+        return patch
+
+
+def _ids(value: Any, label: str) -> list[str]:
+    if not isinstance(value, list) or not value:
+        raise PatchValidationError(f"{label} must be a non-empty list")
+    result = [_required_text(item, label) for item in value]
+    if len(set(result)) != len(result):
+        raise PatchValidationError(f"{label} contains duplicates")
+    return result
+
+
+def _validate_source_parents(value: Any) -> list[dict[str, Any]]:
+    if not isinstance(value, list) or not value:
+        raise PatchValidationError("source_parents must be a non-empty list")
+    expected = {
+        "session_index",
+        "parent_chunk_index",
+        "message_index",
+        "source_record_id",
+        "event_id",
+        "evidence_char_start",
+        "evidence_char_end",
+    }
+    result: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    for parent in value:
+        if not isinstance(parent, Mapping) or set(parent) != expected:
+            raise PatchValidationError("source_parent has an invalid schema")
+        normalized = dict(parent)
+        for key in ("session_index", "parent_chunk_index", "message_index"):
+            if not isinstance(normalized[key], int) or normalized[key] < 0:
+                raise PatchValidationError(f"source_parent {key} must be non-negative integer")
+        if normalized["parent_chunk_index"] != normalized["message_index"]:
+            raise PatchValidationError("source_parent chunk/message coordinates disagree")
+        if (
+            not isinstance(normalized["evidence_char_start"], int)
+            or not isinstance(normalized["evidence_char_end"], int)
+            or normalized["evidence_char_start"] < 0
+            or normalized["evidence_char_end"] <= normalized["evidence_char_start"]
+        ):
+            raise PatchValidationError("source_parent evidence character span is invalid")
+        _required_text(normalized["source_record_id"], "source_record_id")
+        _required_text(normalized["event_id"], "event_id")
+        digest = _json(normalized)
+        if digest not in seen:
+            seen.add(digest)
+            result.append(normalized)
+    return result
+
+
+def _validate_claims(
+    value: Any, *, stored: bool = False
+) -> list[dict[str, Any]]:
+    if not isinstance(value, list) or not value:
+        raise PatchValidationError("claims must be a non-empty list")
+    claims: list[dict[str, Any]] = []
+    seen = set()
+    for claim in value:
+        expected = {"canonical_slot", "text", "support", "counterevidence"}
+        if stored:
+            expected.add("claim_id")
+            expected.add("source_parents")
+        if not isinstance(claim, Mapping):
+            raise PatchValidationError("each claim must be an object")
+        if stored:
+            valid_shape = set(claim) == expected
+        else:
+            valid_shape = (
+                {"canonical_slot", "text"}.issubset(claim)
+                and set(claim).issubset(expected)
+            )
+        if not valid_shape:
+            raise PatchValidationError(
+                "each claim has an invalid schema"
+            )
+        support = claim.get("support", [])
+        counter = claim.get("counterevidence", [])
+        if not isinstance(support, list) or not isinstance(counter, list):
+            raise PatchValidationError("claim evidence must be lists")
+        normalized_support = _ids(support, "claim support") if support else []
+        normalized_counter = (
+            _ids(counter, "claim counterevidence") if counter else []
+        )
+        if not normalized_support and not normalized_counter:
+            raise PatchValidationError("each claim needs support or counterevidence")
+        canonical_slot = _required_text(
+            claim.get("canonical_slot"), "canonical_slot"
+        )
+        claim_text = _required_text(claim.get("text"), "claim text")
+        claim_id = (
+            _required_text(claim.get("claim_id"), "claim_id")
+            if stored
+            else "clm_"
+            + _digest(
+                {
+                    "canonical_slot": canonical_slot,
+                    "text": claim_text,
+                    "support": normalized_support,
+                    "counterevidence": normalized_counter,
+                }
+            )[:24]
+        )
+        if claim_id in seen:
+            raise PatchValidationError("claim_id must be unique")
+        seen.add(claim_id)
+        claims.append(
+            {
+                "claim_id": claim_id,
+                "canonical_slot": canonical_slot,
+                "text": claim_text,
+                "support": normalized_support,
+                "counterevidence": normalized_counter,
+                **(
+                    {
+                        "source_parents": _validate_source_parents(
+                            claim.get("source_parents")
+                        )
+                    }
+                    if stored
+                    else {}
+                ),
+            }
+        )
+    return claims
+
+
+def validate_patch(patch: Mapping[str, Any]) -> None:
+    if (
+        not isinstance(patch, Mapping)
+        or set(patch) != {"operations"}
+        or not isinstance(patch["operations"], list)
+    ):
+        raise PatchValidationError("GraphPatch must contain exactly an operations list")
+    if len(patch["operations"]) > 1:
+        raise PatchValidationError("GraphPatch may contain at most one region operation")
+    for operation in patch["operations"]:
+        if not isinstance(operation, Mapping):
+            raise PatchValidationError("GraphPatch operation must be an object")
+        action = _required_text(operation.get("action"), "action")
+        if action not in PATCH_ACTIONS:
+            raise PatchValidationError("unknown GraphPatch action")
+        if "confidence" in operation:
+            raise PatchValidationError(
+                "model confidence is not an authoritative graph field"
+            )
+        allowed = {"action", "summary", "claims"}
+        if action == "create":
+            if "capsule_key" in operation:
+                raise PatchValidationError(
+                    "create capsule identity is controller-derived from region_key"
+                )
+            if "capsule_id" in operation:
+                if operation.get("capsule_id") is not None:
+                    raise PatchValidationError(
+                        "create capsule identity is controller-derived from region_key"
+                    )
+                allowed.add("capsule_id")
+        elif action == "noop":
+            allowed.add("capsule_id")
+            if "capsule_id" in operation:
+                _required_text(operation.get("capsule_id"), "capsule_id")
+        else:
+            allowed.update({"capsule_id", "base_revision"})
+            _required_text(operation.get("capsule_id"), "capsule_id")
+            if (
+                not isinstance(operation.get("base_revision"), int)
+                or operation["base_revision"] < 1
+            ):
+                raise PatchValidationError("base_revision must be a positive integer")
+        if set(operation) - allowed:
+            raise PatchValidationError("unexpected GraphPatch operation fields")
+        if action != "noop":
+            _validate_claims(operation.get("claims"))
+
+
+class SlowGraphStore:
+    def __init__(
+        self,
+        database: str | Path,
+        *,
+        schema: tuple[type[Any], type[Any]],
+        claim_lease_seconds: int = DEFAULT_CLAIM_LEASE_SECONDS,
+    ) -> None:
+        if claim_lease_seconds <= 0:
+            raise SlowGraphError("claim lease duration must be positive")
+        self.database = Path(database)
+        self.record_type, self.edge_type = schema
+        self.claim_lease_seconds = claim_lease_seconds
+        self.database.parent.mkdir(parents=True, exist_ok=True)
+        self._init_schema()
+
+    def connect(self) -> sqlite3.Connection:
+        con = sqlite3.connect(self.database)
+        con.row_factory = sqlite3.Row
+        con.execute("PRAGMA foreign_keys=ON")
+        return con
+
+    @contextmanager
+    def connection(self):
+        con = self.connect()
+        try:
+            yield con
+            con.commit()
+        except Exception:
+            con.rollback()
+            raise
+        finally:
+            con.close()
+
+    def _init_schema(self) -> None:
+        with self.connection() as con:
+            con.executescript("""
+            CREATE TABLE IF NOT EXISTS slow_graph_jobs (
+              job_id TEXT PRIMARY KEY, idempotency_key TEXT NOT NULL UNIQUE, scope_id TEXT NOT NULL, region_key TEXT NOT NULL,
+              evidence_ids_json TEXT NOT NULL, metadata_json TEXT NOT NULL, status TEXT NOT NULL CHECK(status IN ('pending','retryable','failed','completed')),
+              attempts INTEGER NOT NULL, last_error TEXT NOT NULL, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL,
+              claim_token TEXT, claim_owner TEXT, lease_expires_at INTEGER);
+            CREATE TABLE IF NOT EXISTS slow_graph_attempts (
+              attempt_id TEXT PRIMARY KEY, job_id TEXT NOT NULL, scope_id TEXT NOT NULL, status TEXT NOT NULL,
+              call_metadata_json TEXT NOT NULL, error TEXT NOT NULL, created_at INTEGER NOT NULL, completed_at INTEGER,
+              claim_token TEXT, claim_owner TEXT);
+            CREATE TABLE IF NOT EXISTS slow_graph_batches (
+              batch_id TEXT PRIMARY KEY, batch_key TEXT NOT NULL UNIQUE, scope_id TEXT NOT NULL,
+              evidence_snapshot_hash TEXT NOT NULL, job_ids_json TEXT NOT NULL, manager_metadata_json TEXT NOT NULL,
+              created_at INTEGER NOT NULL);
+            CREATE TABLE IF NOT EXISTS slow_graph_patches (
+              patch_id TEXT PRIMARY KEY, job_id TEXT NOT NULL, scope_id TEXT NOT NULL, region_key TEXT NOT NULL, manager_model TEXT NOT NULL,
+              patch_json TEXT NOT NULL, call_metadata_json TEXT NOT NULL, applied_at INTEGER NOT NULL);
+            CREATE TABLE IF NOT EXISTS slow_graph_patch_operations (
+              operation_id TEXT PRIMARY KEY, patch_id TEXT NOT NULL, ordinal INTEGER NOT NULL, capsule_id TEXT NOT NULL, action TEXT NOT NULL,
+              base_revision INTEGER, result_revision INTEGER, operation_json TEXT NOT NULL, created_at INTEGER NOT NULL);
+            CREATE TABLE IF NOT EXISTS slow_graph_provenance (
+              provenance_id TEXT PRIMARY KEY, patch_id TEXT NOT NULL, scope_id TEXT NOT NULL, capsule_id TEXT NOT NULL, revision INTEGER NOT NULL,
+              evidence_memory_id TEXT NOT NULL, claim_id TEXT NOT NULL, polarity TEXT NOT NULL, source_parent_json TEXT NOT NULL, created_at INTEGER NOT NULL);
+            CREATE INDEX IF NOT EXISTS idx_slow_graph_jobs_pending ON slow_graph_jobs(status, created_at);
+            CREATE INDEX IF NOT EXISTS idx_slow_graph_provenance_capsule ON slow_graph_provenance(scope_id, capsule_id, revision);
+            CREATE TABLE IF NOT EXISTS memory_edges (
+              scope_id TEXT NOT NULL, edge_id TEXT NOT NULL, source_memory_id TEXT NOT NULL, target_memory_id TEXT NOT NULL, edge_type TEXT NOT NULL,
+              score REAL NOT NULL, model_score REAL NOT NULL, evidence_turn INTEGER NOT NULL, evidence TEXT NOT NULL, metadata_json TEXT NOT NULL,
+              PRIMARY KEY(scope_id, edge_id));
+            CREATE TABLE IF NOT EXISTS slot_heads (
+              scope_id TEXT NOT NULL, slot_key TEXT NOT NULL, memory_id TEXT NOT NULL,
+              PRIMARY KEY(scope_id,slot_key));
+            CREATE TABLE IF NOT EXISTS slot_history (
+              scope_id TEXT NOT NULL, slot_key TEXT NOT NULL, ordinal INTEGER NOT NULL, memory_id TEXT NOT NULL,
+              PRIMARY KEY(scope_id,slot_key,ordinal));
+            """)
+            self._add_column_if_missing(con, "slow_graph_jobs", "claim_token TEXT")
+            self._add_column_if_missing(con, "slow_graph_jobs", "claim_owner TEXT")
+            self._add_column_if_missing(
+                con, "slow_graph_jobs", "lease_expires_at INTEGER"
+            )
+            self._add_column_if_missing(
+                con, "slow_graph_attempts", "claim_token TEXT"
+            )
+            self._add_column_if_missing(
+                con, "slow_graph_attempts", "claim_owner TEXT"
+            )
+            con.execute(
+                "CREATE INDEX IF NOT EXISTS idx_slow_graph_jobs_claimable "
+                "ON slow_graph_jobs(status, claim_token, created_at)"
+            )
+
+    @staticmethod
+    def _add_column_if_missing(
+        con: sqlite3.Connection, table: str, declaration: str
+    ) -> None:
+        column = declaration.split()[0]
+        columns = {
+            str(row["name"])
+            for row in con.execute("PRAGMA table_info(" + table + ")")
+        }
+        if column not in columns:
+            con.execute("ALTER TABLE " + table + " ADD COLUMN " + declaration)
+
+    def _records_table_exists(self, con: sqlite3.Connection) -> None:
+        if (
+            con.execute(
+                "SELECT 1 FROM sqlite_master WHERE type='table' AND name='records'"
+            ).fetchone()
+            is None
+        ):
+            raise SlowGraphError("real graph records table is missing")
+
+    def _metadata(self, row: sqlite3.Row, label: str) -> dict[str, Any]:
+        return _strict_json(row["metadata_json"], label=label, expected=dict)
+
+    def fast_regions(self, scope_id: str) -> dict[str, list[dict[str, Any]]]:
+        regions: dict[str, list[dict[str, Any]]] = {}
+        with self.connection() as con:
+            self._records_table_exists(con)
+            rows = con.execute(
+                "SELECT memory_id,value,relation,turn_index,metadata_json FROM records WHERE scope_id=?",
+                (scope_id,),
+            ).fetchall()
+        for row in rows:
+            metadata = self._metadata(row, "fast evidence metadata")
+            if (
+                metadata.get("content_variant") != LEAF_VARIANT
+                or metadata.get("memory_layer") != "fast"
+                or metadata.get("node_kind") != "atomic_user_assertion"
+                or metadata.get("atomic_evidence_leaf") is not True
+                or metadata.get("authority") != "user_assertion"
+            ):
+                continue
+            key = _clean(
+                metadata.get("graph_entity_key")
+                or metadata.get("entity_key")
+                or metadata.get("domain")
+            )
+            if not key:
+                raise SlowGraphError("fast evidence is missing region key")
+            regions.setdefault(key, []).append(
+                {
+                    "memory_id": row["memory_id"],
+                    "value": row["value"],
+                    "relation": row["relation"],
+                    "turn_index": row["turn_index"],
+                    "metadata": metadata,
+                }
+            )
+        return regions
+
+    def _capsules(
+        self, con: sqlite3.Connection, scope_id: str, region_key: str
+    ) -> list[dict[str, Any]]:
+        rows = con.execute(
+            "SELECT memory_id,state,value,metadata_json FROM records WHERE scope_id=?",
+            (scope_id,),
+        ).fetchall()
+        revisions: list[dict[str, Any]] = []
+        for row in rows:
+            meta = self._metadata(row, "capsule metadata")
+            if (
+                meta.get("content_variant") == CAPSULE_VARIANT
+                and meta.get("region_key") == region_key
+            ):
+                revisions.append(
+                    {
+                        "memory_id": row["memory_id"],
+                        "record_state": row["state"],
+                        "value": row["value"],
+                        **meta,
+                    }
+                )
+        if not revisions:
+            return []
+        latest_revision = max(int(item["revision"]) for item in revisions)
+        latest = [
+            item for item in revisions if int(item["revision"]) == latest_revision
+        ]
+        if len(latest) != 1:
+            raise AuditError("region capsule lacks one latest revision")
+        return latest
+
+    def _job_metadata(
+        self,
+        con: sqlite3.Connection,
+        scope_id: str,
+        region_key: str,
+        evidence_ids: list[str],
+        manager: PatchManager | None,
+    ) -> dict[str, Any]:
+        evidence = self._evidence(con, scope_id, evidence_ids)
+        normalized_region = _required_text(region_key, "region key")
+        foreign_evidence = [
+            item["memory_id"]
+            for item in evidence
+            if _clean(item["metadata"].get("graph_entity_key"))
+            != normalized_region
+        ]
+        if foreign_evidence:
+            raise EvidencePolicyError(
+                "fast evidence graph_entity_key does not match job region: "
+                + ",".join(foreign_evidence)
+            )
+        model = dict(manager.model_config) if manager else {"model": "unbound"}
+        prompt_hash = manager.prompt_hash if manager else "unbound"
+        capsules = self._capsules(con, scope_id, region_key)
+        return {
+            "schema_version": SCHEMA_VERSION,
+            "schema_hash": _digest(
+                {"version": SCHEMA_VERSION, "actions": sorted(PATCH_ACTIONS)}
+            ),
+            "prompt_hash": prompt_hash,
+            "model_config": model,
+            "evidence_content_hash": _digest(evidence),
+            "capsule_revision_hash": _digest(capsules),
+        }
+
+    def _enqueue_in_connection(
+        self,
+        con: sqlite3.Connection,
+        scope_id: str,
+        region_key: str,
+        evidence_ids: list[str],
+        *,
+        manager: PatchManager | None = None,
+    ) -> str:
+        now = _now()
+        metadata = self._job_metadata(
+            con, scope_id, region_key, evidence_ids, manager
+        )
+        idem = _digest(
+            {
+                "scope_id": scope_id,
+                "region_key": region_key,
+                "evidence_ids": evidence_ids,
+                **{
+                    key: value
+                    for key, value in metadata.items()
+                    if key != "capsule_revision_hash"
+                },
+            }
+        )
+        job_id = "sgj_" + uuid.uuid4().hex
+        con.execute(
+            "INSERT OR IGNORE INTO slow_graph_jobs("
+            "job_id,idempotency_key,scope_id,region_key,evidence_ids_json,metadata_json,"
+            "status,attempts,last_error,created_at,updated_at) VALUES(?,?,?,?,?,?,?,?,?,?,?)",
+            (
+                job_id,
+                idem,
+                scope_id,
+                region_key,
+                _json(evidence_ids),
+                _json(metadata),
+                "pending",
+                0,
+                "",
+                now,
+                now,
+            ),
+        )
+        row = con.execute(
+            "SELECT job_id FROM slow_graph_jobs WHERE idempotency_key=?", (idem,)
+        ).fetchone()
+        return str(row["job_id"])
+
+    def enqueue(
+        self,
+        scope_id: str,
+        region_key: str,
+        evidence_ids: Iterable[str],
+        *,
+        manager: PatchManager | None = None,
+    ) -> str:
+        normalized_ids = sorted(
+            set(_required_text(item, "evidence id") for item in evidence_ids)
+        )
+        if not normalized_ids:
+            raise SlowGraphError("cannot enqueue without fast evidence")
+        with self.connection() as con:
+            self._records_table_exists(con)
+            return self._enqueue_in_connection(
+                con,
+                scope_id,
+                region_key,
+                normalized_ids,
+                manager=manager,
+            )
+
+    def enqueue_regions(
+        self, scope_id: str, *, manager: PatchManager | None = None
+    ) -> list[str]:
+        regions = self.fast_regions(scope_id)
+        manager_metadata = {
+            "schema_version": SCHEMA_VERSION,
+            "prompt_hash": manager.prompt_hash if manager else "unbound",
+            "model_config": dict(manager.model_config)
+            if manager
+            else {"model": "unbound"},
+        }
+        snapshot = {
+            key: [
+                {
+                    "memory_id": item["memory_id"],
+                    "value": item["value"],
+                    "metadata": item["metadata"],
+                }
+                for item in values
+            ]
+            for key, values in sorted(regions.items())
+        }
+        evidence_snapshot_hash = _digest(snapshot)
+        batch_key = _digest(
+            {
+                "scope_id": scope_id,
+                "evidence_snapshot_hash": evidence_snapshot_hash,
+                **manager_metadata,
+            }
+        )
+        with self.connection() as con:
+            self._records_table_exists(con)
+            existing = con.execute(
+                "SELECT job_ids_json FROM slow_graph_batches WHERE batch_key=?",
+                (batch_key,),
+            ).fetchone()
+            if existing is not None:
+                return [
+                    str(item)
+                    for item in _strict_json(
+                        existing["job_ids_json"], label="batch job IDs", expected=list
+                    )
+                ]
+            job_ids = [
+                self._enqueue_in_connection(
+                    con,
+                    scope_id,
+                    key,
+                    sorted(str(item["memory_id"]) for item in values),
+                    manager=manager,
+                )
+                for key, values in sorted(regions.items())
+            ]
+            con.execute(
+                "INSERT INTO slow_graph_batches VALUES(?,?,?,?,?,?,?)",
+                (
+                    "sgb_" + uuid.uuid4().hex,
+                    batch_key,
+                    scope_id,
+                    evidence_snapshot_hash,
+                    _json(job_ids),
+                    _json(manager_metadata),
+                    _now(),
+                ),
+            )
+            return job_ids
+
+    def _job(self, job_id: str) -> sqlite3.Row:
+        with self.connection() as con:
+            row = con.execute(
+                "SELECT * FROM slow_graph_jobs WHERE job_id=?", (job_id,)
+            ).fetchone()
+        if row is None:
+            raise SlowGraphError("unknown slow graph job: " + job_id)
+        self._metadata(row, "job")
+        return row
+
+    def _evidence(
+        self, con: sqlite3.Connection, scope_id: str, ids: Iterable[str]
+    ) -> list[dict[str, Any]]:
+        result = []
+        for evidence_id in sorted(set(ids)):
+            row = con.execute(
+                "SELECT memory_id,value,turn_index,state,metadata_json FROM records WHERE scope_id=? AND memory_id=?",
+                (scope_id, evidence_id),
+            ).fetchone()
+            if row is None:
+                raise EvidencePolicyError("unknown evidence: " + evidence_id)
+            meta = self._metadata(row, "fast evidence")
+            if (
+                meta.get("content_variant") != LEAF_VARIANT
+                or meta.get("memory_layer") != "fast"
+                or meta.get("node_kind") != "atomic_user_assertion"
+                or meta.get("atomic_evidence_leaf") is not True
+                or meta.get("authority") != "user_assertion"
+            ):
+                raise EvidencePolicyError(
+                    "only fast product_semantic_memory leaves may support capsules: "
+                    + evidence_id
+                )
+            parent = {
+                key: meta.get(key)
+                for key in (
+                    "session_index",
+                    "message_index",
+                    "source_record_id",
+                    "event_id",
+                    "evidence_char_start",
+                    "evidence_char_end",
+                )
+            }
+            if any(value is None or _clean(value) == "" for value in parent.values()):
+                raise EvidencePolicyError(
+                    "fast evidence lacks structured source_parent fields: "
+                    + evidence_id
+                )
+            parent["parent_chunk_index"] = parent["message_index"]
+            record_state = _clean(row["state"])
+            evidence_role = (
+                "current_authoritative"
+                if record_state in {"active", "parallel_active", "promoted"}
+                else "historical_noncurrent"
+            )
+            result.append(
+                {
+                    "memory_id": row["memory_id"],
+                    "value": row["value"],
+                    "turn_index": row["turn_index"],
+                    "record_state": record_state,
+                    "slow_graph_evidence_role": evidence_role,
+                    "metadata": {
+                        **meta,
+                        "record_state": record_state,
+                        "slow_graph_evidence_role": evidence_role,
+                    },
+                    "source_parent": parent,
+                }
+            )
+        return result
+
+    def _head(
+        self, con: sqlite3.Connection, scope_id: str, capsule_id: str
+    ) -> tuple[int, str] | None:
+        rows = con.execute(
+            "SELECT memory_id,metadata_json FROM records WHERE scope_id=?", (scope_id,)
+        ).fetchall()
+        candidates = []
+        for row in rows:
+            meta = self._metadata(row, "capsule metadata")
+            if (
+                meta.get("content_variant") == CAPSULE_VARIANT
+                and meta.get("capsule_id") == capsule_id
+            ):
+                candidates.append((int(meta["revision"]), str(row["memory_id"])))
+        return max(candidates) if candidates else None
+
+    def _capsule_id(self, scope_id: str, region_key: str) -> str:
+        return (
+            "cap_"
+            + _digest(
+                {
+                    "scope_id": scope_id,
+                    "region_key": _required_text(region_key, "region_key"),
+                }
+            )[:24]
+        )
+
+    def _mark_superseded(
+        self, con: sqlite3.Connection, scope_id: str, memory_id: str
+    ) -> None:
+        row = con.execute(
+            "SELECT slot_key,metadata_json FROM records WHERE scope_id=? AND memory_id=?",
+            (scope_id, memory_id),
+        ).fetchone()
+        if row is None:
+            raise SlowGraphError("cannot supersede missing record: " + memory_id)
+        metadata = self._metadata(row, "superseded record")
+        if metadata.get("content_variant") == CAPSULE_VARIANT:
+            metadata["status"] = "superseded"
+        con.execute(
+            "UPDATE records SET state='superseded',metadata_json=? WHERE scope_id=? AND memory_id=?",
+            (_json(metadata), scope_id, memory_id),
+        )
+        con.execute(
+            "DELETE FROM slot_heads WHERE scope_id=? AND slot_key=? AND memory_id=?",
+            (scope_id, row["slot_key"], memory_id),
+        )
+
+    def _write_edge(
+        self,
+        con: sqlite3.Connection,
+        *,
+        scope_id: str,
+        source: str,
+        target: str,
+        edge_type: str,
+        patch_id: str,
+        evidence_refs: list[str],
+        action: str,
+        turn: int,
+    ) -> None:
+        if edge_type not in EDGE_TYPES or source == target:
+            raise AuditError("invalid graph edge")
+        edge = self.edge_type(
+            edge_id="sge_"
+            + _digest(
+                {
+                    "patch": patch_id,
+                    "source": source,
+                    "target": target,
+                    "type": edge_type,
+                }
+            )[:24],
+            source_memory_id=source,
+            target_memory_id=target,
+            edge_type=edge_type,
+            score=0.0,
+            model_score=0.0,
+            evidence_turn=turn,
+            evidence="slow graph patch",
+            metadata={
+                "edge_source": SLOW_EDGE_SOURCE,
+                "patch_id": patch_id,
+                "evidence_refs": evidence_refs,
+                "action": action,
+            },
+        )
+        con.execute(
+            "INSERT INTO memory_edges VALUES(?,?,?,?,?,?,?,?,?,?)",
+            (
+                scope_id,
+                edge.edge_id,
+                edge.source_memory_id,
+                edge.target_memory_id,
+                edge.edge_type,
+                edge.score,
+                edge.model_score,
+                edge.evidence_turn,
+                edge.evidence,
+                _json(edge.metadata),
+            ),
+        )
+
+    def _insert_revision(
+        self,
+        con: sqlite3.Connection,
+        *,
+        job: sqlite3.Row,
+        patch_id: str,
+        operation: Mapping[str, Any],
+        capsule_id: str,
+        revision: int,
+        action: str,
+        old_memory_id: str | None = None,
+    ) -> str:
+        claims = _validate_claims(operation["claims"])
+        evidence_ids = sorted(
+            {
+                item
+                for claim in claims
+                for key in ("support", "counterevidence")
+                for item in claim[key]
+            }
+        )
+        allowed_evidence = set(
+            _strict_json(
+                job["evidence_ids_json"], label="job evidence IDs", expected=list
+            )
+        )
+        if not set(evidence_ids).issubset(allowed_evidence):
+            raise EvidencePolicyError(
+                "GraphPatch cited fast evidence that was not supplied to this job"
+        )
+        evidence = self._evidence(con, job["scope_id"], evidence_ids)
+        evidence_by_id = {item["memory_id"]: item for item in evidence}
+        controller_normalizations: list[dict[str, Any]] = []
+        for index, claim in enumerate(claims):
+            cited_slots = {
+                _clean(evidence_by_id[evidence_id]["metadata"].get("canonical_slot_key"))
+                for evidence_id in [*claim["support"], *claim["counterevidence"]]
+            }
+            cited_slots.discard("")
+            if claim["canonical_slot"] not in cited_slots:
+                if len(cited_slots) != 1:
+                    raise EvidencePolicyError(
+                        "claim canonical_slot is ambiguous across cited fast leaf slots"
+                    )
+                authoritative_slot = next(iter(cited_slots))
+                original_slot = claim["canonical_slot"]
+                normalized_claim = {
+                    **claim,
+                    "canonical_slot": authoritative_slot,
+                }
+                normalized_claim["claim_id"] = "clm_" + _digest(
+                    {
+                        "canonical_slot": authoritative_slot,
+                        "text": normalized_claim["text"],
+                        "support": normalized_claim["support"],
+                        "counterevidence": normalized_claim["counterevidence"],
+                    }
+                )[:24]
+                claims[index] = normalized_claim
+                controller_normalizations.append(
+                    {
+                        "code": "canonical_slot_bound_to_unique_cited_leaf",
+                        "claim_index": index,
+                        "model_value": original_slot,
+                        "authoritative_value": authoritative_slot,
+                    }
+                )
+        claim_ids = [claim["claim_id"] for claim in claims]
+        if len(set(claim_ids)) != len(claim_ids):
+            raise EvidencePolicyError(
+                "canonical slot binding produced duplicate claims"
+            )
+        status = {
+            "challenge": "challenged",
+            "retire": "retired",
+            "resolve_challenge": "active",
+        }.get(action, "active")
+        stored_claims: list[dict[str, Any]] = []
+        for claim in claims:
+            claim_parents = [
+                evidence_by_id[evidence_id]["source_parent"]
+                for evidence_id in [*claim["support"], *claim["counterevidence"]]
+            ]
+            stored_claims.append(
+                {**claim, "source_parents": _validate_source_parents(claim_parents)}
+            )
+        source_parents = _validate_source_parents(
+            [parent for claim in stored_claims for parent in claim["source_parents"]]
+        )
+        record_id = f"slow.{capsule_id}.r{revision}"
+        metadata = {
+            "memory_layer": "slow",
+            "content_variant": CAPSULE_VARIANT,
+            "capsule_id": capsule_id,
+            "revision": revision,
+            "status": status,
+            "claims": stored_claims,
+            "source_parents": source_parents,
+            "canonical_slots": sorted(
+                {claim["canonical_slot"] for claim in stored_claims}
+            ),
+            "patch_id": patch_id,
+            "region_key": job["region_key"],
+            "action": action,
+            "controller_normalizations": controller_normalizations,
+        }
+        record_state = "active" if status in {"active", "challenged"} else status
+        record = self.record_type(
+            memory_id=record_id,
+            category=CAPSULE_VARIANT,
+            slot_key="slow." + capsule_id,
+            value=_clean(operation.get("summary")) or _json(claims),
+            relation="capsule_revision",
+            anchor_concepts=[job["region_key"]],
+            evidence_anchors=evidence_ids,
+            salience=0.7,
+            confidence=0.0,
+            source_kind="slow_graph",
+            turn_index=max(item["turn_index"] for item in evidence),
+            state=record_state,
+            supersedes=[old_memory_id] if old_memory_id else [],
+            metadata=metadata,
+        )
+        payload = record.to_dict()
+        con.execute(
+            "INSERT INTO records(scope_id,memory_id,category,slot_key,value,relation,anchor_concepts_json,evidence_anchors_json,salience,confidence,source_kind,turn_index,state,supersedes_json,metadata_json) VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)",
+            (
+                job["scope_id"],
+                payload["memory_id"],
+                payload["category"],
+                payload["slot_key"],
+                payload["value"],
+                payload["relation"],
+                _json(payload["anchor_concepts"]),
+                _json(payload["evidence_anchors"]),
+                payload["salience"],
+                payload["confidence"],
+                payload["source_kind"],
+                payload["turn_index"],
+                payload["state"],
+                _json(payload["supersedes"]),
+                _json(payload["metadata"]),
+            ),
+        )
+        slot_key = payload["slot_key"]
+        ordinal = int(
+            con.execute(
+                "SELECT COALESCE(MAX(ordinal),-1)+1 FROM slot_history WHERE scope_id=? AND slot_key=?",
+                (job["scope_id"], slot_key),
+            ).fetchone()[0]
+        )
+        con.execute(
+            "INSERT INTO slot_history(scope_id,slot_key,ordinal,memory_id) VALUES(?,?,?,?)",
+            (job["scope_id"], slot_key, ordinal, record_id),
+        )
+        if record_state == "active":
+            con.execute(
+                "INSERT INTO slot_heads(scope_id,slot_key,memory_id) VALUES(?,?,?) "
+                "ON CONFLICT(scope_id,slot_key) DO UPDATE SET memory_id=excluded.memory_id",
+                (job["scope_id"], slot_key, record_id),
+            )
+        else:
+            con.execute(
+                "DELETE FROM slot_heads WHERE scope_id=? AND slot_key=?",
+                (job["scope_id"], slot_key),
+            )
+        for claim in stored_claims:
+            for polarity, edge_kind in (
+                ("support", "supports"),
+                ("counterevidence", "contradicts"),
+            ):
+                for evidence_id in claim[polarity]:
+                    item = evidence_by_id[evidence_id]
+                    con.execute(
+                        "INSERT INTO slow_graph_provenance VALUES(?,?,?,?,?,?,?,?,?,?)",
+                        (
+                            "sgv_" + uuid.uuid4().hex,
+                            patch_id,
+                            job["scope_id"],
+                            capsule_id,
+                            revision,
+                            evidence_id,
+                            claim["claim_id"],
+                            polarity,
+                            _json(item["source_parent"]),
+                            _now(),
+                        ),
+                    )
+                    self._write_edge(
+                        con,
+                        scope_id=job["scope_id"],
+                        source=evidence_id,
+                        target=record_id,
+                        edge_type=edge_kind,
+                        patch_id=patch_id,
+                        evidence_refs=[evidence_id],
+                        action=action,
+                        turn=item["turn_index"],
+                    )
+        if old_memory_id:
+            self._mark_superseded(con, job["scope_id"], old_memory_id)
+            self._write_edge(
+                con,
+                scope_id=job["scope_id"],
+                source=old_memory_id,
+                target=record_id,
+                edge_type="supersedes",
+                patch_id=patch_id,
+                evidence_refs=evidence_ids,
+                action=action,
+                turn=payload["turn_index"],
+            )
+        return record_id
+
+    def _audit_transaction(self, con: sqlite3.Connection, scope_id: str) -> None:
+        """Validate slow-layer invariants against the uncommitted write transaction."""
+        rows = con.execute(
+            "SELECT memory_id,state,metadata_json FROM records WHERE scope_id=?",
+            (scope_id,),
+        ).fetchall()
+        capsules: dict[str, list[tuple[str, str, int, str]]] = {}
+        known_records = {str(row["memory_id"]) for row in rows}
+        for row in rows:
+            meta = self._metadata(row, "transaction record")
+            if meta.get("content_variant") != CAPSULE_VARIANT:
+                continue
+            capsule_id = _required_text(meta.get("capsule_id"), "capsule_id")
+            revision = meta.get("revision")
+            status = _required_text(meta.get("status"), "capsule status")
+            if not isinstance(revision, int) or revision < 1:
+                raise AuditError("capsule revision is invalid")
+            if status not in {"active", "challenged", "retired", "superseded"}:
+                raise AuditError("capsule status is invalid")
+            claims = _validate_claims(meta.get("claims"), stored=True)
+            capsules.setdefault(capsule_id, []).append(
+                (str(row["memory_id"]), str(row["state"]), revision, status)
+            )
+            for claim in claims:
+                expected = set(claim["support"] + claim["counterevidence"])
+                actual = {
+                    str(item["evidence_memory_id"])
+                    for item in con.execute(
+                        "SELECT evidence_memory_id FROM slow_graph_provenance "
+                        "WHERE scope_id=? AND capsule_id=? AND revision=? AND claim_id=?",
+                        (scope_id, capsule_id, revision, claim["claim_id"]),
+                    )
+                }
+                if actual != expected:
+                    raise AuditError("claim provenance does not match claim evidence")
+        for capsule_id, revisions in capsules.items():
+            ordered = sorted(revisions, key=lambda item: item[2])
+            if [item[2] for item in ordered] != list(range(1, len(ordered) + 1)):
+                raise AuditError("capsule revisions are not contiguous")
+            memory_id, state, _, status = ordered[-1]
+            slot_key = "slow." + capsule_id
+            head = con.execute(
+                "SELECT memory_id FROM slot_heads WHERE scope_id=? AND slot_key=?",
+                (scope_id, slot_key),
+            ).fetchone()
+            if status in {"active", "challenged"}:
+                if state != "active" or head is None or head["memory_id"] != memory_id:
+                    raise AuditError("active/challenged capsule head is inconsistent")
+            elif head is not None:
+                raise AuditError("inactive capsule must not retain a slot head")
+            history = [
+                str(item["memory_id"])
+                for item in con.execute(
+                    "SELECT memory_id FROM slot_history WHERE scope_id=? AND slot_key=? ORDER BY ordinal",
+                    (scope_id, slot_key),
+                )
+            ]
+            if history != [item[0] for item in ordered]:
+                raise AuditError("capsule slot history is inconsistent")
+        for edge in con.execute(
+            "SELECT source_memory_id,target_memory_id,edge_type,metadata_json "
+            "FROM memory_edges WHERE scope_id=?",
+            (scope_id,),
+        ):
+            meta = _strict_json(
+                edge["metadata_json"], label="edge metadata", expected=dict
+            )
+            if meta.get("edge_source") != SLOW_EDGE_SOURCE:
+                continue
+            if (
+                edge["source_memory_id"] == edge["target_memory_id"]
+                or edge["edge_type"] not in EDGE_TYPES
+                or edge["source_memory_id"] not in known_records
+                or edge["target_memory_id"] not in known_records
+                or not isinstance(meta.get("evidence_refs"), list)
+                or not _clean(meta.get("patch_id"))
+            ):
+                raise AuditError("slow graph edge is inconsistent")
+
+    def apply_patch(
+        self,
+        job_id: str,
+        patch: Mapping[str, Any],
+        *,
+        manager_model: str,
+        call_metadata: Mapping[str, Any] | None = None,
+        claim: JobClaim,
+    ) -> str:
+        validate_patch(patch)
+        if claim.job_id != job_id:
+            raise SlowGraphError("claim does not belong to job")
+        patch_id = "sgp_" + uuid.uuid4().hex
+        with self.connection() as con:
+            con.execute("BEGIN IMMEDIATE")
+            now = _now()
+            job = con.execute(
+                "SELECT * FROM slow_graph_jobs WHERE job_id=?", (job_id,)
+            ).fetchone()
+            if job is None:
+                raise SlowGraphError("unknown slow graph job")
+            if (
+                job["status"] != "pending"
+                or job["claim_token"] != claim.token
+                or job["claim_owner"] != claim.owner
+                or job["lease_expires_at"] is None
+                or int(job["lease_expires_at"]) < now
+            ):
+                raise SlowGraphError("job claim is no longer active")
+            self._records_table_exists(con)
+            metadata = self._metadata(job, "job")
+            if metadata["schema_version"] != SCHEMA_VERSION:
+                raise SlowGraphError("job schema metadata drift")
+            con.execute(
+                "INSERT INTO slow_graph_patches VALUES(?,?,?,?,?,?,?,?)",
+                (
+                    patch_id,
+                    job_id,
+                    job["scope_id"],
+                    job["region_key"],
+                    manager_model,
+                    _json(patch),
+                    _json(dict(call_metadata or {})),
+                    now,
+                ),
+            )
+            ordinal = 0
+            for operation in patch["operations"]:
+                action = operation["action"]
+                region_capsule_id = self._capsule_id(
+                    job["scope_id"], job["region_key"]
+                )
+                capsule_id = (
+                    region_capsule_id
+                    if action == "create"
+                    else operation.get("capsule_id")
+                    or "region:" + job["region_key"]
+                )
+                if action != "create" and operation.get("capsule_id"):
+                    if capsule_id != region_capsule_id:
+                        raise EvidencePolicyError(
+                            "GraphPatch capsule_id does not belong to the current region"
+                        )
+                head = self._head(con, job["scope_id"], capsule_id)
+                if action == "create":
+                    if head is not None:
+                        raise StaleRevisionError("capsule already exists")
+                    record_id = self._insert_revision(
+                        con,
+                        job=job,
+                        patch_id=patch_id,
+                        operation=operation,
+                        capsule_id=capsule_id,
+                        revision=1,
+                        action=action,
+                    )
+                    base, revision = None, 1
+                elif action == "noop":
+                    if operation.get("capsule_id") and head is None:
+                        raise StaleRevisionError("noop capsule does not exist")
+                    if head is None:
+                        record_id, base, revision = "", None, None
+                    else:
+                        record_id, (revision, _) = head[1], head
+                        base = revision
+                else:
+                    if head is None or operation["base_revision"] != head[0]:
+                        raise StaleRevisionError(
+                            "base_revision is stale for " + capsule_id
+                        )
+                    base, revision = head[0], head[0] + 1
+                    record_id = self._insert_revision(
+                        con,
+                        job=job,
+                        patch_id=patch_id,
+                        operation=operation,
+                        capsule_id=capsule_id,
+                        revision=revision,
+                        action=action,
+                        old_memory_id=head[1],
+                    )
+                    if action == "challenge":
+                        self._write_edge(
+                            con,
+                            scope_id=job["scope_id"],
+                            source=record_id,
+                            target=head[1],
+                            edge_type="challenges",
+                            patch_id=patch_id,
+                            evidence_refs=[],
+                            action=action,
+                            turn=now,
+                        )
+                    if action == "retire":
+                        self._write_edge(
+                            con,
+                            scope_id=job["scope_id"],
+                            source=record_id,
+                            target=head[1],
+                            edge_type="invalidates",
+                            patch_id=patch_id,
+                            evidence_refs=[],
+                            action=action,
+                            turn=now,
+                        )
+                con.execute(
+                    "INSERT INTO slow_graph_patch_operations VALUES(?,?,?,?,?,?,?,?,?)",
+                    (
+                        "sgo_" + uuid.uuid4().hex,
+                        patch_id,
+                        ordinal,
+                        capsule_id,
+                        action,
+                        base,
+                        revision,
+                        _json(operation),
+                        now,
+                    ),
+                )
+                ordinal += 1
+            completed_attempt = con.execute(
+                "UPDATE slow_graph_attempts SET status='completed',"
+                "call_metadata_json=?,completed_at=? WHERE attempt_id=? AND job_id=? "
+                "AND claim_token=? AND claim_owner=? AND status='started'",
+                (
+                    _json(dict(call_metadata or {})),
+                    now,
+                    claim.attempt_id,
+                    job_id,
+                    claim.token,
+                    claim.owner,
+                ),
+            )
+            if completed_attempt.rowcount != 1:
+                raise SlowGraphError("claimed attempt is no longer active")
+            completed_job = con.execute(
+                "UPDATE slow_graph_jobs SET status='completed',attempts=attempts+1,"
+                "last_error='',updated_at=?,claim_token=NULL,claim_owner=NULL,"
+                "lease_expires_at=NULL WHERE job_id=? AND status='pending' "
+                "AND claim_token=? AND claim_owner=? AND lease_expires_at>=?",
+                (now, job_id, claim.token, claim.owner, now),
+            )
+            if completed_job.rowcount != 1:
+                raise SlowGraphError("job claim expired before completion")
+            self._audit_transaction(con, job["scope_id"])
+        return patch_id
+
+    def _claim_pending_job(
+        self, job_id: str | None, *, owner: str
+    ) -> JobClaim | None:
+        token = "sgc_" + uuid.uuid4().hex
+        attempt_id = "sga_" + uuid.uuid4().hex
+        now = _now()
+        with self.connection() as con:
+            con.execute("BEGIN IMMEDIATE")
+            if job_id is None:
+                row = con.execute(
+                    "SELECT job_id,scope_id FROM slow_graph_jobs WHERE status='pending' "
+                    "AND claim_token IS NULL ORDER BY created_at LIMIT 1"
+                ).fetchone()
+            else:
+                row = con.execute(
+                    "SELECT job_id,scope_id FROM slow_graph_jobs WHERE job_id=? "
+                    "AND status='pending' AND claim_token IS NULL",
+                    (job_id,),
+                ).fetchone()
+            if row is None:
+                return None
+            claimed = con.execute(
+                "UPDATE slow_graph_jobs SET claim_token=?,claim_owner=?,"
+                "lease_expires_at=?,updated_at=? WHERE job_id=? AND status='pending' "
+                "AND claim_token IS NULL",
+                (
+                    token,
+                    owner,
+                    now + self.claim_lease_seconds,
+                    now,
+                    str(row["job_id"]),
+                ),
+            )
+            if claimed.rowcount != 1:
+                return None
+            con.execute(
+                "INSERT INTO slow_graph_attempts("
+                "attempt_id,job_id,scope_id,status,call_metadata_json,error,created_at,"
+                "completed_at,claim_token,claim_owner) VALUES(?,?,?,?,?,?,?,?,?,?)",
+                (
+                    attempt_id,
+                    str(row["job_id"]),
+                    str(row["scope_id"]),
+                    "started",
+                    _json({}),
+                    "",
+                    now,
+                    None,
+                    token,
+                    owner,
+                ),
+            )
+        return JobClaim(str(row["job_id"]), attempt_id, token, owner)
+
+    def _claim_owner(self) -> str:
+        return "pid:" + str(os.getpid()) + ":" + uuid.uuid4().hex
+
+    def _claim_context(
+        self, claim: JobClaim
+    ) -> tuple[dict[str, Any], list[dict[str, Any]]]:
+        with self.connection() as con:
+            job = con.execute(
+                "SELECT * FROM slow_graph_jobs WHERE job_id=?", (claim.job_id,)
+            ).fetchone()
+            if job is None:
+                raise SlowGraphError("unknown slow graph job")
+            if (
+                job["status"] != "pending"
+                or job["claim_token"] != claim.token
+                or job["claim_owner"] != claim.owner
+                or job["lease_expires_at"] is None
+                or int(job["lease_expires_at"]) < _now()
+            ):
+                raise SlowGraphError("job claim is no longer active")
+            evidence_ids = _strict_json(
+                job["evidence_ids_json"], label="job evidence IDs", expected=list
+            )
+            return (
+                {
+                    "region_key": job["region_key"],
+                    "evidence": self._evidence(con, job["scope_id"], evidence_ids),
+                },
+                self._capsules(con, job["scope_id"], job["region_key"]),
+            )
+
+    def _renew_claim(self, claim: JobClaim) -> None:
+        now = _now()
+        with self.connection() as con:
+            con.execute("BEGIN IMMEDIATE")
+            renewed = con.execute(
+                "UPDATE slow_graph_jobs SET lease_expires_at=?,updated_at=? "
+                "WHERE job_id=? AND status='pending' AND claim_token=? "
+                "AND claim_owner=? AND lease_expires_at>=?",
+                (
+                    now + self.claim_lease_seconds,
+                    now,
+                    claim.job_id,
+                    claim.token,
+                    claim.owner,
+                    now,
+                ),
+            )
+            if renewed.rowcount != 1:
+                raise SlowGraphError("job claim could not be renewed")
+
+    def _propose_with_lease_heartbeat(
+        self,
+        claim: JobClaim,
+        manager: PatchManager,
+        region: Mapping[str, Any],
+        capsules: list[dict[str, Any]],
+    ) -> dict[str, Any]:
+        stop = threading.Event()
+        errors: list[Exception] = []
+        interval = max(0.1, min(30.0, self.claim_lease_seconds / 3.0))
+
+        def heartbeat() -> None:
+            while not stop.wait(interval):
+                try:
+                    self._renew_claim(claim)
+                except Exception as exc:
+                    errors.append(exc)
+                    stop.set()
+
+        thread = threading.Thread(
+            target=heartbeat,
+            name=f"slow-graph-lease-{claim.job_id}",
+            daemon=True,
+        )
+        thread.start()
+        try:
+            patch = manager.propose(region, capsules)
+        finally:
+            stop.set()
+            thread.join(timeout=max(1.0, interval + 1.0))
+        if thread.is_alive():
+            raise SlowGraphError("slow graph claim heartbeat did not stop")
+        if errors:
+            raise SlowGraphError(f"slow graph claim heartbeat failed: {errors[0]}")
+        self._renew_claim(claim)
+        return patch
+
+    def _finish_claim_failure(
+        self, claim: JobClaim, manager: PatchManager, exc: Exception
+    ) -> bool:
+        status = (
+            "retryable"
+            if isinstance(exc, DeepSeekCallError) and exc.retryable
+            else "failed"
+        )
+        now = _now()
+        with self.connection() as con:
+            con.execute("BEGIN IMMEDIATE")
+            failed_job = con.execute(
+                "UPDATE slow_graph_jobs SET status=?,attempts=attempts+1,last_error=?,"
+                "updated_at=?,claim_token=NULL,claim_owner=NULL,lease_expires_at=NULL "
+                "WHERE job_id=? AND status='pending' AND claim_token=? "
+                "AND claim_owner=? AND lease_expires_at>=?",
+                (status, str(exc), now, claim.job_id, claim.token, claim.owner, now),
+            )
+            if failed_job.rowcount != 1:
+                return False
+            failed_attempt = con.execute(
+                "UPDATE slow_graph_attempts SET status=?,call_metadata_json=?,error=?,"
+                "completed_at=? WHERE attempt_id=? AND job_id=? AND claim_token=? "
+                "AND claim_owner=? AND status='started'",
+                (
+                    status,
+                    _json(dict(manager.last_call_metadata)),
+                    str(exc),
+                    now,
+                    claim.attempt_id,
+                    claim.job_id,
+                    claim.token,
+                    claim.owner,
+                ),
+            )
+            if failed_attempt.rowcount != 1:
+                raise SlowGraphError("claimed attempt is no longer active")
+        return True
+
+    def _run_claimed_job(self, claim: JobClaim, manager: PatchManager) -> str:
+        try:
+            region, capsules = self._claim_context(claim)
+            patch = self._propose_with_lease_heartbeat(
+                claim, manager, region, capsules
+            )
+            patch_id = self.apply_patch(
+                claim.job_id,
+                patch,
+                manager_model=_required_text(
+                    manager.model_config.get("model"), "manager model"
+                ),
+                call_metadata=manager.last_call_metadata,
+                claim=claim,
+            )
+            return patch_id
+        except Exception as exc:
+            self._finish_claim_failure(claim, manager, exc)
+            raise
+
+    def run_job(self, job_id: str, manager: PatchManager) -> str:
+        self.recover_interrupted_attempts()
+        claim = self._claim_pending_job(job_id, owner=self._claim_owner())
+        if claim is None:
+            raise SlowGraphError("job is not pending or is already claimed")
+        return self._run_claimed_job(claim, manager)
+
+    def resume(self, job_id: str) -> None:
+        with self.connection() as con:
+            con.execute("BEGIN IMMEDIATE")
+            row = con.execute(
+                "SELECT status,claim_token FROM slow_graph_jobs WHERE job_id=?",
+                (job_id,),
+            ).fetchone()
+            if (
+                row is None
+                or row["status"] not in {"failed", "retryable"}
+                or row["claim_token"] is not None
+            ):
+                raise SlowGraphError(
+                    "only failed or retryable jobs can be explicitly reopened"
+                )
+            reopened = con.execute(
+                "UPDATE slow_graph_jobs SET status='pending',last_error='',updated_at=?,"
+                "claim_token=NULL,claim_owner=NULL,lease_expires_at=NULL WHERE job_id=? "
+                "AND status IN ('failed','retryable') AND claim_token IS NULL",
+                (_now(), job_id),
+            )
+            if reopened.rowcount != 1:
+                raise SlowGraphError("slow graph job changed while reopening")
+
+    def recover_interrupted_attempts(self) -> int:
+        now = _now()
+        with self.connection() as con:
+            con.execute("BEGIN IMMEDIATE")
+            rows = con.execute(
+                "SELECT job_id,claim_token,claim_owner FROM slow_graph_jobs "
+                "WHERE status='pending' AND claim_token IS NOT NULL "
+                "AND lease_expires_at<?",
+                (now,),
+            ).fetchall()
+            for row in rows:
+                released = con.execute(
+                    "UPDATE slow_graph_jobs SET status='failed',attempts=attempts+1,"
+                    "last_error='claim lease expired; external call outcome uncertain; explicit resume required',"
+                    "updated_at=?,claim_token=NULL,claim_owner=NULL,lease_expires_at=NULL "
+                    "WHERE job_id=? AND status='pending' AND claim_token=? "
+                    "AND claim_owner=? AND lease_expires_at<?",
+                    (
+                        now,
+                        row["job_id"],
+                        row["claim_token"],
+                        row["claim_owner"],
+                        now,
+                    ),
+                )
+                if released.rowcount != 1:
+                    raise SlowGraphError("expired job claim changed during recovery")
+                expired_attempt = con.execute(
+                    "UPDATE slow_graph_attempts SET status='expired',"
+                    "error='claim lease expired; external call outcome uncertain; explicit resume required',completed_at=? "
+                    "WHERE job_id=? AND claim_token=? AND claim_owner=? "
+                    "AND status='started'",
+                    (now, row["job_id"], row["claim_token"], row["claim_owner"]),
+                )
+                if expired_attempt.rowcount != 1:
+                    raise SlowGraphError("expired job has no active claimed attempt")
+        return len(rows)
+
+    def drain(
+        self, manager: PatchManager, *, batch_size: int | None = None
+    ) -> list[str]:
+        self.recover_interrupted_attempts()
+        if batch_size is not None:
+            if batch_size <= 0:
+                raise SlowGraphError("batch_size must be positive")
+        owner = self._claim_owner()
+        result: list[str] = []
+        while batch_size is None or len(result) < batch_size:
+            claim = self._claim_pending_job(None, owner=owner)
+            if claim is None:
+                break
+            result.append(self._run_claimed_job(claim, manager))
+        return result
+
+    def audit(self, scope_id: str) -> dict[str, int]:
+        with self.connection() as con:
+            self._records_table_exists(con)
+            unfinished = con.execute(
+                "SELECT job_id,status,last_error FROM slow_graph_jobs WHERE scope_id=? AND status!='completed' ORDER BY created_at",
+                (scope_id,),
+            ).fetchall()
+            if unfinished:
+                raise AuditError(
+                    "scope has unfinished slow graph jobs: "
+                    + _json([dict(item) for item in unfinished])
+                )
+            rows = con.execute(
+                "SELECT memory_id,state,metadata_json FROM records WHERE scope_id=?",
+                (scope_id,),
+            ).fetchall()
+            fast_state: dict[str, tuple[str, str]] = {}
+            active_fast_by_slot: dict[str, set[str]] = {}
+            for row in rows:
+                row_meta = self._metadata(row, "record")
+                if (
+                    row_meta.get("content_variant") == LEAF_VARIANT
+                    and row_meta.get("memory_layer") == "fast"
+                ):
+                    slot = _clean(row_meta.get("canonical_slot_key"))
+                    state = _clean(row["state"])
+                    fast_state[str(row["memory_id"])] = (state, slot)
+                    if state in {"active", "parallel_active", "promoted"}:
+                        active_fast_by_slot.setdefault(slot, set()).add(
+                            str(row["memory_id"])
+                        )
+            capsules: dict[str, list[tuple[str, str, int, str]]] = {}
+            for row in rows:
+                meta = self._metadata(row, "record")
+                if meta.get("content_variant") != CAPSULE_VARIANT:
+                    continue
+                capsule_id = _required_text(meta.get("capsule_id"), "capsule_id")
+                revision = meta.get("revision")
+                if not isinstance(revision, int) or revision < 1:
+                    raise AuditError("capsule revision is invalid")
+                status = _required_text(meta.get("status"), "capsule status")
+                if status not in {"active", "challenged", "retired", "superseded"}:
+                    raise AuditError("capsule status is invalid")
+                capsules.setdefault(capsule_id, []).append(
+                    (str(row["memory_id"]), str(row["state"]), revision, status)
+                )
+                claims = _validate_claims(meta.get("claims"), stored=True)
+                for claim in claims:
+                    if status in {"active", "challenged"}:
+                        stale_support = {
+                            evidence_id
+                            for evidence_id in claim["support"]
+                            if fast_state.get(evidence_id, ("", ""))[0]
+                            not in {"active", "parallel_active", "promoted"}
+                        }
+                        current_replacements = active_fast_by_slot.get(
+                            claim["canonical_slot"], set()
+                        )
+                        if (
+                            stale_support
+                            and current_replacements
+                            and not current_replacements.intersection(
+                                claim["counterevidence"]
+                            )
+                        ):
+                            raise AuditError(
+                                "active capsule claim promotes superseded fast evidence"
+                            )
+                    evidence = claim["support"] + claim["counterevidence"]
+                    provenance = con.execute(
+                        "SELECT evidence_memory_id,source_parent_json FROM slow_graph_provenance WHERE scope_id=? AND capsule_id=? AND revision=? AND claim_id=?",
+                        (scope_id, capsule_id, revision, claim["claim_id"]),
+                    ).fetchall()
+                    if {item["evidence_memory_id"] for item in provenance} != set(
+                        evidence
+                    ):
+                        raise AuditError(
+                            "claim provenance does not match claim evidence"
+                        )
+                    for item in provenance:
+                        parent = _strict_json(
+                            item["source_parent_json"],
+                            label="provenance source_parent",
+                            expected=dict,
+                        )
+                        if set(parent) != {
+                            "session_index",
+                            "parent_chunk_index",
+                            "message_index",
+                            "source_record_id",
+                            "event_id",
+                            "evidence_char_start",
+                            "evidence_char_end",
+                        }:
+                            raise AuditError("provenance is not a leaf source_parent")
+                        leaf = con.execute(
+                            "SELECT metadata_json FROM records WHERE scope_id=? AND memory_id=?",
+                            (scope_id, item["evidence_memory_id"]),
+                        ).fetchone()
+                        if leaf is None:
+                            raise AuditError("provenance references missing evidence")
+                        leaf_meta = self._metadata(leaf, "provenance leaf")
+                        expected_parent = {
+                            "session_index": leaf_meta.get("session_index"),
+                            "parent_chunk_index": leaf_meta.get("message_index"),
+                            "message_index": leaf_meta.get("message_index"),
+                            "source_record_id": leaf_meta.get("source_record_id"),
+                            "event_id": leaf_meta.get("event_id"),
+                            "evidence_char_start": leaf_meta.get(
+                                "evidence_char_start"
+                            ),
+                            "evidence_char_end": leaf_meta.get("evidence_char_end"),
+                        }
+                        if (
+                            leaf_meta.get("content_variant") != LEAF_VARIANT
+                            or leaf_meta.get("memory_layer") != "fast"
+                            or leaf_meta.get("node_kind") != "atomic_user_assertion"
+                            or leaf_meta.get("atomic_evidence_leaf") is not True
+                            or leaf_meta.get("authority") != "user_assertion"
+                            or expected_parent != parent
+                        ):
+                            raise AuditError(
+                                "provenance does not resolve to the cited fast leaf"
+                            )
+            for capsule_id, revisions in capsules.items():
+                revision_numbers = sorted(item[2] for item in revisions)
+                if revision_numbers != list(range(1, max(revision_numbers) + 1)):
+                    raise AuditError("capsule revisions are not contiguous")
+                latest = [item for item in revisions if item[2] == max(revision_numbers)]
+                if len(latest) != 1:
+                    raise AuditError("capsule lacks one latest revision")
+                memory_id, state, _, status = latest[0]
+                slot_key = "slow." + capsule_id
+                head = con.execute(
+                    "SELECT memory_id FROM slot_heads WHERE scope_id=? AND slot_key=?",
+                    (scope_id, slot_key),
+                ).fetchone()
+                if status in {"active", "challenged"}:
+                    if state != "active" or head is None or head["memory_id"] != memory_id:
+                        raise AuditError("active/challenged capsule head is inconsistent")
+                elif head is not None:
+                    raise AuditError("inactive capsule must not retain a slot head")
+                history = [
+                    item["memory_id"]
+                    for item in con.execute(
+                        "SELECT memory_id FROM slot_history WHERE scope_id=? AND slot_key=? ORDER BY ordinal",
+                        (scope_id, slot_key),
+                    )
+                ]
+                expected_history = [
+                    item[0] for item in sorted(revisions, key=lambda item: item[2])
+                ]
+                if history != expected_history:
+                    raise AuditError("capsule slot history is inconsistent")
+            edge_rows = con.execute(
+                "SELECT source_memory_id,target_memory_id,edge_type,metadata_json FROM memory_edges WHERE scope_id=?",
+                (scope_id,),
+            ).fetchall()
+            for edge in edge_rows:
+                meta = _strict_json(
+                    edge["metadata_json"], label="edge metadata", expected=dict
+                )
+                if meta.get("edge_source") != SLOW_EDGE_SOURCE:
+                    continue
+                if (
+                    edge["source_memory_id"] == edge["target_memory_id"]
+                    or edge["edge_type"] not in EDGE_TYPES
+                    or not isinstance(meta.get("evidence_refs"), list)
+                    or not _clean(meta.get("patch_id"))
+                ):
+                    raise AuditError("edge is inconsistent")
+            return {
+                "slow_graph_batches": int(
+                    con.execute(
+                        "SELECT COUNT(*) FROM slow_graph_batches WHERE scope_id=?",
+                        (scope_id,),
+                    ).fetchone()[0]
+                ),
+                "slow_graph_jobs": int(
+                    con.execute(
+                        "SELECT COUNT(*) FROM slow_graph_jobs WHERE scope_id=?",
+                        (scope_id,),
+                    ).fetchone()[0]
+                ),
+                "slow_graph_patches": int(
+                    con.execute(
+                        "SELECT COUNT(*) FROM slow_graph_patches WHERE scope_id=?",
+                        (scope_id,),
+                    ).fetchone()[0]
+                ),
+                "slow_graph_attempts": int(
+                    con.execute(
+                        "SELECT COUNT(*) FROM slow_graph_attempts WHERE scope_id=?",
+                        (scope_id,),
+                    ).fetchone()[0]
+                ),
+                "slow_graph_patch_operations": int(
+                    con.execute(
+                        "SELECT COUNT(*) FROM slow_graph_patch_operations o JOIN slow_graph_patches p ON p.patch_id=o.patch_id WHERE p.scope_id=?",
+                        (scope_id,),
+                    ).fetchone()[0]
+                ),
+                "slow_graph_provenance": int(
+                    con.execute(
+                        "SELECT COUNT(*) FROM slow_graph_provenance WHERE scope_id=?",
+                        (scope_id,),
+                    ).fetchone()[0]
+                ),
+                "memory_edges": sum(
+                    1
+                    for edge in edge_rows
+                    if _strict_json(
+                        edge["metadata_json"], label="edge metadata", expected=dict
+                    ).get("edge_source")
+                    == SLOW_EDGE_SOURCE
+                ),
+            }
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="TMCRA slow graph controller")
+    parser.add_argument("database", type=Path)
+    parser.add_argument(
+        "--repo",
+        type=Path,
+        required=True,
+        help="TMCRA repository containing the real graph schema",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+    enqueue = sub.add_parser("enqueue")
+    enqueue.add_argument("scope_id")
+    enqueue.add_argument("--region")
+    drain = sub.add_parser("drain")
+    drain.add_argument("--batch-size", type=int)
+    run = sub.add_parser("run")
+    run.add_argument("job_id")
+    resume = sub.add_parser("resume")
+    resume.add_argument("job_id")
+    audit = sub.add_parser("audit")
+    audit.add_argument("scope_id")
+    args = parser.parse_args()
+    store = SlowGraphStore(args.database, schema=load_graph_schema(args.repo))
+    if args.command == "enqueue":
+        manager = DeepSeekProGraphPatchManager(DeepSeekProConfig.from_env())
+        if args.region:
+            region = store.fast_regions(args.scope_id).get(args.region, [])
+            result = [
+                store.enqueue(
+                    args.scope_id,
+                    args.region,
+                    (item["memory_id"] for item in region),
+                    manager=manager,
+                )
+            ]
+        else:
+            result = store.enqueue_regions(args.scope_id, manager=manager)
+    elif args.command == "resume":
+        store.resume(args.job_id)
+        result = {"job_id": args.job_id, "status": "pending"}
+    elif args.command == "audit":
+        result = store.audit(args.scope_id)
+    else:
+        manager = DeepSeekProGraphPatchManager(DeepSeekProConfig.from_env())
+        result = (
+            store.drain(manager, batch_size=args.batch_size)
+            if args.command == "drain"
+            else store.run_job(args.job_id, manager)
+        )
+    print(_json(result))
+
+
+if __name__ == "__main__":
+    main()