@xdarkicex/openclaw-memory-libravdb 1.3.9 → 1.3.12

package/README.md

@@ -2,6 +2,19 @@
 
 ## Install
 
+Recommended on macOS:
+
+```bash
+brew tap xDarkicex/openclaw-libravdb-memory
+brew install libravdbd
+brew services start libravdbd
+openclaw plugins install @xdarkicex/openclaw-memory-libravdb
+```
+
+Then activate the plugin in `~/.openclaw/openclaw.json`.
+
+Manual plugin install:
+
 ```bash
 openclaw plugins install @xdarkicex/openclaw-memory-libravdb
 ```
@@ -34,6 +47,11 @@ Phase 2 packaging assets now live under [`packaging/`](./packaging):
 - `packaging/launchd/com.xdarkicex.libravdbd.plist` for macOS LaunchAgents
 - `packaging/homebrew/libravdbd.rb.tmpl` as the source template for a generated Homebrew formula
 
+Recommended service startup commands:
+
+- macOS: `brew services start libravdbd`
+- Linux: `systemctl --user enable --now libravdbd.service`
+
 ## Activate
 
 Add this to `~/.openclaw/openclaw.json`:

package/docs/README.md

@@ -1,9 +1,17 @@
 # Documentation Index
 
+Versioned `*-v*` design docs are the reviewed authoritative references when a
+legacy non-versioned predecessor also exists. Older non-versioned docs are kept
+to preserve project history and design evolution.
+
 - [installation.md](./installation.md) - Complete install, activation, verification, and troubleshooting reference.
 - [architecture.md](./architecture.md) - End-to-end component model, turn lifecycle, compaction flow, and degraded behavior.
 - [problem.md](./problem.md) - Technical argument for replacing the stock OpenClaw memory lifecycle in this use case.
-- [mathematics.md](./mathematics.md) - Formal reference for hybrid scoring, decay, token budgeting, Matryoshka retrieval, and compaction.
+- [mathematics-v2.md](./mathematics-v2.md) - Formal reference for hybrid scoring, decay, token budgeting, Matryoshka retrieval, compaction, and planned two-pass retrieval.
+- [compaction-evaluation.md](./compaction-evaluation.md) - Real-model benchmark notes for T5 summary confidence, Nomic-space preservation, and the hard preservation gate.
+- [continuity.md](./continuity.md) - Continuity model for invariant context, preserved recent raw session tail, and retrieved older memory.
+- [ast-v2.md](./ast-v2.md) - Reviewed authoritative AST partitioning reference for authored Markdown hard invariants, soft invariants, and variant lore.
+- [ast.md](./ast.md) - Historical predecessor to `ast-v2.md`, kept to show design evolution and earlier bugs.
 - [gating.md](./gating.md) - Full derivation and calibration guide for the domain-adaptive gating scalar.
 - [implementation.md](./implementation.md) - Non-obvious implementation decisions and their rationale.
 - [dependencies.md](./dependencies.md) - Why LibraVDB and slab-based storage were chosen for this plugin.

package/docs/ast-v2.md

