@xneog/dsh-typert-loader 0.1.0 → 0.1.2-rc.1

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/typert/loader/README.md
-README.md: ab9293de1630fdbe8c560bb9e6d00c272cc34161
-README.zh.md: 4e962c05b73982f03accab938cf3282dfe333dbc
+README.md: c46280f12ad5b912cac706326f23fcd6ceb3d066
+README.zh.md: 96cf5ae9c62ff2f61fe31774353cee55498896a4

package/README.md

@@ -1,24 +1,126 @@
+---
+description: "Loader integration for generated Typert artifacts: how mounted packages automatically contribute their host-face reflection and schemas to the runtime registry."
+kind: "package-reference"
+---
+
 # @xneog/dsh-typert-loader
 
 English | [中文](README.zh.md)
 
-Node-only Loader integration for generated Typert artifacts. The plugin requires `ctx.loader` and `ctx.typert`; it does not provide the registry itself.
+## Summary
+
+With `dsh-typert-loader` mounted, every package that mounts in a Loader composition automatically contributes its generated Typert reflection and schemas to the runtime registry — and withdraws them when the package or the plugin unmounts. Packages without the generated export are skipped, so adding the plugin to any composition is safe. An explicit `packages` list covers plugins nested behind another Loader entry, whose fibers carry no resolvable package specifier. It is a Node-only plugin and needs the config-tree resolution anchor to resolve packages.
+
+## 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
+
+Mount this plugin in a Host Loader composition that loads packages publishing generated Typert artifacts. The registry itself comes from `dsh-typert-registry`; this plugin only discovers and registers.
+
+### Minimal configuration
+
+Load the registry and the loader; the loader defaults to discovering every Loader entry:
+
+```yaml
+- name: '@xneog/dsh-typert-registry'
+- name: '@xneog/dsh-typert-loader'
+```
+
+| Field | Default | Meaning |
+|---|---|---|
+| `packages` | `[]` | Additional package artifacts to register for plugins nested behind another Loader entry; each must resolve from the config tree and export `./typert` |
+
+The generated [configuration catalog](../../../docs/config-catalog.md#xneogdsh-typert-loader) is the exhaustive source for every accepted field.
+
+### What gets registered
+
+Each qualifying Loader entry contributes its generated host-face reflection and schemas to the runtime registry. Registration follows the entry lifecycle: it is withdrawn when the entry or the plugin unmounts, and a registration whose import settles after both are gone is discarded.
+
+### Observable behavior and failures
+
+Packages without the export are skipped silently. Resolution verdicts and imported manifests are cached for the process lifetime, so adding a `./typert` export requires a restart. A malformed artifact among already-mounted entries fails activation loudly; a later failure is logged per package without preventing unrelated packages from registering. An explicit `packages` entry that cannot be resolved from the config tree, or that lacks the export, fails loudly and names the package.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
 
-During activation it scans existing Loader entries. It then follows Cordis `internal/plugin` lifecycle notifications, resolves each entry package's `package.json`, imports `./typert` when exported, validates its `TYPERT` manifest, and registers the contribution until the entry or this plugin unmounts. An import that settles after either owner is gone is discarded.
+This section explains how the loader scans, validates, and registers; the observable behavior is covered in [Use this package](#use-this-package).
 
-`packages` lists additional package artifacts to register for plugins nested behind another Loader entry. Cordis fibers do not retain those nested plugins' npm specifiers, so this boundary is explicit; every configured package must resolve from the config tree and export `./typert`.
+### Design concept
 
-Packages without the export are skipped. Package resolution and imported manifests are cached for the process lifetime, so adding an export requires a restart. A malformed artifact fails activation when already mounted; a later failure is logged without preventing unrelated packages from registering.
+The plugin is an incremental scanner mirroring the client-modules node half: every Cordis `internal/plugin` emission marks the fiber's entry name dirty, and a microtask flush reconciles each dirty name against the live Loader entries; the activation pass seeds the same dirty set with all current entries.
 
+### Manifest validation
+
+`validateTypertManifest()` is the module/file boundary: the manifest crosses from a build artifact into the typed registry, so every field is checked. The manifest must name the package that exports it, carry face `host`, hold zod v4 schema instances, and keep well-formed service, event, object, member, type, and documentation records; invocation descriptors must use strict codecs. Every failure names the package and the defect.
+
+### Caching and ownership
+
+Verdicts (resolvable specifier, export presence) and imported manifests are cached per package name and never expire. Registrations are keyed by entry name and withdrawn through the exact `ctx.typert.register()` disposer; in-flight tasks are tracked per entry so a late import cannot register a contribution after its owner is gone.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Plugin entry: `Config`, scanner, manifest validation, registration wiring |
+| — | No runtime invariant companion is published; the Loader entry lifecycle directly owns each exact registry disposer, and integration tests observe registration and removal. |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these pages when the package-level contract is not enough; they move from the loader to what it registers and what produces it.
+
+- [Typert registry](../registry/README.md) — the service this plugin feeds.
+- [Typert generator](../generator/README.md) — what produces the artifacts the loader imports.
+- [Generated configuration catalog](../../../docs/config-catalog.md#xneogdsh-typert-loader) — the `packages` field declaration and JSDoc.
+- [Typert group map](../README.md) — the full type-reflection pipeline.
+
+-----
+
+<a id="model-experience"></a>
 ## Model Experience
 
-None, as the loader only feeds [`ctx.typert`](../registry/README.md); consumers own any model-visible projection.
+None, as loader integration only registers generated artifacts; consumers own any model-visible projection.
 
 #### KV Cache effect
 
-No direct effect.
+No direct effect; registration changes reach a request only through a consumer that reads the registry.
 
 ## Known Limitations and Deferred Work
 
-- Discovery imports only the host face; client runtimes need a separate composition owner before equivalent discovery is added.
-- Loader entries are discovered automatically. Nested or non-Loader plugins require an explicit `packages` entry or direct `ctx.typert.register()` ownership.
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define what the loader does not discover or register; they are current package constraints, not a task backlog.
+
+- **Host face only** — discovery imports only the host `./typert` artifact; client runtimes need a separate composition owner before equivalent discovery is added.
+- **Explicit entries for nested plugins** — Loader entries are discovered automatically, but plugins nested behind another entry, or not loaded by the Loader at all, need an explicit `packages` entry or direct `ctx.typert.register()` ownership.
+- **Cached verdicts never expire** — a package that gains a `./typert` export mid-process needs a restart before the loader registers it.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -1,24 +1,126 @@
+---
+description: "生成的 Typert 产物所用的 Loader 集成：已挂载的包如何自动把宿主侧反射与 schema 贡献给运行时注册表。"
+kind: "package-reference"
+---
+
 # @xneog/dsh-typert-loader
 
 [English](README.md) | 中文
 
-生成的 Typert 产物所用的 Loader 集成，仅支持 Node。该插件需要 `ctx.loader` 和 `ctx.typert`；它本身不提供注册表。
+## 概述
+
+挂载 `dsh-typert-loader` 后，Loader 组合中每个挂载的包都会自动把其生成的 Typert 反射与 schema 贡献给运行时注册表——并在包或本插件卸载时自动撤销。没有该导出的包会被跳过，因此在任何 Loader 组合中挂载它都是安全的。显式 `packages` 用于覆盖嵌套在另一 Loader 配置项之下的插件，这些插件的 fiber 不携带可解析的包说明符。它是仅支持 Node 的插件，需要配置树解析锚点才能解析包。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+在加载发布生成 Typert 产物的包的 Host Loader 组合中挂载本插件。注册表本身来自 `dsh-typert-registry`；本插件只负责发现与注册。
+
+### 最小配置
+
+加载注册表与 loader；loader 默认发现每一个 Loader 配置项：
+
+```yaml
+- name: '@xneog/dsh-typert-registry'
+- name: '@xneog/dsh-typert-loader'
+```
+
+| 字段 | 默认值 | 含义 |
+|---|---|---|
+| `packages` | `[]` | 为嵌套在另一 Loader 配置项下的插件额外注册的包产物；每个包都必须能从配置树解析，并导出 `./typert` |
+
+生成的[配置目录](../../../docs/config-catalog.zh.md#xneogdsh-typert-loader)是每个受支持字段的穷尽式真源。
+
+### 注册什么
+
+每个符合条件的 Loader 配置项都会把其生成的宿主侧反射与 schema 贡献给运行时注册表。注册跟随配置项生命周期：配置项或本插件卸载时撤销；在两者都已消失后才结束的注册会被丢弃。
+
+### 可观察行为与失败
+
+没有该导出的包会被静默跳过。解析结论与已导入的 manifest 会在整个进程生命周期内缓存，因此新增 `./typert` 导出后必须重启。已挂载配置项对应的产物格式错误时，激活会大声失败；之后才发生的失败按包记录日志，不会阻止无关包完成注册。无法从配置树解析、或缺少该导出的显式 `packages` 条目会大声失败并指名该包。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
 
-激活时，该插件会扫描现有的 Loader 配置项。随后它会监听 Cordis `internal/plugin` 生命周期通知，解析每个配置项所属包的 `package.json`，在其导出 `./typert` 时导入该子路径，校验其 `TYPERT` manifest（元数据清单），并注册该贡献项，直到配置项或本插件卸载。如果导入操作在配置项或本插件卸载后才结束，系统会丢弃其结果。
+本节解释 loader 如何扫描、校验与注册；可观察行为已在[使用本包](#use-this-package)中说明。
 
-`packages` 用于列出需要为嵌套在另一 Loader 配置项下的插件额外注册的包产物。Cordis fiber 不会保留这些嵌套插件的 npm 包说明符，因此这里通过显式配置划定边界；配置中列出的每个包都必须能从配置树解析，并导出 `./typert`。
+### 设计理念
 
-未导出该子路径的包会被跳过。包解析结果和已导入的 manifest 会在整个进程生命周期内缓存，因此新增该导出后必须重启进程。插件激活时，如果已挂载 Loader 配置项对应的产物格式错误，激活会失败；之后才发生的失败只会记录到日志，不会阻止无关包完成注册。
+本插件是一个增量扫描器，与 client-modules 的 Node 半实现对称：每次 Cordis `internal/plugin` 事件都会把该 fiber 的配置项名称标记为脏，微任务 flush 会针对实时 Loader 配置项逐一调和每个脏名称；激活阶段用所有当前配置项填充同一脏集合。
 
+### Manifest 校验
+
+`validateTypertManifest()` 是模块／文件边界：manifest 从构建产物进入类型化注册表，因此每个字段都会被检查。manifest 必须指名导出它的包、携带 `host` face、持有 zod v4 schema 实例，并保持服务、事件、对象、成员、类型与文档记录格式正确；调用描述符必须使用严格编解码器。每次失败都会指名包与缺陷。
+
+### 缓存与归属
+
+结论（可解析说明符、是否导出）与已导入的 manifest 按包名缓存且永不过期。注册按配置项名称键控，并通过 `ctx.typert.register()` 返回的同一资源释放函数撤销；进行中的任务按配置项跟踪，因此迟到的导入不可能在其所有者消失后注册贡献。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | 插件入口：`Config`、扫描器、manifest 校验、注册接线 |
+| — | 不发布运行时不变式伴生入口；Loader entry 生命周期直接持有每个准确的 registry disposer，integration test 会观察注册与移除。 |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+当包级约定不够用时阅读以下页面；它们从 loader 逐步进入它注册什么以及什么产生这些内容。
+
+- [Typert 注册表](../registry/README.zh.md)——本插件所供给的服务。
+- [Typert 生成器](../generator/README.zh.md)——产生 loader 所导入产物的包。
+- [生成配置目录](../../../docs/config-catalog.zh.md#xneogdsh-typert-loader)——`packages` 字段声明及其 JSDoc。
+- [Typert 组地图](../README.zh.md)——完整的类型反射流水线。
+
+-----
+
+<a id="model-experience"></a>
 ## 模型体验
 
-无。loader 只向 [`ctx.typert`](../registry/README.md) 提供注册项；任何模型可见投影均由消费方负责。
+无，因为 loader 集成只注册生成的产物；任何模型可见投影均由消费方负责。
 
 #### KV Cache 影响
 
-无直接影响。
+无直接影响；注册变化只有在消费方读取注册表时才会触及请求。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制说明 loader 不会发现或注册什么；它们是当前包约束，不是任务积压。
+
+- **仅宿主侧**——发现机制只会导入宿主侧 `./typert` 产物；在为客户端运行时添加等价的发现机制之前，需要先有独立的组合所有者。
+- **嵌套插件需要显式条目**——Loader 配置项会被自动发现，但嵌套在另一配置项之下、或完全不经 Loader 加载的插件，需要显式加入 `packages`，或由其所有者直接调用 `ctx.typert.register()`。
+- **缓存结论永不过期**——进程中途新增 `./typert` 导出的包需要重启后 loader 才会注册它。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
 
-## 已知限制与暂缓事项
+无。
 
-- 发现机制只会导入宿主侧产物；若要为客户端运行时添加等价的发现机制，需要先有独立的组合所有者。
-- Loader 配置项会自动发现。嵌套插件或非 Loader 插件需要显式加入 `packages`，或由其所有者直接负责调用 `ctx.typert.register()`。
+</details>

package/lib/index.js

@@ -17,9 +17,9 @@ import z from "@xneog/schemastery";
 * fails loud — aggregated into this plugin's activation throw for existing
 * entries, contained to a logged error per package in steady state.
 *
-* Scanning is incremental per entry name, mirroring the client-modules node
-* half: every cordis `internal/plugin` emission marks the fiber's entry name
-* dirty and a microtask flush reconciles each dirty name against the live
+* Scanning is incremental per entry name. Every cordis `internal/plugin`
+* emission marks the fiber's entry name dirty, and a microtask flush
+* reconciles each dirty name against the live
 * loader entries; the activation pass seeds the same dirty set with all
 * current entries. Package verdicts and imported manifests are cached per
 * package name and never expire — plugin-set changes take effect on restart.

package/lib/types/index.d.ts

@@ -11,9 +11,9 @@
  * fails loud — aggregated into this plugin's activation throw for existing
  * entries, contained to a logged error per package in steady state.
  *
- * Scanning is incremental per entry name, mirroring the client-modules node
- * half: every cordis `internal/plugin` emission marks the fiber's entry name
- * dirty and a microtask flush reconciles each dirty name against the live
+ * Scanning is incremental per entry name. Every cordis `internal/plugin`
+ * emission marks the fiber's entry name dirty, and a microtask flush
+ * reconciles each dirty name against the live
  * loader entries; the activation pass seeds the same dirty set with all
  * current entries. Package verdicts and imported manifests are cached per
  * package name and never expire — plugin-set changes take effect on restart.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xneog/dsh-typert-loader",
   "description": "Loader integration for generated Typert package contributions",
-  "version": "0.1.0",
+  "version": "0.1.2-rc.1",
   "publishConfig": {
     "access": "public"
   },
@@ -18,33 +18,26 @@
       "types": "./lib/types/index.d.ts",
       "default": "./lib/index.js"
     },
-    "./invariant": {
-      "types": "./lib/types/invariant.d.ts",
-      "default": "./lib/invariant.js"
-    },
     "./src/*": "./src/*",
     "./package.json": "./package.json"
   },
   "files": [
     "lib/index.js",
-    "lib/invariant.js",
     "lib/types/**/*.d.ts"
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@xneog/cordis-plugin-loader": "0.1.0",
-    "@xneog/dsh-invariants": "0.1.0",
-    "@xneog/dsh-typert-registry": "0.1.0",
-    "@xneog/cordis": "0.1.0"
+    "@xneog/cordis-plugin-loader": "^1.0.3",
+    "@xneog/dsh-typert-registry": "^0.1.2-rc.1",
+    "@xneog/cordis": "^4.0.2"
   },
   "dependencies": {
-    "@xneog/schemastery": "0.1.0"
+    "@xneog/schemastery": "^3.18.2"
   },
   "devDependencies": {
-    "@xneog/cordis-plugin-loader": "0.1.0",
-    "@xneog/dsh-invariants": "0.1.0",
-    "@xneog/dsh-typert-registry": "0.1.0",
-    "@xneog/cordis": "0.1.0",
-    "zod": "^4.4.3"
+    "zod": "^4.4.3",
+    "@xneog/dsh-typert-registry": "^0.1.2-rc.1",
+    "@xneog/cordis-plugin-loader": "^1.0.3",
+    "@xneog/cordis": "^4.0.2"
   }
 }

package/lib/invariant.js

@@ -1,23 +0,0 @@
-//#region lib/types/invariant.js
-/**
-* Package-owned invariant companion for `@xneog/dsh-typert-loader`.
-* @module @xneog/dsh-typert-loader/invariant
-*/
-const PACKAGE_NAME = "@xneog/dsh-typert-loader";
-/** Cordis companion plugin name. */
-const name = "typert-loader-invariant";
-/** Service required before the companion can reserve package ownership. */
-const inject = ["invariants"];
-/**
-* No runtime invariant: the Loader entry lifecycle directly owns each exact
-* registry disposer, and integration tests observe registration and removal.
-*/
-const install = () => {};
-/**
-* Register this package's invariant companion.
-* @param ctx - Cordis context carrying the invariant service.
-* @returns the installed registration's disposer after setup succeeds.
-*/
-const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
-//#endregion
-export { apply, inject, name };

package/lib/types/invariant.d.ts

@@ -1,16 +0,0 @@
-/**
- * Package-owned invariant companion for `@xneog/dsh-typert-loader`.
- * @module @xneog/dsh-typert-loader/invariant
- */
-import type { Context } from '@xneog/cordis';
-/** Cordis companion plugin name. */
-export declare const name = "typert-loader-invariant";
-/** Service required before the companion can reserve package ownership. */
-export declare const inject: string[];
-/**
- * Register this package's invariant companion.
- * @param ctx - Cordis context carrying the invariant service.
- * @returns the installed registration's disposer after setup succeeds.
- */
-export declare const apply: (ctx: Context) => Promise<() => void>;
-//# sourceMappingURL=invariant.d.ts.map