@adhisang/minecraft-modding-mcp 6.2.0 → 7.0.0-rc.0

package/dist/java-process.d.ts

@@ -1,3 +1,4 @@
+import { spawn } from "node:child_process";
 export declare const MAX_STDIO_SNAPSHOT = 6240;
 export interface JavaProcessOptions {
     jarPath: string;
@@ -18,6 +19,7 @@ export declare function isAbsolutePath(value: string): boolean;
 export declare function isOptionArg(value: string): boolean;
 export declare function normalizeArgs(args: string[]): string[];
 export declare function assertJavaAvailable(): Promise<void>;
+export declare function resetJavaAvailabilityCacheForTests(spawnHook?: typeof spawn): void;
 export declare function runJavaProcess(options: JavaProcessOptions): Promise<JavaProcessResult>;
 export declare const javaRunner: {
     run: (options: JavaProcessOptions) => Promise<JavaProcessResult>;

package/dist/java-process.js

@@ -3,6 +3,8 @@ import { createError, ERROR_CODES } from "./errors.js";
 import { normalizePathForHost } from "./path-converter.js";
 const JAVA_CHECK_TIMEOUT_MS = 2_000;
 export const MAX_STDIO_SNAPSHOT = 6_240;
+let javaAvailabilitySpawn = spawn;
+let javaAvailabilityPromise;
 export function limitStdio(text) {
     if (text.length <= MAX_STDIO_SNAPSHOT) {
         return text;
@@ -26,9 +28,9 @@ export function normalizeArgs(args) {
         return arg;
     });
 }
-export async function assertJavaAvailable() {
+function probeJavaAvailability() {
     return new Promise((resolve, reject) => {
-        const proc = spawn("java", ["-version"], { stdio: "ignore" });
+        const proc = javaAvailabilitySpawn("java", ["-version"], { stdio: "ignore" });
         const timer = setTimeout(() => {
             proc.kill();
             reject(createError({
@@ -56,6 +58,24 @@ export async function assertJavaAvailable() {
         });
     });
 }
+export function assertJavaAvailable() {
+    if (javaAvailabilityPromise) {
+        return javaAvailabilityPromise;
+    }
+    const probePromise = Promise.resolve().then(() => probeJavaAvailability());
+    const cachedPromise = probePromise.catch((error) => {
+        if (javaAvailabilityPromise === cachedPromise) {
+            javaAvailabilityPromise = undefined;
+        }
+        throw error;
+    });
+    javaAvailabilityPromise = cachedPromise;
+    return cachedPromise;
+}
+export function resetJavaAvailabilityCacheForTests(spawnHook = spawn) {
+    javaAvailabilityPromise = undefined;
+    javaAvailabilitySpawn = spawnHook;
+}
 export function runJavaProcess(options) {
     const { jarPath, args, cwd, timeoutMs = 120_000, maxMemoryMb, minMemoryMb, normalizePathArgs = false } = options;
     const jvmArgs = [];

package/dist/json-rpc-framing.d.ts

@@ -1,18 +1,75 @@
-import { type JSONRPCMessage } from "@modelcontextprotocol/sdk/types.js";
+import { type JSONRPCMessage } from "@modelcontextprotocol/server";
 export type FramingMode = "unknown" | "line" | "content-length";
 export type ConcreteFramingMode = Exclude<FramingMode, "unknown">;
 export type ParsedJsonRpcFrame = {
     message: JSONRPCMessage;
     mode: ConcreteFramingMode;
 };
+/**
+ * A framing violation the reader cannot provably recover from.
+ *
+ * The reader's framing invariant is: after ANY framing violation it either
+ * provably resynchronizes — resuming at a byte position the peer itself
+ * delimited — or it terminates the session with a diagnostic. It must never
+ * silently consume subsequent valid frames, and it must never wait on bytes
+ * an untrusted declared length says are coming.
+ *
+ * Recoverable violations (plain `Error`, reader keeps running):
+ *  - a line-delimited frame that is oversized or unparseable — the newline
+ *    that terminates it is a delimiter the reader can prove,
+ *  - a Content-Length header block carrying no usable length at all
+ *    (`Content-Length: nope`, a missing header, a malformed header line) —
+ *    the CRLFCRLF boundary delimits the header block and no body length was
+ *    ever declared, so only the header block is consumed,
+ *  - an oversized Content-Length frame whose complete declared body is ALREADY
+ *    buffered — dropping exactly those bytes lands on the byte the peer named
+ *    as the next frame's first,
+ *  - a Content-Length body that is valid JSON but not a valid JSON-RPC message
+ *    — valid JSON of exactly the declared length proves the boundary was
+ *    right, so this is a message-level error, not a framing one.
+ *
+ * Fatal violations (this class, reader stops permanently):
+ *  - an oversized Content-Length whose declared body has NOT fully arrived
+ *    (waiting on it is what let a single unanswerable header wedge the
+ *    transport for the process lifetime),
+ *  - a Content-Length body that is not valid JSON — under-declaration,
+ *    over-declaration and an honestly-framed bad body are indistinguishable,
+ *    and the first two have already desynchronized the stream,
+ *  - duplicate Content-Length headers — the body length is ambiguous,
+ *  - a Content-Length header block that never terminates within the header
+ *    limit — there is no delimiter left to resynchronize on.
+ */
+export declare class JsonRpcFramingFatalError extends Error {
+    readonly framingFatal = true;
+    constructor(message: string);
+}
+/**
+ * Whether an error reported through `processChunk`'s `onError` handler ends
+ * the session. Every transport that owns a {@link JsonRpcFrameReader} MUST
+ * check this and tear its session down: the reader has stopped accepting
+ * input, so ignoring the signal would leave a silently deaf transport.
+ */
+export declare function isJsonRpcFramingFatalError(error: unknown): error is JsonRpcFramingFatalError;
+export declare function loadMaxFrameBytes(value?: string | undefined): number;
 export declare function encodeJsonRpcMessage(message: JSONRPCMessage, mode: ConcreteFramingMode): Buffer;
 export declare class JsonRpcFrameReader {
+    private readonly maxFrameBytes;
     private mode;
     private buffer;
     private pendingChunks;
     private pendingBytes;
     private awaitedFrameEnd;
+    private fatal;
+    constructor(options?: {
+        maxFrameBytes?: number;
+    });
     get currentMode(): FramingMode;
+    /**
+     * Whether an unrecoverable framing violation has stopped this reader. No
+     * further input is examined and no further frame is ever emitted until
+     * `reset()` or `clear()` explicitly re-arms it.
+     */
+    get isFatal(): boolean;
     reset(): void;
     clear(): void;
     processChunk(chunk: Buffer, handlers: {
@@ -20,6 +77,25 @@ export declare class JsonRpcFrameReader {
         onError: (error: Error) => void;
     }): void;
     private canCompleteFrame;
+    private rejectOversizedIncompleteInput;
+    /**
+     * Rejects a Content-Length frame whose declared body can never be accepted
+     * (over the frame limit, or behind an over-limit header block).
+     *
+     * The body is skipped ONLY when every declared byte is already buffered. In
+     * that case the skip is a bounded operation on bytes in hand and it resumes
+     * at exactly the offset the peer itself named as the next frame's first
+     * byte — a resynchronization the reader can prove without extending trust to
+     * a single unarrived byte.
+     *
+     * When the body has NOT fully arrived the reader must not wait for it: the
+     * declared length is attacker-controlled, and arming a countdown with it is
+     * precisely what let a 29-byte header (`Content-Length: 999999999\r\n\r\n`
+     * with no body) silently swallow every later frame for the process lifetime.
+     * There is no delimiter to scan forward to either — an arbitrary binary body
+     * offers none — so the session is terminated instead.
+     */
+    private rejectDeclaredBody;
     private detectMode;
     private readLineDelimitedMessage;
     private readContentLengthMessage;

package/dist/json-rpc-framing.js

@@ -1,4 +1,7 @@
-import { JSONRPCMessageSchema } from "@modelcontextprotocol/sdk/types.js";
+import { parseJSONRPCMessage } from "@modelcontextprotocol/server";
+const DEFAULT_MAX_FRAME_BYTES = 64 * 1024 * 1024;
+const MIN_MAX_FRAME_BYTES = 1024 * 1024;
+const MAX_CONTENT_LENGTH_HEADER_BYTES = 8 * 1024;
 function findHeaderBoundary(buffer) {
     const crlfBoundary = buffer.indexOf("\r\n\r\n");
     if (crlfBoundary !== -1) {
@@ -11,11 +14,71 @@ function findHeaderBoundary(buffer) {
     return undefined;
 }
 function parseJsonRpcMessage(json) {
-    return JSONRPCMessageSchema.parse(JSON.parse(json));
+    return parseJSONRPCMessage(JSON.parse(json));
 }
 function asError(value) {
     return value instanceof Error ? value : new Error(String(value));
 }
+/**
+ * A framing violation the reader cannot provably recover from.
+ *
+ * The reader's framing invariant is: after ANY framing violation it either
+ * provably resynchronizes — resuming at a byte position the peer itself
+ * delimited — or it terminates the session with a diagnostic. It must never
+ * silently consume subsequent valid frames, and it must never wait on bytes
+ * an untrusted declared length says are coming.
+ *
+ * Recoverable violations (plain `Error`, reader keeps running):
+ *  - a line-delimited frame that is oversized or unparseable — the newline
+ *    that terminates it is a delimiter the reader can prove,
+ *  - a Content-Length header block carrying no usable length at all
+ *    (`Content-Length: nope`, a missing header, a malformed header line) —
+ *    the CRLFCRLF boundary delimits the header block and no body length was
+ *    ever declared, so only the header block is consumed,
+ *  - an oversized Content-Length frame whose complete declared body is ALREADY
+ *    buffered — dropping exactly those bytes lands on the byte the peer named
+ *    as the next frame's first,
+ *  - a Content-Length body that is valid JSON but not a valid JSON-RPC message
+ *    — valid JSON of exactly the declared length proves the boundary was
+ *    right, so this is a message-level error, not a framing one.
+ *
+ * Fatal violations (this class, reader stops permanently):
+ *  - an oversized Content-Length whose declared body has NOT fully arrived
+ *    (waiting on it is what let a single unanswerable header wedge the
+ *    transport for the process lifetime),
+ *  - a Content-Length body that is not valid JSON — under-declaration,
+ *    over-declaration and an honestly-framed bad body are indistinguishable,
+ *    and the first two have already desynchronized the stream,
+ *  - duplicate Content-Length headers — the body length is ambiguous,
+ *  - a Content-Length header block that never terminates within the header
+ *    limit — there is no delimiter left to resynchronize on.
+ */
+export class JsonRpcFramingFatalError extends Error {
+    framingFatal = true;
+    constructor(message) {
+        super(message);
+        this.name = "JsonRpcFramingFatalError";
+    }
+}
+/**
+ * Whether an error reported through `processChunk`'s `onError` handler ends
+ * the session. Every transport that owns a {@link JsonRpcFrameReader} MUST
+ * check this and tear its session down: the reader has stopped accepting
+ * input, so ignoring the signal would leave a silently deaf transport.
+ */
+export function isJsonRpcFramingFatalError(error) {
+    return error instanceof JsonRpcFramingFatalError;
+}
+export function loadMaxFrameBytes(value = process.env.MCP_MAX_FRAME_BYTES) {
+    if (!/^[0-9]+$/.test(value ?? "")) {
+        return DEFAULT_MAX_FRAME_BYTES;
+    }
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed)) {
+        return DEFAULT_MAX_FRAME_BYTES;
+    }
+    return Math.max(parsed, MIN_MAX_FRAME_BYTES);
+}
 export function encodeJsonRpcMessage(message, mode) {
     const json = JSON.stringify(message);
     return Buffer.from(mode === "content-length"
@@ -23,17 +86,31 @@ export function encodeJsonRpcMessage(message, mode) {
         : `${json}\n`, "utf8");
 }
 export class JsonRpcFrameReader {
+    maxFrameBytes;
     mode = "unknown";
     buffer = Buffer.alloc(0);
     pendingChunks = [];
     pendingBytes = 0;
     awaitedFrameEnd = -1;
+    fatal = false;
+    constructor(options = {}) {
+        this.maxFrameBytes = options.maxFrameBytes ?? loadMaxFrameBytes();
+    }
     get currentMode() {
         return this.mode;
     }
+    /**
+     * Whether an unrecoverable framing violation has stopped this reader. No
+     * further input is examined and no further frame is ever emitted until
+     * `reset()` or `clear()` explicitly re-arms it.
+     */
+    get isFatal() {
+        return this.fatal;
+    }
     reset() {
         this.mode = "unknown";
         this.awaitedFrameEnd = -1;
+        this.fatal = false;
     }
     clear() {
         this.mode = "unknown";
@@ -41,9 +118,10 @@ export class JsonRpcFrameReader {
         this.pendingChunks = [];
         this.pendingBytes = 0;
         this.awaitedFrameEnd = -1;
+        this.fatal = false;
     }
     processChunk(chunk, handlers) {
-        if (chunk.length === 0) {
+        if (chunk.length === 0 || this.fatal) {
             return;
         }
         this.pendingChunks.push(chunk);
@@ -56,6 +134,7 @@ export class JsonRpcFrameReader {
         this.pendingBytes = 0;
         while (true) {
             try {
+                this.rejectOversizedIncompleteInput();
                 if (this.mode === "unknown") {
                     const detected = this.detectMode();
                     if (!detected) {
@@ -80,16 +159,91 @@ export class JsonRpcFrameReader {
                 });
             }
             catch (caughtError) {
+                const error = asError(caughtError);
                 this.mode = "unknown";
-                handlers.onError(asError(caughtError));
+                this.awaitedFrameEnd = -1;
+                if (error instanceof JsonRpcFramingFatalError) {
+                    // Terminal: drop everything buffered and refuse all further input so
+                    // no byte after the violation can be mistaken for a frame. The
+                    // transport owns the teardown.
+                    this.fatal = true;
+                    this.buffer = Buffer.alloc(0);
+                    this.pendingChunks = [];
+                    this.pendingBytes = 0;
+                    handlers.onError(error);
+                    return;
+                }
+                handlers.onError(error);
             }
         }
     }
     canCompleteFrame(chunk) {
+        const bufferedBytes = this.buffer.length + this.pendingBytes;
         if (this.mode === "content-length" && this.awaitedFrameEnd >= 0) {
-            return this.buffer.length + this.pendingBytes >= this.awaitedFrameEnd;
+            return bufferedBytes >= this.awaitedFrameEnd;
+        }
+        if (this.mode === "content-length" &&
+            bufferedBytes > MAX_CONTENT_LENGTH_HEADER_BYTES) {
+            return true;
+        }
+        return chunk.includes(0x0a) || bufferedBytes > this.maxFrameBytes;
+    }
+    rejectOversizedIncompleteInput() {
+        const headerBoundary = this.mode === "content-length" ? findHeaderBoundary(this.buffer) : undefined;
+        if (this.mode === "content-length" &&
+            !headerBoundary &&
+            this.buffer.length > MAX_CONTENT_LENGTH_HEADER_BYTES) {
+            // No header terminator anywhere in an over-limit header block: there is
+            // no delimiter left to resynchronize on (content-length mode has no
+            // newline delimiter, and a line frame at the head would already have
+            // switched the mode), so the session cannot continue.
+            throw new JsonRpcFramingFatalError(`Content-Length header is ${this.buffer.length} bytes with no header terminator, exceeding ` +
+                `the header limit of ${MAX_CONTENT_LENGTH_HEADER_BYTES} bytes; the stdio session is terminated.`);
+        }
+        if (this.buffer.length <= this.maxFrameBytes) {
+            return;
+        }
+        if (this.mode === "content-length" && headerBoundary) {
+            return;
+        }
+        if (this.mode !== "content-length" && this.buffer.includes(0x0a)) {
+            return;
+        }
+        const observedBytes = this.buffer.length;
+        const description = this.mode === "line" ? "Line-delimited JSON-RPC frame" : "Headerless JSON-RPC input";
+        this.buffer = Buffer.alloc(0);
+        throw new Error(`${description} is ${observedBytes} bytes, exceeding the configured frame limit of ` +
+            `${this.maxFrameBytes} bytes.`);
+    }
+    /**
+     * Rejects a Content-Length frame whose declared body can never be accepted
+     * (over the frame limit, or behind an over-limit header block).
+     *
+     * The body is skipped ONLY when every declared byte is already buffered. In
+     * that case the skip is a bounded operation on bytes in hand and it resumes
+     * at exactly the offset the peer itself named as the next frame's first
+     * byte — a resynchronization the reader can prove without extending trust to
+     * a single unarrived byte.
+     *
+     * When the body has NOT fully arrived the reader must not wait for it: the
+     * declared length is attacker-controlled, and arming a countdown with it is
+     * precisely what let a 29-byte header (`Content-Length: 999999999\r\n\r\n`
+     * with no body) silently swallow every later frame for the process lifetime.
+     * There is no delimiter to scan forward to either — an arbitrary binary body
+     * offers none — so the session is terminated instead.
+     */
+    rejectDeclaredBody(messageStart, contentLength, reason) {
+        const frameEnd = BigInt(messageStart) + contentLength;
+        if (BigInt(this.buffer.length) >= frameEnd) {
+            this.buffer = this.buffer.subarray(Number(frameEnd));
+            this.awaitedFrameEnd = -1;
+            this.mode = "unknown";
+            throw new Error(reason);
         }
-        return chunk.includes(0x0a);
+        const arrivedBodyBytes = Math.max(0, this.buffer.length - messageStart);
+        throw new JsonRpcFramingFatalError(`${reason} Only ${arrivedBodyBytes} of the declared ${contentLength.toString()} body bytes have ` +
+            "arrived, so the reader cannot resynchronize without trusting bytes that may never be sent; " +
+            "the stdio session is terminated.");
     }
     detectMode() {
         while (this.buffer.length > 0) {
@@ -129,14 +283,26 @@ export class JsonRpcFrameReader {
             if (newlineIndex === -1) {
                 return undefined;
             }
+            const lineBytes = newlineIndex > 0 && this.buffer[newlineIndex - 1] === 0x0d
+                ? newlineIndex - 1
+                : newlineIndex;
+            if (lineBytes > this.maxFrameBytes) {
+                this.buffer = this.buffer.subarray(newlineIndex + 1);
+                throw new Error(`Line-delimited JSON-RPC frame is ${lineBytes} bytes, exceeding the configured ` +
+                    `frame limit of ${this.maxFrameBytes} bytes.`);
+            }
             const line = this.buffer.subarray(0, newlineIndex).toString("utf8").replace(/\r$/, "");
             this.buffer = this.buffer.subarray(newlineIndex + 1);
             if (line.trim().length === 0) {
                 continue;
             }
             if (/^\s*content-length\s*:/i.test(line)) {
-                const separator = this.buffer.length > 0 && this.buffer[0] === 0x0d ? "\r\n" : "\n";
-                this.buffer = Buffer.concat([Buffer.from(`${line}${separator}`, "utf8"), this.buffer]);
+                // Always re-inject with CRLF: choosing the separator from the next
+                // buffered byte raced byte-granular chunking (the peer's \r may not
+                // have arrived yet, yielding a "\n\r\n" boundary findHeaderBoundary
+                // cannot see). With CRLF both peer styles stay recognizable:
+                // "...\r\n" + "\r\n…" → "\r\n\r\n", "...\r\n" + "\n…" → "\n\n".
+                this.buffer = Buffer.concat([Buffer.from(`${line}\r\n`, "utf8"), this.buffer]);
                 this.mode = "content-length";
                 return undefined;
             }
@@ -145,6 +311,42 @@ export class JsonRpcFrameReader {
     }
     readContentLengthMessage() {
         this.awaitedFrameEnd = -1;
+        // Skip blank separator lines between frames so the mid-stream mode check
+        // below sees the first byte of the next frame.
+        while (this.buffer.length > 0) {
+            if (this.buffer[0] === 0x0a) {
+                this.buffer = this.buffer.subarray(1);
+                continue;
+            }
+            if (this.buffer.length >= 2 && this.buffer[0] === 0x0d && this.buffer[1] === 0x0a) {
+                this.buffer = this.buffer.subarray(2);
+                continue;
+            }
+            break;
+        }
+        // Mirror of the line→content-length switch in readLineDelimitedMessage:
+        // a JSON object or array opener can never begin a Content-Length header block,
+        // so this is a line-delimited frame arriving after a Content-Length frame.
+        // Arrays are re-dispatched only to surface their JSON-RPC schema error, not
+        // accepted as batch messages. Peek past leading whitespace (pure line mode
+        // tolerates it: blank lines are skipped and JSON.parse accepts a
+        // whitespace-prefixed line) without consuming it, then switch modes and let
+        // processChunk re-dispatch the buffered bytes, so every frame is delivered
+        // with its own true mode.
+        let probeIndex = 0;
+        while (probeIndex < this.buffer.length &&
+            (this.buffer[probeIndex] === 0x20 ||
+                this.buffer[probeIndex] === 0x09 ||
+                this.buffer[probeIndex] === 0x0d ||
+                this.buffer[probeIndex] === 0x0a)) {
+            probeIndex += 1;
+        }
+        if (probeIndex < this.buffer.length &&
+            (this.buffer[probeIndex] === 0x7b /* '{' */ ||
+                this.buffer[probeIndex] === 0x5b /* '[' */)) {
+            this.mode = "line";
+            return undefined;
+        }
         const headerBoundary = findHeaderBoundary(this.buffer);
         if (!headerBoundary) {
             return undefined;
@@ -164,12 +366,19 @@ export class JsonRpcFrameReader {
             const headerName = headerLine.slice(0, separatorIndex).trim().toLowerCase();
             const headerValue = headerLine.slice(separatorIndex + 1).trim();
             if (headerName === "content-length") {
-                const parsed = Number.parseInt(headerValue, 10);
-                if (!Number.isFinite(parsed) || parsed < 0) {
+                if (contentLength !== undefined) {
+                    // Two declarations, no way to tell which delimits the body: the
+                    // classic frame-smuggling shape. Last-wins would hand an attacker
+                    // the choice of where the reader thinks this frame ends.
+                    throw new JsonRpcFramingFatalError(`Duplicate Content-Length header (${contentLength.toString()} then ${headerValue}): the ` +
+                        "declared body length is ambiguous, so the reader cannot determine where this frame " +
+                        "ends; the stdio session is terminated.");
+                }
+                if (!/^[0-9]+$/.test(headerValue)) {
                     this.buffer = this.buffer.subarray(headerBoundary.index + headerBoundary.delimiterBytes);
                     throw new Error(`Invalid Content-Length header value: ${headerValue}`);
                 }
-                contentLength = parsed;
+                contentLength = BigInt(headerValue);
             }
         }
         if (contentLength === undefined) {
@@ -177,14 +386,41 @@ export class JsonRpcFrameReader {
             throw new Error("Missing Content-Length header.");
         }
         const messageStart = headerBoundary.index + headerBoundary.delimiterBytes;
-        const frameEnd = messageStart + contentLength;
+        if (contentLength > BigInt(this.maxFrameBytes)) {
+            this.rejectDeclaredBody(messageStart, contentLength, `Content-Length ${contentLength.toString()} exceeds the configured frame limit of ` +
+                `${this.maxFrameBytes} bytes.`);
+        }
+        if (messageStart > MAX_CONTENT_LENGTH_HEADER_BYTES) {
+            this.rejectDeclaredBody(messageStart, contentLength, `Content-Length header is ${messageStart} bytes, exceeding the header limit of ` +
+                `${MAX_CONTENT_LENGTH_HEADER_BYTES} bytes.`);
+        }
+        const frameEnd = messageStart + Number(contentLength);
         if (this.buffer.length < frameEnd) {
             this.awaitedFrameEnd = frameEnd;
             return undefined;
         }
         const body = this.buffer.subarray(messageStart, frameEnd).toString("utf8");
         this.buffer = this.buffer.subarray(frameEnd);
-        return parseJsonRpcMessage(body);
+        let payload;
+        try {
+            payload = JSON.parse(body);
+        }
+        catch (parseError) {
+            // The declared length is the ONLY delimiter a Content-Length frame has,
+            // and it just failed its one verification: bytes cut at that offset are
+            // not a JSON value. An under-declared length (tail garbage left in the
+            // buffer, which used to corrupt the NEXT frame), an over-declared length
+            // (the next frame already swallowed into this body) and an honestly
+            // framed but malformed body are indistinguishable here — and the first
+            // two have already desynchronized the stream. Line framing keeps its
+            // recoverable parse errors; its newline proves the boundary.
+            throw new JsonRpcFramingFatalError(`Content-Length frame body of ${Number(contentLength)} bytes is not valid JSON ` +
+                `(${asError(parseError).message}); the declared length cannot be trusted to delimit the ` +
+                "next frame, so the stdio session is terminated.");
+        }
+        // Valid JSON of exactly the declared length: the frame boundary is proven,
+        // so a JSON-RPC schema violation is an ordinary message-level error.
+        return parseJSONRPCMessage(payload);
     }
 }
 //# sourceMappingURL=json-rpc-framing.js.map

package/dist/mapping/loaders/tiny-loom-selection.d.ts

@@ -0,0 +1,88 @@
+import type { SourceMapping } from "../../types.js";
+import type { PairKey } from "../internal-types.js";
+/**
+ * Bytes of JS heap one index slot costs, measured on Minecraft 1.21.10 loom
+ * mappings (2,080 MB peak / 6,755,994 slots ~= 323 B; the Mojang proguard index
+ * lands at 330 B). Rounded up so the derived budget errs toward stopping early.
+ */
+export declare const HEAP_BYTES_PER_INDEX_ENTRY = 340;
+/**
+ * How many index slots one Loom tiny load may accumulate before it stops and
+ * warns instead of exhausting the heap.
+ *
+ * The default is derived from the live V8 heap limit, so raising
+ * `--max-old-space-size` raises the budget automatically. `MCP_LOOM_TINY_MAX_INDEX_ENTRIES`
+ * overrides it outright.
+ */
+export declare function resolveTinyIndexEntryBudget(value?: string | undefined, heapStats?: {
+    heap_size_limit: number;
+    used_heap_size: number;
+}): number;
+export type TinyFileCandidate = {
+    path: string;
+    bytes: number;
+    /**
+     * Normalized first namespace column: the coordinates every descriptor in the file
+     * uses. `official` and `obfuscated` normalize to the same value.
+     */
+    descriptorNamespace: SourceMapping | string;
+    namespaces: SourceMapping[];
+};
+export type TinySelection = {
+    /** Files to merge, in the order they should be merged. */
+    selected: TinyFileCandidate[];
+    /** Files whose bytes duplicate an already-selected file exactly. */
+    duplicateOf: Map<string, string>;
+    /**
+     * Files skipped because they restate namespace pairs already covered by a
+     * selected file while declaring their descriptors in a different namespace.
+     */
+    descriptorConflicts: TinyFileCandidate[];
+    /** Files whose header is not a usable tiny v2 header. */
+    unsupported: string[];
+};
+/**
+ * Read just the first line of a tiny file and derive its namespace layout.
+ * Returns `undefined` for anything {@link parseTinyHeader} rejects, so the body
+ * of an unusable file is never read.
+ */
+export declare function readTinyFileCandidate(path: string): Promise<TinyFileCandidate | undefined>;
+/** Every ordered namespace pair a candidate's rows would populate. */
+export declare function candidatePairKeys(candidate: TinyFileCandidate): PairKey[];
+/**
+ * Richest first: more namespaces beats fewer; then a file whose descriptors are
+ * written in obfuscated coordinates beats one that is not, because that is the
+ * form callers query with and the form every other tiny source this server reads
+ * (Fabric intermediary and yarn artifacts, the Maven loader) produces; then larger
+ * beats smaller; then path order so the result never depends on filesystem
+ * enumeration order.
+ *
+ * The descriptor-coordinate rule also decides which rendering becomes the one the
+ * descriptor-conflict filter measures the rest against, so it must come before size:
+ * Loom's `mappings-base.tiny` is written with `intermediary` first AND is the larger
+ * file, and letting it win would leave the whole index carrying intermediary-coordinate
+ * descriptors.
+ */
+export declare function compareCandidates(left: TinyFileCandidate, right: TinyFileCandidate): number;
+/**
+ * Decide which of the discovered tiny files to merge.
+ *
+ * Loom keeps several renderings of one layered mapping set side by side in one
+ * output directory: the final `mappings.tiny`, a `-mojang` rendering with an extra
+ * column, `-migrated` renderings per loader build, and a `mappings-base.tiny`
+ * written with the namespace columns rotated. Two filters apply:
+ *
+ * 1. Byte-identical files are collapsed. Loom copies the same rendering into every
+ *    layered variant directory, so re-reading them is pure repeated work.
+ * 2. A file is dropped as an alternative rendering when ALL of the following hold:
+ *    it declares its descriptors in a different namespace than the rendering
+ *    already chosen, it sits in a directory that already yielded a selected file,
+ *    and every namespace pair it carries is already covered. Tiny v2 writes each
+ *    descriptor once, in the file's first namespace; merging an `intermediary`-first
+ *    rendering into an `official`-first index registers every method a second time
+ *    under an incompatible descriptor, which turns unique lookups into ambiguous
+ *    ones. All three conditions are required so that a genuinely different mapping
+ *    file — a standalone yarn tiny, a cache in another Gradle root — is never
+ *    mistaken for a rendering of data already loaded.
+ */
+export declare function selectTinyFiles(paths: string[]): Promise<TinySelection>;