@adhisang/minecraft-modding-mcp 3.2.0 → 4.1.0

package/dist/stage-emitter.d.ts

@@ -0,0 +1,13 @@
+export type StageEmitter = (stage: string, meta?: Record<string, unknown>) => Promise<void>;
+export declare const NOOP_STAGE_EMITTER: StageEmitter;
+export type StageEmitterExtra = {
+    requestId?: string | number;
+    sendNotification?: (notification: {
+        method: string;
+        params?: unknown;
+    }) => Promise<void>;
+};
+export type StageEmitterOptions = {
+    disabled?: boolean;
+};
+export declare function makeStageEmitter(extra: StageEmitterExtra | undefined, options?: StageEmitterOptions): StageEmitter;

package/dist/stage-emitter.js

@@ -0,0 +1,30 @@
+import { performance } from "node:perf_hooks";
+const STAGE_PROGRESS_DISABLED = process.env.MIXIN_STAGE_PROGRESS_OFF === "1";
+export const NOOP_STAGE_EMITTER = async () => {
+    /* noop */
+};
+export function makeStageEmitter(extra, options = {}) {
+    if (options.disabled ?? STAGE_PROGRESS_DISABLED) {
+        return NOOP_STAGE_EMITTER;
+    }
+    if (!extra) {
+        return NOOP_STAGE_EMITTER;
+    }
+    const requestId = extra.requestId;
+    const sendNotification = extra.sendNotification;
+    if (requestId === undefined || typeof sendNotification !== "function") {
+        return NOOP_STAGE_EMITTER;
+    }
+    return async (stage, meta) => {
+        await sendNotification({
+            method: "$/stageUpdate",
+            params: {
+                stage,
+                meta: meta ?? null,
+                t: performance.now(),
+                requestId
+            }
+        });
+    };
+}
+//# sourceMappingURL=stage-emitter.js.map

package/dist/stdio-supervisor.d.ts

@@ -1,12 +1,72 @@
+import type { JSONRPCResponse } from "@modelcontextprotocol/sdk/types.js";
 type SupervisorOptions = {
     entryFile: string;
 };
