@adhisang/minecraft-modding-mcp 7.0.0-rc.2 → 7.0.0

package/dist/storage/db.js

@@ -135,7 +135,11 @@ export function openDatabase(config, logger = buildDefaultLogger()) {
                     path: config.sqlitePath,
                     reason: errorMessage
                 });
-                throw caughtError;
+                throw createError({
+                    code: ERROR_CODES.DB_FAILURE,
+                    message: `Failed to open SQLite database at ${config.sqlitePath}: ${errorMessage}`,
+                    details: { sqlitePath: config.sqlitePath, reason: caughtError?.code }
+                });
             }
             // The rebuild runs INSIDE the handler for the failure it is recovering
             // from, so it needs a guard of its own: without one a throw from here left

package/dist/tool-schemas.d.ts

@@ -258,10 +258,10 @@ export declare const resolveArtifactShape: {
         full: "full";
     }>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
-        entries: "entries";
         workspace: "workspace";
-        candidates: "candidates";
+        entries: "entries";
         source: "source";
+        candidates: "candidates";
         warnings: "warnings";
         registry: "registry";
         preview: "preview";
@@ -335,10 +335,10 @@ export declare const resolveArtifactSchema: z.ZodObject<{
         full: "full";
     }>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
-        entries: "entries";
         workspace: "workspace";
-        candidates: "candidates";
+        entries: "entries";
         source: "source";
+        candidates: "candidates";
         warnings: "warnings";
         registry: "registry";
         preview: "preview";
@@ -426,10 +426,10 @@ export declare const getClassSourceShape: {
         full: "full";
     }>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
-        entries: "entries";
         workspace: "workspace";
-        candidates: "candidates";
+        entries: "entries";
         source: "source";
+        candidates: "candidates";
         warnings: "warnings";
         registry: "registry";
         preview: "preview";
@@ -518,10 +518,10 @@ export declare const getClassSourceSchema: z.ZodObject<{
         full: "full";
     }>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
-        entries: "entries";
         workspace: "workspace";
-        candidates: "candidates";
+        entries: "entries";
         source: "source";
+        candidates: "candidates";
         warnings: "warnings";
         registry: "registry";
         preview: "preview";
@@ -615,10 +615,10 @@ export declare const getClassMembersShape: {
         full: "full";
     }>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
-        entries: "entries";
         workspace: "workspace";
-        candidates: "candidates";
+        entries: "entries";
         source: "source";
+        candidates: "candidates";
         warnings: "warnings";
         registry: "registry";
         preview: "preview";
@@ -713,10 +713,10 @@ export declare const getClassMembersSchema: z.ZodObject<{
         full: "full";
     }>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
-        entries: "entries";
         workspace: "workspace";
-        candidates: "candidates";
+        entries: "entries";
         source: "source";
+        candidates: "candidates";
         warnings: "warnings";
         registry: "registry";
         preview: "preview";
@@ -935,10 +935,10 @@ export declare const batchClassSourceShape: {
         full: "full";
     }>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
-        entries: "entries";
         workspace: "workspace";
-        candidates: "candidates";
+        entries: "entries";
         source: "source";
+        candidates: "candidates";
         warnings: "warnings";
         registry: "registry";
         preview: "preview";
@@ -1027,10 +1027,10 @@ export declare const batchClassSourceSchema: z.ZodObject<{
         full: "full";
     }>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
-        entries: "entries";
         workspace: "workspace";
-        candidates: "candidates";
+        entries: "entries";
         source: "source";
+        candidates: "candidates";
         warnings: "warnings";
         registry: "registry";
         preview: "preview";
@@ -1135,10 +1135,10 @@ export declare const batchClassMembersShape: {
         signatures: "signatures";
     }>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
-        entries: "entries";
         workspace: "workspace";
-        candidates: "candidates";
+        entries: "entries";
         source: "source";
+        candidates: "candidates";
         warnings: "warnings";
         registry: "registry";
         preview: "preview";
@@ -1230,10 +1230,10 @@ export declare const batchClassMembersSchema: z.ZodObject<{
         signatures: "signatures";
     }>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
-        entries: "entries";
         workspace: "workspace";
-        candidates: "candidates";
+        entries: "entries";
         source: "source";
+        candidates: "candidates";
         warnings: "warnings";
         registry: "registry";
         preview: "preview";
