@unson/brainbase-mcp 0.41.3 → 0.41.6

package/dist/judgment-history.js

@@ -1,3 +1,4 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
 import { createHash } from 'node:crypto';
 import { lstat, mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
@@ -12,6 +13,23 @@ export const JUDGMENT_HISTORY_ENTRYPOINTS = Object.freeze([
     'company_os',
     'unknown'
 ]);
+const judgmentHistoryTimingSlots = new AsyncLocalStorage();
+/** Isolates Server-Timing for one HTTP request from other in-flight reads. */
+export function withJudgmentHistoryRequestTimings(fn) {
+    return judgmentHistoryTimingSlots.run({ current: null }, fn);
+}
+/** Timings published by the in-flight request, when one is bound. */
+export function judgmentHistoryRequestTimings() {
+    const slot = judgmentHistoryTimingSlots.getStore();
+    if (!slot)
+        return { bound: false, timings: null };
+    return { bound: true, timings: slot.current };
+}
+function publishJudgmentHistoryReadTimings(timings) {
+    const slot = judgmentHistoryTimingSlots.getStore();
+    if (slot)
+        slot.current = timings;
+}
 export class JudgmentHistoryReaderError extends Error {
     statusCode;
     code;
@@ -22,6 +40,82 @@ export class JudgmentHistoryReaderError extends Error {
         this.name = 'JudgmentHistoryReaderError';
     }
 }
+export const DEFAULT_LOCAL_JUDGMENT_HISTORY_READ_PARALLEL = 8;
+export const MAX_JUDGMENT_HISTORY_RESOLUTION_BATCH = 100;
+/** Parsed artifacts kept for one local source. The oldest entry is dropped past this. */
+export const DEFAULT_JUDGMENT_HISTORY_JOURNAL_CACHE_LIMIT = 4_096;
+/**
+ * Remembers parsed journal artifacts for one local source.
+ * The key is (session, turn, file name, mtime). A later read of the same turn
+ * misses when that file's mtime changes, and the previous bytes are not reused.
+ * A lookup refreshes recency. Past `limit`, the least recently used entry is dropped.
+ */
+export class JudgmentHistoryJournalScanCache {
+    #files = new Map();
+    #limit;
+    #hits = 0;
+    #misses = 0;
+    constructor(limit = DEFAULT_JUDGMENT_HISTORY_JOURNAL_CACHE_LIMIT) {
+        if (!Number.isInteger(limit) || limit < 1)
+            throw new TypeError('cache limit must be a positive integer');
+        this.#limit = limit;
+    }
+    get limit() {
+        return this.#limit;
+    }
+    get size() {
+        return this.#files.size;
+    }
+    lookup(session, turn, fileName, mtimeNs) {
+        const key = `${session}\0${turn}\0${fileName}`;
+        const entry = this.#files.get(key);
+        if (!entry || entry.mtimeNs !== mtimeNs) {
+            if (entry)
+                this.#files.delete(key);
+            return null;
+        }
+        this.#files.delete(key);
+        this.#files.set(key, entry);
+        this.#hits += 1;
+        return entry.result;
+    }
+    store(session, turn, fileName, mtimeNs, result) {
+        const key = `${session}\0${turn}\0${fileName}`;
+        this.#files.delete(key);
+        this.#files.set(key, { mtimeNs, result });
+        while (this.#files.size > this.#limit) {
+            const oldest = this.#files.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.#files.delete(oldest);
+        }
+    }
+    noteMiss() {
+        this.#misses += 1;
+    }
+    get hits() {
+        return this.#hits;
+    }
+    get misses() {
+        return this.#misses;
+    }
+}
+/** Runs `map` with at most `limit` calls in flight. Results keep input order. */
+export async function mapWithConcurrencyLimit(items, limit, map) {
+    if (!Number.isInteger(limit) || limit < 1)
+        throw new TypeError('parallel limit must be a positive integer');
+    const results = new Array(items.length);
+    let next = 0;
+    const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+        while (next < items.length) {
+            const index = next;
+            next += 1;
+            results[index] = await map(items[index], index);
+        }
+    });
+    await Promise.all(workers);
+    return results;
+}
 export class JudgmentHistoryFeedbackError extends Error {
     statusCode;
     code;
@@ -945,21 +1039,12 @@ function mergeRecordWithFinal(adoptionRecord, final, sessionRef, key, turnInput,
     };
     return { ...baseRecord, missing_fields: missingFields(baseRecord, firstPresent(blocks, 'missing_fields')) };
 }
