docs: regenerate catalogs and document the mock uplink handle

docs/config-catalog.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 docs/config-catalog.md
-config-catalog.md: f8ccc54835146648f8c090e274bfa27af88471e8
-config-catalog.zh.md: 76e5c6f81fa6bebad3502530a921d3a0d224a0f6
+config-catalog.md: 2927b510976631695978f46ed3c012641b4d73a9
+config-catalog.zh.md: 6d57dbe759fee5eaea9e755731fcf22666e8f0f3

docs/config-catalog.md

@@ -199,7 +199,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/api/gateway/src/index.ts:141`](../packages/api/gateway/src/index.ts)
+Source: [`packages/api/gateway/src/index.ts:140`](../packages/api/gateway/src/index.ts)
 
 <a id="deepseek-aidsh-api-session-controller"></a>
 
@@ -430,7 +430,7 @@ export interface ConnectionRecoveryConfig {
 }
 ```
 
-Source: [`packages/client/connection/src/index.ts:91`](../packages/client/connection/src/index.ts)
+Source: [`packages/client/connection/src/index.ts:90`](../packages/client/connection/src/index.ts)
 
 <a id="deepseek-aidsh-client-hmr"></a>
 

docs/config-catalog.zh.md

@@ -201,7 +201,7 @@ export interface Config {
 }
 ```
 
-来源：[`packages/api/gateway/src/index.ts:141`](../packages/api/gateway/src/index.ts)
+来源：[`packages/api/gateway/src/index.ts:140`](../packages/api/gateway/src/index.ts)
 
 <a id="deepseek-aidsh-api-session-controller"></a>
 
@@ -432,7 +432,7 @@ export interface ConnectionRecoveryConfig {
 }
 ```
 
-来源： [`packages/client/connection/src/index.ts:91`](../packages/client/connection/src/index.ts)
+来源： [`packages/client/connection/src/index.ts:90`](../packages/client/connection/src/index.ts)
 
 <a id="deepseek-aidsh-client-hmr"></a>
 

docs/event-producer-consumer.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 docs/event-producer-consumer.md
-event-producer-consumer.md: a0bf6543c2d97c68d85eaafd94f0049660ab34a9
-event-producer-consumer.zh.md: bde5a953db35254c30254efe0f5f5209fc12870b
+event-producer-consumer.md: 619103ab6f813fc9ea915cc4f6bf5b6ae585f8cb
+event-producer-consumer.zh.md: 00a13ca2aa785dd253263f154627e6dd8accacc6

docs/event-producer-consumer.md

@@ -30,7 +30,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `authorization/settled` | `emit` | [`packages/credentials/authorization/src/index.ts:57`](../packages/credentials/authorization/src/index.ts) | [`authorization`](../packages/credentials/authorization) (`events.dispatch`) | [`authorization`](../packages/credentials/authorization) |
 | `commands/change` | `emit` | [`packages/interaction/commands/src/types.ts:89`](../packages/interaction/commands/src/types.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `remotes` |
 | `compaction/summary-error` | `waterfall` | [`packages/compaction/compaction/src/index.ts:106`](../packages/compaction/compaction/src/index.ts) | [`compaction-basic`](../packages/compaction/compaction-basic) (`waterfall`) | [`compaction-image-offload`](../packages/compaction/compaction-image-offload) |
-| `connection/request` | `waterfall` | [`packages/client/connection/src/index.ts:66`](../packages/client/connection/src/index.ts) | `connection` (`waterfall`) | - |
+| `connection/request` | `waterfall` | [`packages/client/connection/src/index.ts:65`](../packages/client/connection/src/index.ts) | `connection` (`waterfall`) | - |
 | `cordis/dynamic-package` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:380`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` |
 | `cordis/dynamic-retract` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:386`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` |
 | `cordis/inspect-query` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:392`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` |

docs/event-producer-consumer.zh.md

@@ -32,7 +32,7 @@
 | `authorization/settled` | `emit` | [`packages/credentials/authorization/src/index.ts:57`](../packages/credentials/authorization/src/index.ts) | [`authorization`](../packages/credentials/authorization) (`events.dispatch`) | [`authorization`](../packages/credentials/authorization) |
 | `commands/change` | `emit` | [`packages/interaction/commands/src/types.ts:89`](../packages/interaction/commands/src/types.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `remotes` |
 | `compaction/summary-error` | `waterfall` | [`packages/compaction/compaction/src/index.ts:106`](../packages/compaction/compaction/src/index.ts) | [`compaction-basic`](../packages/compaction/compaction-basic) (`waterfall`) | [`compaction-image-offload`](../packages/compaction/compaction-image-offload) |
-| `connection/request` | `waterfall` | [`packages/client/connection/src/index.ts:66`](../packages/client/connection/src/index.ts) | `connection` (`waterfall`) | - |
+| `connection/request` | `waterfall` | [`packages/client/connection/src/index.ts:65`](../packages/client/connection/src/index.ts) | `connection` (`waterfall`) | - |
 | `cordis/dynamic-package` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:380`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` |
 | `cordis/dynamic-retract` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:386`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` |
 | `cordis/inspect-query` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:392`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` |

packages/test-support/remote-mock/src/streams.ts

@@ -245,6 +245,11 @@ export class HandleUplink implements AsyncIterable<unknown> {
   private done = false
   private waiter: ((result: IteratorResult<unknown>) => void) | undefined
 
+  /**
+   * Queues one uplink item for the script, or completes the read waiting for it.
+   * @param item - the item the handle's `send()` carried.
+   * @throws {Error} after `end()`.
+   */
   push(item: unknown): void {
     if (this.done) throw new Error('remote-mock: uplink was ended')
     const waiter = this.waiter
@@ -253,6 +258,7 @@ export class HandleUplink implements AsyncIterable<unknown> {
     else waiter({ value: item, done: false })
   }
 
+  /** Half-closes the uplink: pending and later reads complete as done; repeated calls are no-ops. */
   end(): void {
     if (this.done) return
     this.done = true
@@ -260,6 +266,7 @@ export class HandleUplink implements AsyncIterable<unknown> {
     this.waiter = undefined
   }
 
+  /** Ends the uplink and drops its unread items; `dispose()` on the handle and `return()` on the script's iterator call it. */
   close(): void {
     this.items.length = 0
     this.end()