bantamkit-mcp 0.35.7 → 0.35.9

package/dist/mcp/transport.d.ts

@@ -10,13 +10,13 @@
  *    The SDK exposes no hook for this — `ReadBuffer.readMessage` parses inside the buffer and
  *    the buffer is private — so the buffering is done here instead. It is thirty lines
  *    (`indexOf('\n')`, strip a trailing `\r`) and it keeps the LINE next to the parsed
- *    message, keyed by JSON-RPC id. A handler then re-reads its own arguments with
+ *    message, keyed PER MESSAGE (see 3). A handler then re-reads its own arguments with
  *    `pyjson.parseJson`, which tags `5.0` as a float and keeps an integer past 2^53 exact.
  *
  * 2. THE OUTGOING NUMBER LITERALS AND THE ENVELOPE ORDER. `serializeMessage` is
  *    `JSON.stringify(message) + '\n'`, which un-does the work above on the way out: the same
  *    `5.0` in a `structuredContent` leaves as `5`. So a tool handler registers the EXACT text
- *    of its result here, keyed by request id, and `send` splices it in. Everything else still
+ *    of its result here, keyed per message, and `send` splices it in. Everything else still
  *    goes through `JSON.stringify`, which is byte-for-byte what pydantic-core writes for
  *    strings, bools, nulls and safe integers.
  *
@@ -25,6 +25,30 @@
  *    order is not observable to a conforming client, but it costs nothing here and it removes
  *    a difference from the list rather than adding a ruling to it.
  *
