refactor(runtime): drop hardcoded client vocabulary from the loader

The runtime provides mechanism; the client supplies vocabulary. Removed: NormalizeViteSpecifier and both of its second-chance import-map lookups (clients register every rewritten specifier form verbatim), the underscore-chunk bare-specifier heuristic, the import('@') empty-stub sentinel complex on all five sites (a bare '@' now fails loudly as an unresolvable specifier on every route, and can be mapped through the import map like any other specifier), the default canonicalization vocabulary (/ns/, /node_modules/.vite/, /@id/, /@fs/, the /@ng/component preserve rule, and the import/t/v strip params), and the client-URL-shape diagnostic labels. Unconfigured canonicalization is purely mechanical - the fragment is stripped and nothing else; the query is part of the module's identity until the client teaches the runtime otherwise via configureLoader({ canonicalization }). The two supported configure-before-ESM-traffic bootstrap shapes are documented in the cross-runtime contract.
NathanWalker · Aug 20, 2026 · Aug 13, 2026 · Aug 13, 2026 · Aug 13, 2026 · Aug 13, 2026
commit 73ebaabc6c57ee800692eb996f7e2e4e92cfb054
diff --git a/test-app/app/src/main/assets/app/tests/testNsModule.js b/test-app/app/src/main/assets/app/tests/testNsModule.js
@@ -67,22 +67,22 @@ describe("HTTP canonical key (ns:module canonicalizeHttpUrlKey)", function () {
         expect(typeof canon).toBe("function");
     });
 
