rea-agents 2.1.0 → 2.2.0

package/dist/domain/appleApplication.js

@@ -0,0 +1,221 @@
+import { createHash } from "node:crypto";
+import canonicalize from "canonicalize";
+import { z } from "zod";
+import { parseArtifactInventoryEvidence } from "./artifactInventoryEvidence.js";
+import { projectBoundedCartesian } from "./boundedCartesianProjection.js";
+import { evidenceSchema } from "./evidence.js";
+const digestSchema = z.string().regex(/^[a-f0-9]{64}$/u);
+const evidenceIdSchema = z.string().regex(/^ev_[a-f0-9]{64}$/u);
+const boundedPathSchema = z.string().min(1).max(4_096);
+const componentSchema = z.strictObject({
+    path: boundedPathSchema,
+    artifact_id: z.string().regex(/^art_[a-f0-9]{64}$/u),
+    sha256: digestSchema,
+    format: z.string().min(1).max(100),
+});
+/** Authenticated artifact inventory pages projected as one Apple application. */
+export const appleApplicationProjectionInputSchema = z.strictObject({
+    inventory_evidence: z.array(evidenceSchema).min(1).max(100),
+    limits: z
+        .strictObject({
+        max_components: z.number().int().min(1).max(10_000).default(1_000),
+    })
+        .default({ max_components: 1_000 }),
+});
+/** Deterministic, execution-free Apple application inventory projection. */
+export const appleApplicationProjectionResultSchema = z.strictObject({
+    schema_version: z.literal(1),
+    projection_id: z.string().regex(/^aap_[a-f0-9]{64}$/u),
+    root_sha256: digestSchema,
+    root_format: z.literal("ipa"),
+    source_evidence_ids: z.array(evidenceIdSchema).min(1).max(100),
+    application_roots: z.array(boundedPathSchema),
+    components: z.strictObject({
+        bundle_metadata: z.array(componentSchema),
+        executables: z.array(componentSchema),
+        frameworks: z.array(componentSchema),
+        native_libraries: z.array(componentSchema),
+        javascript: z.array(componentSchema),
+        signing: z.array(componentSchema),
+    }),
+    runtime_families: z.array(z.enum([
+        "native",
+        "swift-objective-c",
+        "javascript",
+        "react-native",
+        "flutter",
+        "unity",
+    ])),
+    bridge_candidates: z.array(z.strictObject({
+        source_path: boundedPathSchema,
+        native_path: boundedPathSchema,
+        basis: z.enum([
+            "javascript-and-native-content",
+            "react-native-convention",
+            "flutter-convention",
+            "unity-convention",
+        ]),
+    })),
+    coverage: z.strictObject({
+        status: z.enum(["complete-within-inventory", "partial", "truncated"]),
+        inventory_complete: z.boolean(),
+        omitted_components: z.number().int().min(0),
+        omitted_bridge_candidates: z.number().int().min(0),
+    }),
+    limitations: z.array(z.string().min(1).max(4_096)).max(100),
+});
+/** Project exact IPA paths and hashes without parsing or executing target code. */
+export const projectAppleApplication = (input) => {
+    const parsed = appleApplicationProjectionInputSchema.parse(input);
+    const { evidence, inventory } = parseArtifactInventoryEvidence(parsed.inventory_evidence);
+    if (inventory.manifest.root_format !== "ipa")
+        throw new TypeError("Apple application projection requires IPA Evidence");
+    const nodes = new Map(inventory.nodes.map((node) => [node.artifact_id, node]));
+    const all = inventory.occurrences
+        .filter((occurrence) => occurrence.artifact_id !== null && occurrence.logical_path !== ".")
+        .map((occurrence) => {
+        const node = nodes.get(occurrence.artifact_id ?? "");
+        if (node === undefined)
+            throw new TypeError("Apple application occurrence has no artifact node");
+        return {
+            path: occurrence.logical_path,
+            artifact_id: node.artifact_id,
+            sha256: node.sha256,
+            format: node.format,
+        };
+    });
+    const roots = [
+        ...new Set(inventory.occurrences.flatMap(({ logical_path: path }) => {
+            const match = /^(Payload\/[^/]+\.app)(?:\/|$)/u.exec(path);
+            return match?.[1] === undefined ? [] : [match[1]];
+        })),
+    ].sort(compare);
+    const classified = classifyComponents(all, roots);
+    const retained = retainComponents(classified, parsed.limits.max_components);
+    const omitted = componentCount(classified) - componentCount(retained);
+    const runtimeFamilies = identifyRuntimeFamilies(all);
+    const bridgeProjection = identifyBridgeCandidates(retained.javascript, deduplicateComponents([
+        ...retained.executables,
+        ...retained.native_libraries,
+    ]), parsed.limits.max_components);
+    const limitations = projectionLimitations(inventory.complete, omitted, bridgeProjection.omitted, roots);
+    const withoutId = {
+        schema_version: 1,
+        root_sha256: inventory.manifest.root_sha256,
+        root_format: "ipa",
+        source_evidence_ids: evidence
+            .map(({ evidence_id: id }) => id)
+            .sort(compare),
+        application_roots: roots,
+        components: retained,
+        runtime_families: runtimeFamilies,
+        bridge_candidates: bridgeProjection.candidates,
+        coverage: {
+            status: omitted > 0 || bridgeProjection.omitted > 0
+                ? "truncated"
+                : inventory.complete
+                    ? "complete-within-inventory"
+                    : "partial",
+            inventory_complete: inventory.complete,
+            omitted_components: omitted,
+            omitted_bridge_candidates: bridgeProjection.omitted,
+        },
+        limitations,
+    };
+    return appleApplicationProjectionResultSchema.parse({
+        ...withoutId,
+        projection_id: `aap_${digest(withoutId)}`,
+    });
+};
+const classifyComponents = (all, roots) => {
+    const withinApp = (path) => roots.some((root) => path.startsWith(`${root}/`));
+    return {
+        bundle_metadata: all.filter(({ path }) => /(?:^|\/)Info\.plist$/u.test(path)),
+        executables: all.filter(({ path, format }) => withinApp(path) && ["mach-o", "mach-o-universal"].includes(format)),
+        frameworks: all.filter(({ path }) => /\.framework\//u.test(path)),
+        native_libraries: all.filter(({ path }) => /\.(?:dylib|so)$/iu.test(path)),
+        javascript: all.filter(({ format }) => format === "javascript-bundle"),
+        signing: all.filter(({ path }) => /(?:^|\/)(?:embedded\.mobileprovision|_CodeSignature\/CodeResources)$/u.test(path)),
+    };
+};
+const retainComponents = (groups, maximum) => {
+    let remaining = maximum;
+    return Object.fromEntries(Object.entries(groups).map(([key, values]) => {
+        const retained = [...values]
+            .sort((left, right) => compare(left.path, right.path))
+            .slice(0, remaining);
+        remaining -= retained.length;
+        return [key, retained];
+    }));
+};
+const componentCount = (groups) => Object.values(groups).reduce((total, values) => total + values.length, 0);
+const deduplicateComponents = (values) => [...new Map(values.map((value) => [value.path, value])).values()].sort((left, right) => compare(left.path, right.path));
+const identifyRuntimeFamilies = (all) => {
+    const paths = all.map(({ path }) => path.toLowerCase());
+    const families = new Set();
+    if (all.some(({ format }) => ["mach-o", "mach-o-universal"].includes(format)))
+        families.add("native");
+    if (paths.some((path) => /\.(?:dylib|framework\/[^/]+)$/u.test(path)))
+        families.add("swift-objective-c");
+    if (all.some(({ format }) => format === "javascript-bundle"))
+        families.add("javascript");
+    if (paths.some((path) => path.includes("reactnative") ||
+        path.includes("react.framework") ||
+        path.includes("hermes")))
+        families.add("react-native");
+    if (paths.some((path) => path.includes("flutter.framework") || path.includes("app.framework")))
+        families.add("flutter");
+    if (paths.some((path) => path.includes("unityframework.framework")))
+        families.add("unity");
+    return [...families].sort(compare);
+};
+const identifyBridgeCandidates = (scripts, native, maximum) => {
+    const projection = projectBoundedCartesian(scripts, native, maximum, (script, item) => ({
+        source_path: script.path,
+        native_path: item.path,
+        basis: bridgeBasis(item.path),
+    }));
+    return {
+        candidates: projection.values,
+        omitted: projection.omitted,
+    };
+};
+const bridgeBasis = (path) => {
+    const lower = path.toLowerCase();
+    if (lower.includes("react"))
+        return "react-native-convention";
+    if (lower.includes("flutter") || lower.includes("app.framework"))
+        return "flutter-convention";
+    if (lower.includes("unity"))
+        return "unity-convention";
+    return "javascript-and-native-content";
+};
+const projectionLimitations = (complete, omitted, omittedBridges, roots) => [
+    ...(!complete
+        ? ["Source inventory pages are incomplete; absence is unknown."]
+        : []),
+    ...(omitted > 0
+        ? [
+            `${String(omitted)} component observations were omitted by the projection limit.`,
+        ]
+        : []),
+    ...(omittedBridges > 0
+        ? [
+            `${String(omittedBridges)} bridge hypotheses were omitted by the projection limit.`,
+        ]
+        : []),
+    ...(roots.length === 0
+        ? [
+            "No Payload/*.app directory was present in the supplied inventory pages.",
+        ]
+        : []),
+    "Bundle identifiers and signing claims require dedicated plist and CMS parsing; this projection reports only exact paths and hashes.",
+    "Bridge candidates are path-based hypotheses, not observed runtime calls.",
+];
+const compare = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+const digest = (value) => {
+    const encoded = canonicalize(value);
+    if (encoded === undefined)
+        throw new TypeError("Apple application projection is not canonical JSON");
+    return createHash("sha256").update(encoded).digest("hex");
+};

package/dist/domain/boundedCartesianProjection.js

@@ -0,0 +1,15 @@
+/** Project a Cartesian product without materializing values beyond the output limit. */
+export const projectBoundedCartesian = (left, right, maximum, project) => {
+    const values = [];
+    for (const leftValue of left) {
+        for (const rightValue of right) {
+            if (values.length === maximum)
+                return {
+                    values,
+                    omitted: left.length * right.length - values.length,
+                };
+            values.push(project(leftValue, rightValue));
+        }
+    }
+    return { values, omitted: 0 };
+};

package/dist/domain/processComparison.js

@@ -94,6 +94,25 @@ const filesystemObservations = (capture) => [
         effects: capture.filesystem_effects,
     },
 ];
