full-reverse 0.0.0-stage → 1.0.0

package/skills/full-reverse/schemas/review.schema.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://full-reverse.local/schemas/review.schema.json",
+  "title": "Full Reverse review (review.json)",
+  "description": "Written only by the verify specialist. Valid only for the exact digests of the inventory, evidence index, claims and specifications listed in reviewed_inputs, and for the exact investigation scope (objective, non-goals, question text/feature/build scope and build identities) summarized by reviewed_inputs.scope; any change invalidates closure.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "investigation_id", "reviewed_at", "reviewer", "reviewed_inputs", "validator_report", "dispositions", "findings", "verdict"],
+  "properties": {
+    "schema_version": { "const": "full-reverse.review/1" },
+    "investigation_id": { "$ref": "common.schema.json#/$defs/investigationId" },
+    "reviewed_at": { "$ref": "common.schema.json#/$defs/timestamp" },
+    "reviewer": { "$ref": "common.schema.json#/$defs/nonEmptyString" },
+    "reviewed_inputs": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["inventory", "evidence_index", "claims", "specs", "scope"],
+      "properties": {
+        "inventory": { "oneOf": [{ "$ref": "common.schema.json#/$defs/fileDigest" }, { "type": "null" }] },
+        "evidence_index": { "$ref": "common.schema.json#/$defs/fileDigest" },
+        "claims": { "$ref": "common.schema.json#/$defs/fileDigest" },
+        "specs": { "type": "array", "items": { "$ref": "common.schema.json#/$defs/fileDigest" } },
+        "scope": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["sha256"],
+          "description": "Canonical scope digest from `digests` (reviewed_inputs_template.scope). Covers objective, non_goals, question ids/text/feature/build_ids and build identities; excludes question status/reason/claim_ids, steps, authorizations, phase and lifecycle so lifecycle updates do not invalidate the review.",
+          "properties": { "sha256": { "$ref": "common.schema.json#/$defs/sha256" } }
+        }
+      }
+    },
+    "validator_report": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["mode", "outcome", "failed", "unverified", "note"],
+      "description": "Summary of the deterministic validate run the reviewer relied on. Informational; closure always reruns the validator.",
+      "properties": {
+        "mode": { "enum": ["progress", "resume", "closure"] },
+        "outcome": { "enum": ["pass", "fail", "blocked"] },
+        "failed": { "type": "integer", "minimum": 0 },
+        "unverified": { "type": "integer", "minimum": 0 },
+        "note": { "type": "string" }
+      }
+    },
+    "dispositions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["question_id", "disposition", "reason", "claim_ids"],
+        "properties": {
+          "question_id": { "$ref": "common.schema.json#/$defs/questionId" },
+          "disposition": { "enum": ["answered", "partial", "unresolved"] },
+          "reason": { "$ref": "common.schema.json#/$defs/nonEmptyString" },
+          "claim_ids": { "type": "array", "items": { "$ref": "common.schema.json#/$defs/claimId" } }
+        }
+      }
+    },
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["finding_id", "severity", "category", "claim_id", "text", "status", "route_to"],
+        "properties": {
+          "finding_id": { "$ref": "common.schema.json#/$defs/findingId" },
+          "severity": { "enum": ["blocking", "major", "minor", "note"] },
+          "category": { "enum": ["structural", "semantic-overclaim", "coverage", "contradiction", "other"] },
+          "claim_id": { "oneOf": [{ "$ref": "common.schema.json#/$defs/claimId" }, { "type": "null" }] },
+          "text": { "$ref": "common.schema.json#/$defs/nonEmptyString" },
+          "status": { "enum": ["open", "resolved", "accepted-limitation"] },
+          "route_to": { "enum": ["inspect", "observe", "model", null] }
+        }
+      }
+    },
+    "verdict": { "enum": ["approved", "approved-with-limits", "changes-requested", "blocked"] }
+  }
+}

package/skills/full-reverse/scripts/lib/cli.mjs

