rea-agents 6.4.0 → 6.7.0

package/dist/domain/analysisView/machoView.js

@@ -0,0 +1,186 @@
+import { analysisViewInputError } from "./analysisViewErrors.js";
+import { z } from "zod";
+import { uniqueSorted } from "../canonicalOrdering.js";
+import { isMachOFormat } from "../binaryTargetTypes.js";
+import { inspectMachoSchema } from "../native/nativeInspection.js";
+import { err, ok } from "../result.js";
+import { parseAnalysisViewResult } from "./analysisViewParent.js";
+import { completeWithinViewCoverage, pageViewCoverage, } from "./analysisViewCoverage.js";
+const MACHO_COLLECTIONS = [
+    "entrypoints",
+    "architectures",
+    "build_metadata",
+    "load_commands",
+    "dependencies",
+    "imports",
+    "exports",
+    "segments",
+];
+/** Original inspect_macho rows; offsets count rows in the retained collection. */
+export const machoViewRequestSchema = z.strictObject({
+    kind: z.literal("macho"),
+    facet: z.enum([...MACHO_COLLECTIONS, "provenance"]),
+    offset: z.number().int().nonnegative().default(0),
+    limit: z.number().int().positive().default(64),
+});
+const { shape } = inspectMachoSchema;
+/**
+ * Union members are tried in order and plain objects drop unknown keys, so a
+ * segment or architecture row would otherwise match the entrypoint row and
+ * lose every field but file_offset. Exact key sets keep each page's rows whole.
+ */
+const exactRows = (rows) => z.array(z.strictObject(rows.element.shape));
+export const machoViewItemSchema = z.union([
+    exactRows(shape.entrypoints.shape.items),
+    exactRows(shape.architectures.shape.items),
+    exactRows(shape.build_metadata.shape.items),
+    exactRows(shape.load_commands.shape.items),
+    exactRows(shape.dependencies.shape.items),
+    // Imports and exports share one row shape.
+    exactRows(shape.imports.shape.items),
+    exactRows(shape.segments.shape.items),
+    exactRows(shape.provenance),
+]);
+/** The producer's own coverage of the paged collection, not of this page. */
+export const machoViewContextSchema = z.strictObject({
+    source_total: z.number().int().nonnegative().nullable(),
+    source_exhaustive: z.boolean(),
+});
+const collectionCountSchema = z.strictObject({
+    returned: z.number().int().nonnegative(),
+    total: z.number().int().nonnegative().nullable(),
+    exhaustive: z.boolean(),
+});
+/** Slice identity and per-collection counts without the collections themselves. */
+export const machoSummarySchema = z.strictObject({
+    format: shape.format,
+    selected_architecture: shape.selected_architecture,
+    endian: shape.endian,
+    word_size: shape.word_size,
+    file_type: shape.file_type,
+    flags: shape.flags,
+    uuid: shape.uuid,
+    collections: z.strictObject(Object.fromEntries(MACHO_COLLECTIONS.map((name) => [name, collectionCountSchema]))),
+    provenance_count: z.number().int().nonnegative(),
+    limitation_count: z.number().int().nonnegative(),
+});
+/** Admit a well-formed report whose recorded subject, if any, is a Mach-O. */
+const parseMachoReport = (parent) => {
+    const parsed = parseAnalysisViewResult(inspectMachoSchema, parent);
+    if (!parsed.ok)
+        return parsed;
+    if (parent.subject != null && !isMachOFormat(parent.subject.format))
+        return err(analysisViewInputError([
+            {
+                path: ["source", "subject"],
+                reason: "invalid_value",
+                message: "Mach-O parent Evidence subject must identify a thin or universal Mach-O.",
+            },
+        ]));
+    return ok(parsed.value);
+};
+/** Counts replace rows; every collection caveat stays in the limitations. */
+const summarizeMacho = (report, parentLimitations) => {
+    const limitations = uniqueSorted([
+        ...parentLimitations,
+        ...report.limitations,
+        ...MACHO_COLLECTIONS.flatMap((name) => report[name].limitations),
+    ]);
+    const collections = Object.fromEntries(MACHO_COLLECTIONS.map((name) => [
+        name,
+        {
+            returned: report[name].items.length,
+            total: report[name].total,
+            exhaustive: report[name].exhaustive,
+        },
+    ]));
+    return {
+        limitations,
+        returned: MACHO_COLLECTIONS.reduce((sum, name) => sum + report[name].items.length, 0),
+        summary: {
+            format: report.format,
+            selected_architecture: report.selected_architecture,
+            endian: report.endian,
+            word_size: report.word_size,
+            file_type: report.file_type,
+            flags: report.flags,
+            uuid: report.uuid,
+            collections,
+            provenance_count: report.provenance.length,
+            limitation_count: limitations.length,
+        },
+    };
+};
+/** Project retained inspect_macho Evidence without rerunning native tools. */
+export const projectMachoView = (parent, view) => {
+    if (view.kind !== "summary" && view.kind !== "macho")
+        return err(analysisViewInputError([
+            {
+                path: ["view"],
+                reason: "invalid_value",
+                message: "Mach-O inspection supports summary and macho views.",
+            },
+        ]));
+    const parsed = parseMachoReport(parent);
+    if (!parsed.ok)
+        return parsed;
+    const report = parsed.value;
+    const incomplete = MACHO_COLLECTIONS.filter((name) => !report[name].exhaustive);
+    const shared = {
+        parent_evidence_id: parent.evidenceId,
+        parent_operation: "inspect_macho",
+        parent_digest: parent.evidenceId.slice(3),
+        artifact: parent.subject == null
+            ? { path: "", sha256: null }
+            : {
+                path: parent.subject.local_path,
+                sha256: parent.subject.digest.sha256,
+            },
+        unknowns: [
+            ...(incomplete.length === 0
+                ? []
+                : [
+                    `Native tools did not report exhaustive ${incomplete.join(", ")}; page exhaustion does not establish absence of unreturned rows.`,
+                ]),
+            ...(parent.subject == null
+                ? [
+                    "The parent has no recorded subject, so the inspected artifact path and SHA-256 are unknown.",
+                ]
+                : []),
+        ],
+    };
+    if (view.kind === "summary") {
+        const { summary, limitations, returned } = summarizeMacho(report, parent.limitations);
+        return ok({
+            kind: "summary",
+            view,
+            ...shared,
+            limitations,
+            summary,
+            coverage: completeWithinViewCoverage(returned, returned),
+        });
+    }
+    const source = view.facet === "provenance"
+        ? {
+            items: report.provenance,
+            total: report.provenance.length,
+            exhaustive: true,
+            limitations: [],
+        }
+        : report[view.facet];
+    const item = source.items.slice(view.offset, view.offset + view.limit);
+    return ok({
+        kind: "macho",
+        view,
+        item,
+        ...shared,
+        limitations: uniqueSorted([
+            ...parent.limitations,
+            ...report.limitations,
+            ...source.limitations,
+        ]),
+        source_total: source.total,
+        source_exhaustive: source.exhaustive,
+        coverage: pageViewCoverage(view.offset, item.length, source.items.length),
+    });
+};

