@planet-matrix/mobius-model 0.5.0 → 0.6.0

package/src/orchestration/index.ts

@@ -0,0 +1 @@
+export * from "./coordination/index.ts"

package/src/random/README.md

@@ -1,109 +1,78 @@
 # Random
 
-Runtime utilities for generating random-oriented values with cross-runtime compatibility. This module currently focuses on UUID generation.
+## Description
 
-## For Users
+Random 模块用于提供随机值（random value）相关的基础能力，当前主要承载随机字符串生成语义。
 
-This module provides lightweight helpers for random value generation scenarios.
+它关注的是“如何生成一类通用、可复用、语义清楚的随机文本”，而不是各种标识格式校验、业务编码规则或安全承诺各异的随机机制集合。
 
-### 1. Domain Areas
+## For Understanding
 
-1. UUID: Generate RFC 4122 version-4 UUID strings with runtime-aware fallback behavior.
+理解 Random 模块时，应先把它放在应用边界附近。随机值通常意味着不可复现、带有环境依赖，或者会影响测试与调试行为，因此更合理的做法是把它看作边界输入的生成层，而不是让随机行为无约束地扩散到核心业务逻辑内部。
 
-Current public exports:
+当前这个模块的核心边界比较克制：它主要处理“随机字符串如何生成”这一类问题。也就是说，它更关心字符集、长度、结果格式和重复概率，而不再负责 UUID 这类已经具有明确标识语义的格式模型。
 
-- `isUuid(input: string): boolean`
-- `assertUuid(input: string): void`
-- `getUuidVersion(input: string): number`
-- `generateUuid(): string`
+不适合放入本模块的能力，通常包括两类：一类是与密码学安全直接绑定、需要单独安全承诺的能力；另一类是已经形成稳定标识语义的格式模型，例如 UUID。前者应以更明确的安全语义单独建模，后者则应放入更贴近标识问题域的模块。
 
-## For Contributors
+## For Using
 
-This guide documents conventions and best practices for implementing random utilities in this module.
+当你需要在应用或库的边界层生成临时标识、关联值、会话键或其它非业务主键用途的随机文本时，可以使用这个模块。它更适合被理解为“随机字符串生成接口”，而不是一个什么都往里塞的杂项工具箱。
 
-### 1. Documentation and Comments
+从使用角度看，当前公共能力主要围绕随机字符串生成展开。更合适的接入方式，是在边界层尽早生成这些随机文本，再把得到的结果作为普通输入传给后续模块，从而避免内部逻辑直接依赖随机过程本身。
 
-#### 1.1 JSDoc Comment Format
+需要特别注意的是，本模块中的“随机”默认应被理解为通用应用层随机，而不是自动带有密码学强度承诺的安全随机。只要调用场景对安全性、可预测性、重复碰撞风险或跨环境一致性有更严格要求，就应先在设计上明确这些前提，而不要仅凭模块名称推断安全等级。
 
-Every exported function should include JSDoc in this form:
+## For Contributing
 
-```typescript
-/**
- * Brief one-line description of what the function does.
- *
- * @example
- * ```
- * const example1 = generateUuid()
- * // Expect: true
- * const example2 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(example1)
- * ```
- */
-export const generateUuid = (): string => {
-	...
-}
-```
+贡献 Random 模块时，应先确认新增能力表达的是稳定、清楚且可长期承诺的随机语义，而不是某种实现手段的直接暴露。对外公开的重点应该是“调用方需要什么随机字符串能力”，而不是“内部恰好如何生成这些值”。只要一个能力过度依赖当前实现细节，或者只在某个很窄的业务上下文中成立，就不适合进入这个模块。
 
-**Documentation Rules:**
-- First line: Clear, concise description starting with a verb (Generate, Check, Convert, etc.)
-- Add a blank line after the description
-- Use `@example` tag followed by triple backticks
-- Include multiple cases showing different scenarios
-- Use comment format: `// Expect: <result>`
-- Assign example results to variables like `example1`, `example2` to keep examples readable
-- Place `@see`(if has) after the `@example` block, separated by a blank line
-- Prefer deterministic examples; avoid asserting exact random outputs
-- If a function returns a structured string, show expected format characteristics
+在扩展时，应特别警惕两个方向的边界漂移。其一，不要把安全领域的问题用模糊措辞塞进来，例如把需要明确密码学承诺的能力混入通用随机工具中。其二，不要把已经形成稳定标识语义的格式模型重新拉回 Random。Random 模块应尽量保持为面向广泛调用方的随机文本生成边界，而不是业务专用规则仓库。
 