@@ -0,0 +1,254 @@
+// Command dispatcher. Every command prints one JSON object on stdout.
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { DEFAULT_MAX_PARSE_BYTES, inspectFile, locateValues, pointerSegments, resolvePointer } from "./rea.mjs";
+import { scanFile } from "./jsonscan.mjs";
+import { PINNED_AJV, SCHEMA_NAMES, BUNDLE_DIR, checkNode, loadValidators, validateSchema } from "./schemas.mjs";
+import { validateWorkspace } from "./validate.mjs";
+import {
+  describeBuild,
+  digests,
+  initWorkspace,
+  publishEvidence,
+  publishFile,
+  reconcile,
+  registerExternal,
+  INDEX_PATH,
+} from "./workspace.mjs";
+import { CliError, EXIT, hashFile, openWorkspace, parseArgs, readJson, resolveInWorkspace, toInt, usage } from "./util.mjs";
+
+const BOOLEANS = ["interrupted", "verbose", "check-targets", "no-hash", "help"];
+const MULTI = ["path"];
+
+export const USAGE = `validate-investigation.mjs <command> [flags]   (stdout: one JSON object; exit 0 pass, 1 failed, 2 usage, 3 prerequisite, 4 blocked, 5 I/O)
+  setup-check
+  hash PATH...
+  inspect-file PATH [--max-parse-bytes N]
+  init-workspace --workspace D [--investigation-id inv_x] [--objective TEXT]
+  describe-build --build-id bld_x (--file PATH | --workspace D --entry ei_x [--max-parse-bytes N]) [--name N] [--kind K] [--parent bld_y]
+                   (--entry re-authenticates the saved record: file hash, entry identity, evidence_ids and target digests; the index alone is never trusted)
+  publish-evidence --workspace D --staged FILE [--stderr-file F] [--exit-code N] [--interrupted] [--command-json '["rea",...]'|@FILE]
+                   [--build-id bld_x] [--step-id step_x] [--source cli|session|export|unknown] [--name SLUG] [--note T]
+                   [--producer-name N] [--producer-version V]   (fill producer metadata only for non-REA output; a value that contradicts what a REA record
+                   declares about itself is refused with exit 2; an exact retry may use another --name and reuses the existing file)
+  register-external --workspace D --staged FILE --metadata META.json [--name SLUG] [--step-id step_x]
+  publish --workspace D --target REL --source FILE|- [--schema NAME]
+  digests --workspace D [--path REL ...]
+  reconcile --workspace D [--no-hash]
+  validate --workspace D [--mode progress|resume|closure] [--max-parse-bytes N] [--check-targets] [--verbose]
+  check-schema --schema NAME --file FILE
+  resolve --workspace D --file REL [--record ev_...] --pointer P [--max-bytes N]
+  locate --workspace D --file REL [--record ev_...] --value JSON [--under P] [--limit N]`;
+
+async function setupCheck() {
+  checkNode();
+  const { ajvVersion } = await loadValidators();
+  return { outcome: "pass", node: process.versions.node, ajv: ajvVersion, ajv_pinned: PINNED_AJV, bundle: BUNDLE_DIR, schemas: SCHEMA_NAMES };
+}
+
+async function hashCommand(positionals) {
+  if (positionals.length === 0) throw usage("hash needs at least one PATH");
+  const files = [];
+  for (const file of positionals) {
+    const abs = path.resolve(file);
+    const stat = await fsp.stat(abs).catch(() => null);
+    if (!stat) throw new CliError(`no such file: ${abs}`, { code: "missing" });
+    if (stat.isDirectory()) {
+      throw new CliError(`${abs} is a directory; SHA-256 here covers single files only. For a directory/app target, save REA's own analysis record and use its subject digest (describe-build --entry).`, { code: "is_directory" });
+    }
+    if (!stat.isFile()) {
+      throw new CliError(`${abs} is not a regular file (FIFO, device or socket); it was not opened`, { code: "not_regular_file" });
+    }
+    files.push({ path: abs, ...(await hashFile(abs)) });
+  }
+  return { files };
+}
+
+async function inspectCommand(positionals, flags) {
+  if (positionals.length !== 1) throw usage("inspect-file needs exactly one PATH");
+  const abs = path.resolve(positionals[0]);
+  const stat = await fsp.stat(abs).catch(() => null);
+  if (!stat?.isFile()) throw new CliError(`not a regular file: ${abs}`, { code: "not_regular_file" });
+  const maxParseBytes = toInt(flags["max-parse-bytes"], "max-parse-bytes", { min: 1 }) ?? DEFAULT_MAX_PARSE_BYTES;
+  const result = await inspectFile(abs, { maxParseBytes });
+  const { kind_hint: kindHint, ...rest } = result;
+  return { path: abs, would_index_as: kindHint ?? (result.content_type === "binary" ? "external-or-diagnostic" : "diagnostic"), max_parse_bytes: maxParseBytes, ...rest };
+}
+
+async function locateRecord(flags) {
+  const ws = await openWorkspace(flags.workspace);
+  if (!flags.file) throw usage("--file REL is required");
+  const index = await readJson((await resolveInWorkspace(ws.abs, INDEX_PATH, { allowMissing: false })).abs);
+  const entry = index.entries.find((e) => e.file === flags.file);
+  if (!entry || !["canonical-record", "canonical-bundle", "derived-view"].includes(entry.kind)) {
+    throw new CliError(`${flags.file} is not an indexed canonical evidence file`, { code: "not_indexed" });
+  }
+  let recordPointer = "";
+  if (flags.record) {
+    const rec = entry.records.find((x) => x.evidence_id === flags.record);
+    if (!rec) {
+      if (entry.records_truncated) {
+        throw new CliError(`${flags.record} is outside the indexed record prefix of ${flags.file}; the unindexed suffix cannot be resolved`, { code: "record_beyond_index_limit", exit: EXIT.BLOCKED });
+      }
+      throw new CliError(`${flags.record} is not a record of ${flags.file}`, { code: "unknown_record" });
+    }
+    recordPointer = rec.pointer;
+  } else if (entry.kind === "canonical-bundle" && entry.records.length !== 1) {
+    throw usage("--record ev_... is required for bundle files");
+  } else if (entry.records.length === 1) recordPointer = entry.records[0].pointer;
+  const abs = (await resolveInWorkspace(ws.abs, entry.file, { allowMissing: false })).abs;
+  const live = await hashFile(abs);
+  if (live.sha256 !== entry.sha256 || live.bytes !== entry.bytes) {
+    throw new CliError(`${entry.file} no longer matches its indexed sha256/bytes; the saved evidence was modified and must not be cited as the original`, { code: "evidence_modified", exit: EXIT.FAILED });
+  }
+  const idPointer = `${recordPointer}/evidence_id`;
+  const idScan = await scanFile(abs, [idPointer], { maxCaptureBytes: 1024 });
+  const savedId = idScan.captures.get(idPointer) ? JSON.parse(idScan.captures.get(idPointer).text) : null;
+  const wantedId = flags.record ?? entry.records[0]?.evidence_id ?? null;
+  if (savedId !== wantedId) {
+    throw new CliError(`${entry.file} has evidence_id ${savedId ?? "none"} at ${recordPointer || "/"}, not ${wantedId}; the index pointer is stale or edited`, { code: "record_pointer_mismatch", exit: EXIT.FAILED });
+  }
+  return { abs, entry, recordPointer, bytes: live.bytes };
+}
+
+async function resolveCommand(flags) {
+  if (flags.pointer === undefined) throw usage("--pointer P is required (use \"\" for the record root)");
+  if (pointerSegments(flags.pointer) === null) throw usage("--pointer is not a valid RFC 6901 pointer");
+  const { abs, entry, recordPointer, bytes } = await locateRecord(flags);
+  const maxBytes = toInt(flags["max-bytes"], "max-bytes", { min: 16 }) ?? 4096;
+  const absolutePointer = `${recordPointer}${flags.pointer}`;
+  let found;
+  let value;
+  if (bytes <= DEFAULT_MAX_PARSE_BYTES) {
+    const result = resolvePointer(JSON.parse(await fsp.readFile(abs, "utf8")), absolutePointer);
+    found = result.found;
+    value = result.value;
+  } else {
+    const scan = await scanFile(abs, [absolutePointer], { maxCaptureBytes: Math.max(maxBytes * 4, 1 << 20) });
+    const capture = scan.captures.get(absolutePointer);
+    if (!capture) found = false;
+    else if (capture.oversized) return { found: true, truncated: true, note: "value larger than the capture limit; select a deeper pointer", bytes: capture.bytes };
+    else {
+      found = true;
+      value = JSON.parse(capture.text);
+    }
+  }
+  if (!found) return { found: false, pointer: flags.pointer, evidence_id: flags.record ?? entry.records[0]?.evidence_id ?? null };
+  const text = JSON.stringify(value);
+  const type = Array.isArray(value) ? "array" : value === null ? "null" : typeof value;
+  const size = type === "array" ? value.length : type === "object" ? Object.keys(value).length : null;
+  return {
+    found: true,
+    pointer: flags.pointer,
+    file: entry.file,
+    evidence_id: flags.record ?? entry.records[0]?.evidence_id ?? null,
+    type,
+    size,
+    truncated: text.length > maxBytes,
+    value: text.length > maxBytes ? `${text.slice(0, maxBytes)}…` : value,
+  };
+}
+
+async function locateCommand(flags) {
+  if (flags.value === undefined) throw usage("--value JSON is required");
+  let wanted;
+  try {
+    wanted = JSON.parse(flags.value);
+  } catch {
+    throw usage("--value must be JSON (strings need quotes, e.g. '\"main.js\"')");
+  }
+  const { abs, entry, recordPointer, bytes } = await locateRecord(flags);
+  if (bytes > DEFAULT_MAX_PARSE_BYTES) {
+    throw new CliError(`${entry.file} exceeds the ${DEFAULT_MAX_PARSE_BYTES} byte parse limit; publish a smaller REA view and locate within it`, { code: "parse_limit", exit: EXIT.BLOCKED });
+  }
+  const doc = JSON.parse(await fsp.readFile(abs, "utf8"));
+  const limit = toInt(flags.limit, "limit", { min: 1 }) ?? 20;
+  const under = flags.under ?? "";
+  if (pointerSegments(under) === null) throw usage("--under is not a valid RFC 6901 pointer");
+  const result = locateValues(doc, wanted, { under: `${recordPointer}${under}`, limit });
+  const strip = (pointer) => pointer.slice(recordPointer.length);
+  return {
+    file: entry.file,
+    evidence_id: flags.record ?? entry.records[0]?.evidence_id ?? null,
+    matches: result.matches.map(strip),
+    visited: result.visited,
+    truncated: result.truncated,
+    note: "Pointers are relative to the record root; put them in selectors[].pointer.",
+  };
+}
+
+async function checkSchemaCommand(flags) {
+  if (!flags.schema || !flags.file) throw usage("--schema NAME and --file FILE are required");
+  if (!SCHEMA_NAMES.includes(flags.schema)) throw usage(`--schema must be one of ${SCHEMA_NAMES.join(", ")}`);
+  let doc;
+  try {
+    doc = JSON.parse(await fsp.readFile(flags.file, "utf8"));
+  } catch (error) {
+    throw new CliError(`cannot read JSON: ${error.message}`, { code: "invalid_json" });
+  }
+  const result = await validateSchema(flags.schema, doc, { maxErrors: 50 });
+  return { outcome: result.valid ? "pass" : "fail", schema: flags.schema, errors: result.errors, truncated: result.truncated ?? false };
+}
+
+/** Run a command; returns { exit, body }. */
+export async function run(argv) {
+  const [command, ...rest] = argv;
+  if (!command || command === "--help" || command === "help") return { exit: command ? EXIT.OK : EXIT.USAGE, body: { usage: USAGE } };
+  const { flags, positionals } = parseArgs(rest, { booleans: BOOLEANS, multi: MULTI });
+  if (flags.help) return { exit: EXIT.OK, body: { usage: USAGE } };
+  switch (command) {
+    case "setup-check":
+      return { exit: EXIT.OK, body: await setupCheck() };
+    case "hash":
+      return { exit: EXIT.OK, body: await hashCommand(positionals) };
+    case "inspect-file":
+      return { exit: EXIT.OK, body: await inspectCommand(positionals, flags) };
+    case "init-workspace":
+      await loadValidators();
+      return { exit: EXIT.OK, body: await initWorkspace(flags) };
+    case "describe-build":
+      await loadValidators();
+      return { exit: EXIT.OK, body: await describeBuild(flags) };
+    case "publish-evidence": {
+      await loadValidators();
+      const body = await publishEvidence(flags);
+      return { exit: EXIT.OK, body };
+    }
+    case "register-external":
+      await loadValidators();
+      return { exit: EXIT.OK, body: await registerExternal(flags) };
+    case "publish":
+      await loadValidators();
+      return { exit: EXIT.OK, body: await publishFile(flags) };
+    case "digests":
+      return { exit: EXIT.OK, body: await digests(flags, { paths: flags.path ?? [] }) };
+    case "reconcile": {
+      await loadValidators();
+      const body = await reconcile(flags);
+      return { exit: body.outcome === "pass" ? EXIT.OK : EXIT.FAILED, body };
+    }
+    case "validate": {
+      const mode = flags.mode ?? "progress";
+      if (!["progress", "resume", "closure"].includes(mode)) throw usage("--mode must be progress|resume|closure");
+      const body = await validateWorkspace({
+        workspace: flags.workspace,
+        mode,
+        maxParseBytes: toInt(flags["max-parse-bytes"], "max-parse-bytes", { min: 1 }) ?? DEFAULT_MAX_PARSE_BYTES,
+        verbose: flags.verbose === true,
+        checkTargets: flags["check-targets"] === true,
+      });
+      return { exit: body.outcome === "pass" ? EXIT.OK : body.outcome === "blocked" ? EXIT.BLOCKED : EXIT.FAILED, body };
+    }
+    case "check-schema": {
+      await loadValidators();
+      const body = await checkSchemaCommand(flags);
+      return { exit: body.outcome === "pass" ? EXIT.OK : EXIT.FAILED, body };
+    }
+    case "resolve":
+      return { exit: EXIT.OK, body: await resolveCommand(flags) };
+    case "locate":
+      return { exit: EXIT.OK, body: await locateCommand(flags) };
+    default:
+      throw usage(`unknown command: ${command}`);
+  }
+}