@@ -0,0 +1,125 @@
+# TITLE: Mathematical Reference - Abstract Syntax Tree (AST) Partitioning
+
+This document formalizes the heuristic mapping of user-authored Markdown documents (such as `agents.md` and `souls.md`) into the partitioned sets required by the two-pass retrieval system. It serves as the bridge between raw text ingestion and the rigorous corpus decomposition defined in `mathematics-v2.md`.
+
+The design goal is to extract rigid behavioral rules (the invariant sets) from contextual lore (the variant set) automatically. This is achieved using a three-tier structural and semantic proxy, eliminating monolithic injection while protecting user constraints from token-budget starvation.
+
+## 1. The Document AST and Node Extraction
+
+Let a raw Markdown document \(d_{\mathrm{raw}}\) be parsed into an Abstract Syntax Tree \(\mathcal{T}\). 
+Let \(E: \mathcal{T} \to N_d\) be an extraction function that flattens the tree into an ordered sequence of semantic leaf nodes \(N_d = \langle n_1, n_2, \dots, n_k \rangle\). 
+
+Each node \(n_i \in N_d\) has an associated structural kind assigned by the parser (e.g., `yuin/goldmark`), mapped by the function \(\kappa: N_d \to K\), where \(K\) is the set of supported Markdown node types:
+\[ K = \{ \text{Paragraph}, \text{List}, \text{Blockquote}, \text{YAMLFrontmatter}, \text{Heading}, \dots \} \]
+
+*Implemented in `sidecaragentparser.go`.*
+
+## 2. Formal Deontic Logic (\(\sigma\)) and the Kripke Frame
+
+Structural types alone are insufficient proxies for intent. Narrative lore often resides in paragraphs, but authors frequently place critical instructions there as well (e.g., "You must always answer in JSON"). 
+
+To detect these rules without deep NLP allocations, the parser evaluates raw node bytes against a Kripke Frame \((W, R)\) grounded in Standard Deontic Logic (SDL). 
+
+Let \(\mathcal{B}\) be the set of valid second-person imperative bigrams (e.g., "you must", "never"). A zero-allocation lexer scans the bytes for patterns in \(\mathcal{B}\), mapping them to Modalities (Obligatory, Forbidden, Permitted).
+
+To guarantee logical consistency, the engine enforces Seriality (Axiom D). No world reachable from an Obligatory state may contain a Forbidden obligation on the same action:
+\[ O(\phi) \implies \neg F(\text{next}(\phi)) \]
+
+We formalize this as a binary promotion scalar \(\sigma: N_d \to \{0,1\}\). This function is specifically targeted at Paragraph nodes, as structural invariants bypass it:
+\[
+\sigma(n) = \begin{cases} 
+1 & \text{if } \kappa(n) = \text{Paragraph} \land \text{SDL}(\mathcal{B}) \text{ detects a valid imperative} \\ 
+0 & \text{otherwise} 
+\end{cases}
+\]
+
+*Implemented via `NewDeonticFrame` and `EvaluateText` in the zero-allocation byte lexer.*
+
+## 3. The Three-Tier Structural Indicator Function \(\iota\)
+
+To avoid the brittleness of a binary pass/fail budget, we distribute nodes across a three-tier priority hierarchy.
+
+Let \(K_{\mathcal{I}1} \subset K\) be the subset of node kinds that represent hard authorial constraints:
+\[ K_{\mathcal{I}1} = \{ \text{List}, \text{YAMLFrontmatter} \} \]
+
+Let \(K_{\mathcal{I}2} \subset K\) be the subset of node kinds that represent soft constraints or stylistic guidelines:
+\[ K_{\mathcal{I}2} = \{ \text{Blockquote} \} \]
+
+We define the structural indicator function \(\iota: N_d \to \{0,1,2\}\) mapping each node to a specific tier:
+\[
+\iota(n) = \begin{cases} 
+1 & \text{if } \kappa(n) \in K_{\mathcal{I}1} \quad \text{(Hard Invariant)} \\ 
+2 & \text{if } \kappa(n) \in K_{\mathcal{I}2} \lor \sigma(n) = 1 \quad \text{(Soft Invariant)} \\
+0 & \text{otherwise} \quad \text{(Variant Lore)}
+\end{cases}
+\]
+
+*Proof of Reachability:* If a node is a Paragraph, \(\kappa(n) \notin K_{\mathcal{I}1}\) and \(\kappa(n) \notin K_{\mathcal{I}2}\). However, if the deontic lexer detects a rule, \(\sigma(n) = 1\), causing the logical OR condition for \(\iota(n) = 2\) to evaluate to true, successfully promoting the paragraph to a Soft Invariant.
+
+## 4. Corpus Decomposition and Set Integration
+
+For any document \(d \in \mathbf{D}_{\text{agents}} \cup \mathbf{D}_{\text{souls}}\), the node set \(N_d\) is partitioned cleanly into three sets:
+- **Hard Directives:** \(\mathcal{I}_{1d} = \{ n \in N_d \mid \iota(n) = 1 \}\)
+- **Soft Directives:** \(\mathcal{I}_{2d} = \{ n \in N_d \mid \iota(n) = 2 \}\)
+- **Contextual Lore:** \(\mathcal{V}_d = \{ n \in N_d \mid \iota(n) = 0 \}\)
+
+*Partition Completeness:* Because \(\iota(n)\) maps every node to exactly one integer in \(\{0, 1, 2\}\), the resulting sets are mutually exclusive and collectively exhaustive:
+\[ \mathcal{I}_{1d} \cup \mathcal{I}_{2d} \cup \mathcal{V}_d = N_d \quad \text{and} \quad \mathcal{I}_{1d} \cap \mathcal{I}_{2d} \cap \mathcal{V}_d = \emptyset \]
+
+These sets integrate into the global corpus. Let \(\mathbf{D}_{\text{standard}}\) be the set of standard memory documents (non-core files). We formally define the standard variant node set as \(\mathcal{V}_{\text{standard}} = \bigcup_{d \in \mathbf{D}_{\text{standard}}} E(d)\). The global corpus is then:
+\[ \mathcal{I}_1 = \bigcup_{d} \mathcal{I}_{1d} \qquad \mathcal{I}_2 = \bigcup_{d} \mathcal{I}_{2d} \qquad \mathcal{V} = \mathcal{V}_{\text{standard}} \cup \left( \bigcup_{d} \mathcal{V}_d \right) \]
+
+By definition, any chunk \(n \in \mathcal{I}_{1d}\) inherits the hard startup injection guarantee from `mathematics-v2.md`. To clarify, \(G(q,n)\) represents the runtime *gating admission scalar*, not semantic relevance.
+\[ \iota(n)=1 \implies G(q,n)=1 \quad \forall q \in \mathbf{Q} \]
+
+## 5. Authored Authority Boost for Variant Lore
+
+Chunks in \(\mathcal{V}_d\) lose their invariant injection guarantee and must survive semantic vector retrieval. To ensure that agent-specific lore outcompetes general conversational memory, we enforce a strict authority override. For all \(n \in \mathcal{V}_d\) extracted from a core identity document:
+\[ a_n = 1.0 \]
+This guarantees that variant chunks of core files receive the maximum possible authored weight when scoring against the remaining token budget \(\tau_{\mathcal{V}}\).
+
+## 6. Token Budget Safety Bounds
+
+Adversarial or malformed files containing excessively large constraint blocks could violate the strict prompt limits defined by the host. The system enforces split load-time bounds:
+
+For Hard Invariants (\(\alpha_1\)):
+\[ \sum_{n \in \mathcal{I}_{1d}} \mathrm{toks}(n) \le \alpha_1 \tau \implies \text{fast-fail and reject agent load if exceeded} \]
+
+For Soft Invariants (\(\alpha_2\)):
+\[ \sum_{n \in \mathcal{I}_{2d}} \mathrm{toks}(n) \le \alpha_2 \tau \implies \text{truncate by position if exceeded} \]
+
+*Cumulative Verification Proof:* Let the total reserved invariant budget fraction be \(\alpha\), where \(\alpha_1 + \alpha_2 \le \alpha\). If both independent enforcement bounds are satisfied, then:
+\[ \sum_{n \in \mathcal{I}_{1d}} \mathrm{toks}(n) + \sum_{n \in \mathcal{I}_{2d}} \mathrm{toks}(n) \le \alpha_1 \tau + \alpha_2 \tau = (\alpha_1 + \alpha_2)\tau \le \alpha \tau \]
+This mathematically guarantees the overall token budget \(\tau\) is never breached by the combined invariant sets.
+
+Under the unified assembly contract in [`mathematics-v2.md`](./mathematics-v2.md)
+section 7.8 and [`continuity.md`](./continuity.md), these authored bounds are
+combined with a separate recent-tail target fraction \(\beta\). The runtime
+therefore treats the tiers with the following precedence:
+
+1. **Tier 1 / Hard invariants** must fit their startup reservation \(\alpha_1\tau\).
+2. **Mandatory recent tail** must preserve at least the minimum raw suffix \(T_{\mathrm{base}}\).
+3. **Tier 2 / Soft invariants** are injected by longest-prefix truncation under the effective budget
+   \[
+   \tau_{\mathcal{I}_2}^{\mathrm{eff}}=
+   \min\!\left(\alpha_2\tau,\,
+   \tau-\tau_{\mathcal{I}_1}-\mathrm{toks}(T_{\mathrm{base}})\right)
+   \]
+4. **Variant lore** competes only for the final residual budget after Tier 1,
+   the admitted Tier 2 prefix, and the exact recent tail are accounted for.
+
+This makes \(\mathcal{I}_1\) and the minimum continuity suffix hard
+constraints, while keeping \(\mathcal{I}_2\) order-preserving but elastic.
+
+## 7. The Document-Addressed Cache (\(\Psi\)) and Runtime Implications
+
+The AST extraction, Deontic bigram evaluation, and partition logic are purely deterministic functions of \(d_{\mathrm{raw}}\). To prevent \(O(N)\) recomputation on every conversational turn, the system maintains a document-addressed cache:
+
+\[ \Psi: \text{hash}(d_{\mathrm{raw}}, \text{tokenizer\_id}) \to \{\mathcal{I}_{1d}, \mathcal{I}_{2d}, \mathcal{V}_d, \text{budget}\} \]
+
+Because the token estimator function \(\lceil \frac{|t|}{\chi(t)} \rceil\) depends on the active model tokenizer, \(\text{tokenizer\_id}\) is embedded in the hash key. 
+
+At runtime:
+1. **Tier 1 (\(\mathcal{I}_{1d}\))** is injected via an \(O(1)\) memory copy.
+2. **Tier 2 (\(\mathcal{I}_{2d}\))** is evaluated via an \(O(|\mathcal{I}_{2d}|)\) prefix sum to enforce position truncation under \(\tau_{\mathcal{I}_2}^{\mathrm{eff}}\).
+3. **Tier 0 (\(\mathcal{V}_d\))** bypasses re-parsing and feeds into the semantic Pass 1 vector retrieval only after the continuity layer removes the exact recent tail into \(T_{\mathrm{recent}}\), leaving \(\mathcal{V}_{\mathrm{rest}}\).

