full-reverse 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,496 @@
+// Inspection of saved REA producer output: hash, classify, authenticate
+// record identities, extract intrinsic target bindings, resolve RFC 6901 pointers.
+import { createHash } from "node:crypto";
+import fsp from "node:fs/promises";
+import { scanFile } from "./jsonscan.mjs";
+import { canonicalJson, hashFile } from "./util.mjs";
+
+export const DEFAULT_MAX_PARSE_BYTES = 128 * 1024 * 1024;
+
+const ENVELOPE_REQUIRED = [
+  "evidence_id", "subject", "provider", "analysis_profile", "predicate_type", "operation", "parameters",
+  "raw_result", "normalized_result", "confidence", "authority", "environment", "limitations", "locations",
+  "evidence_links",
+];
+const ENVELOPE_ALLOWED = new Set([...ENVELOPE_REQUIRED, "relationship_coverage"]);
+const BUNDLE_KEYS = ["artifacts", "providers", "environments", "scenarios", "captures", "unknowns", "records"];
+const EVIDENCE_ID = /^ev_[0-9a-f]{64}$/;
+const SHA256 = /^[0-9a-f]{64}$/;
+export const MAX_INDEXED_RECORDS = 20000;
+
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+
+/** Does a record envelope have exactly REA's fixed shape (strict, like REA's own parser)? */
+export function hasEnvelopeShape(record) {
+  if (!isObject(record)) return false;
+  for (const key of ENVELOPE_REQUIRED) if (!(key in record)) return false;
+  for (const key of Object.keys(record)) if (!ENVELOPE_ALLOWED.has(key)) return false;
+  return typeof record.evidence_id === "string" && EVIDENCE_ID.test(record.evidence_id);
+}
+
+/** Recompute REA's semantic evidence ID: ev_ + sha256 of the canonical semantic projection. */
+export function computeEvidenceId(record) {
+  const projection = {
+    subject:
+      record.subject === null
+        ? null
+        : { digest: record.subject.digest, format: record.subject.format, architecture: record.subject.architecture },
+    provider: record.provider,
+    analysis_profile: record.analysis_profile,
+    predicate_type: record.predicate_type,
+    operation: record.operation,
+    parameters: record.parameters,
+    raw_result: record.raw_result,
+    normalized_result: record.normalized_result,
+    confidence: record.confidence,
+    authority: record.authority,
+    environment: record.environment,
+    limitations: record.limitations,
+    ...(record.relationship_coverage == null ? {} : { relationship_coverage: record.relationship_coverage }),
+    locations: record.locations,
+    evidence_links: record.evidence_links,
+  };
+  return `ev_${createHash("sha256").update(canonicalJson(projection)).digest("hex")}`;
+}
+
+/**
+ * Integer literals beyond 2^53 cannot survive JSON.parse, so an ID mismatch there is not proof of tampering.
+ * Scans JSON text outside string literals only (honouring backslash escapes): digits inside strings, such as
+ * runs in hex digests, are data, not numeric tokens. A numeric token is the maximal run of number characters;
+ * only a plain integer (no fraction/exponent) of 16 or more digits is a risk.
+ */
+const UNSAFE_INTEGER_TOKEN = /^-?[0-9]{16,}$/;
+const isNumberChar = (c) => (c >= 48 && c <= 57) || c === 45 || c === 43 || c === 46 || c === 69 || c === 101;
+export function hasPrecisionRisk(text) {
+  const length = text.length;
+  let i = 0;
+  while (i < length) {
+    const c = text.charCodeAt(i);
+    if (c === 34) {
+      i += 1;
+      while (i < length) {
+        const s = text.charCodeAt(i);
+        if (s === 92) i += 2;
+        else if (s === 34) break;
+        else i += 1;
+      }
+      i += 1;
+    } else if (isNumberChar(c)) {
+      const start = i;
+      while (i < length && isNumberChar(text.charCodeAt(i))) i += 1;
+      if (i - start >= 16 && UNSAFE_INTEGER_TOKEN.test(text.slice(start, i))) return true;
+    } else {
+      i += 1;
+    }
+  }
+  return false;
+}
+
+/**
+ * Intrinsic target binding digests of a record, read from saved data only:
+ * the REA subject digest, or for process captures the manifest executable digests.
+ */
+export function bindingOf(record) {
+  if (isObject(record.subject) && isObject(record.subject.digest) && SHA256.test(record.subject.digest.sha256 ?? "")) {
+    return { source: "subject", digests: [record.subject.digest.sha256], identityState: null };
+  }
+  const manifest = record.normalized_result?.manifest;
+  if (record.predicate_type === "rea.process-capture" && isObject(manifest)) {
+    const digests = [manifest.executable_sha256, manifest.selected_executable_sha256].filter(
+      (value) => typeof value === "string" && SHA256.test(value),
+    );
+    return {
+      source: digests.length ? "process-capture-manifest" : "none",
+      digests: [...new Set(digests)],
+      identityState: isObject(manifest.executable_identity) ? (manifest.executable_identity.state ?? null) : null,
+    };
+  }
+  return { source: "none", digests: [], identityState: null };
+}
+
+const summarize = (record, pointer) => ({
+  evidence_id: record.evidence_id,
+  pointer,
+  operation: record.operation,
+  predicate_type: record.predicate_type,
+  confidence: record.confidence,
+  authority: record.authority,
+  binding_digests: bindingOf(record).digests,
+  parent_evidence_id:
+    typeof record.normalized_result?.parent_evidence_id === "string" &&
+    EVIDENCE_ID.test(record.normalized_result.parent_evidence_id)
+      ? record.normalized_result.parent_evidence_id
+      : null,
+});
+
+const isView = (summary) => summary.parent_evidence_id !== null || summary.operation === "inspect_analysis_view";
+
+const providerOf = (record) =>
+  isObject(record.provider)
+    ? { id: record.provider.id, name: record.provider.name, version: record.provider.version ?? null }
+    : null;
+
+function classifyJsonDocument(doc) {
+  if (isObject(doc)) {
+    if (BUNDLE_KEYS.every((key) => key in doc) && Array.isArray(doc.records)) return "rea-bundle";
+    if ("evidence_id" in doc && "normalized_result" in doc) return "rea-record";
+    if (typeof doc.error === "string" && typeof doc.code === "string") return "rea-error";
+  }
+  return "json";
+}
+
+function fileKind(contentType, summaries, structureOk, authStatus) {
+  if (contentType === "rea-record" && structureOk && authStatus !== "failed") {
+    return isView(summaries[0]) ? "derived-view" : "canonical-record";
+  }
+  if (contentType === "rea-bundle" && structureOk && authStatus !== "failed") return "canonical-bundle";
+  return null;
+}
+
+/**
+ * Inspect one saved file. Streams the SHA-256; parses fully when the file is
+ * at most maxParseBytes, otherwise extracts a bounded header with the streaming
+ * scanner and reports ID authentication as unverified.
+ */
+export async function inspectFile(abs, { maxParseBytes = DEFAULT_MAX_PARSE_BYTES, shallow = false } = {}) {
+  const stat = await fsp.stat(abs);
+  const result = {
+    sha256: null,
+    bytes: stat.size,
+    content_type: "binary",
+    structure: "n/a",
+    parse: "none",
+    kind_hint: null,
+    records: [],
+    records_truncated: false,
+    operation: null,
+    predicate_type: null,
+    provider: null,
+    producer_version: null,
+    id_authentication: { status: "not-applicable", reason: null },
+    binding: { source: "none", digests: [], identity_state: null },
+    error: null,
+    reasons: [],
+    jsonl_ok: null,
+  };
+  if (shallow) {
+    const hashed = await hashFile(abs);
+    result.sha256 = hashed.sha256;
+    result.bytes = hashed.bytes;
+    if (hashed.bytes === 0) {
+      result.content_type = "empty";
+      return result;
+    }
+    const sniff = Buffer.alloc(Math.min(8192, hashed.bytes));
+    const handle = await fsp.open(abs, "r");
+    try {
+      await handle.read(sniff, 0, sniff.length, 0);
+    } finally {
+      await handle.close();
+    }
+    result.content_type = sniff.includes(0) ? "binary" : "text";
+    return result;
+  }
+  if (stat.size === 0) {
+    result.sha256 = (await hashFile(abs)).sha256;
+    result.content_type = "empty";
+    return result;
+  }
+  if (stat.size <= maxParseBytes) {
+    const buffer = await fsp.readFile(abs);
+    result.sha256 = createHash("sha256").update(buffer).digest("hex");
+    result.bytes = buffer.length;
+    const sniff = buffer.subarray(0, 8192);
+    if (sniff.includes(0)) return result; // binary
+    const text = buffer.toString("utf8");
+    result.content_type = "text";
+    let doc;
+    try {
+      doc = JSON.parse(text);
+    } catch {
+      return finishNonJson(result, text);
+    }
+    result.parse = "full";
+    result.structure = "complete";
+    classifyParsed(result, doc, text);
+    return result;
+  }
+  // Large file: stream hash and scan a bounded header.
+  result.sha256 = (await hashFile(abs)).sha256;
+  const head = Buffer.alloc(8192);
+  const handle = await fsp.open(abs, "r");
+  try {
+    const { bytesRead } = await handle.read(head, 0, 8192, 0);
+    if (head.subarray(0, bytesRead).includes(0)) return result;
+  } finally {
+    await handle.close();
+  }
+  result.content_type = "text";
+  await classifyLarge(result, abs);
+  return result;
+}
+
+function finishNonJson(result, text) {
+  const lines = text.split("\n").filter((line) => line.trim() !== "");
+  if (lines.length > 0 && lines.length <= 5_000_000) {
+    let ok = true;
+    let allOk = true;
+    for (const line of lines) {
+      try {
+        const parsed = JSON.parse(line);
+        if (isObject(parsed) && parsed.ok === false) allOk = false;
+      } catch {
+        ok = false;
+        break;
+      }
+    }
+    if (ok) {
+      result.content_type = "jsonl";
+      result.parse = "full";
+      result.structure = "complete";
+      result.jsonl_ok = allOk;
+      return result;
+    }
+  }
+  if (/^\s*[{[]/.test(text)) {
+    result.structure = "incomplete";
+    result.reasons.push("json_parse_failed");
+  }
+  return result;
+}
+
+function classifyParsed(result, doc, text) {
+  const type = classifyJsonDocument(doc);
+  result.content_type = type;
+  if (type === "rea-error") {
+    result.error = {
+      code: doc.code,
+      category: typeof doc.category === "string" ? doc.category : null,
+      message: typeof doc.message === "string" ? doc.message.slice(0, 500) : null,
+    };
+    return;
+  }
+  if (type === "json") return;
+  const records = type === "rea-record" ? [[doc, ""]] : doc.records.map((record, index) => [record, `/records/${index}`]);
+  let shapeOk = true;
+  let authStatus = "verified";
+  let authReason = null;
+  const summaries = [];
+  const risk = hasPrecisionRisk(text);
+  for (const [record, pointer] of records) {
+    if (!hasEnvelopeShape(record)) {
+      shapeOk = false;
+      result.reasons.push(`envelope_shape_invalid:${pointer || "/"}`);
+      continue;
+    }
+    if (summaries.length < MAX_INDEXED_RECORDS) summaries.push(summarize(record, pointer));
+    else result.records_truncated = true;
+    if (computeEvidenceId(record) !== record.evidence_id) {
+      if (risk) {
+        if (authStatus === "verified") {
+          authStatus = "unverified";
+          authReason = "evidence_id_mismatch_with_unsafe_integer_literals";
+        }
+      } else {
+        authStatus = "failed";
+        authReason = `evidence_id_mismatch:${pointer || "/"}`;
+      }
+    }
+  }
+  if (type === "rea-bundle" && new Set(summaries.map((s) => s.evidence_id)).size !== summaries.length && !result.records_truncated) {
+    shapeOk = false;
+    result.reasons.push("duplicate_record_ids_in_bundle");
+  }
+  if (!shapeOk) {
+    authStatus = "failed";
+    authReason ??= result.reasons[0];
+  }
+  fillFromRecords(result, records.map(([record]) => record), summaries);
+  result.id_authentication = { status: authStatus, reason: authReason };
+  result.kind_hint = fileKind(type, summaries, shapeOk && summaries.length > 0, authStatus);
+}
+
+function fillFromRecords(result, records, summaries) {
+  result.records = summaries;
+  const first = records.find(isObject);
+  if (first) {
+    result.operation = typeof first.operation === "string" ? first.operation : null;
+    result.predicate_type = typeof first.predicate_type === "string" ? first.predicate_type : null;
+    const providers = new Set(records.filter(isObject).map((r) => canonicalJson(providerOf(r))));
+    result.provider = providers.size === 1 ? providerOf(first) : null;
+    const manifest = first.normalized_result?.manifest;
+    if (isObject(manifest) && typeof manifest.rea_version === "string") result.producer_version = manifest.rea_version;
+  }
+  const digests = new Set();
+  let identityState = null;
+  let source = "none";
+  for (const record of records) {
+    if (!isObject(record) || !("predicate_type" in record)) continue;
+    const binding = bindingOf(record);
+    for (const digest of binding.digests) digests.add(digest);
+    if (binding.source !== "none") source = source === "none" || source === binding.source ? binding.source : "subject";
+    if (binding.identityState) identityState = binding.identityState;
+  }
+  result.binding = { source, digests: [...digests], identity_state: identityState };
+}
+
+const HEADER_FIELDS = [
+  "evidence_id", "subject", "provider", "predicate_type", "operation", "confidence", "authority",
+  "normalized_result/parent_evidence_id", "normalized_result/manifest",
+];
+
+async function classifyLarge(result, abs) {
+  const patterns = [
+    ...HEADER_FIELDS.map((field) => `/${field}`),
+    ...HEADER_FIELDS.map((field) => `/records/*/${field}`),
+  ];
+  const scan = await scanFile(abs, patterns, { maxCaptureBytes: 1 << 20 });
+  result.parse = "header-only";
+  result.structure = scan.balanced ? "complete" : "incomplete";
+  if (!scan.balanced) {
+    result.reasons.push("json_structure_incomplete");
+    return;
+  }
+  const keys = new Set(scan.topKeys);
+  let type = "json";
+  if (scan.rootType === "object") {
+    if (BUNDLE_KEYS.every((key) => keys.has(key))) type = "rea-bundle";
+    else if (keys.has("evidence_id") && keys.has("normalized_result")) type = "rea-record";
+    else if (keys.has("error") && keys.has("code")) type = "rea-error";
+  }
+  result.content_type = type;
+  if (type !== "rea-record" && type !== "rea-bundle") return;
+  const get = (prefix, field) => {
+    const capture = scan.captures.get(`${prefix}/${field.replace(/\//g, "/")}`);
+    if (!capture) return { present: false };
+    if (capture.oversized || capture.text === null) return { present: true, oversized: true };
+    try {
+      return { present: true, value: JSON.parse(capture.text) };
+    } catch {
+      return { present: true, invalid: true };
+    }
+  };
+  const prefixes = type === "rea-record" ? [""] : Array.from({ length: scan.counts.get("/records") ?? 0 }, (_, i) => `/records/${i}`);
+  const records = [];
+  let shapeOk = true;
+  let bindingUnknown = false;
+  for (const prefix of prefixes.slice(0, MAX_INDEXED_RECORDS)) {
+    const id = get(prefix, "evidence_id");
+    const subject = get(prefix, "subject");
+    const parent = get(prefix, "normalized_result/parent_evidence_id");
+    const manifest = get(prefix, "normalized_result/manifest");
+    const operation = get(prefix, "operation");
+    const predicate = get(prefix, "predicate_type");
+    if (typeof id.value !== "string" || !EVIDENCE_ID.test(id.value) || !subject.present || typeof operation.value !== "string") {
+      shapeOk = false;
+      result.reasons.push(`header_incomplete:${prefix || "/"}`);
+      continue;
+    }
+    const partial = {
+      evidence_id: id.value,
+      subject: subject.value ?? null,
+      predicate_type: predicate.value,
+      operation: operation.value,
+      normalized_result: { parent_evidence_id: parent.value, manifest: manifest.value },
+    };
+    if (subject.oversized || (manifest.oversized && predicate.value === "rea.process-capture")) bindingUnknown = true;
+    const binding = bindingOf(partial);
+    const authority = get(prefix, "authority").value;
+    const confidence = get(prefix, "confidence").value;
+    records.push({ prefix, binding, summary: {
+      evidence_id: id.value,
+      pointer: prefix,
+      operation: operation.value,
+      predicate_type: typeof predicate.value === "string" ? predicate.value : "",
+      confidence,
+      authority: typeof authority === "string" ? authority : "",
+      binding_digests: binding.digests,
+      parent_evidence_id: typeof parent.value === "string" && EVIDENCE_ID.test(parent.value) ? parent.value : null,
+    }, provider: get(prefix, "provider").value, manifest: manifest.value });
+  }
+  if (prefixes.length > MAX_INDEXED_RECORDS) result.records_truncated = true;
+  result.records = records.map((r) => r.summary);
+  const first = records[0];
+  if (first) {
+    result.operation = first.summary.operation;
+    result.predicate_type = first.summary.predicate_type;
+    result.provider = isObject(first.provider)
+      ? { id: first.provider.id, name: first.provider.name, version: first.provider.version ?? null }
+      : null;
+    if (isObject(first.manifest) && typeof first.manifest.rea_version === "string") result.producer_version = first.manifest.rea_version;
+  }
+  const digests = new Set(records.flatMap((r) => r.binding.digests));
+  const states = records.map((r) => r.binding.identityState).filter(Boolean);
+  const sources = new Set(records.map((r) => r.binding.source).filter((s) => s !== "none"));
+  result.binding = {
+    source: sources.size === 0 ? "none" : sources.size === 1 ? [...sources][0] : "subject",
+    digests: [...digests],
+    identity_state: states[0] ?? null,
+  };
+  if (bindingUnknown) result.reasons.push("binding_capture_oversized");
+  result.id_authentication = {
+    status: shapeOk ? "unverified" : "failed",
+    reason: shapeOk ? `file_exceeds_parse_limit` : (result.reasons[0] ?? "header_incomplete"),
+  };
+  result.kind_hint = fileKind(type, result.records, shapeOk && result.records.length > 0 && !bindingUnknown, result.id_authentication.status);
+}
+
+// --- RFC 6901 -----------------------------------------------------------------
+
+/** Decode a pointer into segments, or null when it is not a valid RFC 6901 pointer. */
+export function pointerSegments(pointer) {
+  if (pointer === "") return [];
+  if (typeof pointer !== "string" || !pointer.startsWith("/")) return null;
+  const segments = pointer.split("/").slice(1);
+  for (const segment of segments) if (/~(?![01])/.test(segment)) return null;
+  return segments.map((s) => s.replace(/~1/g, "/").replace(/~0/g, "~"));
+}
+
+export const encodePointer = (segments) => segments.map((s) => `/${String(s).replace(/~/g, "~0").replace(/\//g, "~1")}`).join("");
+
+/** Resolve a pointer against parsed JSON. Returns { found, value }. */
+export function resolvePointer(doc, pointer) {
+  const segments = pointerSegments(pointer);
+  if (segments === null) return { found: false, invalid: true };
+  let current = doc;
+  for (const segment of segments) {
+    if (Array.isArray(current)) {
+      if (!/^(0|[1-9][0-9]*)$/.test(segment)) return { found: false };
+      const index = Number(segment);
+      if (index >= current.length) return { found: false };
+      current = current[index];
+    } else if (isObject(current)) {
+      if (!Object.hasOwn(current, segment)) return { found: false };
+      current = current[segment];
+    } else return { found: false };
+  }
+  return { found: true, value: current };
+}
+
+/** Find pointers whose value equals a JSON scalar/value (bounded DFS). */
+export function locateValues(doc, wanted, { under = "", limit = 20, maxVisited = 5_000_000 } = {}) {
+  const start = resolvePointer(doc, under);
+  if (!start.found) return { matches: [], visited: 0, truncated: false, startFound: false };
+  const target = canonicalJson(wanted);
+  const wantedIsContainer = wanted !== null && typeof wanted === "object";
+  const matches = [];
+  let visited = 0;
+  let truncated = false;
+  const walk = (value, segments) => {
+    if (matches.length >= limit || truncated) return;
+    visited += 1;
+    if (visited > maxVisited) {
+      truncated = true;
+      return;
+    }
+    if (value === null || typeof value !== "object") {
+      if (canonicalJson(value) === target) matches.push(under + encodePointer(segments));
+      return;
+    }
+    if (wantedIsContainer && canonicalJson(value) === target) matches.push(under + encodePointer(segments));
+    if (Array.isArray(value)) value.forEach((item, index) => walk(item, [...segments, String(index)]));
+    else for (const key of Object.keys(value)) walk(value[key], [...segments, key]);
+  };
+  walk(start.value, []);
+  return { matches, visited, truncated: truncated || matches.length >= limit, startFound: true };
+}

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

@@ -0,0 +1,79 @@
+// Ajv 2020-12 schema loading. Dependencies are installed explicitly by the user
+// (`npm ci --ignore-scripts` in the entry skill); this module never installs anything.
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { CliError, EXIT } from "./util.mjs";
+
+export const BUNDLE_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+export const SCHEMA_DIR = path.join(BUNDLE_DIR, "schemas");
+export const SCHEMA_NAMES = ["investigation", "inventory", "claims", "evidence-index", "external-evidence", "review"];
+export const PINNED_AJV = "8.20.0";
+
+const MIN_NODE = [
+  { major: 22, minor: 19 },
+  { major: 24, minor: 11 },
+  { major: 26, minor: 0 },
+];
+
+export function checkNode() {
+  const [major, minor] = process.versions.node.split(".").map(Number);
+  const ok = MIN_NODE.some((req) => (req.major === 26 ? major >= 26 : major === req.major && minor >= req.minor));
+  if (!ok) {
+    throw new CliError(`Node ${process.versions.node} is unsupported; need ^22.19.0 || ^24.11.0 || >=26.0.0`, {
+      exit: EXIT.PREREQUISITE,
+      code: "node_unsupported",
+    });
+  }
+}
+
+let cache = null;
+
+/** Load Ajv and compile every schema. Missing dependencies are a prerequisite failure. */
+export async function loadValidators() {
+  if (cache) return cache;
+  checkNode();
+  let Ajv2020;
+  let ajvVersion;
+  try {
+    ({ default: Ajv2020 } = await import("ajv/dist/2020.js"));
+    const pkg = JSON.parse(await fsp.readFile(path.join(BUNDLE_DIR, "node_modules", "ajv", "package.json"), "utf8"));
+    ajvVersion = pkg.version;
+  } catch (error) {
+    throw new CliError(
+      `Helper dependencies are not installed (${error.code ?? error.message}). Run once: (cd "${BUNDLE_DIR}" && npm ci --ignore-scripts)`,
+      { exit: EXIT.PREREQUISITE, code: "dependencies_missing" },
+    );
+  }
+  if (ajvVersion !== PINNED_AJV) {
+    throw new CliError(`Installed ajv ${ajvVersion} differs from pinned ${PINNED_AJV}; reinstall with npm ci --ignore-scripts`, {
+      exit: EXIT.PREREQUISITE,
+      code: "dependency_version_mismatch",
+    });
+  }
+  const ajv = new Ajv2020({ strict: true, strictTypes: false, allErrors: true, allowUnionTypes: true });
+  const files = ["common", ...SCHEMA_NAMES];
+  const schemas = {};
+  for (const name of files) {
+    schemas[name] = JSON.parse(await fsp.readFile(path.join(SCHEMA_DIR, `${name}.schema.json`), "utf8"));
+    ajv.addSchema(schemas[name]);
+  }
+  const validators = {};
+  for (const name of SCHEMA_NAMES) validators[name] = ajv.getSchema(schemas[name].$id);
+  cache = { ajv, ajvVersion, validators, schemas };
+  return cache;
+}
+
+/** Validate data; returns { valid, errors:[{path,message}] } with bounded error list. */
+export async function validateSchema(name, data, { maxErrors = 25 } = {}) {
+  const { validators } = await loadValidators();
+  const validate = validators[name];
+  if (!validate) throw new CliError(`unknown schema: ${name}`, { exit: EXIT.USAGE, code: "usage" });
+  const valid = validate(data);
+  if (valid) return { valid: true, errors: [] };
+  const errors = (validate.errors ?? []).slice(0, maxErrors).map((error) => ({
+    path: error.instancePath || "/",
+    message: `${error.message}${error.params && Object.keys(error.params).length ? ` ${JSON.stringify(error.params)}` : ""}`,
+  }));
+  return { valid: false, errors, truncated: (validate.errors ?? []).length > maxErrors };
+}

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

@@ -0,0 +1,59 @@
+// Canonical review scope digest. A review attests to the objective, the exclusions, the
+// question wording and the builds it examined. Mutable lifecycle data (question status,
+// reason and claim_ids, steps, authorizations, phase, lifecycle checkpoint) is excluded
+// on purpose: it changes while the investigation runs, and the review itself is bound
+// back into lifecycle.review_sha256, so including it would make the binding circular.
+import fsp from "node:fs/promises";
+import { canonicalJson, resolveInWorkspace, sha256Buffer } from "./util.mjs";
+
+export const SCOPE_VERSION = "full-reverse.scope/1";
+
+const sorted = (values) => [...values].sort();
+
+/** The exact JSON value that is hashed. `investigation` must be schema-valid. */
+export function canonicalScope(investigation) {
+  return {
+    version: SCOPE_VERSION,
+    objective: investigation.objective,
+    non_goals: sorted(investigation.non_goals),
+    questions: investigation.questions
+      .map((q) => ({
+        question_id: q.question_id,
+        text: q.text,
+        feature: q.feature,
+        build_ids: sorted(q.build_ids ?? []),
+      }))
+      .sort((a, b) => (a.question_id < b.question_id ? -1 : a.question_id > b.question_id ? 1 : 0)),
+    builds: investigation.builds
+      .map((b) => ({
+        build_id: b.build_id,
+        kind: b.kind,
+        name: b.name,
+        version_label: b.version_label ?? null,
+        identity: b.identity,
+        parent_build_id: b.parent_build_id,
+      }))
+      .sort((a, b) => (a.build_id < b.build_id ? -1 : a.build_id > b.build_id ? 1 : 0)),
+  };
+}
+
+/** SHA-256 (hex) of the canonical scope of a schema-valid investigation document. */
+export function scopeDigest(investigation) {
+  return sha256Buffer(Buffer.from(canonicalJson(canonicalScope(investigation)), "utf8"));
+}
+
+/**
+ * Scope digest of the workspace's current investigation.json as `{ sha256 }`, or null when
+ * the file is missing or is not a document the digest can be computed from. Used by the
+ * `digests` command; validation always checks the schema separately.
+ */
+export async function workspaceScopeDigest(workspaceAbs) {
+  try {
+    const resolved = await resolveInWorkspace(workspaceAbs, "investigation.json");
+    if (!resolved.exists || !resolved.stat.isFile()) return null;
+    const doc = JSON.parse(await fsp.readFile(resolved.abs, "utf8"));
+    return { sha256: scopeDigest(doc) };
+  } catch {
+    return null;
+  }
+}