rea-agents 6.3.0 → 6.5.0

package/dist/domain/analysisView/nativeFunctionView.js

@@ -0,0 +1,150 @@
+import { analysisViewInputError } from "./analysisViewErrors.js";
+import { analysisTextPage } from "./analysisViewText.js";
+import { uniqueSorted } from "../canonicalOrdering.js";
+import { jsonValueSchema } from "../jsonValue.js";
+import { err, ok } from "../result.js";
+import { completeWithinViewCoverage, pageViewCoverage, } from "./analysisViewCoverage.js";
+const viewError = (message) => analysisViewInputError([
+    { path: ["view"], reason: "invalid_value", message },
+]);
+const parentFields = (parent, dossier, artifact) => {
+    const flow = dossier.native_value_flow;
+    const api = dossier.native_api;
+    const unknowns = [];
+    if (flow === null)
+        unknowns.push("native_value_flow was not recorded");
+    else if (!flow.available)
+        unknowns.push("native_value_flow unavailable: " + flow.reason);
+    else if (flow.truncated)
+        unknowns.push("native_value_flow is truncated; omitted observations remain unknown");
+    if (api === null)
+        unknowns.push("native_api was not recorded");
+    else if (!api.available)
+        unknowns.push("native_api unavailable: " + api.reason, ...api.residual_unknowns);
+    return {
+        parent_evidence_id: parent.evidenceId,
+        parent_operation: "analyze_function",
+        parent_digest: parent.evidenceId.slice(3),
+        procedure_address: dossier.procedure.address,
+        artifact,
+        limitations: uniqueSorted([
+            ...parent.limitations,
+            ...dossier.limitations,
+            ...(flow?.limitations ?? []),
+            ...(api?.available ? api.limitations : []),
+        ]),
+        unknowns: uniqueSorted(unknowns),
+    };
+};
+const nativeRows = (dossier, facet) => {
+    const sourceFlow = dossier.native_value_flow;
+    const flow = sourceFlow?.available ? sourceFlow : undefined;
+    return {
+        assembly: dossier.assembly,
+        basic_blocks: dossier.basic_blocks,
+        comments: dossier.comments,
+        callers: dossier.callers,
+        callees: dossier.callees,
+        incoming_references: dossier.incoming_references,
+        outgoing_references: dossier.outgoing_references,
+        unresolved_calls: dossier.unresolved_calls,
+        referenced_strings: dossier.referenced_strings,
+        referenced_names: dossier.referenced_names,
+        swift_string_literals: dossier.swift_string_literals,
+        swift_string_literal_omissions: dossier.swift_string_literal_omissions,
+        value_flow_operations: flow?.operations,
+        value_flow_def_use: flow?.def_use,
+        value_flow_effects: flow?.effects,
+        value_flow_parameters: flow?.parameters,
+        value_flow_parameter_uses: flow?.parameter_uses,
+    }[facet];
+};
+/** Project bounded native function facets from complete retained Evidence without reanalysis. */
+export const projectNativeFunctionView = (parent, dossier, view) => {
+    if (view.kind !== "native")
+        return err(viewError("analyze_function Evidence requires a native view."));
+    const artifact = parent.artifact;
+    if (!artifact)
+        return err(analysisViewInputError([
+            {
+                path: ["source", "subject"],
+                reason: "invalid_value",
+                message: "Native function Evidence requires an artifact-bound subject.",
+            },
+        ]));
+    const common = parentFields(parent, dossier, artifact);
+    const availabilityKeys = {
+        incoming_references: "references",
+        outgoing_references: "references",
+        referenced_strings: "strings_names",
+        referenced_names: "strings_names",
+        basic_blocks: "cfg",
+    };
+    const availabilityKey = availabilityKeys[view.facet] ?? view.facet;
+    const availability = dossier.facet_availability?.[availabilityKey];
+    if (availability?.available === false)
+        common.unknowns = uniqueSorted([...common.unknowns, availability.reason]);
+    const singleton = (item) => ({
+        kind: "native",
+        view,
+        item: jsonValueSchema.parse(item),
+        coverage: completeWithinViewCoverage(1, 1),
+        ...common,
+    });
+    if (availability?.available === false)
+        return ok(singleton(availability));
+    const flow = dossier.native_value_flow;
+    if (view.facet === "procedure" ||
+        view.facet === "native_api" ||
+        view.facet === "value_flow_summary") {
+        if (view.offset !== 0)
+            return err(viewError("Singleton native facets require offset 0."));
+        if (view.facet === "procedure")
+            return ok(singleton(dossier.procedure));
+        if (view.facet === "native_api")
+            return ok(singleton(dossier.native_api ?? { available: false, reason: "not recorded" }));
+        const status = flow === null
+            ? { available: false, reason: "not recorded" }
+            : !flow.available
+                ? { available: false, reason: flow.reason }
+                : {
+                    available: true,
+                    provenance: flow.provenance,
+                    truncated: flow.truncated,
+                    omitted_operations_lower_bound: flow.omitted_operations_lower_bound,
+                    known_omitted_inputs: flow.known_omitted_inputs,
+                    known_omitted_edges: flow.known_omitted_edges,
+                    operations: flow.operations.length,
+                    def_use: flow.def_use.length,
+                    effects: flow.effects.length,
+                    parameters: flow.parameters.length,
+                    parameter_uses: flow.parameter_uses.length,
+                };
+        return ok(singleton(status));
+    }
+    if (view.facet === "pseudocode") {
+        const page = analysisTextPage(dossier.pseudocode, view.offset, view.limit);
+        return page.ok
+            ? ok({ kind: "native", view, ...page.value, ...common })
+            : page;
+    }
+    const rows = nativeRows(dossier, view.facet);
+    if (rows === undefined)
+        return ok(singleton({
+            available: false,
+            // Only value-flow facets inherit the value-flow failure reason; an
+            // older dossier simply has no unresolved_calls record, and a target
+            // whose provider does not decode Swift literals has no such record.
+            reason: view.facet.startsWith("value_flow_") && flow?.available === false
+                ? flow.reason
+                : "not recorded",
+        }));
+    const items = rows.slice(view.offset, view.offset + view.limit);
+    return ok({
+        kind: "native",
+        view,
+        item: jsonValueSchema.parse(items),
+        coverage: pageViewCoverage(view.offset, items.length, rows.length),
+        ...common,
+    });
+};

