rea/src/domain/javascript/javascriptRuntimeReconciliationCaptureParsing.ts

import { z } from "zod";

import {
  browserAllowedOriginsSchema,
  browserEndpointSchema,
  recordedBrowserObservationEndpointSchema,
} from "../browserObservation.js";
import {
  webPageInspectionSchema,
  type WebPageInspection,
} from "../browserObservationSchemas.js";
import {
  classifyBrowserCompleteness,
  type BrowserCompleteness,
} from "../browserCompleteness.js";
import {
  electronPageInspectionSchema,
  type ElectronPageInspection,
} from "./electronObservation.js";
import {
  javascriptRuntimeObservationSchema,
  javascriptRuntimeKindSchema,
  type JavaScriptRuntimeObservation,
  type JavaScriptRuntimeTargetLocation,
} from "./javascriptRuntimeObservation.js";
import { digestCanonicalValue } from "../canonicalDigest.js";
import { compareUnicodeCodePoints } from "../unicodeCodePointOrder.js";
import { parseEvidence, type Evidence } from "../evidence.js";
import { parseActiveElectronCapture } from "./javascriptRuntimeReconciliationActive.js";
import {
  assertEvidenceIdentity,
  invalidInput,
  parseAtPath,
} from "./javascriptRuntimeReconciliationInputValidation.js";

interface RuntimeCaptureBase {
  readonly evidence: Evidence;
  readonly captureSha256: string;
  readonly scriptsCompleteWithinScope: boolean;
}

interface NormalizedV8Inspection {
  readonly target:
    | {
        readonly target_id: string;
        readonly type: string;
        readonly title: string;
        readonly attached: boolean | null;
        readonly file_path: string;
      }
    | {
        readonly target_id: string;
        readonly type: string;
        readonly title: string;
        readonly attached: boolean | null;
        readonly url: string;
      }
    | {
        readonly target_id: string;
        readonly type: string;
        readonly title: string;
        readonly attached: boolean | null;
        readonly unresolved_location: Extract<
          JavaScriptRuntimeObservation["target"]["location"],
          { kind: "unresolved" }
        >;
      };
  readonly frames: readonly [];
  readonly scripts: {
    readonly items: readonly (Readonly<{
      script_key: string;
      frame_id: string | null;
      cdp_hash: string | null;
      length: number | null;
      is_module: boolean | null;
      language: null;
      source: { readonly included: false; readonly reason: string };
    }> &
      (
        | { readonly file_path: string }
        | { readonly url: string }
        | {
            readonly unresolved_location: Extract<
              JavaScriptRuntimeObservation["scripts"]["items"][number]["location"],
              { kind: "unresolved" }
            >;
          }
      ))[];
  };
  readonly workers: readonly [];
  readonly completeness: BrowserCompleteness;
}

export type ParsedRuntimeCapture =
  | (RuntimeCaptureBase & {
      readonly kind: "browser";
      readonly inspection: WebPageInspection;
    })
  | (RuntimeCaptureBase & {
      readonly kind: "electron";
      readonly inspection: ElectronPageInspection;
    })
  | (RuntimeCaptureBase & {
      readonly kind: "v8-inspector";
      readonly inspection: NormalizedV8Inspection;
    })
  | (RuntimeCaptureBase & {
      readonly kind: "electron-active";
      readonly inspection: {
        readonly target: {
          readonly target_id: string;
          readonly type: string;
          readonly title: string;
          readonly attached: boolean;
          readonly file_path: string;
        };
        readonly frames: readonly [];
        readonly scripts: { readonly items: readonly [] };
        readonly workers: readonly [];
        readonly completeness: BrowserCompleteness;
      };
    });

/** Parse only supported passive web/Electron inspection Evidence. */
export const parseRuntimeCaptures = (
  observations: readonly Evidence[],
  path: readonly (string | number)[] = ["runtime_observations"],
): ParsedRuntimeCapture[] =>
  observations
    .map((observation, index) =>
      parseRuntimeCapture(observation, [...path, index]),
    )
    .sort((left, right) =>
      compareUnicodeCodePoints(
        left.evidence.evidence_id,
        right.evidence.evidence_id,
      ),
    );

const parseRuntimeCapture = (
  input: Evidence,
  evidencePath: readonly (string | number)[],
): ParsedRuntimeCapture => {
  const evidence = parseAtPath(parseEvidence, input, evidencePath);
  if (evidence.operation === "inspect_web_page")
    return parseBrowserCapture(evidence, evidencePath);
  if (evidence.operation === "inspect_electron_page")
    return parseElectronCapture(evidence, evidencePath);
  if (evidence.operation === "observe_javascript_runtime")
    return parseV8Capture(evidence, evidencePath);
  if (evidence.operation === "capture_electron_scenario") {
    return parseAtPath(
      () => parseActiveElectronCapture(evidence),
      evidence,
      evidencePath,
    );
  }
  throw invalidInput(
    evidencePath,
    "Runtime reconciliation requires inspect_web_page, inspect_electron_page, observe_javascript_runtime, or capture_electron_scenario Evidence",
  );
};

