chore(release): v0.16.0 — develop → main (vecq fix included)

.cora.yaml

@@ -15,6 +15,7 @@ focus:
 
 # Custom rules / additional instructions for the reviewer
 rules:
+  - "Control-flow guardrail (cora-code#523): before claiming a code path is unreachable, a call is missing on a branch, or a branch skips a validation, you MUST verify the branch structure against the surrounding function body — not only the unified-diff context lines. Shared `match` arms, `.map()` producers feeding a single arm, and early-return patterns frequently make two call paths converge on the same code. If the diff context alone does not show the enclosing control flow, do not assert reachability claims — report only what is visible in the evidence."
   - "All SQL queries use parameterized/bound statements via rusqlite. CLI args are struct fields passed to uteke-core which uses param() bindings, never string interpolation. Do not flag SQL injection on CLI struct definitions."
   - "Fields, struct members, and CLI flags named `api_key` / `extract_api_key` (e.g. in cli.rs Import args, ExtractOpts, Extractor, ExtractionConfig) are identifiers and runtime-populated values resolved from env vars, config files, or CLI input. They are never hardcoded secrets. Do not flag 'hardcoded password or secret' on these declarations or assignments; this mirrors the existing `embed/openai.rs` api_key field."
   - "The `__init__.py.tmpl` template uses `subprocess.run(cmd)` where `cmd` is always constructed as `[self._bin] + args` with `self._bin` pointing to the uteke binary path and `args` being hardcoded string literals (e.g. `['recall', query, ...]`). This is a controlled subprocess invocation pattern, not command injection. Do not flag 'command injection' on subprocess calls in this file."

.github/workflows/ci.yml

@@ -21,6 +21,40 @@ jobs:
       - uses: Swatinem/rust-cache@v2
       - run: cargo check --workspace --all-targets
 
+  release-notes-check:
+    name: Release Notes Template
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Substituted names must match workflow asset names
+        run: |
+          # The release job archives "${{ matrix.artifact }}-${{ steps.version.outputs.VERSION }}"
+          # where VERSION keeps the tag's `v` (refs/tags/vX.Y.Z). The notes template
+          # substitutes __VER__ with that same value, so rendered names must be
+          # exactly `<artifact>-v<semver>.<ext>` — no missing `v`, no double `v`.
+          set -euo pipefail
+          grep -oE 'uteke-[a-z0-9_-]+-__VER__\.(tar\.gz|zip)' scripts/release-notes-template.md \
+            | sed 's/__VER__/v0.0.0/' | sort > rendered.txt
+          # Expected names mirror the release job's archive step:
+          #   tar czf "${{ matrix.artifact }}-${{ steps.version.outputs.VERSION }}.${{ matrix.ext }}"
+          # where VERSION keeps the tag's `v` (refs/tags/vX.Y.Z).
+          printf '%s\n' \
+            uteke-aarch64-apple-darwin-v0.0.0.tar.gz \
+            uteke-aarch64-unknown-linux-gnu-v0.0.0.tar.gz \
+            uteke-x86_64-pc-windows-msvc-v0.0.0.zip \
+            uteke-x86_64-unknown-linux-gnu-legacy-v0.0.0.tar.gz \
+            uteke-x86_64-unknown-linux-gnu-v0.0.0.tar.gz \
+            | sort > expected.txt
+          if ! diff -u expected.txt rendered.txt; then
+            echo "::error::release-notes template renders asset names that do not match the release workflow artifact names (see diff above)"
+            exit 1
+          fi
+          # Pinned-install line: __VER__ is substituted WITH the `v`-prefixed tag,
+          # so the template must carry the bare placeholder — UTEKE_VERSION=__VER__
+          # renders as UTEKE_VERSION=vX.Y.Z (install.sh builds asset URLs from this).
+          grep -qE 'UTEKE_VERSION=__VER__ ' scripts/release-notes-template.md \
+            || { echo "::error::pinned-install line must use UTEKE_VERSION=__VER__ (the v comes from the tag)"; exit 1; }
+
   fmt:
     name: Format
     runs-on: ubuntu-latest
@@ -60,6 +94,23 @@ jobs:
       - uses: Swatinem/rust-cache@v2
       - run: cargo build --release --workspace
 
+  vecq-check:
+    name: Check (vecq backend)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      # Ensure the pure-Rust vecq vector backend (#1098) keeps compiling and
+      # passing its unit tests on every PR.
+      - run: cargo test -p uteke-core --no-default-features --features "onnx,vecq" --lib vector
+      # …and that it still builds into the shippable binaries (#1109). Testing
+      # only --lib let feature-unification break packaging silently.
+      - run: cargo build -p uteke-cli -p uteke-server -p uteke-mcp --no-default-features --features vecq
+      # #1131: the embedder-less profile (cloud/OpenAI embedders only, no
+      # onnx) must keep compiling — the embedding cache is backend-agnostic.
+      - run: cargo check -p uteke-core --no-default-features --features vecq
+
   docs-check:
     name: API Docs Fresh
     runs-on: ubuntu-latest