package/dist/domain/analysisView/pcapCaptureView.js

@@ -0,0 +1,264 @@
+import { analysisViewInputError } from "./analysisViewErrors.js";
+import { z } from "zod";
+import { pcapResultSchemas } from "../pcap/pcapAnalysis.js";
+import { analysisInputErrorFromIssues } from "../inputIssueProjection.js";
+import { err, ok } from "../result.js";
+import { completeWithinViewCoverage, pageViewCoverage, } from "./analysisViewCoverage.js";
+import { analysisTextPage } from "./analysisViewText.js";
+const captureSchema = pcapResultSchemas.inspect_pcap_capture;
+const fields = captureSchema.shape;
+const pageShape = {
+    kind: z.literal("pcap"),
+    offset: z.number().int().nonnegative().default(0),
+    limit: z.number().int().positive().default(64),
+};
+export const pcapViewRequestSchema = z.discriminatedUnion("facet", [
+    z.strictObject({
+        ...pageShape,
+        facet: z.enum([
+            "endpoints",
+            "dns-queries",
+            "tls-sni",
+            "protocols",
+            "http-uris",
+            "unattributed-addresses",
+        ]),
+    }),
+    z.strictObject({
+        ...pageShape,
+        facet: z.literal("dns-addresses"),
+        query: z.string().min(1),
+    }),
+    z.strictObject({
+        ...pageShape,
+        facet: z.literal("diagnostics"),
+        stream: z.enum(["tshark", "capinfos"]),
+    }),
+]);
+export const pcapViewPageSchema = z.discriminatedUnion("facet", [
+    z.strictObject({ facet: z.literal("endpoints"), items: fields.endpoints }),
+    z.strictObject({
+        facet: z.literal("dns-queries"),
+        items: z.array(fields.dns_queries.element.omit({ response_addresses: true }).extend({
+            retained_response_address_count: z.number().int().nonnegative(),
+        })),
+    }),
+    z.strictObject({ facet: z.literal("tls-sni"), items: fields.tls_sni_values }),
+    z.strictObject({
+        facet: z.literal("protocols"),
+        items: fields.protocol_distribution,
+    }),
+    z.strictObject({
+        facet: z.literal("http-uris"),
+        items: fields.http_request_uris,
+    }),
+    z.strictObject({
+        facet: z.literal("unattributed-addresses"),
+        items: fields.unattributed_dns_addresses,
+    }),
+    z.strictObject({
+        facet: z.literal("dns-addresses"),
+        items: fields.unattributed_dns_addresses,
+    }),
+    z.strictObject({
+        facet: z.literal("diagnostics"),
+        text: z.string(),
+        status: z.enum(["retained", "unknown"]),
+    }),
+]);
+export const pcapSummarySchema = captureSchema
+    .omit({
+    endpoints: true,
+    dns_queries: true,
+    tls_sni_values: true,
+    protocol_distribution: true,
+    http_request_uris: true,
+    unattributed_dns_addresses: true,
+    diagnostics: true,
+})
+    .extend({
+    retained_counts: z.strictObject({
+        endpoints: z.number().int().nonnegative(),
+        dns_queries: z.number().int().nonnegative(),
+        tls_sni_values: z.number().int().nonnegative(),
+        protocol_distribution: z.number().int().nonnegative(),
+        http_request_uris: z.number().int().nonnegative(),
+        unattributed_dns_addresses: z.number().int().nonnegative(),
+    }),
+    diagnostics_code_units: z
+        .strictObject({
+        tshark: z.number().int().nonnegative(),
+        capinfos: z.number().int().nonnegative(),
+    })
+        .nullable(),
+});
+const parseParent = (parent) => {
+    const parsed = captureSchema.safeParse(parent.normalizedResult);
+    if (!parsed.success)
+        return err(analysisInputErrorFromIssues("inspect_analysis_view", parsed.error.issues, parent.normalizedResult, { cause: parsed.error }));
+    if (parent.subject?.local_path !== parsed.data.target.path ||
+        parent.subject.digest.sha256 !== parsed.data.target.sha256)
+        return err(analysisViewInputError([
+            {
+                path: ["source", "subject"],
+                reason: "invalid_value",
+                message: "Packet parent subject must identify the report's exact path and SHA-256.",
+            },
+        ]));
+    return ok(parsed.data);
+};
+const summarize = ({ endpoints, dns_queries, tls_sni_values, protocol_distribution, http_request_uris, unattributed_dns_addresses, diagnostics, ...metadata }) => ({
+    ...metadata,
+    retained_counts: {
+        endpoints: endpoints.length,
+        dns_queries: dns_queries.length,
+        tls_sni_values: tls_sni_values.length,
+        protocol_distribution: protocol_distribution.length,
+        http_request_uris: http_request_uris.length,
+        unattributed_dns_addresses: unattributed_dns_addresses.length,
+    },
+    diagnostics_code_units: diagnostics === undefined
+        ? null
+        : {
+            tshark: diagnostics.tshark_stderr.length,
+            capinfos: diagnostics.capinfos_stderr.length,
+        },
+});
+const selectRows = (capture, view) => {
+    const slice = (items) => items.slice(view.offset, view.offset + view.limit);
+    switch (view.facet) {
+        case "endpoints":
+            return ok({
+                page: { facet: view.facet, items: slice(capture.endpoints) },
+                total: capture.endpoints.length,
+            });
+        case "dns-queries":
+            return ok({
+                page: {
+                    facet: view.facet,
+                    items: slice(capture.dns_queries).map(({ response_addresses, ...query }) => ({
+                        ...query,
+                        retained_response_address_count: response_addresses.length,
+                    })),
+                },
+                total: capture.dns_queries.length,
+            });
+        case "tls-sni":
+            return ok({
+                page: { facet: view.facet, items: slice(capture.tls_sni_values) },
+                total: capture.tls_sni_values.length,
+            });
+        case "protocols":
+            return ok({
+                page: {
+                    facet: view.facet,
+                    items: slice(capture.protocol_distribution),
+                },
+                total: capture.protocol_distribution.length,
+            });
+        case "http-uris":
+            return ok({
+                page: { facet: view.facet, items: slice(capture.http_request_uris) },
+                total: capture.http_request_uris.length,
+            });
+        case "unattributed-addresses":
+            return ok({
+                page: {
+                    facet: view.facet,
+                    items: slice(capture.unattributed_dns_addresses),
+                },
+                total: capture.unattributed_dns_addresses.length,
+            });
+        case "dns-addresses": {
+            const matches = capture.dns_queries.filter((query) => query.query === view.query);
+            if (matches.length !== 1)
+                return err(analysisViewInputError([
+                    {
+                        path: ["view", "query"],
+                        reason: "invalid_value",
+                        message: "Select one unambiguous exact retained DNS question.",
+                    },
+                ]));
+            return ok({
+                page: {
+                    facet: view.facet,
+                    items: slice(matches[0].response_addresses),
+                },
+                total: matches[0].response_addresses.length,
+            });
+        }
+    }
+};
+/** Historical packet facts are paged without reopening the source or rerunning Wireshark. */
+export const projectPcapCaptureView = (parent, view) => {
+    if (view.kind !== "summary" && view.kind !== "pcap")
+        return err(analysisViewInputError([
+            {
+                path: ["view"],
+                reason: "invalid_value",
+                message: "Packet summary parents support summary and pcap fact pages.",
+            },
+        ]));
+    const parsed = parseParent(parent);
+    if (!parsed.ok)
+        return parsed;
+    const capture = parsed.value;
+    const shared = {
+        parent_evidence_id: parent.evidenceId,
+        parent_operation: "inspect_pcap_capture",
+        parent_digest: parent.evidenceId.slice(3),
+        artifact: { path: capture.target.path, sha256: capture.target.sha256 },
+        limitations: [
+            ...parent.limitations,
+            "Page totals count retained rows or UTF-16 diagnostic code units. Exhaustion does not prove whole-network completeness; source coverage and examined counts remain separate.",
+        ],
+        unknowns: [
+            "Saved packet observations do not establish process identity, causality, encrypted payload contents or traffic missing from the recording.",
+        ],
+    };
+    if (view.kind === "summary")
+        return ok({
+            kind: "summary",
+            view,
+            ...shared,
+            summary: summarize(capture),
+            coverage: completeWithinViewCoverage(1, 1),
+        });
+    if (view.facet === "diagnostics") {
+        const value = view.stream === "tshark"
+            ? capture.diagnostics?.tshark_stderr
+            : capture.diagnostics?.capinfos_stderr;
+        const text = analysisTextPage(value ?? "", view.offset, view.limit, "Diagnostics");
+        if (!text.ok)
+            return text;
+        return ok({
+            kind: "pcap",
+            view,
+            ...shared,
+            source_coverage: capture.coverage,
+            page: {
+                facet: "diagnostics",
+                text: text.value.item.text,
+                status: value === undefined ? "unknown" : "retained",
+            },
+            coverage: text.value.coverage,
+            unknowns: value === undefined
+                ? [
+                    ...shared.unknowns,
+                    "The parent did not retain diagnostics; an empty text page does not establish their absence.",
+                ]
+                : shared.unknowns,
+        });
+    }
+    const selected = selectRows(capture, view);
+    return selected.ok
+        ? ok({
+            kind: "pcap",
+            view,
+            ...shared,
+            source_coverage: capture.coverage,
+            page: selected.value.page,
+            coverage: pageViewCoverage(view.offset, selected.value.page.items.length, selected.value.total),
+        })
+        : selected;
+};

