feat: bitemporal recall quality evidence

Merges verified PR #88 after all required checks passed and review threads were resolved.

Author: Coding-Dev-Tools

.claude-plugin/skill-assets.sha256

@@ -1,6 +1,6 @@
 a972f840492bf1041f1e9525452127a6d5d117d5fcd231230b1d2ae656d85d13  .claude-plugin/marketplace.json
 dba3e0713559b267581f45cfd5907aae4689df77790b02bbcf22309d9ffa73ef  .claude-plugin/plugin.json
-89bf2728e44a3c877e31982d387fcfab10fbe065eb6441b2792375ca5105c07c  skills/engraphis-memory/SKILL.md
-a295b0448e2ff372ddd8ea4e0bc8dc53f3d4bd56ff1fbd0d88cf4b6179511ce1  skills/engraphis-memory/references/CONVENTIONS.md
+656caf07c9064b219eb974e018180e6a7a88f2c058fb1b1c6a8a36074d67e9cc  skills/engraphis-memory/SKILL.md
+9751b6e7310151c14e6bb7f5d683943a53a95951ff207876053d082e65eecfd5  skills/engraphis-memory/references/CONVENTIONS.md
 45f4b4ad9dbfd39f2b377083d9b3eec5eed7cba7cb8fa139e3f420bdd6105343  skills/engraphis-memory/references/SCOPING.md
-12980f16face01fee5f65cde0c4aa2297200b2252861b341ec7762e32600da60  skills/engraphis-memory/references/TOOLS.md
+dc83c48d1a57122e7b58da29d32ae3b8ebd4ffff0b6d0570a8833e920e365109  skills/engraphis-memory/references/TOOLS.md

.github/workflows/ci.yml

@@ -161,9 +161,10 @@ jobs:
         run: |
           python -m pip install --upgrade pip build pip-audit
           python -m build
