better-dsh 0.2.4-a → 0.2.4-b

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/src/docs/subsystems/typert.md

@@ -1,343 +0,0 @@
-# Typert remote calls
-
-English | [中文](typert.zh.md)
-
-Types shared by generated Remote artifacts, the Host Gateway, and consumer API assemblies. The [Typert Gateway Agent Note](../../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) owns the architecture and transport decisions; this page records the literal public contracts from [`dsh-typert-protocol`](../../packages/typert/protocol/src/types.ts) and [`dsh-api-gateway`](../../packages/api/gateway/src/types.ts).
-
-## Lookup and Context declarations
-
-Business-object packages extend two empty maps through declaration merging. A lookup associates one Host object type with its wire identity; a Context declaration associates one scoped Context kind with its wire identity. Generated descriptors name these keys, while runtime providers supply the live resolution behavior.
-
-```ts type-equiv
-/** Merge-extensible Host object lookup declarations. */
-interface TypertLookupMap {}
-```
-
-```ts type-equiv
-/** Merge-extensible scoped Context declarations. */
-interface TypertContextMap {}
-```
-
-The registry retains a lookup's wire declaration after its resolver unloads. SRC discovery therefore continues to classify the parameter as a lookup and fails unavailable instead of accepting the wire value as an ordinary business object.
-
-```ts type-equiv
-/** Stable wire declaration retained after a lookup provider unloads. */
-interface TypertLookupDefinition {
-  /** Merge-declared lookup key. */
-  readonly key: string
-  /** Source parameter name recognized by the SRC weak parser. */
-  readonly parameter: string
-  /** Wire field replacing the Host object parameter. */
-  readonly wire: string
-  /** Canonical Host type symbol used by strict generation. */
-  readonly hostTypeSymbol: string
-  /** Canonical wire type symbol used by strict generation. */
-  readonly wireTypeSymbol: string
-}
-```
-
-## Invocation descriptors
-
-An `InvocationDescriptor` is local reflection, not a wire message. Host and consumer builds generate corresponding descriptors; the request sends only the endpoint and named `args`. Strict codecs carry generated schemas, while SRC codecs enforce JSON-safe values without structural type recovery. Cancellation is an out-of-band carrier signal injected after business parameters and never enters `args`.
-
-```ts type-equiv
-/** Codec attached to one invocation parameter or result. */
-type TypertCodec =
-  | {
-    readonly mode: 'strict'
-    readonly typeSymbol: string
-    readonly schema: TypertSchema
-  }
-  | {
-    readonly mode: 'src-json'
-  }
-```
-
-```ts type-equiv
-/** One ordered business parameter in a Remote invocation. */
-interface InvocationParameterDescriptor {
-  /** Source-level parameter name. */
-  readonly name: string
-  /** Required key in the wire `args` object. */
-  readonly wire: string
-  /** Whether the value is JSON or requires a registered Host lookup. */
-  readonly source: 'json' | 'lookup'
-  /** Lookup key when `source` is `lookup`. */
-  readonly lookup?: string
-  /** Boundary codec for the wire representation. */
-  readonly codec: TypertCodec
-  /** Missing wire fields decode to `undefined` only for an explicitly declared `T | undefined`. */
-  readonly acceptsUndefined?: true
-}
-```
-
-```ts type-equiv
-/** Carrier-independent description of one exported method invocation. */
-interface InvocationDescriptor {
-  /** Globally stable generated identity. */
-  readonly id: string
-  /** Cordis service key owning the method. */
-  readonly service: string
-  /** Wire namespace, defaulting to the service key. */
-  readonly namespace: string
-  /** Public instance method name. */
-  readonly method: string
-  /** Service member invoked when the exported method name is an alias. */
-  readonly implementation?: string
-  /** Absent for unary calls; stream calls validate and deliver every yielded item. */
-  readonly mode?: 'stream'
-  /** Receiver selection mode. */
-  readonly invocation:
-    | { readonly kind: 'direct' }
-    | {
-      readonly kind: 'context'
-      readonly context: string
-      readonly wire: string
-      readonly codec: TypertCodec
-    }
-  /** Optional consuming-Context projection for one direct lookup parameter. */
-  readonly scope?: {
-    /** Context kind whose Client adapter supplies the identity. */
-    readonly context: string
-    /** Lookup parameter wire field replaced by the Context identity. */
-    readonly wire: string
-  }
-  /** Ordered business parameters. */
-  readonly parameters: readonly InvocationParameterDescriptor[]
-  /** Transport cancellation injected after business parameters instead of entering wire args. */
-  readonly cancellation?: {
-    /** Reserved final Host method parameter. */
-    readonly parameter: 'signal'
-  }
-  /** Codec for the unary result or each yielded stream item. */
-  readonly result: TypertCodec
-  /** Source declaration used only for diagnostics. */
-  readonly sourceLocation?: InvocationSourceLocation
-}
-```
-
-## Typert registry
-
-`ctx.typert` separates current-environment descriptors, explicitly selected Remote contributions, lookup providers, and scoped Context providers. A lookup provider owns the stable wire declaration and default resolver; Host composition can configure an effect-scoped synchronous or asynchronous resolver for the same key, and unloading that configuration restores the default policy. Registrations are Cordis-owned effects and return awaitable disposers.
-
-```ts type-equiv
-/** Minimal Typert runtime consumed through dependency inversion. */
-interface TypertRegistryContract {
-  readonly local: TypertLocalRegistry
-  readonly remotes: TypertRemoteRegistry
-  readonly lookups: TypertLookupRegistry
-  readonly contexts: TypertContextRegistry
-}
-```
-
-Generated consumer declarations merge direct namespaces into the map inherited by `TypertClientRemote`.
-
-```ts type-equiv
-/** Merge-extensible direct namespace surface generated for Client Remote services. */
-interface TypertRemoteNamespaceMap {}
-```
-
-## Host Gateway
-
-Connection decodes its carrier envelope before calling `ctx.typertGateway`. The request carries exact named wire fields and the carrier's cancellation signal separately; infrastructure and boundary failures ride `TypertGatewayError`, whose `gateway/*` codes are ordinary `RemoteError` codes, so the RPC adapter passes every structurally identified `RemoteError` through with its code and details intact and folds only unrecognized exceptions into `gateway/internal`.
-
-```ts type-equiv
-/** One Remote method request after a carrier has decoded its envelope. */
-interface InvokeRemoteRequest {
-  /** Remote namespace selected by the generated descriptor. */
-  readonly namespace: string
-  /** Exported Service method name. */
-  readonly method: string
-  /** Named wire values; fields must exactly match the descriptor. */
-  readonly args: Readonly<Record<string, unknown>>
-  /** Carrier or direct-caller cancellation injected only into cancellation-aware methods. */
-  readonly signal?: AbortSignal
-}
-```
-
-```ts type-equiv
-/** Stable infrastructure and boundary failures emitted before or after business execution. */
-type TypertGatewayErrorCode =
-  | 'gateway/ambiguous-endpoint'
-  | 'gateway/arguments-invalid'
-  | 'gateway/binding-invalid'
-  | 'gateway/context-failed'
-  | 'gateway/context-not-found'
-  | 'gateway/context-unavailable'
-  | 'gateway/definition-unavailable'
-  | 'gateway/input-invalid'
-  | 'gateway/invocation-unavailable'
-  | 'gateway/lookup-failed'
-  | 'gateway/lookup-not-found'
-  | 'gateway/lookup-unavailable'
-  | 'gateway/method-unavailable'
-  | 'gateway/provider-mismatch'
-  | 'gateway/result-invalid'
-  | 'gateway/service-unavailable'
-  | 'gateway/signature-invalid'
-```
-
-```ts type-equiv
-/** Host dispatcher consumed by Connection adapters. */
-interface TypertGateway {
-  /** Carrier adapter shared by WebSocket and in-process transports. */
-  readonly wireStream: TypertGatewayWireStream
-  /**
-   * Register the application-selected forwarded-event source.
-   * @param source - stream factory installed by the Remote assembly.
-   * @param host - stable Host facts included in each Client generation's opening frame.
-   * @returns disposer removing this exact source and cancelling its active streams.
-   */
-  registerRemoteEvents(
-    source: TypertRemoteEventSource,
-    host: RemoteEventHostInfo,
-  ): () => Promise<void>
-  /**
-   * Invoke one live Remote method without assuming a carrier or response envelope.
-   * @param request - decoded endpoint and named wire arguments.
-   * @returns the business result without output decoding.
-   * @throws {@link TypertGatewayError} for dispatch, provider, or boundary failures; lookup-policy and business errors retain identity.
-   */
-  invoke(request: InvokeRemoteRequest): Promise<unknown>
-  /**
-   * Open one live stream Remote method without assuming a physical carrier.
-   * @param request - decoded endpoint and named wire arguments.
-   * @returns a cancellation-aware iterable over the business results.
-   */
-  stream(request: InvokeRemoteRequest): Promise<AsyncIterable<unknown>>
-}
-```
-
-## Consumer Remote
-
-`ctx.remote` exposes only namespaces contributed by imported `/remote` artifacts. `$mount()` installs generated descriptors and concrete methods as one fiber-owned operation. Each namespace is a traced `remote.<namespace>` Cordis child Service whose lifetime spans its mounted methods; no JavaScript Proxy or Host business Service type enters the consumer.
-
-```ts type-equiv
-/** Client Remote capability implemented by the Gateway and consumed by Remote assemblies. */
-interface TypertClientRemote extends TypertRemoteNamespaceMap {
-  /**
-   * Mount one generated Host-for-Client contribution in the caller's fiber.
-   * @param contribution - explicitly selected Remote package artifact.
-   * @returns disposer after namespace services and concrete methods are ready.
-   */
-  $mount(contribution: TypertRemoteContribution): Promise<TypertDisposer>
-  /**
-   * Subscribe to one forwarded Host event. Notifications run in registration
-   * order and isolate failures; scoped waterfalls return, delegate through
-   * `next()`, or reject the Host dispatch.
-   * @template Event - forwarded event name selected by the Host assembly.
-   * @param event - forwarded Host event name, unchanged on the wire.
-   * @param listener - receives the Client projection of the Cordis `Events` declaration.
-   * @returns disposer owned by the calling fiber.
-   */
-  $on<Event extends TypertRemoteEvent>(event: Event, listener: TypertClientEventListener<Event>): () => void
-}
-```
-
-<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
-
-<a id="cordis-surface"></a>
-
-## Cordis API
-
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
-
-<a id="ctxtypert--typertregistry"></a>
-
-### `ctx.typert` — `TypertRegistry`
-
-Registry of generated schemas, package reflection, invocations, and Remote dependency providers.
-
-```ts cordis-catalog
-/**
- * Register one generated contribution atomically for the calling fiber.
- * Duplicate package-face identities, schemas, invocation ids, or endpoints
- * reject the whole batch.
- * @param contribution - generated schemas, reflection, and Host invocations.
- * @returns the exact effect disposer that removes this contribution.
- */
-register(contribution: TypertContribution): TypertDisposer
-
-/**
- * Look up one schema by `<package>#<name>`.
- * @param key - global schema key.
- * @returns the live schema record, or `undefined` when absent.
- */
-get(key: string): TypertSchemaRecord | undefined
-
-/**
- * Resolve one required schema.
- * @param key - global schema key.
- * @returns the live schema record.
- * @throws when the key is malformed, the package face is absent, or the schema is not contributed.
- */
-resolve(key: string): TypertSchemaRecord
-
-/**
- * Enumerate live schemas in registration order.
- * @param filter - optional package and face restriction.
- * @returns matching schema records.
- */
-list(filter: TypertSchemaFilter = {}): TypertSchemaRecord[]
-
-/**
- * Look up generated reflection for one package face.
- * @param packageName - exact npm package name.
- * @param face - face to query; defaults to the host runtime.
- * @returns the live package record, or `undefined` when absent.
- */
-getPackage(packageName: string, face: TypertFace = 'host'): TypertPackageRecord | undefined
-
-/**
- * Enumerate generated package reflection in registration order.
- * @param filter - optional package and face restriction.
- * @returns matching package records.
- */
-listPackages(filter: TypertPackageFilter = {}): TypertPackageRecord[]
-
-/**
- * Project a live Zod schema to JSON Schema without caching the result.
- * @param key - global schema key.
- * @param params - Zod projection parameters.
- * @returns a fresh JSON Schema document.
- */
-toJSONSchema(key: string, params?: z.core.ToJSONSchemaParams): z.core.JSONSchema.BaseSchema
-```
-
-Types: [TypertContribution](invariants.md) · [TypertFace](invariants.md) · [TypertPackageFilter](invariants.md) · [TypertPackageRecord](invariants.md) · [TypertSchemaFilter](invariants.md) · [TypertSchemaRecord](invariants.md)
-
-Source: [`packages/typert/registry/src/service.ts`](../../packages/typert/registry/src/service.ts)
-
-<a id="ctxtypertgateway--typertgatewayservice"></a>
-
-### `ctx.typertGateway` — `TypertGatewayService`
-
-Resolve strict generated definitions or conservative SRC markers against current Cordis Services and Typert providers.
-
-```ts cordis-catalog
-/**
- * Register the sole application-selected forwarded-event source.
- * @param source - stream factory installed by the Remote assembly.
- * @param host - stable Host facts included in each Client generation's opening frame.
- * @returns disposer removing this source and cancelling its active streams.
- */
-registerRemoteEvents( source: TypertRemoteEventSource, host: RemoteEventHostInfo, ): () => Promise<void>
-
-/**
- * Invoke one live Remote method through strict generated reflection or SRC markers.
- * @param request - decoded endpoint and exact named wire arguments.
- * @returns the business result without output decoding.
- * @throws {@link TypertGatewayError} for dispatch, provider, or boundary failures; lookup-policy and business errors retain identity.
- */
-async invoke(request: InvokeRemoteRequest): Promise<unknown>
-
-/**
- * Open one live stream Remote method without assuming a physical carrier.
- * @param request - decoded endpoint and named wire arguments.
- * @returns a cancellation-aware iterable over the business results.
- */
-async stream(request: InvokeRemoteRequest): Promise<AsyncIterable<unknown>>
-```
-
-Source: [`packages/api/gateway/src/index.ts`](../../packages/api/gateway/src/index.ts)
-<!-- END GENERATED cordis-surface -->

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/src/docs/subsystems/typert.zh.md

@@ -1,343 +0,0 @@
-# Typert 远程调用
-
-[English](typert.md) | 中文
-
-以下类型由生成的 Remote 产物、Host Gateway 与消费方 API assembly 共用。[Typert Gateway Agent Note](../../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md) 负责架构与传输决策；本页记录 [`dsh-typert-protocol`](../../packages/typert/protocol/src/types.ts) 和 [`dsh-api-gateway`](../../packages/api/gateway/src/types.ts) 中公共约定的字面定义。
-
-## Lookup 与上下文声明
-
-业务对象包通过声明合并扩展两个空 map。lookup 将一种 Host 对象类型与其 wire identity 关联；上下文声明将一种作用域上下文类别与其 wire identity 关联。生成的 descriptor 引用这些 key，运行时提供方则提供活对象解析行为。
-
-```ts type-equiv
-/** Merge-extensible Host object lookup declarations. */
-interface TypertLookupMap {}
-```
-
-```ts type-equiv
-/** Merge-extensible scoped Context declarations. */
-interface TypertContextMap {}
-```
-
-lookup 的 resolver 卸载后，注册表仍会保留其 wire 声明。因此 SRC 发现过程会继续把该参数归类为 lookup，并因不可用而失败，而不会把 wire 值当作普通业务对象接受。
-
-```ts type-equiv
-/** Stable wire declaration retained after a lookup provider unloads. */
-interface TypertLookupDefinition {
-  /** Merge-declared lookup key. */
-  readonly key: string
-  /** Source parameter name recognized by the SRC weak parser. */
-  readonly parameter: string
-  /** Wire field replacing the Host object parameter. */
-  readonly wire: string
-  /** Canonical Host type symbol used by strict generation. */
-  readonly hostTypeSymbol: string
-  /** Canonical wire type symbol used by strict generation. */
-  readonly wireTypeSymbol: string
-}
-```
-
-## 调用 descriptor
-
-`InvocationDescriptor` 是本地反射信息，不是 wire message。Host 与消费方构建会生成彼此对应的 descriptor；请求只发送 endpoint 与具名 `args`。strict codec 携带生成的 schema，SRC codec 则在不恢复结构类型的前提下强制要求 JSON 安全值。取消通过带外 carrier signal 表达：它在业务参数之后注入，绝不进入 `args`。
-
-```ts type-equiv
-/** Codec attached to one invocation parameter or result. */
-type TypertCodec =
-  | {
-    readonly mode: 'strict'
-    readonly typeSymbol: string
-    readonly schema: TypertSchema
-  }
-  | {
-    readonly mode: 'src-json'
-  }
-```
-
-```ts type-equiv
-/** One ordered business parameter in a Remote invocation. */
-interface InvocationParameterDescriptor {
-  /** Source-level parameter name. */
-  readonly name: string
-  /** Required key in the wire `args` object. */
-  readonly wire: string
-  /** Whether the value is JSON or requires a registered Host lookup. */
-  readonly source: 'json' | 'lookup'
-  /** Lookup key when `source` is `lookup`. */
-  readonly lookup?: string
-  /** Boundary codec for the wire representation. */
-  readonly codec: TypertCodec
-  /** Missing wire fields decode to `undefined` only for an explicitly declared `T | undefined`. */
-  readonly acceptsUndefined?: true
-}
-```
-
-```ts type-equiv
-/** Carrier-independent description of one exported method invocation. */
-interface InvocationDescriptor {
-  /** Globally stable generated identity. */
-  readonly id: string
-  /** Cordis service key owning the method. */
-  readonly service: string
-  /** Wire namespace, defaulting to the service key. */
-  readonly namespace: string
-  /** Public instance method name. */
-  readonly method: string
-  /** Service member invoked when the exported method name is an alias. */
-  readonly implementation?: string
-  /** Absent for unary calls; stream calls validate and deliver every yielded item. */
-  readonly mode?: 'stream'
-  /** Receiver selection mode. */
-  readonly invocation:
-    | { readonly kind: 'direct' }
-    | {
-      readonly kind: 'context'
-      readonly context: string
-      readonly wire: string
-      readonly codec: TypertCodec
-    }
-  /** Optional consuming-Context projection for one direct lookup parameter. */
-  readonly scope?: {
-    /** Context kind whose Client adapter supplies the identity. */
-    readonly context: string
-    /** Lookup parameter wire field replaced by the Context identity. */
-    readonly wire: string
-  }
-  /** Ordered business parameters. */
-  readonly parameters: readonly InvocationParameterDescriptor[]
-  /** Transport cancellation injected after business parameters instead of entering wire args. */
-  readonly cancellation?: {
-    /** Reserved final Host method parameter. */
-    readonly parameter: 'signal'
-  }
-  /** Codec for the unary result or each yielded stream item. */
-  readonly result: TypertCodec
-  /** Source declaration used only for diagnostics. */
-  readonly sourceLocation?: InvocationSourceLocation
-}
-```
-
-## Typert 注册表
-
-`ctx.typert` 分开保存当前环境的 descriptor、显式选择的 Remote contribution、lookup 提供方与作用域上下文提供方。lookup 提供方拥有稳定 wire 声明和默认 resolver；Host 组合可以为同一个 key 配置 effect-scoped 同步或异步 resolver，配置卸载后恢复默认策略。各项注册都是由 Cordis 持有的 effect，并返回可等待的 disposer。
-
-```ts type-equiv
-/** Minimal Typert runtime consumed through dependency inversion. */
-interface TypertRegistryContract {
-  readonly local: TypertLocalRegistry
-  readonly remotes: TypertRemoteRegistry
-  readonly lookups: TypertLookupRegistry
-  readonly contexts: TypertContextRegistry
-}
-```
-
-生成的消费方声明会把 direct namespace 合并到 `TypertClientRemote` 继承的 map 中。
-
-```ts type-equiv
-/** Merge-extensible direct namespace surface generated for Client Remote services. */
-interface TypertRemoteNamespaceMap {}
-```
-
-## Host Gateway
-
-Connection 会先解码 carrier envelope，再调用 `ctx.typertGateway`。请求将精确的具名 wire 字段与 carrier 的取消 signal 分开携带；基础设施与边界失败由 `TypertGatewayError` 承载，其 `gateway/*` 码就是普通的 `RemoteError` 码，因此 RPC 适配器会把每个经结构识别的 `RemoteError` 连同其 code 与 details 原样放行，只把无法识别的异常归并为 `gateway/internal`。
-
-```ts type-equiv
-/** One Remote method request after a carrier has decoded its envelope. */
-interface InvokeRemoteRequest {
-  /** Remote namespace selected by the generated descriptor. */
-  readonly namespace: string
-  /** Exported Service method name. */
-  readonly method: string
-  /** Named wire values; fields must exactly match the descriptor. */
-  readonly args: Readonly<Record<string, unknown>>
-  /** Carrier or direct-caller cancellation injected only into cancellation-aware methods. */
-  readonly signal?: AbortSignal
-}
-```
-
-```ts type-equiv
-/** Stable infrastructure and boundary failures emitted before or after business execution. */
-type TypertGatewayErrorCode =
-  | 'gateway/ambiguous-endpoint'
-  | 'gateway/arguments-invalid'
-  | 'gateway/binding-invalid'
-  | 'gateway/context-failed'
-  | 'gateway/context-not-found'
-  | 'gateway/context-unavailable'
-  | 'gateway/definition-unavailable'
-  | 'gateway/input-invalid'
-  | 'gateway/invocation-unavailable'
-  | 'gateway/lookup-failed'
-  | 'gateway/lookup-not-found'
-  | 'gateway/lookup-unavailable'
-  | 'gateway/method-unavailable'
-  | 'gateway/provider-mismatch'
-  | 'gateway/result-invalid'
-  | 'gateway/service-unavailable'
-  | 'gateway/signature-invalid'
-```
-
-```ts type-equiv
-/** Host dispatcher consumed by Connection adapters. */
-interface TypertGateway {
-  /** Carrier adapter shared by WebSocket and in-process transports. */
-  readonly wireStream: TypertGatewayWireStream
-  /**
-   * Register the application-selected forwarded-event source.
-   * @param source - stream factory installed by the Remote assembly.
-   * @param host - stable Host facts included in each Client generation's opening frame.
-   * @returns disposer removing this exact source and cancelling its active streams.
-   */
-  registerRemoteEvents(
-    source: TypertRemoteEventSource,
-    host: RemoteEventHostInfo,
-  ): () => Promise<void>
-  /**
-   * Invoke one live Remote method without assuming a carrier or response envelope.
-   * @param request - decoded endpoint and named wire arguments.
-   * @returns the business result without output decoding.
-   * @throws {@link TypertGatewayError} for dispatch, provider, or boundary failures; lookup-policy and business errors retain identity.
-   */
-  invoke(request: InvokeRemoteRequest): Promise<unknown>
-  /**
-   * Open one live stream Remote method without assuming a physical carrier.
-   * @param request - decoded endpoint and named wire arguments.
-   * @returns a cancellation-aware iterable over the business results.
-   */
-  stream(request: InvokeRemoteRequest): Promise<AsyncIterable<unknown>>
-}
-```
-
-## 消费方 Remote
-
-`ctx.remote` 只暴露由已导入 `/remote` 产物贡献的 namespace。`$mount()` 会把生成的 descriptor 与具体方法作为一项由 fiber 持有的操作统一注册。每个 namespace 都是可追踪的 `remote.<namespace>` Cordis 子服务，其生命周期覆盖已挂载的方法；JavaScript Proxy 与 Host 业务服务类型都不会进入消费方。
-
-```ts type-equiv
-/** Client Remote capability implemented by the Gateway and consumed by Remote assemblies. */
-interface TypertClientRemote extends TypertRemoteNamespaceMap {
-  /**
-   * Mount one generated Host-for-Client contribution in the caller's fiber.
-   * @param contribution - explicitly selected Remote package artifact.
-   * @returns disposer after namespace services and concrete methods are ready.
-   */
-  $mount(contribution: TypertRemoteContribution): Promise<TypertDisposer>
-  /**
-   * Subscribe to one forwarded Host event. Notifications run in registration
-   * order and isolate failures; scoped waterfalls return, delegate through
-   * `next()`, or reject the Host dispatch.
-   * @template Event - forwarded event name selected by the Host assembly.
-   * @param event - forwarded Host event name, unchanged on the wire.
-   * @param listener - receives the Client projection of the Cordis `Events` declaration.
-   * @returns disposer owned by the calling fiber.
-   */
-  $on<Event extends TypertRemoteEvent>(event: Event, listener: TypertClientEventListener<Event>): () => void
-}
-```
-
-<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
-
-<a id="cordis-surface"></a>
-
-## Cordis API
-
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.zh.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
-
-<a id="ctxtypert--typertregistry"></a>
-
-### `ctx.typert` — `TypertRegistry`
-
-Registry of generated schemas, package reflection, invocations, and Remote dependency providers.
-
-```ts cordis-catalog
-/**
- * Register one generated contribution atomically for the calling fiber.
- * Duplicate package-face identities, schemas, invocation ids, or endpoints
- * reject the whole batch.
- * @param contribution - generated schemas, reflection, and Host invocations.
- * @returns the exact effect disposer that removes this contribution.
- */
-register(contribution: TypertContribution): TypertDisposer
-
-/**
- * Look up one schema by `<package>#<name>`.
- * @param key - global schema key.
- * @returns the live schema record, or `undefined` when absent.
- */
-get(key: string): TypertSchemaRecord | undefined
-
-/**
- * Resolve one required schema.
- * @param key - global schema key.
- * @returns the live schema record.
- * @throws when the key is malformed, the package face is absent, or the schema is not contributed.
- */
-resolve(key: string): TypertSchemaRecord
-
-/**
- * Enumerate live schemas in registration order.
- * @param filter - optional package and face restriction.
- * @returns matching schema records.
- */
-list(filter: TypertSchemaFilter = {}): TypertSchemaRecord[]
-
-/**
- * Look up generated reflection for one package face.
- * @param packageName - exact npm package name.
- * @param face - face to query; defaults to the host runtime.
- * @returns the live package record, or `undefined` when absent.
- */
-getPackage(packageName: string, face: TypertFace = 'host'): TypertPackageRecord | undefined
-
-/**
- * Enumerate generated package reflection in registration order.
- * @param filter - optional package and face restriction.
- * @returns matching package records.
- */
-listPackages(filter: TypertPackageFilter = {}): TypertPackageRecord[]
-
-/**
- * Project a live Zod schema to JSON Schema without caching the result.
- * @param key - global schema key.
- * @param params - Zod projection parameters.
- * @returns a fresh JSON Schema document.
- */
-toJSONSchema(key: string, params?: z.core.ToJSONSchemaParams): z.core.JSONSchema.BaseSchema
-```
-
-Types: [TypertContribution](invariants.zh.md) · [TypertFace](invariants.zh.md) · [TypertPackageFilter](invariants.zh.md) · [TypertPackageRecord](invariants.zh.md) · [TypertSchemaFilter](invariants.zh.md) · [TypertSchemaRecord](invariants.zh.md)
-
-Source: [`packages/typert/registry/src/service.ts`](../../packages/typert/registry/src/service.ts)
-
-<a id="ctxtypertgateway--typertgatewayservice"></a>
-
-### `ctx.typertGateway` — `TypertGatewayService`
-
-Resolve strict generated definitions or conservative SRC markers against current Cordis Services and Typert providers.
-
-```ts cordis-catalog
-/**
- * Register the sole application-selected forwarded-event source.
- * @param source - stream factory installed by the Remote assembly.
- * @param host - stable Host facts included in each Client generation's opening frame.
- * @returns disposer removing this source and cancelling its active streams.
- */
-registerRemoteEvents( source: TypertRemoteEventSource, host: RemoteEventHostInfo, ): () => Promise<void>
-
-/**
- * Invoke one live Remote method through strict generated reflection or SRC markers.
- * @param request - decoded endpoint and exact named wire arguments.
- * @returns the business result without output decoding.
- * @throws {@link TypertGatewayError} for dispatch, provider, or boundary failures; lookup-policy and business errors retain identity.
- */
-async invoke(request: InvokeRemoteRequest): Promise<unknown>
-
-/**
- * Open one live stream Remote method without assuming a physical carrier.
- * @param request - decoded endpoint and named wire arguments.
- * @returns a cancellation-aware iterable over the business results.
- */
-async stream(request: InvokeRemoteRequest): Promise<AsyncIterable<unknown>>
-```
-
-Source: [`packages/api/gateway/src/index.ts`](../../packages/api/gateway/src/index.ts)
-<!-- END GENERATED cordis-surface -->