/**
 * 原生记录JSON数组的逐项byte解析器（parserVersion=3），不先JSON.parse整文件。
 * 游标是[之后/逗号之后的字节位置，必须由runner保存合法边界；这里只校验数值范围，不重新证明任意seek位置。
 * 记录级JSON/UTF8/大小错误可报告后继续；数组结构无法恢复时结束源，已发布业务前缀由runner保留。
 */
import {readImportRange,type ImportByteReader} from './import-byte-reader.ts';
import {createImportBudget,type ImportScheduling} from './import-budget.ts';
import type {ImportSource,ImportLine} from './imports.ts';
import {fault,validJson} from '../canvas-core/values.ts';
/** Seekable JSON array reader. Cursors are byte offsets after '[' or a record comma.
 * Structure errors end the source; previously published records remain explicit. */
/** 捕获Blob/指纹与读取预算，缓存一块源字节；本解析器不分配业务ID、不发布history或发送请求。 */
export function createJsonArrayImportSource(options:{bytes:Blob;fingerprint:string;readBytes?:ImportByteReader;maxRecordBytes?:number;chunkBytes?:number}&ImportScheduling):ImportSource{
 const bytes=options.bytes,max=options.maxRecordBytes??256*1024,chunk=options.chunkBytes??16384;
 if(!(bytes instanceof Blob)||!options.fingerprint||!Number.isSafeInteger(max)||max<1||!Number.isSafeInteger(chunk)||chunk<1||chunk>max)throw fault('invalid_import_source');
 // byte缓存可跨record复用；空白按JSON四种ASCII空白处理，不误把UTF8字符串内容当分隔符。
 let cache={offset:-1,value:new Uint8Array()};const whitespace=(b:number)=>[9,10,13,32].includes(b);
 /** read每次返回一个ImportLine及nextCursor；EOF返回null，源级I/O失败仍抛出而不伪装坏记录。 */
 return Object.freeze({fingerprint:options.fingerprint,parserVersion:3,async read(start:number,signal:AbortSignal):Promise<ImportLine|null>{
  if(!Number.isSafeInteger(start)||start<0||start>bytes.size)throw fault('invalid_import_cursor');
  if(start>0&&start===bytes.size){if(signal.aborted)throw fault('import_aborted');return null;}
  if(bytes.size===0)throw fault('invalid_json_array');
  let cursor=start;const budget=createImportBudget(signal,options);
  /** 按需填充定长byte缓存，不推进cursor；每次读取前后检查取消。 */
  async function peek(){if(signal.aborted)throw fault('import_aborted');if(cursor>=bytes.size)return -1;if(cursor<cache.offset||cursor>=cache.offset+cache.value.length){cache={offset:cursor,value:await readImportRange(bytes,options.readBytes,cursor,cursor+chunk,signal)};if(signal.aborted)throw fault('import_aborted');}return cache.value[cursor-cache.offset];}
  /** 单字节推进并记入合作预算，调用者await可在预算要求时实际让出。 */
  function advance(){cursor++;return budget.step();}
  /** 只跳过JSON语法空白，字符串中的空白由状态机原样收集。 */
  async function spaces(){while(whitespace(await peek()))await advance();}
  /** 结构失败转成一条终结错误记录，nextCursor直接EOF，不能继续猜后面的记录边界。 */
  const failure=(error:string):ImportLine=>({cursor:start,nextCursor:bytes.size,key:`byte:${start}`,error});
  await spaces();if(start===0){if(await peek()!==91)return failure('invalid_json_array');await advance();await spaces();}
  if(await peek()===93){await advance();await spaces();if(cursor!==bytes.size)return failure('invalid_json_array');if(start!==0){/* Empty tail is valid only after a record, not a trailing comma. */return failure('invalid_json_array');}return null;}
  if(await peek()===-1)return failure('incomplete_json_array');
  // quoted/escaped隔离字符串分隔符，stack配对{}与[]；超大小后仍扫描至合法边界但不再保留字节。
  const recordStart=cursor,parts:number[]=[],stack:number[]=[];let quoted=false,escaped=false,oversized=false;
  while(true){const byte=await peek();if(byte===-1)return failure('incomplete_json_array');
   if(!quoted&&stack.length===0&&(byte===44||byte===93))break;
   if(cursor-recordStart<max)parts.push(byte);else oversized=true;
   if(quoted){if(escaped)escaped=false;else if(byte===92)escaped=true;else if(byte===34)quoted=false;}
   else if(byte===34)quoted=true;else if(byte===123||byte===91){stack.push(byte);if(stack.length>256)return failure('json_nesting_limit');}else if(byte===125||byte===93){if(stack.pop()!==(byte===125?123:91))return failure('invalid_json_array');}
   await advance();
  }
  // 消费外层逗号或]并检查尾部/尾逗号；内嵌数组的]已由stack处理，不会截断记录。
  const delimiter=await peek();await advance();
  if(delimiter===93){await spaces();if(cursor!==bytes.size)return failure('invalid_json_array');}
  else {await spaces();if(await peek()===93||await peek()===-1)return failure('invalid_json_array');}
  const base={cursor:start,nextCursor:cursor,key:`byte:${start}`};
  if(oversized)return{...base,error:'record_too_large'};
  // 只解码这一记录：fatal UTF8防替换字符掩盖损坏，再JSON.parse/validJson校验值域。
  let text:string;try{text=new TextDecoder('utf-8',{fatal:true}).decode(new Uint8Array(parts));}catch{return{...base,error:'invalid_utf8'};}
  try{const value=JSON.parse(text);return validJson(value)?{...base,value}:{...base,error:'invalid_json_value'};}catch{return{...base,error:'invalid_json'};}
 }});
}