rea/src/application/environment/environmentSource.ts

import { z } from "zod";

import {
  analysisViewResultSchema,
  type AnalysisViewResult,
} from "../../domain/analysisView/analysisView.js";
import { scenarioCaptureRecords } from "../../domain/analysisView/scenarioCaptureRecords.js";
import {
  readRecordedResponseBody,
  type RecordedResponseBody,
} from "../../domain/analysisView/recordedResponseBody.js";
import { isJsonLike } from "../../domain/analysisView/EnvironmentManifestAccumulator.js";
import {
  mediaTypeEssence,
  readRecordedRequestLine,
} from "../../domain/analysisView/webNetworkRouteTemplates.js";
import { browserScenarioCaptureSchema } from "../../domain/browserScenarioCapture.js";
import type { AnalysisError } from "../../domain/analysisErrorBase.js";
import {
  AnalysisInputError,
  type AnalysisInputIssue,
} from "../../domain/analysisErrorCore.js";
import { immutableEvidence, type Evidence } from "../../domain/evidence.js";
import { parseExactJson } from "../../domain/exactJsonNumber.js";
import { projectInputIssues } from "../../domain/inputIssueProjection.js";
import { immutableJsonSnapshotMember } from "../../domain/immutableJson.js";
import type { JsonValue } from "../../domain/jsonValue.js";
import { err, ok, type Result } from "../../domain/result.js";
import {
  safeParseOwnedWebNetworkCapture,
  type WebNetworkCaptureRecord,
} from "../../domain/webNetworkCapture.js";

/** Operation name every refusal of the serve command reports. */
export const ENVIRONMENT_SERVE_OPERATION = "environment-serve";

export type EnvironmentManifest = Extract<
  AnalysisViewResult,
  { kind: "environment-manifest" }
>;
export type EnvironmentManifestTool = EnvironmentManifest["tools"][number];

/** One retained parent record reduced to what a replay returns; a cut body is reported truncated. */
export interface RecordedExchange extends RecordedResponseBody {
  readonly ordinal: number;
  readonly path: string;
  /** WHATWG query spelling including `?`, or null when the request had none. */
  readonly query: string | null;
  readonly status: number | null;
  readonly contentType: string | null;
}

/** Replayed bodies larger than this are cut at a UTF-8 boundary and flagged. */
export const REPLAY_BODY_LIMIT_BYTES = 256 * 1024;

/** How replay answers with an exchange's body; replay and tool descriptions both read it from here. */
export type ReplayedBody =
  | { readonly kind: "none" }
  /** Non-UTF-8 bytes as base64; `whole` when every recorded byte fits the replay limit. */
  | {
      readonly kind: "base64";
      readonly encoded: string;
      readonly whole: boolean;
    }
  /** UTF-8 text over the replay limit or cut when retained; replay answers with a prefix. */
  | { readonly kind: "cut"; readonly text: string }
  | { readonly kind: "json"; readonly value: JsonValue }
  | { readonly kind: "text"; readonly text: string };

/** Bytes a padded base64 string decodes to. */
const decodedBase64Bytes = (encoded: string): number =>
  Math.floor((encoded.length * 3) / 4) -
  (encoded.endsWith("==") ? 2 : encoded.endsWith("=") ? 1 : 0);

/** Classify a retained body once: whole JSON-like UTF-8 text within the limit that parses exactly is JSON. */
export const replayedBody = (exchange: RecordedExchange): ReplayedBody => {
  const text = exchange.bodyText;
  if (text === null) return { kind: "none" };
  if (exchange.bodyEncoding === "base64")
    return {
      kind: "base64",
      encoded: text,
      whole:
        exchange.bodyCut !== true &&
        decodedBase64Bytes(text) <= REPLAY_BODY_LIMIT_BYTES,
    };
  if (
    exchange.bodyCut === true ||
    // UTF-8 never takes fewer bytes than UTF-16 units, so the length check avoids encoding huge text.
    text.length > REPLAY_BODY_LIMIT_BYTES ||
    Buffer.byteLength(text, "utf8") > REPLAY_BODY_LIMIT_BYTES
  )
    return { kind: "cut", text };
  const value =
    exchange.contentType !== null &&
    isJsonLike(mediaTypeEssence(exchange.contentType))
      ? parseExactJson(text)
      : undefined;
  return value === undefined ? { kind: "text", text } : { kind: "json", value };
};