+type RequestId = string | number;
+export type ExitInfo = {
+    code: number | null;
+    signal: NodeJS.Signals | null;
+};
+export type RetryRecommendation = "narrow-query" | "clear-cache" | "report-bug" | "same-request";
+export type RestartContext = {
+    toolName: string | undefined;
+    durationMs: number;
+    lastStage: string | undefined;
+    lastStageElapsedMs: number | undefined;
+    lastStageMeta: unknown;
+    exit: ExitInfo;
+    toolArgsRedacted: Record<string, unknown> | undefined;
+    /** `true` when redaction replaced any value with a sentinel placeholder; the synthetic envelope omits `suggestedCall` in that case. */
+    toolArgsRedactedModified: boolean;
+    retryRecommendation: RetryRecommendation;
+};
+export type PendingRequestSnapshot = {
+    id: RequestId;
+    method?: string;
+    toolName?: string;
+    toolArgsRedacted?: Record<string, unknown>;
+    /** `true` when toolArgsRedacted contains sentinel placeholders (truncate/redact/overflow). */
+    toolArgsRedactedModified?: boolean;
+    startedAt: number;
+    lastStage?: string;
+    lastStageStartedAt?: number;
+    lastStageMeta?: unknown;
+};
+export declare function buildLegacyJsonRpcError(id: RequestId): JSONRPCResponse;
+export type RedactedToolArgs = {
+    args: Record<string, unknown>;
+    /** `true` when redaction replaced any value with a sentinel; supervisor uses this to decide whether to surface `suggestedCall`. */
+    modified: boolean;
+};
+export declare function redactToolArgs(args: unknown): RedactedToolArgs;
+export declare function decideRetryRecommendation(ctx: Pick<RestartContext, "toolName" | "lastStage" | "lastStageMeta" | "exit">, recentRestartTimestamps: number[]): RetryRecommendation;
+export declare function buildSyntheticCallToolResult(id: RequestId, ctx: RestartContext): JSONRPCResponse;
+export declare function pruneRestartTimestamps(timestamps: number[], now: number, windowMs?: number): number[];
+/**
+ * Group a worker-exit batch by toolName and produce the per-tool pruned
+ * timestamp set plus the post-exit snapshot. Grouping ensures one exit
+ * counts as one death per tool regardless of how many concurrent pending
+ * requests it killed. `prunedByTool` feeds `buildWorkerRestartReply`;
+ * `updatedByTool` is what the caller writes back to `recentRestarts`.
+ */
+export declare function buildExitTimestampGroups(pendingToolNames: Iterable<string | undefined>, recentRestarts: Map<string, number[]>, now: number): {
+    prunedByTool: Map<string, number[]>;
+    updatedByTool: Map<string, number[]>;
+};
+export type BuildWorkerRestartReplyOptions = {
+    structuredRestartDisabled?: boolean;
+};
+export declare function buildWorkerRestartReply(req: PendingRequestSnapshot, exit: ExitInfo, now: number, recentRestartTimestamps: number[], options?: BuildWorkerRestartReplyOptions): {
+    reply: JSONRPCResponse;
+    updatedTimestamps: number[];
+};
 export declare class StdioSupervisor {
     private readonly entryFile;
     private readonly clientReader;
     private readonly workerReader;
     private readonly queuedMessages;
     private readonly pendingRequests;
+    private readonly recentRestarts;
     private child;
     private childReady;
     private shuttingDown;
@@ -33,6 +93,7 @@ export declare class StdioSupervisor {
     private readonly handleWorkerProcessError;
     private readonly handleWorkerExit;
     private handleWorkerMessage;
+    private applyStageUpdate;
     private handleWorkerReady;
     private isInitializationResponse;
     private flushQueue;

package/dist/stdio-supervisor.js

@@ -2,10 +2,20 @@ import { spawn } from "node:child_process";
 import process from "node:process";
 import { encodeJsonRpcMessage, JsonRpcFrameReader } from "./json-rpc-framing.js";
 import { log } from "./logger.js";
+import { buildSuggestedCall } from "./build-suggested-call.js";
+import { getToolSchema } from "./tool-schema-registry.js";
 const DEFAULT_CLIENT_MODE = "line";
 const WORKER_MODE_ENV = "MCP_STDIO_WORKER_MODE";
 const WORKER_READY_MARKER = "__MCP_STDIO_WORKER_READY__";
 const SUPERVISOR_DEBUG_ENABLED = process.env.MCP_SUPERVISOR_DEBUG === "1";
+const STRUCTURED_RESTART_DISABLED = process.env.SUPERVISOR_STRUCTURED_RESTART_OFF === "1";
+const RESTART_WINDOW_MS = 60_000;
+const RESTART_REPEAT_THRESHOLD = 3;
+const REDACT_KEY_PATTERNS = [/secret/i, /token/i, /apikey/i, /password/i];
+const PRESERVED_PATH_KEYS = new Set(["projectPath", "sourcePath", "mixinConfigPath"]);
+const MAX_STRING_BYTES = 256;
+const MAX_ARRAY_LENGTH = 8;
+const MAX_OBJECT_KEYS = 16;
 function isRequest(message) {
     return "method" in message && "id" in message;
 }
@@ -23,7 +33,7 @@ function getTrackedRequestId(message) {
 function requestKey(id) {
     return `${typeof id}:${String(id)}`;
 }
-function buildWorkerRestartError(id) {
+export function buildLegacyJsonRpcError(id) {
     return {
         jsonrpc: "2.0",
         id,
@@ -33,6 +43,252 @@ function buildWorkerRestartError(id) {
         }
     };
 }
+function byteLengthUtf8(value) {
+    return Buffer.byteLength(value, "utf8");
+}
+function isRedactKey(key) {
+    return REDACT_KEY_PATTERNS.some((re) => re.test(key));
+}
+function redactValue(value, counter, keyName) {
+    if (keyName !== undefined && !PRESERVED_PATH_KEYS.has(keyName) && isRedactKey(keyName)) {
+        counter.modified = true;
+        return "<redacted>";
+    }
+    if (value === null || value === undefined) {
+        return value;
+    }
+    const valueType = typeof value;
+    if (valueType === "string") {
+        const str = value;
+        if (keyName !== undefined && PRESERVED_PATH_KEYS.has(keyName)) {
+            return str;
+        }
+        const byteLen = byteLengthUtf8(str);
+        if (byteLen > MAX_STRING_BYTES) {
+            counter.modified = true;
+            return `<truncated:${byteLen} bytes>`;
+        }
+        return str;
+    }
+    if (valueType === "number" || valueType === "boolean") {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        if (value.length > MAX_ARRAY_LENGTH) {
+            counter.modified = true;
+            const head = value
+                .slice(0, MAX_ARRAY_LENGTH)
+                .map((item) => redactValue(item, counter));
+            head.push(`<+${value.length - MAX_ARRAY_LENGTH} more>`);
+            return head;
+        }
+        return value.map((item) => redactValue(item, counter));
+    }
+    if (valueType === "object") {
+        const entries = Object.entries(value);
+        const limited = entries.slice(0, MAX_OBJECT_KEYS);
+        const result = {};
+        for (const [key, child] of limited) {
+            result[key] = redactValue(child, counter, key);
+        }
+        if (entries.length > MAX_OBJECT_KEYS) {
+            counter.modified = true;
+            result["<+more>"] = `<+${entries.length - MAX_OBJECT_KEYS} more keys>`;
+        }
+        return result;
+    }
+    return undefined;
+}
+export function redactToolArgs(args) {
+    if (args === null || args === undefined || typeof args !== "object" || Array.isArray(args)) {
+        return { args: {}, modified: false };
+    }
+    const counter = { modified: false };
+    const redacted = redactValue(args, counter);
+    if (redacted && typeof redacted === "object" && !Array.isArray(redacted)) {
+        return { args: redacted, modified: counter.modified };
+    }
+    return { args: {}, modified: counter.modified };
+}
+export function decideRetryRecommendation(ctx, recentRestartTimestamps) {
+    if (ctx.lastStage === "target-lookup") {
+        const meta = ctx.lastStageMeta;
+        const targetTotal = typeof meta?.targetTotal === "number" ? meta.targetTotal : undefined;
+        if (targetTotal !== undefined && targetTotal > 5) {
+            return "narrow-query";
+        }
+    }
+    if (ctx.exit.signal === "SIGABRT" || ctx.exit.signal === "SIGSEGV" || ctx.exit.signal === "SIGKILL") {
+        return "clear-cache";
+    }
+    if (recentRestartTimestamps.length >= RESTART_REPEAT_THRESHOLD) {
+        return "report-bug";
+    }
+    return "same-request";
+}
+export function buildSyntheticCallToolResult(id, ctx) {
+    const tool = ctx.toolName ?? "unknown";
+    const hints = [];
+    if (ctx.lastStage) {
+        const indexNote = (() => {
+            const meta = ctx.lastStageMeta;
+            if (meta &&
+                typeof meta.targetIndex === "number" &&
+                typeof meta.targetTotal === "number") {
+                return `at index ${meta.targetIndex}/${meta.targetTotal}`;
+            }
+            return "";
+        })();
+        const recommendation = (() => {
+            switch (ctx.retryRecommendation) {
+                case "narrow-query":
+                    return "narrow mixinConfigPath to one file and retry";
+                case "clear-cache":
+                    return "clear cache and retry";
+                case "report-bug":
+                    return "report a bug — repeated worker exits";
+                case "same-request":
+                default:
+                    return "retry the same request";
+            }
+        })();
+        hints.push(`lastStage=${ctx.lastStage}${indexNote ? ` ${indexNote}` : ""} — ${recommendation}`);
+    }
+    else {
+        hints.push("worker exited before stage tracking began");
+    }
+    const error = {
+        type: "about:blank/mcp/worker-restart",
+        title: "MCP worker restarted",
+        detail: `The worker process exited while handling tools/call (${tool}).`,
+        status: 503,
+        code: "ERR_WORKER_RESTART",
+        instance: `urn:mcp:request:${String(id)}`,
+        hints
+    };
+    // Mutated args carry sentinel placeholders (`<truncated:…>`, `<redacted>`)
+    // that are not safe to retry. Surface them on `meta.restart.redactedToolArgs`
+    // for diagnostics instead.
+    if (ctx.toolArgsRedacted !== undefined && !ctx.toolArgsRedactedModified) {
+        // Only emit `suggestedCall` when the resolved tool name is a
+        // currently-registered public tool. The "unknown" fallback above and
+        // unregistered names (typo, disabled tool, version-skewed) cannot
+        // produce a re-callable payload; buildSuggestedCall fails open for
+        // unregistered names so the registration check belongs here. The
+        // diagnostic `restart.redactedToolArgs` field below still surfaces the
+        // args.
+        if (ctx.toolName !== undefined &&
+            ctx.toolName.length > 0 &&
+            getToolSchema(ctx.toolName) !== undefined) {
+            const gated = buildSuggestedCall({
+                tool: ctx.toolName,
+                params: ctx.toolArgsRedacted
+            });
+            if (gated.suggestedCall) {
+                error.suggestedCall = gated.suggestedCall;
+            }
+        }
+    }
+    if (ctx.lastStage !== undefined) {
+        error.failedStage = ctx.lastStage;
+    }
+    const restart = {
+        tool,
+        durationMs: ctx.durationMs,
+        lastStage: ctx.lastStage ?? null,
+        lastStageElapsedMs: ctx.lastStageElapsedMs ?? null,
+        lastStageMeta: ctx.lastStageMeta ?? null,
+        exit: {
+            code: ctx.exit.code,
+            signal: ctx.exit.signal
+        },
+        retryRecommendation: ctx.retryRecommendation
+    };
+    // Diagnostic echo (paired with the modified flag); not retryable.
+    if (ctx.toolArgsRedacted !== undefined) {
+        restart.redactedToolArgs = ctx.toolArgsRedacted;
+        restart.redactedToolArgsModified = ctx.toolArgsRedactedModified;
+    }
+    const meta = {
+        synthetic: true,
+        syntheticSource: "supervisor",
+        restart
+    };
+    const structuredContent = { error, meta };
+    return {
+        jsonrpc: "2.0",
+        id,
+        result: {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(structuredContent)
+                }
+            ],
+            isError: true,
+            structuredContent
+        }
+    };
+}
+export function pruneRestartTimestamps(timestamps, now, windowMs = RESTART_WINDOW_MS) {
+    const cutoff = now - windowMs;
+    return timestamps.filter((t) => t >= cutoff);
+}
+/**
+ * Group a worker-exit batch by toolName and produce the per-tool pruned
+ * timestamp set plus the post-exit snapshot. Grouping ensures one exit
+ * counts as one death per tool regardless of how many concurrent pending
+ * requests it killed. `prunedByTool` feeds `buildWorkerRestartReply`;
+ * `updatedByTool` is what the caller writes back to `recentRestarts`.
+ */
+export function buildExitTimestampGroups(pendingToolNames, recentRestarts, now) {
+    const prunedByTool = new Map();
+    const updatedByTool = new Map();
+    for (const raw of pendingToolNames) {
+        const toolName = raw ?? "unknown";
+        if (prunedByTool.has(toolName))
+            continue;
+        const pruned = pruneRestartTimestamps(recentRestarts.get(toolName) ?? [], now);
+        prunedByTool.set(toolName, pruned);
+        updatedByTool.set(toolName, [...pruned, now]);
+    }
+    return { prunedByTool, updatedByTool };
+}
+export function buildWorkerRestartReply(req, exit, now, recentRestartTimestamps, options = {}) {
+    if (options.structuredRestartDisabled || req.method !== "tools/call") {
+        return {
+            reply: buildLegacyJsonRpcError(req.id),
+            updatedTimestamps: recentRestartTimestamps
+        };
+    }
+    const pruned = pruneRestartTimestamps(recentRestartTimestamps, now);
+    // Include the current restart in the count so "3 deaths in 60s →
+    // report-bug" fires on the third event, not the fourth.
+    const updatedTimestamps = [...pruned, now];
+    const recommendation = decideRetryRecommendation({
+        toolName: req.toolName,
+        lastStage: req.lastStage,
+        lastStageMeta: req.lastStageMeta,
+        exit
+    }, updatedTimestamps);
+    const ctx = {
+        toolName: req.toolName,
+        durationMs: Math.max(0, now - req.startedAt),
+        lastStage: req.lastStage,
+        lastStageElapsedMs: req.lastStageStartedAt !== undefined
+            ? Math.max(0, now - req.lastStageStartedAt)
+            : undefined,
+        lastStageMeta: req.lastStageMeta,
+        exit,
+        toolArgsRedacted: req.toolArgsRedacted,
+        toolArgsRedactedModified: req.toolArgsRedactedModified ?? false,
+        retryRecommendation: recommendation
+    };
+    return {
+        reply: buildSyntheticCallToolResult(req.id, ctx),
+        updatedTimestamps
+    };
+}
 function debugSupervisor(event, details) {
     if (!SUPERVISOR_DEBUG_ENABLED) {
         return;
@@ -45,6 +301,7 @@ export class StdioSupervisor {
     workerReader = new JsonRpcFrameReader();
     queuedMessages = [];
     pendingRequests = new Map();
+    recentRestarts = new Map();
     child;
     childReady = false;
     shuttingDown = false;
@@ -121,10 +378,21 @@ export class StdioSupervisor {
         if (isRequest(message)) {
             const id = getTrackedRequestId(message);
             if (id !== undefined) {
-                this.pendingRequests.set(requestKey(id), {
+                const pending = {
                     id,
-                    method: message.method
-                });
+                    method: message.method,
+                    startedAt: performance.now()
+                };
+                if (message.method === "tools/call") {
+                    const params = (message.params ?? {});
+                    if (typeof params.name === "string") {
+                        pending.toolName = params.name;
+                    }
+                    const redacted = redactToolArgs(params.arguments);
+                    pending.toolArgsRedacted = redacted.args;
+                    pending.toolArgsRedactedModified = redacted.modified;
+                }
+                this.pendingRequests.set(requestKey(id), pending);
             }
             if (message.method === "initialize") {
                 this.initializeSentToWorker = true;
@@ -202,7 +470,7 @@ export class StdioSupervisor {
             signal,
             pendingRequests: this.pendingRequests.size
         });
-        this.failPendingRequestsOnWorkerExit();
+        this.failPendingRequestsOnWorkerExit({ code, signal });
         this.scheduleRestart();
     };
     handleWorkerMessage(message) {
@@ -212,6 +480,12 @@ export class StdioSupervisor {
             id: "id" in message ? message.id : undefined,
             replayingInitialization: this.replayingInitialization
         });
+        if (isNotification(message) && typeof message.method === "string" && message.method.startsWith("$/")) {
+            if (message.method === "$/stageUpdate") {
+                this.applyStageUpdate(message.params);
+            }
+            return;
+        }
         if (this.isInitializationResponse(message)) {
             const id = getTrackedRequestId(message);
             if (id !== undefined) {
@@ -240,6 +514,33 @@ export class StdioSupervisor {
         }
         this.writeToClient(message);
     }
+    applyStageUpdate(params) {
+        if (params === null || params === undefined || typeof params !== "object") {
+            return;
+        }
+        const p = params;
+        const requestId = typeof p.requestId === "string" || typeof p.requestId === "number"
+            ? p.requestId
+            : undefined;
+        if (requestId === undefined)
+            return;
+        const pending = this.pendingRequests.get(requestKey(requestId));
+        if (!pending)
+            return;
+        // Refresh `lastStageStartedAt` only on stage transitions so
+        // `lastStageElapsedMs` measures from stage entry, not from the latest
+        // per-target emit. `lastStageMeta` still updates on every emit so
+        // restart envelopes carry the latest progress payload.
+        if (typeof p.stage === "string" && p.stage !== pending.lastStage) {
+            pending.lastStage = p.stage;
+            pending.lastStageStartedAt = performance.now();
+        }
+        else if (pending.lastStageStartedAt === undefined) {
+            // First emit for this request; bootstrap the stage timer.
+            pending.lastStageStartedAt = performance.now();
+        }
+        pending.lastStageMeta = p.meta;
+    }
     handleWorkerReady() {
         debugSupervisor("worker_ready", {
             hasInitializeRequest: this.initializeRequest !== undefined,
@@ -278,16 +579,32 @@ export class StdioSupervisor {
             this.forwardToWorker(message);
         }
     }
-    failPendingRequestsOnWorkerExit() {
+    failPendingRequestsOnWorkerExit(exit) {
         const preservedInitializeKey = this.initializeRequest && !this.clientInitialized
             ? requestKey(this.initializeRequest.id)
             : undefined;
+        const now = performance.now();
+        // Record this exit once per toolName regardless of how many concurrent
+        // pending requests it killed; per-request recording would inflate the
+        // count to N and falsely escalate retryRecommendation to "report-bug".
+        const pendingToolNames = [];
+        for (const [key, pending] of this.pendingRequests.entries()) {
+            if (key === preservedInitializeKey)
+                continue;
+            pendingToolNames.push(pending.toolName);
+        }
+        const { prunedByTool, updatedByTool } = buildExitTimestampGroups(pendingToolNames, this.recentRestarts, now);
+        for (const [toolName, updated] of updatedByTool) {
+            this.recentRestarts.set(toolName, updated);
+        }
         for (const [key, pending] of [...this.pendingRequests.entries()]) {
-            if (key === preservedInitializeKey) {
+            if (key === preservedInitializeKey)
                 continue;
-            }
             this.pendingRequests.delete(key);
-            this.writeToClient(buildWorkerRestartError(pending.id));
+            const toolName = pending.toolName ?? "unknown";
+            const pruned = prunedByTool.get(toolName) ?? [];
+            const { reply } = buildWorkerRestartReply(pending, exit, now, pruned, { structuredRestartDisabled: STRUCTURED_RESTART_DISABLED });
+            this.writeToClient(reply);
         }
     }
     writeToClient(message) {

package/dist/storage/artifacts-repo.d.ts

@@ -3,6 +3,7 @@ import type { ArtifactProvenance, ArtifactRow, SourceMapping, SourceOrigin } fro
 type SqliteDatabase = InstanceType<typeof Database>;
 interface UpsertArtifactInput {
     artifactId: string;
+    alias?: string;
     origin: SourceOrigin;
     coordinate?: string;
     version?: string;
@@ -27,6 +28,7 @@ export declare class ArtifactsRepo {
     private readonly upsertStmt;
     private readonly getStmt;
     private readonly touchStmt;
+    private readonly setAliasStmt;
     private readonly deleteStmt;
     private readonly listStmt;
     private readonly countStmt;
@@ -34,8 +36,9 @@ export declare class ArtifactsRepo {
     private readonly listLruWithContentBytesStmt;
     constructor(db: SqliteDatabase);
     upsertArtifact(input: UpsertArtifactInput): void;
-    getArtifact(artifactId: string): ArtifactRow | undefined;
+    getArtifact(artifactIdOrAlias: string): ArtifactRow | undefined;
     touchArtifact(artifactId: string, timestamp: string): void;
+    setAlias(artifactId: string, alias: string): void;
     deleteArtifact(artifactId: string): void;
     listArtifactsByLru(limit: number): ArtifactRow[];
     countArtifacts(): number;

package/dist/storage/artifacts-repo.js

@@ -35,6 +35,7 @@ function parseQualityFlags(value) {
 function toArtifactRow(record) {
     return {
         artifactId: record.artifact_id,
+        alias: record.alias ?? undefined,
         origin: record.origin,
         coordinate: record.coordinate ?? undefined,
         version: record.version ?? undefined,
@@ -59,6 +60,7 @@ export class ArtifactsRepo {
     upsertStmt;
     getStmt;
     touchStmt;
+    setAliasStmt;
     deleteStmt;
     listStmt;
     countStmt;
@@ -68,11 +70,12 @@ export class ArtifactsRepo {
         this.db = db;
         this.upsertStmt = this.db.prepare(`
       INSERT INTO artifacts (
-        artifact_id, origin, coordinate, version, binary_jar_path, source_jar_path, repo_url, requested_mapping, mapping_applied, provenance_json, quality_flags_json, artifact_signature, is_decompiled, created_at, updated_at
+        artifact_id, alias, origin, coordinate, version, binary_jar_path, source_jar_path, repo_url, requested_mapping, mapping_applied, provenance_json, quality_flags_json, artifact_signature, is_decompiled, created_at, updated_at
       ) VALUES (
-        @artifact_id, @origin, @coordinate, @version, @binary_jar_path, @source_jar_path, @repo_url, @requested_mapping, @mapping_applied, @provenance_json, @quality_flags_json, @artifact_signature, @is_decompiled, @created_at, @updated_at
+        @artifact_id, @alias, @origin, @coordinate, @version, @binary_jar_path, @source_jar_path, @repo_url, @requested_mapping, @mapping_applied, @provenance_json, @quality_flags_json, @artifact_signature, @is_decompiled, @created_at, @updated_at
       )
       ON CONFLICT(artifact_id) DO UPDATE SET
+        alias = excluded.alias,
         origin = excluded.origin,
         coordinate = excluded.coordinate,
         version = excluded.version,
@@ -87,9 +90,12 @@ export class ArtifactsRepo {
         is_decompiled = excluded.is_decompiled,
         updated_at = excluded.updated_at
     `);
+        // artifact_id is a 64-char SHA hex; alias is `<type>-<...>-<6charhex>` containing
+        // dashes/letters. The two namespaces cannot collide, so OR-matching is unambiguous.
         this.getStmt = this.db.prepare(`
       SELECT
         artifact_id,
+        alias,
         origin,
         coordinate,
         version,
@@ -105,17 +111,28 @@ export class ArtifactsRepo {
         created_at,
         updated_at
       FROM artifacts
-      WHERE artifact_id = ?
+      WHERE artifact_id = ? OR alias = ?
+      LIMIT 1
     `);
         this.touchStmt = this.db.prepare(`
       UPDATE artifacts
       SET updated_at = ?
       WHERE artifact_id = ?
+    `);
+        // Persists alias on cache-hit / migrated-row paths where upsertArtifact would
+        // otherwise be skipped. Conditional WHERE keeps it idempotent and avoids a
+        // pointless write when alias is already correct.
+        this.setAliasStmt = this.db.prepare(`
+      UPDATE artifacts
+      SET alias = ?
+      WHERE artifact_id = ?
+        AND (alias IS NULL OR alias <> ?)
     `);
         this.deleteStmt = this.db.prepare(`DELETE FROM artifacts WHERE artifact_id = ?`);
         this.listStmt = this.db.prepare(`
       SELECT
         artifact_id,
+        alias,
         origin,
         coordinate,
         version,
@@ -157,6 +174,7 @@ export class ArtifactsRepo {
     upsertArtifact(input) {
         this.upsertStmt.run({
             artifact_id: input.artifactId,
+            alias: input.alias ?? null,
             origin: input.origin,
             coordinate: input.coordinate ?? null,
             version: input.version ?? null,
@@ -173,8 +191,11 @@ export class ArtifactsRepo {
             updated_at: input.timestamp
         });
     }
-    getArtifact(artifactId) {
-        const row = this.getStmt.get([artifactId]);
+    // Accepts either an artifact_id (64-char SHA hex) or a human-readable alias
+    // (e.g. `mc-1.21.10-mojang-merged-5ad2e7`). The two key namespaces cannot
+    // collide because aliases always contain `-` and a non-hex prefix.
+    getArtifact(artifactIdOrAlias) {
+        const row = this.getStmt.get([artifactIdOrAlias, artifactIdOrAlias]);
         if (!row) {
             return undefined;
         }
@@ -183,6 +204,13 @@ export class ArtifactsRepo {
     touchArtifact(artifactId, timestamp) {
         this.touchStmt.run([timestamp, artifactId]);
     }
+    // Backfills or rotates the alias for an existing row. Used by warm-cache
+    // resolveArtifact paths where upsertArtifact is skipped, so a freshly
+    // computed alias still reaches the DB and stays in sync with the value the
+    // caller just received in the response.
+    setAlias(artifactId, alias) {
+        this.setAliasStmt.run([alias, artifactId, alias]);
+    }
     deleteArtifact(artifactId) {
         this.deleteStmt.run([artifactId]);
     }

package/dist/storage/files-repo.d.ts

@@ -43,8 +43,6 @@ export declare class FilesRepo {
     private readonly db;
     private readonly deleteStmt;
     private readonly insertFilesStmt;
-    private readonly insertFtsStmt;
-    private readonly deleteFtsStmt;
     private readonly getContentStmt;
     private readonly listStmt;
     private readonly listRowsStmt;