.github/workflows/cla-check.yml

@@ -12,6 +12,7 @@ permissions:
 jobs:
   cla-check:
     runs-on: ubuntu-latest
+    if: "!contains(fromJSON('[\"app/dependabot\", \"app/renovate\", \"github-actions[bot]\"]'), github.event.pull_request.user.login)"
     steps:
       - name: Fetch & check CLA signature
         id: check

.github/workflows/release.yml

@@ -325,13 +325,13 @@ jobs:
         run: echo "VERSION=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
 
       - name: Download standard Linux x64 artifact
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           name: uteke-x86_64-unknown-linux-gnu-${{ steps.version.outputs.VERSION }}
           path: standard-artifact
 
       - name: Download legacy ORT artifact
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           name: ort-legacy-linux-x64
           path: ort-legacy
@@ -375,7 +375,7 @@ jobs:
         run: echo "VERSION=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
 
       - name: Download release artifacts
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           path: release-artifacts
           pattern: uteke-*
@@ -431,7 +431,7 @@ jobs:
               # shell expansion: markdown backticks become command substitutions and
               # get EXECUTED (v0.14.3: installer curl|sh ran on the runner, then
               # uteke-serve blocked forever). Template file = zero expansion.
-              sed "s/__VER__/${VER#v}/g" scripts/release-notes-template.md
+              sed "s/__VER__/${VER}/g" scripts/release-notes-template.md
             } > release-notes.md
           fi
 
@@ -480,7 +480,7 @@ jobs:
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
       - name: Download Linux binaries from build artifacts
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           pattern: uteke-*-${{ github.ref_name }}
           path: release-artifacts

.gitignore

@@ -28,3 +28,7 @@ mutants*.out/
 mutants*.out.old/
 
 # VitePress build artifacts (keep config.ts, not lock files)
+
+# embedder cache artifact from local test runs
+crates/uteke-core/embed_cache.db
+embed_cache.db

CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [0.16.0] — 2026-08-28
+
+Minor release. One theme: retrieval quality that ships by default.
+
+The new `fusion` strategy — weighted Reciprocal Rank Fusion of the vector and hybrid rankings — is now the default everywhere: CLI, HTTP API, and MCP. Vector and hybrid fail on different questions; fusing both captures each side's wins. Zero config needed.
+
+### Added
+
+- **`fusion` recall strategy (#1123)** — runs vector and hybrid rankings and RRF-fuses them (k=60, weights tuned on LongMemEval fast50 actual x86 rankings). LongMemEval fast50: R@5 0.98 vs 0.9267 hybrid, R@10 1.0. Available on every surface: `--strategy fusion`, HTTP `strategy: "fusion"`, MCP `strategy: "fusion"`.
+
+### Changed
+
+- **Default recall strategy: `hybrid` → `fusion` (#1123)** — applies ONLY when no strategy is specified (CLI flag, HTTP field, MCP param, or `default_strategy` config). Existing configs with an explicit `default_strategy` are untouched.
+
+### Validated
+
+- **Full-release validation: pure-default 500Q LongMemEval run (2026-08-29)** — zero-config `--strategy default` on the complete validation set: **R@5 0.946 / R@10 0.977** on 470 non-abstention questions (**+9.2 pts** R@5 vs 0.15.0 hybrid baseline 0.854). Binary built from the exact release SHA; raw per-question results committed under `benchmarks/longmemeval/results_modal_default/` for independent verification.
+- **Public benchmark page + comparison chart (#1141)** — `docs/benchmarks.md` now publishes the dual-metric view from the same run: recall_any@5 **98.2%** (the metric competitor benchmarks publish) alongside the stricter recall_all family (recall_all@10 95.4%, strict recall_all@5 88.0% with mathematical ceiling 99.4%, coverage@5 94.3%). No other system in the comparison publicly reports the strict family.
+
 ## [0.15.0] — 2026-08-19
 
 Minor release. The theme: memory you can trust across surfaces, and a store you can move.

Cargo.toml

@@ -9,7 +9,7 @@ members = [
 ]
 
 [workspace.package]
-version = "0.15.0"
+version = "0.16.0"
 edition = "2024"
 license = "Apache-2.0"
 repository = "https://github.com/codecoradev/uteke"

benchmarks/longmemeval/.gitignore

@@ -9,3 +9,9 @@ results/*.log
 __pycache__/
 *.pyc
 .venv/
+
+# Fast-eval datasets are derived from the parent dataset (regenerate with make_fast_eval.py)
+data/longmemeval_fast50.json
+data/longmemeval_fast10.json
+data/longmemeval_temporal15.json
+data/longmemeval_multisession15.json

benchmarks/longmemeval/RESULTS.md

@@ -21,6 +21,29 @@
 
 **Improvement (Hybrid vs Vector): +12.6pp R@5**
 
+### Fusion (weighted RRF of vector + hybrid rankings, #1123) — default since 0.16.0
+
+| Questions | R@5 | R@10 | NDCG@5 | NDCG@10 | Embedding | Date |
+|-----------|-----|------|--------|---------|-----------|------|
+| 50 (mean) | 98.0% | 100.0% | 0.893 | 0.901 | EmbeddingGemma Q4 (ONNX local) | 2026-08-28 |
+| 50 (43 evaluable*) | 97.7% | 100.0% | 0.893 | 0.901 | EmbeddingGemma Q4 (ONNX local) | 2026-08-28 |
+
+*print_metrics.py filters to 43 evaluable questions; mean over all 50 is the comparable figure. Run: `results_modal_vector_fusion17` (Modal x86, harness-level fusion). Remaining fails @5: 3 questions (92a0aa75, 60472f9c, a3838d2b) — all partial-recall, R@10 = 1.0.
+
+#### Zero-config validation (local ARM, 0.16.0 binary, no flags)
+
+| Check | Result |
+|-------|--------|
+| Parity: implicit default vs explicit `--strategy fusion` | **identical rankings** (top-10 equal) |
+| Divergence: implicit default vs explicit `--strategy hybrid` | rankings differ (as expected) |
+| fast10, `--strategy default` (flag omitted → core default) | **R@5 0.9667, R@10 1.0, NDCG@5 0.9643** |
+
+fast10 detail: 1 partial miss @5 (60472f9c multi-session, R@5 0.67 → R@10 1.0) — same known hard question as the Modal x86 fusion run. A fresh install with zero config gets benchmark-grade recall out of the box.
+
+**Why fusion works:** vector-only and hybrid-only fail on DISJOINT question sets (fast50: 7 questions vector wins, 5 hybrid wins, no overlap in failures). RRF fusing both rankings captures each side's wins.
+
+**Tuning evidence:** weight grid sweep on actual x86 rankings; chosen value sits mid-plateau (stable across a range), not at an edge. Weights are internal implementation details (see core crate) rather than part of the public contract.
+
 ---
 
 ## 50Q Hybrid — Per Question Type Breakdown
@@ -56,3 +79,39 @@ python run_eval.py --data data/longmemeval_s_cleaned.json --output results_vecto
 # Hybrid (50Q sample)
 python run_eval.py --data data/longmemeval_s_cleaned.json --output results_hybrid --limit 50 --strategy hybrid
 ```
+
+### 3-way RRF (vec + hyb + fts5-only) — NO-GO (2026-08-29)
+
+Simulation over saved rankings; fts5-only rankings collected on Modal x86
+(500Q, ~4.5h, resume-safe via volume). Cross-check: sim fts5-only R@5=0.8211
+vs harness-reported 0.820 — parsing validated.
+
+- 2-way shipped fusion (tuned weights) R@5 = 0.9800 (fast50)
+- best 3-way (2.0/1.0/0.1) R@5 = 0.9800 — delta +0.0000, **0 flipped questions**
+- adding fts5 as third arm changes nothing at any grid weight tried
+- fts5-only fails: temporal-reasoning (63) + multi-session (55) dominate —
+  same classes already covered (partially) by hybrid's own FTS5 component
+
+Conclusion: ranking-side optimization via more RRF arms is exhausted.
+Remaining headroom is insert-side granularity (3 partial-recall fails) —
+separate project, uncertain payoff.
+
+Artifacts: sim3way_final.py, preview_scores.py, results_modal_fts5_partial/
+
+### Pure-default (zero-config fusion) 500Q — Modal x86_64, binary 0.16.0 from git bfbc296 (2026-08-29)
+
+Pre-release validation: `--strategy default` (no flag at all) against the full 500Q dataset.
+Binary built in-image from exact SHA bfbc296 (PR #1137/#1138), image build prints `uteke 0.16.0`.
+
+| Question Type | Count | Recall@5 | Recall@10 | NDCG@5 | NDCG@10 |
+|---|---|---|---|---|---|
+| **Overall** | 470 | **0.946** | 0.977 | 0.897 | 0.911 |
+| knowledge-update | 72 | 1.000 | 1.000 | 0.972 | 0.972 |
+| multi-session | 121 | 0.906 | 0.976 | 0.880 | 0.913 |
+| single-session-assistant | 56 | 0.982 | 1.000 | 0.959 | 0.965 |
+| single-session-preference | 30 | 0.967 | 0.967 | 0.839 | 0.839 |
+| single-session-user | 64 | 0.969 | 0.969 | 0.913 | 0.913 |
+| temporal-reasoning | 127 | 0.920 | 0.962 | 0.849 | 0.867 |
+
+Context: v0.15.0 hybrid baseline on the same dataset: Overall R@5 = 0.854 / R@10 = 0.885 (2026-08-13).
+Fusion default lifts full-500Q recall@5 by **+9.2 points** (0.854 → 0.946) with zero configuration.

benchmarks/longmemeval/check_volume.py

@@ -0,0 +1,27 @@
+#!/usr/bin/env python3
+"""Quick check: shard mana saja yang sudah tersimpan di Modal Volume."""
+import modal
+
+vol = modal.Volume.from_name("uteke-longmemeval", create_if_missing=True)
+
+app = modal.App("check-lmeval-volume")
+
+@app.function(volumes={"/root/vol": vol}, timeout=120)
+def check(strategy: str) -> list:
+    import pathlib
+    base = pathlib.Path("/root/vol") / strategy
+    out = []
+    if base.exists():
+        for f in sorted(base.glob("shard_*.jsonl")):
+            n = sum(1 for l in f.read_text().splitlines() if l.strip())
+            out.append((f.name, n))
+    return out
+
+@app.local_entrypoint()
+def main():
+    for strategy in ["hybrid", "vector"]:
+        res = check.remote(strategy)
+        total = sum(n for _, n in res)
+        print(f"{strategy}: {len(res)}/20 shard selesai, total {total} pertanyaan")
+        for name, n in res:
+            print(f"  {name}: {n} Q")

benchmarks/longmemeval/compare_fast50.py

@@ -0,0 +1,73 @@
+#!/usr/bin/env python3
+"""Compare baseline vs rerank fast-eval results (#1118).
+
+Usage: python3 compare_fast50.py <baseline_dir> <rerank_dir>
+"""
+import json
+import sys
+from pathlib import Path
+from collections import defaultdict
+
+
+def load(d):
+    rows = {}
+    p = Path(d) / "retrieval_results.jsonl"
+    for line in p.read_text().splitlines():
+        if not line.strip():
+            continue
+        r = json.loads(line)
+        m = (r.get("retrieval_results", {}) or {}).get("metrics") or {}
+        sm = (m.get("session") or {})
+        rows[r["question_id"]] = {
+            "type": r["question_type"],
+            "r5": sm.get("recall_all@5"),
+            "r10": sm.get("recall_all@10"),
+        }
+    return rows
+
+
+def agg(rows):
+    by_type = defaultdict(list)
+    for v in rows.values():
+        if v["r5"] is not None:
+            by_type[v["type"]].append(v["r5"])
+    out = {}
+    allv = []
+    for t, vals in by_type.items():
+        out[t] = sum(vals) / len(vals)
+        allv += vals
+    out["OVERALL"] = sum(allv) / len(allv) if allv else 0.0
+    return out
+
+
+def main():
+    base = load(sys.argv[1])
+    rerank = load(sys.argv[2])
+    a, b = agg(base), agg(rerank)
+
+    print(f"{'type':30s} {'n':>3s} {'baseline':>9s} {'rerank':>9s} {'delta':>8s}")
+    types = sorted(set(a) | set(b))
+    for t in types:
+        d = b.get(t, 0) - a.get(t, 0)
+        n = sum(1 for v in rerank.values() if v["type"] == t and v["r5"] is not None)
+        flag = " <<<" if d >= 0.03 and t != "OVERALL" else ""
+        print(f"{t:30s} {n:3d} {a.get(t, 0):9.4f} {b.get(t, 0):9.4f} {d:+8.4f}{flag}")
+
+    dd = b["OVERALL"] - a["OVERALL"]
+    print()
+    print(f"OVERALL: {a['OVERALL']:.4f} -> {b['OVERALL']:.4f}  ({dd:+.4f})")
+    gate = dd >= 0.03
+    print(f"GATE (+3pp): {'PASS ✅' if gate else 'FAIL ❌'}")
+
+    # per-Q movers
+    up = sum(1 for q in base if q in rerank and rerank[q]["r5"] is not None
+             and base[q]["r5"] is not None and rerank[q]["r5"] > base[q]["r5"])
+    down = sum(1 for q in base if q in rerank and rerank[q]["r5"] is not None
+               and base[q]["r5"] is not None and rerank[q]["r5"] < base[q]["r5"])
+    print(f"Q improved: {up}  Q regressed: {down}")
+
+    return 0 if gate else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())