@deepseek-ai/dsh-lazy-require 0.1.6-alpha.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# 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/util/lazy-require/README.md
+README.md: d75a7626da61522939f17f6caec1f5d14e6da6c6
+README.zh.md: 7d8e66f15957a990ae37ed04b627dd4a4f147fa0

package/README.md

@@ -0,0 +1,88 @@
+---
+description: "Caller-relative lazy loading for CommonJS-compatible Host dependencies whose initialization is not needed during application startup."
+kind: "package-library"
+---
+
+# @deepseek-ai/dsh-lazy-require
+
+English | [中文](README.zh.md)
+
+## Summary
+
+`dsh-lazy-require` keeps a CommonJS-compatible Host dependency unloaded until its first real operation. Resolution remains relative to the consuming package, and one successful module value is reused for the rest of the process realm.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Pass the dependency's literal specifier and the caller's `import.meta.url`:
+
+```ts
+import { createLazyRequire } from '@deepseek-ai/dsh-lazy-require'
+
+interface NativeModule { open(): void }
+const requireNative = createLazyRequire<NativeModule>('native-package', import.meta.url)
+```
+
+Calling `requireNative()` loads the dependency once. A failed load is not cached.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+The utility creates Node's `require` from the supplied caller URL and caches only a successful return value. The explicit caller URL preserves package-local dependency resolution after publication.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Caller-relative loader and successful-result cache |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+- [Utility package map](../README.md) — adjacent shared primitives.
+- [NPM release sequences](../../../.agents/notes/implemented/process/2026-08-10-npm-release-sequences.md) — published dependency classification and first-use loading policy.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+None, as this Host utility registers no model-facing behavior.
+
+#### KV Cache effect
+
+None.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **CommonJS-compatible dependencies only** — ESM-only packages require an asynchronous factory owned by their caller.
+- **WebWorker packaging needs an explicit request** — the static packer does not discover dependencies named only in `createLazyRequire()` calls. A package used in a Preview image must keep the dependency reachable through a supported literal request until the packer recognizes this helper.
+
+No runtime invariant companion is published because the loader holds no independently observable mutable relationship.
+
+<a id="dev-note"></a>
+### Dev Note
+
+None.

package/README.zh.md

@@ -0,0 +1,88 @@
+---
+description: "按调用方解析并惰性加载 CommonJS 兼容的 Host 依赖，使应用启动时不初始化尚未使用的依赖。"
+kind: "package-library"
+---
+
+# @deepseek-ai/dsh-lazy-require
+
+[English](README.md) | 中文
+
+## 概述
+
+`dsh-lazy-require` 会让 CommonJS 兼容的 Host 依赖保持未加载状态，直到首次实际操作。解析仍以消费方 package 为基准，同一进程 realm 会复用一次成功加载的模块值。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+传入依赖的字面量 specifier 与调用方的 `import.meta.url`：
+
+```ts
+import { createLazyRequire } from '@deepseek-ai/dsh-lazy-require'
+
+interface NativeModule { open(): void }
+const requireNative = createLazyRequire<NativeModule>('native-package', import.meta.url)
+```
+
+调用 `requireNative()` 时才加载依赖，并只加载一次。失败的加载不会被缓存。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+本工具使用传入的调用方 URL 创建 Node `require`，并且只缓存成功返回的值。显式调用方 URL 会在发布后保留 package 局部的依赖解析。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | 按调用方解析的 loader 与成功结果缓存 |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+- [工具包地图](../README.zh.md)——相邻的共享原语。
+- [NPM 发布序列](../../../.agents/notes/implemented/process/2026-08-10-npm-release-sequences.zh.md)——发布依赖分类与首次使用加载策略。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+无，因为本 Host 工具不注册任何模型可见行为。
+
+#### KV Cache 影响
+
+无。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **仅限兼容 CommonJS 的依赖**——仅 ESM package 需要由调用方拥有异步 factory。
+- **WebWorker 打包需要显式请求**——静态 packer 无法发现仅在 `createLazyRequire()` 调用中命名的依赖。Preview image 使用的 package 必须通过受支持的字面量请求保持该依赖可达，直到 packer 能够识别此 helper。
+
+本包不发布运行时 invariant companion，因为 loader 不持有可独立观测的可变关系。
+
+<a id="dev-note"></a>
+### 开发备注
+
+无。

package/lib/index.js

@@ -0,0 +1,24 @@
+import { createRequire } from "node:module";
+//#region lib/types/index.js
+/** Caller-relative lazy loading for CommonJS-compatible Host dependencies. */
+/**
+* Create a successful-result cache around Node's caller-relative `require`.
+* A failed load is not cached, so a corrected installation can be retried.
+* @param specifier - Literal dependency specifier declared by the caller package.
+* @param parentURL - Caller's `import.meta.url`, which owns package resolution.
+* @returns a zero-argument loader that resolves the dependency on first use.
+*/
+function createLazyRequire(specifier, parentURL) {
+	const require = createRequire(parentURL);
+	let loaded = false;
+	let value;
+	return () => {
+		if (!loaded) {
+			value = require(specifier);
+			loaded = true;
+		}
+		return value;
+	};
+}
+//#endregion
+export { createLazyRequire };

package/lib/types/index.d.ts

@@ -0,0 +1,10 @@
+/** Caller-relative lazy loading for CommonJS-compatible Host dependencies. */
+/**
+ * Create a successful-result cache around Node's caller-relative `require`.
+ * A failed load is not cached, so a corrected installation can be retried.
+ * @param specifier - Literal dependency specifier declared by the caller package.
+ * @param parentURL - Caller's `import.meta.url`, which owns package resolution.
+ * @returns a zero-argument loader that resolves the dependency on first use.
+ */
+export declare function createLazyRequire<T>(specifier: string, parentURL: string | URL): () => T;
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@deepseek-ai/dsh-lazy-require",
+  "description": "Caller-relative, success-cached lazy loading for CommonJS-compatible Host dependencies",
+  "version": "0.1.6-alpha.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/util/lazy-require"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2"
+  }
+}