-    it("drops dev cache-busters (t/v/import) but keeps real query params", function () {
-        checkKey("http://h/ns/core?p=x&t=123&v=9&import=1", "http://h/ns/core?p=x");
+    // Unconfigured, canonicalization is purely mechanical: the fragment goes
+    // and the query stays. Which params are cache-busters and which paths are
+    // dev endpoints is client vocabulary the runtime no longer guesses.
+    it("unconfigured: strips the fragment and nothing else", function () {
+        checkKey("http://h/app/foo.js#frag", "http://h/app/foo.js");
+        checkKey("http://h/app/foo.js?t=123&v=9#frag", "http://h/app/foo.js?t=123&v=9");
     });
 
-    it("leaves public (non-dev, non-volatile) URLs untouched", function () {
+    it("unconfigured: leaves every query param in the key", function () {
+        checkKey("http://h/app/foo.js?t=123&v=9&import=1", "http://h/app/foo.js?t=123&v=9&import=1");
         checkKey("https://cdn.example.com/lib.js?token=abc", "https://cdn.example.com/lib.js?token=abc");
     });
 
     it("treats module identity as literally the URL — no path-tag collapses", function () {
-        checkKey("http://h/ns/m/foo.js", "http://h/ns/m/foo.js");
-        checkKey("http://h/ns/rt", "http://h/ns/rt");
-        checkKey("http://h/ns/core", "http://h/ns/core");
-    });
-
-    it("ignores URL fragments for dev endpoints", function () {
-        checkKey("http://h/ns/m/foo.js#frag", "http://h/ns/m/foo.js");
+        checkKey("http://h/app/m/foo.js", "http://h/app/m/foo.js");
+        checkKey("http://h/app/rt", "http://h/app/rt");
     });
 
     it("honors a client-supplied canonicalization vocabulary via configureLoader", function () {
@@ -91,15 +91,20 @@ describe("HTTP canonical key (ns:module canonicalizeHttpUrlKey)", function () {
             pending("ns:module.canonicalizeHttpUrlKey not exposed (release build)");
             return;
         }
+        // Neutral vocabulary: the mechanics under test are the runtime's, the
+        // strings are the client's to choose.
         require("ns:module").configureLoader({
             canonicalization: {
-                stripParams: ["t", "v", "import"],
-                forPathPrefixes: ["/ns/", "/node_modules/.vite/", "/@id/", "/@fs/"],
-                preserveQueryFor: ["/@ng/component"],
+                stripParams: ["cachebust", "rev"],
+                forPathPrefixes: ["/dev/"],
+                preserveQueryFor: ["/dev/metadata"],
             },
         });
-        expect(canon("http://h/ns/core?p=x&t=123&v=9&import=1")).toBe("http://h/ns/core?p=x");
-        expect(canon("http://h/ns/m/comp/@ng/component?c=a&t=42")).toBe("http://h/ns/m/comp/@ng/component?c=a&t=42");
-        expect(canon("https://cdn.example.com/lib.js?token=abc")).toBe("https://cdn.example.com/lib.js?token=abc");
+        // Under a configured dev prefix, the named params drop and the rest sort.
+        expect(canon("http://h/dev/core?p=x&cachebust=123&rev=9")).toBe("http://h/dev/core?p=x");
+        // preserveQueryFor wins over the dev prefix: the query IS the identity.
+        expect(canon("http://h/dev/metadata?c=a&cachebust=42")).toBe("http://h/dev/metadata?c=a&cachebust=42");
+        // Outside every configured prefix, the query is untouched.
+        expect(canon("https://cdn.example.com/lib.js?cachebust=abc")).toBe("https://cdn.example.com/lib.js?cachebust=abc");
     });
 });
diff --git a/test-app/runtime/src/main/cpp/HttpLoader.cpp b/test-app/runtime/src/main/cpp/HttpLoader.cpp
@@ -200,37 +200,42 @@ std::string CanonicalizeHttpUrlKey(const std::string& url) {
     std::string originAndPath = (qPos == std::string::npos) ? noHash : noHash.substr(0, qPos);
     std::string query = (qPos == std::string::npos) ? std::string() : noHash.substr(qPos + 1);
 
+    // This key is the module registry/cache key. For general-purpose HTTP
+    // module loading the query can be part of a module's identity (auth,
+    // content versioning, routing), so query normalization applies only to the
+    // endpoints the client names, through the vocabulary it supplies.
+    //
+    // `preserveQueryFor` is checked BEFORE the dev-endpoint prefix test, so it
+    // covers endpoints nested under a dev prefix: for some endpoints the query
+    // IS the identity, and stripping it would collapse every refetch onto the
+    // boot-time key.
+    //
+    // Until a client supplies that vocabulary, canonicalization is purely
+    // mechanical: the fragment is gone and the query stays. Which params are
+    // cache-busters and which paths are dev endpoints is knowledge only the
+    // client has; guessing would silently collapse two distinct modules onto
+    // one registry key.
     const CanonicalizationConfig* canon = CanonicalizationConfigForCurrentIsolate();
+    if (canon == nullptr) {
+        return noHash;
+    }
     {
         std::string pathOnly = originAndPath.substr(pathStart);
-        if (canon) {
-            for (const auto& p : canon->preserveQueryPrefixes) {
-                if (!p.empty() && pathOnly.find(p) != std::string::npos) {
-                    return noHash;
-                }
-            }
-            bool isDevEndpoint = false;
-            for (const auto& p : canon->devPathPrefixes) {
-                if (!p.empty() && StartsWith(pathOnly, p.c_str())) {
-                    isDevEndpoint = true;
-                    break;
-                }
-            }
-            if (!isDevEndpoint) {
+        for (const auto& p : canon->preserveQueryPrefixes) {
+            if (!p.empty() && pathOnly.find(p) != std::string::npos) {
                 return noHash;
             }
-        } else {
-            if (pathOnly.find("/@ng/component") != std::string::npos) {
-                return noHash;
-            }
-            const bool isDevEndpoint = StartsWith(pathOnly, "/ns/") ||
-                                       StartsWith(pathOnly, "/node_modules/.vite/") ||
-                                       StartsWith(pathOnly, "/@id/") ||
-                                       StartsWith(pathOnly, "/@fs/");
-            if (!isDevEndpoint) {
-                return noHash;
+        }
+        bool isDevEndpoint = false;
+        for (const auto& p : canon->devPathPrefixes) {
+            if (!p.empty() && StartsWith(pathOnly, p.c_str())) {
+                isDevEndpoint = true;
+                break;
             }
         }
+        if (!isDevEndpoint) {
+            return noHash;
+        }
     }
 
     if (query.empty()) return originAndPath;
@@ -244,13 +249,8 @@ std::string CanonicalizeHttpUrlKey(const std::string& url) {
         if (!pair.empty()) {
             size_t eq = pair.find('=');
             std::string name = (eq == std::string::npos) ? pair : pair.substr(0, eq);
-            bool drop;
-            if (canon) {
-                drop = std::find(canon->stripParams.begin(), canon->stripParams.end(),
-                                 name) != canon->stripParams.end();
-            } else {
-                drop = (name == "import" || name == "t" || name == "v");
-            }
+            const bool drop = std::find(canon->stripParams.begin(), canon->stripParams.end(),
+                                        name) != canon->stripParams.end();
             if (!drop) kept.push_back(pair);
         }
         if (amp == std::string::npos) break;

diff --git a/test-app/runtime/src/main/cpp/MetadataNode.cpp b/test-app/runtime/src/main/cpp/MetadataNode.cpp
@@ -1866,8 +1866,8 @@ bool MetadataNode::GetExtendLocation(v8::Isolate* isolate, string& extendLocatio
             } else {
                 // srcFileName is not always `file://<APP_ROOT>/<path>.js`:
                 // HTTP ESM loading (HMR dev workflow) passes a full URL like
-                // `http://127.0.0.1:5173/ns/core/...` with no `.js` suffix and
-                // no app-root prefix, so naive scheme/app-root/`.js` stripping
+                // `http://<dev-host>/<path>` with no `.js` suffix and no
+                // app-root prefix, so naive scheme/app-root/`.js` stripping
                 // can yield an empty `fullPathToFile` and crash downstream on
                 // an empty token list.
                 string normalized = srcFileName;