@heybox/hb-sdk-protocol 0.8.2-alpha.1 → 0.8.2-alpha.2

package/src/guards.ts

@@ -12,6 +12,76 @@ import type {
   MiniProgramPathRootRef,
 } from './payloads';
 
+/**
+ * 判断不可信输入是否具有受支持的小程序 bridge 消息结构。
+ *
+ * @param value - 从 `MessageEvent.data`、反序列化结果或其他外部边界取得的未知值。`null`、数组和非对象值会直接返回 `false`。
+ * @returns 输入满足 v1/v2 envelope 及当前 `type` 的最低结构要求时返回 `true`，并将 TypeScript 类型收窄为
+ * {@link MiniProgramBridgeMessage}；否则返回 `false`。
+ *
+ * @remarks
+ * 所有通过的消息都必须使用 {@link MINI_PROGRAM_MESSAGE_NAMESPACE}，`version` 必须为 `1` 或 `2`，
+ * `nonce` 必须为非空字符串。随后按 `type` 执行以下最低校验：
+ *
+ * - `handshake`（v1/v2）：`id` 非空，`method` 固定为 {@link SDK_HANDSHAKE_METHOD}，`error` 必须为 `undefined`；
+ *   `payload` 必须是对象，且包含非空 `href`、字符串 `userAgent` 和非空 `sdkVersion`。
+ * - `request`（v1/v2）：`id` 与 `method` 都是非空字符串，且 `error` 必须为 `undefined`；`payload` 不在此处校验。
+ * - `response`（v1/v2）：`id` 非空；`method` 可省略，提供时必须非空；`error` 可省略，提供时必须含非空
+ *   `code` 与字符串 `message`。该最低结构允许 `payload` 与合法 `error` 同时存在，终态语义由消费端决定。
+ * - 普通 `event`（v1/v2）：`method` 非空、`error` 必须为 `undefined`，`id` 可省略或为非空字符串；事件名和
+ *   `payload` 不在此处校验。
+ * - `operation.progress` 与 `cancel` 只接受 v2。progress 还要求非空 `id` 和受支持的下载或 companion
+ *   prepare 进度 payload；cancel 要求非空 `id`，且 `method`、`payload`、`error` 都必须为 `undefined`。
+ *
+ * 返回 `true` 只表示 wire envelope 可识别，不建立信任或授权边界。该函数不会校验
+ * `MessageEvent.source` / `origin`，只检查 nonce 非空而不会与当前 iframe 的预期 nonce 比较，也不会确认
+ * 握手状态、协商后的版本、请求 ID 是否重复或对应 pending request。除握手和 operation progress 外，它也不校验
+ * payload schema；不会把普通 `method` / 事件名限制在公开目录，不会检查 Manifest 权限、Runtime 权限状态、
+ * Host 支持、可信用户手势或业务策略。顶层 envelope、握手 payload 与 bridge error 中的额外字段也不会被拒绝。
+ *
+ * [MINI_PROGRAM_MESSAGE_VERSION](/reference/symbols/protocol/constants/MINI_PROGRAM_MESSAGE_VERSION)
+ * 是新消息的发送版本，不是本 guard 的唯一接收版本；接受 v1 是兼容行为，
+ * 调用方仍须在握手后确认消息版本与已协商版本一致。method 是否公开及其权限 requirement 应查询
+ * [MINI_PROGRAM_PROTOCOL_CAPABILITIES](/reference/symbols/protocol/constants/MINI_PROGRAM_PROTOCOL_CAPABILITIES)，
+ * 权限快照应先交给
+ * [parseMiniProgramRuntimePermissions](/reference/symbols/protocol/functions/parseMiniProgramRuntimePermissions) 解析。
+ *
+ * 类型谓词只收窄到宽泛的 {@link MiniProgramBridgeMessage}：`payload` 仍为 `unknown`，`method` 等字段仍保持可选。
+ * 需要精确处理 v2 cancel 或 operation progress 时，应在检查判别字段后使用
+ * [MiniProgramBridgeCancelMessage](/reference/symbols/protocol/interfaces/MiniProgramBridgeCancelMessage) 或
+ * [MiniProgramBridgeProgressMessage](/reference/symbols/protocol/interfaces/MiniProgramBridgeProgressMessage)。
+ *
+ * @example
+ * ```ts
+ * import {
+ *   MINI_PROGRAM_PROTOCOL_CAPABILITIES,
+ *   isMiniProgramBridgeMessage,
+ * } from '@heybox/hb-sdk/protocol';
+ *
+ * const publicMethods = new Set<string>(
+ *   MINI_PROGRAM_PROTOCOL_CAPABILITIES.map(({ method }) => method),
+ * );
+ *
+ * window.addEventListener('message', (event) => {
+ *   if (event.source !== iframe.contentWindow) return;
+ *   if (expectedOrigin && expectedOrigin !== '*' && event.origin !== expectedOrigin) return;
+ *   if (!isMiniProgramBridgeMessage(event.data)) return;
+ *   if (event.data.nonce !== expectedNonce) return;
+ *
+ *   if (event.data.type === 'request') {
+ *     const method = event.data.method;
+ *     if (!method || !publicMethods.has(method)) return;
+ *     // 继续检查握手状态、权限与 method 对应的 payload。
+ *   }
+ * });
+ * ```
+ *
+ * @see [MiniProgramBridgeMessage](/reference/symbols/protocol/interfaces/MiniProgramBridgeMessage) 宽泛的顶层 envelope 类型。
+ * @see [MINI_PROGRAM_MESSAGE_VERSION](/reference/symbols/protocol/constants/MINI_PROGRAM_MESSAGE_VERSION) 新消息的默认发送版本。
+ * @see [MINI_PROGRAM_BRIDGE_NONCE_PARAM](/reference/symbols/protocol/constants/MINI_PROGRAM_BRIDGE_NONCE_PARAM) iframe URL 中的 nonce 参数名。
+ * @see [MINI_PROGRAM_PROTOCOL_CAPABILITIES](/reference/symbols/protocol/constants/MINI_PROGRAM_PROTOCOL_CAPABILITIES) 公开 method 与权限 requirement 目录。
+ * @see [parseMiniProgramRuntimePermissions](/reference/symbols/protocol/functions/parseMiniProgramRuntimePermissions) Runtime 权限快照解析器。
+ */
 export function isMiniProgramBridgeMessage(value: unknown): value is MiniProgramBridgeMessage {
   if (!isRecord(value)) return false;
   if (value.namespace !== MINI_PROGRAM_MESSAGE_NAMESPACE || (value.version !== 1 && value.version !== 2) || !isNonEmptyString(value.nonce)) {
@@ -46,6 +116,60 @@ export function isMiniProgramBridgeMessage(value: unknown): value is MiniProgram
   return false;
 }
 
+/**
+ * 判断未知值是否为以 `/` 分隔的规范逻辑相对路径。
+ *
+ * @param value - 来自 files API、derived ref、Host payload 或其他不可信边界的候选路径。
+ * @returns 值是满足协议语法的字符串时返回 `true`，并将 TypeScript 类型收窄为 `string`；否则返回 `false`。
+ *
+ * @remarks
+ * 该 guard 直接检查输入字符串，规则如下：
+ *
+ * - 必须是非空字符串；空串和非字符串值失败。
+ * - 不能以 `/` 开头或结尾，因此 `/absolute`、`nested/` 与 `/` 失败。
+ * - 不能包含反斜杠 `\\`、U+0000-U+001F 控制字符或 U+007F；Windows 风格分隔符不会被转换。
+ * - 按 `/` 分段后，每段必须非空且不能精确等于 `.` 或 `..`，因此连续 `/`、`nested/./file` 与
+ *   `nested/../file` 失败。
+ *
+ * 只拒绝完整的 dot segment：`.env`、`..cache`、`file.` 与包含普通点号的名称都可通过；单独的 `'.'`
+ * 本身失败。{@link isMiniProgramDirectoryRef} 在外层显式允许 `relativePath: '.'` 表示 root 目录自身，
+ * {@link isMiniProgramFileRef} 则始终要求本 guard 通过，因此文件引用不能指向 root 自身。
+ *
+ * 该函数不 trim 空白、不 URL/percent decode、不 Unicode normalize、不折叠分隔符，也不应用平台保留名或
+ * 字符规则。空白段、`%2e%2e`、全角字符和 `C:/file` 等只要满足上述原始字符串规则就可能通过；路径长度、
+ * 段长度和段数量也没有在此限制。调用方不能把“通过”解释为操作系统级 canonical path。
+ *
+ * 返回 `true` 只证明语法可作为协议逻辑相对路径，不证明目标存在、末段是文件还是目录、root/handle 属于
+ * 当前 session/origin、`filesystem` 权限已启用、访问 mode 允许当前操作或 Host 支持该 capability。
+ * `normalizeRelativePath()` 这类 SDK/Runtime helper 只是复用本 predicate：合法时原样返回同一个字符串，非法时
+ * 转成对应 SDK/bridge 错误；它不会进一步规范化路径。
+ *
+ * @example
+ * ```ts
+ * import { isMiniProgramRelativePath } from '@heybox/hb-sdk/protocol';
+ *
+ * const paths: unknown[] = [
+ *   'data.json',
+ *   'nested/data.json',
+ *   '.env',
+ *   '.',
+ *   '../secret',
+ *   'nested//file',
+ *   'nested\\file',
+ * ];
+ *
+ * const validPaths = paths.filter(isMiniProgramRelativePath);
+ * // ['data.json', 'nested/data.json', '.env']
+ * console.log(validPaths);
+ * ```
+ *
+ * @see [isMiniProgramFileRef](/reference/symbols/protocol/functions/isMiniProgramFileRef) 始终使用本规则的 derived 文件引用。
+ * @see [isMiniProgramDirectoryRef](/reference/symbols/protocol/functions/isMiniProgramDirectoryRef) 额外允许 `'.'` 的 derived 目录引用。
+ * @see [isMiniProgramPathRootRef](/reference/symbols/protocol/functions/isMiniProgramPathRootRef) 与相对路径组合的逻辑 root guard。
+ * @see [PathRoot](/reference/symbols/root/interfaces/PathRoot) 提供 `file()` / `directory()` 的 SDK 路径入口。
+ * @see [FileSystem](/reference/symbols/root/interfaces/FileSystem) `files.sandbox` 逻辑路径能力。
+ * @see [DirectoryHandle](/reference/symbols/root/interfaces/DirectoryHandle) 已授权目录下的相对路径能力。
+ */
 export function isMiniProgramRelativePath(value: unknown): value is string {
   if (typeof value !== 'string' || !value || value.startsWith('/') || value.endsWith('/')) {
     return false;
@@ -54,12 +178,129 @@ export function isMiniProgramRelativePath(value: unknown): value is string {
   return value.split('/').every((segment) => Boolean(segment) && segment !== '.' && segment !== '..');
 }
 
+/**
+ * 判断未知值是否可作为 derived file/directory ref 的逻辑路径 root。
+ *
+ * @param value - 来自文件引用、目录引用或其他不可信 wire 边界的候选 root。
+ * @returns 值满足 sandbox root 或 direct directory root 任一结构时返回 `true`，并将 TypeScript 类型
+ * 收窄为 {@link MiniProgramPathRootRef} 判别联合；否则返回 `false`。
+ *
+ * @remarks
+ * 支持两个以 `kind` 区分的分支：
+ *
+ * - Sandbox root：`{ kind: 'sandbox' }`。对通常的对象字面量，除 `kind` 外不能携带任何字段。
+ * - Directory root：`{ kind: 'directory', handleId }`。`handleId` 必须是非空字符串；空白字符串仍满足
+ *   本 guard 的最低结构，格式、长度和归属由 Runtime 继续校验。
+ *
+ * direct file ref、derived directory ref、普通路径字符串以及其他 `kind` 都不能作为 PathRoot。特别是
+ * `{ kind: 'directory', root, relativePath }` 会因额外 canonical 外字段而失败：derived ref 只能引用 sandbox
+ * 或 direct directory root，不能递归嵌套另一层 derived root。
+ *
+ * 两个分支都会拒绝 canonical 集合之外的可枚举自有字符串键，包括值为 `undefined` 的额外键。检查基于
+ * `Object.keys()`，因此非枚举属性、symbol 键和继承属性不会被列入；必需属性本身也不要求是自有或可枚举
+ * 属性。该函数不会复制、冻结或规范化输入。
+ *
+ * 返回 `true` 只建立结构类型收窄，不证明 directory `handleId` 由当前 Runtime 签发、属于当前 session/origin、
+ * 仍然有效且确为目录，也不证明 `filesystem` 权限、目录访问 mode、provenance 或 Host capability。sandbox
+ * 标记同样不自行建立隔离边界；Runtime 必须把它解析到当前 Mini-program 的私有 root 并执行实际权限策略。
+ *
+ * {@link isMiniProgramFileRef} 与 {@link isMiniProgramDirectoryRef} 都用该 guard 校验 derived ref 的 `root`；
+ * 它只校验 root 身份，不校验各自的 `relativePath`。
+ *
+ * @example
+ * ```ts
+ * import { isMiniProgramPathRootRef } from '@heybox/hb-sdk/protocol';
+ *
+ * const candidates: unknown[] = [
+ *   { kind: 'sandbox' },
+ *   { kind: 'directory', handleId: 'directory_1' },
+ * ];
+ *
+ * for (const candidate of candidates) {
+ *   if (!isMiniProgramPathRootRef(candidate)) continue;
+ *   if (candidate.kind === 'sandbox') {
+ *     console.log('private sandbox root');
+ *   } else {
+ *     console.log('authorized directory root', candidate.handleId);
+ *   }
+ * }
+ *
+ * isMiniProgramPathRootRef({ kind: 'file', handleId: 'file_1' }); // false
+ * isMiniProgramPathRootRef({ kind: 'directory', root: { kind: 'sandbox' }, relativePath: 'nested' }); // false
+ * ```
+ *
+ * @see [MiniProgramPathRootRef](/reference/symbols/protocol/types/MiniProgramPathRootRef) sandbox/direct-directory 联合类型。
+ * @see [isMiniProgramFileRef](/reference/symbols/protocol/functions/isMiniProgramFileRef) 使用 PathRoot 的 derived 文件引用。
+ * @see [isMiniProgramDirectoryRef](/reference/symbols/protocol/functions/isMiniProgramDirectoryRef) 使用 PathRoot 的 derived 目录引用。
+ * @see [PathRoot](/reference/symbols/root/interfaces/PathRoot) SDK 公开的逻辑路径 root 能力。
+ * @see [FilesModule](/reference/symbols/root/interfaces/FilesModule) 提供 `files.sandbox` 与目录 picker 的入口。
+ * @see [DirectoryHandle](/reference/symbols/root/interfaces/DirectoryHandle) 可作为 derived path root 的目录代理。
+ */
 export function isMiniProgramPathRootRef(value: unknown): value is MiniProgramPathRootRef {
   if (!isRecord(value)) return false;
   if (value.kind === 'sandbox') return hasOnlyKeys(value, ['kind']);
   return value.kind === 'directory' && isNonEmptyString(value.handleId) && hasOnlyKeys(value, ['kind', 'handleId']);
 }
 
+/**
+ * 判断未知值是否为 direct handle 或 path-derived 文件引用。
+ *
+ * @param value - 来自 descriptor、capability payload 或其他不可信 wire 边界的候选文件引用。
+ * @returns 值满足 {@link MiniProgramFileRef} 任一分支的最低结构时返回 `true`，并将 TypeScript 类型
+ * 收窄为 direct/derived 文件引用联合；否则返回 `false`。
+ *
+ * @remarks
+ * 两个分支都要求 `kind === 'file'`，并对通常的对象字面量使用互斥的 canonical key 集合：
+ *
+ * - Direct ref：`{ kind: 'file', handleId }`。`handleId` 必须是非空字符串；不能同时携带 `root` 或
+ *   `relativePath`。
+ * - Derived ref：`{ kind: 'file', root, relativePath }`。不能携带 `handleId`；`root` 必须通过
+ *   {@link isMiniProgramPathRootRef}，即精确的 `{ kind: 'sandbox' }`，或带非空 `handleId` 的 direct
+ *   directory root。file ref 与再次嵌套的 derived directory ref 都不能作为 root。
+ *
+ * Derived ref 的 `relativePath` 必须通过 {@link isMiniProgramRelativePath}：非空、不以 `/` 开头或结尾，
+ * 不含空段、`.` / `..` 点段、反斜杠、U+0000-U+001F 控制字符或 U+007F。文件必须指向 root 下的具体路径，
+ * 因此与 {@link isMiniProgramDirectoryRef} 不同，`relativePath: '.'` 不合法。该 guard 不会 URL decode、
+ * Unicode normalize、解析平台分隔符、限制路径长度，或确认末段是文件而不是目录。
+ *
+ * direct 与 derived 分支都会拒绝 canonical 集合之外的可枚举自有字符串键，包括值为 `undefined` 的额外键。
+ * 检查基于 `Object.keys()`，因此非枚举属性、symbol 键和继承属性不会被列入；必需属性本身也不要求是自有
+ * 或可枚举属性。返回对象不会被复制、冻结或规范化。
+ *
+ * 返回 `true` 只证明当前结构可按 wire 类型读取，不证明 direct `handleId` 或 root handle 由当前 Runtime 签发、
+ * 属于当前 session/origin、仍然有效且类型匹配，也不证明目标文件存在、`filesystem` 权限已启用、访问 mode
+ * 允许当前操作或 Host 支持对应 capability。Runtime 在实际解析 ref 时仍须查询 handle registry，执行权限、
+ * provenance 与目标类型校验，并解析 derived path。
+ *
+ * @example
+ * ```ts
+ * import { isMiniProgramFileRef } from '@heybox/hb-sdk/protocol';
+ *
+ * const candidate: unknown = {
+ *   kind: 'file',
+ *   root: { kind: 'directory', handleId: 'directory_1' },
+ *   relativePath: 'screenshots/cover.png',
+ * };
+ *
+ * if (isMiniProgramFileRef(candidate)) {
+ *   if ('handleId' in candidate) {
+ *     console.log('direct', candidate.handleId);
+ *   } else {
+ *     console.log('derived', candidate.root, candidate.relativePath);
+ *   }
+ * }
+ *
+ * isMiniProgramFileRef({ kind: 'file', handleId: 'file_1' }); // true
+ * isMiniProgramFileRef({ kind: 'file', root: { kind: 'sandbox' }, relativePath: '.' }); // false
+ * ```
+ *
+ * @see [MiniProgramFileRef](/reference/symbols/protocol/types/MiniProgramFileRef) direct/derived 联合类型。
+ * @see [isMiniProgramPathRootRef](/reference/symbols/protocol/functions/isMiniProgramPathRootRef) derived ref 的 root guard。
+ * @see [isMiniProgramRelativePath](/reference/symbols/protocol/functions/isMiniProgramRelativePath) derived 文件路径规则。
+ * @see [isMiniProgramFileDescriptor](/reference/symbols/protocol/functions/isMiniProgramFileDescriptor) 包含名称和 mode 的文件 descriptor guard。
+ * @see [isMiniProgramDirectoryRef](/reference/symbols/protocol/functions/isMiniProgramDirectoryRef) 可用 `'.'` 指向 root 自身的目录引用 guard。
+ * @see [FileHandle](/reference/symbols/root/interfaces/FileHandle) 使用文件引用的公开 I/O 代理。
+ */
 export function isMiniProgramFileRef(value: unknown): value is MiniProgramFileRef {
   if (!isRecord(value) || value.kind !== 'file') return false;
   if (isNonEmptyString(value.handleId)) {
@@ -70,6 +311,65 @@ export function isMiniProgramFileRef(value: unknown): value is MiniProgramFileRe
   );
 }
 
+/**
+ * 判断未知值是否为 direct handle 或 path-derived 目录引用。
+ *
+ * @param value - 来自 descriptor、capability payload 或其他不可信 wire 边界的候选目录引用。
+ * @returns 值满足 {@link MiniProgramDirectoryRef} 任一分支的最低结构时返回 `true`，并将 TypeScript 类型
+ * 收窄为 direct/derived 目录引用联合；否则返回 `false`。
+ *
+ * @remarks
+ * 两个分支都要求 `kind === 'directory'`，并对通常的对象字面量使用互斥的 canonical key 集合：
+ *
+ * - Direct ref：`{ kind: 'directory', handleId }`。`handleId` 必须是非空字符串；不能同时携带 `root` 或
+ *   `relativePath`。
+ * - Derived ref：`{ kind: 'directory', root, relativePath }`。不能携带 `handleId`；`root` 必须通过
+ *   {@link isMiniProgramPathRootRef}，即精确的 `{ kind: 'sandbox' }`，或带非空 `handleId` 的 direct
+ *   directory root。file ref 与再次嵌套的 derived directory ref 都不能作为 root。
+ *
+ * Derived ref 的 `relativePath` 可以是 `'.'`，表示 root 目录自身；这是目录引用专属规则，普通
+ * {@link isMiniProgramRelativePath} 和 file ref 都不接受 `'.'`。其他相对路径必须非空，不以 `/` 开头或结尾，
+ * 不含空段、`.` / `..` 点段、反斜杠、U+0000-U+001F 控制字符或 U+007F。该校验不会 URL decode、
+ * Unicode normalize、解析平台分隔符、限制长度，或判断路径指向的目录是否存在。
+ *
+ * direct 与 derived 分支都会拒绝 canonical 集合之外的可枚举自有字符串键，包括值为 `undefined` 的额外键。
+ * 检查基于 `Object.keys()`，因此非枚举属性、symbol 键和继承属性不会被列入；必需属性本身也不要求是自有
+ * 或可枚举属性。返回对象不会被复制、冻结或规范化。
+ *
+ * 返回 `true` 只证明当前结构可按 wire 类型读取，不证明 direct `handleId` 或 root handle 由当前 Runtime 签发、
+ * 属于当前 session/origin、仍然有效且确为目录，也不证明目标存在、`filesystem` 权限已启用、访问模式允许
+ * 当前操作或 Host 支持对应 capability。Runtime 在实际解析 ref 时仍须查询 handle registry、执行权限与
+ * provenance 校验，并解析 derived path。
+ *
+ * @example
+ * ```ts
+ * import { isMiniProgramDirectoryRef } from '@heybox/hb-sdk/protocol';
+ *
+ * const candidate: unknown = {
+ *   kind: 'directory',
+ *   root: { kind: 'directory', handleId: 'directory_1' },
+ *   relativePath: 'screenshots/2026',
+ * };
+ *
+ * if (isMiniProgramDirectoryRef(candidate)) {
+ *   if ('handleId' in candidate) {
+ *     console.log('direct', candidate.handleId);
+ *   } else {
+ *     console.log('derived', candidate.root, candidate.relativePath);
+ *   }
+ * }
+ *
+ * isMiniProgramDirectoryRef({ kind: 'directory', root: { kind: 'sandbox' }, relativePath: '.' }); // true
+ * isMiniProgramDirectoryRef({ kind: 'directory', handleId: 'd1', relativePath: '.' }); // false：分支键混用
+ * ```
+ *
+ * @see [MiniProgramDirectoryRef](/reference/symbols/protocol/types/MiniProgramDirectoryRef) direct/derived 联合类型。
+ * @see [isMiniProgramPathRootRef](/reference/symbols/protocol/functions/isMiniProgramPathRootRef) derived ref 的 root guard。
+ * @see [isMiniProgramRelativePath](/reference/symbols/protocol/functions/isMiniProgramRelativePath) 非 `'.'` 相对路径规则。
+ * @see [isMiniProgramDirectoryDescriptor](/reference/symbols/protocol/functions/isMiniProgramDirectoryDescriptor) 包含名称和 mode 的目录 descriptor guard。
+ * @see [isMiniProgramFileRef](/reference/symbols/protocol/functions/isMiniProgramFileRef) 不接受 root 自身 `'.'` 的文件引用 guard。
+ * @see [DirectoryHandle](/reference/symbols/root/interfaces/DirectoryHandle) 使用目录引用的公开路径操作代理。
+ */
 export function isMiniProgramDirectoryRef(value: unknown): value is MiniProgramDirectoryRef {
   if (!isRecord(value) || value.kind !== 'directory') return false;
   if (isNonEmptyString(value.handleId)) {
@@ -80,6 +380,72 @@ export function isMiniProgramDirectoryRef(value: unknown): value is MiniProgramD
   );
 }
 
+/**
+ * 判断未知值是否具有文件 descriptor 的最低 wire 结构。
+ *
+ * @param value - 来自 Host、bridge response、目录列表或其他不可信边界的候选 descriptor。
+ * @returns 顶层字段及嵌套文件引用都满足协议结构时返回 `true`，并将 TypeScript 类型收窄为
+ * {@link MiniProgramFileDescriptor}；否则返回 `false`。
+ *
+ * @remarks
+ * guard 会读取并校验以下四个属性；对通常的对象字面量，它们也是唯一允许的可枚举自有字符串字段：
+ *
+ * - `kind`：固定为 `'file'`。
+ * - `name`：非空字符串。该 guard 不检查空白、`.`、`..`、`/`、反斜杠、控制字符、平台保留名或
+ *   `name` 是否等于 `ref.relativePath` 的 basename；SDK 创建 `FileHandle` 时还会执行更严格的名称校验。
+ * - `mode`：只能是 `'read'` 或 `'readwrite'`。这是 descriptor 声明值，不证明 Host 实际授予了读写权限。
+ * - `ref`：必须通过 {@link isMiniProgramFileRef}。
+ *
+ * `ref` 可以是 `{ kind: 'file', handleId }` 形式的 direct file ref，其中 `handleId` 只要求非空；也可以是
+ * `{ kind: 'file', root, relativePath }` 形式的 derived ref。derived root 只能是精确的 sandbox root 或
+ * 带非空 `handleId` 的 direct directory root，不能是 file ref 或再次派生的 directory ref；`relativePath`
+ * 必须是非空、非绝对、无尾随 `/`、无空段、`.` / `..` 点段、反斜杠或控制字符的相对路径。与目录 ref
+ * 不同，文件 ref 不接受 `relativePath: '.'`，因为它必须指向 root 下的具体文件。
+ *
+ * 顶层 descriptor、`ref` 与 `root` 的额外可枚举自有字符串键都会导致失败，包括值为 `undefined` 的额外键；
+ * 非枚举属性、symbol 键和继承属性不在 `Object.keys()` 检查范围内，必需属性本身也不要求是自有或可枚举
+ * 属性。该函数不会复制、冻结或规范化输入。
+ *
+ * 返回 `true` 只建立结构类型收窄，不证明 direct `handleId` 或 root handle 由当前 Runtime 签发、属于当前
+ * session/origin、仍然有效且确为预期类型，也不证明文件存在、名称真实、`filesystem` 权限已启用、mode
+ * 允许当前操作或 Host 支持对应 capability。实际文件操作仍须由 Runtime 查询 handle registry、执行权限、
+ * provenance、目标类型和存在性校验。
+ *
+ * {@link isMiniProgramFileSystemEntityDescriptor} 使用本 guard 与目录 descriptor guard 识别目录列表项。
+ * `files.pickFiles()` 与 `files.saveFile()` 的成功结果要求更窄的 direct file ref，而 sandbox/path API 返回的
+ * descriptor 可以使用 derived ref；本 guard 本身不会区分 descriptor 的来源。
+ *
+ * @example
+ * ```ts
+ * import { isMiniProgramFileDescriptor } from '@heybox/hb-sdk/protocol';
+ *
+ * const candidate = {
+ *   kind: 'file',
+ *   name: 'report.json',
+ *   mode: 'readwrite',
+ *   ref: {
+ *     kind: 'file',
+ *     root: { kind: 'sandbox' },
+ *     relativePath: 'exports/report.json',
+ *   },
+ * };
+ * const untrusted: unknown = candidate;
+ *
+ * if (isMiniProgramFileDescriptor(untrusted)) {
+ *   // 这里只能安全读取 wire 字段；文件 I/O 仍交给 files API/Runtime。
+ *   console.log(untrusted.name, untrusted.mode, untrusted.ref);
+ * }
+ *
+ * isMiniProgramFileDescriptor({ ...candidate, size: 1024 }); // false：顶层存在额外键
+ * ```
+ *
+ * @see [MiniProgramFileDescriptor](/reference/symbols/protocol/interfaces/MiniProgramFileDescriptor) descriptor 字段类型。
+ * @see [isMiniProgramFileRef](/reference/symbols/protocol/functions/isMiniProgramFileRef) 嵌套 direct/derived 文件引用校验。
+ * @see [isMiniProgramFileSystemEntityDescriptor](/reference/symbols/protocol/functions/isMiniProgramFileSystemEntityDescriptor) 文件与目录 descriptor 联合 guard。
+ * @see [FileHandle](/reference/symbols/root/interfaces/FileHandle) 校验后由 SDK 建立的文件代理。
+ * @see [PickFilesResult](/reference/symbols/protocol/types/PickFilesResult) picker 的 direct-ref 文件结果。
+ * @see [SaveFileResult](/reference/symbols/protocol/types/SaveFileResult) save picker 的 direct-ref 文件结果。
+ */
 export function isMiniProgramFileDescriptor(value: unknown): value is MiniProgramFileDescriptor {
   return (
     isRecord(value) &&
@@ -91,6 +457,68 @@ export function isMiniProgramFileDescriptor(value: unknown): value is MiniProgra
   );
 }
 
+/**
+ * 判断未知值是否具有目录 descriptor 的精确 wire 结构。
+ *
+ * @param value - 来自 Host、bridge response、目录列表或其他不可信边界的候选 descriptor。
+ * @returns 顶层字段及嵌套目录引用都满足协议最低结构时返回 `true`，并将 TypeScript 类型收窄为
+ * {@link MiniProgramDirectoryDescriptor}；否则返回 `false`。
+ *
+ * @remarks
+ * guard 会读取并校验以下四个属性；对通常的对象字面量，它们也是唯一允许的可枚举自有字符串字段：
+ *
+ * - `kind`：固定为 `'directory'`。
+ * - `name`：非空字符串。该 guard 不检查空白、`.`、`..`、斜杠、反斜杠、控制字符或平台文件名规则；
+ *   SDK 将 descriptor 转为 `DirectoryHandle` 时还会执行更严格的名称校验。
+ * - `mode`：只能是 `'read'` 或 `'readwrite'`；这里只识别声明值，不证明 Host 实际授予了对应访问模式。
+ * - `ref`：必须通过 {@link isMiniProgramDirectoryRef}。
+ *
+ * `ref` 可以是 `{ kind: 'directory', handleId }` 形式的直接引用，其中 `handleId` 只要求为非空字符串；
+ * 也可以是 `{ kind: 'directory', root, relativePath }` 形式的派生引用。派生引用的 `root` 只能是精确的
+ * sandbox root，或带非空 `handleId` 的直接目录 root；`relativePath` 可用 `'.'` 表示 root 自身，其他值
+ * 必须是非空、非绝对、无尾随 `/`、无空段/点段/父目录段、反斜杠或控制字符的规范相对路径。
+ *
+ * 顶层 descriptor、`ref` 与 `root` 的额外可枚举自有字符串键都会导致失败；但非枚举属性、symbol 键和
+ * 继承属性不在 `Object.keys()` 检查范围内，必需属性本身也不要求是自有或可枚举属性。该函数不会复制、
+ * 冻结或规范化对象，也不会验证 `handleId` 是否由当前 Runtime 签发、是否属于当前 session/origin、目标目录
+ * 是否存在、`name` 是否与真实目录一致，或 Manifest/Runtime 权限、Host 支持及当前操作是否允许。
+ * 返回 `true` 只建立结构类型收窄，不建立信任边界。
+ *
+ * {@link isMiniProgramFileSystemEntityDescriptor} 使用本 guard 与文件 descriptor guard 共同识别目录列表项。
+ * `files.pickDirectory()` 成功结果还要求 direct ref，而 sandbox/path 派生的目录可由 `DirectoryHandle`
+ * 的路径 API 产生；这些来源和能力差异不能仅凭本 guard 判定。
+ *
+ * @example
+ * ```ts
+ * import { isMiniProgramDirectoryDescriptor } from '@heybox/hb-sdk/protocol';
+ *
+ * const candidate = {
+ *   kind: 'directory',
+ *   name: 'screenshots',
+ *   mode: 'readwrite',
+ *   ref: {
+ *     kind: 'directory',
+ *     root: { kind: 'sandbox' },
+ *     relativePath: 'exports/screenshots',
+ *   },
+ * };
+ * const untrusted: unknown = candidate;
+ *
+ * if (isMiniProgramDirectoryDescriptor(untrusted)) {
+ *   // 这里只能安全读取已收窄的 wire 字段；实际操作仍交给 files API/Runtime。
+ *   console.log(untrusted.name, untrusted.ref);
+ * }
+ *
+ * isMiniProgramDirectoryDescriptor({ ...candidate, size: 0 }); // false：顶层存在额外键
+ * ```
+ *
+ * @see [MiniProgramDirectoryDescriptor](/reference/symbols/protocol/interfaces/MiniProgramDirectoryDescriptor) descriptor 字段类型。
+ * @see [isMiniProgramDirectoryRef](/reference/symbols/protocol/functions/isMiniProgramDirectoryRef) 嵌套 direct/derived 引用校验。
+ * @see [isMiniProgramFileSystemEntityDescriptor](/reference/symbols/protocol/functions/isMiniProgramFileSystemEntityDescriptor) 文件与目录 descriptor 联合 guard。
+ * @see [FilesModule](/reference/symbols/root/interfaces/FilesModule) `files` 公开能力入口。
+ * @see [DirectoryHandle](/reference/symbols/root/interfaces/DirectoryHandle) 校验后由 SDK 建立的目录代理。
+ * @see [PickDirectoryResult](/reference/symbols/protocol/types/PickDirectoryResult) picker 的 direct-ref 返回契约。
+ */
 export function isMiniProgramDirectoryDescriptor(value: unknown): value is MiniProgramDirectoryDescriptor {
   return (
     isRecord(value) &&
@@ -102,14 +530,179 @@ export function isMiniProgramDirectoryDescriptor(value: unknown): value is MiniP
   );
 }
 
+/**
+ * 判断未知值是否为文件或目录 descriptor。
+ *
+ * @param value - 来自 `directory.list`、Host response 或其他不可信边界的候选文件系统实体 descriptor。
+ * @returns 值通过文件或目录任一子 guard 时返回 `true`，并将 TypeScript 类型收窄为
+ * {@link MiniProgramFileSystemEntityDescriptor} 判别联合；否则返回 `false`。
+ *
+ * @remarks
+ * 该函数不维护第三套 schema，而是依次调用 {@link isMiniProgramFileDescriptor} 和
+ * {@link isMiniProgramDirectoryDescriptor}：
+ *
+ * - `kind === 'file'` 的值必须同时具有非空 `name`、`'read' | 'readwrite'` mode，以及合法 direct/derived
+ *   file ref。derived 文件路径必须指向 root 下的具体文件，不接受 `relativePath: '.'`。
+ * - `kind === 'directory'` 的值必须同时具有非空 `name`、`'read' | 'readwrite'` mode，以及合法
+ *   direct/derived directory ref。derived 目录 ref 可用 `relativePath: '.'` 表示 root 自身。
+ *
+ * 两个分支的 `kind` 互斥，因此通过后可直接用 `descriptor.kind` 判别收窄到对应类型。各分支完整继承子 guard
+ * 的键与嵌套 ref 规则：对通常的对象字面量，顶层只允许 `kind`、`name`、`mode`、`ref`，nested ref/root
+ * 也只允许其 canonical key；额外可枚举自有字符串键会导致失败。非枚举属性、symbol 键和继承属性不在
+ * `Object.keys()` 检查范围内，必需属性本身也不要求是自有或可枚举属性。
+ *
+ * 返回 `true` 只建立单个 descriptor 的结构类型收窄。该函数不会复制、冻结或规范化输入，也不会验证
+ * `name` 的完整平台规则、handle 是否由当前 Runtime 签发并属于当前 session/origin、目标实体是否存在且类型
+ * 与 `kind` 一致、mode 是否真实、`filesystem` 权限、provenance 或 Host capability。实际创建 `FileHandle` /
+ * `DirectoryHandle` 时仍须由 SDK 与 Runtime 完成这些校验。
+ *
+ * 对 {@link DirectoryListResult}，本 guard 只适合逐项验证，不验证外层值是否为稠密数组、结果数量、重复项、
+ * 子项 mode 是否继承父目录，或列表是否来自当前请求。`DirectoryHandle.list()` 调用链必须另行处理这些集合级
+ * 与请求级约束。
+ *
+ * @example
+ * ```ts
+ * import { isMiniProgramFileSystemEntityDescriptor } from '@heybox/hb-sdk/protocol';
+ *
+ * const candidates: unknown[] = [
+ *   { kind: 'file', name: 'report.json', mode: 'read', ref: { kind: 'file', handleId: 'file_1' } },
+ *   { kind: 'directory', name: 'exports', mode: 'read', ref: { kind: 'directory', handleId: 'directory_1' } },
+ * ];
+ *
+ * const descriptors = candidates.filter(isMiniProgramFileSystemEntityDescriptor);
+ * for (const descriptor of descriptors) {
+ *   if (descriptor.kind === 'file') {
+ *     console.log('file', descriptor.ref);
+ *   } else {
+ *     console.log('directory', descriptor.ref);
+ *   }
+ * }
+ * ```
+ *
+ * @see [MiniProgramFileSystemEntityDescriptor](/reference/symbols/protocol/types/MiniProgramFileSystemEntityDescriptor) file/directory 判别联合。
+ * @see [isMiniProgramFileDescriptor](/reference/symbols/protocol/functions/isMiniProgramFileDescriptor) file 分支的完整字段与边界。
+ * @see [isMiniProgramDirectoryDescriptor](/reference/symbols/protocol/functions/isMiniProgramDirectoryDescriptor) directory 分支的完整字段与边界。
+ * @see [DirectoryListResult](/reference/symbols/protocol/types/DirectoryListResult) 由 descriptor 数组组成的 wire 返回类型。
+ * @see [FileSystemEntity](/reference/symbols/root/types/FileSystemEntity) SDK 公开的 FileHandle/DirectoryHandle 联合。
+ * @see [FileHandle](/reference/symbols/root/interfaces/FileHandle) 文件 descriptor 对应的能力代理。
+ * @see [DirectoryHandle](/reference/symbols/root/interfaces/DirectoryHandle) 目录 descriptor 对应的能力代理及 `list()` 入口。
+ */
 export function isMiniProgramFileSystemEntityDescriptor(value: unknown): value is MiniProgramFileSystemEntityDescriptor {
   return isMiniProgramFileDescriptor(value) || isMiniProgramDirectoryDescriptor(value);
 }
 
+/**
+ * 判断未知值是否为使用普通 `ArrayBuffer` 存储的 `Uint8Array` 字节视图。
+ *
+ * @param value - 来自 bridge payload、Host 返回值或其他不可信边界的候选字节数据。
+ * @returns 值是当前 realm 的 `Uint8Array`（或其子类），且 `buffer` 是 `ArrayBuffer` 时返回 `true`，
+ * 并将 TypeScript 类型收窄为 `Uint8Array`；否则返回 `false`。
+ *
+ * @remarks
+ * `Uint8Array` 的每个索引元素由 JavaScript 保证为 `0` 到 `255` 的整数。本 guard 接受空视图、非零
+ * `byteOffset` 以及只覆盖底层 buffer 一部分的视图；它不要求视图覆盖整个 `ArrayBuffer`，也不限制
+ * `byteLength`、文件大小或 Companion stdio 消息大小。
+ *
+ * 普通数组无论是否稀疏、`ArrayBuffer` 本身、`DataView`、`Int8Array`、`Uint8ClampedArray` 及其他 typed array
+ * 都会被拒绝。使用 `SharedArrayBuffer` 作为 backing buffer 的 `Uint8Array` 也会被拒绝。由于判断依赖
+ * `instanceof`，由另一个 JavaScript realm 创建且未经过 structured clone 重建的 `Uint8Array` 可能无法通过；
+ * 当前 realm 的 `Uint8Array` 子类则可能通过。
+ *
+ * 该函数不会枚举键，因此挂在 `Uint8Array` 实例上的额外自有属性不会导致失败；它也不会检查 buffer
+ * 是否已 detached、数据来源是否可信、内容是否符合业务格式，或调用方是否拥有文件/Companion 权限。
+ * 返回 `true` 后仍得到原来的可变视图，而不是副本或冻结值。跨异步边界持有或交给其他消费者前，建议使用
+ * `new Uint8Array(value)` 创建只包含当前视图字节的快照。
+ *
+ * 文件 `readBytes()` 用它识别 Host 返回的
+ * [FileReadBytesResult](/reference/symbols/protocol/types/FileReadBytesResult)，`writeBytes()` 的
+ * [FileWriteBytesPayload](/reference/symbols/protocol/interfaces/FileWriteBytesPayload) `content` 也采用同一字节表示；
+ * 路径、句柄类型和访问模式由文件引用与 descriptor guards 单独校验。Companion stdio 的 stdin、stdout 和 stderr
+ * 同样传输 `Uint8Array`，但 Session ownership、controller generation、stream、sequence、framing、容量与权限
+ * 都不属于本 guard 的职责。
+ *
+ * @example
+ * ```ts
+ * import { isMiniProgramByteArray } from '@heybox/hb-sdk/protocol';
+ *
+ * const candidate: unknown = new Uint8Array([0, 128, 255]);
+ * if (!isMiniProgramByteArray(candidate)) {
+ *   throw new TypeError('需要 ArrayBuffer-backed Uint8Array');
+ * }
+ *
+ * // guard 只做结构收窄；复制后再跨异步边界使用。
+ * const snapshot = new Uint8Array(candidate);
+ *
+ * isMiniProgramByteArray([0, 128, 255]); // false：普通数组不是 wire 字节视图
+ * isMiniProgramByteArray(new DataView(new ArrayBuffer(3))); // false
+ * ```
+ *
+ * @see [FileHandle](/reference/symbols/root/interfaces/FileHandle) `readBytes()` 与 `writeBytes()` 的业务入口。
+ * @see [FileReadBytesResult](/reference/symbols/protocol/types/FileReadBytesResult) 文件二进制读取结果。
+ * @see [FileWriteBytesPayload](/reference/symbols/protocol/interfaces/FileWriteBytesPayload) 文件二进制写入 payload。
+ * @see [CompanionStdio](/reference/symbols/root/interfaces/CompanionStdio) Companion 原始字节 stdin/stdout/stderr。
+ * @see [isMiniProgramFileDescriptor](/reference/symbols/protocol/functions/isMiniProgramFileDescriptor) 文件 descriptor guard。
+ * @see [isMiniProgramDirectoryDescriptor](/reference/symbols/protocol/functions/isMiniProgramDirectoryDescriptor) 目录 descriptor guard。
+ */
 export function isMiniProgramByteArray(value: unknown): value is Uint8Array {
   return value instanceof Uint8Array && value.buffer instanceof ArrayBuffer;
 }
 
+/**
+ * 判断未知值是否具有文件元数据快照的最低 wire 结构。
+ *
+ * @param value - 来自 `file.stat` Host 返回值、bridge response 或其他不可信边界的候选元数据。
+ * @returns `kind`、`size` 与可选时间字段满足 {@link MiniProgramFileStat} 结构时返回 `true`，并将
+ * TypeScript 类型收窄为文件元数据；否则返回 `false`。
+ *
+ * @remarks
+ * 对通常的对象字面量，仅允许 `kind`、`size`、`modifiedAt`、`createdAt` 四个 canonical key：
+ *
+ * - `kind` 必须固定为 `'file'`。
+ * - `size` 必须是 `0` 到 `Number.MAX_SAFE_INTEGER` 范围内的整数。`0` 表示空文件；负数、小数、`NaN`、
+ *   `Infinity`、unsafe integer、bigint 和数字字符串都会被拒绝。文件 API 将该值解释为字节数，但本 guard
+ *   只验证数字结构，不能证明 Host 使用了正确单位。
+ * - `modifiedAt` 与 `createdAt` 相互独立且都可省略，也可显式为 `undefined`；提供时必须是非负有限 number。
+ *   与 `size` 不同，时间值不要求是整数或 safe integer，因此非负小数以及大于 `Number.MAX_SAFE_INTEGER`
+ *   但仍有限的值都可通过。
+ *
+ * 文件 API 把时间字段解释为 Unix epoch milliseconds，但该 guard 不验证值是否落在 JavaScript `Date`
+ * 可表示范围内，也不要求 `createdAt <= modifiedAt`、时间不晚于当前时刻，或两项同时存在。消费者若要排序、
+ * 格式化或比较时间，仍须按自己的业务范围继续校验。
+ *
+ * canonical 集合之外的可枚举自有字符串键会导致失败，包括值为 `undefined` 的额外键；非枚举属性、
+ * symbol 键和继承属性不在 `Object.keys()` 检查范围内，必需字段本身也不要求是自有或可枚举属性。
+ * 该函数不会复制、冻结或规范化输入，返回的仍是原始可变对象。
+ *
+ * 返回 `true` 只建立结构类型收窄，不证明该快照来自可信 Host、对应当前 `FileHandle` 或当前 request，也不证明
+ * 文件仍然存在、`size` 与磁盘内容一致、时间由文件系统提供、handle 属于当前 session/origin、`filesystem`
+ * 权限已启用或 Host 支持 `file.stat`。这些关联、权限与 I/O 错误必须由 Runtime 和 `FileHandle.stat()` 调用链处理。
+ *
+ * @example
+ * ```ts
+ * import { isMiniProgramFileStat } from '@heybox/hb-sdk/protocol';
+ *
+ * const candidate: unknown = {
+ *   kind: 'file',
+ *   size: 4096,
+ *   modifiedAt: 1_795_027_200_000,
+ * };
+ *
+ * if (isMiniProgramFileStat(candidate)) {
+ *   console.log(`${candidate.size} bytes`);
+ *   if (candidate.modifiedAt !== undefined) {
+ *     console.log(candidate.modifiedAt);
+ *   }
+ * }
+ *
+ * isMiniProgramFileStat({ kind: 'file', size: 0 }); // true：时间字段可全部省略
+ * isMiniProgramFileStat({ kind: 'file', size: 1.5 }); // false：size 必须是 safe integer
+ * ```
+ *
+ * @see [MiniProgramFileStat](/reference/symbols/protocol/interfaces/MiniProgramFileStat) bridge 使用的元数据字段类型。
+ * @see [FileStatResult](/reference/symbols/protocol/types/FileStatResult) `file.stat` 的 wire 返回类型。
+ * @see [FileStat](/reference/symbols/root/interfaces/FileStat) SDK 向业务返回的元数据快照。
+ * @see [FileHandle](/reference/symbols/root/interfaces/FileHandle) 提供 `stat()` 的当前 session 文件代理。
+ */
 export function isMiniProgramFileStat(value: unknown): value is MiniProgramFileStat {
   return (
     isRecord(value) &&
@@ -121,6 +714,58 @@ export function isMiniProgramFileStat(value: unknown): value is MiniProgramFileS
   );
 }
 
+/**
+ * 判断未知值是否为单个 `network.download` 进度 payload。
+ *
+ * @param value - 来自 operation progress 事件、Host adapter 或其他不可信边界的候选进度快照。
+ * @returns 字段组合满足 {@link DownloadProgressPayload} 的最低 wire 约束时返回 `true`，并将 TypeScript
+ * 类型收窄为下载进度 payload；否则返回 `false`。
+ *
+ * @remarks
+ * 对通常的对象字面量，仅允许 `loaded`、`total`、`lengthComputable` 三个 canonical key，并执行以下组合校验：
+ *
+ * - `loaded` 始终必需，必须是 `0` 到 `Number.MAX_SAFE_INTEGER` 范围内的整数。负数、小数、`NaN`、
+ *   `Infinity`、unsafe integer、bigint 和数字字符串都会被拒绝。
+ * - `lengthComputable` 必须是 boolean，不能使用 `0` / `1` 或其他 truthy/falsy 值代替。
+ * - `lengthComputable === false` 时，`total` 必须为 `undefined`；既可以省略该 key，也可以显式写成
+ *   `total: undefined`。此分支不对 `loaded` 应达到的最终值作推断。
+ * - `lengthComputable === true` 时，`total` 必须是非负 safe integer，且 `loaded <= total`。
+ *   `{ loaded: 0, total: 0, lengthComputable: true }` 是有效的空内容进度。
+ *
+ * canonical 集合之外的可枚举自有字符串键会导致失败；非枚举属性、symbol 键和继承属性不在
+ * `Object.keys()` 检查范围内，必需字段本身也不要求是自有或可枚举属性。该函数不会复制、冻结或
+ * 规范化输入。类型谓词只收窄到字段仍为可变、`total` 仍为可选的 {@link DownloadProgressPayload}，
+ * 不会在 TypeScript 中建立以 `lengthComputable` 为判别字段的精确联合。
+ *
+ * 单个 payload 通过不表示进度来自当前 request、使用当前 pending operation 的 ID，或由可信 Host 产生；
+ * 也不保证单位确为字节、事件按时间排序、`loaded` 相对前一事件单调、`total` 跨事件稳定、这是最终进度，
+ * 或对应字节已经原子提交到目标文件。`network.download` 的 Runtime 状态机必须另行绑定 request ID，校验
+ * 可信响应 framing、`maxBytes`、取消与终态，并过滤倒退或越界值。
+ *
+ * @example
+ * ```ts
+ * import { isMiniProgramDownloadProgressPayload } from '@heybox/hb-sdk/protocol';
+ *
+ * function renderProgress(candidate: unknown) {
+ *   if (!isMiniProgramDownloadProgressPayload(candidate)) return;
+ *
+ *   if (candidate.lengthComputable && candidate.total !== undefined) {
+ *     console.log(`${candidate.loaded}/${candidate.total}`);
+ *   } else {
+ *     console.log(`${candidate.loaded} bytes`);
+ *   }
+ * }
+ *
+ * renderProgress({ loaded: 512, total: 1024, lengthComputable: true }); // valid
+ * renderProgress({ loaded: 512, lengthComputable: false }); // valid：总长度未知
+ * renderProgress({ loaded: 5, total: 4, lengthComputable: true }); // ignored：loaded > total
+ * ```
+ *
+ * @see [DownloadProgressPayload](/reference/symbols/protocol/interfaces/DownloadProgressPayload) bridge 使用的进度字段类型。
+ * @see [DownloadProgress](/reference/symbols/root/interfaces/DownloadProgress) `onProgress` 接收的公开 SDK 进度类型。
+ * @see [network.download](/reference/sdk/network/download) 产生并消费该进度的下载能力。
+ * @see [isMiniProgramBridgeMessage](/reference/symbols/protocol/functions/isMiniProgramBridgeMessage) operation progress envelope 的最低校验。
+ */
 export function isMiniProgramDownloadProgressPayload(value: unknown): value is DownloadProgressPayload {
   if (
     !isRecord(value) ||