@deepseek-ai/dsh-client-modules 0.1.6-alpha.2 → 0.1.7-alpha.2

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/modules/README.md
-README.md: 5b751268430b716e7a0af24f8e25aaf2f865d079
-README.zh.md: 4152d64ca9dde60ab1aeb76c98508d8d86fcf54e
+README.md: 3388eb2ae421b303df6709f0bfc656fe67e3a866
+README.zh.md: 3cbc600ee5ed211640070773efb72f58b91d4669

package/README.md

@@ -35,7 +35,7 @@ A browser plugin package declares `dsh.client` in its `package.json` with `platf
 
 ### What the browser loads
 
-The application combo scripts carry only each plugin's `client.js` entry and register those factories once during boot; module bodies remain lazy and run only at first import or materialization. A source `import()` split by tsdown compiles to `require.async("./client.<name>.js")`; its versioned sibling script arrives only when that expression runs. Rows that share a combo URL share one in-flight script task. HMR switches one changed row to its revisioned one-resource combo URL. `<id>/client` and the bare id resolve to the same exports, because a plugin bundle is its package's client half.
+The application combo scripts carry only each plugin's `client.js` entry and register those factories once during boot; module bodies remain lazy and run only at first import or materialization. A source `import()` split by tsdown compiles to `require.async("./client.<name>.js")`; its versioned sibling script arrives only when that expression runs. Rows that share a combo URL share one in-flight script task. A combo whose `<script>` fails to load is requested once more; a combo that loads without registering a row is never re-executed, because the batch script registers its packages in sequence and a replay would stop at the first duplicate registration. In both cases each still-missing row then loads its own one-resource combo URL, so one failed batch costs at most three requests per missing row and leaves the rows it did register untouched. The module system records the last import failure per row (transport, registration, dependency cascade, or factory execution); the Web boot audit reports that text per entry. HMR switches one changed row to its revisioned one-resource combo URL. `<id>/client` and the bare id resolve to the same exports, because a plugin bundle is its package's client half.
 
 ### Live plugin composition
 
@@ -71,7 +71,7 @@ Executing a plugin bundle only registers its factory; every module-body side eff
 
 The Node half scans incrementally per package — no full-rescan path. Every `internal/plugin` emission marks the fiber's entry name dirty; a microtask flush reconciles each dirty name against the live loader entries, and the activation pass seeds the same dirty set and flushes synchronously, so first scan and steady state share one implementation. Package metadata is cached per Loader specifier and owning-tree base URL until restart, while the resolved manifest package name identifies the browser module. Distinct active Loader sources resolving to one package name are rejected; removing the conflict promotes the remaining source without requiring its fiber to restart. Bundle content changes reach the graph only through `rebuilt()` (the HMR hook).
 
-The Node half snapshots each `client.js` entry before publication and creates combo descriptors without building response bodies. It groups resources into `/plugins/??...&rev=...` combo URLs, with one bootstrap combo for the modules row and one or more application combos for the other rows; each phase is partitioned before a URL exceeds 3 KiB. A script body is combined once on its first `GET` and ends with its map URL. The corresponding map files are read, validated, and combined separately on the first map `GET`; `HEAD` materializes neither body. The Host does not scan or preload sibling chunks: an exact `/plugins/<package>/client.<name>.js?rev=<rev>` request reads and caches that script, and its map remains uncomputed until the map URL is requested. Every combo or chunk map is Indexed Source Map v3 and uses an authored section when available or an identity section for the packaged bundle. Initial per-plugin revisions use process nonces. During development, the shared preset stamps `client.js` after every package output is written; HMR derives the next revision from the entry bytes and that completed-build stamp, so a chunk-only rebuild changes the owner revision without a Host-side chunk scan. Combo revisions derive from the ordered row revisions. Advertised combo responses and requested chunk responses remain immutable across unrelated graph recomposition, and an unknown resource or revision returns 404.
+The Node half snapshots each `client.js` entry before publication and creates combo descriptors without building response bodies. It groups resources into combo route keys (`/plugins/??...&rev=...`), with one bootstrap combo for the modules row and one or more application combos for the other rows; each phase is partitioned before a URL exceeds 3 KiB. The graph and batch descriptors carry the app-directory-relative form of the same key (`plugins/??...&rev=...`), which a browser document resolves under its own mount, while the response table stays keyed by the absolute route; the source-map trailer is resolved against the combo script's own directory. A script body is combined once on its first `GET` and ends with its map reference. The corresponding map files are read, validated, and combined separately on the first map `GET`; `HEAD` materializes neither body. The Host does not scan or preload sibling chunks: an exact `/plugins/<package>/client.<name>.js?rev=<rev>` request reads and caches that script, and its map remains uncomputed until the map URL is requested. The chunk reference the browser derives from its owner row is document-relative as well (`plugins/<package>/client.<name>.js?rev=<rev>`), and a chunk script's map trailer is the bare `client.<name>.js.map?rev=<rev>` name, which resolves against the script's own directory. Every combo or chunk map is Indexed Source Map v3 and uses an authored section when available or an identity section for the packaged bundle. Initial publication and HMR derive per-plugin revisions from the entry's `mtimeMs`, `ctimeMs`, and size, without hashing artifact contents. Status-change time distinguishes rewrites that preserve mtime and size. Unchanged artifacts therefore retain their revisions across Host restarts, so SSE reconnection does not replace their browser plugins. The shared preset stamps `client.js` after every package output is written, so a chunk-only rebuild changes the owner revision without a Host-side chunk scan. Combo revisions derive from the ordered row revisions. Advertised combo responses and requested chunk responses remain immutable across unrelated graph recomposition, and an unknown resource or revision returns 404.
 
 ### Boot manifest injection
 
@@ -127,6 +127,7 @@ None; this package neither assembles nor sends a provider request.
 
 These limits define what the module system does not do. They are current package constraints, not a task backlog.
 
+- **Metadata-based revisions** — revisions identify filesystem generations, not content equality. Metadata-only changes can reload a plugin; changes invisible in mtime, ctime, and size cannot be distinguished.
 - **Flat module graph by design** — every bundle is one module node whose edges point only at table leaves; the interface (`loadCache`/`edges`/`invalidate`) already supports a general module graph, so the externalization granularity can change without an interface change.
 - **Bootstrap and code replacement limits** — the page retains its modules bootstrap and static platform identities. Removing or replacing the bootstrap requires a page reload; live replacement requests report a page-local error while retaining its fiber and exports; replacing package code and all existing consumers is outside ordinary enable/disable synchronization.
 - **Lazy delivery retains requested bodies** — the Host holds each bundle and lazy response plan; a script or map body remains cached after its first `GET`, and HMR additionally retains one prior startup generation. Memory grows only for response bodies that clients request while preserving one-generation race tolerance.

package/README.zh.md

@@ -35,7 +35,7 @@ kind: "package-reference"
 
 ### 浏览器加载什么
 
-application combo 脚本只携带每个插件的 `client.js` 入口，并在启动时仅注册一次这些 factory；模块主体仍保持惰性，只在首次 import 或物化时运行。经 tsdown 拆分的源码 `import()` 会编译为 `require.async("./client.<name>.js")`；只有执行该表达式时，对应的带版本同级脚本才会到达。共享 combo URL 的 row 共用一个进行中的脚本任务。HMR（热模块替换）会让一条发生变化的 row 改用带 revision 的单资源 combo URL。`<id>/client` 与裸 id 解析到同一组导出，因为插件 bundle 就是其包的客户端半侧。
+application combo 脚本只携带每个插件的 `client.js` 入口，并在启动时仅注册一次这些 factory；模块主体仍保持惰性，只在首次 import 或物化时运行。经 tsdown 拆分的源码 `import()` 会编译为 `require.async("./client.<name>.js")`；只有执行该表达式时，对应的带版本同级脚本才会到达。共享 combo URL 的 row 共用一个进行中的脚本任务。`<script>` 加载失败的 combo 会再请求一次；加载成功但没有注册某条 row 的 combo 绝不会重新执行，因为批量脚本按顺序注册各个包，重放会在第一个重复注册处停止。两种情况下，每条仍缺失的 row 随后加载自己的单资源 combo URL，因此一个失败的 batch 对每条缺失 row 最多花费三次请求，且不影响它已经注册的 row。模块系统按 row 记录最后一次 import 失败（传输、注册、依赖级联或 factory 执行）；Web 启动审计按条目报告该文本。HMR（热模块替换）会让一条发生变化的 row 改用带 revision 的单资源 combo URL。`<id>/client` 与裸 id 解析到同一组导出，因为插件 bundle 就是其包的客户端半侧。
 
 ### 插件动态组合
 
@@ -71,7 +71,7 @@ application combo 脚本只携带每个插件的 `client.js` 入口，并在启
 
 Node 半侧逐包增量扫描——没有全量重扫路径。每次发出 `internal/plugin` 事件时，系统都会把该 fiber 的 entry 名标脏；微任务 flush 会把每个脏名与当前 loader 条目对账，激活 pass 会初始化同一个脏集合并同步 flush，因此首次扫描与稳态共用同一实现。包元数据按 Loader specifier 与所属 tree base URL 缓存至重启，解析出的 manifest（元数据清单）包名作为浏览器模块身份。若不同的 active Loader source 解析到同一包名，组合会失败；移除冲突来源后，剩余来源无需重启 fiber 即可接替。bundle 内容变更只能通过 `rebuilt()`（HMR 钩子）进入图。
 
-Node 半侧会在发布前快照每个 `client.js` 入口，并在不构建响应 body 的情况下创建 combo descriptor。它把资源分组到 `/plugins/??...&rev=...` combo URL：modules row 使用一个 bootstrap combo，其余 row 使用一个或多个 application combo；每个阶段都会在 URL 超过 3 KiB 之前分区。脚本 body 在首次 `GET` 时只组合一次，并以对应 map URL 结尾；map 文件则在首次 map `GET` 时单独读取、校验并组合，`HEAD` 不会物化任一 body。Host 不扫描也不预加载同级 chunk：精确的 `/plugins/<package>/client.<name>.js?rev=<rev>` 请求会读取并缓存该脚本，其 map 仍会等到 map URL 被请求后才计算。每个 combo 或 chunk map 都是 Indexed Source Map v3，并在可用时使用作者提供的 section，否则为已打包 bundle 生成 identity section。初始逐插件 revision 使用进程 nonce。开发期间，共享预设会在该包所有输出写完后标记 `client.js`；HMR 从入口字节和该构建完成标记派生下一 revision，因此仅 chunk 发生重建也会更换 owner revision，无需 Host 扫描 chunk。combo revision 从有序 row revision 派生。已公告的 combo 响应与已请求的 chunk 响应会跨无关图重组保持不可变；未知资源或 revision 返回 404。
+Node 半侧会在发布前快照每个 `client.js` 入口，并在不构建响应 body 的情况下创建 combo descriptor。它把资源分组为 combo 路由键（`/plugins/??...&rev=...`）：modules row 使用一个 bootstrap combo，其余 row 使用一个或多个 application combo；每个阶段都会在 URL 超过 3 KiB 之前分区。启动图与批次描述符携带同一路由键的应用目录相对形式（`plugins/??...&rev=...`），浏览器文档会按其自身挂载解析它，而响应表仍以绝对路由为键；source-map trailer 则相对该 combo 脚本自身目录解析。脚本 body 在首次 `GET` 时只组合一次，并以对应的 map 引用结尾；map 文件则在首次 map `GET` 时单独读取、校验并组合，`HEAD` 不会物化任一 body。Host 不扫描也不预加载同级 chunk：精确的 `/plugins/<package>/client.<name>.js?rev=<rev>` 请求会读取并缓存该脚本，其 map 仍会等到 map URL 被请求后才计算。浏览器从所属 row 派生出该 chunk 引用，因此它同样是文档相对形式（`plugins/<package>/client.<name>.js?rev=<rev>`）；chunk 脚本携带的 map trailer 则是裸文件名 `client.<name>.js.map?rev=<rev>`，由该脚本自身目录解析。每个 combo 或 chunk map 都是 Indexed Source Map v3，并在可用时使用作者提供的 section，否则为已打包 bundle 生成 identity section。首次发布与 HMR 都从入口的 `mtimeMs`、`ctimeMs` 和大小派生逐插件 revision，不对产物内容求哈希。状态变更时间用于区分保留 mtime 和大小的重写。未变化的产物因此会跨 Host 重启保持 revision，SSE 重连不会替换其浏览器插件。共享预设会在该包所有输出写完后标记 `client.js`，因此仅 chunk 发生重建也会更换 owner revision，无需 Host 扫描 chunk。combo revision 从有序 row revision 派生。已公告的 combo 响应与已请求的 chunk 响应会跨无关图重组保持不可变；未知资源或 revision 返回 404。
 
 ### 启动 manifest 注入
 
@@ -127,6 +127,7 @@ bundle 路由随注入的 `webServer` 生命周期注册：服务就绪时注册
 
 这些限制说明模块系统不做什么。它们是当前包约束，不是任务积压。
 
+- **基于元数据的 revision**——revision 标识文件系统代际，而非内容相等性。仅元数据变化也可能重载插件；mtime、ctime 和大小都无法反映的变化无法区分。
 - **有意采用扁平模块图**——每个 bundle 是一个模块节点，其边只指向表中的叶节点；接口（`loadCache`/`edges`/`invalidate`）已经支持通用模块图，因此可以改变 externalization 粒度而不更改接口。
 - **Bootstrap 与代码替换限制**——页面保留 modules bootstrap 和静态平台模块的身份。移除或替换 bootstrap 需要刷新页面；动态替换请求会报告页面本地错误，并保留其 fiber 与导出；替换包代码及其所有现有消费者不属于普通启停同步。
 - **惰性提供会保留已请求的 body**——Host 在内存中保留每个 bundle 与惰性响应计划；脚本或 map body 在首次 `GET` 后保留缓存，HMR 还会保留上一代启动响应。内存仅随客户端实际请求的响应 body 增长，同时保留一代竞态容忍。

package/lib/client.js

@@ -468,6 +468,10 @@ window.__ModuleLoader__.load({
 			return url.replace(/([?&]rev=)[^&#]*/, `$1${encodeURIComponent(rev)}`);
 		}
 		const CLIENT_CHUNK = /^client\.[A-Za-z0-9][A-Za-z0-9._-]*\.js$/;
+		/** The message of a thrown value: an Error's message, anything else stringified. */
+		function describeError(error) {
+			return error instanceof Error ? error.message : String(error);
+		}
 		/** Internal module-table key for one package-local chunk. */
 		function chunkId(ownerId, fileName) {
 			return `${ownerId}/${fileName}`;
@@ -517,6 +521,12 @@ window.__ModuleLoader__.load({
 			materializing = /* @__PURE__ */ new Set();
 			graphRows = /* @__PURE__ */ new Map();
 			loadBundle;
+			/** Last import or prefetch failure per graph row, cleared by a later success or invalidation. */
+			importErrors = /* @__PURE__ */ new Map();
+			/** Batch URLs whose transport or execution already failed; rows still missing from them go straight to their one-resource URL. */
+			failedBundleUrls = /* @__PURE__ */ new Set();
+			/** Every URL whose script has executed once; a batch among them is never requested again. */
+			executedBundleUrls = /* @__PURE__ */ new Set();
 			/**
 			* Build the module system over the parsed boot rows.
 			* @param options - Parsed graph, platform seed, bootstrap module, registration facade, and transport.
@@ -569,23 +579,66 @@ window.__ModuleLoader__.load({
 					rev: this.reloadTargets.get(ownerId)?.rev ?? this.graphRows.get(ownerId)?.rev
 				});
 			}
-			/** Load one graph row so its factory is registered (idempotent per in-flight arrival). */
-			arrive(row) {
-				const { id } = row;
-				if (this.loadCache.has(id) || this.factories.has(id)) return Promise.resolve();
-				const reload = this.reloadTargets.get(id);
-				const url = reload?.url ?? row.initialUrl;
+			/** Run one bundle transport per URL; every row waiting on the same URL shares the in-flight request. */
+			loadShared(url) {
 				let transport = this.pendingArrival.get(url);
 				if (transport === void 0) {
-					transport = this.loadBundle(url).finally(() => {
+					transport = this.loadBundle(url).then(() => {
+						this.executedBundleUrls.add(url);
+					}).finally(() => {
 						this.pendingArrival.delete(url);
 					});
 					this.pendingArrival.set(url, transport);
 				}
-				return transport.then(() => {
-					if (!this.factories.has(id)) throw new Error(`client-modules: bundle ${url} loaded without registering "${id}" via __ModuleLoader__.load`);
-					if (reload !== void 0 && this.reloadTargets.get(id) === reload) this.reloadTargets.delete(id);
-				});
+				return transport;
+			}
+			/**
+			* Load one graph row so its factory is registered (idempotent per in-flight
+			* arrival). A batch script is one classic script that registers every
+			* package in sequence, and {@link register} rejects a second registration,
+			* so the two failure kinds differ: a transport failure (`error` event, nothing
+			* executed) is retried once on the same URL; a script that loaded without
+			* registering this row (a parse error registered nothing, or a runtime throw
+			* stopped it after registering others) is never re-executed, because a replay
+			* would stop again at the first duplicate registration; that holds even when
+			* the row that first imports from the batch is one it did register, because
+			* every executed batch URL is remembered. Either way the row then falls back
+			* to its own one-resource URL, which the Host serves for every package, so one
+			* failed batch costs at most three requests per missing row and never fails
+			* the rows that were registered.
+			*/
+			async arrive(row) {
+				const { id } = row;
+				if (this.loadCache.has(id) || this.factories.has(id)) return;
+				const reload = this.reloadTargets.get(id);
+				const preferred = reload?.url ?? row.initialUrl;
+				const fallback = reload === void 0 && row.url !== preferred ? row.url : void 0;
+				const failures = [];
+				const attempt = async (url) => {
+					try {
+						await this.loadShared(url);
+					} catch (error) {
+						failures.push(`${url}: ${describeError(error)}`);
+						return "transport-failed";
+					}
+					if (this.factories.has(id)) return "registered";
+					failures.push(`${url}: loaded without registering "${id}" via __ModuleLoader__.load`);
+					return "not-registered";
+				};
+				let outcome = "transport-failed";
+				if (this.failedBundleUrls.has(preferred)) failures.push(`${preferred}: skipped after an earlier failure of this bundle`);
+				else if (fallback !== void 0 && this.executedBundleUrls.has(preferred)) {
+					failures.push(`${preferred}: already executed without registering "${id}"`);
+					outcome = "not-registered";
+					this.failedBundleUrls.add(preferred);
+				} else {
+					outcome = await attempt(preferred);
+					if (outcome === "transport-failed") outcome = await attempt(preferred);
+					if (outcome !== "registered" && fallback !== void 0) this.failedBundleUrls.add(preferred);
+				}
+				if (outcome !== "registered" && fallback !== void 0) outcome = await attempt(fallback);
+				if (outcome !== "registered") throw new Error(`client-modules: could not load "${id}": ${failures.join("; ")}`);
+				if (reload !== void 0 && this.reloadTargets.get(id) === reload) this.reloadTargets.delete(id);
 			}
 			/** Register each injected package and unresolved dynamic request before its consumer. */
 			async arriveGraphRow(row, open = [], visited = /* @__PURE__ */ new Set()) {
@@ -598,14 +651,22 @@ window.__ModuleLoader__.load({
 					const id = stripClientSuffix(request);
 					if (this.seed.has(request) || this.loadCache.has(id)) continue;
 					const dependency = this.graphRows.get(id);
-					if (dependency !== void 0) await this.arriveGraphRow(dependency, next, visited);
+					if (dependency !== void 0) await this.arriveDependency(row.id, dependency, next, visited);
 				}
 				for (const packageName of row.inject) {
 					const dependency = this.graphRows.get(packageName);
-					if (dependency !== void 0) await this.arriveGraphRow(dependency, [], visited);
+					if (dependency !== void 0) await this.arriveDependency(row.id, dependency, [], visited);
 				}
 				await this.arrive(row);
 			}
+			/** Arrive one dependency, naming the consumer it failed for so a cascade reads as a chain, not as 44 unrelated failures. */
+			async arriveDependency(consumerId, dependency, open, visited) {
+				try {
+					await this.arriveGraphRow(dependency, open, visited);
+				} catch (error) {
+					throw new Error(`client-modules: "${consumerId}" not loaded because dependency "${dependency.id}" failed: ${describeError(error)}`, { cause: error });
+				}
+			}
 			/** Materialize a registered factory (synchronous; memoized in loadCache). */
 			materialize(id, ownerId = id) {
 				const existing = this.loadCache.get(id);
@@ -685,16 +746,40 @@ window.__ModuleLoader__.load({
 				const existing = this.loadCache.get(id);
 				if (existing !== void 0) return existing.exports;
 				const row = this.graphRows.get(id);
-				if (row !== void 0) await this.arriveGraphRow(row);
-				else if (!this.factories.has(id)) throw new Error(`client-modules: cannot resolve "${specifier}" — not a seed word, not a materialized module, and not a row in the boot graph (the runtime mirror of the bundle purity gate)`);
-				return this.materialize(id).exports;
+				if (row === void 0) {
+					if (this.factories.has(id)) return this.materialize(id).exports;
+					throw new Error(`client-modules: cannot resolve "${specifier}" — not a seed word, not a materialized module, and not a row in the boot graph (the runtime mirror of the bundle purity gate)`);
+				}
+				return this.recordingImportError(id, async () => {
+					await this.arriveGraphRow(row);
+					return this.materialize(id).exports;
+				});
 			}
 			async prefetch(id) {
 				const normalized = stripClientSuffix(id);
 				if (this.loadCache.has(normalized)) return;
 				const row = this.graphRows.get(normalized);
 				if (row === void 0) throw new Error(`client-modules: prefetch("${id}") — not a graph entry`);
-				await this.arriveGraphRow(row);
+				await this.recordingImportError(normalized, () => this.arriveGraphRow(row));
+			}
+			importError(id) {
+				return this.importErrors.get(stripClientSuffix(id));
+			}
+			/**
+			* Run one graph-row operation, recording its failure for the boot audit and
+			* clearing the record on success. Arrival and materialization both run in
+			* here, so a factory that throws is recorded as well as a bundle that never
+			* arrived; the Loader only sees a missing fiber either way.
+			*/
+			async recordingImportError(id, operation) {
+				try {
+					const result = await operation();
+					this.importErrors.delete(id);
+					return result;
+				} catch (error) {
+					this.importErrors.set(id, error instanceof Error ? error : new Error(describeError(error)));
+					throw error;
+				}
 			}
 			/** Refresh descriptors and unowned factory revisions before any entry imports its dependencies. */
 			updateManifest(manifest, managed) {
@@ -739,6 +824,7 @@ window.__ModuleLoader__.load({
 			invalidate(id, rev) {
 				const normalized = stripClientSuffix(id);
 				if (this.bootstrapIds.has(normalized)) return;
+				this.importErrors.delete(normalized);
 				this.generations.set(normalized, (this.generations.get(normalized) ?? 0) + 1);
 				const row = this.graphRows.get(normalized);
 				if (row !== void 0) {

package/lib/index.js

@@ -1,5 +1,5 @@
 import { createRequire } from "node:module";
-import { createHash, randomBytes } from "node:crypto";
+import { createHash } from "node:crypto";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { dirname, isAbsolute, join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -179,31 +179,58 @@ function clientExportOf(pkgName, exportsField) {
 	}
 	throw new Error(`client-modules: ${pkgName} exports["./client"] must be a string or an object with a string default`);
 }
-/** sha1 content hash shortened to 12 hex chars (combo / graph / rebuilt-artifact rev). */
+/** sha1 metadata hash shortened to 12 hex chars. */
 function shortHash(input) {
 	return createHash("sha1").update(input).digest("hex").slice(0, HASH_REVISION_LENGTH);
 }
 /** Hash several response fields without allowing bytes to move across field boundaries. */
 function framedHash(domain, parts) {
 	const hash = createHash("sha1").update(domain).update("\0");
-	for (const part of parts) hash.update(`${String(part.byteLength)}:`).update(part);
+	for (const part of parts) hash.update(`${String(Buffer.byteLength(part))}:`).update(part);
 	return hash.digest("hex").slice(0, HASH_REVISION_LENGTH);
 }
-/** Hash one completed build generation observed through its entry artifact. */
-function artifactRevision(bundle, baseline) {
-	return framedHash("plugin-artifact", [bundle, Buffer.from(String(baseline.mtimeMs))]);
+/** Identify an entry's build from filesystem metadata without hashing its contents. */
+function artifactRevision(baseline) {
+	return framedHash("plugin-artifact", [
+		String(baseline.mtimeMs),
+		String(baseline.ctimeMs),
+		String(baseline.size)
+	]);
 }
-/** Address one ordered plugin-file list through the shared combo route. */
+/** Absolute route prefix serving every plugin resource. */
+const PLUGIN_ROUTE = "/plugins";
+/** Combo query addressing one ordered plugin-file list. */
+function comboSearch(ids, rev, sourceMap = false) {
+	return `??${ids.map((id) => `${id}/client.js${sourceMap ? ".map" : ""}`).join(",")}&rev=${rev}`;
+}
+/** Absolute route URL for one combo resource. */
 function comboUrl(ids, rev, sourceMap = false) {
-	return `/plugins/??${ids.map((id) => `${id}/client.js${sourceMap ? ".map" : ""}`).join(",")}&rev=${rev}`;
+	return `${PLUGIN_ROUTE}/${comboSearch(ids, rev, sourceMap)}`;
 }
-/** Address one package-local chunk through the same revision as its entry. */
+/**
+* Browser reference to one combo resource: app-owned browser routes are
+* document-relative, so the route key's leading slash is stripped here, at the
+* boundary between the two halves. The rule and its reasons are owned by
+* .agents/notes/implemented/architecture/2026-09-14-web-document-relative-app-routes.md.
+*/
+function comboReference(ids, rev, sourceMap = false) {
+	return comboUrl(ids, rev, sourceMap).slice(1);
+}
+/** Absolute route URL for one package-local chunk. */
 function chunkUrl(id, fileName, rev, sourceMap = false) {
-	return `/plugins/${id}/${fileName}${sourceMap ? ".map" : ""}?rev=${rev}`;
+	return `${PLUGIN_ROUTE}/${id}/${fileName}${sourceMap ? ".map" : ""}?rev=${rev}`;
+}
+/**
+* Source-map reference stamped into one chunk script. A script's map reference
+* resolves against that script's own directory rather than the document, so
+* this is the bare map file name, not the document-relative route.
+*/
+function chunkMapReference(fileName, rev) {
+	return `${fileName}.map?rev=${rev}`;
 }
-/** Measure the longer map-form URL used to partition a startup resource list. */
+/** Measure the longest browser-facing combo URL used to partition a startup resource list. */
 function projectedComboUrlBytes(records) {
-	return Buffer.byteLength(comboUrl(records.map((record) => record.entry.id), COMBO_REVISION_PLACEHOLDER, true));
+	return Buffer.byteLength(comboReference(records.map((record) => record.entry.id), COMBO_REVISION_PLACEHOLDER, true));
 }
 /** Partition one phase in graph order without allowing a generated URL above the protocol limit. */
 function partitionComboRecords(records) {
@@ -235,7 +262,7 @@ function prepareSource(resource) {
 		fallbackSource
 	};
 }
-/** Stamp a combo script's absolute indexed-map URL onto its executable bytes. */
+/** Stamp a combo script's source-map reference onto its executable bytes. */
 function comboScript(input, sourceMapUrl) {
 	return Buffer.from(sourceMapUrl === void 0 ? input : `${input}//# sourceMappingURL=${sourceMapUrl}\n`);
 }