+ * 3. ONE ENTRY PER MESSAGE, NOT PER ID (#146, #148). The side table used to be keyed by the
+ *    client's id, so two requests in flight under ONE id (JSON-RPC forbids it; a client can
+ *    still do it) shared one slot: the second line overwrote the first and both answers were
+ *    computed from the second request's arguments. And the SDK's schema refuses an integer id
+ *    past 2^53 (`JSON.parse` has already rounded it), so such a request got no answer at all.
+ *    Both are fixed the same way: every request is handed to the SDK under a TOKEN of this
+ *    file's own (`bantamkit-<n>`, unique per message), and the client's id is kept as the
+ *    exact TEXT it arrived as, read losslessly with `pyjson.parseJson`; `send` writes that
+ *    text back. The reference answers each request from its own arguments and echoes a big
+ *    id exactly, so this is the port catching up, not a choice. A `notifications/cancelled`
+ *    naming a client id is pointed at the newest token carrying it.
+ *
+ * 4. A FRAME THE SDK WOULD DROP IS ANSWERED (#148). A line that is not JSON is answered
+ *    `-32700 Parse error`, and JSON that is not a JSON-RPC message (a batch array, a bare
+ *    number, a message with no `jsonrpc`) `-32600 Invalid Request`, both with `id: null`
+ *    as JSON-RPC 2.0 section 5.1 requires, and both in the bytes `mcpstdio.py` writes. Before,
+ *    both went to `onerror` and the client waited forever. A blank line is still skipped.
+ *
+ * 5. A HOST THAT CLOSED ITS READ END ENDS THE SESSION QUIETLY (#181). `process.stdout` had no
+ *    `error` listener, so an EPIPE mid-answer was an unhandled `error` event: exit 1 and a
+ *    stack. It is now what stdin EOF already was, the host going away: the transport closes,
+ *    stdin is released, and the process exits 0 with nothing on stderr. Any OTHER write error
+ *    is rethrown and still crashes, because it is not that.
+ *
  * NOTHING IN THIS FILE WRITES TO STDOUT EXCEPT `send`. That is the invariant the whole
  * package is under, and it is checked by `test/server.test.mjs`, which asserts that every
  * line a real session produced parses as a frame and that stdout never ends mid-line.
@@ -33,6 +57,12 @@ import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
 import type { JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js';
 type Readable = NodeJS.ReadableStream;
 type Writable = NodeJS.WritableStream;
+/**
+ * The two frames JSON-RPC 2.0 section 5.1 prescribes for a message no id can be read from,
+ * byte for byte what `mcpstdio.py` writes (`JSONRPCError(id=None, ...)` dumped by the SDK).
+ */
+export declare const PARSE_ERROR_FRAME = "{\"jsonrpc\":\"2.0\",\"id\":null,\"error\":{\"code\":-32700,\"message\":\"Parse error\"}}";
+export declare const INVALID_REQUEST_FRAME = "{\"jsonrpc\":\"2.0\",\"id\":null,\"error\":{\"code\":-32600,\"message\":\"Invalid Request\"}}";
 export declare class RawStdioTransport implements Transport {
     private readonly input;
     private readonly output;
@@ -42,18 +72,31 @@ export declare class RawStdioTransport implements Transport {
     sessionId?: string;
     private buffer;
     private started;
-    private readonly rawLines;
-    private readonly exactResults;
+    private outputGone;
+    private sequence;
+    /** Token (the id the SDK sees) -> the request it stands for. One entry per MESSAGE. */
+    private readonly inFlight;
+    /** Client id text -> the newest token carrying it, for `notifications/cancelled`. */
+    private readonly newest;
     private readonly ondata;
     private readonly onstreamerror;
+    private readonly onoutputerror;
     constructor(input?: Readable, output?: Writable);
-    /** The verbatim request line that carried this id, or `undefined` if it is gone. */
+    /** The verbatim request line this message token stands for, or `undefined` if it is gone. */
     rawLineFor(id: unknown): string | undefined;
-    /** Register the exact JSON text to send as this request's `result`. */
+    /**
+     * #147: whether the reference would refuse this request's params on its `_meta` alone, a
+     * member the TS SDK checks in its ENVELOPE schema and the reference only per method.
+     */
+    paramsRefused(id: unknown): boolean;
+    /** Register the exact JSON text to send as this message's `result`. */
     setExactResult(id: unknown, json: string): void;
     start(): Promise<void>;
     close(): Promise<void>;
     send(message: JSONRPCMessage): Promise<void>;
+    private write;
+    /** Answer a line no id could be read from, in order with every other frame. */
+    private refuse;
     /**
      * One frame, in the reference's key order, with an exact `result` when one was registered.
      *
@@ -64,5 +107,7 @@ export declare class RawStdioTransport implements Transport {
      */
     private frame;
     private consume;
+    /** Point a `notifications/cancelled` at the token now standing for the id it names. */
+    private retarget;
 }
 export {};

package/dist/mcp/transport.js

@@ -1,7 +1,37 @@
 import { JSONRPCMessageSchema } from '@modelcontextprotocol/sdk/types.js';
 import { PY_LINESEP } from '../memory/pyfs.js';
-/** A JSON-RPC id is a string or a number; the map key is its JSON text, which is total. */
-const idKey = (id) => JSON.stringify(id ?? null);
+import { parseJson } from '../pyjson.js';
+/**
+ * The two frames JSON-RPC 2.0 section 5.1 prescribes for a message no id can be read from,
+ * byte for byte what `mcpstdio.py` writes (`JSONRPCError(id=None, ...)` dumped by the SDK).
+ */
+export const PARSE_ERROR_FRAME = '{"jsonrpc":"2.0","id":null,"error":{"code":-32700,"message":"Parse error"}}';
+export const INVALID_REQUEST_FRAME = '{"jsonrpc":"2.0","id":null,"error":{"code":-32600,"message":"Invalid Request"}}';
+/** The write errors that mean the reader of stdout is gone, on POSIX and on Windows (libuv EOF). */
+const HOST_GONE = new Set(['EPIPE', 'ECONNRESET', 'EOF', 'ERR_STREAM_DESTROYED']);
+/**
+ * The client's id as the exact JSON text to echo, or `undefined` when it is not one a
+ * JSON-RPC id may be. A string is re-serialised (`JSON.stringify` is pydantic-core's string
+ * spelling); a number is read again LOSSLESSLY, because `JSON.parse` has already rounded an
+ * integer past 2^53 and cannot tell `1.0` from `1`. The reference's `RequestId` is a STRICT
+ * int or a str, so a float literal is no id at all there either.
+ */
+function clientIdText(line, id) {
+    if (typeof id === 'string')
+        return JSON.stringify(id);
+    if (typeof id !== 'number')
+        return undefined;
+    try {
+        const frame = parseJson(line);
+        const value = frame.t === 'dict' ? frame.v.get('id') : undefined;
+        return value?.t === 'int' ? value.v.toString() : undefined;
+    }
+    catch {
+        return Number.isSafeInteger(id) ? String(id) : undefined;
+    }
+}
+/** The JSON text of an id named INSIDE a message (a cancellation's `requestId`). */
+const namedIdText = (id) => typeof id === 'string' ? JSON.stringify(id) : Number.isSafeInteger(id) ? String(id) : undefined;
 export class RawStdioTransport {
     input;
     output;
@@ -11,21 +41,45 @@ export class RawStdioTransport {
     sessionId;
     buffer = Buffer.alloc(0);
     started = false;
-    rawLines = new Map();
-    exactResults = new Map();
+    outputGone = false;
+    sequence = 0;
+    /** Token (the id the SDK sees) -> the request it stands for. One entry per MESSAGE. */
+    inFlight = new Map();
+    /** Client id text -> the newest token carrying it, for `notifications/cancelled`. */
+    newest = new Map();
     ondata = (chunk) => this.consume(chunk);
     onstreamerror = (error) => this.onerror?.(error);
+    onoutputerror = (error) => {
+        if (!HOST_GONE.has(error.code ?? ''))
+            throw error;
+        if (this.outputGone)
+            return;
+        this.outputGone = true;
+        // The host is gone, so nothing will ever read another answer: stop reading too, or a
+        // stdin the host left open would keep the process alive with nowhere to write.
+        this.input.destroy?.();
+        void this.close();
+    };
     constructor(input = process.stdin, output = process.stdout) {
         this.input = input;
         this.output = output;
     }
-    /** The verbatim request line that carried this id, or `undefined` if it is gone. */
+    /** The verbatim request line this message token stands for, or `undefined` if it is gone. */
     rawLineFor(id) {
-        return this.rawLines.get(idKey(id));
+        return typeof id === 'string' ? this.inFlight.get(id)?.line : undefined;
+    }
+    /**
+     * #147: whether the reference would refuse this request's params on its `_meta` alone, a
+     * member the TS SDK checks in its ENVELOPE schema and the reference only per method.
+     */
+    paramsRefused(id) {
+        return typeof id === 'string' && this.inFlight.get(id)?.paramsRefused === true;
     }
-    /** Register the exact JSON text to send as this request's `result`. */
+    /** Register the exact JSON text to send as this message's `result`. */
     setExactResult(id, json) {
-        this.exactResults.set(idKey(id), json);
+        const entry = typeof id === 'string' ? this.inFlight.get(id) : undefined;
+        if (entry !== undefined)
+            entry.exact = json;
     }
     async start() {
         if (this.started)
@@ -33,6 +87,7 @@ export class RawStdioTransport {
         this.started = true;
         this.input.on('data', this.ondata);
         this.input.on('error', this.onstreamerror);
+        this.output.on('error', this.onoutputerror);
     }
     async close() {
         this.input.off('data', this.ondata);
@@ -40,13 +95,19 @@ export class RawStdioTransport {
         if (this.input.listenerCount('data') === 0)
             this.input.pause();
         this.buffer = Buffer.alloc(0);
-        this.rawLines.clear();
-        this.exactResults.clear();
+        this.inFlight.clear();
+        this.newest.clear();
         this.onclose?.();
     }
     send(message) {
+        return this.write(this.frame(message));
+    }
+    write(text) {
         return new Promise((resolve) => {
-            const text = this.frame(message);
+            if (this.outputGone) {
+                resolve();
+                return;
+            }
             // `os.linesep`, because the reference's stdout is a TEXT stream. The Python SDK writes
             // its frames through `TextIOWrapper(sys.stdout.buffer)` with the default
             // `newline=None`, so on Windows every frame CPython emits ends `\r\n`. MEASURED, run
@@ -59,6 +120,10 @@ export class RawStdioTransport {
                 this.output.once('drain', () => resolve());
         });
     }
+    /** Answer a line no id could be read from, in order with every other frame. */
+    refuse(frame) {
+        void this.write(frame);
+    }
     /**
      * One frame, in the reference's key order, with an exact `result` when one was registered.
      *
@@ -69,17 +134,18 @@ export class RawStdioTransport {
      */
     frame(message) {
         const framed = message;
-        if (framed.id === undefined)
+        if (framed.id === undefined || 'method' in framed)
             return JSON.stringify(message);
-        const key = idKey(framed.id);
-        this.rawLines.delete(key);
-        const id = JSON.stringify(framed.id);
+        const entry = typeof framed.id === 'string' ? this.inFlight.get(framed.id) : undefined;
+        if (entry !== undefined) {
+            this.inFlight.delete(framed.id);
+            if (this.newest.get(entry.idText) === framed.id)
+                this.newest.delete(entry.idText);
+        }
+        const id = entry?.idText ?? JSON.stringify(framed.id);
         if ('result' in framed) {
-            const exact = this.exactResults.get(key);
-            this.exactResults.delete(key);
-            return `{"jsonrpc":"2.0","id":${id},"result":${exact ?? JSON.stringify(framed.result)}}`;
+            return `{"jsonrpc":"2.0","id":${id},"result":${entry?.exact ?? JSON.stringify(framed.result)}}`;
         }
-        this.exactResults.delete(key);
         if ('error' in framed)
             return `{"jsonrpc":"2.0","id":${id},"error":${JSON.stringify(framed.error)}}`;
         return JSON.stringify(message);
@@ -94,18 +160,143 @@ export class RawStdioTransport {
             this.buffer = this.buffer.subarray(at + 1);
             if (line.trim() === '')
                 continue;
-            let message;
+            let parsed;
             try {
-                message = JSONRPCMessageSchema.parse(JSON.parse(line));
+                parsed = JSON.parse(line);
+            }
+            catch {
+                this.refuse(PARSE_ERROR_FRAME);
+                continue;
             }
-            catch (error) {
-                this.onerror?.(error);
+            // A LONE SURROGATE is text `JSON.parse` keeps and pydantic's parser refuses, so the
+            // reference's SDK cannot read such a frame at all; `mcpstdio.py` answers it `-32600`
+            // (the standard library CAN read it). The one exception is job65/#160's: a `tools/call`
+            // carrying one in its arguments is refused BY NAME, which the server does here too.
+            if (LONE_ESCAPE.test(line) && holdsLoneSurrogate(parsed) && !refusedByName(line, parsed)) {
+                this.refuse(INVALID_REQUEST_FRAME);
                 continue;
             }
-            const id = message.id;
-            if (id !== undefined)
-                this.rawLines.set(idKey(id), line);
+            // The reference's adapter is pydantic, which IGNORES a member it has no field for and
+            // takes `params: null` as no params; the TS SDK's schemas are strict and refuse both.
+            // Measured on both SDKs (J66-3 note): normalised here, so a frame the reference answers
+            // is not one the port calls an Invalid Request.
+            if (isObject(parsed)) {
+                for (const key of Object.keys(parsed))
+                    if (!MESSAGE_KEYS.has(key))
+                        delete parsed[key];
+                if (parsed['params'] === null)
+                    delete parsed['params'];
+            }
+            // A REQUEST (an object with an id and a method) travels under a token of this file's
+            // own; its client id is kept as text. Anything else goes to the SDK's schema unchanged.
+            let token;
+            let idText;
+            if (isObject(parsed) && 'id' in parsed && 'method' in parsed) {
+                idText = clientIdText(line, parsed['id']);
+                if (idText === undefined) {
+                    // Not a str and not an int (`null`, `1.0`, `true`): the reference's `RequestId`
+                    // refuses it, and its union then reads the frame as a NOTIFICATION with the id
+                    // ignored, so nothing is answered. Measured; the port does the same.
+                    delete parsed['id'];
+                }
+                else {
+                    token = `bantamkit-${++this.sequence}`;
+                    parsed['id'] = token;
+                }
+            }
+            let message;
+            let paramsRefused = false;
+            try {
+                message = JSONRPCMessageSchema.parse(parsed);
+            }
+            catch {
+                // #147: the TS SDK's envelope checks a request's `params._meta`; the reference's
+                // envelope takes any object as params and checks `_meta` with the METHOD's model,
+                // so `_meta: 5` is -32602 with the client's id there (and `_meta: null` or a
+                // `progressToken: true` is served), where this used to be -32600 with id null. A
+                // request the envelope takes once `_meta` is set aside travels on without it, and
+                // `server.ts`'s guard refuses it -32602 if the reference's model would have.
+                const params = token !== undefined && isObject(parsed) ? parsed['params'] : undefined;
+                const withoutMeta = isObject(params) && '_meta' in params ? withoutKey(parsed, params) : undefined;
+                const retry = withoutMeta === undefined ? undefined : JSONRPCMessageSchema.safeParse(withoutMeta);
+                if (retry === undefined || !retry.success) {
+                    this.refuse(INVALID_REQUEST_FRAME);
+                    continue;
+                }
+                message = retry.data;
+                paramsRefused = !referenceTakesMeta(params['_meta']);
+            }
+            if (token !== undefined && idText !== undefined) {
+                this.inFlight.set(token, paramsRefused ? { idText, line, paramsRefused } : { idText, line });
+                this.newest.set(idText, token);
+            }
+            else {
+                this.retarget(message);
+            }
             this.onmessage?.(message);
         }
     }
+    /** Point a `notifications/cancelled` at the token now standing for the id it names. */
+    retarget(message) {
+        const note = message;
+        if (note.method !== 'notifications/cancelled' || note.params === undefined)
+            return;
+        const named = namedIdText(note.params.requestId);
+        const token = named === undefined ? undefined : this.newest.get(named);
+        if (token !== undefined)
+            note.params.requestId = token;
+    }
+}
+/** Only a line spelling a surrogate escape can hold a lone surrogate (`mcpstdio._ESCAPE`). */
+const LONE_ESCAPE = /\\u[dD][89a-fA-F][0-9a-fA-F]{2}/;
+const LONE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+/** Whether any string in the value, member names included, holds a lone surrogate. */
+function holdsLoneSurrogate(value) {
+    if (typeof value === 'string')
+        return LONE.test(value);
+    if (Array.isArray(value))
+        return value.some(holdsLoneSurrogate);
+    if (isObject(value))
+        return Object.entries(value).some(([key, item]) => LONE.test(key) || holdsLoneSurrogate(item));
+    return false;
+}
+/**
+ * `mcpstdio.refusal_for`'s test, less the roster: a `tools/call` with a str or int id whose
+ * `arguments` object holds a lone surrogate goes on to the server, which refuses it by name
+ * (`pyargs.loneSurrogateArgument`). The reference also requires the tool to be one it
+ * serves; for an unserved name it answers `-32600` where the port answers `Unknown tool:`.
+ */
+function refusedByName(line, parsed) {
+    if (!isObject(parsed) || parsed['method'] !== 'tools/call' || !('id' in parsed))
+        return false;
+    if (clientIdText(line, parsed['id']) === undefined)
+        return false;
+    const params = parsed['params'];
+    return isObject(params) && typeof params['name'] === 'string' && isObject(params['arguments']) && holdsLoneSurrogate(params['arguments']);
+}
+/** The frame again with `params._meta` left out. */
+function withoutKey(frame, params) {
+    const { _meta: _dropped, ...rest } = params;
+    return { ...frame, params: rest };
+}
+/**
+ * Whether `mcp_types.RequestParams.meta` (`RequestParamsMeta | None`, lax) takes this
+ * `_meta`: absent or `null`, or an open object whose `progressToken`, if any, is a str or
+ * what lax `int` takes — an integral number or a bool (`NotRequired`, so not `null`).
+ * Measured on the reference: `5`, `[]`, `{"progressToken": 1.5}`, `{"progressToken": null}`
+ * and `{"progressToken": {}}` are -32602; `null`, `{"progressToken": true}` and
+ * `{"progressToken": 2.0}` are served.
+ */
+function referenceTakesMeta(meta) {
+    if (meta === undefined || meta === null)
+        return true;
+    if (!isObject(meta))
+        return false;
+    const token = meta['progressToken'];
+    return token === undefined || typeof token === 'string' || typeof token === 'boolean' || Number.isInteger(token);
+}
+/** The members a JSON-RPC 2.0 message may carry; any other is dropped as pydantic drops it. */
+const MESSAGE_KEYS = new Set(['jsonrpc', 'id', 'method', 'params', 'result', 'error']);
+function isObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
 }

package/dist/mcpreport.d.ts

@@ -74,6 +74,18 @@ export interface HostCall {
 }
 /** The one timestamp the join hangs on when only one end was logged. */
 export declare function anchorMs(call: HostCall): number;
+/**
+ * The two input paths, spelled in ASCII.
+ *
+ * `docs/mcpreport.md` promises an ASCII report, and the two paths it echoes are the only
+ * bytes in it that come from outside a closed vocabulary. Measured 2026-10-13 (#187): a root
+ * named `แคช-😀` reached stdout verbatim. Every UTF-16 code unit outside printable ASCII
+ * (0x20–0x7E) becomes `\uXXXX`, lowercase hex — one escape per code unit, so a character
+ * outside the BMP is two — and nothing else is touched: a backslash stays a backslash, so a
+ * Windows path reads as typed. The reference walks code points and splits astral ones into
+ * surrogates by hand; the two spell the same bytes.
+ */
+export declare function escapeAscii(text: string): string;
 export interface PairedCalls {
     readonly calls: HostCall[];
     readonly incomplete: number;

package/dist/mcpreport.js

@@ -211,6 +211,57 @@ export function parseHostLine(line) {
 export function anchorMs(call) {
     return call.startMs !== null ? call.startMs : (call.endMs ?? 0);
 }
+/**
+ * `min()` / `max()` over a non-empty list, as a LOOP, and `list.extend` as a loop too.
+ *
+ * `Math.min(...values)` and `out.push(...lines)` spread a list into CALL ARGUMENTS, and V8
+ * caps those at the stack. Measured 2026-10-14 (#130): one session of 130,000 calls — 32 MB
+ * of host log, a legal busy day — ended `--mcp-report` with `RangeError: Maximum call stack
+ * size exceeded` on this side where the reference answered the same log in 1.4 s. The host
+ * log is UNBOUNDED by contract (`docs/mcpreport.md`: the host never rotates it), so nothing
+ * derived from it — a session's anchors, a bucket's durations, one line per session — may be
+ * spread into a call. `[...items]` in an array literal is iteration, not a call, and stays.
+ */
+function minOf(values) {
+    let best = values[0];
+    for (let i = 1; i < values.length; i += 1)
+        if (values[i] < best)
+            best = values[i];
+    return best;
+}
+function maxOf(values) {
+    let best = values[0];
+    for (let i = 1; i < values.length; i += 1)
+        if (values[i] > best)
+            best = values[i];
+    return best;
+}
+function extend(out, lines) {
+    for (const line of lines)
+        out.push(line);
+}
+/**
+ * The two input paths, spelled in ASCII.
+ *
+ * `docs/mcpreport.md` promises an ASCII report, and the two paths it echoes are the only
+ * bytes in it that come from outside a closed vocabulary. Measured 2026-10-13 (#187): a root
+ * named `แคช-😀` reached stdout verbatim. Every UTF-16 code unit outside printable ASCII
+ * (0x20–0x7E) becomes `\uXXXX`, lowercase hex — one escape per code unit, so a character
+ * outside the BMP is two — and nothing else is touched: a backslash stays a backslash, so a
+ * Windows path reads as typed. The reference walks code points and splits astral ones into
+ * surrogates by hand; the two spell the same bytes.
+ */
+export function escapeAscii(text) {
+    let out = '';
+    for (let i = 0; i < text.length; i += 1) {
+        const unit = text.charCodeAt(i);
+        if (unit >= 0x20 && unit <= 0x7e)
+            out += text[i];
+        else
+            out += `\\u${unit.toString(16).padStart(4, '0')}`;
+    }
+    return out;
+}
 /** `sorted(key=...)` over tuples of numbers and strings — Python's, so codepoint order. */
 function byKey(items, key) {
     return [...items].sort((a, b) => {
@@ -508,8 +559,8 @@ function candidates(event, calls, windowMs) {
         const ends = [call.startMs, call.endMs].filter((t) => t !== null);
         if (ends.length === 0)
             continue;
-        const lo = Math.min(...ends) - windowMs;
-        const hi = Math.max(...ends) + windowMs;
+        const lo = minOf(ends) - windowMs;
+        const hi = maxOf(ends) + windowMs;
         if (lo <= event.tsMs && event.tsMs <= hi)
             out.push(index);
     }
@@ -628,22 +679,23 @@ export function render(host, events, joined) {
         out.push(`host-log-root: unknown on this platform (${host.platform}); set ${HOST_LOG_ROOT_ENV}`);
     }
     else if (host.missing === 'not-found') {
-        out.push(`host-log-root: not found at ${host.root}`);
+        out.push(`host-log-root: not found at ${escapeAscii(host.root ?? '')}`);
     }
     else {
-        out.push(`host-log-root: ${host.root}`);
+        out.push(`host-log-root: ${escapeAscii(host.root ?? '')}`);
     }
     out.push(`host-log-dirs: ${host.dirs}`, `host-log-files: ${host.files}`, `host-records: ${host.records}`, `host-records-lifecycle: ${host.lifecycle}`, `host-records-unclassified: ${host.unclassified}`, `host-error-records: ${host.errors}`, `host-calls: ${host.calls.length}`, `host-calls-incomplete: ${host.incomplete}`, `host-calls-orphan-completion: ${host.orphanCompletions}`);
     if (events.missing === 'off')
         out.push('event-log: off (BANTAMKIT_EVENT_LOG unset or off)');
-    else if (events.missing === 'not-found')
-        out.push(`event-log: not found at ${events.path}`);
+    else if (events.missing === 'not-found') {
+        out.push(`event-log: not found at ${escapeAscii(events.path ?? '')}`);
+    }
     else
-        out.push(`event-log: ${events.path}`);
+        out.push(`event-log: ${escapeAscii(events.path ?? '')}`);
     out.push(`event-records: ${events.records}`, `event-records-unreadable: ${events.unreadable}`, '', '[join]', 'method: (ts, tool) interval containment, mutually unique only', 'APPROXIMATE: the host stamps the dispatch, bantamkit stamps the decision,' +
         ' and under concurrency the two files can disagree about order. (ts, tool)' +
         ' is EVIDENCE, NOT A KEY.', `window-ms: ${joined.windowMs}`, `matched-pairs: ${joined.matched.length}`, `ambiguous-groups: ${joined.ambiguousGroups.length}`, `ambiguous-events: ${joined.ambiguousEvents}`, `ambiguous-calls: ${joined.ambiguousCalls}`, `unmatched-events: ${joined.unmatchedEvents.length}`, `unmatched-calls: ${joined.unmatchedCalls.length}`, `attributed-events: ${joined.matched.length} of ${events.events.length}`);
-    out.push(...linesOrNone(joined.ambiguousGroups.map(([e, c]) => `ambiguous-group: events=${e} calls=${c}`)));
+    extend(out, linesOrNone(joined.ambiguousGroups.map(([e, c]) => `ambiguous-group: events=${e} calls=${c}`)));
     // --- durations: the number NEITHER file holds. `ms` is source A, `outcome` is B.
     const buckets = new Map();
     for (const [event, call] of joined.matched) {
@@ -659,8 +711,8 @@ export function render(host, events, joined) {
         }
     }
     out.push('', '[durations]', 'matched pairs only; ms from the host, outcome from bantamkit');
-    out.push(...linesOrNone(byKey([...buckets.values()], (b) => [b.tool, b.outcome]).map(({ tool, outcome, values }) => `${tool} ${outcome} n=${values.length} min=${Math.min(...values)}` +
-        ` p50=${p50(values)} max=${Math.max(...values)}`)));
+    extend(out, linesOrNone(byKey([...buckets.values()], (b) => [b.tool, b.outcome]).map(({ tool, outcome, values }) => `${tool} ${outcome} n=${values.length} min=${minOf(values)}` +
+        ` p50=${p50(values)} max=${maxOf(values)}`)));
     // --- sessions: the only place a sessionId exists, plus what B could attach to it.
     const perSession = new Map();
     for (const call of host.calls) {
@@ -675,19 +727,19 @@ export function render(host, events, joined) {
         attributed.set(call.session, (attributed.get(call.session) ?? 0) + 1);
     }
     const orderedSessions = byKey([...perSession.entries()], ([name, calls]) => [
-        Math.min(...calls.map(anchorMs)),
+        minOf(calls.map(anchorMs)),
         name,
     ]);
     out.push('', '[sessions]');
-    out.push(...linesOrNone(orderedSessions.map(([name, calls]) => {
+    extend(out, linesOrNone(orderedSessions.map(([name, calls]) => {
         const anchors = calls.map(anchorMs);
         const tools = [...new Set(calls.map((c) => c.tool))].sort(cmpCodepoint);
         return (`${name} calls=${calls.length}` +
             ` ok=${calls.filter((c) => c.ok === true).length}` +
             ` fail=${calls.filter((c) => c.ok === false).length}` +
             ` incomplete=${calls.filter((c) => c.ok === null).length}` +
-            ` first=${formatTimestamp(Math.min(...anchors))}` +
-            ` last=${formatTimestamp(Math.max(...anchors))}` +
+            ` first=${formatTimestamp(minOf(anchors))}` +
+            ` last=${formatTimestamp(maxOf(anchors))}` +
             ` attributed=${attributed.get(name) ?? 0}` +
             ` tools=${tools.join(',')}`);
     })));
@@ -703,7 +755,7 @@ export function render(host, events, joined) {
             ` session=${call.session} later-calls=${later.length}` +
             ` later-same-tool=${later.filter((c) => c.tool === event.tool).length}`);
     }
-    out.push(...linesOrNone(follow));
+    extend(out, linesOrNone(follow));
     // --- the host's errors, counted and never quoted.
     out.push('', '[host-errors]', `records=${host.errors} with-tool=${host.errorsWithTool}` +
         ` without-tool=${host.errors - host.errorsWithTool}`, 'text withheld by design: the host log has been measured to persist argument' +

package/dist/memory/cli.js

@@ -89,6 +89,18 @@ function positive(text) {
         throw new ArgumentTypeError('must be >= 1');
     return value;
 }
+/**
+ * `_nonnegative`: `--reserve 0` is a real request — compact to the budget itself — and the
+ * tool's schema says `minimum: 0`, so the CLI accepts it too (#134). WAS `positive`, which
+ * refused 0 with `must be >= 1` on both CLIs while `memory_compact` took it. `typeName` is
+ * `_nonnegative` for the reason `positive` gives: argparse prints the callable's `__name__`.
+ */
+function nonnegative(text) {
+    const value = pyIntStrict(text);
+    if (value < 0)
+        throw new ArgumentTypeError('must be >= 0');
+    return value;
+}
 /**
  * `common(sub)`: the store selector and the budget, on every subcommand.
  *
@@ -176,9 +188,12 @@ const PARSER = {
                             dest: 'reserve',
                             metavar: 'BYTES',
                             kind: 'store',
-                            help: 'headroom to leave below the budget (default: the largest index line kept)',
-                            convert: positive,
-                            typeName: '_positive',
+                            // The default is `MemoryStore.compact`'s (job46): the sentence quotes it rather
+                            // than the pre-job46 "largest index line kept" it used to state (#134).
+                            help: 'headroom to leave below the budget (default: the budget minus its 90 percent ' +
+                                'warning line, plus the largest index line kept; capped at half the budget)',
+                            convert: nonnegative,
+                            typeName: '_nonnegative',
                             defaultValue: null,
                         },
                     ])),

package/dist/memory/component.d.ts

@@ -104,6 +104,21 @@ export interface RecallOutcome {
      * that says so, `null` for every other query — the walk that has always run, unchanged.
      */
     readonly lookup: string | null;
+    /**
+     * Every fact file a layer this walk READ could not read as a fact (job65/#119), as
+     * `{layer, file, reason}`; the reply names them in a closing paragraph (`skippedNote`).
+     */
+    readonly skipped: ReadonlyArray<{
+        layer: string;
+        file: string;
+        reason: string;
+    }>;
+    /**
+     * The header line of each fact in the reply, in reply order, BUILT FROM THE PARSED FIELDS
+     * (job65/#155). The hook reads these instead of filtering the reply's lines, so a body line
+     * shaped like a header can never pass for one.
+     */
+    readonly headers: readonly string[];
 }
 /**
  * What `dream` DID, beside the sentence it says about it.
@@ -384,5 +399,7 @@ export declare class Memory {
      * literal, so the message and the resolver cannot drift onto two different variables.
      */
     private bindingDiagnosis;
+    /** `[layer] [name] (type) description`, from the parsed fields (job65/#155). */
+    private header;
     private format;
 }