/** A HAR inspected by inspect_web_network_capture, or a session recorded by capture_browser_scenario. */
export type EnvironmentCaptureKind = "web-network-capture" | "browser-scenario";

/** A manifest and the parent capture it cites, authenticated and cross-checked. */
export interface EnvironmentSource {
  readonly manifest: EnvironmentManifest;
  readonly manifestEvidenceId: string;
  readonly evidenceId: string;
  /** Which REA operation recorded the parent capture. */
  readonly captureKind: EnvironmentCaptureKind;
  /**
   * SHA-256 of the captured artifact for a web network capture, or of the scenario definition for a
   * browser scenario; null when the capture excluded it from Evidence.
   */
  readonly captureSha256: string | null;
  /** Parent records cited by at least one tool, keyed by producer ordinal. */
  readonly exchanges: ReadonlyMap<number, RecordedExchange>;
}

/** An input refusal whose issue paths name the offending file. */
export const inputError = (
  operation: string,
  issues: readonly AnalysisInputIssue[],
  userMessage?: string,
): AnalysisInputError =>
  new AnalysisInputError(
    operation,
    userMessage === undefined ? undefined : { userMessage },
    issues,
  );

/** Authenticate one Evidence file; schema failures name the file role in their paths. */
export const parseEvidenceFile = (
  operation: string,
  role: "manifest" | "evidence" | "state",
  value: unknown,
): Result<Evidence, AnalysisError> => {
  try {
    for (const key of ["parameters", "raw_result", "normalized_result"])
      immutableJsonSnapshotMember(value, key);
    return ok(immutableEvidence(value));
  } catch (cause: unknown) {
    if (!(cause instanceof z.ZodError)) throw cause;
    return err(
      inputError(
        operation,
        projectInputIssues(cause.issues, value).map((issue) => ({
          ...issue,
          path: [role, ...issue.path],
        })),
        `The ${role} file is not authenticated REA Evidence JSON.`,
      ),
    );
  }
};

const recordedExchange = (
  record: WebNetworkCaptureRecord,
): RecordedExchange | undefined => {
  const line = readRecordedRequestLine(record.reported, true, () => true);
  if (line === null || line.kind !== "line") return undefined;
  return {
    ordinal: record.ordinal,
    path: line.path,
    query: line.query === undefined || line.query === "" ? null : line.query,
    status: line.status,
    contentType: line.rawMime === "" ? null : line.rawMime,
    ...readRecordedResponseBody(record, REPLAY_BODY_LIMIT_BYTES),
  };
};

/** Authenticate a view Evidence file and require one view kind; a refusal names the file role. */
export const parseViewEvidence = <Kind extends AnalysisViewResult["kind"]>(
  operation: string,
  role: "manifest" | "state",
  value: unknown,
  kind: Kind,
): Result<
  {
    readonly view: Extract<AnalysisViewResult, { kind: Kind }>;
    readonly evidenceId: string;
  },
  AnalysisError
> => {
  const evidence = parseEvidenceFile(operation, role, value);
  if (!evidence.ok) return evidence;
  const view = analysisViewResultSchema.safeParse(
    evidence.value.normalized_result,
  );
  if (
    evidence.value.operation !== "inspect_analysis_view" ||
    !view.success ||
    view.data.kind !== kind
  )
    return err(
      inputError(
        operation,
        [
          {
            path: [role, "normalized_result", "kind"],
            reason: "invalid_value",
            expected: kind,
            message: `The ${role} file must be inspect_analysis_view Evidence of kind ${kind}.`,
          },
        ],
        `The ${role} file is not ${kind} view Evidence.`,
      ),
    );
  return ok({
    view: view.data as Extract<AnalysisViewResult, { kind: Kind }>,
    evidenceId: evidence.value.evidence_id,
  });
};

/** Authenticate the evidence file and require complete capture Evidence of either kind. */
const parseCaptureEvidence = (
  operation: string,
  value: unknown,
): Result<
  {
    readonly records: readonly WebNetworkCaptureRecord[];
    readonly evidenceId: string;
    readonly captureKind: EnvironmentCaptureKind;
    readonly captureSha256: string | null;
  },
  AnalysisError