-### 2. Runtime Implementation Patterns
+### JSDoc 注释格式要求
 
-#### 2.1 Compatibility First
+- 每个公开导出的目标（类型、函数、变量、类等）都应包含 JSDoc 注释，让人在不跳转实现的情况下就能理解用途。
+- JSDoc 注释第一行应为清晰且简洁的描述，该描述优先使用中文（英文也可以）。
+- 如果描述后还有其他内容，应在描述后加一个空行。
+- 如果有示例，应使用 `@example` 标签，后接三重反引号代码块（不带语言标识）。
+- 如果有示例，应包含多个场景，展示不同用法，尤其要覆盖常见组合方式或边界输入。
+- 如果有示例，应使用注释格式说明每个场景：`// Expect: <result>`。
+- 如果有示例，应将结果赋值给 `example1`、`example2` 之类的变量，以保持示例易读。
+- 如果有示例，`// Expect: <result>` 应该位于 `example1`、`example2` 之前，以保持示例的逻辑清晰。
+- 如果有示例，应优先使用确定性示例；避免断言精确的随机输出。
+- 如果函数返回结构化字符串，应展示其预期格式特征。
+- 如果有参考资料，应将 `@see` 放在 `@example` 代码块之后，并用一个空行分隔。
 
-- Prefer standard runtime APIs when available (for example, `crypto.randomUUID`).
-- Keep fallback logic for environments where modern APIs are unavailable.
+### 实现规范要求
 
-#### 2.2 Deterministic Interface
+- 不同程序元素之间使用一个空行分隔，保持结构清楚。这里的程序元素，通常指函数、类型、常量，以及直接服务于它们的辅助元素。
+- 某程序元素独占的辅助元素与该程序元素本身视为一个整体，不要在它们之间添加空行。
+- 程序元素的辅助元素应该放置在该程序元素的上方，以保持阅读时的逻辑顺序。
+- 若辅助元素被多个程序元素共享，则应将其视为独立的程序元素，放在这些程序元素中第一个相关目标的上方，并与后续程序元素之间保留一个空行。
+- 辅助元素也应该像其它程序元素一样，保持清晰的命名和适当的注释，以便在需要阅读实现细节时能够快速理解它们的作用和使用方式。
+- 辅助元素的命名必须以前缀 `internal` 开头（或 `Internal`，大小写不敏感）。
+- 辅助元素永远不要公开导出。
+- 被模块内多个不同文件中的程序元素共享的辅助元素，应该放在一个单独的文件中，例如 `./src/random/internal.ts`。
+- 模块内可以包含子模块。只有当某个子目录表达一个稳定、可单独理解、且可能被父模块重导出的子问题域时，才应将其视为子模块。
+- 子模块包含多个文件时，应该为其单独创建子文件夹，并为其创建单独的 Barrel 文件；父模块的 Barrel 文件再重导出子模块的 Barrel 文件。
+- 子模块不需要有自己的 `README.md`。
+- 子模块可以有自己的 `internal.ts` 文件，多个子模块共享的辅助元素应该放在父模块的 `internal.ts` 文件中，单个子模块共享的辅助元素应该放在该子模块的 `internal.ts` 文件中。
+- 对模块依赖关系的要求（通常是不循环依赖或不反向依赖）与对 DRY 的要求可能产生冲突。此时，若复用的代码数量不大，可以适当牺牲 DRY，复制粘贴并保留必要的注释说明；若复用的代码数量较大，则可以将其抽象到新的文件或子模块中，如 `common.ts`，并在需要的地方导入使用。
+- 与随机相关的实现应优先围绕结果格式、边界约束与调用方可理解的失败语义组织，不要把底层算法细节直接提升为公共承诺。
 
-- Public API shape should remain deterministic even if output values are random.
-- Return values should always conform to the documented output format.
+### 导出策略要求
 
-#### 2.3 Helper Placement
+- 保持内部辅助项和内部符号为私有，不要让外部接入依赖临时性的内部结构。
+- 每个模块都应有一个用于重导出所有公共 API 的 Barrel 文件。
+- Barrel 文件应命名为 `index.ts`，放在模块目录根部，并且所有公共 API 都应从该文件导出。
+- 新增公共能力时，应优先检查它是否表达稳定、清楚且值得长期维护的随机语义，而不是某段实现细节的便捷暴露；仅在确认需要长期对外承诺时再加入 Barrel 导出。
 