package/dist/domain/analysisView/qlogCaptureView.js

@@ -0,0 +1,198 @@
+import { z } from "zod";
+import { qlogCaptureFactsSchema, } from "../qlogCapture.js";
+import { err, ok } from "../result.js";
+import { analysisViewInputError } from "./analysisViewErrors.js";
+import { pageViewCoverage } from "./analysisViewCoverage.js";
+const traceSchema = qlogCaptureFactsSchema.shape.traces.element;
+const streamSchema = traceSchema.shape.streams.element;
+export const qlogViewContextSchema = qlogCaptureFactsSchema.omit({
+    traces: true,
+});
+export const qlogSummarySchema = qlogViewContextSchema.extend({
+    trace_count: z.number().int().nonnegative(),
+    retained_stream_count: z.number().int().nonnegative(),
+    loss_declaration_count: z.number().int().nonnegative(),
+    incomplete_fact_record_count: z.number().int().nonnegative(),
+});
+/** Select retained trace facts without copying event inventories or every contribution. */
+const pageRequestShape = {
+    kind: z.literal("qlog"),
+    offset: z.number().int().nonnegative().default(0),
+    limit: z.number().int().positive().default(64),
+};
+const traceSelectorShape = { trace_index: z.number().int().nonnegative() };
+const streamSelectorShape = {
+    ...traceSelectorShape,
+    stream_id: streamSchema.shape.stream_id,
+    direction: streamSchema.shape.direction,
+};
+export const qlogViewRequestSchema = z.discriminatedUnion("facet", [
+    z.strictObject({ ...pageRequestShape, facet: z.literal("traces") }),
+    z.strictObject({
+        ...pageRequestShape,
+        ...traceSelectorShape,
+        facet: z.literal("streams"),
+    }),
+    z.strictObject({
+        ...pageRequestShape,
+        ...traceSelectorShape,
+        facet: z.literal("loss-declarations"),
+    }),
+    z.strictObject({
+        ...pageRequestShape,
+        ...traceSelectorShape,
+        facet: z.literal("incomplete-records"),
+    }),
+    z.strictObject({
+        ...pageRequestShape,
+        ...streamSelectorShape,
+        facet: z.literal("contributions"),
+    }),
+    z.strictObject({
+        ...pageRequestShape,
+        ...streamSelectorShape,
+        facet: z.literal("ranges"),
+    }),
+    z.strictObject({
+        ...pageRequestShape,
+        ...streamSelectorShape,
+        facet: z.literal("final-sizes"),
+    }),
+]);
+const traceSummarySchema = traceSchema
+    .omit({
+    streams: true,
+    loss_declarations: true,
+    incomplete_fact_records: true,
+})
+    .extend({
+    stream_count: z.number().int().nonnegative(),
+    loss_declaration_count: z.number().int().nonnegative(),
+    incomplete_fact_record_count: z.number().int().nonnegative(),
+});
+const streamSummarySchema = streamSchema
+    .omit({
+    contributions: true,
+    covered_ranges: true,
+    reported_final_sizes: true,
+})
+    .extend({
+    contribution_count: z.number().int().nonnegative(),
+    covered_range_count: z.number().int().nonnegative(),
+    reported_final_size_count: z.number().int().nonnegative(),
+});
+/** Each page advertises exactly the retained item contract for its facet. */
+export const qlogViewPageSchema = z.discriminatedUnion("facet", [
+    z.strictObject({
+        facet: z.literal("traces"),
+        items: z.array(traceSummarySchema),
+    }),
+    z.strictObject({
+        facet: z.literal("streams"),
+        items: z.array(streamSummarySchema),
+    }),
+    z.strictObject({
+        facet: z.literal("loss-declarations"),
+        items: traceSchema.shape.loss_declarations,
+    }),
+    z.strictObject({
+        facet: z.literal("incomplete-records"),
+        items: traceSchema.shape.incomplete_fact_records,
+    }),
+    z.strictObject({
+        facet: z.literal("contributions"),
+        items: streamSchema.shape.contributions,
+    }),
+    z.strictObject({
+        facet: z.literal("ranges"),
+        items: streamSchema.shape.covered_ranges,
+    }),
+    z.strictObject({
+        facet: z.literal("final-sizes"),
+        items: streamSchema.shape.reported_final_sizes,
+    }),
+]);
+export const summarizeQlogCapture = (qlog) => {
+    const { traces, ...context } = qlog;
+    return {
+        ...context,
+        trace_count: traces.length,
+        retained_stream_count: traces.reduce((sum, trace) => sum + trace.streams.length, 0),
+        loss_declaration_count: traces.reduce((sum, trace) => sum + trace.loss_declarations.length, 0),
+        incomplete_fact_record_count: traces.reduce((sum, trace) => sum + trace.incomplete_fact_records.length, 0),
+    };
+};
+const summarizeTrace = ({ streams, loss_declarations, incomplete_fact_records, ...trace }) => ({
+    ...trace,
+    stream_count: streams.length,
+    loss_declaration_count: loss_declarations.length,
+    incomplete_fact_record_count: incomplete_fact_records.length,
+});
+const summarizeStream = ({ contributions, covered_ranges, reported_final_sizes, ...stream }) => ({
+    ...stream,
+    contribution_count: contributions.length,
+    covered_range_count: covered_ranges.length,
+    reported_final_size_count: reported_final_sizes.length,
+});
+/** Array offsets refer to retained facts, whose scope remains all recorded events. */
+export const projectQlogCapturePage = (qlog, view) => {
+    const invalid = (field, message) => err(analysisViewInputError([
+        { path: ["view", field], reason: "invalid_value", message },
+    ]));
+    const slice = (items) => items.slice(view.offset, view.offset + view.limit);
+    let page;
+    let total;
+    if (view.facet === "traces") {
+        total = qlog.traces.length;
+        page = {
+            facet: "traces",
+            items: slice(qlog.traces).map(summarizeTrace),
+        };
+    }
+    else {
+        const matches = qlog.traces.filter((trace) => trace.trace_index === view.trace_index);
+        if (matches.length !== 1)
+            return invalid("trace_index", "Select one unambiguous retained trace index.");
+        const trace = matches[0];
+        if (view.facet === "streams") {
+            total = trace.streams.length;
+            page = {
+                facet: "streams",
+                items: slice(trace.streams).map(summarizeStream),
+            };
+        }
+        else if (view.facet === "loss-declarations") {
+            total = trace.loss_declarations.length;
+            page = { facet: view.facet, items: slice(trace.loss_declarations) };
+        }
+        else if (view.facet === "incomplete-records") {
+            total = trace.incomplete_fact_records.length;
+            page = { facet: view.facet, items: slice(trace.incomplete_fact_records) };
+        }
+        else {
+            const matches = trace.streams.filter((stream) => stream.stream_id === view.stream_id &&
+                stream.direction === view.direction);
+            if (matches.length !== 1)
+                return invalid("stream_id", "Select one unambiguous retained stream ID and direction within the trace.");
+            const stream = matches[0];
+            if (view.facet === "contributions") {
+                total = stream.contributions.length;
+                page = { facet: view.facet, items: slice(stream.contributions) };
+            }
+            else if (view.facet === "ranges") {
+                total = stream.covered_ranges.length;
+                page = { facet: view.facet, items: slice(stream.covered_ranges) };
+            }
+            else {
+                total = stream.reported_final_sizes.length;
+                page = { facet: view.facet, items: slice(stream.reported_final_sizes) };
+            }
+        }
+    }
+    const { traces: _traces, ...context } = qlog;
+    return ok({
+        context,
+        page,
+        coverage: pageViewCoverage(view.offset, page.items.length, total),
+    });
+};