package/dist/domain/analysisView/managedArtifactView.js

@@ -0,0 +1,108 @@
+import { analysisViewInputError } from "./analysisViewErrors.js";
+import { z } from "zod";
+import { uniqueSorted } from "../canonicalOrdering.js";
+import { managedArtifactInspectionSchema, managedMemberInspectionSchema, } from "../managed/managedArtifact.js";
+import { err, ok } from "../result.js";
+import { parseAnalysisViewResult } from "./analysisViewParent.js";
+import { completeWithinViewCoverage, pageViewCoverage, } from "./analysisViewCoverage.js";
+/** Original metadata rows; offsets count entries in the returned parent collection. */
+export const managedViewRequestSchema = z.strictObject({
+    kind: z.literal("managed"),
+    collection: z.enum(["references", "resources", "attributes"]),
+    offset: z.number().int().nonnegative().default(0),
+    limit: z.number().int().positive().default(64),
+});
+export const managedViewItemSchema = z.union([
+    managedArtifactInspectionSchema.shape.references,
+    managedArtifactInspectionSchema.shape.resources,
+    managedArtifactInspectionSchema.shape.attributes,
+]);
+/** Keep complete classification and coverage; unrequested inventories remain retained. */
+export const managedSummarySchema = managedArtifactInspectionSchema
+    .omit({ references: true, resources: true, attributes: true })
+    .extend({
+    reported_counts: z.strictObject({
+        references: z.number().int().nonnegative(),
+        resources: z.number().int().nonnegative(),
+        attributes: z.number().int().nonnegative(),
+    }),
+    identity_scope: managedMemberInspectionSchema.shape.identity_scope,
+});
+export const managedViewContextSchema = z.strictObject({
+    identity_scope: managedMemberInspectionSchema.shape.identity_scope,
+    source_metadata_status: managedArtifactInspectionSchema.shape.metadata.shape.status,
+    source_coverage: managedArtifactInspectionSchema.shape.coverage,
+});
+/** Token scope and identity limits shared by every managed metadata view. */
+export const managedViewIdentityUnknowns = (parent, mvid) => [
+    "Metadata tokens are build-local coordinates bound to the recorded artifact SHA-256 and module MVID; this view does not load or execute the assembly.",
+    ...(parent.subject == null
+        ? [
+            "The parent has no recorded subject; its normalized artifact identity cannot be cross-checked against a subject digest.",
+        ]
+        : []),
+    ...(mvid === null
+        ? [
+            "The module MVID is unknown; tokens cannot establish a cross-observation module match.",
+        ]
+        : []),
+];
+/** Project authenticated metadata without reading a path or invoking a provider. */
+export const projectManagedArtifactView = (parent, view) => {
+    if (view.kind !== "summary" && view.kind !== "managed")
+        return err(analysisViewInputError([
+            {
+                path: ["view"],
+                reason: "invalid_value",
+                message: "Managed artifact inspection supports summary and managed views.",
+            },
+        ]));
+    const parsed = parseAnalysisViewResult(managedArtifactInspectionSchema, parent);
+    if (!parsed.ok)
+        return parsed;
+    const report = parsed.value;
+    const identity_scope = {
+        token_identity: "build-local",
+        requires_artifact_sha256: report.artifact.sha256,
+        requires_mvid: report.module?.mvid ?? null,
+    };
+    const shared = {
+        parent_evidence_id: parent.evidenceId,
+        parent_operation: "inspect_managed_artifact",
+        parent_digest: parent.evidenceId.slice(3),
+        artifact: { path: report.artifact.path, sha256: report.artifact.sha256 },
+        limitations: uniqueSorted([...parent.limitations, ...report.limitations]),
+        unknowns: [
+            "Collection counts and pages cover producer-returned rows; metadata completeness remains the original metadata status and coverage, not an absence claim about unreturned rows.",
+            ...managedViewIdentityUnknowns(parent, identity_scope.requires_mvid),
+        ],
+    };
+    if (view.kind === "summary") {
+        const { references, resources, attributes, ...summary } = report;
+        const reported_counts = {
+            references: references.length,
+            resources: resources.length,
+            attributes: attributes.length,
+        };
+        const total = references.length + resources.length + attributes.length;
+        return ok({
+            kind: "summary",
+            view,
+            ...shared,
+            summary: { ...summary, reported_counts, identity_scope },
+            coverage: completeWithinViewCoverage(total, total),
+        });
+    }
+    const collection = report[view.collection];
+    const item = collection.slice(view.offset, view.offset + view.limit);
+    return ok({
+        kind: "managed",
+        view,
+        item,
+        ...shared,
+        identity_scope,
+        source_metadata_status: report.metadata.status,
+        source_coverage: report.coverage,
+        coverage: pageViewCoverage(view.offset, item.length, collection.length),
+    });
+};

