@iowarp/clio-coder 0.4.9 → 0.5.0

package/dist/data-tool-JJPBGMQJ.js

@@ -0,0 +1,2986 @@
+import { createRequire as __clioCreateRequire } from "node:module"; const require = __clioCreateRequire(import.meta.url);
+import {
+  DATA_FORMATS,
+  DATA_OBSERVATION_SELF_CAP_BYTES,
+  DATA_OPS,
+  DATA_TOOL_NAME,
+  DataRefusalError,
+  MAX_NUMBER_LITERAL_CHARS,
+  capText,
+  classifyCell,
+  cutView,
+  dataToolSurface,
+  emptyCellHistogram,
+  exactView,
+  headerArg,
+  histogramRecord,
+  inferColumnType,
+  isDataFormat,
+  isDataRefusal,
+  numberLiteralPrecision,
+  prepareDataAdmissionArguments,
+  prepareDataArguments,
+  refusal,
+  refusalFromError,
+  resolveMaxRows,
+  sampledNotice,
+  sampledView,
+  statDataFile,
+  streamTextChunks,
+  throwIfAborted
+} from "./chunk-FFYTC2KQ.js";
+import {
+  commitObservationReservation,
+  finalizeObservation,
+  observationBudgetExhausted,
+  releaseObservation,
+  reserveObservation
+} from "./chunk-OPD7GL6F.js";
+import "./chunk-733ZBT5P.js";
+import "./chunk-GHXGMFQ5.js";
+import "./chunk-KECNXMDE.js";
+import "./chunk-WXA2CFJO.js";
+import "./chunk-6CTHLZFB.js";
+import "./chunk-2KUBKL63.js";
+import "./chunk-MYI32N4R.js";
+import "./chunk-X6FLVUM5.js";
+import "./chunk-L7G7K4I2.js";
+import "./chunk-ALJWT6O6.js";
+import "./chunk-O3VV6IVK.js";
+import "./chunk-5EQO5NWP.js";
+import "./chunk-VYRQHORQ.js";
+import "./chunk-P4GNZPXO.js";
+import "./chunk-R2P2U3ZS.js";
+import "./chunk-NTTS3O53.js";
+import {
+  resolveToCwd
+} from "./chunk-C2CPOIH2.js";
+import "./chunk-MGLRTOCK.js";
+import "./chunk-M4KFUXS7.js";
+import "./chunk-V4XJWDHR.js";
+import "./chunk-C27U2TYG.js";
+import "./chunk-B5GGDIHT.js";
+import "./chunk-M2IPMWCN.js";
+import "./chunk-XS2QPZJE.js";
+import "./chunk-6EXUUOSN.js";
+import "./chunk-ZTNFYMIO.js";
+import "./chunk-DVJL77SO.js";
+import "./chunk-GH5ZR6JP.js";
+import "./chunk-TK2BMCBZ.js";
+import "./chunk-CTTI7G3T.js";
+import "./chunk-ZZFWWYLX.js";
+import "./chunk-ZPST2KQO.js";
+import "./chunk-FD2I4KBR.js";
+import {
+  init_esm_shims
+} from "./chunk-ECBHH7LU.js";
+
+// src/tools/gateway/data-tool.ts
+init_esm_shims();
+import path from "node:path";
+
+// src/tools/data/index.ts
+init_esm_shims();
+import { open } from "node:fs/promises";
+import { extname } from "node:path";
+
+// src/tools/data/csv.ts
+init_esm_shims();
+var CHAR_QUOTE = 34;
+var CHAR_LF = 10;
+var CHAR_CR = 13;
+var CSV_MAX_FIELD_CHARS = 1048576;
+var CSV_MAX_RECORD_CHARS = 16 * 1048576;
+var CsvParser = class {
+  constructor(delimiter, callbacks) {
+    this.delimiter = delimiter;
+    this.callbacks = callbacks;
+  }
+  delimiter;
+  callbacks;
+  state = 0 /* FieldStart */;
+  fields = [];
+  current = "";
+  recordChars = 0;
+  hasContent = false;
+  skipLf = false;
+  line = 1;
+  recordLine = 1;
+  records = 0;
+  stopped = false;
+  issueThisRecord = null;
+  blankLines = 0;
+  crlf = 0;
+  lf = 0;
+  cr = 0;
+  get isStopped() {
+    return this.stopped;
+  }
+  get recordCount() {
+    return this.records;
+  }
+  /** Feed one chunk. Returns false once the record sink asked to stop. */
+  push(text) {
+    if (this.stopped) return false;
+    const length = text.length;
+    let runStart = this.state === 1 /* Unquoted */ || this.state === 2 /* Quoted */ ? 0 : -1;
+    for (let index = 0; index < length; index += 1) {
+      const code = text.charCodeAt(index);
+      if (this.skipLf) {
+        this.skipLf = false;
+        if (code === CHAR_LF) {
+          this.crlf += 1;
+          this.cr -= 1;
+          continue;
+        }
+      }
+      switch (this.state) {
+        case 0 /* FieldStart */:
+          if (code === CHAR_QUOTE) {
+            this.state = 2 /* Quoted */;
+            this.hasContent = true;
+            runStart = index + 1;
+          } else if (code === this.delimiter) {
+            this.hasContent = true;
+            this.pushField("");
+          } else if (code === CHAR_LF || code === CHAR_CR) {
+            if (this.hasContent) this.pushField("");
+            this.newline(code);
+            this.endRecord();
+          } else {
+            this.state = 1 /* Unquoted */;
+            this.hasContent = true;
+            runStart = index;
+          }
+          break;
+        case 1 /* Unquoted */:
+          if (code === this.delimiter) {
+            const fits = this.appendRun(text, runStart, index);
+            runStart = -1;
+            if (!fits) break;
+            this.pushField(this.current);
+            this.current = "";
+            if (this.state === 1 /* Unquoted */) this.state = 0 /* FieldStart */;
+          } else if (code === CHAR_LF || code === CHAR_CR) {
+            const fits = this.appendRun(text, runStart, index);
+            runStart = -1;
+            if (!fits) {
+              this.closeOverflow(code);
+              break;
+            }
+            this.pushField(this.current);
+            this.current = "";
+            this.state = 0 /* FieldStart */;
+            this.newline(code);
+            this.endRecord();
+          } else if (code === CHAR_QUOTE) {
+            this.issue("bare-quote", "a quote inside an unquoted field was read as literal text");
+          }
+          break;
+        case 2 /* Quoted */:
+          if (code === CHAR_QUOTE) {
+            const fits = this.appendRun(text, runStart, index);
+            runStart = -1;
+            if (fits) this.state = 3 /* QuoteInQuoted */;
+          } else if (code === CHAR_LF || code === CHAR_CR) {
+            const pending = index - runStart;
+            if (this.current.length + pending > CSV_MAX_FIELD_CHARS || this.recordChars + pending > CSV_MAX_RECORD_CHARS) {
+              this.appendRun(text, runStart, index);
+              runStart = -1;
+              this.closeOverflow(code);
+            } else if (code === CHAR_LF) {
+              this.line += 1;
+              this.lf += 1;
+            } else {
+              this.line += 1;
+              this.cr += 1;
+              this.skipLf = true;
+            }
+          }
+          break;
+        case 3 /* QuoteInQuoted */:
+          if (code === CHAR_QUOTE) {
+            if (this.appendRun('"', 0, 1)) {
+              this.state = 2 /* Quoted */;
+              runStart = index + 1;
+            }
+          } else if (code === this.delimiter) {
+            this.pushField(this.current);
+            this.current = "";
+            if (this.state === 3 /* QuoteInQuoted */) this.state = 0 /* FieldStart */;
+          } else if (code === CHAR_LF || code === CHAR_CR) {
+            this.pushField(this.current);
+            this.current = "";
+            this.state = 0 /* FieldStart */;
+            this.newline(code);
+            this.endRecord();
+          } else {
+            this.issue("text-after-quote", "text after a closing quote was joined to the field");
+            this.state = 1 /* Unquoted */;
+            runStart = index;
+          }
+          break;
+        case 4 /* Overflow */:
+          if (code === CHAR_LF || code === CHAR_CR) this.closeOverflow(code);
+          break;
+      }
+      if (this.stopped) return false;
+    }
+    if (runStart >= 0 && (this.state === 1 /* Unquoted */ || this.state === 2 /* Quoted */)) {
+      this.appendRun(text, runStart, length);
+    }
+    return true;
+  }
+  end() {
+    if (this.stopped) return;
+    switch (this.state) {
+      case 2 /* Quoted */:
+        this.issue("unterminated-quote", "the file ended inside a quoted field");
+        this.fields.push(this.current);
+        this.endRecord();
+        break;
+      case 3 /* QuoteInQuoted */:
+      case 1 /* Unquoted */:
+      case 4 /* Overflow */:
+        this.fields.push(this.current);
+        this.endRecord();
+        break;
+      default:
+        if (this.hasContent) {
+          this.fields.push("");
+          this.endRecord();
+        }
+        break;
+    }
+    this.current = "";
+    this.state = 0 /* FieldStart */;
+  }
+  /**
+   * Append text[from, to) to the current field within the caps. Returns false
+   * when a cap was hit: the field keeps what fit and the parser is in the
+   * Overflow state, dropping input until the record's next line break.
+   */
+  appendRun(text, from, to) {
+    if (to <= from) return true;
+    const run = to - from;
+    const fieldRoom = CSV_MAX_FIELD_CHARS - this.current.length;
+    const recordRoom = CSV_MAX_RECORD_CHARS - this.recordChars;
+    const room = Math.min(fieldRoom, recordRoom);
+    if (run <= room) {
+      this.current += text.slice(from, to);
+      this.recordChars += run;
+      return true;
+    }
+    if (room > 0) {
+      this.current += text.slice(from, from + room);
+      this.recordChars += room;
+    }
+    this.overflow(fieldRoom <= recordRoom ? "field-too-large" : "record-too-large");
+    return false;
+  }
+  /** Complete a field; each field also costs one character of the record cap. */
+  pushField(value) {
+    this.fields.push(value);
+    this.recordChars += 1;
+    if (this.recordChars > CSV_MAX_RECORD_CHARS) this.overflow("record-too-large");
+  }
+  overflow(kind) {
+    const message = kind === "field-too-large" ? `a field exceeded ${CSV_MAX_FIELD_CHARS} characters${this.state === 2 /* Quoted */ ? " inside quotes, likely an unterminated quote" : ""}; it was cut at the cap and the record was closed at the next line break` : `a record exceeded ${CSV_MAX_RECORD_CHARS} characters; it was cut at the cap and closed at the next line break`;
+    this.issue(kind, message);
+    this.state = 4 /* Overflow */;
+  }
+  closeOverflow(code) {
+    this.fields.push(this.current);
+    this.current = "";
+    this.state = 0 /* FieldStart */;
+    this.newline(code);
+    this.endRecord();
+  }
+  newline(code) {
+    this.line += 1;
+    if (code === CHAR_CR) {
+      this.cr += 1;
+      this.skipLf = true;
+    } else {
+      this.lf += 1;
+    }
+  }
+  endRecord() {
+    const startLine = this.recordLine;
+    this.recordLine = this.line;
+    this.recordChars = 0;
+    if (!this.hasContent && this.fields.length === 0) {
+      this.blankLines += 1;
+      return;
+    }
+    this.records += 1;
+    const fields = this.fields;
+    this.fields = [];
+    this.hasContent = false;
+    this.issueThisRecord = null;
+    if (!this.callbacks.onRecord(fields, this.records, startLine)) this.stopped = true;
+  }
+  issue(kind, message) {
+    if (this.issueThisRecord === kind) return;
+    this.issueThisRecord = kind;
+    this.callbacks.onIssue({ kind, record: this.records + 1, line: this.recordLine, message });
+  }
+};
+var CSV_DELIMITER_CANDIDATES = [",", "	", ";", "|"];
+var DELIMITER_SAMPLE_CHARS = 64 * 1024;
+var DELIMITER_SAMPLE_RECORDS = 200;
+function detectCsvDelimiter(sample, sampleComplete) {
+  let best = { delimiter: ",", confidence: 0, fieldCount: 1 };
+  for (const candidate of CSV_DELIMITER_CANDIDATES) {
+    const counts = [];
+    const parser = new CsvParser(candidate.charCodeAt(0), {
+      onRecord(fields) {
+        counts.push(fields.length);
+        return counts.length < DELIMITER_SAMPLE_RECORDS;
+      },
+      onIssue() {
+      }
+    });
+    parser.push(sample);
+    if (sampleComplete) parser.end();
+    const usable = sampleComplete || parser.isStopped ? counts : counts.slice(0, -1);
+    if (usable.length === 0) continue;
+    const tally = /* @__PURE__ */ new Map();
+    for (const count of usable) tally.set(count, (tally.get(count) ?? 0) + 1);
+    let modal = 1;
+    let modalHits = 0;
+    for (const [count, hits] of tally) {
+      if (hits > modalHits || hits === modalHits && count > modal) {
+        modal = count;
+        modalHits = hits;
+      }
+    }
+    if (modal < 2) continue;
+    const confidence = modalHits / usable.length;
+    if (confidence > best.confidence) best = { delimiter: candidate, confidence, fieldCount: modal };
+  }
+  return best;
+}
+function headerLooksLikeNames(record) {
+  return record.length > 0 && record.every((cell) => cell.trim().length > 0 && classifyCell(cell.trim()) === "string");
+}
+function defaultColumnName(index) {
+  return `column_${index + 1}`;
+}
+var CSV_DEFAULT_SAMPLE_ROWS = 10;
+var CSV_DEFAULT_MAX_ROWS = 1e5;
+var COLUMN_TRACK_CAP = 1e4;
+var FIRST_ISSUES_CAP = 10;
+var SAMPLE_VALUES_CAP = 5;
+function newColumn(index, name) {
+  return {
+    index,
+    name,
+    nonEmpty: 0,
+    empty: 0,
+    sentinels: /* @__PURE__ */ new Map(),
+    types: emptyCellHistogram(),
+    samples: [],
+    minLength: Number.POSITIVE_INFINITY,
+    maxLength: 0,
+    intMin: null,
+    intMax: null,
+    intMinText: "",
+    intMaxText: "",
+    floatMin: Number.POSITIVE_INFINITY,
+    floatMax: Number.NEGATIVE_INFINITY,
+    floatMinText: "",
+    floatMaxText: "",
+    floatApproximate: false,
+    precisionIssues: 0
+  };
+}
+function accumulateCell(column, cell) {
+  const cls = classifyCell(cell);
+  column.types[cls] += 1;
+  if (cls === "empty") {
+    column.empty += 1;
+    column.minLength = 0;
+    return null;
+  }
+  column.nonEmpty += 1;
+  column.minLength = Math.min(column.minLength, cell.length);
+  column.maxLength = Math.max(column.maxLength, cell.length);
+  if (cls === "sentinel") {
+    column.sentinels.set(cell, (column.sentinels.get(cell) ?? 0) + 1);
+    return null;
+  }
+  if (column.samples.length < SAMPLE_VALUES_CAP && !column.samples.includes(cell)) column.samples.push(cell);
+  if (cls === "integer") {
+    const value = BigInt(cell);
+    if (column.intMin === null || value < column.intMin) {
+      column.intMin = value;
+      column.intMinText = cell;
+    }
+    if (column.intMax === null || value > column.intMax) {
+      column.intMax = value;
+      column.intMaxText = cell;
+    }
+    const precision = numberLiteralPrecision(cell);
+    if (precision !== null) column.precisionIssues += 1;
+    return precision;
+  }
+  if (cls === "float") {
+    const value = Number(cell);
+    const precision = numberLiteralPrecision(cell);
+    if (precision !== null) {
+      column.precisionIssues += 1;
+      column.floatApproximate = true;
+    }
+    if (Number.isFinite(value)) {
+      if (value < column.floatMin) {
+        column.floatMin = value;
+        column.floatMinText = cell;
+      }
+      if (value > column.floatMax) {
+        column.floatMax = value;
+        column.floatMaxText = cell;
+      }
+    }
+    return precision;
+  }
+  return null;
+}
+function numericRange(column) {
+  const hasInt = column.intMin !== null && column.intMax !== null;
+  const hasFloat = Number.isFinite(column.floatMin);
+  if (!hasInt && !hasFloat) return void 0;
+  if (hasInt && !hasFloat) return { min: column.intMinText, max: column.intMaxText, approximate: false };
+  if (!hasInt) return { min: column.floatMinText, max: column.floatMaxText, approximate: column.floatApproximate };
+  const intMinNumber = Number(column.intMin);
+  const intMaxNumber = Number(column.intMax);
+  const approximate = column.floatApproximate || !Number.isSafeInteger(intMinNumber) || !Number.isSafeInteger(intMaxNumber);
+  const min = intMinNumber <= column.floatMin ? column.intMinText : column.floatMinText;
+  const max = intMaxNumber >= column.floatMax ? column.intMaxText : column.floatMaxText;
+  return { min, max, approximate };
+}
+function columnReport(column) {
+  const range = numericRange(column);
+  return {
+    index: column.index,
+    name: column.name,
+    inferredType: inferColumnType(column.types),
+    nonEmpty: column.nonEmpty,
+    empty: column.empty,
+    sentinels: histogramRecord(column.sentinels),
+    types: { ...column.types },
+    sampleValues: column.samples.map((value) => capText(value).text),
+    minLength: Number.isFinite(column.minLength) ? column.minLength : 0,
+    maxLength: column.maxLength,
+    ...range !== void 0 ? { numericRange: range } : {},
+    precisionIssues: column.precisionIssues
+  };
+}
+function lineEndingOf(parser) {
+  const kinds = [parser.lf > 0, parser.crlf > 0, parser.cr > 0].filter(Boolean).length;
+  if (kinds === 0) return "none";
+  if (kinds > 1) return "mixed";
+  if (parser.crlf > 0) return "crlf";
+  if (parser.cr > 0) return "cr";
+  return "lf";
+}
+function resolveDelimiter(explicit, format) {
+  if (explicit === void 0) return format === "tsv" ? "	" : null;
+  if (explicit === "\\t") return "	";
+  if (explicit.length !== 1) return new Error("delimiter must be one character (or \\t)");
+  if (explicit === '"' || explicit === "\n" || explicit === "\r") {
+    return new Error("delimiter cannot be a quote or a line break");
+  }
+  return explicit;
+}
+async function scanCsv(path2, explicitDelimiter, signal, stats, callbacks) {
+  let parser = null;
+  let delimiter = explicitDelimiter;
+  let delimiterSource = delimiter === null ? "detected" : "explicit";
+  let sample = "";
+  for await (const chunk of streamTextChunks(path2, { signal, stats })) {
+    if (parser === null) {
+      if (delimiter === null) {
+        sample += chunk.text;
+        if (sample.length < DELIMITER_SAMPLE_CHARS) continue;
+        const detected = detectCsvDelimiter(sample.slice(0, DELIMITER_SAMPLE_CHARS), false);
+        delimiter = detected.delimiter;
+        if (detected.confidence === 0) delimiterSource = "default";
+        parser = new CsvParser(delimiter.charCodeAt(0), callbacks);
+        const keepGoing = parser.push(sample);
+        sample = "";
+        if (!keepGoing) break;
+        continue;
+      }
+      parser = new CsvParser(delimiter.charCodeAt(0), callbacks);
+    }
+    if (!parser.push(chunk.text)) break;
+  }
+  throwIfAborted(signal, path2);
+  if (parser === null) {
+    if (delimiter === null) {
+      const detected = detectCsvDelimiter(sample, true);
+      delimiter = detected.delimiter;
+      if (detected.confidence === 0) delimiterSource = "default";
+    }
+    parser = new CsvParser(delimiter.charCodeAt(0), callbacks);
+    parser.push(sample);
+  }
+  if (!parser.isStopped) parser.end();
+  return { parser, delimiter, delimiterSource };
+}
+var HeaderResolver = class {
+  constructor(option) {
+    this.option = option;
+  }
+  option;
+  header = null;
+  source = "none";
+  fieldCount = 0;
+  settled = false;
+  pending = null;
+  /** Returns the data rows this record releases, in order. */
+  feed(fields, line) {
+    if (this.settled) return [{ fields, line }];
+    if (this.option === true) {
+      this.settle(fields, "explicit", fields.length);
+      return [];
+    }
+    if (this.option === false) {
+      this.settle(null, "none", fields.length);
+      return [{ fields, line }];
+    }
+    if (this.pending === null) {
+      this.pending = { fields, line };
+      return [];
+    }
+    const first = this.pending;
+    this.pending = null;
+    if (headerLooksLikeNames(first.fields)) {
+      this.settle(first.fields, "detected", first.fields.length);
+      return [{ fields, line }];
+    }
+    this.settle(null, "none", first.fields.length);
+    return [first, { fields, line }];
+  }
+  /** End of input: a lone pending record is data. */
+  finish() {
+    if (this.settled) return [];
+    const first = this.pending;
+    this.pending = null;
+    if (first === null) {
+      this.settle(this.option === true ? [] : null, this.option === true ? "explicit" : "none", 0);
+      return [];
+    }
+    this.settle(null, "none", first.fields.length);
+    return [first];
+  }
+  settle(header, source, fieldCount) {
+    this.settled = true;
+    this.header = header;
+    this.source = source;
+    this.fieldCount = fieldCount;
+  }
+};
+async function inspectCsv(path2, options = {}) {
+  const stat = statDataFile(path2);
+  if ("ok" in stat) return stat;
+  const format = options.format ?? "csv";
+  const explicitDelimiter = resolveDelimiter(options.delimiter, format);
+  if (explicitDelimiter instanceof Error) return refusal("invalid-argument", explicitDelimiter.message, { path: path2 });
+  const sampleRows = Math.max(0, Math.min(1e3, Math.floor(options.sampleRows ?? CSV_DEFAULT_SAMPLE_ROWS)));
+  const maxRows = resolveMaxRows(options.maxRows, CSV_DEFAULT_MAX_ROWS);
+  const stats = { bytesRead: 0, bom: false };
+  const headers = new HeaderResolver(options.header ?? "auto");
+  const state = {
+    columns: [],
+    columnsTruncated: false,
+    columnsEstablished: false,
+    dataRows: 0,
+    stoppedAtRows: false,
+    raggedCount: 0,
+    raggedFirst: [],
+    issueCount: 0,
+    issueFirst: [],
+    precisionCount: 0,
+    precisionFirst: [],
+    sample: [],
+    sampleTruncatedCells: 0
+  };
+  const establishColumns = () => {
+    if (state.columnsEstablished) return;
+    state.columnsEstablished = true;
+    const names = headers.header ?? Array.from({ length: headers.fieldCount }, (_, index) => defaultColumnName(index));
+    for (const [index, name] of names.entries()) {
+      if (state.columns.length >= COLUMN_TRACK_CAP) {
+        state.columnsTruncated = true;
+        break;
+      }
+      state.columns.push(newColumn(index, name));
+    }
+  };
+  const consumeDataRow = (fields, line) => {
+    establishColumns();
+    if (state.dataRows >= maxRows) {
+      state.stoppedAtRows = true;
+      return false;
+    }
+    state.dataRows += 1;
+    if (fields.length !== headers.fieldCount) {
+      state.raggedCount += 1;
+      if (state.raggedFirst.length < FIRST_ISSUES_CAP) {
+        state.raggedFirst.push({ row: state.dataRows, line, fields: fields.length });
+      }
+    }
+    for (const [index, cell] of fields.entries()) {
+      let column = state.columns[index];
+      if (column === void 0) {
+        if (state.columns.length >= COLUMN_TRACK_CAP) {
+          state.columnsTruncated = true;
+          break;
+        }
+        column = newColumn(index, defaultColumnName(index));
+        state.columns.push(column);
+      }
+      const precision = accumulateCell(column, cell);
+      if (precision !== null) {
+        state.precisionCount += 1;
+        if (state.precisionFirst.length < FIRST_ISSUES_CAP) {
+          state.precisionFirst.push({ kind: precision, literal: cell, row: state.dataRows, column: index });
+        }
+      }
+    }
+    if (state.sample.length < sampleRows) {
+      state.sample.push(
+        fields.map((cell) => {
+          const capped = capText(cell);
+          if (capped.truncated) state.sampleTruncatedCells += 1;
+          return capped.text;
+        })
+      );
+    }
+    return true;
+  };
+  const callbacks = {
+    onRecord(fields, _record, line) {
+      for (const row of headers.feed(fields, line)) {
+        if (!consumeDataRow(row.fields, row.line)) return false;
+      }
+      return true;
+    },
+    onIssue(issue) {
+      state.issueCount += 1;
+      if (state.issueFirst.length < FIRST_ISSUES_CAP) state.issueFirst.push(issue);
+    }
+  };
+  let scan;
+  try {
+    scan = await scanCsv(path2, explicitDelimiter, options.signal, stats, callbacks);
+  } catch (error) {
+    return refusalFromError(error, path2, options.signal);
+  }
+  if (!scan.parser.isStopped) {
+    for (const row of headers.finish()) consumeDataRow(row.fields, row.line);
+    establishColumns();
+  }
+  const sampled = state.stoppedAtRows;
+  const notes = [];
+  if (stats.bom) notes.push("a UTF-8 byte-order mark was stripped");
+  if (sampled) notes.push(sampledNotice(state.dataRows, "rows"));
+  if (scan.delimiterSource === "default") {
+    notes.push("no delimiter split the sample consistently; read as one column with the comma");
+  }
+  if (state.columnsTruncated) notes.push(`column tracking capped at ${COLUMN_TRACK_CAP} columns`);
+  if (state.raggedCount > 0) {
+    notes.push(`${state.raggedCount} row(s) have a field count other than ${headers.fieldCount}`);
+  }
+  if (state.issueCount > 0) notes.push(`${state.issueCount} quoting issue(s) were recovered leniently and are listed`);
+  if (state.precisionCount > 0) {
+    notes.push(`${state.precisionCount} numeric cell(s) would lose precision as doubles; cells stay source text`);
+  }
+  return {
+    ok: true,
+    format,
+    path: path2,
+    bytes: stat.size,
+    bytesScanned: stats.bytesRead,
+    view: sampled ? sampledView() : exactView(),
+    rowsScanned: state.dataRows,
+    rowCount: sampled ? null : state.dataRows,
+    delimiter: scan.delimiter,
+    delimiterSource: scan.delimiterSource,
+    header: headers.header,
+    headerSource: headers.source,
+    bom: stats.bom,
+    lineEnding: lineEndingOf(scan.parser),
+    fieldCount: headers.fieldCount,
+    columns: state.columns.map(columnReport),
+    columnsTruncated: state.columnsTruncated,
+    raggedRows: { count: state.raggedCount, first: state.raggedFirst },
+    quotingIssues: { count: state.issueCount, first: state.issueFirst },
+    precision: { count: state.precisionCount, first: state.precisionFirst },
+    blankLines: scan.parser.blankLines,
+    sample: state.sample,
+    sampleTruncatedCells: state.sampleTruncatedCells,
+    notes
+  };
+}
+var CSV_SELECT_DEFAULT_LIMIT = 50;
+var CSV_SELECT_MAX_LIMIT = 1e3;
+async function selectCsv(path2, options = {}) {
+  const stat = statDataFile(path2);
+  if ("ok" in stat) return stat;
+  const format = options.format ?? "csv";
+  const explicitDelimiter = resolveDelimiter(options.delimiter, format);
+  if (explicitDelimiter instanceof Error) return refusal("invalid-argument", explicitDelimiter.message, { path: path2 });
+  const offset = Math.max(0, Math.floor(options.offset ?? 0));
+  const limit = Math.max(1, Math.min(CSV_SELECT_MAX_LIMIT, Math.floor(options.limit ?? CSV_SELECT_DEFAULT_LIMIT)));
+  const stats = { bytesRead: 0, bom: false };
+  const headers = new HeaderResolver(options.header ?? "auto");
+  const state = {
+    projection: null,
+    projectionResolved: false,
+    projectionError: null,
+    dataRows: 0,
+    hasMore: false,
+    rows: []
+  };
+  const resolveProjection = () => {
+    if (state.projectionResolved) return state.projectionError === null;
+    state.projectionResolved = true;
+    if (options.columns === void 0) return true;
+    const names = headers.header;
+    const indexes2 = [];
+    for (const column of options.columns) {
+      if (typeof column === "number") {
+        if (!Number.isInteger(column) || column < 0) {
+          state.projectionError = refusal("invalid-argument", `column index ${column} is not a non-negative integer`, {
+            path: path2
+          });
+          return false;
+        }
+        indexes2.push(column);
+        continue;
+      }
+      const index = names?.indexOf(column) ?? -1;
+      if (index === -1) {
+        state.projectionError = refusal(
+          "unknown-column",
+          names === null ? `column "${column}" cannot be resolved: the file has no header; use a 0-based index` : `unknown column "${column}"; header columns are ${names.map((name) => JSON.stringify(name)).join(", ")}`,
+          { path: path2 }
+        );
+        return false;
+      }
+      indexes2.push(index);
+    }
+    state.projection = indexes2;
+    return true;
+  };
+  const consumeDataRow = (fields) => {
+    if (!resolveProjection()) return false;
+    const index = state.dataRows;
+    state.dataRows += 1;
+    if (index < offset) return true;
+    if (state.rows.length >= limit) {
+      state.hasMore = true;
+      return false;
+    }
+    const projection2 = state.projection;
+    state.rows.push(projection2 === null ? fields : projection2.map((column) => fields[column] ?? null));
+    return true;
+  };
+  const callbacks = {
+    onRecord(fields, _record, line) {
+      for (const row of headers.feed(fields, line)) {
+        if (!consumeDataRow(row.fields)) return false;
+      }
+      if (headers.settled && !resolveProjection()) return false;
+      return true;
+    },
+    onIssue() {
+    }
+  };
+  let scan;
+  try {
+    scan = await scanCsv(path2, explicitDelimiter, options.signal, stats, callbacks);
+  } catch (error) {
+    return refusalFromError(error, path2, options.signal);
+  }
+  if (state.projectionError !== null) return state.projectionError;
+  if (!scan.parser.isStopped) {
+    for (const row of headers.finish()) consumeDataRow(row.fields);
+    if (!resolveProjection()) return state.projectionError ?? refusal("invalid-argument", "bad projection", { path: path2 });
+  }
+  const header = headers.header;
+  const projection = state.projection;
+  const indexes = projection ?? (header !== null ? header.map((_, index) => index) : Array.from({ length: state.rows.reduce((max, row) => Math.max(max, row.length), 0) }, (_, index) => index));
+  const notes = [];
+  if (stats.bom) notes.push("a UTF-8 byte-order mark was stripped");
+  if (scan.delimiterSource === "default") {
+    notes.push("no delimiter split the sample consistently; read as one column with the comma");
+  }
+  return {
+    ok: true,
+    format,
+    path: path2,
+    bytes: stat.size,
+    bytesScanned: stats.bytesRead,
+    view: exactView(),
+    delimiter: scan.delimiter,
+    header: header === null ? null : projection === null ? header : projection.map((column) => header[column] ?? defaultColumnName(column)),
+    columnIndexes: indexes,
+    offset,
+    limit,
+    returned: state.rows.length,
+    hasMore: state.hasMore,
+    rowsScanned: state.dataRows,
+    rows: state.rows,
+    notes
+  };
+}
+async function validateCsv(path2, options = {}) {
+  const stat = statDataFile(path2);
+  if ("ok" in stat) return stat;
+  const format = options.format ?? "csv";
+  const explicitDelimiter = resolveDelimiter(options.delimiter, format);
+  if (explicitDelimiter instanceof Error) return refusal("invalid-argument", explicitDelimiter.message, { path: path2 });
+  const maxRows = resolveMaxRows(options.maxRows, CSV_DEFAULT_MAX_ROWS);
+  const stats = { bytesRead: 0, bom: false };
+  const headers = new HeaderResolver(options.header ?? "auto");
+  const state = {
+    dataRows: 0,
+    stoppedAtRows: false,
+    raggedCount: 0,
+    raggedFirst: [],
+    issueCount: 0,
+    issueFirst: []
+  };
+  const consumeDataRow = (fields, line) => {
+    if (state.dataRows >= maxRows) {
+      state.stoppedAtRows = true;
+      return false;
+    }
+    state.dataRows += 1;
+    if (fields.length !== headers.fieldCount) {
+      state.raggedCount += 1;
+      if (state.raggedFirst.length < FIRST_ISSUES_CAP) {
+        state.raggedFirst.push({ row: state.dataRows, line, fields: fields.length });
+      }
+    }
+    return true;
+  };
+  const callbacks = {
+    onRecord(fields, _record, line) {
+      for (const row of headers.feed(fields, line)) {
+        if (!consumeDataRow(row.fields, row.line)) return false;
+      }
+      return true;
+    },
+    onIssue(issue) {
+      state.issueCount += 1;
+      if (state.issueFirst.length < FIRST_ISSUES_CAP) state.issueFirst.push(issue);
+    }
+  };
+  let scan;
+  try {
+    scan = await scanCsv(path2, explicitDelimiter, options.signal, stats, callbacks);
+  } catch (error) {
+    return refusalFromError(error, path2, options.signal);
+  }
+  if (!scan.parser.isStopped) {
+    for (const row of headers.finish()) consumeDataRow(row.fields, row.line);
+  }
+  const complete = !state.stoppedAtRows;
+  const faults = state.raggedCount + state.issueCount;
+  const notes = [];
+  if (stats.bom) notes.push("a UTF-8 byte-order mark was stripped");
+  if (!complete) {
+    notes.push(
+      `validation incomplete: stopped after ${state.dataRows} rows; pass maxRows null to validate the whole file`
+    );
+  }
+  if (state.raggedCount > 0) {
+    notes.push(`${state.raggedCount} row(s) have a field count other than ${headers.fieldCount}`);
+  }
+  if (state.issueCount > 0) notes.push(`${state.issueCount} quoting issue(s)`);
+  return {
+    ok: true,
+    format,
+    path: path2,
+    bytes: stat.size,
+    bytesScanned: stats.bytesRead,
+    view: complete ? exactView() : sampledView(),
+    valid: faults > 0 ? false : complete ? true : null,
+    complete,
+    rowsScanned: state.dataRows,
+    rowCount: complete ? state.dataRows : null,
+    delimiter: scan.delimiter,
+    fieldCount: headers.fieldCount,
+    header: headers.header,
+    raggedRows: { count: state.raggedCount, first: state.raggedFirst },
+    quotingIssues: { count: state.issueCount, first: state.issueFirst },
+    blankLines: scan.parser.blankLines,
+    notes
+  };
+}
+
+// src/tools/data/json.ts
+init_esm_shims();
+var JSON_MAX_DEPTH = 1024;
+var KEY_CAPTURE_CAP = 1024;
+var STRING_CAPTURE_CAP = 65536;
+var CHAR_QUOTE2 = 34;
+var CHAR_BACKSLASH = 92;
+var CHAR_LF2 = 10;
+function escapeChar(code) {
+  switch (code) {
+    case CHAR_QUOTE2:
+      return '"';
+    case CHAR_BACKSLASH:
+      return "\\";
+    case 47:
+      return "/";
+    case 98:
+      return "\b";
+    case 102:
+      return "\f";
+    case 110:
+      return "\n";
+    case 114:
+      return "\r";
+    case 116:
+      return "	";
+    default:
+      return null;
+  }
+}
+function isWhitespace(code) {
+  return code === 32 || code === 9 || code === CHAR_LF2 || code === 13;
+}
+function isNumberChar(code) {
+  return code >= 48 && code <= 57 || code === 45 || code === 43 || code === 46 || code === 69 || code === 101;
+}
+var NUMBER_GRAMMAR = /^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$/u;
+var JsonStreamParser = class {
+  constructor(sink) {
+    this.sink = sink;
+  }
+  sink;
+  stack = [];
+  expect = 0 /* Value */;
+  tokenState = 0 /* None */;
+  token = "";
+  tokenTruncated = false;
+  stringCapture = false;
+  stringLength = 0;
+  stringIsKey = false;
+  escape = false;
+  unicodeHex = null;
+  line = 1;
+  column = 0;
+  chunkText = "";
+  chunkByteOffset = 0;
+  chunkIndex = 0;
+  stopped = false;
+  rootComplete = false;
+  /** Depth of the deepest container opened so far (root object or array is 0). */
+  maxDepth = 0;
+  get isStopped() {
+    return this.stopped;
+  }
+  get depth() {
+    return this.stack.length;
+  }
+  /** Feed one chunk. Returns false once a sink asked to stop; further pushes are ignored. */
+  push(text, byteOffset = 0) {
+    if (this.stopped) return false;
+    this.chunkText = text;
+    this.chunkByteOffset = byteOffset;
+    const length = text.length;
+    let index = 0;
+    while (index < length) {
+      this.chunkIndex = index;
+      const code = text.charCodeAt(index);
+      if (code === CHAR_LF2) {
+        this.line += 1;
+        this.column = 0;
+      } else {
+        this.column += 1;
+      }
+      switch (this.tokenState) {
+        case 1 /* String */:
+          index = this.scanString(text, index, length);
+          break;
+        case 2 /* Number */:
+          if (isNumberChar(code)) {
+            this.appendNumberChar(text[index]);
+            index += 1;
+          } else {
+            this.column -= 1;
+            if (code === CHAR_LF2) {
+              this.line -= 1;
+              this.column = 0;
+            }
+            this.completeNumber();
+            this.tokenState = 0 /* None */;
+          }
+          break;
+        case 3 /* Literal */:
+          if (code >= 97 && code <= 122) {
+            this.token += text[index];
+            index += 1;
+            if (this.token.length >= 5) this.completeLiteral();
+          } else {
+            this.column -= 1;
+            if (code === CHAR_LF2) {
+              this.line -= 1;
+              this.column = 0;
+            }
+            this.completeLiteral();
+          }
+          break;
+        default:
+          index = this.scanStructural(text, index, code);
+          break;
+      }
+      if (this.stopped) return false;
+    }
+    return true;
+  }
+  end() {
+    if (this.stopped) return;
+    this.chunkIndex = this.chunkText.length;
+    if (this.tokenState === 2 /* Number */) {
+      this.completeNumber();
+      this.tokenState = 0 /* None */;
+    } else if (this.tokenState === 3 /* Literal */) {
+      this.completeLiteral();
+    } else if (this.tokenState === 1 /* String */) {
+      throw this.error("unterminated string at end of input");
+    }
+    if (this.stopped) return;
+    if (!this.rootComplete) {
+      throw this.error(this.stack.length === 0 ? "unexpected end of input: no JSON value" : "unexpected end of input");
+    }
+  }
+  scanStructural(text, index, code) {
+    if (isWhitespace(code)) return index + 1;
+    if (this.expect === 6 /* End */) throw this.error("unexpected content after the JSON value");
+    switch (code) {
+      case CHAR_QUOTE2: {
+        const isKey = this.expect === 2 /* Key */ || this.expect === 1 /* KeyOrEnd */;
+        if (!isKey && this.expect !== 0 /* Value */ && this.expect !== 5 /* ValueOrEnd */) {
+          throw this.error(this.describeExpectation());
+        }
+        this.tokenState = 1 /* String */;
+        this.stringIsKey = isKey;
+        this.stringCapture = isKey || this.sink.captureStrings(this.stack.length);
+        this.token = "";
+        this.tokenTruncated = false;
+        this.stringLength = 0;
+        this.escape = false;
+        this.unicodeHex = null;
+        return index + 1;
+      }
+      case 123:
+        this.requireValueExpectation();
+        this.openContainer("object");
+        return index + 1;
+      case 91:
+        this.requireValueExpectation();
+        this.openContainer("array");
+        return index + 1;
+      case 125:
+        this.closeContainer("object");
+        return index + 1;
+      case 93:
+        this.closeContainer("array");
+        return index + 1;
+      case 58:
+        if (this.expect !== 3 /* Colon */) throw this.error(this.describeExpectation());
+        this.expect = 0 /* Value */;
+        return index + 1;
+      case 44: {
+        if (this.expect !== 4 /* CommaOrEnd */) throw this.error(this.describeExpectation());
+        const top = this.stack[this.stack.length - 1];
+        top.expect = top.kind === "object" ? 2 /* Key */ : 0 /* Value */;
+        this.expect = top.expect;
+        return index + 1;
+      }
+      default:
+        this.requireValueExpectation();
+        if (isNumberChar(code) && code !== 43 && code !== 46 && code !== 69 && code !== 101) {
+          this.tokenState = 2 /* Number */;
+          this.token = text[index];
+          this.tokenTruncated = false;
+          return index + 1;
+        }
+        if (code >= 97 && code <= 122) {
+          this.tokenState = 3 /* Literal */;
+          this.token = text[index];
+          return index + 1;
+        }
+        throw this.error(`unexpected character ${JSON.stringify(text[index])}`);
+    }
+  }
+  scanString(text, index, length) {
+    if (!this.escape && this.unicodeHex === null) {
+      let end = index;
+      while (end < length) {
+        const code2 = text.charCodeAt(end);
+        if (code2 === CHAR_QUOTE2 || code2 === CHAR_BACKSLASH || code2 < 32) break;
+        end += 1;
+      }
+      if (end > index) {
+        const run = end - index;
+        this.stringLength += run;
+        if (this.stringCapture) this.captureString(text.slice(index, end));
+        this.column += run - 1;
+        if (end >= length) return end;
+        index = end;
+        this.chunkIndex = index;
+        this.column += 1;
+      }
+    }
+    const code = text.charCodeAt(index);
+    if (this.unicodeHex !== null) {
+      if (!(code >= 48 && code <= 57 || code >= 65 && code <= 70 || code >= 97 && code <= 102)) {
+        throw this.error("invalid \\u escape in string");
+      }
+      this.unicodeHex += text[index];
+      if (this.unicodeHex.length === 4) {
+        const decoded = String.fromCharCode(Number.parseInt(this.unicodeHex, 16));
+        this.unicodeHex = null;
+        this.stringLength += 1;
+        if (this.stringCapture) this.captureString(decoded);
+      }
+      return index + 1;
+    }
+    if (this.escape) {
+      this.escape = false;
+      if (code === 117) {
+        this.unicodeHex = "";
+        return index + 1;
+      }
+      const decoded = escapeChar(code);
+      if (decoded === null) throw this.error(`invalid escape \\${text[index]} in string`);
+      this.stringLength += 1;
+      if (this.stringCapture) this.captureString(decoded);
+      return index + 1;
+    }
+    if (code === CHAR_QUOTE2) {
+      this.completeString();
+      return index + 1;
+    }
+    if (code === CHAR_BACKSLASH) {
+      this.escape = true;
+      return index + 1;
+    }
+    if (code < 32) throw this.error("unescaped control character in string");
+    this.stringLength += 1;
+    if (this.stringCapture) this.captureString(text[index]);
+    return index + 1;
+  }
+  captureString(piece) {
+    const cap = this.stringIsKey ? KEY_CAPTURE_CAP : STRING_CAPTURE_CAP;
+    if (this.token.length >= cap) {
+      this.tokenTruncated = true;
+      return;
+    }
+    if (this.token.length + piece.length <= cap) {
+      this.token += piece;
+      return;
+    }
+    this.token += piece.slice(0, cap - this.token.length);
+    this.tokenTruncated = true;
+  }
+  completeString() {
+    this.tokenState = 0 /* None */;
+    if (this.stringIsKey) {
+      const top = this.stack[this.stack.length - 1];
+      top.expect = 3 /* Colon */;
+      this.expect = 3 /* Colon */;
+      this.dispatch(this.sink.onKey(this.token, this.stack.length, this.tokenTruncated));
+      return;
+    }
+    this.completeValue({
+      type: "string",
+      value: this.token,
+      literal: null,
+      captured: this.stringCapture,
+      length: this.stringLength,
+      truncated: this.tokenTruncated
+    });
+  }
+  appendNumberChar(char) {
+    if (this.token.length >= MAX_NUMBER_LITERAL_CHARS) {
+      this.tokenTruncated = true;
+      return;
+    }
+    this.token += char;
+  }
+  completeNumber() {
+    if (!this.tokenTruncated && !NUMBER_GRAMMAR.test(this.token)) {
+      throw this.error(`invalid number literal ${JSON.stringify(this.token)}`);
+    }
+    const literal = this.tokenTruncated ? `${this.token}\u2026` : this.token;
+    this.completeValue({
+      type: "number",
+      value: this.tokenTruncated ? Number.NaN : Number(this.token),
+      literal,
+      captured: true,
+      length: 0,
+      truncated: this.tokenTruncated
+    });
+  }
+  completeLiteral() {
+    this.tokenState = 0 /* None */;
+    const scalar = {
+      type: "null",
+      value: null,
+      literal: null,
+      captured: true,
+      length: 0,
+      truncated: false
+    };
+    if (this.token === "true") {
+      scalar.type = "boolean";
+      scalar.value = true;
+    } else if (this.token === "false") {
+      scalar.type = "boolean";
+      scalar.value = false;
+    } else if (this.token !== "null") {
+      throw this.error(`unexpected literal ${JSON.stringify(this.token)}`);
+    }
+    this.completeValue(scalar);
+  }
+  requireValueExpectation() {
+    if (this.expect !== 0 /* Value */ && this.expect !== 5 /* ValueOrEnd */) throw this.error(this.describeExpectation());
+  }
+  openContainer(kind) {
+    if (this.stack.length >= JSON_MAX_DEPTH) {
+      throw new DataRefusalError(
+        refusal("nesting-too-deep", `JSON nesting exceeds ${JSON_MAX_DEPTH} levels at line ${this.line}`, {
+          line: this.line,
+          column: this.column,
+          byteOffset: this.byteOffset()
+        })
+      );
+    }
+    const depth = this.stack.length;
+    if (depth > this.maxDepth) this.maxDepth = depth;
+    const container = { kind, count: 0, expect: kind === "object" ? 1 /* KeyOrEnd */ : 5 /* ValueOrEnd */ };
+    this.stack.push(container);
+    this.expect = container.expect;
+    this.dispatch(kind === "object" ? this.sink.onStartObject(depth) : this.sink.onStartArray(depth));
+  }
+  closeContainer(kind) {
+    const top = this.stack[this.stack.length - 1];
+    if (top === void 0 || top.kind !== kind) throw this.error(`unexpected ${kind === "object" ? "}" : "]"}`);
+    const canClose = this.expect === 4 /* CommaOrEnd */ || kind === "object" && this.expect === 1 /* KeyOrEnd */ || kind === "array" && this.expect === 5 /* ValueOrEnd */;
+    if (!canClose) throw this.error(this.describeExpectation());
+    this.stack.pop();
+    const depth = this.stack.length;
+    this.dispatch(kind === "object" ? this.sink.onEndObject(depth, top.count) : this.sink.onEndArray(depth, top.count));
+    if (this.stopped) return;
+    this.afterValue();
+  }
+  completeValue(scalar) {
+    this.dispatch(this.sink.onScalar(scalar, this.stack.length));
+    if (this.stopped) return;
+    this.afterValue();
+  }
+  afterValue() {
+    const top = this.stack[this.stack.length - 1];
+    if (top === void 0) {
+      this.rootComplete = true;
+      this.expect = 6 /* End */;
+      return;
+    }
+    top.count += 1;
+    top.expect = 4 /* CommaOrEnd */;
+    this.expect = 4 /* CommaOrEnd */;
+  }
+  dispatch(verdict) {
+    if (verdict === false) this.stopped = true;
+  }
+  describeExpectation() {
+    switch (this.expect) {
+      case 0 /* Value */:
+        return "expected a JSON value";
+      case 5 /* ValueOrEnd */:
+        return "expected a JSON value or ']'";
+      case 1 /* KeyOrEnd */:
+        return "expected a string key or '}'";
+      case 2 /* Key */:
+        return "expected a string key";
+      case 3 /* Colon */:
+        return "expected ':' after object key";
+      case 4 /* CommaOrEnd */:
+        return `expected ',' or '${this.stack[this.stack.length - 1].kind === "object" ? "}" : "]"}'`;
+      default:
+        return "unexpected content after the JSON value";
+    }
+  }
+  byteOffset() {
+    return this.chunkByteOffset + Buffer.byteLength(this.chunkText.slice(0, this.chunkIndex), "utf8");
+  }
+  error(message) {
+    const byteOffset = this.byteOffset();
+    return new DataRefusalError(
+      refusal("invalid-json", `${message} at line ${this.line} column ${this.column} (byte offset ${byteOffset})`, {
+        line: this.line,
+        column: this.column,
+        byteOffset
+      })
+    );
+  }
+};
+var JsonValueBuilder = class {
+  constructor(budgetChars, rootPointer) {
+    this.budgetChars = budgetChars;
+    this.rootPointer = rootPointer;
+  }
+  budgetChars;
+  rootPointer;
+  frames = [];
+  spent = 0;
+  exceeded = false;
+  summaryType = "object";
+  result;
+  done = false;
+  stringsCut = 0;
+  issues = [];
+  get complete() {
+    return this.done;
+  }
+  /** The budget ran out; the value is (or contains) a $summary placeholder. */
+  get overBudget() {
+    return this.exceeded;
+  }
+  /** Strings cut at the capture cap, each left as a $truncated placeholder. */
+  get cutStrings() {
+    return this.stringsCut;
+  }
+  /** Anything in the value stands in for content that was not carried. */
+  get truncated() {
+    return this.exceeded || this.stringsCut > 0;
+  }
+  get value() {
+    return this.result;
+  }
+  pointer() {
+    let pointer = this.rootPointer;
+    for (const frame of this.frames) {
+      pointer += frame.kind === "object" ? `/${(frame.key ?? "").replace(/~/gu, "~0").replace(/\//gu, "~1")}` : `/${frame.value.length}`;
+    }
+    return pointer;
+  }
+  charge(chars) {
+    if (this.exceeded) return false;
+    this.spent += chars;
+    if (this.spent > this.budgetChars) {
+      this.exceeded = true;
+      return false;
+    }
+    return true;
+  }
+  place(value) {
+    const frame = this.frames[this.frames.length - 1];
+    if (frame === void 0) {
+      this.result = value;
+      this.done = true;
+      return;
+    }
+    if (frame.kind === "array") frame.value.push(value);
+    else frame.value[frame.key ?? ""] = value;
+    frame.count += 1;
+  }
+  /**
+   * The budget ran out somewhere inside the subtree. Everything built so far
+   * is discarded and the whole subtree becomes one `$summary` placed when its
+   * root closes, carrying the root's true member count from the parser.
+   */
+  exhaust(rootKind) {
+    this.exceeded = true;
+    this.summaryType = this.frames[0]?.kind ?? rootKind;
+    this.frames.length = 0;
+  }
+  startContainer(kind, _relativeDepth) {
+    if (this.exceeded) return;
+    if (!this.charge(2)) {
+      this.exhaust(kind);
+      return;
+    }
+    this.frames.push({ kind, value: kind === "object" ? {} : [], key: null, count: 0 });
+  }
+  key(name, _relativeDepth) {
+    if (this.exceeded) return;
+    const frame = this.frames[this.frames.length - 1];
+    if (frame === void 0) return;
+    if (!this.charge(name.length + 4)) {
+      this.exhaust(frame.kind);
+      return;
+    }
+    frame.key = name;
+  }
+  endContainer(kind, relativeDepth, count) {
+    if (this.exceeded) {
+      if (relativeDepth === 0) {
+        this.result = {
+          $summary: this.summaryType === "object" ? { type: "object", members: count, reason: "budget" } : { type: "array", length: count, reason: "budget" }
+        };
+        this.done = true;
+      }
+      return;
+    }
+    const frame = this.frames.pop();
+    if (frame === void 0 || frame.kind !== kind) return;
+    this.place(frame.value);
+  }
+  scalar(scalar, _relativeDepth) {
+    if (this.exceeded) return;
+    const cost = scalar.type === "string" ? scalar.length + 2 : scalar.literal?.length ?? 4;
+    if (!this.charge(cost)) {
+      const frame = this.frames[this.frames.length - 1];
+      if (frame === void 0) {
+        this.exceeded = false;
+        this.spent = 0;
+      } else {
+        this.exhaust(frame.kind);
+        return;
+      }
+    }
+    if (scalar.type === "number") {
+      const literal = scalar.literal ?? "";
+      const precision = scalar.truncated ? "oversized-literal" : numberLiteralPrecision(literal);
+      if (precision !== null) {
+        this.issues.push({ kind: precision, literal, path: this.pointer() });
+        this.place({ $literal: literal, precision });
+        return;
+      }
+      this.place(scalar.value);
+      return;
+    }
+    if (scalar.type === "string") {
+      if (scalar.truncated) {
+        this.stringsCut += 1;
+        this.place({ $truncated: "string", length: scalar.length, text: scalar.value });
+      } else this.place(scalar.value);
+      return;
+    }
+    this.place(scalar.value);
+  }
+};
+function escapePointerSegment(segment) {
+  return segment.replace(/~/gu, "~0").replace(/\//gu, "~1");
+}
+function parseJsonPointer(pointer) {
+  if (pointer === "") return [];
+  if (!pointer.startsWith("/")) return new Error("JSON pointer must start with '/' or be empty for the whole document");
+  return pointer.slice(1).split("/").map((segment) => segment.replace(/~1/gu, "/").replace(/~0/gu, "~"));
+}
+var PathTracker = class {
+  segments = [];
+  kinds = [];
+  indexes = [];
+  startContainer(kind) {
+    this.kinds.push(kind);
+    this.indexes.push(0);
+    this.segments.push(kind === "array" ? "0" : "");
+  }
+  key(name) {
+    this.segments[this.segments.length - 1] = name;
+  }
+  endContainer() {
+    this.kinds.pop();
+    this.indexes.pop();
+    this.segments.pop();
+  }
+  /** Advance after a value completes inside the current container. */
+  advance() {
+    const top = this.kinds.length - 1;
+    if (top < 0) return;
+    if (this.kinds[top] === "array") {
+      const next = this.indexes[top] + 1;
+      this.indexes[top] = next;
+      this.segments[top] = String(next);
+    }
+  }
+  pointer() {
+    return this.segments.map((segment) => `/${escapePointerSegment(segment)}`).join("");
+  }
+  /** Pointer of the innermost open container. */
+  containerPointer() {
+    return this.segments.slice(0, -1).map((segment) => `/${escapePointerSegment(segment)}`).join("");
+  }
+};
+var DUPLICATE_KEY_TRACK_CAP = 1e4;
+var KEY_LIST_CAP = 200;
+var PRECISION_FIRST_CAP = 20;
+var SAMPLE_BUDGET_CHARS = 8192;
+var SELECT_BUDGET_CHARS = 1048576;
+var StructureScanner = class {
+  constructor(pointerPrefix = "") {
+    this.pointerPrefix = pointerPrefix;
+  }
+  pointerPrefix;
+  path = new PathTracker();
+  frames = [];
+  duplicateCount = 0;
+  duplicateFirst = null;
+  duplicateCheckedFully = true;
+  precisionCount = 0;
+  precisionFirst = [];
+  startContainer(kind) {
+    this.path.startContainer(kind);
+    this.frames.push({ seen: kind === "object" ? /* @__PURE__ */ new Set() : null, overCap: false });
+  }
+  key(name) {
+    this.path.key(name);
+    const frame = this.frames[this.frames.length - 1];
+    if (frame?.seen === null || frame === void 0) return;
+    if (frame.overCap) return;
+    if (frame.seen.has(name)) {
+      this.duplicateCount += 1;
+      if (this.duplicateFirst === null) {
+        this.duplicateFirst = { path: this.pointerPrefix + this.path.containerPointer(), key: name };
+      }
+      return;
+    }
+    if (frame.seen.size >= DUPLICATE_KEY_TRACK_CAP) {
+      frame.overCap = true;
+      frame.seen = null;
+      this.duplicateCheckedFully = false;
+      return;
+    }
+    frame.seen.add(name);
+  }
+  endContainer() {
+    this.frames.pop();
+    this.path.endContainer();
+    this.path.advance();
+  }
+  scalar(scalar) {
+    if (scalar.type === "number") {
+      const literal = scalar.literal ?? "";
+      const precision = scalar.truncated ? "oversized-literal" : numberLiteralPrecision(literal);
+      if (precision !== null) {
+        this.precisionCount += 1;
+        if (this.precisionFirst.length < PRECISION_FIRST_CAP) {
+          this.precisionFirst.push({ kind: precision, literal, path: this.pointerPrefix + this.path.pointer() });
+        }
+      }
+    }
+    this.path.advance();
+  }
+  duplicates() {
+    return { count: this.duplicateCount, first: this.duplicateFirst, checkedFully: this.duplicateCheckedFully };
+  }
+  precision() {
+    return { count: this.precisionCount, first: [...this.precisionFirst] };
+  }
+};
+var JSON_DEFAULT_SAMPLE_ROWS = 10;
+var JSON_DEFAULT_MAX_ROWS = 1e5;
+var InspectSink = class {
+  constructor(sampleRows, maxRows) {
+    this.sampleRows = sampleRows;
+    this.maxRows = maxRows;
+  }
+  sampleRows;
+  maxRows;
+  scanner = new StructureScanner();
+  root = null;
+  rows = 0;
+  rowCount = null;
+  stoppedAtRows = false;
+  keys = [];
+  keysTruncated = false;
+  types = /* @__PURE__ */ new Map();
+  sample = [];
+  /** Sample values that carry a $summary or $truncated placeholder; the counts stay exact. */
+  sampleCuts = 0;
+  rootValue;
+  builder = null;
+  builderDepth = 0;
+  currentKey = "";
+  sampleIssues = [];
+  countType(type) {
+    this.types.set(type, (this.types.get(type) ?? 0) + 1);
+  }
+  /** A depth-1 value begins: count it, decide whether it is sampled, or stop at the row bound. */
+  beginRow(type) {
+    if (this.rows >= this.maxRows) {
+      this.stoppedAtRows = true;
+      return false;
+    }
+    this.rows += 1;
+    this.countType(type);
+    if (this.sample.length < this.sampleRows) {
+      const pointer = this.root === "array" ? `/${this.rows - 1}` : `/${escapePointerSegment(this.currentKey)}`;
+      this.builder = new JsonValueBuilder(SAMPLE_BUDGET_CHARS, pointer);
+      this.builderDepth = 1;
+    }
+    return true;
+  }
+  finishSampled() {
+    const builder = this.builder;
+    if (builder === null || !builder.complete) return;
+    this.builder = null;
+    if (builder.truncated) this.sampleCuts += 1;
+    const value = builder.value;
+    if (this.root === "array") this.sample.push(value);
+    else this.sample.push({ key: this.currentKey, value });
+    this.sampleIssues.push(...builder.issues);
+  }
+  onStartObject(depth) {
+    if (depth === 0) {
+      this.root = "object";
+      this.scanner.startContainer("object");
+      return void 0;
+    }
+    if (depth === 1 && !this.beginRow("object")) return false;
+    this.scanner.startContainer("object");
+    this.builder?.startContainer("object", depth - this.builderDepth);
+    return void 0;
+  }
+  onStartArray(depth) {
+    if (depth === 0) {
+      this.root = "array";
+      this.scanner.startContainer("array");
+      return void 0;
+    }
+    if (depth === 1 && !this.beginRow("array")) return false;
+    this.scanner.startContainer("array");
+    this.builder?.startContainer("array", depth - this.builderDepth);
+    return void 0;
+  }
+  onKey(key, depth, truncated) {
+    this.scanner.key(key);
+    if (depth === 1) {
+      if (this.rows >= this.maxRows) {
+        this.stoppedAtRows = true;
+        return false;
+      }
+      this.currentKey = truncated ? `${key}\u2026` : key;
+      if (this.keys.length < KEY_LIST_CAP) this.keys.push(this.currentKey);
+      else this.keysTruncated = true;
+      return void 0;
+    }
+    this.builder?.key(key, depth - this.builderDepth);
+    return void 0;
+  }
+  onEndObject(depth, memberCount) {
+    if (depth === 0) {
+      this.rowCount = memberCount;
+      return void 0;
+    }
+    this.scanner.endContainer();
+    this.builder?.endContainer("object", depth - this.builderDepth, memberCount);
+    if (depth === 1) this.finishSampled();
+    return void 0;
+  }
+  onEndArray(depth, length) {
+    if (depth === 0) {
+      this.rowCount = length;
+      return void 0;
+    }
+    this.scanner.endContainer();
+    this.builder?.endContainer("array", depth - this.builderDepth, length);
+    if (depth === 1) this.finishSampled();
+    return void 0;
+  }
+  onScalar(scalar, depth) {
+    if (depth === 0) {
+      this.root = scalar.type;
+      this.rows = 1;
+      this.rowCount = 1;
+      const builder = new JsonValueBuilder(SAMPLE_BUDGET_CHARS, "");
+      builder.scalar(scalar, 0);
+      this.rootValue = builder.value;
+      this.sampleIssues.push(...builder.issues);
+      this.scanner.scalar(scalar);
+      return void 0;
+    }
+    if (depth === 1 && !this.beginRow(scalar.type)) return false;
+    this.scanner.scalar(scalar);
+    this.builder?.scalar(scalar, depth - this.builderDepth);
+    if (depth === 1) this.finishSampled();
+    return void 0;
+  }
+  captureStrings(depth) {
+    if (depth === 0) return true;
+    if (depth === 1) return this.rows < this.maxRows && this.sample.length < this.sampleRows;
+    return this.builder !== null && !this.builder.overBudget;
+  }
+  /** Precision issues seen inside sampled values that the scanner already counted; used only for cross-checks. */
+  get sampledIssues() {
+    return this.sampleIssues;
+  }
+};
+async function runParser(path2, sink, signal, stats) {
+  const parser = new JsonStreamParser(sink);
+  for await (const chunk of streamTextChunks(path2, { signal, stats })) {
+    if (!parser.push(chunk.text, chunk.byteOffset)) return { parser, stopped: true };
+  }
+  parser.end();
+  throwIfAborted(signal, path2);
+  return { parser, stopped: parser.isStopped };
+}
+async function inspectJson(path2, options = {}) {
+  const stat = statDataFile(path2);
+  if ("ok" in stat) return stat;
+  const sampleRows = Math.max(0, Math.min(1e3, Math.floor(options.sampleRows ?? JSON_DEFAULT_SAMPLE_ROWS)));
+  const maxRows = resolveMaxRows(options.maxRows, JSON_DEFAULT_MAX_ROWS);
+  const stats = { bytesRead: 0, bom: false };
+  const sink = new InspectSink(sampleRows, maxRows);
+  let parser;
+  try {
+    parser = (await runParser(path2, sink, options.signal, stats)).parser;
+  } catch (error) {
+    return refusalFromError(error, path2, options.signal);
+  }
+  const sampled = sink.stoppedAtRows;
+  const notes = [];
+  if (stats.bom) notes.push("a UTF-8 byte-order mark was stripped");
+  if (sampled) notes.push(sampledNotice(sink.rows, sink.root === "object" ? "members" : "elements"));
+  if (sink.sampleCuts > 0) {
+    notes.push(
+      `${sink.sampleCuts} sample value(s) were cut to the preview budget and carry $summary or $truncated placeholders; the counts are exact`
+    );
+  }
+  if (!sink.scanner.duplicateCheckedFully) {
+    notes.push(
+      `duplicate-key tracking stopped at ${DUPLICATE_KEY_TRACK_CAP} keys in one object; later duplicates there are unreported`
+    );
+  }
+  if (sink.keysTruncated) notes.push(`key list capped at ${KEY_LIST_CAP} names`);
+  const root = sink.root ?? "null";
+  const result = {
+    ok: true,
+    format: "json",
+    path: path2,
+    bytes: stat.size,
+    bytesScanned: stats.bytesRead,
+    view: sampled ? sampledView() : exactView(),
+    rowsScanned: sink.rows,
+    rowCount: sampled ? null : sink.rowCount,
+    root,
+    maxDepth: parser.maxDepth,
+    duplicateKeys: sink.scanner.duplicates(),
+    precision: sink.scanner.precision(),
+    sample: sink.sample,
+    notes
+  };
+  const types = {};
+  for (const [type, count] of sink.types) types[type] = count;
+  if (root === "array") result.elementTypes = types;
+  else if (root === "object") {
+    result.keys = { names: sink.keys, truncated: sink.keysTruncated };
+    result.memberTypes = types;
+  } else if (sink.rootValue !== void 0) result.value = sink.rootValue;
+  return result;
+}
+var JSON_SELECT_DEFAULT_LIMIT = 50;
+var JSON_SELECT_MAX_LIMIT = 1e3;
+var SelectSink = class {
+  constructor(segments, windowOffset, windowLimit) {
+    this.segments = segments;
+    this.windowOffset = windowOffset;
+    this.windowLimit = windowLimit;
+  }
+  segments;
+  windowOffset;
+  windowLimit;
+  path = new PathTracker();
+  phase = "seeking";
+  targetDepth = -1;
+  found = false;
+  targetType = null;
+  builder = null;
+  /** Array-window mode state. */
+  windowed = false;
+  elementIndex = 0;
+  elements = [];
+  hasMore = false;
+  issues = [];
+  tooLarge = false;
+  cutStrings = 0;
+  /** Deepest matched prefix length, for the not-found message. */
+  deepestMatch = 0;
+  /** Per-object key sets inside the captured value; null past the tracking cap. */
+  keySets = [];
+  duplicateCount = 0;
+  duplicateFirst = null;
+  duplicatesCheckedFully = true;
+  trackObjectStart() {
+    if (this.builder !== null) this.keySets.push(/* @__PURE__ */ new Set());
+  }
+  trackKey(key) {
+    if (this.builder === null) return;
+    const keys = this.keySets[this.keySets.length - 1];
+    if (keys === null || keys === void 0) return;
+    if (keys.has(key)) {
+      this.duplicateCount += 1;
+      if (this.duplicateFirst === null) this.duplicateFirst = { path: this.path.containerPointer(), key };
+      return;
+    }
+    if (keys.size >= DUPLICATE_KEY_TRACK_CAP) {
+      this.duplicatesCheckedFully = false;
+      this.keySets[this.keySets.length - 1] = null;
+      return;
+    }
+    keys.add(key);
+  }
+  trackObjectEnd() {
+    if (this.builder !== null) this.keySets.pop();
+  }
+  pointerMatches() {
+    const current = this.path.segments;
+    if (current.length !== this.segments.length) return false;
+    for (let index = 0; index < current.length; index += 1) {
+      if (current[index] !== this.segments[index]) return false;
+    }
+    return true;
+  }
+  prefixMatches() {
+    const current = this.path.segments;
+    if (current.length > this.segments.length) return false;
+    for (let index = 0; index < current.length; index += 1) {
+      if (current[index] !== this.segments[index]) return false;
+    }
+    if (current.length > this.deepestMatch) this.deepestMatch = current.length;
+    return true;
+  }
+  beginTarget(type, depth) {
+    this.found = true;
+    this.targetType = type;
+    this.targetDepth = depth;
+    this.phase = "capturing";
+    if (type === "array" && this.windowOffset !== null) {
+      this.windowed = true;
+      return;
+    }
+    this.builder = new JsonValueBuilder(SELECT_BUDGET_CHARS, this.path.pointer());
+  }
+  finishBuilder() {
+    const builder = this.builder;
+    if (builder === null || !builder.complete) return void 0;
+    this.builder = null;
+    if (builder.overBudget) {
+      this.tooLarge = true;
+      return false;
+    }
+    this.cutStrings += builder.cutStrings;
+    this.issues.push(...builder.issues);
+    if (this.windowed) {
+      this.elements.push(builder.value);
+      if (this.elements.length >= this.windowLimit) {
+        return void 0;
+      }
+      return void 0;
+    }
+    this.value = builder.value;
+    this.phase = "done";
+    return false;
+  }
+  value;
+  beginElement(type, depth) {
+    if (!this.windowed || depth !== this.targetDepth + 1) return void 0;
+    const index = this.elementIndex;
+    this.elementIndex += 1;
+    const offset = this.windowOffset;
+    if (index < offset) return void 0;
+    if (this.elements.length >= this.windowLimit) {
+      this.hasMore = true;
+      this.phase = "done";
+      return false;
+    }
+    this.builder = new JsonValueBuilder(SELECT_BUDGET_CHARS, `${this.path.pointer()}`);
+    void type;
+    return void 0;
+  }
+  onStartObject(depth) {
+    if (this.phase === "seeking") {
+      if (this.pointerMatches()) {
+        this.beginTarget("object", depth);
+        this.builder?.startContainer("object", 0);
+      } else this.prefixMatches();
+    } else if (this.phase === "capturing") {
+      const stop = this.beginElement("object", depth);
+      if (stop === false) return false;
+      this.builder?.startContainer("object", depth - (this.windowed ? this.targetDepth + 1 : this.targetDepth));
+    }
+    this.trackObjectStart();
+    this.path.startContainer("object");
+    return void 0;
+  }
+  onStartArray(depth) {
+    if (this.phase === "seeking") {
+      if (this.pointerMatches()) {
+        this.beginTarget("array", depth);
+        this.builder?.startContainer("array", 0);
+      } else this.prefixMatches();
+    } else if (this.phase === "capturing") {
+      const stop = this.beginElement("array", depth);
+      if (stop === false) return false;
+      this.builder?.startContainer("array", depth - (this.windowed ? this.targetDepth + 1 : this.targetDepth));
+    }
+    this.path.startContainer("array");
+    return void 0;
+  }
+  onKey(key, depth) {
+    this.path.key(key);
+    if (this.phase === "seeking") this.prefixMatches();
+    else if (this.phase === "capturing") {
+      this.trackKey(key);
+      this.builder?.key(key, depth - (this.windowed ? this.targetDepth + 1 : this.targetDepth));
+    }
+    return void 0;
+  }
+  onEndObject(depth, memberCount) {
+    this.trackObjectEnd();
+    this.path.endContainer();
+    this.path.advance();
+    if (this.phase !== "capturing") return void 0;
+    if (this.windowed) {
+      if (depth === this.targetDepth) {
+        this.phase = "done";
+        return false;
+      }
+      this.builder?.endContainer("object", depth - (this.targetDepth + 1), memberCount);
+      if (depth === this.targetDepth + 1) return this.finishBuilder();
+      return void 0;
+    }
+    this.builder?.endContainer("object", depth - this.targetDepth, memberCount);
+    if (depth === this.targetDepth) return this.finishBuilder();
+    return void 0;
+  }
+  onEndArray(depth, length) {
+    this.path.endContainer();
+    this.path.advance();
+    if (this.phase !== "capturing") return void 0;
+    if (this.windowed) {
+      if (depth === this.targetDepth) {
+        this.phase = "done";
+        return false;
+      }
+      this.builder?.endContainer("array", depth - (this.targetDepth + 1), length);
+      if (depth === this.targetDepth + 1) return this.finishBuilder();
+      return void 0;
+    }
+    this.builder?.endContainer("array", depth - this.targetDepth, length);
+    if (depth === this.targetDepth) return this.finishBuilder();
+    return void 0;
+  }
+  onScalar(scalar, depth) {
+    let verdict;
+    if (this.phase === "seeking") {
+      if (this.pointerMatches()) {
+        this.beginTarget(scalar.type, depth);
+        this.builder?.scalar(scalar, 0);
+        verdict = this.finishBuilder();
+      } else this.prefixMatches();
+    } else if (this.phase === "capturing") {
+      const stop = this.beginElement(scalar.type, depth);
+      if (stop === false) return false;
+      if (this.windowed) {
+        this.builder?.scalar(scalar, depth - (this.targetDepth + 1));
+        if (depth === this.targetDepth + 1) verdict = this.finishBuilder();
+      } else {
+        this.builder?.scalar(scalar, depth - this.targetDepth);
+      }
+    }
+    this.path.advance();
+    return verdict;
+  }
+  captureStrings(depth) {
+    if (this.phase === "seeking") return this.pointerMatches();
+    if (this.phase !== "capturing") return false;
+    if (this.windowed && depth === this.targetDepth + 1) {
+      return this.elementIndex >= this.windowOffset && this.elements.length < this.windowLimit;
+    }
+    return this.builder !== null && !this.builder.overBudget;
+  }
+};
+async function selectJson(path2, options = {}) {
+  const stat = statDataFile(path2);
+  if ("ok" in stat) return stat;
+  const pointer = options.pointer ?? "";
+  const segments = parseJsonPointer(pointer);
+  if (segments instanceof Error) return refusal("invalid-argument", segments.message, { path: path2 });
+  const windowed = options.offset !== void 0 || options.limit !== void 0;
+  const offset = windowed ? Math.max(0, Math.floor(options.offset ?? 0)) : null;
+  const limit = Math.max(1, Math.min(JSON_SELECT_MAX_LIMIT, Math.floor(options.limit ?? JSON_SELECT_DEFAULT_LIMIT)));
+  const stats = { bytesRead: 0, bom: false };
+  const sink = new SelectSink(segments, offset, limit);
+  let stopped = false;
+  try {
+    stopped = (await runParser(path2, sink, options.signal, stats)).stopped;
+  } catch (error) {
+    return refusalFromError(error, path2, options.signal);
+  }
+  if (sink.tooLarge) {
+    const where = pointer || "the document root";
+    return refusal(
+      "selection-too-large",
+      windowed ? `an element of the array at ${where} exceeds the ${SELECT_BUDGET_CHARS}-character selection budget; select a deeper pointer into that element, or a window of 1 to isolate it` : `the value at ${where} exceeds the ${SELECT_BUDGET_CHARS}-character selection budget; select a deeper pointer or an array window with offset and limit`,
+      { path: path2 }
+    );
+  }
+  if (!sink.found) {
+    const matched = segments.slice(0, sink.deepestMatch);
+    const matchedPointer = matched.map((segment) => `/${escapePointerSegment(segment)}`).join("");
+    return refusal(
+      "pointer-not-found",
+      `no value at ${pointer}; the deepest existing prefix is ${matchedPointer === "" ? "the document root" : matchedPointer}`,
+      { path: path2 }
+    );
+  }
+  const notes = [];
+  if (stats.bom) notes.push("a UTF-8 byte-order mark was stripped");
+  if (stopped) {
+    notes.push("reading stopped once the selection was complete; the rest of the document was not checked for syntax");
+  }
+  if (sink.cutStrings > 0) {
+    notes.push(
+      `${sink.cutStrings} string(s) longer than ${STRING_CAPTURE_CAP} characters were cut; each is a $truncated placeholder with its full length`
+    );
+  }
+  if (sink.duplicateCount > 0) {
+    notes.push(`${sink.duplicateCount} duplicate object key(s) inside the selection; the last value was kept`);
+  }
+  const precision = {
+    count: sink.issues.length,
+    first: sink.issues.slice(0, PRECISION_FIRST_CAP)
+  };
+  const base = {
+    ok: true,
+    format: "json",
+    path: path2,
+    bytes: stat.size,
+    bytesScanned: stats.bytesRead,
+    view: sink.cutStrings > 0 ? cutView() : exactView(),
+    pointer,
+    precision,
+    duplicateKeys: {
+      count: sink.duplicateCount,
+      first: sink.duplicateFirst,
+      checkedFully: sink.duplicatesCheckedFully
+    },
+    notes
+  };
+  if (windowed) {
+    if (sink.targetType !== "array") {
+      return refusal(
+        "invalid-argument",
+        `offset and limit apply to an array target; the value at ${pointer || "the document root"} is ${sink.targetType ?? "unknown"}`,
+        { path: path2 }
+      );
+    }
+    return {
+      ...base,
+      elements: sink.elements,
+      offset,
+      limit,
+      returned: sink.elements.length,
+      hasMore: sink.hasMore
+    };
+  }
+  return { ...base, value: sink.value ?? null };
+}
+var ValidateSink = class {
+  constructor(maxRows) {
+    this.maxRows = maxRows;
+  }
+  maxRows;
+  scanner = new StructureScanner();
+  root = null;
+  rows = 0;
+  rowCount = null;
+  stoppedAtRows = false;
+  beginRow() {
+    if (this.rows >= this.maxRows) {
+      this.stoppedAtRows = true;
+      return false;
+    }
+    this.rows += 1;
+    return true;
+  }
+  onStartObject(depth) {
+    if (depth === 0) this.root = "object";
+    else if (depth === 1 && !this.beginRow()) return false;
+    this.scanner.startContainer("object");
+    return void 0;
+  }
+  onStartArray(depth) {
+    if (depth === 0) this.root = "array";
+    else if (depth === 1 && !this.beginRow()) return false;
+    this.scanner.startContainer("array");
+    return void 0;
+  }
+  onKey(key, depth) {
+    if (depth === 1 && this.rows >= this.maxRows) {
+      this.stoppedAtRows = true;
+      return false;
+    }
+    this.scanner.key(key);
+    return void 0;
+  }
+  onEndObject(depth, memberCount) {
+    if (depth === 0) this.rowCount = memberCount;
+    this.scanner.endContainer();
+    return void 0;
+  }
+  onEndArray(depth, length) {
+    if (depth === 0) this.rowCount = length;
+    this.scanner.endContainer();
+    return void 0;
+  }
+  onScalar(scalar, depth) {
+    if (depth === 0) {
+      this.root = scalar.type;
+      this.rows = 1;
+      this.rowCount = 1;
+    } else if (depth === 1 && !this.beginRow()) return false;
+    this.scanner.scalar(scalar);
+    return void 0;
+  }
+  captureStrings() {
+    return false;
+  }
+};
+async function validateJson(path2, options = {}) {
+  const stat = statDataFile(path2);
+  if ("ok" in stat) return stat;
+  const maxRows = resolveMaxRows(options.maxRows, JSON_DEFAULT_MAX_ROWS);
+  const stats = { bytesRead: 0, bom: false };
+  const sink = new ValidateSink(maxRows);
+  const parser = new JsonStreamParser(sink);
+  let syntaxError;
+  try {
+    let stopped = false;
+    for await (const chunk of streamTextChunks(path2, { signal: options.signal, stats })) {
+      if (!parser.push(chunk.text, chunk.byteOffset)) {
+        stopped = true;
+        break;
+      }
+    }
+    if (!stopped) parser.end();
+    throwIfAborted(options.signal, path2);
+  } catch (error) {
+    if (error instanceof DataRefusalError && (error.refusal.reason === "invalid-json" || error.refusal.reason === "nesting-too-deep")) {
+      syntaxError = {
+        message: error.refusal.message,
+        ...error.refusal.line !== void 0 ? { line: error.refusal.line } : {},
+        ...error.refusal.column !== void 0 ? { column: error.refusal.column } : {},
+        ...error.refusal.byteOffset !== void 0 ? { byteOffset: error.refusal.byteOffset } : {}
+      };
+    } else {
+      return refusalFromError(error, path2, options.signal);
+    }
+  }
+  const complete = !sink.stoppedAtRows;
+  const notes = [];
+  if (stats.bom) notes.push("a UTF-8 byte-order mark was stripped");
+  if (!complete) {
+    notes.push(
+      `validation incomplete: stopped after ${sink.rows} top-level rows; pass maxRows null to validate the whole document`
+    );
+  }
+  if (sink.scanner.duplicateCount > 0)
+    notes.push(`${sink.scanner.duplicateCount} duplicate object key(s); JSON.parse would keep the last value`);
+  return {
+    ok: true,
+    format: "json",
+    path: path2,
+    bytes: stat.size,
+    bytesScanned: stats.bytesRead,
+    view: complete ? exactView() : sampledView(),
+    valid: syntaxError !== void 0 ? false : complete ? true : null,
+    complete,
+    rowsScanned: sink.rows,
+    rowCount: complete && syntaxError === void 0 ? sink.rowCount : null,
+    root: sink.root,
+    maxDepth: parser.maxDepth,
+    duplicateKeys: sink.scanner.duplicates(),
+    precision: sink.scanner.precision(),
+    ...syntaxError !== void 0 ? { syntaxError } : {},
+    notes
+  };
+}
+var TextScanSink = class {
+  scanner;
+  root = null;
+  keys = [];
+  memberTypes = /* @__PURE__ */ new Map();
+  currentKey = "";
+  builder;
+  constructor(pointerPrefix, budgetChars) {
+    this.scanner = new StructureScanner(pointerPrefix);
+    this.builder = budgetChars === null ? null : new JsonValueBuilder(budgetChars, "");
+  }
+  get value() {
+    return this.builder?.value;
+  }
+  get valueTruncated() {
+    return this.builder?.truncated ?? false;
+  }
+  noteMember(type, depth) {
+    if (depth !== 1) return;
+    if (this.root === "object") {
+      if (!this.memberTypes.has(this.currentKey)) this.memberTypes.set(this.currentKey, type);
+    }
+  }
+  onStartObject(depth) {
+    if (depth === 0) this.root = "object";
+    this.noteMember("object", depth);
+    this.scanner.startContainer("object");
+    this.builder?.startContainer("object", depth);
+    return void 0;
+  }
+  onStartArray(depth) {
+    if (depth === 0) this.root = "array";
+    this.noteMember("array", depth);
+    this.scanner.startContainer("array");
+    this.builder?.startContainer("array", depth);
+    return void 0;
+  }
+  onKey(key, depth) {
+    this.scanner.key(key);
+    if (depth === 1) {
+      this.currentKey = key;
+      this.keys.push(key);
+    }
+    this.builder?.key(key, depth);
+    return void 0;
+  }
+  onEndObject(depth, memberCount) {
+    this.scanner.endContainer();
+    this.builder?.endContainer("object", depth, memberCount);
+    return void 0;
+  }
+  onEndArray(depth, length) {
+    this.scanner.endContainer();
+    this.builder?.endContainer("array", depth, length);
+    return void 0;
+  }
+  onScalar(scalar, depth) {
+    if (depth === 0) this.root = scalar.type;
+    this.noteMember(scalar.type, depth);
+    this.scanner.scalar(scalar);
+    this.builder?.scalar(scalar, depth);
+    return void 0;
+  }
+  captureStrings() {
+    return this.builder !== null && !this.builder.overBudget;
+  }
+};
+function scanJsonText(text, options = {}) {
+  const sink = new TextScanSink(options.pointerPrefix ?? "", options.materializeBudgetChars ?? null);
+  const parser = new JsonStreamParser(sink);
+  parser.push(text, 0);
+  parser.end();
+  return {
+    root: sink.root ?? "null",
+    keys: sink.keys,
+    memberTypes: sink.memberTypes,
+    maxDepth: parser.maxDepth,
+    duplicateKeys: sink.scanner.duplicateCount,
+    precision: [...sink.scanner.precisionFirst],
+    value: sink.value,
+    valueTruncated: sink.valueTruncated
+  };
+}
+
+// src/tools/data/jsonl.ts
+init_esm_shims();
+var JSONL_DEFAULT_SAMPLE_ROWS = 10;
+var JSONL_DEFAULT_MAX_ROWS = 1e5;
+var KEY_HISTOGRAM_CAP = 500;
+var INVALID_FIRST_CAP = 10;
+function oversizedMessage(chars) {
+  return `line is ${chars} characters, over the ${JSONL_MAX_LINE_CHARS}-character limit for one JSONL record; skipped without being read (a whole JSON document saved as .jsonl looks like this: read it with format json)`;
+}
+var JSONL_MAX_LINE_CHARS = 1048576;
+async function forEachLine(path2, signal, stats, visitor) {
+  let carry = "";
+  let skipping = false;
+  let skippedChars = 0;
+  let line = 0;
+  let stopped = false;
+  const emit = (text) => {
+    line += 1;
+    const body = text.endsWith("\r") ? text.slice(0, -1) : text;
+    if (body.trim().length === 0) {
+      visitor.onBlank?.(line);
+      return true;
+    }
+    return visitor.onLine(body, line);
+  };
+  const emitOversized = (chars) => {
+    line += 1;
+    return visitor.onOversized(line, chars);
+  };
+  outer: for await (const chunk of streamTextChunks(path2, { signal, stats })) {
+    const text = chunk.text;
+    let start = 0;
+    for (; ; ) {
+      const newline = text.indexOf("\n", start);
+      if (newline === -1) break;
+      const span = newline - start;
+      if (skipping) {
+        skipping = false;
+        if (!emitOversized(skippedChars + span)) {
+          stopped = true;
+          break outer;
+        }
+      } else if (carry.length + span > JSONL_MAX_LINE_CHARS) {
+        const chars = carry.length + span;
+        carry = "";
+        if (!emitOversized(chars)) {
+          stopped = true;
+          break outer;
+        }
+      } else {
+        const lineText = carry.length === 0 ? text.slice(start, newline) : carry + text.slice(start, newline);
+        carry = "";
+        if (!emit(lineText)) {
+          stopped = true;
+          break outer;
+        }
+      }
+      start = newline + 1;
+    }
+    const rest = text.length - start;
+    if (rest === 0) continue;
+    if (skipping) skippedChars += rest;
+    else if (carry.length + rest > JSONL_MAX_LINE_CHARS) {
+      skipping = true;
+      skippedChars = carry.length + rest;
+      carry = "";
+    } else carry += text.slice(start);
+  }
+  throwIfAborted(signal, path2);
+  if (!stopped) {
+    if (skipping) emitOversized(skippedChars);
+    else if (carry.length > 0 && !emit(carry)) stopped = true;
+  }
+  return { lines: line, stopped };
+}
+async function inspectJsonl(path2, options = {}) {
+  const stat = statDataFile(path2);
+  if ("ok" in stat) return stat;
+  const sampleRows = Math.max(0, Math.min(1e3, Math.floor(options.sampleRows ?? JSONL_DEFAULT_SAMPLE_ROWS)));
+  const maxRows = resolveMaxRows(options.maxRows, JSONL_DEFAULT_MAX_ROWS);
+  const stats = { bytesRead: 0, bom: false };
+  const state = {
+    records: 0,
+    blank: 0,
+    stoppedAtRows: false,
+    invalidCount: 0,
+    invalidFirst: [],
+    rootTypes: /* @__PURE__ */ new Map(),
+    keys: /* @__PURE__ */ new Map(),
+    keysTruncated: false,
+    keyTypes: /* @__PURE__ */ new Map(),
+    maxDepth: 0,
+    duplicateCount: 0,
+    duplicateFirstLine: null,
+    precisionCount: 0,
+    precisionFirst: [],
+    sample: [],
+    sampleCuts: 0
+  };
+  let scanOutcome;
+  try {
+    scanOutcome = await forEachLine(path2, options.signal, stats, {
+      onBlank() {
+        state.blank += 1;
+      },
+      onOversized(line, chars) {
+        if (state.records >= maxRows) {
+          state.stoppedAtRows = true;
+          return false;
+        }
+        state.records += 1;
+        state.invalidCount += 1;
+        if (state.invalidFirst.length < INVALID_FIRST_CAP) {
+          state.invalidFirst.push({ line, message: oversizedMessage(chars) });
+        }
+        return true;
+      },
+      onLine(text, line) {
+        if (state.records >= maxRows) {
+          state.stoppedAtRows = true;
+          return false;
+        }
+        state.records += 1;
+        const wantSample = state.sample.length < sampleRows;
+        let scan;
+        try {
+          scan = scanJsonText(text, {
+            pointerPrefix: "",
+            materializeBudgetChars: wantSample ? SAMPLE_BUDGET_CHARS : null
+          });
+        } catch (error) {
+          if (!(error instanceof DataRefusalError)) throw error;
+          state.invalidCount += 1;
+          if (state.invalidFirst.length < INVALID_FIRST_CAP) {
+            state.invalidFirst.push({ line, message: error.refusal.message });
+          }
+          return true;
+        }
+        state.rootTypes.set(scan.root, (state.rootTypes.get(scan.root) ?? 0) + 1);
+        if (scan.root === "object") {
+          for (const key of new Set(scan.keys)) {
+            const seen = state.keys.get(key);
+            if (seen === void 0) {
+              if (state.keys.size >= KEY_HISTOGRAM_CAP) {
+                state.keysTruncated = true;
+                continue;
+              }
+              state.keys.set(key, 1);
+            } else state.keys.set(key, seen + 1);
+            const type = scan.memberTypes.get(key);
+            if (type === void 0) continue;
+            let types = state.keyTypes.get(key);
+            if (types === void 0) {
+              types = /* @__PURE__ */ new Map();
+              state.keyTypes.set(key, types);
+            }
+            types.set(type, (types.get(type) ?? 0) + 1);
+          }
+        }
+        if (scan.maxDepth > state.maxDepth) state.maxDepth = scan.maxDepth;
+        if (scan.duplicateKeys > 0) {
+          state.duplicateCount += scan.duplicateKeys;
+          if (state.duplicateFirstLine === null) state.duplicateFirstLine = line;
+        }
+        for (const issue of scan.precision) {
+          state.precisionCount += 1;
+          if (state.precisionFirst.length < PRECISION_FIRST_CAP) state.precisionFirst.push({ ...issue, line });
+        }
+        if (wantSample && scan.value !== void 0) {
+          state.sample.push({ line, value: scan.value });
+          if (scan.valueTruncated) state.sampleCuts += 1;
+        }
+        return true;
+      }
+    });
+  } catch (error) {
+    return refusalFromError(error, path2, options.signal);
+  }
+  const sampled = state.stoppedAtRows;
+  const notes = [];
+  if (stats.bom) notes.push("a UTF-8 byte-order mark was stripped");
+  if (sampled) notes.push(sampledNotice(state.records, "records"));
+  if (state.invalidCount > 0)
+    notes.push(`${state.invalidCount} line(s) are not valid JSON and are listed with their fault`);
+  if (state.keysTruncated) notes.push(`key histogram capped at ${KEY_HISTOGRAM_CAP} distinct keys`);
+  if (state.sampleCuts > 0) {
+    notes.push(
+      `${state.sampleCuts} sample record(s) were cut to the preview budget and carry $summary or $truncated placeholders; the counts are exact`
+    );
+  }
+  const keyTypes = {};
+  for (const [key, types] of state.keyTypes) keyTypes[key] = histogramRecord(types);
+  return {
+    ok: true,
+    format: "jsonl",
+    path: path2,
+    bytes: stat.size,
+    bytesScanned: stats.bytesRead,
+    view: sampled ? sampledView() : exactView(),
+    rowsScanned: state.records,
+    rowCount: sampled ? null : state.records,
+    linesScanned: scanOutcome.lines,
+    blankLines: state.blank,
+    invalid: { count: state.invalidCount, first: state.invalidFirst },
+    rootTypes: histogramRecord(state.rootTypes),
+    keys: { histogram: histogramRecord(state.keys), truncated: state.keysTruncated },
+    keyTypes,
+    maxDepth: state.maxDepth,
+    duplicateKeys: { count: state.duplicateCount, firstLine: state.duplicateFirstLine },
+    precision: { count: state.precisionCount, first: state.precisionFirst },
+    sample: state.sample,
+    notes
+  };
+}
+var JSONL_SELECT_DEFAULT_LIMIT = 50;
+var JSONL_SELECT_MAX_LIMIT = 1e3;
+var SELECT_LINE_BUDGET_CHARS = 1048576;
+async function selectJsonl(path2, options = {}) {
+  const stat = statDataFile(path2);
+  if ("ok" in stat) return stat;
+  const offset = Math.max(0, Math.floor(options.offset ?? 0));
+  const limit = Math.max(1, Math.min(JSONL_SELECT_MAX_LIMIT, Math.floor(options.limit ?? JSONL_SELECT_DEFAULT_LIMIT)));
+  const stats = { bytesRead: 0, bom: false };
+  const state = {
+    records: 0,
+    hasMore: false,
+    out: [],
+    precisionCount: 0,
+    precisionFirst: [],
+    duplicateCount: 0,
+    duplicateFirstLine: null
+  };
+  try {
+    await forEachLine(path2, options.signal, stats, {
+      onOversized(line, chars) {
+        const index = state.records;
+        state.records += 1;
+        if (index < offset) return true;
+        if (state.out.length >= limit) {
+          state.hasMore = true;
+          return false;
+        }
+        state.out.push({ line, error: oversizedMessage(chars) });
+        return true;
+      },
+      onLine(text, line) {
+        const index = state.records;
+        state.records += 1;
+        if (index < offset) return true;
+        if (state.out.length >= limit) {
+          state.hasMore = true;
+          return false;
+        }
+        try {
+          const scan = scanJsonText(text, { materializeBudgetChars: SELECT_LINE_BUDGET_CHARS });
+          for (const issue of scan.precision) {
+            state.precisionCount += 1;
+            if (state.precisionFirst.length < PRECISION_FIRST_CAP) state.precisionFirst.push({ ...issue, line });
+          }
+          if (scan.duplicateKeys > 0) {
+            state.duplicateCount += scan.duplicateKeys;
+            if (state.duplicateFirstLine === null) state.duplicateFirstLine = line;
+          }
+          state.out.push({ line, value: scan.value ?? null, truncated: scan.valueTruncated });
+        } catch (error) {
+          if (!(error instanceof DataRefusalError)) throw error;
+          state.out.push({ line, error: error.refusal.message });
+        }
+        return true;
+      }
+    });
+  } catch (error) {
+    return refusalFromError(error, path2, options.signal);
+  }
+  const notes = [];
+  if (stats.bom) notes.push("a UTF-8 byte-order mark was stripped");
+  const truncated = state.out.filter((record) => "truncated" in record && record.truncated).length;
+  if (truncated > 0) {
+    notes.push(
+      `${truncated} record(s) were cut to the per-record budget or the string cap; $summary and $truncated placeholders mark the cuts`
+    );
+  }
+  if (state.duplicateCount > 0) {
+    notes.push(`${state.duplicateCount} duplicate object key(s) in the returned records; the last value was kept`);
+  }
+  return {
+    ok: true,
+    format: "jsonl",
+    path: path2,
+    bytes: stat.size,
+    bytesScanned: stats.bytesRead,
+    view: truncated > 0 ? cutView() : exactView(),
+    offset,
+    limit,
+    returned: state.out.length,
+    hasMore: state.hasMore,
+    rowsScanned: state.records,
+    records: state.out,
+    precision: { count: state.precisionCount, first: state.precisionFirst },
+    duplicateKeys: { count: state.duplicateCount, firstLine: state.duplicateFirstLine },
+    notes
+  };
+}
+async function validateJsonl(path2, options = {}) {
+  const stat = statDataFile(path2);
+  if ("ok" in stat) return stat;
+  const maxRows = resolveMaxRows(options.maxRows, JSONL_DEFAULT_MAX_ROWS);
+  const stats = { bytesRead: 0, bom: false };
+  const state = {
+    records: 0,
+    blank: 0,
+    stoppedAtRows: false,
+    invalidCount: 0,
+    invalidFirst: [],
+    duplicateCount: 0,
+    duplicateFirstLine: null,
+    precisionCount: 0,
+    precisionFirst: []
+  };
+  let scanOutcome;
+  try {
+    scanOutcome = await forEachLine(path2, options.signal, stats, {
+      onBlank() {
+        state.blank += 1;
+      },
+      onOversized(line, chars) {
+        if (state.records >= maxRows) {
+          state.stoppedAtRows = true;
+          return false;
+        }
+        state.records += 1;
+        state.invalidCount += 1;
+        if (state.invalidFirst.length < INVALID_FIRST_CAP) {
+          state.invalidFirst.push({ line, message: oversizedMessage(chars) });
+        }
+        return true;
+      },
+      onLine(text, line) {
+        if (state.records >= maxRows) {
+          state.stoppedAtRows = true;
+          return false;
+        }
+        state.records += 1;
+        try {
+          const scan = scanJsonText(text);
+          if (scan.duplicateKeys > 0) {
+            state.duplicateCount += scan.duplicateKeys;
+            if (state.duplicateFirstLine === null) state.duplicateFirstLine = line;
+          }
+          for (const issue of scan.precision) {
+            state.precisionCount += 1;
+            if (state.precisionFirst.length < PRECISION_FIRST_CAP) state.precisionFirst.push({ ...issue, line });
+          }
+        } catch (error) {
+          if (!(error instanceof DataRefusalError)) throw error;
+          state.invalidCount += 1;
+          if (state.invalidFirst.length < INVALID_FIRST_CAP) {
+            state.invalidFirst.push({ line, message: error.refusal.message });
+          }
+        }
+        return true;
+      }
+    });
+  } catch (error) {
+    return refusalFromError(error, path2, options.signal);
+  }
+  const complete = !state.stoppedAtRows;
+  const notes = [];
+  if (stats.bom) notes.push("a UTF-8 byte-order mark was stripped");
+  if (!complete) {
+    notes.push(
+      `validation incomplete: stopped after ${state.records} records; pass maxRows null to validate the whole file`
+    );
+  }
+  if (state.invalidCount > 0) notes.push(`${state.invalidCount} line(s) are not valid JSON`);
+  if (state.duplicateCount > 0)
+    notes.push(`${state.duplicateCount} duplicate object key(s); JSON.parse would keep the last value`);
+  return {
+    ok: true,
+    format: "jsonl",
+    path: path2,
+    bytes: stat.size,
+    bytesScanned: stats.bytesRead,
+    view: complete ? exactView() : sampledView(),
+    valid: state.invalidCount > 0 ? false : complete ? true : null,
+    complete,
+    rowsScanned: state.records,
+    rowCount: complete ? state.records : null,
+    linesScanned: scanOutcome.lines,
+    blankLines: state.blank,
+    invalid: { count: state.invalidCount, first: state.invalidFirst },
+    duplicateKeys: { count: state.duplicateCount, firstLine: state.duplicateFirstLine },
+    precision: { count: state.precisionCount, first: state.precisionFirst },
+    notes
+  };
+}
+
+// src/tools/data/index.ts
+var EXTENSION_FORMATS = {
+  ".csv": "csv",
+  ".tsv": "tsv",
+  ".tab": "tsv",
+  ".json": "json",
+  ".jsonl": "jsonl",
+  ".ndjson": "jsonl"
+};
+var SNIFF_BYTES = 4096;
+async function detectDataFormat(path2, explicit) {
+  if (explicit !== void 0 && explicit !== null) {
+    const normalized = explicit.trim().toLowerCase();
+    return isDataFormat(normalized) ? normalized : null;
+  }
+  const byExtension = EXTENSION_FORMATS[extname(path2).toLowerCase()];
+  if (byExtension !== void 0) return byExtension;
+  let text;
+  try {
+    const handle = await open(path2, "r");
+    try {
+      const buffer = Buffer.alloc(SNIFF_BYTES);
+      const { bytesRead } = await handle.read(buffer, 0, SNIFF_BYTES, 0);
+      text = buffer.subarray(0, bytesRead).toString("utf8");
+    } finally {
+      await handle.close();
+    }
+  } catch {
+    return null;
+  }
+  if (text.startsWith("\uFEFF")) text = text.slice(1);
+  const trimmed = text.trimStart();
+  if (trimmed.length === 0) return null;
+  const first = trimmed[0];
+  if (first === "[" || first === "{") {
+    const lines = trimmed.split(/\r?\n/u).filter((line) => line.trim().length > 0);
+    const second = lines[1]?.trimStart()[0];
+    if (lines.length > 1 && (second === "{" || second === "[") && (lines[0] ?? "").trimEnd().endsWith("}")) {
+      return "jsonl";
+    }
+    return "json";
+  }
+  const firstLine = trimmed.split(/\r?\n/u)[0] ?? "";
+  if (firstLine.includes("	")) return "tsv";
+  if (firstLine.includes(",") || firstLine.includes(";") || firstLine.includes("|")) return "csv";
+  return null;
+}
+function unsupported(path2, explicit) {
+  const named = explicit === void 0 || explicit === null ? "" : ` (${JSON.stringify(explicit)})`;
+  return refusal(
+    "unsupported-format",
+    `${path2} is not a supported structured-data format${named}; supported formats are ${DATA_FORMATS.join(", ")}. Pass format explicitly for a file with an unusual extension, or use run_script with a library for binary scientific formats.`,
+    { path: path2, supported: DATA_FORMATS }
+  );
+}
+async function inspectData(path2, options = {}) {
+  const stat = statDataFile(path2);
+  if ("ok" in stat) return stat;
+  const format = await detectDataFormat(path2, options.format);
+  if (format === null) return unsupported(path2, options.format);
+  const shared = {
+    ...options.sampleRows !== void 0 ? { sampleRows: options.sampleRows } : {},
+    ...options.maxRows !== void 0 ? { maxRows: options.maxRows } : {},
+    signal: options.signal
+  };
+  try {
+    switch (format) {
+      case "csv":
+      case "tsv":
+        return await inspectCsv(path2, {
+          ...shared,
+          format,
+          ...options.delimiter !== void 0 ? { delimiter: options.delimiter } : {},
+          ...options.header !== void 0 ? { header: options.header } : {}
+        });
+      case "json":
+        return await inspectJson(path2, shared);
+      case "jsonl":
+        return await inspectJsonl(path2, shared);
+    }
+  } catch (error) {
+    return refusalFromError(error, path2, options.signal);
+  }
+}
+async function selectData(path2, options = {}) {
+  const stat = statDataFile(path2);
+  if ("ok" in stat) return stat;
+  const format = await detectDataFormat(path2, options.format);
+  if (format === null) return unsupported(path2, options.format);
+  const window = {
+    ...options.offset !== void 0 ? { offset: options.offset } : {},
+    ...options.limit !== void 0 ? { limit: options.limit } : {},
+    signal: options.signal
+  };
+  try {
+    switch (format) {
+      case "csv":
+      case "tsv":
+        return await selectCsv(path2, {
+          ...window,
+          format,
+          ...options.delimiter !== void 0 ? { delimiter: options.delimiter } : {},
+          ...options.header !== void 0 ? { header: options.header } : {},
+          ...options.columns !== void 0 ? { columns: options.columns } : {}
+        });
+      case "json":
+        if (options.columns !== void 0) {
+          return refusal("invalid-argument", "columns applies to CSV/TSV; use pointer for a JSON document", { path: path2 });
+        }
+        return await selectJson(path2, {
+          ...window,
+          ...options.pointer !== void 0 ? { pointer: options.pointer } : {}
+        });
+      case "jsonl":
+        if (options.pointer !== void 0) {
+          return refusal(
+            "invalid-argument",
+            "pointer applies to a JSON document; JSONL selects records by offset and limit",
+            {
+              path: path2
+            }
+          );
+        }
+        return await selectJsonl(path2, window);
+    }
+  } catch (error) {
+    return refusalFromError(error, path2, options.signal);
+  }
+}
+async function validateData(path2, options = {}) {
+  const stat = statDataFile(path2);
+  if ("ok" in stat) return stat;
+  const format = await detectDataFormat(path2, options.format);
+  if (format === null) return unsupported(path2, options.format);
+  const shared = {
+    ...options.maxRows !== void 0 ? { maxRows: options.maxRows } : {},
+    signal: options.signal
+  };
+  try {
+    switch (format) {
+      case "csv":
+      case "tsv":
+        return await validateCsv(path2, {
+          ...shared,
+          format,
+          ...options.delimiter !== void 0 ? { delimiter: options.delimiter } : {},
+          ...options.header !== void 0 ? { header: options.header } : {}
+        });
+      case "json":
+        return await validateJson(path2, shared);
+      case "jsonl":
+        return await validateJsonl(path2, shared);
+    }
+  } catch (error) {
+    return refusalFromError(error, path2, options.signal);
+  }
+}
+
+// src/tools/gateway/data-tool.ts
+function isDataOp(value) {
+  return DATA_OPS.includes(value);
+}
+function countResult(op, payload) {
+  if (op === "select") {
+    const result = payload;
+    const rows = result.rows ?? result.records ?? result.elements;
+    const returned = typeof result.returned === "number" ? result.returned : Array.isArray(rows) ? rows.length : 1;
+    const offset = typeof result.offset === "number" ? result.offset : 0;
+    const limit = typeof result.limit === "number" ? result.limit : returned;
+    const hasMore = result.hasMore === true;
+    const total = typeof result.total === "number" ? result.total : hasMore ? null : offset + returned;
+    return {
+      unit: "entries",
+      shownCount: returned,
+      totalCount: total,
+      truncated: hasMore,
+      ...hasMore ? { next: `offset=${offset + limit}` } : {}
+    };
+  }
+  return { unit: "results", shownCount: 1, totalCount: 1, truncated: false };
+}
+function describeDataView(view) {
+  const flags = typeof view === "object" && view !== null ? view : {};
+  if (flags.exact === true) return "exact";
+  const parts = [...flags.sampled === true ? ["sampled"] : [], ...flags.converted === true ? ["converted"] : []];
+  return parts.length > 0 ? parts.join(", ") : "value cut to budget";
+}
+function refusalResult(op, refusal2) {
+  return {
+    kind: "error",
+    message: `data: ${op} refused (${refusal2.reason}): ${refusal2.message}`,
+    details: { refusal: refusal2 }
+  };
+}
+function createDataTool(deps = {}) {
+  const getCwd = deps.getCwd ?? (() => process.cwd());
+  return {
+    ...dataToolSurface,
+    prepareAdmissionArguments: (args) => prepareDataAdmissionArguments(args, getCwd()),
+    async run(rawArgs, options) {
+      const args = prepareDataArguments(rawArgs);
+      const op = typeof args.op === "string" ? args.op : "";
+      if (!isDataOp(op)) {
+        return { kind: "error", message: `data: op must be inspect, select, or validate; got '${op}'` };
+      }
+      if (typeof args.path !== "string" || args.path.trim().length === 0) {
+        return { kind: "error", message: "data: path is required" };
+      }
+      const target = resolveToCwd(args.path.trim(), getCwd());
+      const reservation = reserveObservation(DATA_OBSERVATION_SELF_CAP_BYTES, options);
+      if (reservation.exhausted) {
+        return observationBudgetExhausted({
+          tool: DATA_TOOL_NAME,
+          unit: op === "select" ? "entries" : "results",
+          reservation,
+          subject: `${op} ${path.relative(getCwd(), target) || target}`,
+          hint: "Continue in a follow-up turn."
+        });
+      }
+      commitObservationReservation(reservation);
+      try {
+        const format = typeof args.format === "string" ? args.format : void 0;
+        const delimiter = typeof args.delimiter === "string" ? args.delimiter : void 0;
+        const header = headerArg(args.header);
+        const signal = options?.signal;
+        let result;
+        if (op === "inspect") {
+          const inspectOptions = {
+            ...format !== void 0 ? { format } : {},
+            ...delimiter !== void 0 ? { delimiter } : {},
+            ...header !== void 0 ? { header } : {},
+            ...typeof args.sample_rows === "number" ? { sampleRows: args.sample_rows } : {},
+            ...args.max_rows === null || typeof args.max_rows === "number" ? { maxRows: args.max_rows } : {},
+            signal
+          };
+          result = await inspectData(target, inspectOptions);
+        } else if (op === "select") {
+          const selectOptions = {
+            ...format !== void 0 ? { format } : {},
+            ...delimiter !== void 0 ? { delimiter } : {},
+            ...header !== void 0 ? { header } : {},
+            ...typeof args.offset === "number" ? { offset: args.offset } : {},
+            ...typeof args.limit === "number" ? { limit: args.limit } : {},
+            ...Array.isArray(args.columns) ? { columns: args.columns } : {},
+            ...typeof args.pointer === "string" ? { pointer: args.pointer } : {},
+            signal
+          };
+          result = await selectData(target, selectOptions);
+        } else {
+          const validateOptions = {
+            ...format !== void 0 ? { format } : {},
+            ...delimiter !== void 0 ? { delimiter } : {},
+            ...header !== void 0 ? { header } : {},
+            ...args.max_rows === null || typeof args.max_rows === "number" ? { maxRows: args.max_rows } : {},
+            signal
+          };
+          result = await validateData(target, validateOptions);
+        }
+        if (isDataRefusal(result)) {
+          releaseObservation(reservation);
+          return refusalResult(op, result);
+        }
+        const counted = countResult(op, result);
+        return finalizeObservation({
+          tool: DATA_TOOL_NAME,
+          unit: counted.unit,
+          format: "json",
+          output: JSON.stringify(result),
+          shownCount: counted.shownCount,
+          totalCount: counted.totalCount,
+          truncated: counted.truncated,
+          ...counted.next !== void 0 ? { next: counted.next } : {},
+          details: { op, path: target, format: result.format, view: result.view, viewLabel: describeDataView(result.view) },
+          reservation,
+          ...options ? { options } : {}
+        });
+      } catch (error) {
+        releaseObservation(reservation);
+        return { kind: "error", message: `data: ${error instanceof Error ? error.message : String(error)}` };
+      }
+    }
+  };
+}
+var dataTool = createDataTool();
+export {
+  DATA_OBSERVATION_SELF_CAP_BYTES,
+  DATA_TOOL_NAME,
+  createDataTool,
+  dataTool,
+  dataToolSurface,
+  prepareDataArguments
+};
+//# sourceMappingURL=data-tool-JJPBGMQJ.js.map