@x1a0f3n9/dsh-typert-loader 0.1.5-rc.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/typert/loader/README.md
+README.md: 378be98dea5f47e4d6b0a0c70600e2a4c221c80b
+README.zh.md: e598127bba12e4057405231fe09199db18f9604d

package/README.md

@@ -0,0 +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"
+---
+
+# @x1a0f3n9/dsh-typert-loader
+
+English | [中文](README.zh.md)
+
+## 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: '@x1a0f3n9/dsh-typert-registry'
+- name: '@x1a0f3n9/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#deepseek-aidsh-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 an import that settles after either owner is 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>
+
+This section explains how the loader scans, validates, and registers; the observable behavior is covered in [Use this package](#use-this-package).
+
+### Design concept
+
+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#deepseek-aidsh-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 loader integration only registers generated artifacts; consumers own any model-visible projection.
+
+#### KV Cache effect
+
+No direct effect; registration changes reach a request only through a consumer that reads the registry.
+
+## Known Limitations and Deferred Work
+
+<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

@@ -0,0 +1,126 @@
+---
+description: "生成的 Typert 产物所用的 Loader 集成：已挂载的包如何自动把宿主侧反射与 schema 贡献给运行时注册表。"
+kind: "package-reference"
+---
+
+# @x1a0f3n9/dsh-typert-loader
+
+[English](README.md) | 中文
+
+## 概述
+
+挂载 `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: '@x1a0f3n9/dsh-typert-registry'
+- name: '@x1a0f3n9/dsh-typert-loader'
+```
+
+| 字段 | 默认值 | 含义 |
+|---|---|---|
+| `packages` | `[]` | 为嵌套在另一 Loader 配置项下的插件额外注册的包产物；每个包都必须能从配置树解析，并导出 `./typert` |
+
+生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-typert-loader)是所有受支持字段的完整真源。
+
+### 注册什么
+
+每个符合条件的 Loader 配置项都会把其生成的宿主侧反射与 schema 贡献给运行时注册表。注册跟随配置项生命周期：配置项或本插件卸载时撤销；在配置项或本插件任一方卸载后才结束的导入操作会被丢弃。
+
+### 可观察行为与失败
+
+没有该导出的包会被静默跳过。解析结论与已导入的 manifest（元数据清单）会在整个进程生命周期内缓存，因此新增 `./typert` 导出后必须重启。已挂载配置项对应的产物格式错误时，激活会明确报错；之后才发生的失败按包记录日志，不会阻止无关包完成注册。无法从配置树解析、或缺少该导出的显式 `packages` 条目会明确报错并指名该包。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+本节解释 loader 如何扫描、校验与注册；可观察行为已在[使用本包](#use-this-package)中说明。
+
+### 设计理念
+
+本插件是一个增量扫描器，与 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 配置项的生命周期直接持有每个对应的注册表资源释放函数，集成测试会观察注册与移除。 |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+当包级约定不够用时阅读以下页面；这些页面从 loader 开始，依次介绍它注册的内容及其生成方。
+
+- [Typert 注册表](../registry/README.zh.md)——本插件所供给的服务。
+- [Typert 生成器](../generator/README.zh.md)——产生 loader 所导入产物的包。
+- [生成配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-typert-loader)——`packages` 字段声明及其 JSDoc。
+- [Typert 组地图](../README.zh.md)——完整的类型反射流水线。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+无，因为 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>
+
+无。
+
+</details>

package/lib/index.js

@@ -0,0 +1,333 @@
+import { createRequire } from "node:module";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+import z from "@deepseek-ai/schemastery";
+//#region lib/types/index.js
+/**
+* Typert Loader integration: automatic registration for mounted plugin packages.
+*
+* When a loader entry mounts, this plugin resolves the entry's package.json; a
+* package exporting `./typert` has its host face imported and its
+* `TYPERT` manifest registered into `ctx.typert`, and the registration is
+* withdrawn when the entry unmounts. Explicit `packages` cover plugins nested
+* behind another Loader entry, whose Cordis fibers carry no resolvable package
+* specifier. Packages without the export are skipped silently when discovered
+* from Loader entries; an explicit package or declared artifact that is broken
+* 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. 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.
+*
+* Manual `ctx.typert.register()` remains available for contributions
+* that do not use a `./typert` artifact (hand-written wire schemas,
+* tests, non-loader compositions).
+*
+* @module @x1a0f3n9/dsh-typert-loader
+*/
+var __rewriteRelativeImportExtension = function(path, preserveJsx) {
+	if (typeof path === "string" && /^\.\.?\//.test(path)) return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function(m, tsx, d, ext, cm) {
+		return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : d + ext + "." + cm.toLowerCase() + "js";
+	});
+	return path;
+};
+/** The package.json exports key naming a package's host-face typert artifact. */
+const TYPERT_HOST_EXPORT = "./typert";
+/** Cordis plugin name. */
+const name = "typert-loader";
+/** Services required before registration: the registry this plugin feeds and the Loader it observes. */
+const inject = ["typert", "loader"];
+/** Validate explicit package names and default to Loader-entry discovery only. */
+const Config = z.object({ packages: z.array(z.string().min(1)).default([]) });
+const MEMBER_KINDS = new Set([
+	"property",
+	"method",
+	"getter",
+	"setter",
+	"call",
+	"construct",
+	"index"
+]);
+/** Resolve the `./typert` export to a relative path, accepting the string and one-level conditional forms. */
+function typertExportOf(pkgName, exportsField) {
+	if (typeof exportsField !== "object" || exportsField === null) return void 0;
+	const target = exportsField[TYPERT_HOST_EXPORT];
+	if (target === void 0) return void 0;
+	if (typeof target === "string") return target;
+	if (typeof target === "object" && target !== null) {
+		const fallback = target.default;
+		if (typeof fallback === "string") return fallback;
+	}
+	throw new Error(`typert-loader: ${pkgName} exports["${TYPERT_HOST_EXPORT}"] must be a string or an object with a string default`);
+}
+/**
+* Narrow a dynamically imported typert module's `TYPERT` export to a
+* contribution owned by `pkgName`. This is the module/file boundary: the
+* manifest crosses from a build artifact into the typed registry, so every
+* field is checked and every failure names the package and the defect.
+* @param pkgName - the package whose typert face was imported.
+* @param exported - the module's `TYPERT` export.
+* @returns the validated contribution.
+*/
+function validateTypertManifest(pkgName, exported) {
+	if (typeof exported !== "object" || exported === null) throw new Error(`typert-loader: ${pkgName} exports "${TYPERT_HOST_EXPORT}" but its module has no TYPERT manifest object`);
+	const manifest = exported;
+	if (manifest.package !== pkgName) throw new Error(`typert-loader: ${pkgName} TYPERT manifest names package ${JSON.stringify(manifest.package)} — the manifest must be owned by the package that exports it`);
+	if (manifest.face !== "host") throw new Error(`typert-loader: ${pkgName} exports "${TYPERT_HOST_EXPORT}" but TYPERT.face is not "host"`);
+	if (!Array.isArray(manifest.schemas)) throw new Error(`typert-loader: ${pkgName} TYPERT.schemas must be an array`);
+	for (const value of manifest.schemas) {
+		if (typeof value !== "object" || value === null) throw new Error(`typert-loader: ${pkgName} TYPERT.schemas contains a non-object schema`);
+		const schema = value;
+		requireString(pkgName, schema, "name", "schema");
+		if (typeof schema.schema !== "object" || schema.schema === null || !("_zod" in schema.schema)) throw new Error(`typert-loader: ${pkgName} TYPERT schema "${schema.name}" is not a zod v4 schema instance`);
+	}
+	const model = requireObject(pkgName, manifest.model, "TYPERT.model");
+	const services = requireArray(pkgName, model.services, "TYPERT.model.services");
+	const events = requireArray(pkgName, model.events, "TYPERT.model.events");
+	const objects = requireArray(pkgName, model.objects, "TYPERT.model.objects");
+	for (const value of services) {
+		const service = requireObject(pkgName, value, "service");
+		requireDocumentation(pkgName, service, "service");
+		requireString(pkgName, service, "key", "service");
+		requireString(pkgName, service, "exportName", "service");
+		requireMembers(pkgName, service.members, `service "${service.key}"`);
+		requireTypes(pkgName, service.types, `service "${service.key}"`);
+	}
+	for (const value of events) {
+		const event = requireObject(pkgName, value, "event");
+		requireDocumentation(pkgName, event, "event");
+		requireString(pkgName, event, "name", "event");
+		requireString(pkgName, event, "signature", `event "${event.name}"`);
+		if (event.mode !== void 0 && typeof event.mode !== "string") throw new Error(`typert-loader: ${pkgName} event "${event.name}" mode must be a string`);
+	}
+	for (const value of objects) {
+		const object = requireObject(pkgName, value, "object");
+		requireDocumentation(pkgName, object, "object");
+		requireString(pkgName, object, "name", "object");
+		requireString(pkgName, object, "exportName", "object");
+		requireMembers(pkgName, object.members, `object "${object.name}"`);
+		requireTypes(pkgName, object.types, `object "${object.name}"`);
+	}
+	for (const value of requireArray(pkgName, manifest.invocations, "TYPERT.invocations")) requireInvocation(pkgName, value);
+	return manifest;
+}
+function requireObject(pkgName, value, subject) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error(`typert-loader: ${pkgName} ${subject} must be an object`);
+	return value;
+}
+function requireArray(pkgName, value, subject) {
+	if (!Array.isArray(value)) throw new Error(`typert-loader: ${pkgName} ${subject} must be an array`);
+	return value;
+}
+function requireString(pkgName, value, key, subject) {
+	if (typeof value[key] !== "string" || value[key].length === 0) throw new Error(`typert-loader: ${pkgName} ${subject} has a missing or empty ${key}`);
+}
+function requireDocumentation(pkgName, value, subject) {
+	requireArray(pkgName, value.tags, `${subject}.tags`);
+	for (const key of [
+		"description",
+		"summary",
+		"jsDoc"
+	]) if (value[key] !== void 0 && typeof value[key] !== "string") throw new Error(`typert-loader: ${pkgName} ${subject}.${key} must be a string`);
+}
+function requireMembers(pkgName, value, subject) {
+	for (const item of requireArray(pkgName, value, `${subject}.members`)) {
+		const member = requireObject(pkgName, item, `${subject} member`);
+		requireString(pkgName, member, "name", `${subject} member`);
+		requireString(pkgName, member, "signature", `${subject} member`);
+		if (typeof member.kind !== "string" || !MEMBER_KINDS.has(member.kind)) throw new Error(`typert-loader: ${pkgName} ${subject} member "${member.name}" has invalid kind`);
+	}
+}
+function requireTypes(pkgName, value, subject) {
+	for (const item of requireArray(pkgName, value, `${subject}.types`)) {
+		const type = requireObject(pkgName, item, `${subject} type`);
+		requireString(pkgName, type, "name", `${subject} type`);
+		requireString(pkgName, type, "declaration", `${subject} type`);
+	}
+}
+function requireInvocation(pkgName, value) {
+	const invocation = requireObject(pkgName, value, "invocation");
+	for (const key of [
+		"id",
+		"service",
+		"namespace",
+		"method"
+	]) requireString(pkgName, invocation, key, "invocation");
+	const id = invocation.id;
+	const receiver = requireObject(pkgName, invocation.invocation, `invocation "${id}" receiver`);
+	if (receiver.kind === "context") {
+		requireString(pkgName, receiver, "context", `invocation "${id}" Context receiver`);
+		requireString(pkgName, receiver, "wire", `invocation "${id}" Context receiver`);
+		requireStrictCodec(pkgName, receiver.codec, `invocation "${id}" Context codec`);
+	} else if (receiver.kind !== "direct") throw new Error(`typert-loader: ${pkgName} invocation "${id}" receiver kind must be "direct" or "context"`);
+	const wires = /* @__PURE__ */ new Set();
+	const parameters = /* @__PURE__ */ new Map();
+	let lookupCount = 0;
+	for (const valueParameter of requireArray(pkgName, invocation.parameters, `invocation "${id}" parameters`)) {
+		const parameter = requireObject(pkgName, valueParameter, `invocation "${id}" parameter`);
+		requireString(pkgName, parameter, "name", `invocation "${id}" parameter`);
+		requireString(pkgName, parameter, "wire", `invocation "${id}" parameter`);
+		const wire = parameter.wire;
+		if (wires.has(wire)) throw new Error(`typert-loader: ${pkgName} invocation "${id}" repeats wire field "${wire}"`);
+		wires.add(wire);
+		if (parameter.source === "lookup") {
+			lookupCount += 1;
+			requireString(pkgName, parameter, "lookup", `invocation "${id}" lookup parameter`);
+		} else if (parameter.source === "json") {
+			if (parameter.lookup !== void 0) throw new Error(`typert-loader: ${pkgName} invocation "${id}" JSON parameter declares a lookup`);
+		} else throw new Error(`typert-loader: ${pkgName} invocation "${id}" parameter source must be "json" or "lookup"`);
+		parameters.set(wire, parameter);
+		requireStrictCodec(pkgName, parameter.codec, `invocation "${id}" parameter codec`);
+	}
+	if (invocation.cancellation !== void 0) {
+		if (requireObject(pkgName, invocation.cancellation, `invocation "${id}" cancellation`).parameter !== "signal") throw new Error(`typert-loader: ${pkgName} invocation "${id}" cancellation parameter must be "signal"`);
+	}
+	if (invocation.scope !== void 0) {
+		if (receiver.kind !== "direct") throw new Error(`typert-loader: ${pkgName} invocation "${id}" Context receiver cannot declare a direct scope projection`);
+		const scope = requireObject(pkgName, invocation.scope, `invocation "${id}" scope`);
+		requireString(pkgName, scope, "context", `invocation "${id}" scope`);
+		requireString(pkgName, scope, "wire", `invocation "${id}" scope`);
+		const parameter = parameters.get(scope.wire);
+		if (lookupCount !== 1 || parameter?.source !== "lookup" || parameter.lookup !== scope.context) throw new Error(`typert-loader: ${pkgName} invocation "${id}" scope wire "${scope.wire}" must select its only lookup parameter`);
+	}
+	if (receiver.kind === "context" && wires.has(receiver.wire)) throw new Error(`typert-loader: ${pkgName} invocation "${id}" repeats Context wire field "${receiver.wire}"`);
+	requireStrictCodec(pkgName, invocation.result, `invocation "${id}" result codec`);
+	if (invocation.sourceLocation !== void 0) {
+		const location = requireObject(pkgName, invocation.sourceLocation, `invocation "${id}" sourceLocation`);
+		requireString(pkgName, location, "file", `invocation "${id}" sourceLocation`);
+		for (const key of ["line", "column"]) if (!Number.isInteger(location[key]) || location[key] < 1) throw new Error(`typert-loader: ${pkgName} invocation "${id}" sourceLocation.${key} must be a positive integer`);
+	}
+}
+function requireStrictCodec(pkgName, value, subject) {
+	const codec = requireObject(pkgName, value, subject);
+	if (codec.mode !== "strict") throw new Error(`typert-loader: ${pkgName} ${subject} must use a strict codec`);
+	requireString(pkgName, codec, "typeSymbol", subject);
+	if (typeof codec.schema !== "object" || codec.schema === null || !("_zod" in codec.schema) || typeof codec.schema.parse !== "function") throw new Error(`typert-loader: ${pkgName} ${subject} is not backed by a zod v4 schema`);
+}
+/**
+* Scan current Loader entries during activation, then follow entry mounts and
+* unmounts for this plugin's lifetime.
+* @param ctx - plugin context carrying `typert` and `loader`.
+* @param config - explicit package artifacts in addition to Loader entries.
+*/
+async function apply(ctx, config) {
+	if (ctx.baseUrl === void 0) throw new Error("typert-loader: ctx.baseUrl is unset — the loader needs the config-tree anchor to resolve plugin packages");
+	const require = createRequire(ctx.baseUrl);
+	const configured = new Set(config.packages);
+	const registered = /* @__PURE__ */ new Map();
+	const pending = /* @__PURE__ */ new Map();
+	const artifactPath = /* @__PURE__ */ new Map();
+	const manifests = /* @__PURE__ */ new Map();
+	const dirty = /* @__PURE__ */ new Set();
+	let flushQueued = false;
+	let active = true;
+	ctx.effect(function* () {
+		yield () => {
+			active = false;
+			dirty.clear();
+		};
+	}, "typert loader lifetime");
+	const resolveArtifact = (pkgName) => {
+		const cached = artifactPath.get(pkgName);
+		if (cached !== void 0) return cached;
+		let pkgPath;
+		try {
+			pkgPath = require.resolve(`${pkgName}/package.json`);
+		} catch (cause) {
+			if (configured.has(pkgName)) throw new Error(`typert-loader: configured package "${pkgName}" cannot be resolved from the config tree — add it to the composition package dependencies or remove it from packages`, { cause });
+			artifactPath.set(pkgName, null);
+			return null;
+		}
+		const rel = typertExportOf(pkgName, JSON.parse(readFileSync(pkgPath, "utf8")).exports);
+		if (rel === void 0 && configured.has(pkgName)) throw new Error(`typert-loader: configured package "${pkgName}" does not export "${TYPERT_HOST_EXPORT}"`);
+		const resolved = rel === void 0 ? null : join(dirname(pkgPath), rel);
+		artifactPath.set(pkgName, resolved);
+		return resolved;
+	};
+	const loadManifest = (pkgName, path) => {
+		let loading = manifests.get(pkgName);
+		if (loading === void 0) {
+			loading = import(__rewriteRelativeImportExtension(pathToFileURL(path).href)).then((mod) => validateTypertManifest(pkgName, mod.TYPERT), (cause) => {
+				throw new Error(`typert-loader: ${pkgName} exports "${TYPERT_HOST_EXPORT}" but importing ${path} failed: ${String(cause)}`);
+			});
+			manifests.set(pkgName, loading);
+		}
+		return loading;
+	};
+	const qualifies = (entryName) => {
+		if (configured.has(entryName)) return true;
+		for (const entry of ctx.loader.entries()) if (entry.options.name === entryName && entry.fiber !== void 0 && !entry.disabled) return true;
+		return false;
+	};
+	/** Reconcile one entry name against the live loader entries; a mount returns its async task. */
+	const processOne = (entryName) => {
+		if (!qualifies(entryName)) {
+			const dispose = registered.get(entryName);
+			if (dispose !== void 0) {
+				registered.delete(entryName);
+				return dispose();
+			}
+			return;
+		}
+		if (registered.has(entryName) || pending.has(entryName)) return void 0;
+		const path = resolveArtifact(entryName);
+		if (path === null) return void 0;
+		const task = loadManifest(entryName, path).then((manifest) => {
+			if (!active || !qualifies(entryName) || registered.has(entryName)) return;
+			registered.set(entryName, ctx.typert.register(manifest));
+		});
+		pending.set(entryName, task);
+		const settle = () => {
+			pending.delete(entryName);
+		};
+		task.then(settle, settle);
+		return task;
+	};
+	const flush = (onError) => {
+		const tasks = [];
+		for (const entryName of [...dirty]) {
+			dirty.delete(entryName);
+			try {
+				const task = processOne(entryName);
+				if (task !== void 0) tasks.push(task.catch((error) => {
+					onError(toError(error));
+				}));
+			} catch (error) {
+				onError(toError(error));
+			}
+		}
+		return tasks;
+	};
+	ctx.on("internal/plugin", (fiber) => {
+		const entryName = fiber.entry?.options.name;
+		if (entryName === void 0) return;
+		dirty.add(entryName);
+		if (flushQueued) return;
+		flushQueued = true;
+		queueMicrotask(() => {
+			flushQueued = false;
+			if (!active) return;
+			for (const task of flush((err) => {
+				ctx.logger.error(err);
+			}));
+		});
+	});
+	for (const packageName of configured) dirty.add(packageName);
+	for (const entry of ctx.loader.entries()) dirty.add(entry.options.name);
+	const failures = [];
+	await Promise.all(flush((err) => {
+		failures.push(err);
+	}));
+	if (failures.length > 0) throw new AggregateError(failures, `typert-loader: ${String(failures.length)} typert contributor(s) failed to register:\n${failures.map((e) => `  - ${e.message}`).join("\n")}`);
+}
+/** Normalize an arbitrary import or manifest failure to an Error. */
+function toError(error) {
+	return error instanceof Error ? error : new Error(String(error));
+}
+//#endregion
+export { Config, TYPERT_HOST_EXPORT, apply, inject, name, validateTypertManifest };

