docs(canvas): explain import parsers, identities and integrity gates

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

@@ -1,17 +1,27 @@
+/**
+ * 解析器的统一精确字节读取边界。默认读不可变 Blob，也可注入带块证明的 reader。
+ * 这里检查范围/长度与取消，不负责整源SHA、JSON语法或业务记录；源级读取失败不能降格为可跳过的坏记录。
+ */
 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 或错误文本包含某个词。 */
 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 结果额外复制以隔离缓冲复用。 */
 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');
  const limit=Math.min(end,bytes.size);let value:Uint8Array;
+ // 保留已识别源错误，其它I/O异常统一为source_read_failed；取消优先返回import_aborted。
  try{value=reader?await reader.read(start,limit,signal):new Uint8Array(await bytes.slice(start,end).arrayBuffer());}
  catch(error){if(signal.aborted)throw fault('import_aborted');if(isImportByteFailure(error))throw error;throw fault('import_source_read_failed');}
  if(signal.aborted)throw fault('import_aborted');
+ // 长度或响应类型不符视为源改变，不能让解析器在缺字节内容上继续产出业务修改。
  if(!(value instanceof Uint8Array)||value.byteLength!==limit-start)throw fault('import_source_changed');
  return reader?new Uint8Array(value):value as Uint8Array<ArrayBuffer>;
 }