@@ -1339,10 +1339,10 @@ export declare const batchSymbolExistsShape: {
         full: "full";
     }>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
-        entries: "entries";
         workspace: "workspace";
-        candidates: "candidates";
+        entries: "entries";
         source: "source";
+        candidates: "candidates";
         warnings: "warnings";
         registry: "registry";
         preview: "preview";
@@ -1425,10 +1425,10 @@ export declare const batchSymbolExistsSchema: z.ZodObject<{
         full: "full";
     }>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
-        entries: "entries";
         workspace: "workspace";
-        candidates: "candidates";
+        entries: "entries";
         source: "source";
+        candidates: "candidates";
         warnings: "warnings";
         registry: "registry";
         preview: "preview";
@@ -1517,10 +1517,10 @@ export declare const batchMappingsShape: {
         full: "full";
     }>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
-        entries: "entries";
         workspace: "workspace";
-        candidates: "candidates";
+        entries: "entries";
         source: "source";
+        candidates: "candidates";
         warnings: "warnings";
         registry: "registry";
         preview: "preview";
@@ -1590,10 +1590,10 @@ export declare const batchMappingsSchema: z.ZodObject<{
         full: "full";
     }>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
-        entries: "entries";
         workspace: "workspace";
-        candidates: "candidates";
+        entries: "entries";
         source: "source";
+        candidates: "candidates";
         warnings: "warnings";
         registry: "registry";
         preview: "preview";
@@ -1789,10 +1789,10 @@ export declare const searchClassSourceShape: {
         full: "full";
     }>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
-        entries: "entries";
         workspace: "workspace";
-        candidates: "candidates";
+        entries: "entries";
         source: "source";
+        candidates: "candidates";
         warnings: "warnings";
         registry: "registry";
         preview: "preview";
@@ -1891,10 +1891,10 @@ export declare const searchClassSourceSchema: z.ZodObject<{
         full: "full";
     }>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
-        entries: "entries";
         workspace: "workspace";
-        candidates: "candidates";
+        entries: "entries";
         source: "source";
+        candidates: "candidates";
         warnings: "warnings";
         registry: "registry";
         preview: "preview";
@@ -2022,10 +2022,10 @@ export declare const listArtifactFilesShape: {
         full: "full";
     }>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
-        entries: "entries";
         workspace: "workspace";
-        candidates: "candidates";
+        entries: "entries";
         source: "source";
+        candidates: "candidates";
         warnings: "warnings";
         registry: "registry";
         preview: "preview";
@@ -2087,10 +2087,10 @@ export declare const listArtifactFilesSchema: z.ZodObject<{
         full: "full";
     }>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
-        entries: "entries";
         workspace: "workspace";
-        candidates: "candidates";
+        entries: "entries";
         source: "source";
+        candidates: "candidates";
         warnings: "warnings";
         registry: "registry";
         preview: "preview";
@@ -2233,10 +2233,10 @@ export declare const findMappingShape: {
         full: "full";
     }>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
-        entries: "entries";
         workspace: "workspace";
-        candidates: "candidates";
+        entries: "entries";
         source: "source";
+        candidates: "candidates";
         warnings: "warnings";
         registry: "registry";
         preview: "preview";
@@ -2305,10 +2305,10 @@ export declare const findMappingSchema: z.ZodObject<{
         full: "full";
     }>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
-        entries: "entries";
         workspace: "workspace";
-        candidates: "candidates";
+        entries: "entries";
         source: "source";
+        candidates: "candidates";
         warnings: "warnings";
         registry: "registry";
         preview: "preview";
@@ -2360,10 +2360,10 @@ export declare const resolveMethodMappingExactShape: {
         full: "full";
     }>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
-        entries: "entries";
         workspace: "workspace";
-        candidates: "candidates";
+        entries: "entries";
         source: "source";
+        candidates: "candidates";
         warnings: "warnings";
         registry: "registry";
         preview: "preview";
@@ -2415,10 +2415,10 @@ export declare const resolveMethodMappingExactSchema: z.ZodObject<{
         full: "full";
     }>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
-        entries: "entries";
         workspace: "workspace";
-        candidates: "candidates";
+        entries: "entries";
         source: "source";
+        candidates: "candidates";
         warnings: "warnings";
         registry: "registry";
         preview: "preview";