package/dist/domain/analysisView/managedMemberView.js

@@ -0,0 +1,215 @@
+import { analysisViewInputError } from "./analysisViewErrors.js";
+import { z } from "zod";
+import { uniqueSorted } from "../canonicalOrdering.js";
+import { managedMemberInspectionSchema, } from "../managed/managedArtifact.js";
+import { err, ok } from "../result.js";
+import { completeWithinViewCoverage, pageViewCoverage, } from "./analysisViewCoverage.js";
+import { managedViewIdentityUnknowns } from "./managedArtifactView.js";
+import { parseAnalysisViewResult } from "./analysisViewParent.js";
+const member = managedMemberInspectionSchema.shape;
+/** Original member rows; offsets count entries in the returned parent collection. */
+export const managedMembersViewRequestSchema = z.strictObject({
+    kind: z.literal("managed-members"),
+    collection: z.enum([
+        "types",
+        "exported_types",
+        "fields",
+        "methods",
+        "member_refs",
+        "call_edges",
+        "field_accesses",
+        "user_strings",
+    ]),
+    offset: z.number().int().nonnegative().default(0),
+    limit: z.number().int().positive().default(64),
+});
+const rowsOf = (collection, rows) => z.strictObject({ collection: z.literal(collection), rows });
+/**
+ * Rows of one collection, keyed by that collection: several row schemas accept
+ * each other's rows after stripping keys, so no union may pick one by order.
+ */
+export const managedMembersViewPageSchema = z.discriminatedUnion("collection", [
+    rowsOf("types", member.types),
+    rowsOf("exported_types", member.exported_types.unwrap().unwrap()),
+    rowsOf("fields", member.fields),
+    rowsOf("methods", member.methods),
+    rowsOf("member_refs", member.member_refs),
+    rowsOf("call_edges", member.call_edges),
+    rowsOf("field_accesses", member.field_accesses),
+    rowsOf("user_strings", member.user_strings.unwrap().unwrap().shape.literals),
+]);
+const nullableCount = z.number().int().nonnegative().nullable();
+/** Keep identity, selection and coverage; member collections remain retained. */
+export const managedMemberSummarySchema = z.strictObject({
+    signature_resolution: member.signature_resolution,
+    nesting_read: member.nesting_read,
+    artifact: member.artifact,
+    module: member.module,
+    metadata: member.metadata,
+    identity_scope: member.identity_scope,
+    selection: member.selection.unwrap(),
+    coverage: member.coverage,
+    user_strings: z
+        .strictObject({
+        state: member.user_strings.unwrap().unwrap().shape.state,
+        issues: member.user_strings.unwrap().unwrap().shape.issues,
+    })
+        .nullable(),
+    limitations: member.limitations,
+    reported_counts: z.strictObject({
+        types: z.number().int().nonnegative(),
+        exported_types: nullableCount,
+        fields: z.number().int().nonnegative(),
+        methods: z.number().int().nonnegative(),
+        member_refs: z.number().int().nonnegative(),
+        call_edges: z.number().int().nonnegative(),
+        field_accesses: z.number().int().nonnegative(),
+        user_strings: nullableCount,
+    }),
+});
+export const managedMembersViewContextSchema = z.strictObject({
+    signature_resolution: member.signature_resolution,
+    nesting_read: member.nesting_read,
+    identity_scope: member.identity_scope,
+    selection: member.selection.unwrap(),
+    source_metadata_status: member.metadata.shape.status,
+    source_coverage: member.coverage,
+});
+const slice = (collection, rows, { offset, limit }) => rows == null
+    ? null
+    : {
+        page: { collection, rows: rows.slice(offset, offset + limit) },
+        total: rows.length,
+    };
+/** One page of a collection, or null when the parent never examined it. */
+const collectionPage = (report, view) => {
+    const { collection } = view;
+    switch (collection) {
+        case "types":
+            return slice(collection, report.types, view);
+        case "exported_types":
+            return slice(collection, report.exported_types, view);
+        case "fields":
+            return slice(collection, report.fields, view);
+        case "methods":
+            return slice(collection, report.methods, view);
+        case "member_refs":
+            return slice(collection, report.member_refs, view);
+        case "call_edges":
+            return slice(collection, report.call_edges, view);
+        case "field_accesses":
+            return slice(collection, report.field_accesses, view);
+        case "user_strings":
+            return slice(collection, report.user_strings?.literals, view);
+    }
+};
+// A sealed parent result cannot change, so its validated report stays exact for
+// every later page. The weak reference lets memory pressure reclaim the copy;
+// unsealed input is validated on each call.
+const validatedReports = new WeakMap();
+/** Validate the parent once per sealed result instead of once per page. */
+const parseMemberReport = (parent) => {
+    const { normalizedResult } = parent;
+    const sealed = parent.sealedResult === true &&
+        typeof normalizedResult === "object" &&
+        normalizedResult !== null;
+    const cached = sealed
+        ? validatedReports.get(normalizedResult)?.deref()
+        : undefined;
+    if (cached !== undefined)
+        return ok(cached);
+    const parsed = parseAnalysisViewResult(managedMemberInspectionSchema, parent);
+    if (parsed.ok && sealed)
+        validatedReports.set(normalizedResult, new WeakRef(parsed.value));
+    return parsed;
+};
+/** Everything but the member collections, which are replaced by their counts. */
+const summarizeMembers = (report) => {
+    const { types, exported_types, fields, methods, member_refs, call_edges, field_accesses, user_strings, ...identity } = report;
+    return {
+        ...identity,
+        user_strings: user_strings === null
+            ? null
+            : { state: user_strings.state, issues: user_strings.issues },
+        reported_counts: {
+            types: types.length,
+            exported_types: exported_types?.length ?? null,
+            fields: fields.length,
+            methods: methods.length,
+            member_refs: member_refs.length,
+            call_edges: call_edges.length,
+            field_accesses: field_accesses.length,
+            user_strings: user_strings?.literals.length ?? null,
+        },
+    };
+};
+/** Project authenticated member Evidence without reading a path or invoking a provider. */
+export const projectManagedMemberView = (parent, view) => {
+    if (view.kind !== "summary" && view.kind !== "managed-members")
+        return err(analysisViewInputError([
+            {
+                path: ["view"],
+                reason: "invalid_value",
+                message: "Managed member inspection supports summary and managed-members views.",
+            },
+        ]));
+    const parsed = parseMemberReport(parent);
+    if (!parsed.ok)
+        return parsed;
+    const report = parsed.value;
+    const shared = {
+        parent_evidence_id: parent.evidenceId,
+        parent_operation: "inspect_managed_members",
+        parent_digest: parent.evidenceId.slice(3),
+        artifact: { path: report.artifact.path, sha256: report.artifact.sha256 },
+        limitations: uniqueSorted([...parent.limitations, ...report.limitations]),
+        unknowns: [
+            "Collection counts and pages cover producer-returned rows; member completeness remains the original coverage, not an absence claim about unreturned rows.",
+            ...(report.selection === null
+                ? []
+                : [
+                    "Exported types and member references cover the whole assembly; the other collections cover only the selected declaring types.",
+                ]),
+            ...managedViewIdentityUnknowns(parent, report.identity_scope.requires_mvid),
+        ],
+    };
+    if (view.kind === "summary") {
+        const summary = summarizeMembers(report);
+        const total = Object.values(summary.reported_counts).reduce((sum, count) => sum + (count ?? 0), 0);
+        return ok({
+            kind: "summary",
+            view,
+            ...shared,
+            summary,
+            coverage: completeWithinViewCoverage(total, total),
+        });
+    }
+    const selected = collectionPage(report, view);
+    if (selected === null)
+        return err(analysisViewInputError([
+            {
+                path: ["view", "collection"],
+                reason: "invalid_value",
+                message: `The parent Evidence did not examine ${view.collection}; repeat inspect_managed_members with the current runtime to record it.`,
+            },
+        ]));
+    const { page, total } = selected;
+    return ok({
+        kind: "managed-members",
+        view,
+        page,
+        ...shared,
+        signature_resolution: report.signature_resolution,
+        nesting_read: report.nesting_read,
+        identity_scope: report.identity_scope,
+        selection: report.selection,
+        source_metadata_status: report.metadata.status,
+        source_coverage: view.collection === "user_strings" && report.user_strings !== null
+            ? {
+                state: report.user_strings.state,
+                issues: report.user_strings.issues,
+            }
+            : report.coverage,
+        coverage: pageViewCoverage(view.offset, page.rows.length, total),
+    });
+};

