@event4u/agent-config 8.7.0 → 8.9.0

package/src/scripts/lint_versioned_cache.ts

@@ -0,0 +1,195 @@
+#!/usr/bin/env tsx
+/**
+ * Versioned-cache lint (road-to-retrieval-substrate-hardening B5b).
+ *
+ * Every derived cache the suite writes MUST be safe to invalidate when its
+ * producer changes — otherwise a tool-version bump silently reads a
+ * stale-format cache and corrupts the read path. This lint makes that
+ * discipline structural: any cache-file path literal in `src/scripts/**`
+ * must EITHER carry a version namespace in the path (`v<N>`, a `${…version…}`
+ * interpolation, or a `_VERSION`/`schema_version` reference), OR carry an
+ * explicit invalidation justification comment (`cache-version:` /
+ * `cache-invalidation:`) within a few lines — an author's ack that the cache
+ * is invalidated by another mechanism (full overwrite, content hash, …).
+ *
+ * It is a FAILING gate (this roadmap introduces it), scoped tightly to
+ * cache-file SUFFIXES so it has near-zero false-positive surface: it fires on
+ * the derived caches later phases create (B2 index, B3 learning sidecar, B5a
+ * stat-index), not on directories or ordinary data files.
+ *
+ * Usage: lint_versioned_cache.ts [--dir <root>] [--format text|json] [--quiet]
+ * Exit codes: 0 = clean, 1 = usage error, 2 = violations found, 3 = internal.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+const PROG = 'lint_versioned_cache.ts';
+
+/** Window (lines) around a cache-path literal scanned for a justification. */
+export const JUSTIFY_WINDOW = 6;
+
+/**
+ * A path literal is a "derived cache file" when its basename matches one of
+ * these suffixes. Suffix-based (not dir-based) to keep the trigger precise —
+ * ordinary data/config JSON does not match.
+ */
+export const CACHE_SUFFIX_RE =
+    /(?:^|[\/'"`\-.])(?:[a-z0-9_\-.]*)(?:-index|\.index|-cache|\.cache|\.stat-index|-stat-index|\.agent-learning)\.json(?:['"`]|$)/i;
+
+/** A version namespace present in the path literal itself. */
+const VERSION_IN_PATH_RE = /(?:[\/_\-.]v\d+|\$\{[^}]*[Vv]ersion[^}]*\}|\$\{[^}]*VERSION[^}]*\})/;
+
+/** An explicit author justification comment near the literal. */
+const JUSTIFY_RE = /(?:cache-version:|cache-invalidation:)/i;
+
+/** A string / template literal containing a cache-file path. */
+const LITERAL_RE = /(['"`])((?:\\.|(?!\1).)*?)\1/g;
+
+export interface Violation {
+    file: string;
+    line: number; // 1-indexed
+    literal: string;
+    message: string;
+}
+
+function listTsFiles(root: string): string[] {
+    const out: string[] = [];
+    const skip = new Set([
+        'node_modules',
+        '.git',
+        'dist',
+        'coverage',
+        '.turbo',
+        '.cache',
+        '__pycache__',
+    ]);
+    const walk = (dir: string): void => {
+        let entries: fs.Dirent[];
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        } catch {
+            return;
+        }
+        for (const e of entries) {
+            if (e.isDirectory()) {
+                if (!skip.has(e.name)) walk(path.join(dir, e.name));
+            } else if (e.isFile() && e.name.endsWith('.ts') && !e.name.endsWith('.d.ts')) {
+                out.push(path.join(dir, e.name));
+            }
+        }
+    };
+    walk(root);
+    return out.sort();
+}
+
+function _isCachePathLiteral(value: string): boolean {
+    // Reset lastIndex — CACHE_SUFFIX_RE has no /g flag, so test() is safe.
+    return CACHE_SUFFIX_RE.test(value);
+}
+
+export function scanFile(file: string, source: string): Violation[] {
+    const lines = source.split('\n');
+    const violations: Violation[] = [];
+    for (let i = 0; i < lines.length; i++) {
+        const text = lines[i] as string;
+        LITERAL_RE.lastIndex = 0;
+        let m: RegExpExecArray | null;
+        while ((m = LITERAL_RE.exec(text)) !== null) {
+            const value = m[2] as string;
+            if (!_isCachePathLiteral(value)) continue;
+            if (VERSION_IN_PATH_RE.test(value)) continue; // versioned in the path itself
+
+            // Look for a justification comment in the window around the literal.
+            const from = Math.max(0, i - JUSTIFY_WINDOW);
+            const to = Math.min(lines.length - 1, i + JUSTIFY_WINDOW);
+            let justified = false;
+            for (let j = from; j <= to; j++) {
+                if (JUSTIFY_RE.test(lines[j] as string)) {
+                    justified = true;
+                    break;
+                }
+            }
+            if (justified) continue;
+
+            violations.push({
+                file,
+                line: i + 1,
+                literal: value,
+                message:
+                    'derived cache without a version namespace — add a `v<N>` (or ' +
+                    '`${…version…}`) segment to the path, or an inline ' +
+                    '`// cache-invalidation: <why no version is needed>` comment',
+            });
+        }
+    }
+    return violations;
+}
+
+export function runChecks(root: string): Violation[] {
+    const violations: Violation[] = [];
+    for (const file of listTsFiles(root)) {
+        // Never lint this file itself — its regexes contain the very suffixes
+        // it hunts for.
+        if (path.basename(file) === 'lint_versioned_cache.ts') continue;
+        let source: string;
+        try {
+            source = fs.readFileSync(file, 'utf-8');
+        } catch {
+            continue;
+        }
+        violations.push(...scanFile(file, source));
+    }
+    return violations;
+}
+
+export function main(argv: string[]): number {
+    let dir = 'src/scripts';
+    let format: 'text' | 'json' = 'text';
+    let quiet = false;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i] as string;
+        if (a === '--dir') {
+            dir = argv[++i] ?? dir;
+        } else if (a.startsWith('--dir=')) {
+            dir = a.slice('--dir='.length);
+        } else if (a === '--format') {
+            format = (argv[++i] as 'text' | 'json') ?? 'text';
+        } else if (a === '--quiet') {
+            quiet = true;
+        } else if (a === '-h' || a === '--help') {
+            process.stdout.write(`usage: ${PROG} [--dir <root>] [--format text|json] [--quiet]\n`);
+            return 0;
+        } else {
+            process.stderr.write(`${PROG}: error: unknown argument ${a}\n`);
+            return 1;
+        }
+    }
+
+    let violations: Violation[];
+    try {
+        violations = runChecks(path.resolve(dir));
+    } catch (exc) {
+        process.stderr.write(`${PROG}: internal error: ${String(exc)}\n`);
+        return 3;
+    }
+
+    if (format === 'json') {
+        process.stdout.write(JSON.stringify({ violations }, null, 2) + '\n');
+        return violations.length > 0 ? 2 : 0;
+    }
+    if (violations.length === 0) {
+        if (!quiet) process.stdout.write(`${PROG}: no unversioned derived caches\n`);
+        return 0;
+    }
+    for (const v of violations) {
+        process.stdout.write(`❌ ${v.file}:${v.line} — cache '${v.literal}': ${v.message}\n`);
+    }
+    process.stdout.write(`${PROG}: ${violations.length} unversioned derived cache(s)\n`);
+    return 2;
+}
+
+if (fileURLToPath(import.meta.url) === path.resolve(process.argv[1] ?? '')) {
+    process.exit(main(process.argv.slice(2)));
+}