@@ -2507,10 +2507,10 @@ export declare const resolveWorkspaceSymbolShape: {
         full: "full";
     }>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
-        entries: "entries";
         workspace: "workspace";
-        candidates: "candidates";
+        entries: "entries";
         source: "source";
+        candidates: "candidates";
         warnings: "warnings";
         registry: "registry";
         preview: "preview";
@@ -2562,10 +2562,10 @@ export declare const resolveWorkspaceSymbolSchema: z.ZodObject<{
         full: "full";
     }>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
-        entries: "entries";
         workspace: "workspace";
-        candidates: "candidates";
+        entries: "entries";
         source: "source";
+        candidates: "candidates";
         warnings: "warnings";
         registry: "registry";
         preview: "preview";
@@ -2624,10 +2624,10 @@ export declare const checkSymbolExistsShape: {
         full: "full";
     }>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
-        entries: "entries";
         workspace: "workspace";
-        candidates: "candidates";
+        entries: "entries";
         source: "source";
+        candidates: "candidates";
         warnings: "warnings";
         registry: "registry";
         preview: "preview";
@@ -2686,10 +2686,10 @@ export declare const checkSymbolExistsSchema: z.ZodObject<{
         full: "full";
     }>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
-        entries: "entries";
         workspace: "workspace";
-        candidates: "candidates";
+        entries: "entries";
         source: "source";
+        candidates: "candidates";
         warnings: "warnings";
         registry: "registry";
         preview: "preview";
@@ -3125,8 +3125,8 @@ export declare const modSearchTypeSchema: z.ZodEnum<{
     class: "class";
     field: "field";
     method: "method";
-    all: "all";
     content: "content";
+    all: "all";
 }>;
 export declare const searchModSourceShape: {
     jarPath: z.ZodString;
@@ -3135,8 +3135,8 @@ export declare const searchModSourceShape: {
         class: "class";
         field: "field";
         method: "method";
-        all: "all";
         content: "content";
+        all: "all";
     }>>;
     limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
 };
@@ -3147,8 +3147,8 @@ export declare const searchModSourceSchema: z.ZodObject<{
         class: "class";
         field: "field";
         method: "method";
-        all: "all";
         content: "content";
+        all: "all";
     }>>;
     limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
 }, z.core.$strip>;

package/dist/types.d.ts

@@ -182,9 +182,26 @@ export interface Config {
     remapMaxMemoryMb: number;
     decompileMaxMemoryMb: number;
 }
