Improve recall reliability and introduce the update on the homepage

.github/workflows/ci.yml

@@ -11,32 +11,4 @@ permissions:
 
 jobs:
   test:
-    strategy:
-      matrix:
-        os: [ubuntu-latest, windows-latest]
-    runs-on: ${{ matrix.os }}
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Setup Node
-        uses: actions/setup-node@v4
-        with:
-          node-version: 22
-          cache: npm
-
-      - name: Install
-        run: npm ci
-
-      - name: Source, compiled, links and installed-package tests
-        run: npm test
-
-      - name: Memory lint
-        run: node scripts/dejavu-lint-memory.mjs && node scripts/dejavu-lint-memory.mjs --memory-root starter-kit/memory && node scripts/dejavu-lint-memory.mjs --memory-root examples/protocol-project/memory && node scripts/dejavu-lint-memory.mjs --memory-root docs/examples/settings-project/memory
-
-      - name: Project readiness
-        run: node scripts/deja-vu.mjs doctor --json
-
-      - name: Feedback report
-        run: npm run report:feedback
+    uses: ./.github/workflows/recall-acceptance.yml

.github/workflows/recall-acceptance.yml

@@ -0,0 +1,101 @@
+name: Recall acceptance
+
+on:
+  workflow_call:
+  push:
+    branches:
+      - fix/recall-efficiency-and-budgets
+
+permissions:
+  contents: read
+
+jobs:
+  acceptance:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 20
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - name: Checkout exact push revision
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Export public source and synthetic fixtures
+        working-directory: ${{ github.workspace }}
+        run: |
+          git rev-parse HEAD
+          public_root="$RUNNER_TEMP/deja-vu-public"
+          if [[ "$RUNNER_OS" == "Windows" ]]; then
+            public_root="$(cygpath -u "$RUNNER_TEMP")/deja-vu-public"
+          fi
+          mkdir -p "$public_root"
+          # Export committed bytes rather than runner-specific CRLF conversion.
+          git -c core.autocrlf=false archive HEAD AGENTS.md CHANGELOG.md CONTRIBUTING.md LICENSE README.md package.json package-lock.json tsconfig.json src tests scripts docs examples starter-kit .github .gitignore encoding-status.md llms.txt | tar -x -C "$public_root"
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Install locked dependencies
+        working-directory: ${{ runner.temp }}/deja-vu-public
+        run: npm ci
+
+      - name: Type check
+        working-directory: ${{ runner.temp }}/deja-vu-public
+        run: node node_modules/typescript/bin/tsc --noEmit -p tsconfig.json
+
+      - name: Complete source, links, compiled and installed-package acceptance
+        working-directory: ${{ runner.temp }}/deja-vu-public
+        run: npm test
+
+      - name: Frozen recall quality and cache lifecycle counts
+        working-directory: ${{ runner.temp }}/deja-vu-public
+        run: |
+          node scripts/evaluate-recall.mjs dist/src/index.js dist/src/index.js > "$RUNNER_TEMP/recall-quality.json"
+          node scripts/benchmark-cache-ownership.mjs dist/src/index.js dist/src/index.js > "$RUNNER_TEMP/recall-cache.json"
+          node --input-type=module <<'NODE'
+          import assert from 'node:assert/strict';
+          import { readFileSync } from 'node:fs';
+          import { join } from 'node:path';
+          const read = path => JSON.parse(readFileSync(path, 'utf8'));
+          const quality = read(join(process.env.RUNNER_TEMP, 'recall-quality.json'));
+          const expected = read('docs/engine/recall-evaluation.json');
+          // Runtime metadata is recorded, not a recall quality assertion.
+          console.log('Evaluation runtime:', quality.node, 'recorded runtime:', expected.node);
+          const { node: actualNode, ...actualQuality } = quality;
+          const { node: expectedNode, ...expectedQuality } = expected;
+          assert.deepEqual(actualQuality, expectedQuality);
+          const cache = read(join(process.env.RUNNER_TEMP, 'recall-cache.json'));
+          const recorded = read('docs/engine/recall-cache-ownership-benchmark.json');
+          for (const mode of ['after-unscoped', 'after-owned']) {
+            assert.deepEqual(cache.modes[mode], recorded.modes[mode]);
+          }
+          assert.deepEqual(cache.modes['before-unscoped'], cache.modes['after-unscoped']);
+          console.log('Frozen development/held-out IDs and metrics, cache call counts and retained entries: passed');
+          NODE
+
+      - name: Synthetic protocol fixture checks
+        working-directory: ${{ runner.temp }}/deja-vu-public
+        run: |
+          node scripts/dejavu-lint-memory.mjs --memory-root starter-kit/memory
+          node scripts/dejavu-lint-memory.mjs --memory-root examples/protocol-project/memory
+          node scripts/dejavu-lint-memory.mjs --memory-root docs/examples/settings-project/memory
+          npm run report:feedback
+
+      - name: Fresh synthetic project readiness
+        working-directory: ${{ runner.temp }}/deja-vu-public
+        run: |
+          project_root="$RUNNER_TEMP/deja-vu-readiness"
+          if [[ "$RUNNER_OS" == "Windows" ]]; then
+            project_root="$(cygpath -u "$RUNNER_TEMP")/deja-vu-readiness"
+          fi
+          node scripts/deja-vu.mjs init --cwd "$project_root" --project-id project:ci --json
+          node scripts/dejavu-lint-memory.mjs --memory-root "$project_root/memory"
+          node scripts/deja-vu.mjs doctor --cwd "$project_root" --json