const parseBrowserCapture = (
  evidence: Evidence,
  path: readonly (string | number)[],
): ParsedRuntimeCapture => {
  assertEvidenceIdentity(
    evidence,
    {
      operation: "inspect_web_page",
      predicate: "rea.web-page-inspection",
      providerId: "rea-cdp-browser",
      providerName: "REA Chrome DevTools Protocol observation provider",
      providerVersion: "2",
      authority: "external-service",
      confidence: "observed",
    },
    path,
  );
  const inspection = parseAtPath(
    (value) => webPageInspectionSchema.parse(value),
    evidence.normalized_result,
    [...path, "normalized_result"],
  );
  assertRuntimeParameters(
    evidence,
    {
      kind: "browser",
      targetId: inspection.target.target_id,
      targetOrigin: inspection.target.origin,
      sourceIncluded: inspection.scripts.items.some(
        ({ source }) => source.included,
      ),
    },
    path,
  );
  return {
    kind: "browser",
    evidence,
    inspection,
    captureSha256: digestCanonicalValue(inspection, "Runtime reconciliation"),
    scriptsCompleteWithinScope: scriptsComplete(inspection.completeness),
  };
};

const parseElectronCapture = (
  evidence: Evidence,
  path: readonly (string | number)[],
): ParsedRuntimeCapture => {
  assertEvidenceIdentity(
    evidence,
    {
      operation: "inspect_electron_page",
      predicate: "rea.electron-page-inspection",
      providerId: "rea-cdp-electron",
      providerName: "REA Electron file-page CDP observation provider",
      providerVersion: "1",
      authority: "external-service",
      confidence: "observed",
    },
    path,
  );
  const inspection = parseAtPath(
    (value) => electronPageInspectionSchema.parse(value),
    evidence.normalized_result,
    [...path, "normalized_result"],
  );
  assertRuntimeParameters(
    evidence,
    {
      kind: "electron",
      targetId: inspection.target.target_id,
      sourceIncluded: inspection.scripts.items.some(
        ({ source }) => source.included,
      ),
    },
    path,
  );
  return {
    kind: "electron",
    evidence,
    inspection,
    captureSha256: digestCanonicalValue(inspection, "Runtime reconciliation"),
    scriptsCompleteWithinScope: scriptsComplete(inspection.completeness),
  };
};

const parseV8Capture = (
  evidence: Evidence,
  path: readonly (string | number)[],
): ParsedRuntimeCapture => {
  assertEvidenceIdentity(
    evidence,
    {
      operation: "observe_javascript_runtime",
      predicate: "rea.javascript-runtime-observation",
      providerId: "rea-v8-inspector",
      providerName: "REA passive Node/Electron V8 Inspector provider",
      providerVersion: "1",
      authority: "external-service",
      confidence: "observed",
    },
    path,
  );
  const result = parseAtPath(
    (value) => javascriptRuntimeObservationSchema.parse(value),
    evidence.normalized_result,
    [...path, "normalized_result"],
  );
  assertV8RuntimeParameters(evidence, result, path);
  return {
    kind: "v8-inspector",
    evidence,
    inspection: normalizeV8Inspection(result),
    captureSha256: digestCanonicalValue(result, "Runtime reconciliation"),
    scriptsCompleteWithinScope: false,
  };
};

const assertV8RuntimeParameters = (
  evidence: Evidence,
  result: JavaScriptRuntimeObservation,
  path: readonly (string | number)[],
): void => {
  const parameters = parseAtPath(
    (value) =>
      z
        .object({
          inspector_endpoint: browserEndpointSchema,
          target_id: z.string().trim().min(1),
          runtime_kind: javascriptRuntimeKindSchema.optional(),
        })
        .passthrough()
        .parse(value),
    evidence.parameters,
    [...path, "parameters"],
  );
  if (
    parameters.target_id !== result.target.target_id ||
    (parameters.runtime_kind !== undefined &&
      parameters.runtime_kind !== result.target.runtime_kind)
  )
    throw invalidInput(
      [...path, "parameters", "target_id"],
      "Runtime Evidence target or declared role disagrees with its result",
    );
  if (
    result.target.location.kind === "builtin" &&
    !result.target.location.specifier.startsWith("node:")
  )
    throw invalidInput(
      [...path, "normalized_result", "target", "location"],
      "Runtime Evidence contains an invalid builtin location",
    );
  for (const [index, { location }] of result.scripts.items.entries())
    if (location.kind === "builtin" && !location.specifier.startsWith("node:"))
      throw invalidInput(
        [...path, "normalized_result", "scripts", "items", index, "location"],
        "Runtime Evidence contains an invalid builtin location",
      );
};