package/docs/ast.md

@@ -0,0 +1,70 @@
+# TITLE: Mathematical Reference - Abstract Syntax Tree (AST) Partitioning
+
+Historical note: this document is preserved to show the project's design
+evolution. The reviewed authoritative AST reference is
+[`ast-v2.md`](./ast-v2.md).
+
+This document formalizes the heuristic mapping of user-authored Markdown documents (such as `agents.md` and `souls.md`) into the partitioned sets required by the two-pass retrieval system. It serves as the bridge between raw text ingestion and the rigorous corpus decomposition defined in `mathematics-v2.md` Section 7.2.
+
+The design goal is to extract rigid behavioral rules (the invariant set) from contextual lore (the variant set) automatically, using structural types as a mathematically stable proxy for user intent. 
+
+## 1. The Document AST and Node Extraction
+
+Let a raw Markdown document $d_{\mathrm{raw}}$ be parsed into an Abstract Syntax Tree $\mathcal{T}$. 
+Let $E: \mathcal{T} \to N_d$ be an extraction function that flattens the tree into an ordered sequence of semantic leaf nodes $N_d = \langle n_1, n_2, \dots, n_k \rangle$. 
+
+Each node $n_i \in N_d$ has an associated structural kind assigned by the parser (e.g., `yuin/goldmark`), mapped by the function $\kappa: N_d \to K$, where $K$ is the set of supported Markdown node types:
+\[ K = \{ \text{Paragraph}, \text{List}, \text{Blockquote}, \text{YAMLFrontmatter}, \text{Heading}, \dots \} \]
+
+*Implemented in `sidecaragentparser.go`.*
+
+## 2. The Structural Indicator Function $\iota$
+
+To avoid document-level monolithic injection, we redefine the invariant membership predicate from `mathematics-v2.md` Section 7.2 at the node level. 
+
+Let $K_{\mathcal{I}} \subset K$ be the subset of node kinds structurally correlated with hard constraints, core directives, and programmatic definitions:
+\[ K_{\mathcal{I}} = \{ \text{List}, \text{Blockquote}, \text{YAMLFrontmatter} \} \]
+
+We define the structural indicator function $\iota: N_d \to \{0,1\}$ as:
+\[
+\iota(n) = \begin{cases} 
+1 & \text{if } \kappa(n) \in K_{\mathcal{I}} \\ 
+0 & \text{otherwise} 
+\end{cases}
+\]
+
+**Note on structural proxy limits:** This heuristic relies entirely on the probability that human authors place absolute rules in lists/frontmatter and narrative lore in standard paragraphs. It is mathematically blind to the semantic meaning of the text.
+
+## 3. Corpus Decomposition and Set Integration
+
+For any document $d \in \mathbf{D}_{\text{agents}} \cup \mathbf{D}_{\text{souls}}$, the node set $N_d$ is partitioned cleanly:
+- **The Core Directives (Invariant):** $\mathcal{I}_d = \{ n \in N_d \mid \iota(n) = 1 \}$
+- **The Contextual Lore (Variant):** $\mathcal{V}_d = \{ n \in N_d \mid \iota(n) = 0 \}$
+
+This guarantees partition integrity:
+\[ \mathcal{I}_d \cup \mathcal{V}_d = N_d \quad \text{and} \quad \mathcal{I}_d \cap \mathcal{V}_d = \emptyset \]
+
+These sets feed directly into the global corpus partitioning:
+\[ \mathcal{I} = \bigcup_{d} \mathcal{I}_d \qquad \mathcal{V} = \mathbf{D}_{\text{standard}} \cup \left( \bigcup_{d} \mathcal{V}_d \right) \]
+
+By definition, any chunk $n \in \mathcal{I}_d$ inherits the hard startup guarantee from `mathematics-v2.md` Section 7.1:
+\[ \iota(n)=1 \implies G(q,n)=1 \quad \forall q \in \mathbf{Q} \]
+
+## 4. Authored Authority Boost for Variant Lore
+
+Chunks in $\mathcal{V}_d$ (such as standard paragraph nodes) lose their invariant guarantee and must survive the Pass 1 coarse semantic filter defined in `mathematics-v2.md` Section 7.4.
+
+To ensure that agent-specific lore outcompetes general conversational memory during Pass 2, we enforce a strict authority override. For all $n \in \mathcal{V}_d$ extracted from a core identity document:
+\[ a_n = 1.0 \]
+
+Following the authority weight convex combination $d_{\omega}$ from `mathematics-v2.md` Section 7.3, this guarantees that variant chunks of core files receive the maximum possible authored weight when scoring against the remaining token budget $\tau_{\mathcal{V}}$.
+
+## 5. Token Budget Safety Bounds
+
+Because invariants bypass all truncation (Section 7.8), an adversarial or malformed file containing an excessively large list block could violate the token budget:
+\[ \sum_{n \in \mathcal{I}_d} \mathrm{toks}(n) > \tau \]
+
+Therefore, the system must enforce a load-time safety bound on the extracted AST invariants:
+\[ \tau_{\text{max\_invariant}} \le \alpha \tau \quad \text{where } \alpha \in (0, 1) \]
+
+If parsing yields an $\mathcal{I}_d$ that exceeds $\alpha \tau$ (e.g., $\alpha = 0.4$, reserving 60% of context for variant history and tools), the parser must fast-fail and reject the agent load. This protects the runtime invariants dictated in `mathematics-v2.md` Section 7.10 from mathematically impossible token fits.