> => {
  const evidence = parseEvidenceFile(operation, "evidence", value);
  if (!evidence.ok) return evidence;
  const { evidence_id: evidenceId } = evidence.value;
  const normalized = immutableJsonSnapshotMember(
    evidence.value,
    "normalized_result",
  );
  if (evidence.value.operation === "capture_browser_scenario") {
    const scenario = browserScenarioCaptureSchema.safeParse(normalized);
    const definition = z
      .object({ scenario_sha256: z.string() })
      .safeParse(evidence.value.parameters);
    if (scenario.success)
      return ok({
        records: scenarioCaptureRecords(scenario.data, "replay").records,
        evidenceId,
        captureKind: "browser-scenario",
        captureSha256: definition.success
          ? definition.data.scenario_sha256
          : null,
      });
  } else if (evidence.value.operation === "inspect_web_network_capture") {
    const records = immutableJsonSnapshotMember(normalized, "records");
    if (Array.isArray(records))
      for (let index = 0; index < records.length; index += 1) {
        const record = immutableJsonSnapshotMember(records, String(index));
        immutableJsonSnapshotMember(record, "reported");
      }
    // An owned snapshot is validated once and borrowed, so deriving the state reuses this validation.
    const capture = safeParseOwnedWebNetworkCapture(normalized);
    if (capture.success) {
      // The manifest view projects HAR captures only, and replay reads HAR's response fields.
      if (capture.data.format !== "har")
        return err(
          inputError(
            operation,
            [
              {
                path: ["evidence", "normalized_result", "format"],
                reason: "invalid_value",
                expected: "har",
                message: `Agent environments replay HAR captures; this capture's format is ${capture.data.format}.`,
              },
            ],
            "The evidence file is not a HAR capture.",
          ),
        );
      return ok({
        records: capture.data.records,
        evidenceId,
        captureKind: "web-network-capture",
        captureSha256: capture.data.artifact.sha256,
      });
    }
  }
  return err(
    inputError(
      operation,
      [
        {
          path: ["evidence", "operation"],
          reason: "invalid_value",
          expected: "inspect_web_network_capture or capture_browser_scenario",
          message:
            "The evidence file must be complete inspect_web_network_capture or capture_browser_scenario Evidence.",
        },
      ],
      "The evidence file is not web network capture or browser scenario Evidence.",
    ),
  );
};

/**
 * Reduce every record a tool cites to its replayable exchange. Authentication
 * already proves the capture is the manifest's parent, so every cited ordinal
 * is a record with a request line; a record that still yields none is left
 * out and the tool refuses at call time.
 */
const indexExchanges = (
  manifest: EnvironmentManifest,
  records: readonly WebNetworkCaptureRecord[],
): ReadonlyMap<number, RecordedExchange> => {
  const byOrdinal = new Map(records.map((record) => [record.ordinal, record]));
  const exchanges = new Map<number, RecordedExchange>();
  for (const tool of manifest.tools)
    for (const ordinal of tool.record_ordinals) {
      if (exchanges.has(ordinal)) continue;
      const record = byOrdinal.get(ordinal);
      const exchange =
        record === undefined ? undefined : recordedExchange(record);
      if (exchange !== undefined) exchanges.set(ordinal, exchange);
    }
  return exchanges;
};

/**
 * Load the manifest Evidence and its parent capture Evidence, refusing any pair
 * that does not belong together; refusals name the command that loaded them.
 */
export const loadEnvironmentSource = (
  manifestValue: unknown,
  evidenceValue: unknown,
  operation: string = ENVIRONMENT_SERVE_OPERATION,
): Result<EnvironmentSource, AnalysisError> => {
  const manifest = parseViewEvidence(
    operation,
    "manifest",
    manifestValue,
    "environment-manifest",
  );
  if (!manifest.ok) return manifest;
  const capture = parseCaptureEvidence(operation, evidenceValue);
  if (!capture.ok) return capture;
  const parentId = manifest.value.view.parent_evidence_id;
  if (parentId !== capture.value.evidenceId)
    return err(
      inputError(
        operation,
        [
          {
            path: ["evidence", "evidence_id"],
            reason: "invalid_value",
            expected: parentId,
            message: `The manifest cites parent Evidence ${parentId}; the evidence file is ${capture.value.evidenceId}.`,
          },
        ],
        "The manifest was projected from a different capture than the supplied evidence file.",
      ),
    );
  return ok({
    manifest: manifest.value.view,
    manifestEvidenceId: manifest.value.evidenceId,
    evidenceId: capture.value.evidenceId,
    captureKind: capture.value.captureKind,
    captureSha256: capture.value.captureSha256,
    exchanges: indexExchanges(manifest.value.view, capture.value.records),
  });
};