+          python scripts/verify_distribution_contents.py dist/*
           python -m venv .audit-venv
           .audit-venv/bin/python -m pip install --upgrade "pip>=26.1.2" "setuptools>=83"
           .audit-venv/bin/python -m pip install dist/*.whl
           AUDIT_SITE=$(.audit-venv/bin/python -c "import site; print(site.getsitepackages()[0])")
           python -m pip_audit --path "$AUDIT_SITE"
-          .audit-venv/bin/python -c "import engraphis; print('wheel import OK')"
+          .audit-venv/bin/python -c "import engraphis, eval.harness; print('wheel imports OK')"

.github/workflows/release.yml

@@ -61,13 +61,18 @@ jobs:
           ruff check .
           python -c "import fastapi, httpx, mcp, multipart, pydantic, uvicorn"
           python -m pytest -o addopts="" tests/ -q -rs
+          python -m pytest -o addopts="" tests/test_public_research_boundary.py -q
+          python -m pytest -o addopts="" tests/test_compact_recall.py tests/test_eval_performance.py -q
+          python -m pytest -o addopts="" tests/test_eval_harness.py tests/test_benchmark_evidence.py -q
           python -m eval.harness --dataset eval/datasets/sample.jsonl --k 5
           python -m eval.harness --dataset eval/datasets/codemem.jsonl --k 5
           python -m eval.ablation
           python -m pip_audit --local
 
       - name: Build source and universal wheel distributions
-        run: python -m build
+        run: |
+          python -m build
+          python scripts/verify_distribution_contents.py dist/*
 
       - name: Validate distributions
         run: python -m twine check dist/*
@@ -134,7 +139,7 @@ jobs:
           npm ci
           npx playwright install --with-deps chromium
       - name: Playwright desktop/mobile, keyboard, CSP, console, and axe checks
-        run: npx playwright test
+        run: npm run test:e2e
 
   docker-smoke:
     name: Production image release gate
@@ -176,9 +181,58 @@ jobs:
         if: always()
         run: docker rm -f engraphis-release || true
 
+  release-evidence:
+    name: Generate public release evidence
+    needs: [build, python-matrix, browser-accessibility, docker-smoke]
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.11"
+      - name: Install SBOM generator and project dependencies
+        run: >-
+          python -m pip install --upgrade "pip>=26.1.2" "setuptools>=83"
+          cyclonedx-bom==7.3.0 ".[all,test]"
+      - name: Download distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Generate evidence and reproducible SBOM after all release gates
+        shell: bash
+        run: |
+          mkdir release-evidence
+          sbom="release-evidence/engraphis-${GITHUB_REF_NAME#v}.cdx.json"
+          cyclonedx-py environment --output-reproducible --of JSON --pyproject pyproject.toml -o "$sbom"
+          python scripts/release_evidence.py --dist dist --commit "$GITHUB_SHA" \
+            --tag "$GITHUB_REF_NAME" \
+            --sbom "$sbom" \
+            --verified-check ruff \
+            --verified-check pytest \
+            --verified-check privacy-boundary \
+            --verified-check token-efficiency \
+            --verified-check benchmark-schema-evidence \
+            --verified-check browser-e2e \
+            --verified-check dependency-audit \
+            --verified-check container-smoke \
+            --verified-check retrieval-sample \
+            --verified-check retrieval-codemem \
+            --verified-check retrieval-ablation \
+            --output release-evidence/release-evidence.json
+      - name: Store public release evidence
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: public-release-evidence
+          path: release-evidence/
+
   publish:
     name: Publish to PyPI
-    needs: [build, python-matrix, browser-accessibility, docker-smoke]
+    needs: release-evidence
     # Manual dispatch is intentionally build/check-only. Publication requires a pushed
     # semver tag, whose value was matched to pyproject.toml in the build job above.
     if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
@@ -236,6 +290,12 @@ jobs:
           name: python-package-distributions
           path: dist/
 
+      - name: Download public release evidence
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
+        with:
+          name: public-release-evidence
+          path: release-evidence/
+
       - name: Create GitHub Release
         env:
           GH_TOKEN: ${{ github.token }}
@@ -246,11 +306,11 @@ jobs:
             # A previous partial attempt may have created the release before every
             # canonical package asset uploaded. Reconcile same-named assets from the
             # exact aggregate that passed the publish gate.
-            gh release upload "$GITHUB_REF_NAME" dist/* \
+            gh release upload "$GITHUB_REF_NAME" dist/* release-evidence/release-evidence.json release-evidence/*.cdx.json \
               --repo "$GH_REPO" \
               --clobber
           else
-            gh release create "$GITHUB_REF_NAME" dist/* \
+            gh release create "$GITHUB_REF_NAME" dist/* release-evidence/release-evidence.json release-evidence/*.cdx.json \
               --repo "$GH_REPO" \
               --verify-tag \
               --generate-notes \
@@ -319,11 +379,44 @@ jobs:
                                         (.conclusion == "success" or
                                          .conclusion == "failure"))] | length' \
             <<<"$jobs")" -eq 1
+          test "$(jq '[.jobs[] | select(.name == "Generate public release evidence" and
+                                        .conclusion == "success")] | length' \
+            <<<"$jobs")" -eq 1
           gh run download "$run_id" \
             --repo "$GH_REPO" \
             --name python-package-distributions \
             --dir dist
 
+          gh run download "$run_id" \
+            --repo "$GH_REPO" \
+            --name public-release-evidence \
+            --dir release-evidence
+          python - "$RELEASE_TAG" "$tag_sha" <<'PY'
+          import hashlib
+          import json
+          import sys
+          from pathlib import Path
+
+          tag, commit = sys.argv[1:]
+          with open("release-evidence/release-evidence.json", encoding="utf-8") as handle:
+              evidence = json.load(handle)
+          assert evidence.get("format") == "engraphis-release-evidence/2"
+          assert evidence.get("package", {}).get("version") == tag.removeprefix("v")
+          assert evidence.get("tag") == tag
+          assert evidence.get("commit") == commit
+          assert evidence.get("provenance", {}).get("source") == {"tag": tag, "commit": commit}
+          expected = {
+              item["filename"]: item["sha256"]
+              for item in evidence.get("artifacts", [])
+          }
+          actual = {
+              path.name: hashlib.sha256(path.read_bytes()).hexdigest()
+              for path in Path("dist").iterdir()
+              if path.is_file() and (path.name.endswith(".whl") or path.name.endswith(".tar.gz"))
+          }
+          assert expected == actual
+          PY
+
       - name: Verify any previously published subset
         env:
           RELEASE_TAG: ${{ inputs.release_tag }}
@@ -361,11 +454,11 @@ jobs:
         shell: bash
         run: |
           if gh release view "$RELEASE_TAG" --repo "$GH_REPO" >/dev/null 2>&1; then
-            gh release upload "$RELEASE_TAG" dist/* \
+            gh release upload "$RELEASE_TAG" dist/* release-evidence/release-evidence.json release-evidence/*.cdx.json \
               --repo "$GH_REPO" \
               --clobber
           else
-            gh release create "$RELEASE_TAG" dist/* \
+            gh release create "$RELEASE_TAG" dist/* release-evidence/release-evidence.json release-evidence/*.cdx.json \
               --repo "$GH_REPO" \
               --verify-tag \
               --generate-notes \

AGENTS.md

@@ -20,7 +20,7 @@ most common mistake here.
 | Status | Primary scoped, bi-temporal, interface-driven implementation. | Compatibility/reference implementation with flat namespaces. |
 | Model | Scoped + bi-temporal + typed; interface-driven. | Single flat `namespace` string per memory. |
 | Code | `engraphis/core/`, `engraphis/backends/`, `eval/`, `tests/`, `scripts/migrate_to_v2.py` | `engraphis/app.py`, `config.py`, `models.py`, `routes/`, `stores/`, `engines/`, `llm/`, `static/` |
-| Data | new v2 schema (`SCHEMA_VERSION = 4`) | `engraphis_v1.db` |
+| Data | new v2 schema (`SCHEMA_VERSION = 6`) | `engraphis_v1.db` |
 | Entry | `MemoryEngine.create()` → `core/engine.py` | `python -m scripts.start_server` → FastAPI on :8700 |
 
 **Rule:** build new capability on **v2** (`core/` + `backends/`) behind the interfaces.
@@ -79,8 +79,6 @@ python -m scripts.cli recall "what do we know about X" -n vault    # CLI: ingest
 python -m scripts.migrate_to_v2 --old engraphis_v1.db --new engraphis_v2.db --dry-run
 python -m scripts.migrate_to_v2 --old engraphis_v1.db --new engraphis_v2.db
 
-# ── Seed memories from an Obsidian/markdown vault (v1) ───────────────────────
-python -m scripts.seed_from_obsidian "C:/path/to/Vault" --namespace vault
 ```
 
 `requires-python >= 3.9` (ruff targets `py39`); CI and the recommended dev environment use **3.11**.
@@ -93,15 +91,17 @@ python -m scripts.seed_from_obsidian "C:/path/to/Vault" --namespace vault
 
 ```
 query
-  └─ SearchFilter (scope + as_of time anchor)            core/interfaces.py
-     └─ 3 retrieval arms (run in parallel, then fused):
+  └─ SearchFilter (scope + valid_at/known_at anchors)    core/interfaces.py
+     └─ 4 retrieval arms (run in parallel, then fused):
         • vector   — VectorIndex.search (cosine)         backends/vector_*.py
         • lexical  — Store.fts_search (FTS5/BM25 + LIKE fallback)   core/store.py
         • graph    — Personalized PageRank over entities+links      core/recall.py + core/graphrank.py
                      (graph_mode="1hop" keeps the old expansion for ablation)
+        • code     — symbols/files/calls with memory bridges          core/engine.py
      └─ RRF fusion + six-term weighted score             core/scoring.py
      └─ rerank top-N                                      backends/reranker.py
-     └─ context packing (token budget) + reinforce()      core/recall.py / core/store.py
+     └─ context packing (token budget) + optional explicit reinforcement
+                                                       core/recall.py / core/store.py
 ```
 
 Backends are selected by `get_embedder()` / `get_vector_index()` / `get_reranker()` and
@@ -177,7 +177,7 @@ These are pure, unit-tested functions — change them only with a corresponding
 
 ---
 
-## 5. Data model cheat-sheet (`core/interfaces.py`, `core/schema.py` — `SCHEMA_VERSION = 4`)
+## 5. Data model cheat-sheet (`core/interfaces.py`, `core/schema.py` — `SCHEMA_VERSION = 6`)
 
 - **Scope hierarchy:** `workspace → repo → session → memory`. Scopes: `session|repo|workspace|user`.
 - **Bi-temporal validity on every record:** world-time `valid_from/valid_to` +
@@ -188,7 +188,8 @@ These are pure, unit-tested functions — change them only with a corresponding
   Lexicographic sort == chronological.
 - **Tables:** `workspaces`, `repos`, `sessions`, `memories`, `mem_vectors`,
   `mem_fts` (FTS5 + plain-table fallback), `entities`, `edges` (bi-temporal), `mem_links`,
-  `symbols`, `code_edges`, `code_files`, `code_memory_links`, `operation_receipts`,
+  `memory_entities`, `symbols`, `code_edges`, `code_files`, `code_memory_links`,
+  `operation_receipts`,
   `events`, `audit`, `schema_migrations`.
 - **Vectors are stored L2-normalized** so cosine similarity == dot product.
 
@@ -221,7 +222,7 @@ These are pure, unit-tested functions — change them only with a corresponding
 - **`README.md`** — installation, product surfaces, configuration, and public API usage.
 - **`CHANGELOG.md`** — shipped capability and release history. Keep phase/status ledgers out of
   this operating manual.
-- **`docs/SYNC.md`** — cloud sync (Pro): architecture, the convergent merge, CLI usage, the
+- **`docs/SYNC.md`** — cloud sync (Pro): architecture, the convergent merge, CLI usage, and the
   untrusted-bundle security model.
 - **`AGENTS.md`** (this file) + **`CLAUDE.md`** — how to work in the repo.
 - **`skills/engraphis-memory/`** — portable Agent Skill (SKILL.md + `references/`) that teaches any