@unson/brainbase-mcp 0.41.3 → 0.41.6

package/dist/judgment-history-http.js

@@ -1,8 +1,19 @@
-import { JUDGMENT_HISTORY_ENTRYPOINTS, createJudgmentHistoryReader, JudgmentHistoryFeedbackConflictError } from './judgment-history.js';
+import { JUDGMENT_HISTORY_ENTRYPOINTS, MAX_JUDGMENT_HISTORY_RESOLUTION_BATCH, createJudgmentHistoryReader, judgmentHistoryRequestTimings, JudgmentHistoryFeedbackConflictError, withJudgmentHistoryRequestTimings } from './judgment-history.js';
 import { LocalWebHttpError, readJsonObjectBody, writeJson } from './local-web-security.js';
 export const JUDGMENT_HISTORY_HTTP_VERSION = 'judgment-history-http.v1';
 export const JUDGMENT_HISTORY_HTTP_PREFIX = '/api/judgment-history';
 export const JUDGMENT_HISTORY_FEEDBACK_BODY_LIMIT_BYTES = 64 * 1024;
+function serverTimingHeader(timings, handlerMs) {
+    const parts = [`total;dur=${handlerMs.toFixed(1)}`];
+    if (timings) {
+        parts.push(`journal;dur=${timings.journal_ms.toFixed(1)}`);
+        parts.push(`page;dur=${timings.page_ms.toFixed(1)}`);
+        parts.push(`cache;desc="hits=${timings.cache_hits},misses=${timings.cache_misses}"`);
+        parts.push(`parallel;desc="${timings.parallel_limit}"`);
+    }
+    parts.push('order;desc="newest-first"');
+    return parts.join(', ');
+}
 function methodNotAllowed() {
     const error = new Error('Use GET or POST');
     error.statusCode = 405;
@@ -14,6 +25,8 @@ function matchRoute(pathname, basePath) {
         return { name: 'home' };
     if (pathname === `${basePath}/feedback`)
         return { name: 'feedback' };
+    if (pathname === `${basePath}/resolutions`)
+        return { name: 'resolutions' };
     if (!pathname.startsWith(`${basePath}/records/`))
         return null;
     const encoded = pathname.slice(`${basePath}/records/`.length);
@@ -48,6 +61,17 @@ function readerError(statusCode, code, message) {
     error.code = code;
     return error;
 }
+function parseResolutionIds(url) {
+    for (const key of url.searchParams.keys()) {
+        if (key !== 'id')
+            throw readerError(400, 'unknown_query', `Unknown query parameter: ${key}`);
+    }
+    const ids = url.searchParams.getAll('id');
+    if (ids.length < 1 || ids.length > MAX_JUDGMENT_HISTORY_RESOLUTION_BATCH) {
+        throw readerError(400, 'invalid_resolution_ids', `id must be repeated between 1 and ${MAX_JUDGMENT_HISTORY_RESOLUTION_BATCH} times`);
+    }
+    return ids;
+}
 function parseQuery(url) {
     const allowed = new Set(['period', 'project', 'entrypoint', 'cursor', 'limit']);
     for (const key of url.searchParams.keys()) {
@@ -90,7 +114,18 @@ export function createJudgmentHistoryHttpHandler(options) {
     }
     const basePath = (options.basePath ?? JUDGMENT_HISTORY_HTTP_PREFIX).replace(/\/+$/u, '');
     const reader = options.reader;
-    return async (request, response) => {
+    return (request, response) => withJudgmentHistoryRequestTimings(async () => {
+        const started = performance.now();
+        const writeTimed = (statusCode, body) => {
+            if (!response.headersSent) {
+                const scoped = judgmentHistoryRequestTimings();
+                const timings = scoped.bound
+                    ? scoped.timings
+                    : (typeof reader.timings === 'function' ? reader.timings() : null);
+                response.setHeader('Server-Timing', serverTimingHeader(timings, performance.now() - started));
+            }
+            writeJson(response, statusCode, body);
+        };
         const url = new URL(request.url ?? '/', 'http://localhost');
         let route;
         try {
@@ -98,7 +133,7 @@ export function createJudgmentHistoryHttpHandler(options) {
         }
         catch (error) {
             const normalized = toError(error);
-            writeJson(response, normalized.statusCode, {
+            writeTimed(normalized.statusCode, {
                 error: { code: normalized.code, message: normalized.message }
             });
             return true;
@@ -125,24 +160,30 @@ export function createJudgmentHistoryHttpHandler(options) {
                     feedback_event: result.event,
                     ...result.event
                 };
-                writeJson(response, result.created ? 201 : 200, responseBody);
+                writeTimed(result.created ? 201 : 200, responseBody);
             }
             else {
                 if (request.method !== 'GET')
                     throw methodNotAllowed();
-                if (route.name === 'home') {
-                    writeJson(response, 200, await reader.home(parseQuery(url)));
+                if (route.name === 'resolutions') {
+                    if (typeof reader.findByResolutionIds !== 'function') {
+                        throw readerError(501, 'resolution_batch_unavailable', 'This reader cannot look up resolution ids in one read');
+                    }
+                    writeTimed(200, await reader.findByResolutionIds(parseResolutionIds(url)));
+                }
+                else if (route.name === 'home') {
+                    writeTimed(200, await reader.home(parseQuery(url)));
                 }
                 else {
                     const result = await reader.detail(route.recordId);
                     if (result.status === 'unavailable') {
-                        writeJson(response, 200, result);
+                        writeTimed(200, result);
                     }
                     else if (result.status === 'available' && !result.record) {
                         throw readerError(404, 'judgment_history_not_found', 'No judgment history record matches this id');
                     }
                     else {
-                        writeJson(response, 200, result);
+                        writeTimed(200, result);
                     }
                 }
             }
@@ -150,19 +191,19 @@ export function createJudgmentHistoryHttpHandler(options) {
         catch (error) {
             const normalized = toError(error);
             if (error instanceof JudgmentHistoryFeedbackConflictError) {
-                writeJson(response, normalized.statusCode, {
+                writeTimed(normalized.statusCode, {
                     error: { code: normalized.code, message: normalized.message },
                     feedback_event: error.existing
                 });
             }
             else {
-                writeJson(response, normalized.statusCode, {
+                writeTimed(normalized.statusCode, {
                     error: { code: normalized.code, message: normalized.message }
                 });
             }
         }
         return true;
-    };
+    });
 }
 /** Convenience composition seam for adapters that want the HTTP contract without a local journal. */
 export function createJudgmentHistoryHttpReader(options) {

package/dist/judgment-history.d.ts

@@ -85,11 +85,34 @@ export interface JudgmentHistorySourceSnapshot {
     readonly coverage: JudgmentHistoryCoverage;
     /** Stable source revision used to bind pagination cursors. */
     readonly snapshot_id?: string;
+    /** Measurements for this read. Concurrent reads each carry their own. */
+    readonly timings?: JudgmentHistoryReadTimings;
+}
+export interface JudgmentHistoryReadTimings {
+    /** Wall time of the latest home, detail, or batch read, including paging. */
+    readonly total_ms: number;
+    /** Time spent discovering and reading journal artifacts. */
+    readonly journal_ms: number;
+    /** Time spent filtering and slicing the newest-first page. */
+    readonly page_ms: number;
+    readonly cache_hits: number;
+    readonly cache_misses: number;
+    readonly parallel_limit: number;
+    readonly scanned_files: number;
 }
 export interface JudgmentHistorySource {
     readonly storage: JudgmentHistoryStorage;
     readonly read: () => Promise<JudgmentHistorySourceSnapshot>;
-}
+    /** Timings of the latest completed `read`. Overlapping reads use `snapshot.timings`. */
+    readonly timings?: () => JudgmentHistoryReadTimings | null;
+}
+/** Isolates Server-Timing for one HTTP request from other in-flight reads. */
+export declare function withJudgmentHistoryRequestTimings<T>(fn: () => Promise<T>): Promise<T>;
+/** Timings published by the in-flight request, when one is bound. */
+export declare function judgmentHistoryRequestTimings(): {
+    readonly bound: boolean;
+    readonly timings: JudgmentHistoryReadTimings | null;
+};
 export interface JudgmentHistoryQuery {
     readonly period?: JudgmentHistoryPeriod;
     readonly project?: string;
@@ -128,9 +151,18 @@ export interface JudgmentHistoryReaderOptions {
     /** Organization adapters provide trusted scope authorization here. */
     readonly authorizeProject?: (project: string) => boolean | Promise<boolean>;
 }
+export interface JudgmentHistoryResolutionBatch {
+    readonly contract_version: typeof JUDGMENT_HISTORY_CONTRACT_VERSION;
+    readonly status: JudgmentHistoryStatus;
+    readonly records: readonly (JudgmentHistoryRecord | null)[];
+    readonly coverage: JudgmentHistoryCoverage;
+}
 export interface JudgmentHistoryReader {
     readonly home: (query?: JudgmentHistoryQuery) => Promise<JudgmentHistoryHome>;
     readonly detail: (recordId: string) => Promise<JudgmentHistoryDetail>;
+    /** One journal read for many resolution ids. `records` keeps the request order. */
+    readonly findByResolutionIds: (resolutionIds: readonly string[]) => Promise<JudgmentHistoryResolutionBatch>;
+    readonly timings: () => JudgmentHistoryReadTimings | null;
 }
 export declare class JudgmentHistoryReaderError extends Error {
     readonly statusCode: number;
@@ -144,7 +176,34 @@ export interface LocalJudgmentHistorySourceOptions {
     readonly max_files?: number;
     /** Maximum size of one journal artifact, in bytes. */
     readonly max_record_bytes?: number;
-}
+    /** Maximum journal artifact reads in flight. */
+    readonly read_parallel?: number;
+    /** Reuses parsed artifacts while (session, turn, mtime) is unchanged. */
+    readonly cache?: JudgmentHistoryJournalScanCache;
+}
+export declare const DEFAULT_LOCAL_JUDGMENT_HISTORY_READ_PARALLEL = 8;
+export declare const MAX_JUDGMENT_HISTORY_RESOLUTION_BATCH = 100;
+/** Parsed artifacts kept for one local source. The oldest entry is dropped past this. */
+export declare const DEFAULT_JUDGMENT_HISTORY_JOURNAL_CACHE_LIMIT = 4096;
+/**
+ * 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 declare class JudgmentHistoryJournalScanCache {
+    #private;
+    constructor(limit?: number);
+    get limit(): number;
+    get size(): number;
+    lookup(session: string, turn: string, fileName: string, mtimeNs: bigint): BoundedJsonResult | null;
+    store(session: string, turn: string, fileName: string, mtimeNs: bigint, result: BoundedJsonResult): void;
+    noteMiss(): void;
+    get hits(): number;
+    get misses(): number;
+}
+/** Runs `map` with at most `limit` calls in flight. Results keep input order. */
+export declare function mapWithConcurrencyLimit<T, R>(items: readonly T[], limit: number, map: (item: T, index: number) => Promise<R>): Promise<R[]>;
 export interface LocalJudgmentHistoryFeedbackWriterOptions {
     readonly root: string;
     readonly reader: JudgmentHistoryReader;
@@ -160,9 +219,17 @@ export declare class JudgmentHistoryFeedbackConflictError extends JudgmentHistor
     readonly existing: JudgmentHistoryFeedbackEvent;
     constructor(existing: JudgmentHistoryFeedbackEvent);
 }
+interface JsonObject {
+    [key: string]: unknown;
+}
 export declare const DEFAULT_LOCAL_JUDGMENT_HISTORY_SCAN_CAP = 4096;
 export declare const DEFAULT_LOCAL_JUDGMENT_HISTORY_RECORD_BYTES: number;
 export declare function canonicalJson(value: unknown): string;
+interface BoundedJsonResult {
+    readonly value: JsonObject | null;
+    readonly missing: boolean;
+    readonly invalid: boolean;
+}
 /** Reads only the configured local owner journal; it never searches or uploads another journal. */
 export declare function createLocalJudgmentHistorySource(options: LocalJudgmentHistorySourceOptions): JudgmentHistorySource;
 /**
@@ -176,3 +243,4 @@ export declare function appendLocalJudgmentHistoryFeedback(options: LocalJudgmen
 }): Promise<JudgmentHistoryFeedbackWriteResult>;
 /** Reader shared by local, organization, Mana, and Company OS adapters. */
 export declare function createJudgmentHistoryReader(options: JudgmentHistoryReaderOptions): JudgmentHistoryReader;
+export {};