package/docs/compaction-evaluation.md

@@ -0,0 +1,182 @@
+# Compaction Evaluation
+
+This document records the first local evaluation pass for the Nomic-first
+compaction confidence design.
+
+The goal of the experiment was to compare:
+
+- raw ONNX T5 decoder confidence
+- Nomic-space preservation metrics
+- the planned hybrid confidence model with a hard preservation gate
+
+The evaluation harness lives in:
+
+- `sidecar/cmd/eval_compaction`
+
+It runs real local models:
+
+- Nomic `nomic-embed-text-v1.5` for embedding-space evaluation
+- ONNX T5-small for optional abstractive summarization
+
+## Why This Exists
+
+The compaction system previously trusted T5 decoder confidence alone:
+
+```text
+conf_t5(s, C) = exp(mean log p(token_i | token_<i, C))
+```
+
+That quantity measures decoder self-consistency, not semantic preservation in
+the retrieval geometry used by the vector store.
+
+The new design evaluates every summary back in Nomic space:
+
+```text
+Q_align(s, C) = cos(E(s), mu_C)
+Q_cover(s, C) = mean_i max(0, cos(E(s), E(t_i)))
+conf_nomic(s, C) = clamp01((Q_align + Q_cover) / 2)
+```
+
+And then applies:
+
+```text
+if Q_align < tau_preserve:
+  reject abstractive summary and fall back to extractive
+
+confidence =
+  conf_nomic                                  for extractive
+  lambda * conf_nomic + (1 - lambda) * conf_t5 for T5 summaries
+```
+
+with the current implementation constants:
+
+- `tau_preserve = 0.65`
+- `lambda = 0.8`
+
+## Baseline Corpus
+
+The current real-model pass uses 17 fixed synthetic clusters:
+
+- 5 normal engineering-memory clusters
+- 12 adversarial clusters designed to stress abstractive faithfulness
+
+The adversarial set included:
+
+- conflicting subsystem failures
+- dense Go code and test logic
+- four-way architectural decision bundles
+- many-number and threshold-heavy cases
+- continuity vs progress tension
+- cross-domain product/math/infra mixtures
+- token-budget contract distinctions
+- conflicting proposed resolutions vs the actual root cause
+- long noisy code-trace clusters with one decisive invariant
+- topic-shift clusters that tempt generic summaries
+- near-duplicate threshold statements from different subsystems
+
+## Results
+
+### Core Cases
+
+| case | raw_conf | align | cover | final_conf | delta_conf |
+|---|---:|---:|---:|---:|---:|
+| auth_migration | 0.8501 | 0.9183 | 0.8342 | 0.8710 | +0.0209 |
+| compaction_boundary | 0.6894 | 0.7983 | 0.7216 | 0.7458 | +0.0564 |
+| gating_math | 0.7790 | 0.9167 | 0.8285 | 0.8539 | +0.0748 |
+| release_pipeline | 0.8859 | 0.9697 | 0.8729 | 0.9142 | +0.0283 |
+| adversarial_multi_fact | 0.8545 | 0.9052 | 0.7893 | 0.8487 | -0.0058 |
+
+### Adversarial Cases
+
+| case | raw_conf | align | cover | final_conf | delta_conf |
+|---|---:|---:|---:|---:|---:|
+| adversarial_conflicting_errors | 0.8540 | 0.8579 | 0.7440 | 0.8116 | -0.0424 |
+| adversarial_dense_go_code | 0.8945 | 0.9167 | 0.8212 | 0.8741 | -0.0205 |
+| adversarial_four_way_decision_bundle | 0.8451 | 0.8651 | 0.7598 | 0.8190 | -0.0261 |
+| adversarial_many_numbers | 0.6915 | 0.8854 | 0.7900 | 0.8084 | +0.1170 |
+| adversarial_boundary_vs_progress | 0.7824 | 0.8993 | 0.8109 | 0.8406 | +0.0581 |
+| adversarial_cross_domain_mix | 0.5240 | 0.8099 | 0.7327 | 0.7218 | +0.1978 |
+| adversarial_token_budget_rules | 0.7938 | 0.9060 | 0.8249 | 0.8511 | +0.0573 |
+| adversarial_conflicting_resolutions | 0.8600 | 0.9284 | 0.8560 | 0.8858 | +0.0258 |
+| adversarial_long_noisy_code_trace | 0.8144 | 0.8565 | 0.7893 | 0.8212 | +0.0068 |
+| adversarial_topic_shift_generic_bait | 0.8860 | 0.9166 | 0.8209 | 0.8722 | -0.0138 |
+| adversarial_near_duplicate_thresholds | 0.8731 | 0.9123 | 0.8266 | 0.8702 | -0.0029 |
+
+## What We Learned
+
+### 1. T5 and Nomic are locally compatible
+
+Every evaluated case produced:
+
+```text
+Q_align > 0.65
+```
+
+So the hard preservation gate did not trigger on the initial corpus. This is
+useful evidence that the local T5 summaries are generally pointing in the same
+semantic direction as the source cluster in Nomic space.
+
+### 2. The new math improves confidence grounding
+
+The hybrid model changed confidence more often than it changed summary text.
+
+This is still a meaningful result:
+
+- positive deltas mean Nomic-space preservation validated summaries that T5
+  scored pessimistically
+- negative deltas mean Nomic-space preservation penalized summaries that T5
+  scored too generously
+
+The largest rescue was:
+
+- `adversarial_cross_domain_mix`: `0.5240 -> 0.7218` (`+0.1978`)
+
+The largest penalty was:
+
+- `adversarial_conflicting_errors`: `0.8540 -> 0.8116` (`-0.0424`)
+
+So even without fallback, the confidence signal is more retrieval-aware than the
+old T5-only design.
+
+### 3. Harsher corpus plus threshold sweep sharpened the evidence
+
+Even after expanding the corpus to 17 cases, the shipped gate still did not
+trip:
+
+```text
+tau_preserve = 0.65  -> 0 trips
+tau_preserve = 0.75  -> 0 trips
+tau_preserve = 0.85  -> 2 trips
+```
+
+The two cases that fall below `0.85` are:
+
+- `compaction_boundary`
+- `adversarial_cross_domain_mix`
+
+So the section-5 preservation machinery is now evidenced in two ways:
+
+- unit tests prove the hard fallback path when `Q_align < tau_preserve`
+- real-model threshold sweeps show where the current corpus begins to stress
+  geometric drift, even though the shipped `0.65` threshold remains conservative
+
+This means the earlier evidence gap has narrowed: the corpus is now harsh enough
+to differentiate thresholds and expose weaker cases, even if it still does not
+force fallback at the default gate.
+
+Remaining interpretation questions are now about calibration, not about whether
+the gate machinery exists or whether the evaluation corpus can separate stronger
+and weaker summaries.
+
+## Current Interpretation
+
+The preservation gate is not decorative, but its first practical value is
+confidence correction rather than frequent fallback.
+
+That is still a win:
+
+- T5 remains the lightweight local decoder
+- Nomic remains the canonical retrieval geometry
+- compaction confidence is now judged in the same space retrieval uses
+
+This is the mathematically coherent compromise for a stable shippable plugin.