@adhisang/minecraft-modding-mcp 4.2.0 → 5.0.0

package/dist/mixin/annotation-validators.js

@@ -43,13 +43,59 @@ export function validateInjection(inj, targetMembers, targetNames, issues, resol
             });
         }
         else {
-            resolvedMembers.push({
-                annotation: `@${inj.annotation}`,
-                name: methodName,
-                line: inj.line,
-                resolvedTo: `${targetName}#${methodName}`,
-                status: "resolved"
-            });
+            // Name matched. If the reference carries a JVM descriptor, require an
+            // overload to match it; otherwise a wrong-signature target (e.g. tick(D)V
+            // when only tick(I)V exists) is silently reported as resolved.
+            const refDescriptor = extractMethodDescriptor(inj.method);
+            const sameNameMembers = [...members.constructors, ...members.methods].filter((member) => member.name === methodName);
+            if (refDescriptor &&
+                sameNameMembers.length > 0 &&
+                !sameNameMembers.some((member) => member.jvmDescriptor === refDescriptor)) {
+                const available = [...new Set(sameNameMembers.map((member) => member.jvmDescriptor))];
+                const isRemapFailed = remapFailedMembers?.get(targetName)?.has(methodName);
+                const isSigFailed = signatureFailedTargets?.has(targetName);
+                // Only a healthy mapping lets us trust that the user-written descriptor is
+                // byte-equal to the runtime descriptor; otherwise downgrade to a warning.
+                const mappingDegraded = Boolean(isRemapFailed) || Boolean(isSigFailed) || healthReport?.overallHealthy === false;
+                const resolutionPath = isRemapFailed
+                    ? "member-remap-failed"
+                    : isSigFailed
+                        ? "source-signature-unavailable"
+                        : undefined;
+                const issueConfidence = mappingDegraded
+                    ? "uncertain"
+                    : confidence ?? "definite";
+                issues.push({
+                    severity: mappingDegraded ? "warning" : "error",
+                    kind: "descriptor-mismatch",
+                    annotation: `@${inj.annotation}`,
+                    target: `${targetName}#${inj.method}`,
+                    message: `Method "${methodName}" exists in "${targetName}" but no overload matches descriptor ${refDescriptor} (available: ${available.join(", ")}).${mappingDegraded ? " (mapping degraded; may be a remap artifact)" : ""}`,
+                    suggestions: available.length > 0 ? available : undefined,
+                    line: inj.line,
+                    confidence: issueConfidence,
+                    confidenceReason: mappingDegraded
+                        ? `Member remap/signature degraded; descriptor mismatch may be a tooling artifact, not a true signature error.`
+                        : confidenceReason,
+                    resolutionPath,
+                    falsePositiveRisk: computeFalsePositiveRisk(healthReport, resolutionPath, issueConfidence)
+                });
+                resolvedMembers.push({
+                    annotation: `@${inj.annotation}`,
+                    name: methodName,
+                    line: inj.line,
+                    status: "not-found"
+                });
+            }
+            else {
+                resolvedMembers.push({
+                    annotation: `@${inj.annotation}`,
+                    name: methodName,
+                    line: inj.line,
+                    resolvedTo: `${targetName}#${methodName}`,
+                    status: "resolved"
+                });
+            }
         }
     }
 }

package/dist/mixin/parsed-validator.js