package/dist/domain/analysisView/nativeFunctionView.js

@@ -1,7 +1,8 @@
+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 { analysisViewInputError, } from "./analysisView.js";
 import { completeWithinViewCoverage, pageViewCoverage, } from "./analysisViewCoverage.js";
 const viewError = (message) => analysisViewInputError([
     { path: ["view"], reason: "invalid_value", message },
@@ -35,28 +36,6 @@ const parentFields = (parent, dossier, artifact) => {
         unknowns: uniqueSorted(unknowns),
     };
 };
-const pseudocodePage = (body, offset, limit) => {
-    const start = Math.min(offset, body.length);
-    const high = (n) => n >= 0xd800 && n <= 0xdbff;
-    const low = (n) => n >= 0xdc00 && n <= 0xdfff;
-    if (start > 0 &&
-        start < body.length &&
-        high(body.charCodeAt(start - 1)) &&
-        low(body.charCodeAt(start)))
-        return err(viewError("Pseudocode offset splits a UTF-16 surrogate pair."));
-    let end = Math.min(start + limit, body.length);
-    if (end > start &&
-        end < body.length &&
-        high(body.charCodeAt(end - 1)) &&
-        low(body.charCodeAt(end)))
-        end--;
-    if (end === start && start < body.length)
-        return err(viewError("Increase pseudocode limit to include the next complete Unicode character."));
-    return ok({
-        item: { text: body.slice(start, end), unit: "utf16-code-units" },
-        coverage: pageViewCoverage(start, end - start, body.length),
-    });
-};
 const nativeRows = (dossier, facet) => {
     const sourceFlow = dossier.native_value_flow;
     const flow = sourceFlow?.available ? sourceFlow : undefined;
@@ -71,6 +50,8 @@ const nativeRows = (dossier, facet) => {
         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,
@@ -92,6 +73,17 @@ export const projectNativeFunctionView = (parent, dossier, view) => {
             },
         ]));
     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,
@@ -99,6 +91,8 @@ export const projectNativeFunctionView = (parent, dossier, view) => {
         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" ||
@@ -129,7 +123,7 @@ export const projectNativeFunctionView = (parent, dossier, view) => {
         return ok(singleton(status));
     }
     if (view.facet === "pseudocode") {
-        const page = pseudocodePage(dossier.pseudocode, view.offset, view.limit);
+        const page = analysisTextPage(dossier.pseudocode, view.offset, view.limit);
         return page.ok
             ? ok({ kind: "native", view, ...page.value, ...common })
             : page;
@@ -139,7 +133,8 @@ export const projectNativeFunctionView = (parent, dossier, view) => {
         return ok(singleton({
             available: false,
             // Only value-flow facets inherit the value-flow failure reason; an
-            // older dossier simply has no unresolved_calls record.
+            // 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",