AGENTS.md

@@ -30,3 +30,16 @@ Write back only durable project memory:
 - safety or privacy constraints
 
 Never store secrets, full transcripts, PII, raw logs, low-signal chatter, or disposable exploration noise.
+
+## Verification Loop
+
+For implementation or repair work:
+
+1. Define the scope, exclusions, baseline revision and acceptance checklist before changing code. Preserve unrelated user changes and original requirements.
+2. Make acceptance observable: include relevant source and compiled tests, types, package/install/use checks, regression coverage, behavior/quality checks and accurate documentation. Distinguish case counts from file-level summaries.
+3. Keep evidence for each failure: command, environment, revision, exit status, original error/cause and the smallest reproducible example. Do not replace an operational error with a secondary parsing error.
+4. Follow failure -> diagnosis -> focused correction -> affected regression tests -> full acceptance. State the hypothesis and use a check that can distinguish it from alternatives.
+5. After two iterations without new evidence or improvement, change the hypothesis or strategy. Do not endlessly retry the same failure or spend the loop on unrelated polish.
+6. Never weaken assertions, skip failing cases, hide errors or change security controls to obtain a green result. Use runtime/execution alternatives only when authorized and established not to bypass restrictions.
+7. Finish only when acceptance passes or a genuine external blocker is demonstrated. For a blocker, preserve a reproducible checkpoint, identify the blocked gates and exact resource/permission needed, and report it as blocked rather than passed.
+8. Review the final diff, document measured effects and limitations, and verify repository status. Commit, push, merge or publish only within the user's authorization. Task-specific data/privacy constraints take precedence over a generic verification command.

CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to this project will be documented in this file.
 
 ## Unreleased
 
+- Introduce the source update on the repository homepage, with [opt-in examples, migration guidance and scoped measurements](docs/recall-update.md). No new npm package or GitHub Release is published.
+- Reuse the complete synthetic-data acceptance workflow for main and pull requests, including fresh-project lint/readiness checks, without reading project memory.
+- Preserve original CLI subprocess failures in test helpers, retain execution/parse causes for invalid error responses, and add ten diagnostic regressions without weakening product assertions.
+- Append general acceptance/evidence/repair-loop rules to AGENTS.md and preserve the historical [Cloud blocker checkpoint](docs/verification-loop.md).
+- Verify complete source, compiled, installed-package, type, recall-quality and cache gates on Ubuntu and Windows in [branch-only Actions](docs/actions-acceptance-results.md). Fix workflow context/path/newline handling and freeze the recall tie fixture's clock without changing product assertions. These changes remain unreleased.
+
+- Add opt-in exact query aliases, managed per-memory/revision embedding scopes, and serialized reads; digest cache keys avoid retained plaintext input keys.
+- Compensate failed deletions, add explicit recoverable `supersedeMemory`, and return defensive summary/chunk copies from the in-memory adapter.
+- Add opt-in prompt provenance and qualifier-loss warnings, plus explicit raw-content retrieval.
+- Record development/held-out synthetic recall evaluation, ownership costs, repeated performance comparisons, and direct offline installed-package verification in the [round-two notes](docs/release-recall-lifecycle.md). Hosted validation now passes; the native cause of the historical Cloud EPERM remains unresolved.
+
+- Fix optional-engine false-none recall when an ineligible hybrid winner hides an eligible candidate; keep existing thresholds.
+- Add opt-in candidate search breadth, bounded prompt projection, metadata-only embedding reuse, and a content/model-keyed bounded embedding cache.
+- Cache lexical token sets with update/delete invalidation and validate recall/chunking limits before expensive work.
+- Add synthetic regression tests, a reproducible comparison benchmark, and [unreleased notes](docs/release-recall-efficiency.md) with migration guidance and measurement limits.
+
 ## [0.7.1] - Unreleased
 
 Release preparation only; not yet published. See the [release checklist](docs/release-v0.7.1.md).