@@ -209,7 +209,7 @@ export function validateParsedMixin(parsed, targetMembers, warnings, provenance,
                     if (version) {
                         assignSuggested(issue, "get-class-source", {
                             className: issue.target,
-                            target: { type: "resolve", kind: "version", value: version },
+                            target: { kind: "version", value: version },
                             ...(mapping ? { mapping } : {}),
                             mode: "metadata",
                             ...classSourceContext
@@ -236,7 +236,7 @@ export function validateParsedMixin(parsed, targetMembers, warnings, provenance,
                     if (version) {
                         assignSuggested(issue, "get-class-source", {
                             className,
-                            target: { type: "resolve", kind: "version", value: version },
+                            target: { kind: "version", value: version },
                             ...(mapping ? { mapping } : {}),
                             mode: "metadata",
                             ...classSourceContext

package/dist/mixin-parser.js

@@ -61,9 +61,38 @@ function collectMultilineAnnotation(lines, startIndex) {
  * Lines with inline annotation + declaration (e.g. `@Nullable private int x;`)
  * are treated as declaration lines (not skipped).
  */
+function isUpperCaseLetter(ch) {
+    return ch !== ch.toLowerCase() && ch === ch.toUpperCase();
+}
 function skipAnnotations(lines, startIndex) {
     let idx = startIndex;
-    while (idx < lines.length && /^\s*@/.test(lines[idx])) {
+    while (idx < lines.length) {
+        const current = lines[idx];
+        // Skip blank lines and comment-only lines that sit between an annotation and the
+        // member declaration; otherwise the declaration line is missed and the member dropped.
+        if (/^\s*$/.test(current) || /^\s*\/\//.test(current)) {
+            idx++;
+            continue;
+        }
+        if (/^\s*\/\*/.test(current)) {
+            if (current.includes("*/")) {
+                const afterComment = current.slice(current.indexOf("*/") + 2).trim();
+                if (afterComment === "") {
+                    idx++;
+                    continue;
+                }
+                break; // declaration text follows an inline block comment
+            }
+            idx++;
+            while (idx < lines.length && !lines[idx].includes("*/")) {
+                idx++;
+            }
+            idx++; // move past the closing "*/" line
+            continue;
+        }
+        if (!/^\s*@/.test(current)) {
+            break;
+        }
         if (lines[idx].includes("(")) {
             // Check if parentheses are unbalanced (multi-line annotation) — always skip
             let depth = 0;
@@ -106,18 +135,33 @@ const INLINE_ANNOTATION_RE = /\s*@[\w$.]+(?:\([^)]*\))?\s*/g;
 function stripInlineAnnotations(line) {
     return line.replace(INLINE_ANNOTATION_RE, " ").trim();
 }
+/**
+ * JavaBeans `Introspector.decapitalize`, which SpongePowered Mixin's AccessorInfo
+ * uses for inflection: leave the name unchanged when its first two characters are
+ * both upper case (getURL -> URL, getNBT -> NBT), otherwise lower-case the first
+ * character (getId -> id, getHealth -> health).
+ */
+function decapitalize(name) {
+    if (name.length === 0) {
+        return name;
+    }
+    if (name.length > 1 && isUpperCaseLetter(name.charAt(1)) && isUpperCaseLetter(name.charAt(0))) {
+        return name;
+    }
+    return name.charAt(0).toLowerCase() + name.slice(1);
+}
 function inferAccessorTarget(methodName) {
     const getterMatch = GETTER_PREFIX_RE.exec(methodName);
     if (getterMatch) {
-        return getterMatch[1].charAt(0).toLowerCase() + getterMatch[1].slice(1);
+        return decapitalize(getterMatch[1]);
     }
     const setterMatch = SETTER_PREFIX_RE.exec(methodName);
     if (setterMatch) {
-        return setterMatch[1].charAt(0).toLowerCase() + setterMatch[1].slice(1);
+        return decapitalize(setterMatch[1]);
     }
     const invokerMatch = INVOKER_PREFIX_RE.exec(methodName);
     if (invokerMatch) {
-        return invokerMatch[1].charAt(0).toLowerCase() + invokerMatch[1].slice(1);
+        return decapitalize(invokerMatch[1]);
     }
     return methodName;
 }

package/dist/mod-decompile-service.js

@@ -7,6 +7,7 @@ import { decompileBinaryJar } from "./decompiler/vineflower.js";
 import { resolveVineflowerJar } from "./vineflower-resolver.js";
 import { analyzeModJar } from "./mod-analyzer.js";
 import { validateAndNormalizeJarPath } from "./path-resolver.js";
+import { sliceToMaxCharsSafe } from "./text-truncate.js";
 const DECOMPILE_TIMEOUT_MS = 300_000;
 function modDecompileCacheKey(jarPath) {
     return createHash("sha256").update(jarPath).digest("hex");
@@ -122,7 +123,7 @@ export class ModDecompileService {
         }
         // Apply maxChars truncation
         if (input.maxChars != null && input.maxChars > 0 && content.length > input.maxChars) {
-            content = content.slice(0, input.maxChars);
+            content = sliceToMaxCharsSafe(content, input.maxChars);
             charsTruncated = true;
             truncated = true;
         }

package/dist/mod-remap-service.d.ts

@@ -1,9 +1,18 @@
+import { resolveTinyMappingFile } from "./mapping-service.js";
+import { resolveMojangTinyFile } from "./mojang-tiny-mapping-service.js";
+import { remapJar } from "./tiny-remapper-service.js";
+import { resolveTinyRemapperJar } from "./tiny-remapper-resolver.js";
 import type { Config } from "./types.js";
 export interface ModRemapInput {
     inputJar: string;
     outputJar?: string;
     mcVersion?: string;
     targetMapping: "yarn" | "mojang";
+    /**
+     * Skip the remap cache and force re-resolution of the newest yarn build
+     * (bypasses both the output-jar cache hit and the yarn metadata TTL).
+     */
+    forceRemap?: boolean;
 }
 export interface ModRemapResult {
     outputJar: string;
@@ -14,4 +23,14 @@ export interface ModRemapResult {
     durationMs: number;
     warnings: string[];
 }
-export declare function remapModJar(input: ModRemapInput, config: Config): Promise<ModRemapResult>;
+/**
+ * Injectable external dependencies, used by tests to drive the remap pipeline
+ * without spawning Java or downloading mapping jars. Production callers omit it.
+ */
+export interface RemapModJarDeps {
+    remapJar?: typeof remapJar;
+    resolveTinyMappingFile?: typeof resolveTinyMappingFile;
+    resolveMojangTinyFile?: typeof resolveMojangTinyFile;
+    resolveTinyRemapperJar?: typeof resolveTinyRemapperJar;
+}
+export declare function remapModJar(input: ModRemapInput, config: Config, deps?: RemapModJarDeps): Promise<ModRemapResult>;

package/dist/mod-remap-service.js

@@ -11,6 +11,13 @@ import { normalizePathForHost } from "./path-converter.js";
 import { detectFabricLikeInputNamespace } from "./source-jar-reader.js";
 import { remapJar } from "./tiny-remapper-service.js";
 import { resolveTinyRemapperJar } from "./tiny-remapper-resolver.js";
+// Bumped whenever the remap pipeline changes in a way that makes previously
+// cached output jars wrong. The v1 pipeline mis-mapped intermediary jars to
+// mojang using an obfuscated<->mojang tiny (no intermediary namespace), so any
+// cached mojang output is invalid and must not be reused. v3 adds the resolved
+// mapping identity (yarn build coordinate) to the cache key so a newer yarn
+// build no longer serves the stale jar; the bump invalidates v2 outputs once.
+const REMAP_PIPELINE_VERSION = "v3";
 function normalizeTargetNamespace(target) {
     return target === "yarn" ? "yarn" : "mojang";
 }
@@ -58,14 +65,18 @@ function copyJarToDestination(sourceJar, destinationJar) {
     mkdirSync(dirname(destinationJar), { recursive: true });
     copyFileSync(sourceJar, destinationJar);
 }
-function buildCacheKey(inputJar, fromNamespace, targetNamespace, mcVersion) {
+function buildCacheKey(inputJar, fromNamespace, targetNamespace, mcVersion, mappingIdentity) {
     const stat = statSync(inputJar, { throwIfNoEntry: false });
     const signature = stat ? `${stat.mtimeMs}:${stat.size}` : "unknown";
     return createHash("sha256")
-        .update(`${inputJar}|${signature}|${fromNamespace}|${targetNamespace}|${mcVersion}`)
+        .update(`${REMAP_PIPELINE_VERSION}|${inputJar}|${signature}|${fromNamespace}|${targetNamespace}|${mcVersion}|${mappingIdentity}`)
         .digest("hex");
 }
-export async function remapModJar(input, config) {
+export async function remapModJar(input, config, deps = {}) {
+    const remapJarFn = deps.remapJar ?? remapJar;
+    const resolveTinyMappingFileFn = deps.resolveTinyMappingFile ?? resolveTinyMappingFile;
+    const resolveMojangTinyFileFn = deps.resolveMojangTinyFile ?? resolveMojangTinyFile;
+    const resolveTinyRemapperJarFn = deps.resolveTinyRemapperJar ?? resolveTinyRemapperJar;
     const startedAt = Date.now();
     const warnings = [];
     // 1. Normalize input JAR path
@@ -111,12 +122,33 @@ export async function remapModJar(input, config) {
         });
     }
     const outputJar = resolveOutputJarPath(input, normalizedInput, analysis.modId, analysis.modVersion);
-    // 4. Check cache after mapping context is known
-    const cacheKey = buildCacheKey(normalizedInput, fromNamespace, resolvedTargetNamespace, mcVersion);
+    // 4. Resolve the mapping identity BEFORE the cache key so the key reflects
+    // which mappings produced the jar. Yarn builds are mutable (Fabric publishes
+    // new builds per MC version), so the resolved yarn coordinate is the identity;
+    // mojang is immutable per release so its version-keyed path string suffices.
+    // The yarn resolution is TTL-fenced (see resolveTinyMappingFile), so on the
+    // common warm path this is zero-network and stays off the cache-hit fast path.
+    let mappingIdentity;
+    let resolvedYarnTiny;
+    if (fromNamespace === resolvedTargetNamespace) {
+        // No remap will run (input already in target namespace); the output is a
+        // copy of the input, so no mapping identity is involved.
+        mappingIdentity = `copy:${resolvedTargetNamespace}`;
+    }
+    else if (resolvedTargetNamespace === "yarn") {
+        resolvedYarnTiny = await resolveTinyMappingFileFn(mcVersion, "yarn", config.cacheDir, undefined, {
+            forceRefresh: input.forceRemap
+        });
+        mappingIdentity = resolvedYarnTiny.coordinate ?? resolvedYarnTiny.path;
+    }
+    else {
+        mappingIdentity = `${mcVersion}-mojang-merged.tiny`;
+    }
+    const cacheKey = buildCacheKey(normalizedInput, fromNamespace, resolvedTargetNamespace, mcVersion, mappingIdentity);
     const cacheDir = join(config.cacheDir, "remapped-mods");
     mkdirSync(cacheDir, { recursive: true });
     const cachedOutput = join(cacheDir, `${cacheKey}.jar`);
-    if (existsSync(cachedOutput)) {
+    if (!input.forceRemap && existsSync(cachedOutput)) {
         const cacheHitOutputJar = input.outputJar
             ? outputJar
             : cachedOutput;
@@ -161,51 +193,74 @@ export async function remapModJar(input, config) {
         });
     }
     // 5. Resolve tiny-remapper
-    const tinyRemapperJar = await resolveTinyRemapperJar(config.cacheDir, config.tinyRemapperJarPath);
-    // 6. Resolve mapping file and remap
-    let mappingsFile;
-    let toNamespace;
+    const tinyRemapperJar = await resolveTinyRemapperJarFn(config.cacheDir, config.tinyRemapperJarPath);
+    const passes = [];
     if (resolvedTargetNamespace === "yarn") {
-        mappingsFile = await resolveTinyMappingFile(mcVersion, "yarn", config.cacheDir);
-        toNamespace = "named";
+        // The Fabric yarn v2 tiny declares both intermediary and named, so a single
+        // intermediary -> named pass is sufficient.
+        // Reuse the coordinate resolved for the cache key (already TTL-fenced).
+        const yarnTiny = resolvedYarnTiny ?? await resolveTinyMappingFileFn(mcVersion, "yarn", config.cacheDir, undefined, {
+            forceRefresh: input.forceRemap
+        });
+        passes.push({ mappingsFile: yarnTiny.path, fromNamespace, toNamespace: "named" });
     }
     else {
-        const mojangTiny = await resolveMojangTinyFile(mcVersion, config);
-        mappingsFile = mojangTiny.path;
-        toNamespace = "mojang";
+        // Mojang target. The merged mojang tiny only bridges obfuscated <-> mojang,
+        // but a Fabric/Quilt jar is intermediary-named, so a direct intermediary ->
+        // mojang remap finds no matching keys and silently no-ops. Remap in two passes:
+        //   pass 1: intermediary -> official (= obfuscated) via the Fabric intermediary v2 tiny
+        //   pass 2: obfuscated    -> mojang                via the merged mojang tiny
+        const mojangTiny = await resolveMojangTinyFileFn(mcVersion, config);
         warnings.push(...mojangTiny.warnings);
+        if (fromNamespace === "intermediary") {
+            const intermediaryTiny = await resolveTinyMappingFileFn(mcVersion, "intermediary", config.cacheDir);
+            passes.push({ mappingsFile: intermediaryTiny.path, fromNamespace: "intermediary", toNamespace: "official" });
+            passes.push({ mappingsFile: mojangTiny.path, fromNamespace: "obfuscated", toNamespace: "mojang" });
+        }
+        else {
+            // Defensive: an already-obfuscated input maps directly. (mojang -> mojang is
+            // handled earlier by the copy short-circuit, so this is not normally reached.)
+            passes.push({ mappingsFile: mojangTiny.path, fromNamespace: "obfuscated", toNamespace: "mojang" });
+        }
     }
     mkdirSync(dirname(outputJar), { recursive: true });
-    // 8. Use temporary directory for intermediate work
+    // 7. Use a temporary directory for intermediate work
     const tempDir = join(tmpdir(), `mcp-remap-${cacheKey.slice(0, 12)}`);
     mkdirSync(tempDir, { recursive: true });
     try {
-        const tempOutput = join(tempDir, "remapped.jar");
-        try {
-            await remapJar(tinyRemapperJar, {
-                inputJar: normalizedInput,
-                outputJar: tempOutput,
-                mappingsFile,
-                fromNamespace,
-                toNamespace,
-                timeoutMs: config.remapTimeoutMs,
-                maxMemoryMb: config.remapMaxMemoryMb
-            });
-        }
-        catch (caughtError) {
-            if (isAppError(caughtError)) {
-                throw createError({
-                    code: caughtError.code,
-                    message: caughtError.message,
-                    details: {
-                        ...(caughtError.details ?? {}),
-                        fromMapping: fromNamespace,
-                        targetMapping: input.targetMapping,
-                        resolvedTargetNamespace
-                    }
+        let passInput = normalizedInput;
+        let tempOutput = "";
+        for (let passIndex = 0; passIndex < passes.length; passIndex += 1) {
+            const pass = passes[passIndex];
+            tempOutput = join(tempDir, `pass-${passIndex}.jar`);
+            try {
+                await remapJarFn(tinyRemapperJar, {
+                    inputJar: passInput,
+                    outputJar: tempOutput,
+                    mappingsFile: pass.mappingsFile,
+                    fromNamespace: pass.fromNamespace,
+                    toNamespace: pass.toNamespace,
+                    timeoutMs: config.remapTimeoutMs,
+                    maxMemoryMb: config.remapMaxMemoryMb
                 });
             }
-            throw caughtError;
+            catch (caughtError) {
+                if (isAppError(caughtError)) {
+                    throw createError({
+                        code: caughtError.code,
+                        message: caughtError.message,
+                        details: {
+                            ...(caughtError.details ?? {}),
+                            fromMapping: fromNamespace,
+                            targetMapping: input.targetMapping,
+                            resolvedTargetNamespace,
+                            pass: `${pass.fromNamespace}->${pass.toNamespace}`
+                        }
+                    });
+                }
+                throw caughtError;
+            }
+            passInput = tempOutput;
         }
         // Copy to final destination and cache
         copyFileSync(tempOutput, outputJar);

package/dist/nbt/java-nbt-codec.js

@@ -37,6 +37,91 @@ function resolveTagName(tagId, pointer) {
     }
     return tagName;
 }
+// Java NBT TAG_String uses MUTF-8 (Mojang's on-disk format matches the JVM
+// `DataInput/OutputStream.{read,write}UTF` contract), which differs from UTF-8
+// for two ranges: `U+0000` encodes as `C0 80`, and supplementary code points
+// (`U+10000`+) encode as two 3-byte sequences for the UTF-16 surrogate pair
+// (6 bytes total). All other characters share the UTF-8 byte sequence.
+function mutf8ByteLength(value) {
+    let length = 0;
+    for (let i = 0; i < value.length; i += 1) {
+        const c = value.charCodeAt(i);
+        if (c === 0x0000) {
+            length += 2;
+        }
+        else if (c <= 0x007f) {
+            length += 1;
+        }
+        else if (c <= 0x07ff) {
+            length += 2;
+        }
+        else {
+            length += 3;
+        }
+    }
+    return length;
+}
+function encodeMutf8(value) {
+    const buffer = Buffer.allocUnsafe(mutf8ByteLength(value));
+    let offset = 0;
+    for (let i = 0; i < value.length; i += 1) {
+        const c = value.charCodeAt(i);
+        if (c === 0x0000) {
+            buffer[offset++] = 0xc0;
+            buffer[offset++] = 0x80;
+        }
+        else if (c <= 0x007f) {
+            buffer[offset++] = c;
+        }
+        else if (c <= 0x07ff) {
+            buffer[offset++] = 0xc0 | (c >> 6);
+            buffer[offset++] = 0x80 | (c & 0x3f);
+        }
+        else {
+            buffer[offset++] = 0xe0 | (c >> 12);
+            buffer[offset++] = 0x80 | ((c >> 6) & 0x3f);
+            buffer[offset++] = 0x80 | (c & 0x3f);
+        }
+    }
+    return buffer;
+}
+function decodeMutf8(buffer, start, end) {
+    const codeUnits = [];
+    let i = start;
+    while (i < end) {
+        const b0 = buffer[i++];
+        if ((b0 & 0x80) === 0) {
+            codeUnits.push(b0);
+        }
+        else if ((b0 & 0xe0) === 0xc0) {
+            if (i >= end) {
+                throw parseError("Truncated MUTF-8 2-byte sequence.", { offset: i - 1 });
+            }
+            const b1 = buffer[i++];
+            if ((b1 & 0xc0) !== 0x80) {
+                throw parseError("Invalid MUTF-8 continuation byte.", { byte: b1, offset: i - 1 });
+            }
+            codeUnits.push(((b0 & 0x1f) << 6) | (b1 & 0x3f));
+        }
+        else if ((b0 & 0xf0) === 0xe0) {
+            if (i + 1 >= end) {
+                throw parseError("Truncated MUTF-8 3-byte sequence.", { offset: i - 1 });
+            }
+            const b1 = buffer[i++];
+            const b2 = buffer[i++];
+            if ((b1 & 0xc0) !== 0x80 || (b2 & 0xc0) !== 0x80) {
+                throw parseError("Invalid MUTF-8 continuation byte.", { offset: i - 2 });
+            }
+            codeUnits.push(((b0 & 0x0f) << 12) | ((b1 & 0x3f) << 6) | (b2 & 0x3f));
+        }
+        else {
+            throw parseError("Invalid MUTF-8 lead byte.", { byte: b0, offset: i - 1 });
+        }
+    }
+    // NBT TAG_String is bounded by uint16 length so codeUnits.length <= 65535,
+    // safely within String.fromCharCode's argument cap.
+    return String.fromCharCode(...codeUnits);
+}
 class NbtReader {
     buffer;
     offset = 0;
@@ -103,7 +188,7 @@ class NbtReader {
     readString() {
         const byteLength = this.readUInt16();
         this.ensure(byteLength);
-        const value = this.buffer.toString("utf8", this.offset, this.offset + byteLength);
+        const value = decodeMutf8(this.buffer, this.offset, this.offset + byteLength);
         this.offset += byteLength;
         return value;
     }
@@ -154,7 +239,7 @@ class NbtWriter {
         this.chunks.push(chunk);
     }
     writeString(value) {
-        const encoded = Buffer.from(value, "utf8");
+        const encoded = encodeMutf8(value);
         if (encoded.length > 0xffff) {
             throw encodeError("NBT string length exceeds uint16.", { byteLength: encoded.length });
         }

package/dist/observability.d.ts

@@ -40,6 +40,8 @@ export interface RuntimeMetricSnapshot {
     search_rows_scanned: number;
     search_rows_returned: number;
     search_indexed_zero_shortcircuit_count: number;
+    search_like_prefilter_count: number;
+    search_scan_truncated_count: number;
     reindex_count: number;
     reindex_skip_count: number;
     cache_evictions: number;
@@ -74,6 +76,8 @@ export declare class RuntimeMetrics {
     private searchRowsScanned;
     private searchRowsReturned;
     private searchIndexedZeroShortcircuitCount;
+    private searchLikePrefilterCount;
+    private searchScanTruncatedCount;
     private reindexCount;
     private reindexSkipCount;
     private cacheEvictions;
@@ -102,6 +106,8 @@ export declare class RuntimeMetrics {
     recordSearchRowsScanned(count: number): void;
     recordSearchRowsReturned(count: number): void;
     recordSearchIndexedZeroShortcircuit(): void;
+    recordSearchLikePrefilter(): void;
+    recordSearchScanTruncated(): void;
     recordReindex(): void;
     recordReindexSkip(): void;
     recordCacheEviction(count?: number): void;

package/dist/observability.js

@@ -26,6 +26,8 @@ export class RuntimeMetrics {
     searchRowsScanned = 0;
     searchRowsReturned = 0;
     searchIndexedZeroShortcircuitCount = 0;
+    searchLikePrefilterCount = 0;
+    searchScanTruncatedCount = 0;
     reindexCount = 0;
     reindexSkipCount = 0;
     cacheEvictions = 0;
@@ -128,6 +130,12 @@ export class RuntimeMetrics {
     recordSearchIndexedZeroShortcircuit() {
         this.searchIndexedZeroShortcircuitCount += 1;
     }
+    recordSearchLikePrefilter() {
+        this.searchLikePrefilterCount += 1;
+    }
+    recordSearchScanTruncated() {
+        this.searchScanTruncatedCount += 1;
+    }
     recordReindex() {
         this.reindexCount += 1;
     }
@@ -192,6 +200,8 @@ export class RuntimeMetrics {
             search_rows_scanned: this.searchRowsScanned,
             search_rows_returned: this.searchRowsReturned,
             search_indexed_zero_shortcircuit_count: this.searchIndexedZeroShortcircuitCount,
+            search_like_prefilter_count: this.searchLikePrefilterCount,
+            search_scan_truncated_count: this.searchScanTruncatedCount,
             reindex_count: this.reindexCount,
             reindex_skip_count: this.reindexSkipCount,
             cache_evictions: this.cacheEvictions,

package/dist/page-cursor.d.ts

@@ -0,0 +1,17 @@
+export type OffsetCursor = {
+    offset: number;
+    contextKey: string;
+};
+/** Build a stable context key from the query parameters a cursor belongs to. */
+export declare function buildPageContextKey(parts: Array<string | number | boolean | undefined>): string;
+export declare function encodeOffsetCursor(offset: number, contextKey: string): string;
+export declare function decodeOffsetCursor(cursor: string | undefined): OffsetCursor | undefined;
+/**
+ * Resolve the starting offset from an incoming cursor. Returns offset 0 when the
+ * cursor is absent, malformed, or belongs to a different query context, and
+ * reports whether a provided cursor was ignored.
+ */
+export declare function resolveCursorOffset(cursor: string | undefined, contextKey: string): {
+    offset: number;
+    cursorIgnored: boolean;
+};

package/dist/registry-service.js

@@ -82,6 +82,25 @@ function parseRegistrySnapshot(raw, version, registryFile) {
             details: { version, registryFile }
         });
     }
+    // Every registry value must carry an `entries` object. Without this guard a
+    // malformed value slips through and later throws a raw TypeError on `.entries`
+    // (registry-service.ts:268/305, version-diff-service.ts), bypassing the
+    // corrupt-snapshot regeneration path that keys off REGISTRY_GENERATION_FAILED.
+    for (const [registryName, value] of Object.entries(parsed)) {
+        const entries = value?.entries;
+        if (typeof value !== "object" ||
+            value === null ||
+            Array.isArray(value) ||
+            typeof entries !== "object" ||
+            entries === null ||
+            Array.isArray(entries)) {
+            throw createError({
+                code: ERROR_CODES.REGISTRY_GENERATION_FAILED,
+                message: `registries.json for version "${version}" has a malformed "${registryName}" registry (missing entries).`,
+                details: { version, registryFile, registryName }
+            });
+        }
+    }
     return parsed;
 }
 function runDataGen(serverJarPath, outputDir, version) {
@@ -252,8 +271,13 @@ export class RegistryService {
     }
     async loadRegistries(version, warnings) {
         const cached = this.registryCache.get(version);
-        if (cached)
+        if (cached) {
+            // LRU touch: move to most-recently-used so the bound evicts the true
+            // coldest entry (Map preserves insertion order).
+            this.registryCache.delete(version);
+            this.registryCache.set(version, cached);
             return cached;
+        }
         const registryDir = join(this.config.cacheDir, "registries", version);
         const cachedRegistries = this.loadExistingRegistries(registryDir, version, warnings);
         if (cachedRegistries) {