package/skills/full-reverse/scripts/lib/jsonscan.mjs

@@ -0,0 +1,285 @@
+// Streaming JSON scanner: captures selected values by RFC 6901 pointer patterns
+// and counts container sizes without loading or parsing the whole document.
+// Structural bytes are ASCII and never occur inside UTF-8 multibyte sequences,
+// so the scan works on raw bytes. Pattern segments may be "*" (any key/index).
+// Captures nest: a value that matches a pattern inside another captured value
+// gets its own independent, separately bounded capture, so an ancestor that
+// exceeds the capture limit never hides a smaller descendant.
+import fs from "node:fs";
+
+const QUOTE = 0x22;
+const BACKSLASH = 0x5c;
+const COMMA = 0x2c;
+const COLON = 0x3a;
+const LBRACE = 0x7b;
+const RBRACE = 0x7d;
+const LBRACKET = 0x5b;
+const RBRACKET = 0x5d;
+
+const isWs = (b) => b === 0x20 || b === 0x0a || b === 0x0d || b === 0x09;
+const escapeSegment = (segment) => String(segment).replace(/~/g, "~0").replace(/\//g, "~1");
+const unescapeSegment = (segment) => segment.replace(/~1/g, "/").replace(/~0/g, "~");
+
+export function parsePattern(pointer) {
+  if (pointer === "") return [];
+  if (!pointer.startsWith("/")) throw new TypeError(`invalid pointer pattern: ${pointer}`);
+  return pointer.split("/").slice(1).map(unescapeSegment);
+}
+
+class Scanner {
+  constructor(patterns, maxCaptureBytes) {
+    this.patterns = patterns.map(parsePattern);
+    this.maxCaptureBytes = maxCaptureBytes;
+    this.stack = [];
+    this.state = "value"; // value | key | colon | comma | done
+    this.inString = false;
+    this.escaped = false;
+    this.stringIsKey = false;
+    this.keyParts = null;
+    this.scalar = false;
+    this.sawRoot = false;
+    this.rootType = null;
+    this.malformed = false;
+    this.active = []; // open captures, outermost first (strictly increasing depth)
+    this.captureRoot = this.patterns.some((pattern) => pattern.length === 0);
+    this.captures = new Map();
+    this.counts = new Map();
+    this.topKeys = [];
+    this.allIndexes = this.patterns.map((_, index) => index).filter((index) => this.patterns[index].length >= 1);
+  }
+
+  // --- capture helpers -----------------------------------------------------
+  startCapture(pointer, from) {
+    this.active.push({ pointer, depth: this.stack.length, pieces: [], size: 0, from, oversized: false });
+  }
+
+  addPiece(cap, buf, from, to) {
+    const length = to - from;
+    if (length <= 0) return;
+    cap.size += length;
+    if (cap.size > this.maxCaptureBytes) {
+      cap.oversized = true;
+      cap.pieces = null;
+      return;
+    }
+    if (cap.pieces) cap.pieces.push(Buffer.from(buf.subarray(from, to)));
+  }
+
+  finishCapture(buf, endInclusive) {
+    const cap = this.active.pop();
+    if (!cap.oversized) this.addPiece(cap, buf, cap.from, endInclusive + 1);
+    else cap.size += endInclusive + 1 - cap.from;
+    this.captures.set(cap.pointer, {
+      text: cap.oversized || !cap.pieces ? null : Buffer.concat(cap.pieces).toString("utf8"),
+      bytes: cap.size,
+      oversized: cap.oversized,
+    });
+  }
+
+  // --- value lifecycle -----------------------------------------------------
+  valueStart(buf, i, b) {
+    const frame = this.stack[this.stack.length - 1];
+    let parentInterest;
+    let depth;
+    let segment = null;
+    let parentPointer = "";
+    if (frame === undefined) {
+      parentInterest = this.allIndexes;
+      depth = 0;
+      if (this.sawRoot) this.malformed = true;
+      this.sawRoot = true;
+      this.rootType = b === LBRACE ? "object" : b === LBRACKET ? "array" : "scalar";
+    } else {
+      frame.count += 1;
+      if (frame.type === "a") frame.index += 1;
+      parentInterest = frame.interest;
+      depth = this.stack.length - 1;
+      segment = frame.type === "o" ? frame.key : String(frame.index);
+      parentPointer = frame.pointer;
+    }
+    let childInterest = null;
+    let captureHere = false;
+    let pointer = null;
+    if (frame !== undefined && parentInterest) {
+      for (const pi of parentInterest) {
+        const pattern = this.patterns[pi];
+        if (pattern.length > depth && (pattern[depth] === "*" || pattern[depth] === segment)) {
+          if (pattern.length === depth + 1) captureHere = true;
+          else (childInterest ??= []).push(pi);
+        }
+      }
+      if (captureHere || childInterest) pointer = `${parentPointer}/${escapeSegment(segment)}`;
+    } else if (frame === undefined) {
+      if (b === LBRACE || b === LBRACKET) childInterest = parentInterest;
+      if (this.captureRoot) captureHere = true;
+      if (captureHere || childInterest) pointer = "";
+    }
+    if (captureHere) this.startCapture(pointer, i);
+    if (b === LBRACE || b === LBRACKET) {
+      this.stack.push({
+        type: b === LBRACE ? "o" : "a",
+        key: null,
+        index: -1,
+        count: 0,
+        interest: childInterest,
+        pointer,
+        capturing: false,
+      });
+      this.state = b === LBRACE ? "key" : "value";
+    } else if (b === QUOTE) {
+      this.inString = true;
+      this.stringIsKey = false;
+      this.escaped = false;
+    } else {
+      this.scalar = true;
+    }
+  }
+
+  valueEnd(buf, i) {
+    // A complete value ended at byte index i (inclusive).
+    const top = this.active[this.active.length - 1];
+    if (top && top.depth === this.stack.length) this.finishCapture(buf, i);
+    this.state = this.stack.length === 0 ? "done" : "comma";
+  }
+
+  closeContainer(buf, i, expected) {
+    const frame = this.stack[this.stack.length - 1];
+    if (!frame || frame.type !== expected) {
+      this.malformed = true;
+      return;
+    }
+    this.stack.pop();
+    if (frame.pointer !== null) {
+      this.counts.set(frame.pointer, frame.type === "a" ? frame.index + 1 : frame.count);
+    }
+    this.valueEnd(buf, i);
+  }
+
+  // --- main loop -------------------------------------------------------------
+  push(buf) {
+    const n = buf.length;
+    // open captures continue from the start of this chunk (their offsets are reset after each carry)
+    for (let i = 0; i < n; i += 1) {
+      const b = buf[i];
+      if (this.inString) {
+        if (this.escaped) this.escaped = false;
+        else if (b === BACKSLASH) this.escaped = true;
+        else if (b === QUOTE) {
+          this.inString = false;
+          if (this.stringIsKey) this.endKey(buf, i);
+          else this.valueEnd(buf, i);
+        }
+        continue;
+      }
+      if (this.scalar) {
+        if (isWs(b) || b === COMMA || b === RBRACE || b === RBRACKET) {
+          this.scalar = false;
+          this.valueEnd(buf, i - 1);
+        } else continue;
+      }
+      if (isWs(b)) continue;
+      switch (this.state) {
+        case "value":
+          if (b === RBRACKET) {
+            // empty array
+            this.closeContainer(buf, i, "a");
+          } else if (b === COMMA || b === COLON || b === RBRACE) {
+            this.malformed = true;
+          } else {
+            this.valueStart(buf, i, b);
+          }
+          break;
+        case "key":
+          if (b === QUOTE) {
+            this.inString = true;
+            this.escaped = false;
+            this.stringIsKey = true;
+            this.keyParts = [];
+            this.keyFrom = i + 1;
+          } else if (b === RBRACE) {
+            this.closeContainer(buf, i, "o");
+          } else this.malformed = true;
+          break;
+        case "colon":
+          if (b === COLON) this.state = "value";
+          else this.malformed = true;
+          break;
+        case "comma": {
+          const frame = this.stack[this.stack.length - 1];
+          if (b === COMMA) this.state = frame && frame.type === "o" ? "key" : "value";
+          else if (b === RBRACE) this.closeContainer(buf, i, "o");
+          else if (b === RBRACKET) this.closeContainer(buf, i, "a");
+          else this.malformed = true;
+          break;
+        }
+        default:
+          this.malformed = true; // trailing data after the root value
+      }
+    }
+    // carry open captures and key text across chunk boundaries
+    for (const cap of this.active) {
+      if (!cap.oversized) this.addPiece(cap, buf, cap.from, n);
+      else cap.size += n - cap.from;
+      cap.from = 0;
+    }
+    if (this.inString && this.stringIsKey) {
+      this.keyParts.push(Buffer.from(buf.subarray(this.keyFrom, n)));
+      this.keyFrom = 0;
+    }
+  }
+
+  endKey(buf, i) {
+    const frame = this.stack[this.stack.length - 1];
+    this.keyParts.push(Buffer.from(buf.subarray(this.keyFrom, i)));
+    const raw = Buffer.concat(this.keyParts).toString("utf8");
+    this.keyParts = null;
+    let key;
+    try {
+      key = JSON.parse(`"${raw}"`);
+    } catch {
+      this.malformed = true;
+      key = raw;
+    }
+    frame.key = key;
+    if (this.stack.length === 1) this.topKeys.push(key);
+    this.state = "colon";
+  }
+
+  end() {
+    if (this.scalar) {
+      this.scalar = false;
+      this.valueEnd(Buffer.alloc(0), -1);
+    }
+    const balanced =
+      this.sawRoot && !this.malformed && this.stack.length === 0 && !this.inString && this.state === "done";
+    return {
+      balanced,
+      rootType: this.rootType,
+      topKeys: this.topKeys,
+      captures: this.captures,
+      counts: this.counts,
+    };
+  }
+}
+
+/**
+ * Scan a file once, capturing values at the given pointer patterns.
+ * Returns { balanced, rootType, topKeys, captures: Map(pointer -> {text, bytes, oversized}),
+ * counts: Map(pointer -> element/key count of interesting containers) }.
+ * balanced=false means the structure was truncated or malformed (not a full JSON parse).
+ * Captures nest: every matching value is captured independently, each bounded by
+ * maxCaptureBytes. chunkBytes is the read size (tests shrink it to exercise chunk boundaries).
+ */
+export async function scanFile(file, patterns, { maxCaptureBytes = 1 << 20, chunkBytes = 1 << 20 } = {}) {
+  const scanner = new Scanner(patterns, maxCaptureBytes);
+  const stream = fs.createReadStream(file, { highWaterMark: chunkBytes });
+  for await (const chunk of stream) scanner.push(chunk);
+  return scanner.end();
+}
+
+/** Scan an in-memory buffer (used by tests and small inputs). */
+export function scanBuffer(buffer, patterns, { maxCaptureBytes = 1 << 20 } = {}) {
+  const scanner = new Scanner(patterns, maxCaptureBytes);
+  scanner.push(buffer);
+  return scanner.end();
+}