-export interface ArtifactSignature {
+/**
+ * A jar's filesystem stat, stamped. NOT an artifact identity: nothing here is
+ * read from the jar's bytes, so a `touch` moves it and a byte-for-byte
+ * replacement of the same length at the same mtime does not.
+ *
+ * Artifact identity lives in `src/artifact-identity.ts`. This shape feeds the
+ * `jarSignature` field `get-project-context` publishes, and that field's
+ * stat-based value is part of the tool's output contract.
+ */
+export interface JarStatStamp {
     sourcePath: string;
+    /**
+     * sha256 of `jar|<resolved path>|<mtimeMs>:<size>`.
+     *
+     * The name is inherited and overstates it: this is not the artifactId of
+     * anything. Its only consumer is the `jarSignature` field in
+     * `src/minecraft-explorer-service.ts`.
+     */
     sourceArtifactId: string;
+    /** The `<truncated mtimeMs>:<size>` stamp itself. */
     signature: string;
     signatureParts: {
         mtimeMs: number;

package/docs/tool-reference.md

@@ -142,7 +142,7 @@ Artifact-relative file read from a workspace:
 | target shape | When to use | Required input | Result |
 |---|---|---|---|
 | `{ kind: "workspace", scope?, strict? }` | When the caller already passes a `projectPath` and wants the tool to detect Minecraft version, compile mapping, and loader from `gradle.properties` and `build.gradle(.kts)`. | `projectPath` | Synthesised to `{ kind: "version", value: <detected> }`. Scope precedence is `target.scope` → top-level `scope` → loader-derived default (`"merged"` when a loader is detected, `"vanilla"` otherwise). When the version is not detected, raises `ERR_WORKSPACE_VERSION_UNRESOLVED` regardless of `strict`. Detected facts surface on `provenance.workspaceResolution`. |
-| `{ kind: "dependency", group, name, version?, versionFromProject? }` | When the caller wants to resolve a Maven-coordinate dependency (e.g. `dev.architectury:architectury`) without computing the exact version themselves. | `projectPath` (unless `version` is given) | Synthesised to `{ kind: "coordinate", value: "<group>:<name>:<version>" }`. The dependency JAR is treated as non-vanilla: binary remap is suppressed, so a non-obfuscated mapping request is honored only if a source-backed jar can supply it. If a source-backed jar is available, the resolver returns `mappingApplied` equal to the requested mapping with `qualityFlags` including `"source-backed"`, and no warning is added. Otherwise the resolver returns the JAR with `mappingApplied: "obfuscated"` and `qualityFlags: ["dependency-mapping-unverified"]`, plus a warning that the caller must validate symbol availability. Resolution metadata appears on `provenance.dependencyResolution`. |
+| `{ kind: "dependency", group, name, version?, versionFromProject? }` | When the caller wants to resolve a Maven-coordinate dependency (e.g. `dev.architectury:architectury`) without computing the exact version themselves. | `projectPath` (unless `version` is given) | Synthesised to `{ kind: "coordinate", value: "<group>:<name>:<version>" }`. The dependency JAR is treated as non-vanilla: binary remap is suppressed, so a non-obfuscated mapping request is honored only if a source-backed jar can supply it. If a source-backed jar is available, the resolver returns `mappingApplied` equal to the requested mapping with `qualityFlags` including `"source-backed"`, and no warning is added. If none is, that same non-obfuscated request comes back with `mappingApplied: "obfuscated"` and `qualityFlags` including `"dependency-mapping-unverified"`, plus a warning that the caller must validate symbol availability. An explicit `mapping: "obfuscated"` request never takes that branch: it passes through as `mappingApplied: "obfuscated"` with `qualityFlags` including `"source-backed"` (or `"decompiled"`), and never carries `"dependency-mapping-unverified"`. Resolution metadata appears on `provenance.dependencyResolution`. |
 
 ### Inspecting a Fabric / loader dependency like vanilla
 
@@ -161,11 +161,18 @@ the same way you read vanilla, pass a `dependency` target straight to
 ```
 
 Use an explicit `"version"` instead of `versionFromProject` when you already
-know it. Because dependency JARs are not remapped, members come back in the
-dependency's own namespace with `qualityFlags: ["dependency-mapping-unverified"]`;
-treat the names as the JAR's compiled names. For repeated lookups against the
-same dependency, call `resolve-artifact` once and reuse the returned
-`artifactId` via `target: { kind: "artifact", artifactId }`.
+know it. Because dependency JARs are not binary-remapped, a non-obfuscated
+mapping request is honored only when a source-backed jar can supply it: there
+`mappingApplied` equals the requested mapping and `qualityFlags` includes
+`"source-backed"`. When no source-backed jar can supply it, that same
+non-obfuscated request comes back in the dependency's own namespace with
+`mappingApplied: "obfuscated"` and `qualityFlags` including
+`"dependency-mapping-unverified"`, and the names are the JAR's compiled names.
+A request that asks for `"obfuscated"` outright is a separate branch: it passes
+through as `mappingApplied: "obfuscated"` with `"source-backed"` or
+`"decompiled"`, never with `"dependency-mapping-unverified"`.
+For repeated lookups against the same dependency, call `resolve-artifact` once
+and reuse the returned `artifactId` via `target: { kind: "artifact", artifactId }`.
 
 Workspace detection is memoised in a process-resident `WorkspaceContextCache` (16-entry LRU, 5-minute TTL). The cache is observable through `manage-cache` with `cacheKinds: ["workspace"]`, and individual entries can be invalidated via `selector.projectPath`.
 
@@ -382,6 +389,7 @@ Because only `issueOrigin` is overridable, the two axes can disagree, and one pa
 - `get-class-members` — every `target.kind` except `"jar"`, `{ "kind": "artifact", "artifactId": ... }` included. An `artifactId` is an opaque handle: its holder cannot tell from it whether the artifact has a binary jar, and cannot re-resolve it either, since `resolve-artifact` does not accept an `artifactId`. Only `target: { "kind": "jar", ... }`, where the caller named the exact jar, reports `issueOrigin: "code_issue"`.
 - `batch-class-members` — same rule, applied once to the shared target and repeated on every failed entry. Its target schema has no `"artifact"` kind at all, so only `"jar"` reports `code_issue`.
 - `inspect-minecraft` `task="class-members"` — same rule once more: only a subject whose artifact reference is `target: { "kind": "jar", ... }` reports `code_issue`. A subject naming a resolved artifact (`{ "type": "resolved-id", "artifactId": ... }`) reports `tool_issue`, matching the equivalent `get-class-members` target: it is the same opaque handle from an earlier resolve, and wrapping it in a subject does not give the caller any way to vet the artifact's binary jar.
+- `verify-mixin-target` — the same rule on its own `target`: the tool reads the target's members from bytecode, so every `target.kind` except `"jar"` reports `tool_issue`. Like `batch-class-members`, its target schema has no `"artifact"` kind at all, so only `"jar"` reports `code_issue`.
 
 To check whether an artifact carries a binary jar before retrying, call `manage-cache` with `action: "inspect"`, `selector: { "artifactId": ... }` and `include: ["cacheEntries"]`. The `cacheEntries` block reports that artifact's stored `meta.binaryJarPath` — read from the same row the members lookup reads, and absent when the row has none. The `include` is not optional: `manage-cache` defaults to `detail: "summary"`, which drops `cacheEntries` entirely, so without it the reply never shows the field (`detail: "standard"` or `"full"` opts the block back in as well).
 
@@ -443,7 +451,7 @@ These environment variables are read once at worker startup and provide rollback
   | `workspace.detected` | A `gradle.properties`, `settings.gradle{,.kts}`, or `build.gradle{,.kts}` file exists at `subject.projectPath`. | `evidence: ["gradle.properties", ...]` lists the gradle files that were found. | `missing` when no gradle files exist; `error` when the filesystem read itself failed. |
   | `gradle.readable` | `gradle.properties` can be read and the workspace's gradle build scripts are enumerable. | `propertiesPath` and `buildScripts[]` (relative paths). | `skipped` when `workspace.detected` is not `ok`; `missing` when no gradle files at all; `error` on parse / read failure. |
   | `loom.cache.found` | A Loom (Fabric / Quilt) cache directory exists under the workspace, `gradleUserHome`, or the process `GRADLE_USER_HOME`. It is independent of `workspace.detected`, so callers can detect a global Loom cache even on non-Gradle workspaces. | `cachePath` of the first matching directory. | `missing` when none of the candidate roots exist; `error` on filesystem failure. |
-  | `minecraft.artifact.resolved` | A lightweight artifact metadata probe can locate `target: { kind: "version", value: <resolvedVersion> }` against the workspace context. The probe does not decompile Minecraft or rebuild the source index. | `artifactId` and `mappingApplied`. | `skipped` when `workspace.detected` or `gradle.readable` is not `ok`; `error` when the lightweight probe cannot verify the artifact or requested mapping without full resolution (carries `error.code` and `error.detail`). |
+  | `minecraft.artifact.resolved` | A lightweight artifact metadata probe can locate `target: { kind: "version", value: <resolvedVersion> }` against the workspace context. The probe does not decompile Minecraft or rebuild the source index. It does read the runtime jar's bytes to derive the reported `artifactId`, which is composed from that digest and the jar's symlink-resolved path; repeat probes of the same jar in one process reuse the digest. | `artifactId` and `mappingApplied`. | `skipped` when `workspace.detected` or `gradle.readable` is not `ok`; `error` when the lightweight probe cannot verify the artifact or requested mapping without full resolution (carries `error.code` and `error.detail`). |
   | `mixins.validated` | At least one `*.mixins.json` file was discovered AND every per-config validation completed without throwing. | `counts: { ok, partial, invalid }` (validation outcomes from `validate-mixin`). | `error` when any per-config validation threw (still emits `counts`); `skipped` when discovery was empty AND `workspace.detected` / `gradle.readable` blocked; `missing` when discovery returned 0 paths and upstream probes were `ok`. A failed `minecraft.artifact.resolved` does not flip executed validators to `skipped`. |
   | `accessWideners.validated` | At least one Access Widener file was discovered AND every validation completed without throwing. | `counts: { ok, invalid }`. | Same rules as `mixins.validated`. |
   | `accessTransformers.validated` | At least one Access Transformer file was discovered AND every validation completed without throwing. | `counts: { ok, invalid }`. | Same rules as `mixins.validated`. |
@@ -481,7 +489,7 @@ MCP resources provide URI-based access to Minecraft data for clients that suppor
 | `find-mapping` | `mc://mappings/{version}/{sourceMapping}/{targetMapping}/{kind}/{name}` | Look up a **class** mapping between two naming namespaces. The URI carries no `owner`, so use `find-member-mapping` (or the `find-mapping` tool) for field/method lookups. |
 | `find-member-mapping` | `mc://mappings/{version}/{sourceMapping}/{targetMapping}/{kind}/{owner}/{name}` | Look up a **field or method** mapping, including the `owner` class the member belongs to. For exact method overload resolution use the `find-mapping` tool with a `descriptor`. |
 | `class-members` | `mc://artifact/{artifactId}/members/{className}` | List constructors, methods, and fields for a class |
-| `artifact-metadata` | `mc://artifact/{artifactId}` | Metadata for a previously resolved artifact |
+| `artifact-metadata` | `mc://artifact/{artifactId}` | Metadata for a previously resolved artifact. Its `artifactSignature` field carries the artifact's identity signature: a bare 64-character sha256 hex digest of the identified jar's bytes, or that digest followed by `:decompile`. A client that pattern-matched the older `<mtimeMs>:<size>` shape no longer matches. |
 
 `versions-list`, `runtime-metrics`, `find-mapping`, `find-member-mapping`, `class-source-json`, `class-members`, and `artifact-metadata` return structured JSON envelopes on success (`{ result, meta }`) and failure (`{ error, meta }`).
 
@@ -524,7 +532,7 @@ The supervisor caches the completed `initialize` / `notifications/initialized` p
 The legacy wire contract is byte-compatible with the pre-migration (SDK v1) server, with these recorded exceptions:
 
 - `tools/call` with `arguments` omitted reaches the application validator as `{}`. Three outcome arms: (a) input-free tools succeed (`get-runtime-metrics`); (b) required-field schemas answer per-field `ERR_INVALID_INPUT` (`analyze-mod`); (c) a `{}`-accepting schema whose handler requires input answers that tool's own handler-level ProblemDetails — `json-to-nbt` answers `ERR_NBT_INVALID_TYPED_JSON` (status 400, `isError: true`) instead of the pre-migration validation-layer `ERR_INVALID_INPUT`.
-- Legacy `tools/list` entries omit the v1-only `execution: {"taskSupport":"forbidden"}` field (SDK v2 does not emit it); every other advertised field, including the `inputSchema` bytes, is identical to the pre-migration snapshots.
+- Legacy `tools/list` entries omit the v1-only `execution: {"taskSupport":"forbidden"}` field (SDK v2 does not emit it); the migration introduced no other drift, and the `inputSchema` bytes are served verbatim from the frozen pre-migration contracts in `tests/fixtures/premigration/tool-contracts/` (through the generated `src/v1-parity-schemas.ts`, which `tools/list` advertises in preference to the zod shape). Those frozen contracts are deliberately extended when a tool genuinely gains a parameter in a later release — 7.0.0-rc.2 added `projectPath` to four of the flat-`artifactId` tools — so "identical to the pre-migration snapshots" describes the migration, not a promise that a tool's schema never changes across releases.
 - An unknown or disabled tool is answered immediately at the supervisor, before queueing: the reply bytes are identical to v1, but the reply consumes no queue slot and no worker round-trip, so reply ordering and queue-overflow outcomes can differ from v1 under concurrent load.
 - The unmatched-resource-URI error keeps the raw JSON-RPC `-32602` code, but its message changed from the pre-migration `MCP error -32602: Resource <uri> not found` to `Resource not found: <uri>`, and the error carries a `data.uri` field (SDK v2 wording).
 - The `initialize` result advertises `resources: { listChanged: false }` and `tools: { listChanged: false }`, where the pre-migration server advertised `true` for both. The suppression is deliberate and is NOT era-gated — both eras read one `getCapabilities()`, so gating it would leave one process advertising two different contracts; the reasoning is under the modern-era capability paragraph below. Every other byte of the `initialize` result is unchanged.
@@ -616,11 +624,13 @@ Notification variants: a modern-era notification without a valid claim (for exam
 
 ### Synthetic terminal responses and retry semantics
 
-Supervisor-synthesized replies (queue overflow, worker restart, `validate-project` timeout, startup failure — shapes in `## Errors` and `## Meta fields`) are FINAL for that request instance: a late worker answer for the same id is discarded, so a client sees exactly one response per id. Retrying with the SAME id after a synthetic terminal reply is legal — the retry re-forwards and clears the finality bookkeeping. Era rejections synthesize no such finality (they answer without forwarding), and dropped notifications receive no response at all. Modern-era synthetic results are decorated like ordinary modern results (`resultType: "complete"` plus the identity `_meta` echo); legacy synthetic results remain byte-compatible with the pre-migration shapes.
+Supervisor-synthesized replies (queue overflow, worker restart, `validate-project` timeout, startup failure — shapes in `## Errors` and `## Meta fields`) are FINAL for that request instance: a late worker answer for the same id is discarded, so a client sees exactly one response per id. A raw JSON-RPC `-32603` whose message begins "MCP supervisor failed to" belongs to the same class: the supervisor emits one when an internal fault stops it from admitting a request, dispatching a queued one, or handing a worker response back to the client, and it is terminal and discards the worker's own later answer in exactly the same way. One case where the supervisor deliberately sends nothing: when its own cleanup after such a fault cannot prove the request was removed, it reports and stands down rather than risk a second reply for one id. Only `validate-project` carries a deadline of its own, so any other request left in that state waits for the worker to exit. Retrying with the SAME id after a synthetic terminal reply is legal — the retry re-forwards and clears the finality bookkeeping. Era rejections synthesize no such finality (they answer without forwarding), and dropped notifications receive no response at all. Modern-era synthetic results are decorated like ordinary modern results (`resultType: "complete"` plus the identity `_meta` echo); legacy synthetic results remain byte-compatible with the pre-migration shapes.
 
 ### Framing
 
-Standard framing is newline-delimited JSON-RPC (the MCP stdio standard). `Content-Length` header framing is a LOCAL, NONSTANDARD compatibility extension — it is not part of MCP. The reader auto-detects both and may switch mid-stream; every response, including synthetic replies and replies released after a worker restart, uses the framing of the request it answers. `MCP_MAX_FRAME_BYTES` bounds accepted frames (see `## Environment Variables`).
+Standard framing is newline-delimited JSON-RPC (the MCP stdio standard). `Content-Length` header framing is a LOCAL, NONSTANDARD compatibility extension — it is not part of MCP. The reader auto-detects both and may switch mid-stream; every response, including synthetic replies and replies released after a worker restart, uses the framing of the request it answers. `MCP_MAX_FRAME_BYTES` bounds accepted frames (see `## Environment Variables`), and a header block is capped at 8 KiB.
+
+A `Content-Length` header block ends at its FIRST EMPTY LINE. A header line ends at an LF, and a CR immediately before that LF belongs to the terminator, so all four combinations a peer can write — `\r\n\r\n`, `\n\n`, `\n\r\n` and `\r\n\n` — delimit the block, and no `\r\n\r\n` sequence inside the JSON body can be mistaken for one. An EXTRA empty line after that terminator is body, not header: the peer's declared `Content-Length` does not count it, so the body window opens two or three bytes early and normally runs off the end of the JSON. That is a body-parse failure, which is framing-fatal — the session ends and the frames behind it are lost. Such a frame is malformed, but the outcome is worth knowing: it is not recovered from. It is not certain to fail, either. The window is shifted rather than mis-sized, so a declared length that happens to count trailing whitespace can absorb the shift exactly and the frame is delivered normally; the reader never detects the extra blank line, only where the bytes fall.
 
 ### Adopted-policy note
 
@@ -708,7 +718,9 @@ Path-based overrides treat blank values and the literal strings `undefined` and
 | `MCP_MAPPING_SOURCE_PRIORITY` | `loom-first` | Mapping source priority (`loom-first` or `maven-first`) |
 | `MCP_VERSION_MANIFEST_URL` | Mojang manifest URL | Override the Minecraft version manifest endpoint |
 
-Jars downloaded from the repositories in `MCP_SOURCE_REPOS` are cached under `MCP_CACHE_DIR` and identified by a sha256 of their bytes, so the same jar keeps one `artifactId` no matter which repository served it. (Minecraft version jars and mapping archives share that cache directory but are identified separately.) Whether a cached jar is re-checked depends on the coordinate's **version**, not on which repository serves it. A release version is served from cache with no request. A version ending in `-SNAPSHOT` is treated as mutable, as Maven defines it, and is re-checked against every configured repository — including the defaults: where the cached copy recorded an `ETag` or `Last-Modified` the check is a conditional request and an unchanged answer costs no transfer, otherwise the jar is transferred again. A republished jar replaces the cached one and yields a new `artifactId`. If the check cannot be completed — anything short of a definitive answer, including unreachable, a timeout, 5xx, 429, or an authentication failure — the cached copy is still served; if the repository answers definitively about the artifact itself (404 or 410 gone, 403 refused) it is treated as absent there and resolution moves on to the next repository. Note that `MCP_SOURCE_REPOS` replaces the default list rather than adding to it.
+Jars downloaded from the repositories in `MCP_SOURCE_REPOS` are cached under `MCP_CACHE_DIR` and identified by a sha256 of their bytes, so the same jar keeps one `artifactId` no matter which repository served it. (Minecraft version jars and mapping archives share that cache directory but sit outside this URL-keyed download-cache identity; a Minecraft version jar's own `artifactId` is covered by the jar rule below.) Jars served from the local stores — `MCP_LOCAL_M2` and the Gradle dependency cache — are identified from their bytes the same way whenever they are reached through a Maven coordinate (`target.kind="dependency"` and `target.kind="coordinate"`), so touching one, or restoring byte-identical contents, keeps its `artifactId`. A jar named directly by path (`target.kind="jar"`) is identified from its bytes as well, and so is a Minecraft runtime jar, because `target.kind="version"` and `target.kind="workspace"` both reach one through that same route. The digest is taken over whichever jar the id is actually about: the named jar's own bytes; or, when the named jar carries no Java sources and its same-name `-sources.jar` sibling supplies them, that sibling's bytes; or, when neither carries sources and the jar goes to the decompiler, the binary jar's bytes under a separate `decompile` identity. The jar's symlink-resolved path still enters the id beside the digest, so one file reached through two names is one artifact, while two byte-identical jars at two real paths stay two artifacts. One bound on "identified from its bytes": within a single server process the digest for a path is reused while that file's size, modification time, inode and inode-change time all still match, so on a filesystem that does not advance the inode-change time on a write, an in-place replacement of the same length whose modification time was restored can be answered from the earlier digest until that memo entry is evicted.
+
+Whether a cached jar is re-checked depends on the coordinate's **version**, not on which repository serves it. A release version is served from cache with no request. A version ending in `-SNAPSHOT` is treated as mutable, as Maven defines it, and is re-checked against every configured repository — including the defaults: where the cached copy recorded an `ETag` or `Last-Modified` the check is a conditional request and an unchanged answer costs no transfer, otherwise the jar is transferred again. A republished jar replaces the cached one and yields a new `artifactId`. If the check cannot be completed — anything short of a definitive answer, including unreachable, a timeout, 5xx, 429, or an authentication failure — the cached copy is still served; if the repository answers definitively about the artifact itself (404 or 410 gone, 403 refused) it is treated as absent there and resolution moves on to the next repository. A definitive answer is also remembered for about five minutes, so a repeat resolve of the same target inside that window is answered from the record instead of asking that repository again. The record is bounded in every direction: only 403, 404 and 410 are eligible, so a timeout, a 5xx, a 429, an authentication failure and a network error are all retried on the next call; a `-SNAPSHOT` coordinate is never recorded; the records are held per cache directory; and they live in memory only, so restarting the server clears them and an artifact published after its rejection was recorded becomes reachable again as soon as the record expires. Note that `MCP_SOURCE_REPOS` replaces the default list rather than adding to it.
 
 ### Search, Index, and Cache Tuning
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhisang/minecraft-modding-mcp",
-  "version": "7.0.0-rc.2",
+  "version": "7.0.0",
   "description": "MCP server for AI-assisted Minecraft modding: inspect decompiled source, resolve Mojang/Yarn/Intermediary mappings, diff versions, analyze Fabric/Forge/NeoForge mod JARs, and validate Mixin, Access Widener, and Access Transformer files.",
   "type": "module",
   "packageManager": "pnpm@10.30.1",