docs(runtime): clarify streaming import cursors and byte reads

src/lib/canvas-runtime/import-byte-reader.ts

@@ -6,13 +6,17 @@ import {fault} from '../canvas-core/values.ts';
 
 /** 会破坏整个源读取可信性的错误集合，供上层区分单记录失败与源级暂停/失败。 */
 const failures=new Set(['import_source_changed','invalid_import_byte_range','import_read_capacity','import_source_closed','import_source_read_failed','invalid_import_read_proof','import_read_proof_interpreter_unavailable']);
-/** 仅按稳定领域错误码分类，不依赖展示 message 或错误文本包含某个词。 */
+/** 只按 code 是否在固定集合分类，不校验错误对象的来源；其它码（含一般 import_aborted）不在集合内。
+ * 取消是否应优先由读取调用方看 signal；本分类器不是所有源错误/取消的通用判定器。 */
 export const isImportByteFailure=(error:unknown)=>failures.has((error as {code?:string}|undefined)?.code??'');
 
 /** Optional immutable-source port. Implementations return exactly the requested bytes. */
 /** 可选只读端口声明完整长度，必须返回所请求区间的精确字节，不能截断或换源。 */
 export type ImportByteReader={readonly byteLength:number;read(start:number,end:number,signal:AbortSignal):Promise<Uint8Array>};
-/** 校验安全整数范围，end 可截至EOF；读取前后查取消，外来 reader 结果额外复制以隔离缓冲复用。 */
+/** 校验安全整数范围，允许 end 超出 EOF 并截到 bytes.size；start 超出 EOF 则拒绝。
+ * reader 长度须等于 Blob 长度，但本函数不逐字节比较 Blob/reader，也不证明同长度源未被替换。
+ * 外来 Uint8Array 结果复制为自有缓冲，默认 Blob 路径返回此次新读缓冲；不缓存结果或做并发合并。
+ * 空范围仍会调用 reader/Blob 读取，是否优化零 I/O 由端口决定；bytes 依赖调用方已验证的 Blob 合同。 */
 export async function readImportRange(bytes:Blob,reader:ImportByteReader|undefined,start:number,end:number,signal:AbortSignal):Promise<Uint8Array<ArrayBuffer>>{
  if(signal.aborted)throw fault('import_aborted');
  if(!Number.isSafeInteger(start)||!Number.isSafeInteger(end)||start<0||end<start||start>bytes.size||reader&&reader.byteLength!==bytes.size)throw fault('invalid_import_byte_range');