@@ -297,7 +324,7 @@ function lazyBody(produce) {
 }
 /** Derive one combo revision from the ordered immutable row revisions. */
 function comboRevision(resources) {
-	return framedHash("combo", resources.flatMap((resource) => [Buffer.from(resource.id), Buffer.from(resource.rev)]));
+	return framedHash("combo", resources.flatMap((resource) => [resource.id, resource.rev]));
 }
 /** Concatenate one or more factory registrations without reading or composing source maps. */
 function buildComboScript(resources, sourceMapUrl) {
@@ -342,14 +369,12 @@ function buildCombo(records, sourceMapOf, revision) {
 	}));
 	const rev = revision ?? comboRevision(resources);
 	const entries = resources.map((resource) => resource.id);
-	const url = comboUrl(entries, rev);
-	const sourceMapUrl = comboUrl(entries, rev, true);
 	return {
-		url,
+		url: comboUrl(entries, rev),
 		rev,
 		entries,
-		sourceMapUrl,
-		scriptBody: lazyBody(() => buildComboScript(resources, sourceMapUrl)),
+		sourceMapUrl: comboUrl(entries, rev, true),
+		scriptBody: lazyBody(() => buildComboScript(resources, comboSearch(entries, rev, true))),
 		sourceMapBody: lazyBody(() => buildComboSourceMap(resources, sourceMapOf))
 	};
 }