package/src/scripts/mcp_server/consumer_tool_catalog.json

@@ -50,14 +50,18 @@
           "last": {"type": "integer", "description": "Return only the most recent N entries, after other filters apply.", "minimum": 1},
           "session": {"type": "string", "description": "Filter to a single 16-char session id."},
           "entry_type": {"type": "string", "description": "Filter by the `t` tag (e.g. note, decision, phase)."},
-          "path": {"type": "string", "description": "Optional history-file path override; defaults to the standard chat-history location under the project root."}
+          "path": {"type": "string", "description": "Optional history-file path override; defaults to the standard chat-history location under the project root."},
+          "around": {"type": "integer", "minimum": 0, "description": "Timeline anchor: return the entries around this ref (from a detail:\"index\" row) instead of the filtered list — depth_before/depth_after neighbours plus the anchor. Refs are within-file ordinals; rotation invalidates them."},
+          "depth_before": {"type": "integer", "minimum": 0, "default": 3, "description": "Neighbours before the anchor (with `around`). Defaults to 3."},
+          "depth_after": {"type": "integer", "minimum": 0, "default": 3, "description": "Neighbours after the anchor (with `around`). Defaults to 3."},
+          "detail": {"type": "string", "enum": ["index", "full"], "default": "full", "description": "'index' returns compact rows (ref, t tag, ~100-char preview, tokens_estimate) instead of full entries — scan first, then re-read the refs you need via `around` or a narrowed filter. 'full' (default) returns complete entries."}
         },
         "additionalProperties": false
       }
     },
     {
       "name": "memory_lookup",
-      "description": "Retrieve engineering-memory entries for one or more memory types, optionally narrowed to specific anchor paths. Use before editing a security-sensitive or historically buggy file to surface prior incidents, ownership, and patterns tied to it. Reads `agents/memory/<type>/*.yml` plus the `agents/memory/intake/*.jsonl` signal log. Read-only. Returns the v1 retrieval envelope: a `status` field plus per-type `slices` carrying the matched entries.",
+      "description": "Retrieve engineering-memory entries for one or more memory types, optionally narrowed to specific anchor paths. Use before editing a security-sensitive or historically buggy file to surface prior incidents, ownership, and patterns tied to it. WORKFLOW: call with detail:\"index\" FIRST — each row carries id, title and tokens_estimate (the cost of fetching it) — then fetch full bodies via memory_get ONLY for the ids you will actually use, batching multiple ids into one call. Reads `agents/memory/<type>/*.yml` plus the `agents/memory/intake/*.jsonl` signal log. Read-only. Returns the v1 retrieval envelope: a `status` field plus per-type `slices` carrying the matched entries.",
       "side_effect": "ro",
       "implemented_on": ["stdio"],
       "input_schema": {
@@ -65,12 +69,28 @@
         "properties": {
           "types": {"type": "array", "items": {"type": "string"}, "minItems": 1, "description": "Memory types to scan, e.g. `historical-patterns`, `incident-learnings`, `ownership`. At least one required."},
           "keys": {"type": "array", "items": {"type": "string"}, "description": "Optional anchor paths or globs to match entries against (e.g. a file you are about to edit)."},
-          "limit": {"type": "integer", "minimum": 1, "default": 5, "description": "Maximum entries to return per type. Defaults to 5."}
+          "limit": {"type": "integer", "minimum": 1, "default": 5, "description": "Maximum entries to return per type. Defaults to 5."},
+          "detail": {"type": "string", "enum": ["index", "full"], "default": "full", "description": "'index' returns compact priced rows (id, title, tokens_estimate) instead of full bodies — call this first, then memory_get the ids you need. 'full' (default) returns complete entries."},
+          "token_budget": {"type": "integer", "minimum": 1, "description": "Optional token budget. When set, entries are rendered as one-line compact rows (id, type, confidence, `line`) and the row set is hard-cut at token_budget × 4 chars; omitted hits appear as a top-level `truncation` hint naming a concrete next step. Absent → the envelope is unchanged."}
         },
         "required": ["types"],
         "additionalProperties": false
       }
     },
