From 099d4b50b6aaedc8fa69cc2c73290f35cda7b66b Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Mon, 20 Apr 2026 13:56:18 +0100
Subject: [PATCH] docs: clarify alias map memoization rationale

---
 src/plugins/sdk-alias.test.ts | 4 +---
 src/plugins/sdk-alias.ts      | 8 +++-----
 2 files changed, 4 insertions(+), 8 deletions(-)

diff --git a/src/plugins/sdk-alias.test.ts b/src/plugins/sdk-alias.test.ts
index 6a3742f4490..3e5e88f9621 100644
--- a/src/plugins/sdk-alias.test.ts
+++ b/src/plugins/sdk-alias.test.ts
@@ -1058,7 +1058,7 @@ export const syntheticRuntimeMarker = {
 });
 
 describe("buildPluginLoaderAliasMap memoization", () => {
-  it("returns the same object reference for identical inputs (jiti sentinel safety)", () => {
+  it("returns the same object reference for identical effective context", () => {
     const fixture = createPluginSdkAliasFixture();
     const sourceRootAlias = path.join(fixture.root, "src", "plugin-sdk", "root-alias.cjs");
     fs.writeFileSync(sourceRootAlias, "module.exports = {};\n", "utf-8");
@@ -1070,8 +1070,6 @@ describe("buildPluginLoaderAliasMap memoization", () => {
     const first = buildPluginLoaderAliasMap(sourcePluginEntry);
     const second = buildPluginLoaderAliasMap(sourcePluginEntry);
 
-    // Reference identity is critical: jiti's normalizeAliases uses a
-    // reference-identity sentinel to skip O(N²) re-processing.
     expect(second).toBe(first);
   });
 
diff --git a/src/plugins/sdk-alias.ts b/src/plugins/sdk-alias.ts
index 2b14cd29297..e709f226f8a 100644
--- a/src/plugins/sdk-alias.ts
+++ b/src/plugins/sdk-alias.ts
@@ -430,11 +430,9 @@ export function resolveExtensionApiAlias(params: LoaderModuleResolveParams = {})
   return null;
 }
 
-// Memoize alias maps by inputs so the same object reference is returned for
-// identical parameters. jiti's `normalizeAliases` uses a reference-identity
-// sentinel (`if (e[pt]) return e`) to skip its O(N²) normalization — returning
-// the same object lets the sentinel fire on the 2nd+ call instead of repeating
-// the full cycle every time. See #68983.
+// Memoize alias maps by effective resolution context so repeated loader setup
+// avoids rebuilding the same filesystem-derived map. Include cwd/env inputs
+// because the fallback root and private QA alias surfaces depend on them.
 const aliasMapCache = new Map<string, Record<string, string>>();
 
 function buildPluginLoaderAliasMapCacheKey(params: {