const normalizeV8Inspection = (
  result: JavaScriptRuntimeObservation,
): NormalizedV8Inspection => ({
  target: {
    target_id: result.target.target_id,
    type: result.target.protocol_type,
    title: result.target.runtime_kind,
    attached: result.target.attached,
    ...(result.target.location.kind === "unresolved"
      ? { unresolved_location: result.target.location }
      : runtimeLocation(result.target.location)),
  },
  frames: [],
  scripts: {
    items: result.scripts.items.map((script) => ({
      script_key: script.script_key,
      frame_id: script.execution_context_key,
      ...runtimeLocation(script.location),
      cdp_hash: script.cdp_hash,
      length: script.length,
      is_module: script.is_module,
      language: null,
      source: {
        included: false,
        reason: "V8 Inspector source capture is outside passive authority.",
      },
    })),
  },
  workers: [],
  completeness: classifyBrowserCompleteness({
    policyFilteredSections: new Set(
      excludedV8Scripts(result) > 0 ? ["scripts"] : [],
    ),
    attachLimitedSections: new Set([
      "frames",
      "scripts",
      "script_sources",
      "workers",
    ]),
    truncatedSections: new Set(result.capture.truncated ? ["scripts"] : []),
    unavailableSections: new Set(["frames", "script_sources", "workers"]),
    excluded:
      excludedV8Scripts(result) === 0
        ? []
        : [
            {
              section: "scripts",
              reason: "out_of_target_scope",
              count: excludedV8Scripts(result),
            },
          ],
    droppedEvents: {
      scripts: result.capture.events_dropped,
      network_requests: 0,
      console_events: 0,
      websocket_connections: 0,
      websocket_frames: 0,
      webmcp_tools: 0,
      timeline_events: 0,
    },
  }),
});

const runtimeLocation = (
  location: JavaScriptRuntimeTargetLocation,
):
  | { readonly file_path: string }
  | { readonly url: string }
  | {
      readonly unresolved_location: Extract<
        JavaScriptRuntimeTargetLocation,
        { kind: "unresolved" }
      >;
    } => {
  if (location.kind === "unresolved") return { unresolved_location: location };
  if (location.kind === "file") return { file_path: location.file_path };
  if (location.kind === "url") return { url: location.sanitized_url };
  return { url: location.specifier };
};

const excludedV8Scripts = (result: JavaScriptRuntimeObservation): number =>
  Object.values(result.scripts.excluded).reduce(
    (total, count) => total + count,
    0,
  );

const assertRuntimeParameters = (
  evidence: Evidence,
  expected:
    | {
        readonly kind: "browser";
        readonly targetId: string;
        readonly targetOrigin: string;
        readonly sourceIncluded: boolean;
      }
    | {
        readonly kind: "electron";
        readonly targetId: string;
        readonly sourceIncluded: boolean;
      },
  path: readonly (string | number)[],
): void => {
  const common = {
    target_id: z.string().trim().min(1),
    include_script_sources: z.boolean(),
  };
  if (expected.kind === "browser") {
    const parameters = parseAtPath(
      (value) =>
        z
          .object({
            ...common,
            cdp_endpoint: recordedBrowserObservationEndpointSchema,
            allowed_origins: browserAllowedOriginsSchema,
          })
          .passthrough()
          .parse(value),
      evidence.parameters,
      [...path, "parameters"],
    );
    if (parameters.target_id !== expected.targetId)
      throw invalidInput(
        [...path, "parameters", "target_id"],
        "Runtime Evidence target disagrees with its captured result",
      );
    if (!parameters.allowed_origins.includes(expected.targetOrigin))
      throw invalidInput(
        [...path, "parameters", "allowed_origins"],
        "Browser Evidence target is outside its recorded origin scope",
      );
    if (expected.sourceIncluded && !parameters.include_script_sources)
      throw invalidInput(
        [...path, "parameters", "include_script_sources"],
        "Runtime Evidence contains source without source-capture selection",
      );
    return;
  }
  const parameters = parseAtPath(
    (value) =>
      z
        .object({ ...common, cdp_endpoint: browserEndpointSchema })
        .passthrough()
        .parse(value),
    evidence.parameters,
    [...path, "parameters"],
  );
  if (parameters.target_id !== expected.targetId)
    throw invalidInput(
      [...path, "parameters", "target_id"],
      "Runtime Evidence target disagrees with its captured result",
    );
  if (expected.sourceIncluded && !parameters.include_script_sources)
    throw invalidInput(
      [...path, "parameters", "include_script_sources"],
      "Runtime Evidence contains source without source-capture selection",
    );
};

const scriptsComplete = (completeness: {
  readonly truncated_sections: readonly string[];
  readonly unavailable_sections: readonly string[];
  readonly dropped_events: { readonly scripts: number };
}): boolean =>
  !completeness.truncated_sections.includes("scripts") &&
  !completeness.unavailable_sections.includes("scripts") &&
  completeness.dropped_events.scripts === 0;