-async function readLocalRecords(root, configuredEntrypoint, maxFiles, maxRecordBytes) {
+async function loadNewestJournalGroups(root, maxFiles, maxRecordBytes, cache, readParallel) {
     const sessions = await readdir(root, { withFileTypes: true });
     const groups = new Map();
+    const discovered = [];
     let invalidCount = 0;
-    let candidateCount = 0;
-    let capped = false;
-    const stop = () => {
-        if (candidateCount >= maxFiles) {
-            capped = true;
-            return true;
-        }
-        candidateCount += 1;
-        return false;
-    };
-    outer: for (const session of sessions.sort((left, right) => left.name.localeCompare(right.name))) {
+    for (const session of sessions.sort((left, right) => left.name.localeCompare(right.name))) {
         if (session.isSymbolicLink()) {
             invalidCount += 1;
             continue;
@@ -975,7 +1060,6 @@ async function readLocalRecords(root, configuredEntrypoint, maxFiles, maxRecordB
             invalidCount += 1;
             continue;
         }
-        const groupMap = new Map();
         const recognized = names.map((entry) => {
             const name = entry.name;
             if (ADOPTION_FILE.test(name))
@@ -1002,12 +1086,9 @@ async function readLocalRecords(root, configuredEntrypoint, maxFiles, maxRecordB
                 invalidCount += 1;
                 continue;
             }
-            if (stop())
-                break outer;
-            const group = groupMap.get(key) ?? groupFor(groups, session.name, key);
-            groupMap.set(key, group);
             const path = join(sessionPath, candidate.entry.name);
             if (candidate.kind === 'events') {
+                const group = groupFor(groups, session.name, key);
                 group.eventDirectorySeen = true;
                 if (candidate.entry.isSymbolicLink() || !candidate.entry.isDirectory()) {
                     group.invalid += 1;
@@ -1024,33 +1105,106 @@ async function readLocalRecords(root, configuredEntrypoint, maxFiles, maxRecordB
                 for (const eventEntry of eventEntries.sort((left, right) => left.name.localeCompare(right.name))) {
                     if (!eventEntry.name.endsWith('.json'))
                         continue;
-                    if (stop())
-                        break outer;
-                    const eventResult = await readBoundedJson(join(path, eventEntry.name), maxRecordBytes);
-                    const eventKey = eventEntry.name.endsWith('.json') ? eventEntry.name.slice(0, -5) : undefined;
-                    if (eventResult.invalid || !eventResult.value || !validJournalEvent(eventResult.value, session.name, candidate.key, eventKey)) {
-                        group.invalid += 1;
-                        continue;
-                    }
-                    group.events.push(eventResult.value);
+                    discovered.push({
+                        session: session.name,
+                        key,
+                        kind: 'event',
+                        path: join(path, eventEntry.name),
+                        name: eventEntry.name,
+                        eventKey: eventEntry.name.slice(0, -5),
+                        mtimeNs: 0n
+                    });
                 }
                 continue;
             }
-            const result = await readBoundedJson(path, maxRecordBytes);
-            if (result.invalid || !result.value) {
+            discovered.push({
+                session: session.name,
+                key,
+                kind: candidate.kind,
+                path,
+                name: candidate.entry.name,
+                mtimeNs: 0n
+            });
+        }
+    }
+    const stated = await mapWithConcurrencyLimit(discovered, readParallel, async (candidate) => {
+        let mtimeNs = 0n;
+        try {
+            mtimeNs = (await lstat(candidate.path, { bigint: true })).mtimeNs;
+        }
+        catch {
+            mtimeNs = 0n;
+        }
+        return { ...candidate, mtimeNs };
+    });
+    const newestFirst = [...stated].sort((left, right) => {
+        if (left.mtimeNs === right.mtimeNs)
+            return left.path.localeCompare(right.path);
+        return left.mtimeNs > right.mtimeNs ? -1 : 1;
+    });
+    const capped = newestFirst.length > maxFiles;
+    const selectedPaths = new Set(newestFirst.slice(0, maxFiles).map((candidate) => candidate.path));
+    const selected = stated.filter((candidate) => selectedPaths.has(candidate.path));
+    let cacheHits = 0;
+    let cacheMisses = 0;
+    const loaded = await mapWithConcurrencyLimit(selected, readParallel, async (candidate) => {
+        const hit = cache.lookup(candidate.session, candidate.key, candidate.name, candidate.mtimeNs);
+        if (hit) {
+            cacheHits += 1;
+            return { path: candidate.path, result: hit };
+        }
+        cacheMisses += 1;
+        cache.noteMiss();
+        const result = await readBoundedJson(candidate.path, maxRecordBytes);
+        cache.store(candidate.session, candidate.key, candidate.name, candidate.mtimeNs, result);
+        return { path: candidate.path, result };
+    });
+    const byPath = new Map(loaded.map((item) => [item.path, item.result]));
+    for (const candidate of selected) {
+        const group = groupFor(groups, candidate.session, candidate.key);
+        const result = byPath.get(candidate.path);
+        if (!result) {
+            group.invalid += 1;
+            continue;
+        }
+        if (candidate.kind === 'event') {
+            group.eventDirectorySeen = true;
+            if (result.invalid || !result.value || !validJournalEvent(result.value, candidate.session, candidate.key, candidate.eventKey)) {
                 group.invalid += 1;
                 continue;
             }
-            if (candidate.kind === 'adoption')
-                group.adoption = result.value;
-            else if (candidate.kind === 'final')
-                group.final = result.value;
-            else if (candidate.kind === 'episode')
-                group.episode = result.value;
-            else
-                group.turnInput = result.value;
+            group.events.push(result.value);
+            continue;
+        }
+        if (result.invalid || !result.value) {
+            group.invalid += 1;
+            continue;
         }
+        if (candidate.kind === 'adoption')
+            group.adoption = result.value;
+        else if (candidate.kind === 'final')
+            group.final = result.value;
+        else if (candidate.kind === 'episode')
+            group.episode = result.value;
+        else
+            group.turnInput = result.value;
     }
+    return { groups, invalidCount, candidateCount: selected.length, capped, cacheHits, cacheMisses };
+}
+async function readLocalRecords(root, configuredEntrypoint, maxFiles, maxRecordBytes, cache, readParallel) {
+    const loaded = await loadNewestJournalGroups(root, maxFiles, maxRecordBytes, cache, readParallel);
+    const groups = loaded.groups;
+    let invalidCount = loaded.invalidCount;
+    let candidateCount = loaded.candidateCount;
+    let capped = loaded.capped;
+    const stop = () => {
+        if (candidateCount >= maxFiles) {
+            capped = true;
+            return true;
+        }
+        candidateCount += 1;
+        return false;
+    };
     const records = [];
     const seen = new Set();
     for (const group of groups.values()) {
@@ -1139,7 +1293,7 @@ async function readLocalRecords(root, configuredEntrypoint, maxFiles, maxRecordB
     }
     records.sort(compareRecords);
     const contentDigest = sha256(canonicalJson({ records, candidateCount, invalidCount, capped }));
-    return { records, invalidCount, candidateCount, capped, contentDigest };
+    return { records, invalidCount, candidateCount, capped, contentDigest, cacheHits: loaded.cacheHits, cacheMisses: loaded.cacheMisses };
 }
 function compareRecords(left, right) {
     const dateOrder = right.recorded_at.localeCompare(left.recorded_at);
@@ -1171,30 +1325,50 @@ export function createLocalJudgmentHistorySource(options) {
         throw new TypeError('max_files must be a positive integer');
     if (!Number.isInteger(maxRecordBytes) || maxRecordBytes < 1)
         throw new TypeError('max_record_bytes must be a positive integer');
+    const readParallel = options.read_parallel ?? DEFAULT_LOCAL_JUDGMENT_HISTORY_READ_PARALLEL;
+    if (!Number.isInteger(readParallel) || readParallel < 1)
+        throw new TypeError('read_parallel must be a positive integer');
+    const cache = options.cache ?? new JudgmentHistoryJournalScanCache();
     const root = resolve(options.root);
+    let lastTimings = null;
     return {
         storage: 'local',
+        timings: () => lastTimings,
         async read() {
+            const started = performance.now();
+            const finish = (scanned, cacheHits = 0, cacheMisses = 0, snapshot) => {
+                const journalMs = performance.now() - started;
+                const timings = {
+                    total_ms: journalMs,
+                    journal_ms: journalMs,
+                    page_ms: 0,
+                    cache_hits: cacheHits,
+                    cache_misses: cacheMisses,
+                    parallel_limit: readParallel,
+                    scanned_files: scanned
+                };
+                lastTimings = timings;
+                return { ...snapshot, timings };
+            };
             try {
                 const rootStats = await lstat(root);
                 if (rootStats.isSymbolicLink()) {
-                    return { status: 'unavailable', records: null, coverage: unavailableCoverage('local', 'journal_symlink_rejected') };
+                    return finish(0, 0, 0, { status: 'unavailable', records: null, coverage: unavailableCoverage('local', 'journal_symlink_rejected') });
+                }
+                if (!rootStats.isDirectory()) {
+                    return finish(0, 0, 0, { status: 'unavailable', records: null, coverage: unavailableCoverage('local', 'journal_not_directory') });
                 }
-                if (!rootStats.isDirectory())
-                    return { status: 'unavailable', records: null, coverage: unavailableCoverage('local', 'journal_not_directory') };
             }
             catch (error) {
-                if (error.code === 'ENOENT') {
-                    return { status: 'unavailable', records: null, coverage: unavailableCoverage('local', 'journal_unavailable') };
-                }
-                return { status: 'unavailable', records: null, coverage: unavailableCoverage('local', 'journal_unreadable') };
+                const reason = error.code === 'ENOENT' ? 'journal_unavailable' : 'journal_unreadable';
+                return finish(0, 0, 0, { status: 'unavailable', records: null, coverage: unavailableCoverage('local', reason) });
             }
             let result;
             try {
-                result = await readLocalRecords(root, configuredEntrypoint, maxFiles, maxRecordBytes);
+                result = await readLocalRecords(root, configuredEntrypoint, maxFiles, maxRecordBytes, cache, readParallel);
             }
             catch {
-                return { status: 'unavailable', records: null, coverage: unavailableCoverage('local', 'journal_unreadable') };
+                return finish(0, 0, 0, { status: 'unavailable', records: null, coverage: unavailableCoverage('local', 'journal_unreadable') });
             }
             const status = result.invalidCount > 0 || result.capped ? 'partial' : 'available';
             const reason = result.capped ? 'journal_scan_capped' : result.invalidCount > 0 ? 'some_journal_records_unreadable' : null;
@@ -1211,7 +1385,7 @@ export function createLocalJudgmentHistorySource(options) {
                 sources,
                 total: status === 'available' ? result.records.length : null
             };
-            return {
+            return finish(result.candidateCount, result.cacheHits, result.cacheMisses, {
                 status,
                 records: result.records,
                 coverage,
@@ -1224,7 +1398,7 @@ export function createLocalJudgmentHistorySource(options) {
                     capped: result.capped,
                     content_digest: result.contentDigest
                 })
-            };
+            });
         }
     };
 }
@@ -1417,105 +1591,190 @@ export function createJudgmentHistoryReader(options) {
     if (!options?.source || typeof options.source.read !== 'function')
         throw new TypeError('source is required');
     const now = options.now ?? (() => new Date());
+    let lastTimings = null;
+    const takeSource = async () => {
+        const snapshot = await options.source.read();
+        return {
+            source: buildSourceSnapshot(snapshot),
+            sourceTimings: snapshot.timings ?? options.source.timings?.() ?? null
+        };
+    };
+    const remember = (readStarted, pageStarted, sourceTimings) => {
+        const finished = performance.now();
+        const timings = {
+            total_ms: finished - readStarted,
+            journal_ms: sourceTimings?.journal_ms ?? Math.max(0, pageStarted - readStarted),
+            page_ms: Math.max(0, finished - pageStarted),
+            cache_hits: sourceTimings?.cache_hits ?? 0,
+            cache_misses: sourceTimings?.cache_misses ?? 0,
+            parallel_limit: sourceTimings?.parallel_limit ?? 0,
+            scanned_files: sourceTimings?.scanned_files ?? 0
+        };
+        lastTimings = timings;
+        publishJudgmentHistoryReadTimings(timings);
+    };
     return {
+        timings: () => lastTimings,
         async home(inputQuery = {}) {
             const query = normalizeQuery(inputQuery);
             if (query.project !== null && options.authorizeProject && !(await options.authorizeProject(query.project))) {
                 throw new JudgmentHistoryReaderError(403, 'project_scope_forbidden', 'project is outside the trusted scope');
             }
-            const source = buildSourceSnapshot(await options.source.read());
-            let records = source.records;
-            const filters = { period: query.period, project: query.project, entrypoint: query.entrypoint };
-            if (source.status === 'unavailable' || records === null) {
-                return {
+            const readStarted = performance.now();
+            const loaded = await takeSource();
+            const source = loaded.source;
+            const pageStarted = performance.now();
+            try {
+                let records = source.records;
+                const filters = { period: query.period, project: query.project, entrypoint: query.entrypoint };
+                if (source.status === 'unavailable' || records === null) {
+                    return {
+                        contract_version: JUDGMENT_HISTORY_CONTRACT_VERSION,
+                        status: source.status,
+                        records: null,
+                        coverage: { ...source.coverage, total: null },
+                        pagination: { cursor: query.cursor, next_cursor: null, limit: query.limit, has_more: false },
+                        filters
+                    };
+                }
+                let scopeUnverified = false;
+                if (query.project === null && options.authorizeProject) {
+                    const visible = [];
+                    for (const record of records) {
+                        // A record without a trusted project binding must never enter a
+                        // scoped aggregate, because its owner cannot be authorized.
+                        if (record.project_code === null) {
+                            scopeUnverified = true;
+                            continue;
+                        }
+                        if (await options.authorizeProject(record.project_code))
+                            visible.push(record);
+                    }
+                    records = visible;
+                }
+                const effectiveNow = now();
+                const start = periodStart(query.period, effectiveNow);
+                const anchor = query.period === 'all' ? null : startOfJstDay(effectiveNow);
+                const status = scopeUnverified && source.status === 'available' ? 'partial' : source.status;
+                const baseCoverage = scopeUnverified
+                    ? { ...source.coverage, complete: false, reason: 'project_scope_unverified', total: null }
+                    : { ...source.coverage, total: null };
+                const base = {
                     contract_version: JUDGMENT_HISTORY_CONTRACT_VERSION,
-                    status: source.status,
+                    status,
                     records: null,
-                    coverage: { ...source.coverage, total: null },
+                    coverage: baseCoverage,
                     pagination: { cursor: query.cursor, next_cursor: null, limit: query.limit, has_more: false },
                     filters
                 };
+                const filtered = records.filter((record) => {
+                    if (query.project !== null && record.project_code !== query.project)
+                        return false;
+                    if (query.entrypoint !== null && record.entrypoint !== query.entrypoint)
+                        return false;
+                    if (start && Date.parse(record.recorded_at) < start.getTime())
+                        return false;
+                    return true;
+                });
+                const filter = filterKey(query, start, anchor);
+                const offset = query.cursor ? decodeCursor(query.cursor, filter, source.snapshot_id) : 0;
+                const page = filtered.slice(offset, offset + query.limit);
+                const hasMore = offset + page.length < filtered.length;
+                const nextCursor = hasMore ? encodeCursor({ filter, snapshot: source.snapshot_id, offset: offset + page.length }) : null;
+                const coverage = {
+                    ...baseCoverage,
+                    total: baseCoverage.complete ? filtered.length : null
+                };
+                return {
+                    ...base,
+                    records: page,
+                    coverage,
+                    pagination: { cursor: query.cursor, next_cursor: nextCursor, limit: query.limit, has_more: hasMore }
+                };
             }
-            let scopeUnverified = false;
-            if (query.project === null && options.authorizeProject) {
-                const visible = [];
-                for (const record of records) {
-                    // A record without a trusted project binding must never enter a
-                    // scoped aggregate, because its owner cannot be authorized.
-                    if (record.project_code === null) {
-                        scopeUnverified = true;
-                        continue;
-                    }
-                    if (await options.authorizeProject(record.project_code))
-                        visible.push(record);
-                }
-                records = visible;
+            finally {
+                remember(readStarted, pageStarted, loaded.sourceTimings);
             }
-            const effectiveNow = now();
-            const start = periodStart(query.period, effectiveNow);
-            const anchor = query.period === 'all' ? null : startOfJstDay(effectiveNow);
-            const status = scopeUnverified && source.status === 'available' ? 'partial' : source.status;
-            const baseCoverage = scopeUnverified
-                ? { ...source.coverage, complete: false, reason: 'project_scope_unverified', total: null }
-                : { ...source.coverage, total: null };
-            const base = {
-                contract_version: JUDGMENT_HISTORY_CONTRACT_VERSION,
-                status,
-                records: null,
-                coverage: baseCoverage,
-                pagination: { cursor: query.cursor, next_cursor: null, limit: query.limit, has_more: false },
-                filters
-            };
-            const filtered = records.filter((record) => {
-                if (query.project !== null && record.project_code !== query.project)
-                    return false;
-                if (query.entrypoint !== null && record.entrypoint !== query.entrypoint)
-                    return false;
-                if (start && Date.parse(record.recorded_at) < start.getTime())
-                    return false;
-                return true;
-            });
-            const filter = filterKey(query, start, anchor);
-            const offset = query.cursor ? decodeCursor(query.cursor, filter, source.snapshot_id) : 0;
-            const page = filtered.slice(offset, offset + query.limit);
-            const hasMore = offset + page.length < filtered.length;
-            const nextCursor = hasMore ? encodeCursor({ filter, snapshot: source.snapshot_id, offset: offset + page.length }) : null;
-            const coverage = {
-                ...baseCoverage,
-                total: baseCoverage.complete ? filtered.length : null
-            };
-            return {
-                ...base,
-                records: page,
-                coverage,
-                pagination: { cursor: query.cursor, next_cursor: nextCursor, limit: query.limit, has_more: hasMore }
-            };
         },
         async detail(recordId) {
             const safeRecordId = safeId(recordId);
             if (!safeRecordId)
                 throw new JudgmentHistoryReaderError(400, 'invalid_record_id', 'record_id is invalid');
-            const source = buildSourceSnapshot(await options.source.read());
-            if (source.status === 'unavailable' || source.records === null) {
+            const readStarted = performance.now();
+            const loaded = await takeSource();
+            const source = loaded.source;
+            const pageStarted = performance.now();
+            try {
+                if (source.status === 'unavailable' || source.records === null) {
+                    return {
+                        contract_version: JUDGMENT_HISTORY_CONTRACT_VERSION,
+                        status: source.status,
+                        record: null,
+                        coverage: source.coverage
+                    };
+                }
+                const record = source.records.find((candidate) => candidate.record_id === safeRecordId) ?? null;
+                if (record && options.authorizeProject) {
+                    if (record.project_code === null || !(await options.authorizeProject(record.project_code))) {
+                        throw new JudgmentHistoryReaderError(403, 'project_scope_forbidden', 'record is outside the trusted scope');
+                    }
+                }
                 return {
                     contract_version: JUDGMENT_HISTORY_CONTRACT_VERSION,
                     status: source.status,
-                    record: null,
-                    coverage: source.coverage
+                    record,
+                    coverage: { ...source.coverage, total: source.coverage.complete ? source.records.length : null }
                 };
             }
-            const record = source.records.find((candidate) => candidate.record_id === safeRecordId) ?? null;
-            if (record && options.authorizeProject) {
-                if (record.project_code === null || !(await options.authorizeProject(record.project_code))) {
-                    throw new JudgmentHistoryReaderError(403, 'project_scope_forbidden', 'record is outside the trusted scope');
+            finally {
+                remember(readStarted, pageStarted, loaded.sourceTimings);
+            }
+        },
+        async findByResolutionIds(resolutionIds) {
+            if (!Array.isArray(resolutionIds) || resolutionIds.length < 1 || resolutionIds.length > MAX_JUDGMENT_HISTORY_RESOLUTION_BATCH) {
+                throw new JudgmentHistoryReaderError(400, 'invalid_resolution_ids', `resolution ids must contain between 1 and ${MAX_JUDGMENT_HISTORY_RESOLUTION_BATCH} ids`);
+            }
+            const ids = resolutionIds.map((id) => {
+                const safe = safeId(id);
+                if (!safe)
+                    throw new JudgmentHistoryReaderError(400, 'invalid_resolution_id', 'resolution id is invalid');
+                return safe;
+            });
+            const readStarted = performance.now();
+            const loaded = await takeSource();
+            const source = loaded.source;
+            const pageStarted = performance.now();
+            try {
+                if (source.status === 'unavailable' || source.records === null) {
+                    return {
+                        contract_version: JUDGMENT_HISTORY_CONTRACT_VERSION,
+                        status: source.status,
+                        records: ids.map(() => null),
+                        coverage: source.coverage
+                    };
+                }
+                const byId = new Map(source.records.map((record) => [record.record_id, record]));
+                const records = [];
+                for (const id of ids) {
+                    const record = byId.get(id) ?? null;
+                    if (!record || !options.authorizeProject) {
+                        records.push(record);
+                        continue;
+                    }
+                    // A forbidden or unbound project is indistinguishable from a missing id.
+                    const allowed = record.project_code !== null && await options.authorizeProject(record.project_code);
+                    records.push(allowed ? record : null);
                 }
+                return {
+                    contract_version: JUDGMENT_HISTORY_CONTRACT_VERSION,
+                    status: source.status,
+                    records,
+                    coverage: { ...source.coverage, total: source.coverage.complete ? source.records.length : null }
+                };
+            }
+            finally {
+                remember(readStarted, pageStarted, loaded.sourceTimings);
             }
-            return {
-                contract_version: JUDGMENT_HISTORY_CONTRACT_VERSION,
-                status: source.status,
-                record,
-                coverage: { ...source.coverage, total: source.coverage.complete ? source.records.length : null }
-            };
         }
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unson/brainbase-mcp",
-  "version": "0.41.3",
+  "version": "0.41.6",
   "description": "Local-first Brainbase judgment OS that lets supported AI agents reuse a user's approved goals, priorities, decisions, and judgment criteria.",
   "type": "module",
   "license": "MIT",
@@ -483,5 +483,5 @@
   "engines": {
     "node": ">=20"
   },
-  "gitHead": "19cc7821541c7e563e4d08fd4b2b09936e80a701"
+  "gitHead": "0c67baf7d7c57f4f671c966c8053705af65ba4d0"
 }

package/ui/brainbase-tokens.css

@@ -62,6 +62,10 @@
   --bb-color-notice-control-border: #ffffff45;
   --bb-color-inline-error: #9b3d3d;
   --bb-color-record-missing: #80601c;
+  --bb-color-drawer-overlay: rgb(13 25 46 / 6%);
+  --bb-color-drawer-overlay-clear: rgb(13 25 46 / 0%);
+  --bb-shadow-drawer: -18px 0 48px rgb(13 25 46 / 10%);
+  --bb-shadow-popover: 0 8px 28px rgb(13 25 46 / 14%);
   --bb-color-dialog-overlay: #0d192e66;
   --bb-color-scrollbar-rgb: 36,50,75;
   --bb-color-scrollbar-dark-rgb: 203,212,225;