@@ -360,17 +385,17 @@ function buildBatch(phase, records, sourceMapOf) {
 		...artifact,
 		descriptor: {
 			phase,
-			url: artifact.url,
+			url: artifact.url.slice(1),
 			rev: artifact.rev,
 			entries: artifact.entries
 		}
 	};
 }
-/** Graph row for one bundle rev (url carries the rev as its cache-busting query). */
+/** Graph row for one bundle rev (the reference carries the rev as its cache-busting query). */
 function graphRow(id, rev, fields) {
 	return {
 		id,
-		url: comboUrl([id], rev),
+		url: comboReference([id], rev),
 		rev,
 		...fields.inject !== void 0 ? { inject: fields.inject } : {},
 		...fields.immediately ? { immediately: true } : {},
@@ -486,8 +511,6 @@ var ClientModuleRegistry = class extends Service {
 	rebuildListeners = /* @__PURE__ */ new Set();
 	graphListeners = /* @__PURE__ */ new Set();
 	dirty = /* @__PURE__ */ new Set();
-	initialRevisionNonce = randomBytes(8).toString("hex");
-	nextInitialRevision = 0;
 	responses = /* @__PURE__ */ new Map();
 	batchResponses = /* @__PURE__ */ new Map();
 	/** One prior graph generation covers a request racing the HMR recomposition that replaced its URL. */
@@ -522,7 +545,7 @@ var ClientModuleRegistry = class extends Service {
 		const registerWebCarrier = (webCtx) => {
 			webCtx.effect(() => webCtx.webServer.register({
 				kind: "prefix",
-				path: "/plugins",
+				path: PLUGIN_ROUTE,
 				handler: this.serveBundle
 			}), "client-modules: bundle route");
 		};
@@ -577,17 +600,18 @@ var ClientModuleRegistry = class extends Service {
 	/**
 	* Publish one completed bundle generation (the HMR watch's registration
 	* hook — the only entry point through which build changes reach the graph).
+	* Unchanged mtime, ctime and size preserve the graph without reading the bundle.
 	* @param id - entry id (package name).
-	* @returns the new rev, or undefined for an unknown id.
+	* @returns the current artifact rev, or undefined for an unknown id.
 	*/
 	rebuilt(id) {
 		const record = this.table.get(id);
 		if (record === void 0) return void 0;
 		const baseline = this.captureArtifactBaseline(record.meta.clientPath);
+		const rev = artifactRevision(baseline);
+		if (rev === record.entry.rev) return rev;
 		const bundle = readFileSync(record.meta.clientPath);
-		const rev = artifactRevision(bundle, baseline);
 		record.baseline = baseline;
-		if (rev === record.entry.rev) return rev;
 		record.entry = graphRow(id, rev, record.meta);
 		record.bundle = bundle;
 		this.composed = this.compose();
@@ -600,7 +624,7 @@ var ClientModuleRegistry = class extends Service {
 		return rev;
 	}
 	/**
-	* Subscribe to bundle rebuilds; fires only when the re-hash changed the rev.
+	* Subscribe to bundle rebuilds; fires only when artifact metadata changes the rev.
 	* @param listener - receives the entry id and its new bundle rev.
 	* @returns the unsubscriber.
 	*/
@@ -632,7 +656,7 @@ var ClientModuleRegistry = class extends Service {
 		for (const records of partitionComboRecords(application)) artifacts.push(buildBatch("application", records, this.readSourceMap));
 		const batchResponses = /* @__PURE__ */ new Map();
 		for (const artifact of artifacts) {
-			batchResponses.set(artifact.descriptor.url, this.responses.get(artifact.descriptor.url) ?? {
+			batchResponses.set(artifact.url, this.responses.get(artifact.url) ?? {
 				body: artifact.scriptBody,
 				contentType: "text/javascript; charset=utf-8"
 			});
@@ -773,13 +797,10 @@ var ClientModuleRegistry = class extends Service {
 		return {
 			path: clientPath,
 			mtimeMs: bundle.mtimeMs,
+			ctimeMs: bundle.ctimeMs,
 			size: bundle.size
 		};
 	}
-	/** Allocate an opaque initial row revision without inspecting artifact bytes. */
-	allocateInitialRevision() {
-		return `${this.initialRevisionNonce}-${String(this.nextInitialRevision++)}`;
-	}
 	/**
 	* Read the activation-time bundle snapshot.
 	* @param pkgName - package that declares the client bundle.
@@ -858,7 +879,7 @@ var ClientModuleRegistry = class extends Service {
 		if (source === void 0) return this.table.delete(packageName);
 		if (this.table.get(packageName)?.sourceKey === source.sourceKey) return false;
 		const snapshot = this.initialBundleSnapshot(packageName, source.meta.clientPath);
-		const rev = this.allocateInitialRevision();
+		const rev = artifactRevision(snapshot.baseline);
 		this.table.set(packageName, {
 			entry: graphRow(packageName, rev, source.meta),
 			loaderName: source.loaderName,
@@ -916,7 +937,7 @@ var ClientModuleRegistry = class extends Service {
 		const { record, fileName, sourceMap, resourceUrl } = request;
 		const clientPath = join(dirname(record.meta.clientPath), fileName);
 		if (!existsSync(clientPath)) return void 0;
-		const sourceMapUrl = chunkUrl(record.entry.id, fileName, record.entry.rev, true);
+		const sourceMapUrl = chunkMapReference(fileName, record.entry.rev);
 		const resource = () => ({
 			id: record.entry.id,
 			rev: record.entry.rev,

package/lib/invariant.js

@@ -11,8 +11,8 @@ const inject = ["invariants"];
 /**
 * Owned relation: the node half's boot entry graph must stay self-consistent
 * — every row must resolve a clientPath under the same id (the
-* /plugins/<id>/client.js URL it advertises would otherwise 404 on a browser
-* that just received the graph). Checked on every scan trigger (cordis
+* `plugins/<id>/client.js` reference it advertises would otherwise 404 in the
+* browser that just received the graph). Checked on every scan trigger (cordis
 * 'internal/plugin'): graph() and clientPath() read the same table object,
 * so the relation holds at any instant — no need to wait out the node half's
 * own microtask-debounced flush.

package/lib/types/client/manifest.d.ts

@@ -48,7 +48,10 @@ declare module '@deepseek-ai/cordis' {
 export interface WebBootEntry {
     /** Entry name == package name. */
     id: string;
-    /** Revisioned single-resource combo endpoint used by HMR. */
+    /**
+     * Revisioned single-resource combo reference used by HMR. It is relative to
+     * the document, so the browser resolves it under whatever mount served the page.
+     */
     url: string;
     /** Opaque plugin-artifact revision used for HMR cache busting. */
     rev: string;
@@ -65,7 +68,7 @@ export type WebBootBatchPhase = 'bootstrap' | 'application';
 export interface WebBootBatch {
     /** Parser-blocking bootstrap or preloaded application scheduling. */
     phase: WebBootBatchPhase;
-    /** Revisioned combo script endpoint. */
+    /** Content-addressed combo script reference, document-relative like {@link WebBootEntry.url}. */
     url: string;
     /** Revision derived from the ordered entry revisions. */
     rev: string;
@@ -89,9 +92,9 @@ export interface WebBootGraph {
 export interface BootModuleRow {
     /** Entry name == package name (module-table key). */
     id: string;
-    /** Revisioned single-resource combo endpoint used after HMR invalidation. */
+    /** Revisioned single-resource combo reference: the fallback when the row's batch fails and the reload target after HMR invalidation. */
     url: string;
-    /** Revisioned combo endpoint used before the first HMR invalidation. */
+    /** Content-addressed combo reference used before the first HMR invalidation. */
     initialUrl: string;
     /** Opaque plugin-artifact revision used after HMR invalidation. */
     rev: string;
@@ -263,6 +266,15 @@ export interface ClientModuleLoader {
      * @param id - graph entry name.
      */
     prefetch(id: string): Promise<void>;
+    /**
+     * The last failure of {@link import} or {@link prefetch} for one graph row:
+     * transport, registration, dependency cascade, or factory execution. Cleared
+     * by a later success and by {@link invalidate}. The boot audit reads it to
+     * report why a Loader entry has no fiber.
+     * @param id - graph entry name.
+     * @returns the recorded failure, or `undefined` when the row never failed or succeeded since.
+     */
+    importError(id: string): Error | undefined;
     /**
      * Full reset of one non-bootstrap package: drop its entry and chunk factories
      * and materialized records so the next prefetch/import loads its one-resource

package/lib/types/client/system.d.ts

@@ -25,6 +25,12 @@ export declare class ClientModuleSystem implements ClientModuleLoader {
     private readonly materializing;
     private readonly graphRows;
     private readonly loadBundle;
+    /** Last import or prefetch failure per graph row, cleared by a later success or invalidation. */
+    private readonly importErrors;
+    /** Batch URLs whose transport or execution already failed; rows still missing from them go straight to their one-resource URL. */
+    private readonly failedBundleUrls;
+    /** Every URL whose script has executed once; a batch among them is never requested again. */
+    private readonly executedBundleUrls;
     /**
      * Build the module system over the parsed boot rows.
      * @param options - Parsed graph, platform seed, bootstrap module, registration facade, and transport.
@@ -32,10 +38,28 @@ export declare class ClientModuleSystem implements ClientModuleLoader {
     constructor(options: ClientModuleSystemOptions);
     /** Register one bundle factory, rejecting a script that executes twice without invalidation. */
     private register;
-    /** Load one graph row so its factory is registered (idempotent per in-flight arrival). */
+    /** Run one bundle transport per URL; every row waiting on the same URL shares the in-flight request. */
+    private loadShared;
+    /**
+     * Load one graph row so its factory is registered (idempotent per in-flight
+     * arrival). A batch script is one classic script that registers every
+     * package in sequence, and {@link register} rejects a second registration,
+     * so the two failure kinds differ: a transport failure (`error` event, nothing
+     * executed) is retried once on the same URL; a script that loaded without
+     * registering this row (a parse error registered nothing, or a runtime throw
+     * stopped it after registering others) is never re-executed, because a replay
+     * would stop again at the first duplicate registration; that holds even when
+     * the row that first imports from the batch is one it did register, because
+     * every executed batch URL is remembered. Either way the row then falls back
+     * to its own one-resource URL, which the Host serves for every package, so one
+     * failed batch costs at most three requests per missing row and never fails
+     * the rows that were registered.
+     */
     private arrive;
     /** Register each injected package and unresolved dynamic request before its consumer. */
     private arriveGraphRow;
+    /** Arrive one dependency, naming the consumer it failed for so a cascade reads as a chain, not as 44 unrelated failures. */
+    private arriveDependency;
     /** Materialize a registered factory (synchronous; memoized in loadCache). */
     private materialize;
     /** Build the synchronous module-table require and its asynchronous chunk operation. */
@@ -44,6 +68,14 @@ export declare class ClientModuleSystem implements ClientModuleLoader {
     private importChunk;
     import(specifier: string): Promise<unknown>;
     prefetch(id: string): Promise<void>;
+    importError(id: string): Error | undefined;
+    /**
+     * Run one graph-row operation, recording its failure for the boot audit and
+     * clearing the record on success. Arrival and materialization both run in
+     * here, so a factory that throws is recorded as well as a bundle that never
+     * arrived; the Loader only sees a missing fiber either way.
+     */
+    private recordingImportError;
     /** Refresh descriptors and unowned factory revisions before any entry imports its dependencies. */
     private updateManifest;
     /** Retain live Loader modules and their transitive requests before evicting unreferenced graph records. */

package/lib/types/index.d.ts

@@ -40,6 +40,8 @@ export interface ClientArtifactBaseline {
     readonly path: string;
     /** Bundle modification time in milliseconds. */
     readonly mtimeMs: number;
+    /** Bundle status-change time in milliseconds, including writes that preserve mtime. */
+    readonly ctimeMs: number;
     /** Bundle size in bytes. */
     readonly size: number;
 }
@@ -81,8 +83,6 @@ export declare class ClientModuleRegistry extends Service {
     private readonly rebuildListeners;
     private readonly graphListeners;
     private readonly dirty;
-    private readonly initialRevisionNonce;
-    private nextInitialRevision;
     private responses;
     private batchResponses;
     /** One prior graph generation covers a request racing the HMR recomposition that replaced its URL. */
@@ -127,12 +127,13 @@ export declare class ClientModuleRegistry extends Service {
     /**
      * Publish one completed bundle generation (the HMR watch's registration
      * hook — the only entry point through which build changes reach the graph).
+     * Unchanged mtime, ctime and size preserve the graph without reading the bundle.
      * @param id - entry id (package name).
-     * @returns the new rev, or undefined for an unknown id.
+     * @returns the current artifact rev, or undefined for an unknown id.
      */
     rebuilt(id: string): string | undefined;
     /**
-     * Subscribe to bundle rebuilds; fires only when the re-hash changed the rev.
+     * Subscribe to bundle rebuilds; fires only when artifact metadata changes the rev.
      * @param listener - receives the entry id and its new bundle rev.
      * @returns the unsubscriber.
      */
@@ -163,8 +164,6 @@ export declare class ClientModuleRegistry extends Service {
     private sourceKey;
     /** Capture the bundle stats before reading its bytes. */
     private captureArtifactBaseline;
-    /** Allocate an opaque initial row revision without inspecting artifact bytes. */
-    private allocateInitialRevision;
     /**
      * Read the activation-time bundle snapshot.
      * @param pkgName - package that declares the client bundle.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-modules",
   "description": "Client module system, dual-face: node half composes the __DSH_BOOT__ entry graph (incremental dsh.client scan, bundle route, index tap, webPlugins service); browser half is the lazy-CJS module table the vendored cordis Loader consumes as its internal seam",
-  "version": "0.1.6-alpha.2",
+  "version": "0.1.7-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -38,12 +38,12 @@
   },
   "license": "MIT",
   "devDependencies": {
-    "@deepseek-ai/dsh-host-webserver": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-invariants": "^0.1.6-alpha.2",
-    "@deepseek-ai/cordis-plugin-loader": "^1.0.3",
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-package-manifest": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-client-store": "^0.1.6-alpha.2"
+    "@deepseek-ai/cordis-plugin-loader": "~1.0.5",
+    "@deepseek-ai/dsh-host-webserver": "0.1.7-alpha.2",
+    "@deepseek-ai/cordis": "~4.0.4",
+    "@deepseek-ai/dsh-package-manifest": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-client-store": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-invariants": "0.1.7-alpha.2"
   },
   "files": [
     "lib/index.js",
@@ -52,7 +52,7 @@
     "lib/types/**/*.d.ts"
   ],
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2"
+    "@deepseek-ai/cordis": "~4.0.4"
   },
   "scripts": {
     "bundle": "tsdown",