-- Place local helper constants/functions immediately before the utility they support.
-- Prefix non-exported helpers with `internal`.
-- Never export internal helpers.
+### 测试要求
 
-#### 2.4 Spacing
-
-- Separate different utility functions with a single blank line.
-
-### 3. Naming Conventions
-
-#### 3.1 Function Name Format
-
-Use clear operation-oriented names in the `random` domain:
-
-- `isUuid` for UUID format validation checks
-- `assertUuid` for UUID validation that throws on malformed input
-- `getUuidVersion` for extracting UUID version numbers
-- `generateUuid` for UUID creation helpers
-
-Prefer names that clearly indicate output format and intent.
-
-### 4. Export Strategy
-
-- Export all public utilities from domain files.
-- Re-export them through `index.ts`.
-- Do not export internal helpers.
-
-### 5. Common Pitfalls to Avoid
-
-1. Do not assume browser-only APIs are always available.
-2. Do not couple random utilities to a specific runtime unless documented.
-3. Do not assert exact random results in tests.
-4. Do not mutate shared/global state permanently.
-
-### 6. Testing Requirements
-
-- Write one test per function.
-- If multiple cases are needed, include them within the same test.
-- For random outputs, validate shape/constraints instead of exact value.
+- 若程序元素是函数，则只为该函数编写一个测试，如果该函数需要测试多个用例，应放在同一个测试中。
+- 若程序元素是类，则至少要为该类的每一个方法编写一个测试，如果该方法需要测试多个用例，应放在同一个测试中。
+- 若程序元素是类，除了为该类的每一个方法编写至少一个测试之外，还可以为该类编写任意多个测试，以覆盖该类的不同使用场景或边界情况。
+- 若编写测试时需要用到辅助元素（Mock 或 Spy 等），可以在测试文件中直接定义这些辅助元素。若辅助元素较为简单，则可以直接放在每一个测试内部，优先保证每个测试的独立性，而不是追求极致 DRY；若辅助元素较为复杂或需要在多个测试中复用，则可以放在测试文件顶部，供该测试文件中的所有测试使用。
+- 测试顺序应与源文件中被测试目标的原始顺序保持一致。
+- 若该模块不需要测试，必须在说明文件中明确说明该模块不需要测试，并说明理由。一般来说，只有在该模块没有可执行的公共函数、只承载类型层表达，或其语义已被上层模块的测试完整覆盖且重复测试几乎不再带来额外价值时，才适合这样处理。
+- 模块的单元测试文件目录是 `./tests/unit/random`，若模块包含子模块，则子模块的单元测试文件目录为 `./tests/unit/random/<sub-module-name>`。
+- 对随机字符串相关能力，应优先测试长度约束、字符集边界与结果特征，而不要把测试建立在脆弱的精确随机输出之上。

package/src/random/index.ts

@@ -1 +1 @@
-export * from "./uuid.ts"
+export * from "./string.ts"

package/src/random/string.ts

@@ -0,0 +1,35 @@
+const internalRandomStringPacket: Record<number, string[]> = {}
+/**
+ * 生成指定长度的随机字符串，并可选限制字符集。
+ *
+ * 该函数适合生成界面状态键、临时标识或其它非业务主键用途的随机文本。
+ *
+ * 当未传入字符集时，将使用数字、小写字母与大写字母组成的默认字符集。
+ * 同一运行时内会按长度记录已生成结果，尽量避免返回同长度的重复值。
+ *
+ * @example
+ * ```
+ * // Expect: 8
+ * const example1 = randomString(8).length
+ * // Expect: true
+ * const example2 = randomString(4, "ab").split("").every(char => char === "a" || char === "b")
+ * ```
+ */
+export const randomString = (length: number, chars?: string | undefined): string => {
+  let result = ""
+  const preparedChars = chars ?? "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"
+
+  Array.from({ length }).forEach(() => {
+    result = result + preparedChars[Math.floor(Math.random() * preparedChars.length)]!
+  })
+
+  internalRandomStringPacket[length] = internalRandomStringPacket[length] ?? []
+  const packet = internalRandomStringPacket[length]
+  if (packet.includes(result)) {
+    return randomString(length, preparedChars)
+  }
+  else {
+    packet.push(result)
+    return result
+  }
+}