README.md

@@ -11,6 +11,23 @@ Deja Vu is a three-file, repo-local memory system that any capable coding agent
 
 No database. No vector store. No embeddings. No SaaS. No daemon. No required npm install.
 
+## Latest update: more reliable, bounded recall
+
+**Available in repository source; a new npm package release has not been published.**
+
+The optional TypeScript engine now keeps eligible memories from being hidden by
+less relevant ranking winners. It also adds bounded prompt excerpts, recoverable
+deletion and supersession, and opt-in query aliases and embedding-cache reuse.
+The three-file protocol and [60-second setup](#start-in-60-seconds) stay the same.
+
+Efficiency depends on the workload and enabled options: these changes do not
+make every request faster. Explicit aliases are routing rules, not a new
+multilingual semantic model.
+
+**[Read the full update, opt-in examples and migration notes](./docs/recall-update.md)**
+· [Measurements and tradeoffs](./docs/release-recall-lifecycle.md)
+· [Complete Ubuntu/Windows acceptance evidence](./docs/actions-acceptance-results.md)
+
 ![Deja Vu turns tiny repo-local cues into minimal, relevant recall](./docs/assets/deja-vu-preview.svg)
 
 ## Start in 60 seconds
@@ -196,6 +213,13 @@ const engine = createInMemorySemanticRecallEngine({
 
 Read the [engine guide](./docs/engine/semantic-engine.md) or run the [basic example](./examples/basic/index.ts). The engine is an optional acceleration layer, not the default adoption path.
 
+Repository source includes eligible-candidate selection, bounded prompt output,
+and opt-in embedding reuse, [explicit aliases, cache ownership and provenance](docs/engine/recall-lifecycle.md).
+These additions are not yet published in a new npm package. See the
+[update and migration overview](docs/recall-update.md),
+[usage examples](docs/engine/recall-efficiency.md), and
+[complete hosted acceptance results](docs/actions-acceptance-results.md).
+
 ## Contributing
 
 Issues and focused pull requests are welcome. Read [CONTRIBUTING.md](./CONTRIBUTING.md) for the project boundaries and verification commands.

docs/actions-acceptance-results.json

@@ -0,0 +1,168 @@
+{
+  "status": "hosted acceptance passed; unreleased",
+  "verifiedRun": {
+    "id": 39089631583,
+    "url": "https://github.com/focaxisdev/deja-vu/actions/runs/39089631583",
+    "sha": "db56925d789482ba1f2a850b5833e73e7f031de4",
+    "status": "completed",
+    "conclusion": "success"
+  },
+  "publicationMappings": [
+    {
+      "local": "a66a52d4fceaeba3dac4a24c8e7cc82d834a4331",
+      "remote": "586f73016fc134c09c2e19b02e45c94b390e8c98",
+      "tree": "7365590fdcc4ea07a3513e9695ecf53a0e80e759",
+      "run": 39089273873
+    },
+    {
+      "local": "f880ca2d67b14e939164bb7fc594800598e8fcdd",
+      "remote": "57aaf0d9d15733aa1c3c955ed09ac275d123b601",
+      "tree": "da94ba9b8c80a7cfd0d79a114a8dcdbb4fb5b97e",
+      "parent": "586f73016fc134c09c2e19b02e45c94b390e8c98",
+      "files": 148,
+      "changed": 1,
+      "run": 39089353842
+    },
+    {
+      "local": "bb2b64e486e8530c8eeca09ed3d8fe6fc71f8c67",
+      "remote": "262e82660c23b9cc008c9d944b58b57148f77331",
+      "tree": "c574e262740b3ec25a212c752ba1a14eb3953e0d",
+      "parent": "57aaf0d9d15733aa1c3c955ed09ac275d123b601",
+      "files": 148,
+      "changed": 2,
+      "run": 39089505184
+    },
+    {
+      "local": "b139302c87b891cdc4e45ed735b5e2b7461b941f",
+      "remote": "db56925d789482ba1f2a850b5833e73e7f031de4",
+      "tree": "0cbc219a67320f375f3685656e2e30ecf424baa2",
+      "parent": "262e82660c23b9cc008c9d944b58b57148f77331",
+      "files": 148,
+      "changed": 1,
+      "run": 39089631583
+    }
+  ],
+  "verification": {
+    "initialCompleteTreeFileCount": 148,
+    "initialDeltaFromMain": {
+      "added": 26,
+      "modified": 16,
+      "deleted": 0,
+      "modeChanges": 0
+    },
+    "everyPublication": "root tree SHA and each recursive file path/type/mode/blob SHA equal the source local tree; remote commit parent and branch ref verified",
+    "permissions": "contents: read; no release/deploy/publish job; no force updates",
+    "localHistory": "all original local commits retained"
+  },
+  "jobs": [
+    {
+      "os": "Ubuntu 24.04.5",
+      "id": 117563410807,
+      "url": "https://github.com/focaxisdev/deja-vu/actions/runs/39089631583/job/117563410807",
+      "node": "v22.23.3",
+      "npm": "10.9.9",
+      "source": {
+        "tests": 119,
+        "pass": 119,
+        "fail": 0,
+        "skipped": 0
+      },
+      "compiled": {
+        "tests": 119,
+        "pass": 119,
+        "fail": 0,
+        "skipped": 0
+      },
+      "packageInstallUse": {
+        "tests": 1,
+        "pass": 1,
+        "fail": 0,
+        "skipped": 0
+      },
+      "types": "passed",
+      "frozenRecallQuality": "passed",
+      "cacheLifecycleCounts": "passed",
+      "protocolFixtures": "passed",
+      "publicMarkdownLinks": {
+        "files": 69,
+        "status": "passed"
+      }
+    },
+    {
+      "os": "Windows Server 2025",
+      "id": 117563410610,
+      "url": "https://github.com/focaxisdev/deja-vu/actions/runs/39089631583/job/117563410610",
+      "node": "v22.23.3",
+      "npm": "10.9.9",
+      "source": {
+        "tests": 119,
+        "pass": 119,
+        "fail": 0,
+        "skipped": 0
+      },
+      "compiled": {
+        "tests": 119,
+        "pass": 119,
+        "fail": 0,
+        "skipped": 0
+      },
+      "packageInstallUse": {
+        "tests": 1,
+        "pass": 1,
+        "fail": 0,
+        "skipped": 0
+      },
+      "types": "passed",
+      "frozenRecallQuality": "passed",
+      "cacheLifecycleCounts": "passed",
+      "protocolFixtures": "passed",
+      "publicMarkdownLinks": {
+        "files": 69,
+        "status": "passed"
+      }
+    }
+  ],
+  "failuresPreserved": [
+    {
+      "run": 39089273873,
+      "kind": "workflow planning",
+      "jobs": 0,
+      "detail": "runner.temp context was used under job defaults; moved workdir resolution to steps. API exposed no validation annotation or runner log."
+    },
+    {
+      "run": 39089353842,
+      "job": 117562559666,
+      "kind": "nondeterministic test fixture",
+      "source": {
+        "tests": 119,
+        "pass": 118,
+        "fail": 1,
+        "skipped": 0
+      },
+      "error": "ERR_ASSERTION: 'tie2' !== 'tie0'",
+      "fix": "Freeze Date in the lexical-tie/candidateLimit test; all 95 efficiency assertions retained."
+    },
+    {
+      "run": 39089353842,
+      "job": 117562559864,
+      "kind": "Windows archive path",
+      "error": "tar: Cannot open: No such file or directory",
+      "fix": "Convert Windows RUNNER_TEMP to a Bash path using cygpath."
+    },
+    {
+      "run": 39089505184,
+      "job": 117563017821,
+      "kind": "frozen fixture byte mismatch",
+      "expectedFixtureSha256": "4e1b70b5520e1d3cfb85489aad053825e339938016b20e659f2a4eb4677aee5d",
+      "actualFixtureSha256": "21552541a3f35ae72ba055b265d2fd99a03f67c768bd9ca9b4f07b95a9373a7e",
+      "fix": "Command-scoped core.autocrlf=false on git archive preserves committed LF bytes. Hash/content assertions and frozen answers unchanged."
+    }
+  ],
+  "limits": [
+    "Hosted Node 22 results do not identify the native syscall/policy cause of Cloud Node 24 spawnSync EPERM.",
+    "Five historical masked errors cannot be retrospectively attributed.",
+    "No new latency benchmark; provider-call/retained-entry checks are not performance or token claims.",
+    "Source/compiled and OS counts repeat the same cases; 120 distinct selected tests, not 478 distinct tests.",
+    "Documentation follow-up changes require another complete run at their own published SHA."
+  ]
+}