package/lib/types/index.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Typert Loader integration: automatic registration for mounted plugin packages.
+ *
+ * When a loader entry mounts, this plugin resolves the entry's package.json; a
+ * package exporting `./typert` has its host face imported and its
+ * `TYPERT` manifest registered into `ctx.typert`, and the registration is
+ * withdrawn when the entry unmounts. Explicit `packages` cover plugins nested
+ * behind another Loader entry, whose Cordis fibers carry no resolvable package
+ * specifier. Packages without the export are skipped silently when discovered
+ * from Loader entries; an explicit package or declared artifact that is broken
+ * 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. 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.
+ *
+ * Manual `ctx.typert.register()` remains available for contributions
+ * that do not use a `./typert` artifact (hand-written wire schemas,
+ * tests, non-loader compositions).
+ *
+ * @module @x1a0f3n9/dsh-typert-loader
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { TypertContribution } from '@x1a0f3n9/dsh-typert-registry/types';
+/** The package.json exports key naming a package's host-face typert artifact. */
+export declare const TYPERT_HOST_EXPORT = "./typert";
+/** Cordis plugin name. */
+export declare const name = "typert-loader";
+/** Services required before registration: the registry this plugin feeds and the Loader it observes. */
+export declare const inject: string[];
+/** Additional package artifacts whose owning plugins are nested behind another Loader entry. */
+export interface Config {
+    /** Exact npm package names that must resolve and export `./typert`. */
+    packages?: string[];
+}
+/** Validate explicit package names and default to Loader-entry discovery only. */
+export declare const Config: z<Config>;
+/**
+ * Narrow a dynamically imported typert module's `TYPERT` export to a
+ * contribution owned by `pkgName`. This is the module/file boundary: the
+ * manifest crosses from a build artifact into the typed registry, so every
+ * field is checked and every failure names the package and the defect.
+ * @param pkgName - the package whose typert face was imported.
+ * @param exported - the module's `TYPERT` export.
+ * @returns the validated contribution.
+ */
+export declare function validateTypertManifest(pkgName: string, exported: unknown): TypertContribution;
+/**
+ * Scan current Loader entries during activation, then follow entry mounts and
+ * unmounts for this plugin's lifetime.
+ * @param ctx - plugin context carrying `typert` and `loader`.
+ * @param config - explicit package artifacts in addition to Loader entries.
+ */
+export declare function apply(ctx: Context, config: Config): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@x1a0f3n9/dsh-typert-loader",
+  "description": "Loader integration for generated Typert package contributions",
+  "version": "0.1.5-rc.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-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"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.3",
+    "@x1a0f3n9/dsh-typert-registry": "^0.1.5-rc.2",
+    "@deepseek-ai/cordis": "^4.0.2"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.2"
+  },
+  "devDependencies": {
+    "zod": "^4.4.3",
+    "@x1a0f3n9/dsh-typert-registry": "^0.1.5-rc.2",
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.3",
+    "@deepseek-ai/cordis": "^4.0.2"
+  }
+}