package/src/reactor/README.md

@@ -1,5 +1,9 @@
 # Reactor
 
+## Description
+
+> 本模块纯人工实现，AI 不要插手！
+
 Reactor 的实现与以下项目有关：
 
 - [alien-signals](https://github.com/stackblitz/alien-signals): Reactor 源于该项目，是在对该项目进行重构的基础上添加了其它个性化实现得到的，两者核心区别包括：1、alien-signals 的 API 更加“函数式”，而 Reactor 的 API 更加“对象式”；2、alien-signals 的源码更注重性能，因而比较晦涩，而 Reactor 的实现更注重可维护性与可扩展性因而比较易懂；3、alien-signals 的功能更单一更克制，几乎只提供了核心的响应式算法，而 Reactor 则提供了更多的相关功能与工具函数。

package/src/reactor/reactor-core/primitive.ts

@@ -107,7 +107,7 @@ export abstract class BaseReactor<V = unknown> implements Node {
 }
 
 const VOID = Symbol("void") as unknown;
-const isVoid = <T>(value: T): boolean => {
+const isVoid = (value: unknown): boolean => {
   return value === VOID;
 }
 
@@ -241,7 +241,7 @@ export interface SignalOptions<V> extends BaseReactorOptions {
  * Signal 的值只有在被获取的时候才会更新。
  */
 export class Signal<V = unknown> extends BaseReactor<V> {
-  private isEqual: (oldValue: V, newValue: V) => boolean;
+  private readonly isEqual: (oldValue: V, newValue: V) => boolean;
 
   private valueGetter: SignalValueGetter<V>;
 
@@ -377,9 +377,9 @@ export interface DerivedOptions<V> extends BaseReactorOptions {
  * Derived 的下游节点全部解除连接时会自动与所有上游节点解除连接，并回到初始状态。
  */
 export class Derived<V = unknown> extends BaseReactor<V> {
-  private isEqual: (oldValue: V, newValue: V) => boolean;
+  private readonly isEqual: (oldValue: V, newValue: V) => boolean;
 
-  private valueGetter: DerivedValueGetter<V>;
+  private readonly valueGetter: DerivedValueGetter<V>;
   private manualValueGetter: DerivedValueGetter<V> | undefined;
 
   constructor(valueGetter: DerivedValueGetter<V>, options: DerivedOptions<V>) {
@@ -558,9 +558,9 @@ export interface ComputedOptions<V> extends BaseReactorOptions {
  * Computed 的下游节点全部解除连接时会自动与所有上游节点解除连接，并回到初始状态。
  */
 export class Computed<V = unknown> extends BaseReactor<V> {
-  private isEqual: (oldValue: V, newValue: V) => boolean;
+  private readonly isEqual: (oldValue: V, newValue: V) => boolean;
 
-  private valueGetter: ComputedValueGetter<V>;
+  private readonly valueGetter: ComputedValueGetter<V>;
 
   constructor(valueGetter: ComputedValueGetter<V>, options: ComputedOptions<V>) {
     super(options);
@@ -684,7 +684,7 @@ export interface EffectOptions extends BaseReactorOptions {
  * 作为上游节点的 Effect 在没有下游节点时会自动与所有上游节点解除连接，并将标记清空。
  */
 export class Effect<V = void> extends BaseReactor<V> {
-  private valueGetter: EffectValueGetter<V>;
+  private readonly valueGetter: EffectValueGetter<V>;
   private cleanupFn: CleanupFn | undefined;
 
   constructor(valueGetter: EffectValueGetter<V>, options: EffectOptions) {
@@ -799,7 +799,7 @@ export type EffectScopeValueGetter<V> = (context: EffectScopeValueGetterContext<
 export interface EffectScopeOptions extends BaseReactorOptions {
 }
 export class EffectScope<V = void> extends BaseReactor<V> {
-  private valueGetter: EffectScopeValueGetter<V>;
+  private readonly valueGetter: EffectScopeValueGetter<V>;
   private cleanupFn: CleanupFn | void;
 
   constructor(valueGetter: EffectScopeValueGetter<V>, options: EffectScopeOptions) {
@@ -894,7 +894,7 @@ export type TriggerValueGetter<V> = (context: TriggerValueGetterContext<V>) => V
 export interface TriggerOptions extends BaseReactorOptions {
 }
 export class Trigger<V = void> extends BaseReactor<V> {
-  private valueGetter: TriggerValueGetter<V>;
+  private readonly valueGetter: TriggerValueGetter<V>;
   private cleanupFn: CleanupFn | void;
 
   constructor(valueGetter: TriggerValueGetter<V>, options: TriggerOptions) {

package/src/reactor/reactor-core/reactive-system.ts

@@ -178,7 +178,7 @@ export interface ReactiveSystem {
   /**
    * 设置当前正在进行依赖收集的节点。
    */
-  setActiveNodeAsSub(nodeAsSub: Node | undefined): void;
+  setActiveNodeAsSub(nodeAsSub: Node | undefined): Node | undefined;
   /**
    * 设置当前正在进行依赖收集的节点为空。
    */
@@ -186,7 +186,7 @@ export interface ReactiveSystem {
   /**
    * 重置当前正在进行依赖收集的节点。
    */
-  resetActiveNodeAsSub(): void;
+  resetActiveNodeAsSub(): Node | undefined;
   /**
    * 将指定节点作为当前正在进行依赖收集的节点执行指定函数。
    */
@@ -591,7 +591,7 @@ export const createReactiveSystem = (options: CreateReactiveSystemOptions): Reac
     return subNodes;
   }
 
-  let prevActiveNodeAsSubStack: Array<Node | undefined> = [];
+  const prevActiveNodeAsSubStack: Array<Node | undefined> = [];
   let activeNodeAsSub: Node | undefined = undefined;
   const getActiveNodeAsSub = (): Node | undefined => {
     return activeNodeAsSub;
@@ -636,7 +636,7 @@ export const createReactiveSystem = (options: CreateReactiveSystemOptions): Reac
   const endTracking = (nodeAsSub: Node): void => {
     const flags = nodeAsSub.flags;
     if (flags.hasTrackingReusing() === true) {
-      const firstRedundantDepLink = nodeAsSub?.tailDepLink?.nextDepLink;
+      const firstRedundantDepLink = nodeAsSub.tailDepLink?.nextDepLink;
       if (firstRedundantDepLink !== undefined) {
         let toRemove: Link | undefined = firstRedundantDepLink;
         while (toRemove !== undefined) {
@@ -703,7 +703,7 @@ export const createReactiveSystem = (options: CreateReactiveSystemOptions): Reac
     }
   }
   const track = (node: Node): void => {
-    let targetSub = getActiveNodeAsSub();
+    const targetSub = getActiveNodeAsSub();
     if (targetSub !== undefined) {
       addLinkBetweenOptimizedForTracking(node, targetSub);
     }

package/src/singleton/README.md

@@ -0,0 +1,79 @@
+# Singleton
+
+## Description
+
+Singleton 模块用于提供单例（singleton）相关的基础能力，主要承载惰性初始化（lazy initialization）、结果缓存以及具名共享实例的组织语义。
+
+它关注的不是“如何制造全局变量”，而是“当某个值确实只应初始化一次并被稳定复用时，应如何用清楚、可维护的方式表达这种共享关系”。因此，这个模块更适合用来建模实例生命周期与访问边界，而不是无差别地为任何对象增加全局缓存入口。
+
+## For Understanding
+
+理解 Singleton 模块时，重点不在“单例”这个词本身，而在“共享值的生命周期由谁负责、初始化在什么时候发生、调用方如何稳定访问它”。这个模块解决的是共享实例的建模问题：某个值是否应在首次读取时才创建、是否应在后续始终复用、是否需要通过名称组织多个共享项。
+
+因此，它适合放在那些需要明确所有权和初始化时机的边界中，例如基础配置、昂贵对象构造结果、应用级共享资源或一组可按名称访问的依赖项。它不适合表达的，则是带有复杂销毁规则、作用域切换规则或线程级隔离要求的资源管理问题；那类问题通常需要更完整的生命周期模型，不能仅靠“只创建一次”来概括。
+
+还需要注意的是，单例只是一种共享策略，不应被误解为默认设计。只有当值的复用边界、初始化副作用和缓存语义都足够清楚时，它才适合进入这个模块。否则，过早把普通依赖硬塞进单例模型，只会把状态管理问题隐藏起来，而不会真正减少复杂度。
+
+## For Using
+
+当你需要把某个值设计为“首次访问时初始化，之后持续复用”的共享实例时，可以使用这个模块。它适合那些初始化成本较高、创建时机需要延后、并且复用边界明确的场景。
+
+从使用角度看，这个模块大致包含两类能力。一类是惰性工厂能力，用来把一次性初始化逻辑包装成可复用入口，使值只在真正需要时才被创建。另一类是具名单例集合能力，用来把多个共享实例组织成一个稳定的命名集合，便于调用方按名称读取相应的缓存结果。
+
+更合理的使用方式，是把单例能力放在应用或模块边界附近，并让初始化逻辑保持尽量确定。特别是在初始化会接触 I/O、环境变量、全局对象或其它外部资源时，应先明确这些副作用是否真的适合缓存。测试场景中也应明确控制缓存状态的生命周期，避免不同用例之间因为共享状态而互相影响。
+
+## For Contributing
+
+贡献 Singleton 模块时，应优先判断新增能力解决的是不是稳定的共享生命周期问题，而不是某个局部实现里一时方便的缓存技巧。这个模块的公共语义应围绕“值只初始化一次并被复用”以及“多个共享项如何被命名和访问”展开，而不是替调用方偷偷管理越来越复杂的状态机。
+
+在继续扩展时，应守住几个边界。不要把作用域管理、资源销毁、并发隔离或依赖注入容器的完整语义混入 Singleton 模块；这些问题虽然与共享实例有关，但通常比单例语义更大。也不要为了省掉几次参数传递，就把本应显式注入的依赖升级为全局单例。只有当共享关系本身就是模块想表达的稳定模型时，新增能力才值得公开。
+
+### JSDoc 注释格式要求
+
+- 每个公开导出的目标（类型、函数、变量、类等）都应包含 JSDoc 注释，让人在不跳转实现的情况下就能理解用途。
+- JSDoc 注释第一行应为清晰且简洁的描述，该描述优先使用中文（英文也可以）。
+- 如果描述后还有其他内容，应在描述后加一个空行。
+- 如果有示例，应使用 `@example` 标签，后接三重反引号代码块（不带语言标识）。
+- 如果有示例，应包含多个场景，展示不同用法，尤其要覆盖常见组合方式或边界输入。
+- 如果有示例，应使用注释格式说明每个场景：`// Expect: <result>`。
+- 如果有示例，应将结果赋值给 `example1`、`example2` 之类的变量，以保持示例易读。
+- 如果有示例，`// Expect: <result>` 应该位于 `example1`、`example2` 之前，以保持示例的逻辑清晰。
+- 如果有示例，应优先使用确定性示例；避免断言精确的随机输出。
+- 如果函数返回结构化字符串，应展示其预期格式特征。
+- 如果有参考资料，应将 `@see` 放在 `@example` 代码块之后，并用一个空行分隔。
+
+### 实现规范要求
+
+- 不同程序元素之间使用一个空行分隔，保持结构清楚。这里的程序元素，通常指函数、类型、常量，以及直接服务于它们的辅助元素。
+- 某程序元素独占的辅助元素与该程序元素本身视为一个整体，不要在它们之间添加空行。
+- 程序元素的辅助元素应该放置在该程序元素的上方，以保持阅读时的逻辑顺序。
+- 若辅助元素被多个程序元素共享，则应将其视为独立的程序元素，放在这些程序元素中第一个相关目标的上方，并与后续程序元素之间保留一个空行。
+- 辅助元素也应该像其它程序元素一样，保持清晰的命名和适当的注释，以便在需要阅读实现细节时能够快速理解它们的作用和使用方式。
+- 辅助元素的命名必须以前缀 `internal` 开头（或 `Internal`，大小写不敏感）。
+- 辅助元素永远不要公开导出。
+- 被模块内多个不同文件中的程序元素共享的辅助元素，应该放在一个单独的文件中，例如 `./src/singleton/internal.ts`。
+- 模块内可以包含子模块。只有当某个子目录表达一个稳定、可单独理解、且可能被父模块重导出的子问题域时，才应将其视为子模块。
+- 子模块包含多个文件时，应该为其单独创建子文件夹，并为其创建单独的 Barrel 文件；父模块的 Barrel 文件再重导出子模块的 Barrel 文件。
+- 子模块不需要有自己的 `README.md`。
+- 子模块可以有自己的 `internal.ts` 文件，多个子模块共享的辅助元素应该放在父模块的 `internal.ts` 文件中，单个子模块共享的辅助元素应该放在该子模块的 `internal.ts` 文件中。
+- 对模块依赖关系的要求（通常是不循环依赖或不反向依赖）与对 DRY 的要求可能产生冲突。此时，若复用的代码数量不大，可以适当牺牲 DRY，复制粘贴并保留必要的注释说明；若复用的代码数量较大，则可以将其抽象到新的文件或子模块中，如 `common.ts`，并在需要的地方导入使用。
+
+- 与单例相关的实现应优先围绕初始化时机、复用边界与具名共享语义组织，避免把销毁策略、作用域切换或依赖注入容器语义混入模块边界。
+
+### 导出策略要求
+
+- 保持内部辅助项和内部符号为私有，不要让外部接入依赖临时性的内部结构。
+- 每个模块都应有一个用于重导出所有公共 API 的 Barrel 文件。
+- Barrel 文件应命名为 `index.ts`，放在模块目录根部，并且所有公共 API 都应从该文件导出。
+- 新增公共能力时，应优先检查它是否表达稳定、清楚且值得长期维护的单例语义，而不是某段实现细节的便捷暴露；仅在确认需要长期对外承诺时再加入 Barrel 导出。
+
+### 测试要求
+
+- 若程序元素是函数，则只为该函数编写一个测试，如果该函数需要测试多个用例，应放在同一个测试中。
+- 若程序元素是类，则至少要为该类的每一个方法编写一个测试，如果该方法需要测试多个用例，应放在同一个测试中。
+- 若程序元素是类，除了为该类的每一个方法编写至少一个测试之外，还可以为该类编写任意多个测试，以覆盖该类的不同使用场景或边界情况。
+- 若编写测试时需要用到辅助元素（Mock 或 Spy 等），可以在测试文件中直接定义这些辅助元素。若辅助元素较为简单，则可以直接放在每一个测试内部，优先保证每个测试的独立性，而不是追求极致 DRY；若辅助元素较为复杂或需要在多个测试中复用，则可以放在测试文件顶部，供该测试文件中的所有测试使用。
+- 测试顺序应与源文件中被测试目标的原始顺序保持一致。
+- 若该模块不需要测试，必须在说明文件中明确说明该模块不需要测试，并说明理由。一般来说，只有在该模块没有可执行的公共函数、只承载类型层表达，或其语义已被上层模块的测试完整覆盖且重复测试几乎不再带来额外价值时，才适合这样处理。
+- 模块的单元测试文件目录是 `./tests/unit/singleton`，若模块包含子模块，则子模块的单元测试文件目录为 `./tests/unit/singleton/<sub-module-name>`。
+- 对单例相关能力，应优先覆盖首次初始化、重复访问复用、不同名称隔离、错误分支以及测试间状态控制等场景。

package/src/singleton/factory.ts

@@ -0,0 +1,55 @@
+/**
+ * 定义惰性单例工厂函数类型。
+ */
+export type SingletonFactory<T> = () => T
+
+/**
+ * 创建一个会缓存首次结果的单例工厂。
+ *
+ * @example
+ * ```
+ * // Scenario 1: object values are created once and then reused.
+ * let calls = 0
+ * const getConfig = getSingletonFactory(() => {
+ *   calls += 1
+ *   return { env: "test" }
+ * })
+ *
+ * const example1 = getConfig()
+ * const example2 = getConfig()
+ * const example3 = example1 === example2
+ * const example4 = calls
+ *
+ * // Expect: true
+ * example3
+ * // Expect: 1
+ * example4
+ *
+ * // Scenario 2: primitive values are also cached after the first read.
+ * let count = 0
+ * const getPort = getSingletonFactory(() => {
+ *   count += 1
+ *   return 3000
+ * })
+ *
+ * const example5 = getPort()
+ * const example6 = getPort()
+ * const example7 = count
+ *
+ * // Expect: 3000
+ * example5
+ * // Expect: 3000
+ * example6
+ * // Expect: 1
+ * example7
+ * ```
+ */
+export const getSingletonFactory = <T>(make: () => T): SingletonFactory<T> => {
+  let singleton: T | undefined = undefined
+  return () => {
+    if (singleton === undefined) {
+      singleton = make()
+    }
+    return singleton
+  }
+}

package/src/singleton/index.ts

@@ -0,0 +1,2 @@
+export * from "./factory.ts"
+export * from "./manager.ts"