来自 descriptor、capability payload 或其他不可信 wire 边界的候选文件引用。
值满足 MiniProgramFileRef 任一分支的最低结构时返回 true，并将 TypeScript 类型
收窄为 direct/derived 文件引用联合；否则返回 false。
两个分支都要求 kind === 'file'，并对通常的对象字面量使用互斥的 canonical key 集合：
{ kind: 'file', handleId }。handleId 必须是非空字符串；不能同时携带 root 或
relativePath。{ kind: 'file', root, relativePath }。不能携带 handleId；root 必须通过
isMiniProgramPathRootRef，即精确的 { kind: 'sandbox' }，或带非空 handleId 的 direct
directory root。file ref 与再次嵌套的 derived directory ref 都不能作为 root。Derived ref 的 relativePath 必须通过 isMiniProgramRelativePath：非空、不以 / 开头或结尾，
不含空段、. / .. 点段、反斜杠、U+0000-U+001F 控制字符或 U+007F。文件必须指向 root 下的具体路径，
因此与 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。
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
'.' 指向 root 自身的目录引用 guard。
判断未知值是否为 direct handle 或 path-derived 文件引用。