+    {
+      "name": "memory_get",
+      "description": "Batch-fetch FULL memory entries by id — the second half of the index-first retrieval workflow. Call memory_lookup with detail:\"index\" first, pick the ids whose title/tokens_estimate justify the fetch, then fetch them here in ONE batched call. Unknown ids are reported per-id (ids[<id>]=\"unknown\"), never failing the batch. Read-only.",
+      "side_effect": "ro",
+      "implemented_on": ["stdio"],
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "ids": {"type": "array", "items": {"type": "string"}, "minItems": 1, "description": "Entry ids to fetch (from a detail:\"index\" lookup)."}
+        },
+        "required": ["ids"],
+        "additionalProperties": false
+      }
+    },
     {
       "name": "memory_signal",
       "description": "Record an engineering-memory signal — a short, anchored observation such as a recurring bug pattern or an ownership note — to the monthly intake log `agents/memory/intake/signals-YYYY-MM.jsonl`. Use to capture a learning tied to a specific file so future `memory_lookup` calls surface it. Appends to the filesystem and is rate-limited per `(type, path)` within a rolling window. Returns the recorded signal.",

package/src/scripts/mcp_server/tools.ts

@@ -38,7 +38,10 @@ import {
     SCHEMA_VERSION as _CH_SCHEMA_VERSION,
     append as _chAppendImpl,
     init as _chInitImpl,
+    history_index_row as _chHistoryIndexRow,
     read_entries as _chReadEntriesImpl,
+    read_entries_with_refs as _chReadEntriesWithRefs,
+    slice_around as _chSliceAround,
     read_header as _chReadHeaderImpl,
 } from '../chat_history.js';
 import {
@@ -364,10 +367,63 @@ async function _chatHistoryReadHandler(
         throw new Error("'entry_type' must be a string when provided");
     }
 
+    const around = args.around;
+    if (
+        around !== undefined &&
+        around !== null &&
+        (typeof around !== 'number' || !Number.isInteger(around) || around < 0)
+    ) {
+        throw new Error("'around' must be a non-negative integer when provided");
+    }
+    const depthBefore = args.depth_before ?? 3;
+    const depthAfter = args.depth_after ?? 3;
+    for (const [name, v] of [
+        ['depth_before', depthBefore],
+        ['depth_after', depthAfter],
+    ] as const) {
+        if (typeof v !== 'number' || !Number.isInteger(v) || v < 0) {
+            throw new Error(`'${name}' must be a non-negative integer`);
+        }
+    }
+    const detail = args.detail ?? 'full';
+    if (detail !== 'full' && detail !== 'index') {
+        throw new Error("'detail' must be 'index' or 'full'");
+    }
+
     if (!fs.existsSync(target)) {
         return { path: target, entries: [], count: 0 };
     }
 
+    // Timeline anchor path (road-to-memory-retrieval-economy Phase 3):
+    // refs index the FULL chronological list, so `around` ignores the
+    // session/entry_type/last filters by contract.
+    if (around !== undefined && around !== null) {
+        const pairs = _chSliceAround(
+            target,
+            around as number,
+            depthBefore as number,
+            depthAfter as number,
+        );
+        const entries =
+            detail === 'index'
+                ? pairs.map((p) => _chHistoryIndexRow(p))
+                : pairs.map((p) => ({ ref: p.ref, ...p.entry }));
+        return { path: target, entries, count: entries.length, anchor: around };
+    }
+
+    if (detail === 'index') {
+        let pairs = _chReadEntriesWithRefs({
+            path: target,
+            last: (last ?? null) as number | null,
+            session: (session ?? null) as string | null,
+        });
+        if (entryType) {
+            pairs = pairs.filter((p) => p.entry.t === entryType);
+        }
+        const entries = pairs.map((p) => _chHistoryIndexRow(p));
+        return { path: target, entries, count: entries.length };
+    }
+
     let entries = _chReadEntries(
         target,
         (last ?? null) as number | null,
@@ -416,6 +472,23 @@ async function _memoryLookupHandler(
     // Mirror the Python `os.chdir(consumer_root)` scoping: memory_lookup
     // resolves `agents/memory` relative to CWD, so the consumer root is
     // applied via a chdir window that is always restored.
+    const detailRaw = args.detail ?? 'full';
+    if (detailRaw !== 'full' && detailRaw !== 'index') {
+        throw new Error("'detail' must be 'index' or 'full'");
+    }
+
+    // B1 (road-to-retrieval-substrate-hardening): optional token budget →
+    // compact one-line rows, hard-cut with a truncation hint. Absent → the
+    // envelope is unchanged (v1 default-full contract holds).
+    const opts: { detail: 'full' | 'index'; token_budget?: number } = { detail: detailRaw };
+    if (args.token_budget !== undefined) {
+        const tb = args.token_budget;
+        if (typeof tb !== 'number' || !Number.isInteger(tb) || typeof tb === 'boolean' || tb < 1) {
+            throw new Error("'token_budget' must be a positive integer");
+        }
+        opts.token_budget = tb;
+    }
+
     const prevCwd = process.cwd();
     let envelope: Record<string, unknown>;
     try {
@@ -424,6 +497,7 @@ async function _memoryLookupHandler(
             [...(types as string[])],
             [...(keys as string[])],
             limitRaw,
+            opts,
         );
     } finally {
         process.chdir(prevCwd);
@@ -431,6 +505,30 @@ async function _memoryLookupHandler(
     return envelope;
 }
 
+/**
+ * Batch full-entry fetch by ID (road-to-memory-retrieval-economy Phase 1).
+ * The second half of the index→fetch economy: `memory_lookup` with
+ * `detail: 'index'` returns priced rows; this fetches ONLY the bodies the
+ * caller actually needs. Unknown IDs degrade per-ID, never the batch.
+ */
+async function _memoryGetHandler(
+    args: Record<string, unknown>,
+    consumerRoot: string,
+): Promise<Record<string, unknown>> {
+    const memoryLookup = await import('../memory_lookup.js');
+    const ids = args.ids;
+    if (!Array.isArray(ids) || ids.length === 0 || !ids.every((i) => typeof i === 'string')) {
+        throw new Error("'ids' must be a non-empty list of strings");
+    }
+    const prevCwd = process.cwd();
+    try {
+        process.chdir(consumerRoot);
+        return memoryLookup.memory_get_v1([...(ids as string[])]);
+    } finally {
+        process.chdir(prevCwd);
+    }
+}
+
 /** Phase 3 L2 — surface `scripts/memory_status.status()` as JSON. */
 async function _memoryStatusHandler(
     _args: Record<string, unknown>,
@@ -1225,6 +1323,40 @@ export const ALLOWLIST: Record<string, BuiltinTool> = {
                         'the standard chat-history location under the ' +
                         'project root.',
                 },
+                around: {
+                    type: 'integer',
+                    minimum: 0,
+                    description:
+                        'Timeline anchor: return the entries around this ' +
+                        'ref (from a detail:"index" row) instead of the ' +
+                        'filtered list — depth_before/depth_after ' +
+                        'neighbours plus the anchor. Refs are within-file ' +
+                        'ordinals; rotation invalidates them.',
+                },
+                depth_before: {
+                    type: 'integer',
+                    minimum: 0,
+                    default: 3,
+                    description: 'Neighbours before the anchor (with `around`). Defaults to 3.',
+                },
+                depth_after: {
+                    type: 'integer',
+                    minimum: 0,
+                    default: 3,
+                    description: 'Neighbours after the anchor (with `around`). Defaults to 3.',
+                },
+                detail: {
+                    type: 'string',
+                    enum: ['index', 'full'],
+                    default: 'full',
+                    description:
+                        "'index' returns compact rows (ref, t tag, ~100-char " +
+                        'preview, tokens_estimate) instead of full entries — ' +
+                        'scan first, then re-read the refs you need via ' +
+                        '`around` or a narrowed filter. History entries are ' +
+                        "large, so index mode pays off here. 'full' " +
+                        '(default) returns complete entries.',
+                },
             },
             additionalProperties: false,
         },
@@ -1237,7 +1369,11 @@ export const ALLOWLIST: Record<string, BuiltinTool> = {
             'types, optionally narrowed to specific anchor paths. Use ' +
             'before editing a security-sensitive or historically buggy ' +
             'file to surface prior incidents, ownership, and patterns ' +
-            'tied to it. Reads `agents/memory/<type>/*.yml` plus the ' +
+            'tied to it. WORKFLOW: call with detail:"index" FIRST — each ' +
+            'row carries id, title and tokens_estimate (the cost of ' +
+            'fetching it) — then fetch full bodies via memory_get ONLY ' +
+            'for the ids you will actually use, batching multiple ids ' +
+            'into one call. Reads `agents/memory/<type>/*.yml` plus the ' +
             '`agents/memory/intake/*.jsonl` signal log. Read-only. ' +
             'Returns the v1 retrieval envelope: a `status` field plus ' +
             'per-type `slices` carrying the matched entries.',
@@ -1266,12 +1402,57 @@ export const ALLOWLIST: Record<string, BuiltinTool> = {
                     default: 5,
                     description: 'Maximum entries to return per type. Defaults to 5.',
                 },
+                detail: {
+                    type: 'string',
+                    enum: ['index', 'full'],
+                    default: 'full',
+                    description:
+                        "'index' returns compact priced rows (id, title, " +
+                        "tokens_estimate) instead of full bodies — call " +
+                        "this first, then memory_get the ids you need. " +
+                        "'full' (default) returns complete entries.",
+                },
+                token_budget: {
+                    type: 'integer',
+                    minimum: 1,
+                    description:
+                        'Optional token budget. When set, entries are ' +
+                        'rendered as one-line compact rows (id, type, ' +
+                        'confidence, `line`) and the row set is hard-cut at ' +
+                        'token_budget × 4 chars; omitted hits appear as a ' +
+                        'top-level `truncation` hint naming a concrete next ' +
+                        'step. Absent → the envelope is unchanged.',
+                },
             },
             required: ['types'],
             additionalProperties: false,
         },
         handler: _memoryLookupHandler,
     },
+    memory_get: {
+        name: 'memory_get',
+        description:
+            'Batch-fetch FULL memory entries by id — the second half of ' +
+            'the index-first retrieval workflow. Call memory_lookup with ' +
+            'detail:"index" first, pick the ids whose title/tokens_estimate ' +
+            'justify the fetch, then fetch them here in ONE batched call. ' +
+            'Unknown ids are reported per-id (ids[<id>]="unknown"), never ' +
+            'failing the batch. Read-only.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                ids: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    minItems: 1,
+                    description: 'Entry ids to fetch (from a detail:"index" lookup).',
+                },
+            },
+            required: ['ids'],
+            additionalProperties: false,
+        },
+        handler: _memoryGetHandler,
+    },
     memory_status: {
         name: 'memory_status',
         description:

package/src/scripts/measure_lexical_ranking.ts

@@ -0,0 +1,173 @@
+#!/usr/bin/env tsx
+/**
+ * Ranking-lift measurement for the hand-rolled lexical index
+ * (road-to-retrieval-substrate-hardening B2, deterministic + free).
+ *
+ * The gate on shipping the index (roadmap Phase 2): it must measurably rank
+ * BETTER than the current `_score` bucket scorer, else honest-null. This
+ * script runs both scorers over the SAME retrieval-precision corpus + store
+ * (internal/bench/second-brain/retrieval-store/) and reports, per task and in
+ * aggregate:
+ *
+ *   - mean top tie-set size — how many entries share the TOP score. `_score`
+ *     gives 0.8 to any keyword match, so the needed entry ties with its
+ *     confusers (the "recalls but does not rank" finding, mean 3.3). A good
+ *     ranker drives this toward 1.
+ *   - precision@1 / @k — was the NEEDED entry actually first / in the top-k.
+ *
+ * No model, no spend: pure retrieval scoring. Exit 0 ok / 1 error / 2 usage.
+ *
+ * Usage: measure_lexical_ranking.ts [--write] [--format text|json]
+ *   --write  persist the report to internal/bench/reports/lexical-ranking.json
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import * as YAML from 'yaml';
+
+import { LexicalIndex } from './_lib/lexical_index.js';
+import { _score, _setIntakeRoot, _setKnowledgeRoot, _setMemoryRoot, retrieve } from './memory_lookup.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+export const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+export const STORE_DIR = path.join(REPO_ROOT, 'internal', 'bench', 'second-brain', 'retrieval-store');
+export const CORPUS = path.join(STORE_DIR, 'retrieval-corpus.yml');
+export const REPORT = path.join(REPO_ROOT, 'internal', 'bench', 'reports', 'lexical-ranking.json');
+
+interface Task {
+    id: string;
+    query: string[];
+    needed: string;
+}
+
+interface TaskResult {
+    id: string;
+    needed: string;
+    baseline: { rank: number; tieSet: number };
+    index: { rank: number; tieSet: number };
+}
+
+interface RankingSummary {
+    tasks: number;
+    k: number;
+    baseline_mean_tie_set: number;
+    index_mean_tie_set: number;
+    baseline_precision_at_1: number;
+    index_precision_at_1: number;
+    baseline_precision_at_k: number;
+    index_precision_at_k: number;
+}
+
+/** Text an entry contributes to the index — the fields `_score` also reads. */
+function entryText(entry: Record<string, unknown>): string {
+    const parts: string[] = [];
+    for (const f of ['path', 'key', 'symptom', 'feature', 'rule', 'body']) {
+        const v = entry[f];
+        if (typeof v === 'string') parts.push(v);
+        else if (Array.isArray(v)) for (const x of v) parts.push(String(x));
+    }
+    return parts.join(' | ');
+}
+
+/** Top tie-set size + rank of the needed id in a sorted (id, score) list. */
+function diagnose(ranked: Array<{ id: string; score: number }>, needed: string): { rank: number; tieSet: number } {
+    if (ranked.length === 0) return { rank: -1, tieSet: 0 };
+    const top = ranked[0]?.score ?? 0;
+    const tieSet = ranked.filter((r) => r.score === top).length;
+    const rank = ranked.findIndex((r) => r.id === needed);
+    return { rank, tieSet };
+}
+
+export function measure(): { tasks: TaskResult[]; summary: RankingSummary } {
+    _setMemoryRoot(STORE_DIR);
+    _setKnowledgeRoot(path.join(STORE_DIR, 'knowledge-none'));
+    _setIntakeRoot(path.join(STORE_DIR, 'intake-none'));
+
+    const doc = YAML.parse(fs.readFileSync(CORPUS, 'utf-8')) as { type: string; k: number; tasks: Task[] };
+    const type = doc.type;
+    const k = doc.k;
+    const results: TaskResult[] = [];
+
+    for (const task of doc.tasks) {
+        // Shared universe: every store entry `_score` considers relevant.
+        const hits = retrieve([type], task.query, 100);
+
+        // Baseline — rank by the current bucket scorer, ties broken by the
+        // order `retrieve` already returns (store order), exactly as today.
+        const baselineRanked = hits.map((h) => ({ id: h.id, score: h.score }));
+        const baseline = diagnose(baselineRanked, task.needed);
+
+        // Index — BM25 over the same entries' text.
+        const index = new LexicalIndex(hits.map((h) => ({ id: h.id, text: entryText(h.entry) })));
+        const indexRanked = index.rank(task.query);
+        const idx = diagnose(indexRanked, task.needed);
+
+        results.push({ id: task.id, needed: task.needed, baseline, index: idx });
+        void _score; // referenced for provenance — retrieve() applies it internally
+    }
+
+    const n = results.length;
+    const mean = (sel: (r: TaskResult) => number): number =>
+        n === 0 ? 0 : Math.round((results.reduce((a, r) => a + sel(r), 0) / n) * 1000) / 1000;
+    const precAt = (sel: (r: TaskResult) => number, kk: number): number =>
+        n === 0 ? 0 : Math.round((results.filter((r) => sel(r) >= 0 && sel(r) < kk).length / n) * 1000) / 1000;
+
+    const summary = {
+        tasks: n,
+        k,
+        baseline_mean_tie_set: mean((r) => r.baseline.tieSet),
+        index_mean_tie_set: mean((r) => r.index.tieSet),
+        baseline_precision_at_1: precAt((r) => r.baseline.rank, 1),
+        index_precision_at_1: precAt((r) => r.index.rank, 1),
+        baseline_precision_at_k: precAt((r) => r.baseline.rank, k),
+        index_precision_at_k: precAt((r) => r.index.rank, k),
+    };
+    return { tasks: results, summary };
+}
+
+export function main(argv: string[]): number {
+    let write = false;
+    let format: 'text' | 'json' = 'text';
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i] as string;
+        if (a === '--write') write = true;
+        else if (a === '--format') format = (argv[++i] as 'text' | 'json') ?? 'text';
+        else if (a === '-h' || a === '--help') {
+            process.stdout.write('usage: measure_lexical_ranking.ts [--write] [--format text|json]\n');
+            return 0;
+        } else {
+            process.stderr.write(`measure_lexical_ranking: unknown argument ${a}\n`);
+            return 2;
+        }
+    }
+
+    let out: { tasks: TaskResult[]; summary: RankingSummary };
+    try {
+        out = measure();
+    } catch (exc) {
+        process.stderr.write(`measure_lexical_ranking: error: ${String(exc)}\n`);
+        return 1;
+    }
+
+    if (write) {
+        fs.mkdirSync(path.dirname(REPORT), { recursive: true });
+        fs.writeFileSync(REPORT, JSON.stringify({ schema_version: 1, ...out }, null, 2) + '\n');
+    }
+    if (format === 'json') {
+        process.stdout.write(JSON.stringify(out, null, 2) + '\n');
+        return 0;
+    }
+    const s = out.summary;
+    process.stdout.write(
+        `lexical-ranking (${s.tasks} tasks, k=${s.k}):\n` +
+            `  mean top tie-set   baseline=${s.baseline_mean_tie_set}  index=${s.index_mean_tie_set}\n` +
+            `  precision@1        baseline=${s.baseline_precision_at_1}  index=${s.index_precision_at_1}\n` +
+            `  precision@${s.k}        baseline=${s.baseline_precision_at_k}  index=${s.index_precision_at_k}\n`,
+    );
+    return 0;
+}
+
+if (fileURLToPath(import.meta.url) === path.resolve(process.argv[1] ?? '')) {
+    process.exit(main(process.argv.slice(2)));
+}