+/** Canonical observations for one process-comparison dimension. */
+export const processDimensionObservations = (capture, dimension) => {
+    switch (dimension) {
+        case "terminal":
+            return terminalObservations(capture);
+        case "interaction":
+            return capture.interaction_events;
+        case "exit":
+            return [{ ...capture.exit, settlement: capture.settlement }];
+        case "filesystem":
+            return filesystemObservations(capture);
+        case "protocol":
+            return capture.protocol_events;
+        case "process":
+            return capture.process_samples;
+        case "shim":
+            return capture.shim_events;
+    }
+};
 const classifyCollection = (left, right) => {
     if (JSON.stringify(left) === JSON.stringify(right))
         return "unchanged";

package/dist/domain/processPairedExperiment.js

@@ -0,0 +1,128 @@
+import { z } from "zod";
+import { PROCESS_COMPARISON_DIMENSIONS, compareProcessCaptures, processDimensionObservations, } from "./processComparison.js";
+import { digestProcessCommitment, processScenarioSchema, } from "./processScenario.js";
+const sideIdentifierSchema = z
+    .string()
+    .regex(/^[A-Za-z][A-Za-z0-9._-]{0,127}$/u);
+const environmentNameSchema = z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/u);
+const processDimensionSchema = z.enum(PROCESS_COMPARISON_DIMENSIONS);
+const sideBindingSchema = z
+    .object({
+    id: sideIdentifierSchema,
+    executable: z.string().startsWith("/"),
+    arguments: z.array(z.string()).max(256).optional(),
+    environment: z.record(environmentNameSchema, z.string()).default({}),
+})
+    .strict();
+/** Boundary contract for one bounded authority/candidate process experiment. */
+export const processPairedExperimentSchema = z
+    .object({
+    approved: z.literal(true),
+    shared_scenario: processScenarioSchema,
+    authority: sideBindingSchema,
+    candidate: sideBindingSchema,
+    repeat_count: z.number().int().min(2).max(10).default(3),
+    freshness_policy: z
+        .object({
+        max_capture_age_ms: z.number().int().positive().max(86_400_000),
+    })
+        .strict(),
+    required_dimensions: z
+        .array(processDimensionSchema)
+        .min(1)
+        .max(PROCESS_COMPARISON_DIMENSIONS.length)
+        .default([...PROCESS_COMPARISON_DIMENSIONS]),
+})
+    .strict()
+    .superRefine((experiment, context) => {
+    if (experiment.authority.id === experiment.candidate.id)
+        context.addIssue({
+            code: "custom",
+            message: "authority and candidate identities must differ",
+            path: ["candidate", "id"],
+        });
+    if (new Set(experiment.required_dimensions).size !==
+        experiment.required_dimensions.length)
+        context.addIssue({
+            code: "custom",
+            message: "required process dimensions must be unique",
+            path: ["required_dimensions"],
+        });
+});
+/** Apply a side binding without changing the shared observation contract. */
+export const bindProcessScenario = (shared, side) => processScenarioSchema.parse({
+    ...shared,
+    executable: side.executable,
+    arguments: side.arguments ?? shared.arguments,
+    environment: { ...shared.environment, ...side.environment },
+});
+const classifyInstability = (dimensions) => {
+    if (dimensions.has("exit"))
+        return "flaky_exit";
+    if (dimensions.has("filesystem") || dimensions.has("process"))
+        return "environmental_drift";
+    return "nondeterministic_output";
+};
+const timingKeys = new Set([
+    "at_ms",
+    "scheduled_at_ms",
+    "dispatched_at_ms",
+    "elapsed_ms",
+]);
+const withoutTiming = (value) => typeof value !== "object" || value === null || Array.isArray(value)
+    ? value
+    : Object.fromEntries(Object.entries(value).filter(([key]) => !timingKeys.has(key)));
+const observationsWithoutTiming = (capture, dimension) => dimension === "exit"
+    ? [
+        {
+            ...capture.exit,
+            settlement: {
+                state: capture.settlement.state,
+                cleanup_outcome: capture.settlement.cleanup_outcome,
+            },
+        },
+    ]
+    : processDimensionObservations(capture, dimension).map(withoutTiming);
+const hasOnlyTimingVariance = (captures, dimensions) => dimensions.every((dimension) => {
+    const first = captures[0];
+    if (first === undefined)
+        return false;
+    const baseline = JSON.stringify(observationsWithoutTiming(first, dimension));
+    return captures
+        .slice(1)
+        .every((capture) => JSON.stringify(observationsWithoutTiming(capture, dimension)) ===
+        baseline);
+});
+/** Compare same-side repeats before permitting a cross-side claim. */
+export const analyzeProcessRepeatability = (captures, requiredDimensions) => {
+    if (captures.length < 2)
+        return {
+            classification: "insufficient_samples",
+            stable: false,
+            digest: digestProcessCommitment({ captures: [], requiredDimensions }),
+            comparisons: [],
+            unstable_dimensions: [],
+        };
+    const baseline = captures[0];
+    if (baseline === undefined)
+        throw new TypeError("Repeatability analysis lost its baseline capture");
+    const comparisons = captures
+        .slice(1)
+        .map((capture) => compareProcessCaptures(baseline, capture));
+    const unstable = new Set(requiredDimensions.filter((dimension) => comparisons.some((comparison) => comparison[dimension] !== "unchanged")));
+    const unstableDimensions = PROCESS_COMPARISON_DIMENSIONS.filter((dimension) => unstable.has(dimension));
+    return {
+        classification: unstable.size === 0
+            ? "stable"
+            : hasOnlyTimingVariance(captures, unstableDimensions)
+                ? "timing_variance"
+                : classifyInstability(unstable),
+        stable: unstable.size === 0,
+        digest: digestProcessCommitment({
+            requiredDimensions,
+            comparisons,
+        }),
+        comparisons,
+        unstable_dimensions: unstableDimensions,
+    };
+};