{"_id":"@buddhilive/dsh-typert-loader","name":"@buddhilive/dsh-typert-loader","dist-tags":{"alpha":"0.1.2-alpha.3","latest":"0.1.2-alpha.3"},"versions":{"0.1.2-alpha.3":{"name":"@buddhilive/dsh-typert-loader","description":"Loader integration for generated Typert package contributions","version":"0.1.2-alpha.3","publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/Buddhilive/buddhi-ai-harness.git","directory":"packages/typert/loader"},"type":"module","main":"lib/index.js","types":"lib/types/index.d.ts","exports":{".":{"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"},"license":"MIT","peerDependencies":{"@deepseek-ai/cordis-plugin-loader":"^1.0.3","@buddhilive/dsh-invariants":"^0.1.2-alpha.3","@buddhilive/dsh-typert-registry":"^0.1.2-alpha.3","@deepseek-ai/cordis":"^4.0.2"},"dependencies":{"@deepseek-ai/schemastery":"^3.18.2"},"devDependencies":{"zod":"^4.4.3","@deepseek-ai/cordis-plugin-loader":"^1.0.3","@buddhilive/dsh-invariants":"^0.1.2-alpha.3","@buddhilive/dsh-typert-registry":"^0.1.2-alpha.3","@deepseek-ai/cordis":"^4.0.2"},"_id":"@buddhilive/dsh-typert-loader@0.1.2-alpha.3","bugs":{"url":"https://github.com/Buddhilive/buddhi-ai-harness/issues"},"homepage":"https://github.com/Buddhilive/buddhi-ai-harness#readme","_integrity":"sha512-YkIEhREWaN3bFWKUiKYGWnz8QEyRPIVf3qpUxZL7QNnHeW62BcjnCDUAdcLRGNASzS3lxPCYZZO6f1Q8F+yizw==","_resolved":"C:\\DevDojo\\Buddhi\\buddhi-ai-harness\\dist\\npm\\buddhilive-dsh-typert-loader-0.1.2-alpha.3.tgz","_from":"file:C:/DevDojo/Buddhi/buddhi-ai-harness/dist/npm/buddhilive-dsh-typert-loader-0.1.2-alpha.3.tgz","_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-YkIEhREWaN3bFWKUiKYGWnz8QEyRPIVf3qpUxZL7QNnHeW62BcjnCDUAdcLRGNASzS3lxPCYZZO6f1Q8F+yizw==","shasum":"f86259ca519509f0c472020ba1b21a570f917e18","tarball":"https://registry.npmjs.org/@buddhilive/dsh-typert-loader/-/dsh-typert-loader-0.1.2-alpha.3.tgz","fileCount":9,"unpackedSize":37035,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIFvRdUJQnEN40oNPDUV12N4xFga25Z3WdhN/qkWsYdKaAiEA2Fowq7A4HSZ7Wy8NMGw9dV/8Ha9V+MM6rRED7W4uoHg="}]},"_npmUser":{"name":"buddhilive","email":"visitbudkavin@gmail.com"},"directories":{},"maintainers":[{"name":"buddhilive","email":"visitbudkavin@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/dsh-typert-loader_0.1.2-alpha.3_1788165947675_0.39943702330924347"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-31T08:45:47.484Z","0.1.2-alpha.3":"2026-08-31T08:45:47.816Z","modified":"2026-08-31T08:45:48.021Z"},"maintainers":[{"name":"buddhilive","email":"visitbudkavin@gmail.com"}],"description":"Loader integration for generated Typert package contributions","homepage":"https://github.com/Buddhilive/buddhi-ai-harness#readme","repository":{"type":"git","url":"git+https://github.com/Buddhilive/buddhi-ai-harness.git","directory":"packages/typert/loader"},"bugs":{"url":"https://github.com/Buddhilive/buddhi-ai-harness/issues"},"license":"MIT","readme":"---\ndescription: \"生成的 Typert 产物所用的 Loader 集成：已挂载的包如何自动把宿主侧反射与 schema 贡献给运行时注册表。\"\nkind: \"package-reference\"\n---\n\n# @buddhilive/dsh-typert-loader\n\n[English](README.md) | 中文\n\n## 概述\n\n挂载 `dsh-typert-loader` 后，Loader 组合中每个挂载的包都会自动把其生成的 Typert 反射与 schema 贡献给运行时注册表——并在包或本插件卸载时自动撤销。没有该导出的包会被跳过，因此在任何 Loader 组合中挂载它都是安全的。显式 `packages` 用于覆盖嵌套在另一 Loader 配置项之下的插件，这些插件的 fiber 不携带可解析的包说明符。它是仅支持 Node 的插件，需要配置树解析锚点才能解析包。\n\n## 目录\n\n- [使用本包](#use-this-package)\n- [理解实现](#understand-the-implementation)\n- [进一步探索](#further-exploration)\n- [模型体验](#model-experience)\n- [已知限制与延期工作](#known-limitations-and-deferred-work)\n- [开发备注](#dev-note)\n\n-----\n\n<a id=\"use-this-package\"></a>\n## 使用本包\n\n在加载发布生成 Typert 产物的包的 Host Loader 组合中挂载本插件。注册表本身来自 `dsh-typert-registry`；本插件只负责发现与注册。\n\n### 最小配置\n\n加载注册表与 loader；loader 默认发现每一个 Loader 配置项：\n\n```yaml\n- name: '@buddhilive/dsh-typert-registry'\n- name: '@buddhilive/dsh-typert-loader'\n```\n\n| 字段 | 默认值 | 含义 |\n|---|---|---|\n| `packages` | `[]` | 为嵌套在另一 Loader 配置项下的插件额外注册的包产物；每个包都必须能从配置树解析，并导出 `./typert` |\n\n生成的[配置目录](../../../docs/config-catalog.zh.md#buddhilivedsh-typert-loader)是每个受支持字段的穷尽式真源。\n\n### 注册什么\n\n每个符合条件的 Loader 配置项都会把其生成的宿主侧反射与 schema 贡献给运行时注册表。注册跟随配置项生命周期：配置项或本插件卸载时撤销；在两者都已消失后才结束的注册会被丢弃。\n\n### 可观察行为与失败\n\n没有该导出的包会被静默跳过。解析结论与已导入的 manifest 会在整个进程生命周期内缓存，因此新增 `./typert` 导出后必须重启。已挂载配置项对应的产物格式错误时，激活会大声失败；之后才发生的失败按包记录日志，不会阻止无关包完成注册。无法从配置树解析、或缺少该导出的显式 `packages` 条目会大声失败并指名该包。\n\n-----\n\n<a id=\"understand-the-implementation\"></a>\n## 理解实现\n\n<details>\n<summary>实现细节——点击展开</summary>\n\n本节解释 loader 如何扫描、校验与注册；可观察行为已在[使用本包](#use-this-package)中说明。\n\n### 设计理念\n\n本插件是一个增量扫描器，与 client-modules 的 Node 半实现对称：每次 Cordis `internal/plugin` 事件都会把该 fiber 的配置项名称标记为脏，微任务 flush 会针对实时 Loader 配置项逐一调和每个脏名称；激活阶段用所有当前配置项填充同一脏集合。\n\n### Manifest 校验\n\n`validateTypertManifest()` 是模块／文件边界：manifest 从构建产物进入类型化注册表，因此每个字段都会被检查。manifest 必须指名导出它的包、携带 `host` face、持有 zod v4 schema 实例，并保持服务、事件、对象、成员、类型与文档记录格式正确；调用描述符必须使用严格编解码器。每次失败都会指名包与缺陷。\n\n### 缓存与归属\n\n结论（可解析说明符、是否导出）与已导入的 manifest 按包名缓存且永不过期。注册按配置项名称键控，并通过 `ctx.typert.register()` 返回的同一资源释放函数撤销；进行中的任务按配置项跟踪，因此迟到的导入不可能在其所有者消失后注册贡献。\n\n### 源码地图\n\n| 文件 | 职责 |\n|---|---|\n| [`src/index.ts`](src/index.ts) | 插件入口：`Config`、扫描器、manifest 校验、注册接线 |\n| [`src/invariant.ts`](src/invariant.ts) | 不变式伴生插件 |\n\n</details>\n\n-----\n\n<a id=\"further-exploration\"></a>\n## 进一步探索\n\n当包级约定不够用时阅读以下页面；它们从 loader 逐步进入它注册什么以及什么产生这些内容。\n\n- [Typert 注册表](../registry/README.zh.md)——本插件所供给的服务。\n- [Typert 生成器](../generator/README.zh.md)——产生 loader 所导入产物的包。\n- [生成配置目录](../../../docs/config-catalog.zh.md#buddhilivedsh-typert-loader)——`packages` 字段声明及其 JSDoc。\n- [Typert 组地图](../README.zh.md)——完整的类型反射流水线。\n\n-----\n\n<a id=\"model-experience\"></a>\n## 模型体验\n\n无，因为 loader 集成只注册生成的产物；任何模型可见投影均由消费方负责。\n\n#### KV Cache 影响\n\n无直接影响；注册变化只有在消费方读取注册表时才会触及请求。\n\n## 已知限制与延期工作\n\n<a id=\"known-limitations-and-deferred-work\"></a>\n\n\n这些限制说明 loader 不会发现或注册什么；它们是当前包约束，不是任务积压。\n\n- **仅宿主侧**——发现机制只会导入宿主侧 `./typert` 产物；在为客户端运行时添加等价的发现机制之前，需要先有独立的组合所有者。\n- **嵌套插件需要显式条目**——Loader 配置项会被自动发现，但嵌套在另一配置项之下、或完全不经 Loader 加载的插件，需要显式加入 `packages`，或由其所有者直接调用 `ctx.typert.register()`。\n- **缓存结论永不过期**——进程中途新增 `./typert` 导出的包需要重启后 loader 才会注册它。\n\n<a id=\"dev-note\"></a>\n### 开发备注\n\n<details>\n<summary>维护者的工作上下文——点击展开</summary>\n\n无。\n\n</details>\n","readmeFilename":"README.zh.md","_rev":"1-07c5e6e888953b31d646fba283adce1a"}