rea-agents 0.3.0 → 0.4.0

package/dist/domain/errors.js

@@ -8,9 +8,124 @@ export class HopperError extends AnalysisError {
 export class AnalysisProtocolError extends AnalysisError {
     _tag = "AnalysisProtocolError";
 }
-/** An evidence bundle or bounded session ledger rejected caller-controlled data. */
-export class EvidenceLedgerError extends AnalysisError {
-    _tag = "EvidenceLedgerError";
+/** Caller input failed provider-neutral application parsing. */
+export class AnalysisInputError extends AnalysisError {
+    operation;
+    _tag = "AnalysisInputError";
+    constructor(operation, options) {
+        super(`Invalid analysis input for ${operation}`, options);
+        this.operation = operation;
+    }
+}
+/** Provider output failed provider-neutral application parsing. */
+export class AnalysisOutputError extends AnalysisError {
+    operation;
+    reason;
+    _tag = "AnalysisOutputError";
+    constructor(operation, reason, options) {
+        super(`Invalid analysis output for ${operation}: ${reason}`, options);
+        this.operation = operation;
+        this.reason = reason;
+    }
+}
+/** Selected provider cannot execute a declared analysis operation. */
+export class AnalysisCapabilityUnavailableError extends AnalysisError {
+    providerId;
+    operation;
+    reason;
+    _tag = "AnalysisCapabilityUnavailableError";
+    constructor(providerId, operation, reason) {
+        super(`Provider ${providerId} cannot execute ${operation}: ${reason}`);
+        this.providerId = providerId;
+        this.operation = operation;
+        this.reason = reason;
+    }
+}
+/** Caller cancellation won before provider-neutral work completed. */
+export class AnalysisCancelledError extends AnalysisError {
+    operation;
+    _tag = "AnalysisCancelledError";
+    constructor(operation) {
+        super(`Analysis operation was cancelled: ${operation}`);
+        this.operation = operation;
+    }
+}
+/** Provider-neutral operation exceeded its declared execution deadline. */
+export class AnalysisTimeoutError extends AnalysisError {
+    operation;
+    timeoutMs;
+    _tag = "AnalysisTimeoutError";
+    constructor(operation, timeoutMs) {
+        super(`Analysis operation timed out after ${String(timeoutMs)}ms: ${operation}`);
+        this.operation = operation;
+        this.timeoutMs = timeoutMs;
+    }
+}
+/** No configured provider can satisfy a requested operation. */
+export class ProviderSelectionError extends AnalysisError {
+    operation;
+    _tag = "ProviderSelectionError";
+    constructor(operation) {
+        super(`No configured provider can execute ${operation}`);
+        this.operation = operation;
+    }
+}
+/** A provider adapter failed outside its more precise typed variants. */
+export class ProviderAdapterError extends AnalysisError {
+    providerId;
+    operation;
+    _tag = "ProviderAdapterError";
+    constructor(providerId, operation, options) {
+        super(`Provider ${providerId} adapter failed during ${operation}`, options);
+        this.providerId = providerId;
+        this.operation = operation;
+    }
+}
+/** Artifact inventory or extraction failed a typed safety boundary. */
+export class ArtifactOperationError extends AnalysisError {
+    operation;
+    reason;
+    _tag = "ArtifactOperationError";
+    constructor(operation, reason) {
+        super(`Artifact ${operation} failed: ${reason}`);
+        this.operation = operation;
+        this.reason = reason;
+    }
+}
+/** Evidence identity, schema, or bundle manifests failed integrity checks. */
+export class EvidenceIntegrityError extends AnalysisError {
+    _tag = "EvidenceIntegrityError";
+}
+/** A bounded evidence ledger cannot accept more records or serialized bytes. */
+export class EvidenceLimitError extends AnalysisError {
+    limit;
+    maximum;
+    _tag = "EvidenceLimitError";
+    constructor(limit, maximum) {
+        super(`Evidence ledger ${limit} limit exceeded (${String(maximum)})`);
+        this.limit = limit;
+        this.maximum = maximum;
+    }
+}
+/** Evidence bundle filesystem access failed within the configured policy. */
+export class EvidenceFileError extends AnalysisError {
+    operation;
+    reason;
+    _tag = "EvidenceFileError";
+    constructor(operation, reason, options) {
+        super(`Evidence bundle ${operation} failed: ${reason}`, options);
+        this.operation = operation;
+        this.reason = reason;
+    }
+}
+/** Residual-unknown mutation failed a lifecycle, reference, or CAS invariant. */
+export class UnknownRegistryError extends AnalysisError {
+    reason;
+    _tag = "UnknownRegistryError";
+    constructor(reason, options) {
+        super(`Residual unknown registry mutation failed: ${reason}`, options);
+        this.reason = reason;
+    }
 }
 /** Hopper did not respond within the configured operation deadline. */
 export class HopperTimeoutError extends HopperError {
@@ -75,7 +190,80 @@ export class BinaryTargetError extends AnalysisError {
     path;
     _tag = "BinaryTargetError";
     constructor(path, reason, options) {
-        super(`Cannot open app: ${reason}: ${path}`, options);
+        super(`Cannot open artifact: ${reason}`, options);
         this.path = path;
     }
 }
+/** Project expected failures into exhaustive, secret-safe caller fields. */
+export const projectAnalysisError = (error) => {
+    assertKnownTag(error._tag);
+    return {
+        tag: error._tag,
+        message: error.message,
+        details: safeDetails(error),
+    };
+};
+const safeDetails = (error) => {
+    if (error instanceof AnalysisInputError)
+        return { operation: error.operation };
+    if (error instanceof AnalysisOutputError)
+        return { operation: error.operation, reason: error.reason };
+    if (error instanceof AnalysisCapabilityUnavailableError)
+        return {
+            providerId: error.providerId,
+            operation: error.operation,
+            reason: error.reason,
+        };
+    if (error instanceof AnalysisCancelledError)
+        return { operation: error.operation };
+    if (error instanceof AnalysisTimeoutError)
+        return { operation: error.operation, timeoutMs: error.timeoutMs };
+    if (error instanceof ProviderSelectionError)
+        return { operation: error.operation };
+    if (error instanceof ProviderAdapterError)
+        return { providerId: error.providerId, operation: error.operation };
+    if (error instanceof ArtifactOperationError)
+        return { operation: error.operation, reason: error.reason };
+    if (error instanceof EvidenceLimitError)
+        return { limit: error.limit, maximum: error.maximum };
+    if (error instanceof EvidenceFileError)
+        return { operation: error.operation, reason: error.reason };
+    if (error instanceof UnknownRegistryError)
+        return { reason: error.reason };
+    if (error instanceof HopperTimeoutError)
+        return { timeoutMs: error.timeoutMs };
+    if (error instanceof HopperRemoteError)
+        return { code: error.code, safeMessage: error.safeMessage };
+    if (error instanceof HopperProcessError)
+        return { exitCode: error.exitCode };
+    return {};
+};
+const KNOWN_ERROR_TAGS = {
+    AnalysisProtocolError: true,
+    AnalysisInputError: true,
+    AnalysisOutputError: true,
+    AnalysisCapabilityUnavailableError: true,
+    AnalysisCancelledError: true,
+    AnalysisTimeoutError: true,
+    ProviderSelectionError: true,
+    ProviderAdapterError: true,
+    ArtifactOperationError: true,
+    ProcessCaptureError: true,
+    EvidenceIntegrityError: true,
+    EvidenceLimitError: true,
+    EvidenceFileError: true,
+    UnknownRegistryError: true,
+    HopperTimeoutError: true,
+    HopperCancelledError: true,
+    HopperProtocolError: true,
+    HopperRemoteError: true,
+    HopperProcessError: true,
+    HopperStartError: true,
+    ConfigurationError: true,
+    NoBinaryOpenError: true,
+    BinaryTargetError: true,
+};
+const assertKnownTag = (tag) => {
+    if (KNOWN_ERROR_TAGS[tag] !== true)
+        throw new TypeError("Unknown analysis error tag");
+};

package/dist/domain/evidence.js

@@ -11,11 +11,32 @@ const providerSchema = z.object({
 const subjectSchema = z.object({
     name: z.string().min(1),
     digest: z.object({ sha256: digestSchema }),
-    format: z.enum(["hopper", "mach-o", "elf", "pe"]),
+    format: z.enum([
+        "hopper",
+        "mach-o",
+        "elf",
+        "pe",
+        "zip",
+        "ipa",
+        "apk",
+        "asar",
+        "dmg",
+        "pkg",
+        "plist",
+        "javascript",
+        "source-map",
+        "directory",
+        "file",
+        "unknown",
+        "mach-o-universal",
+        "javascript-bundle",
+        "entitlements",
+    ]),
     architecture: z.enum(["x86", "x86_64", "arm", "arm64"]).nullable(),
     local_path: z.string(),
 });
-const locationSchema = z.discriminatedUnion("kind", [
+/** Source location attached to an evidence observation. */
+const evidenceLocationSchema = z.discriminatedUnion("kind", [
     z.object({ kind: z.literal("address"), address: z.string().min(1) }),
     z.object({
         kind: z.literal("address-range"),
@@ -23,6 +44,12 @@ const locationSchema = z.discriminatedUnion("kind", [
         end: z.string().min(1),
     }),
     z.object({ kind: z.literal("artifact-path"), path: z.string().min(1) }),
+    z.object({ kind: z.literal("file-offset"), offset: z.number().int().min(0) }),
+    z.object({
+        kind: z.literal("file-offset-range"),
+        start: z.number().int().min(0),
+        end: z.number().int().min(0),
+    }),
 ]);
 const evidenceAuthoritySchema = z.enum([
     "shipped-artifact",
@@ -46,13 +73,13 @@ export const evidenceSchema = z.object({
     predicate_type: z.string().min(1),
     operation: z.string().min(1),
     parameters: z.record(z.string(), jsonValueSchema),
-    result: jsonValueSchema,
-    raw_payload_sha256: digestSchema.nullable(),
+    raw_result: jsonValueSchema.nullable(),
+    normalized_result: jsonValueSchema,
     confidence: z.enum(["observed", "derived", "inferred"]),
     authority: evidenceAuthoritySchema,
     environment: executionEnvironmentSchema.nullable(),
     limitations: z.array(z.string()),
-    locations: z.array(locationSchema),
+    locations: z.array(evidenceLocationSchema),
     evidence_links: z.array(z.string().regex(/^ev_[a-f0-9]{64}$/u)),
 });
 const sha256 = (value) => createHash("sha256").update(value).digest("hex");
@@ -76,7 +103,8 @@ const semanticProjection = (evidence) => ({
     predicate_type: evidence.predicate_type,
     operation: evidence.operation,
     parameters: evidence.parameters,
-    result: evidence.result,
+    raw_result: evidence.raw_result,
+    normalized_result: evidence.normalized_result,
     confidence: evidence.confidence,
     authority: evidence.authority,
     environment: evidence.environment,
@@ -88,6 +116,11 @@ const semanticProjection = (evidence) => ({
 const computeEvidenceId = (evidence) => `ev_${sha256(canonicalJson(semanticProjection(evidence)))}`;
 /** Parse evidence and reject a syntactically valid but tampered semantic ID. */
 export const parseEvidence = (input) => {
+    if (typeof input === "object" &&
+        input !== null &&
+        "schema_version" in input &&
+        input.schema_version !== 2)
+        throw new TypeError(`Unsupported evidence schema_version ${String(input.schema_version)}; Evidence v1 is not accepted. Produce Evidence v2.`);
     const evidence = evidenceSchema.parse(input);
     const { evidence_id: evidenceId, ...withoutId } = evidence;
     if (computeEvidenceId(withoutId) !== evidenceId)
@@ -122,7 +155,8 @@ export const createEvidence = (target, provider, observation) => {
         predicate_type: observation.predicateType ?? "rea.analysis/v2",
         operation: observation.operation,
         parameters: observation.parameters,
-        result: observation.result,
+        raw_result: observation.rawResult ?? null,
+        normalized_result: observation.result,
         confidence: observation.confidence ?? "observed",
         authority: observation.authority ?? "shipped-artifact",
         environment: observation.environment ?? null,
@@ -139,8 +173,5 @@ export const createEvidence = (target, provider, observation) => {
         ...semantic,
         evidence_id: `ev_${sha256(canonicalJson(semantic))}`,
         subject,
-        raw_payload_sha256: observation.redactedRawPayload === undefined
-            ? null
-            : sha256(canonicalJson(observation.redactedRawPayload)),
     });
 };

package/dist/domain/evidenceBundle.js

@@ -1,11 +1,192 @@
 import { z } from "zod";
-import { evidenceSchema } from "./evidence.js";
+import canonicalize from "canonicalize";
+import { evidenceSchema, parseEvidence } from "./evidence.js";
+import { residualUnknownSchema, } from "./residualUnknown.js";
+const artifactManifestSchema = evidenceSchema.shape.subject.unwrap().pick({
+    digest: true,
+    format: true,
+    architecture: true,
+});
+const providerManifestSchema = evidenceSchema.shape.provider;
+const environmentManifestSchema = evidenceSchema.shape.environment.unwrap();
+const scenarioManifestSchema = z.object({
+    evidence_id: evidenceSchema.shape.evidence_id,
+    operation: z.string().min(1),
+    authority: z.literal("controlled-replay"),
+});
+const captureManifestSchema = z.object({
+    evidence_id: evidenceSchema.shape.evidence_id,
+    predicate_type: z.string().min(1),
+});
 export const evidenceBundleSchema = z.object({
-    bundle_version: z.literal(1),
+    bundle_version: z.literal(2),
+    artifacts: z.array(artifactManifestSchema),
+    providers: z.array(providerManifestSchema),
+    environments: z.array(environmentManifestSchema),
+    scenarios: z.array(scenarioManifestSchema),
+    captures: z.array(captureManifestSchema),
+    unknowns: z.array(residualUnknownSchema),
     records: z.array(evidenceSchema),
 });
 /** Project records into a deterministic bundle whose order has no semantics. */
-export const createEvidenceBundle = (records) => ({
-    bundle_version: 1,
-    records: [...records].sort((left, right) => left.evidence_id.localeCompare(right.evidence_id)),
-});
+export const createEvidenceBundle = (records, unknowns = []) => {
+    const sortedRecords = [...records].sort((left, right) => left.evidence_id.localeCompare(right.evidence_id));
+    return {
+        bundle_version: 2,
+        artifacts: uniqueSorted(sortedRecords.flatMap(({ subject }) => subject === null
+            ? []
+            : [
+                {
+                    digest: subject.digest,
+                    format: subject.format,
+                    architecture: subject.architecture,
+                },
+            ])),
+        providers: uniqueSorted(sortedRecords.map(({ provider }) => provider)),
+        environments: uniqueSorted(sortedRecords.flatMap(({ environment }) => environment === null ? [] : [environment])),
+        scenarios: sortedRecords.flatMap((evidence) => evidence.authority === "controlled-replay"
+            ? [
+                {
+                    evidence_id: evidence.evidence_id,
+                    operation: evidence.operation,
+                    authority: evidence.authority,
+                },
+            ]
+            : []),
+        captures: sortedRecords.flatMap((evidence) => evidence.predicate_type.startsWith("rea.process-capture/")
+            ? [
+                {
+                    evidence_id: evidence.evidence_id,
+                    predicate_type: evidence.predicate_type,
+                },
+            ]
+            : []),
+        unknowns: [...unknowns].sort((left, right) => left.unknown_id.localeCompare(right.unknown_id) ||
+            left.revision - right.revision),
+        records: sortedRecords,
+    };
+};
+/** Parse records, verify semantic IDs, and reject inconsistent manifests. */
+export const parseEvidenceBundle = (input) => {
+    const parsed = evidenceBundleSchema.parse(input);
+    const recordIds = parsed.records.map(({ evidence_id: id }) => id);
+    if (new Set(recordIds).size !== recordIds.length)
+        throw new TypeError("Evidence bundle contains duplicate record IDs");
+    validateUnknownGraph(parsed.unknowns, parsed.records);
+    const canonical = createEvidenceBundle(parsed.records.map(parseEvidence), parsed.unknowns);
+    if (JSON.stringify(parsed) !== JSON.stringify(canonical))
+        throw new TypeError("Evidence bundle manifests are not canonical");
+    return canonical;
+};
+const validateUnknownGraph = (unknowns, records) => {
+    const evidenceById = new Map(records.map((record) => [record.evidence_id, record]));
+    const histories = new Map();
+    for (const unknown of unknowns) {
+        const history = histories.get(unknown.unknown_id) ?? [];
+        history.push(unknown);
+        histories.set(unknown.unknown_id, history);
+    }
+    const unknownById = new Map();
+    for (const [id, unordered] of histories) {
+        const history = [...unordered].sort((left, right) => left.revision - right.revision);
+        for (const [index, revision] of history.entries()) {
+            if (revision.revision !== index + 1)
+                throw new TypeError(`Residual unknown ${id} revision history has a gap`);
+            if (index > 0 &&
+                revision.previous_revision_digest !==
+                    history[index - 1]?.revision_digest)
+                throw new TypeError(`Residual unknown ${id} revision chain is broken`);
+        }
+        const head = history.at(-1);
+        if (head === undefined)
+            throw new TypeError("Residual unknown revision history is empty");
+        unknownById.set(id, head);
+    }
+    for (const unknown of unknowns) {
+        const referencedEvidence = [
+            ...unknown.supporting_evidence_ids,
+            ...unknown.contradicting_evidence_ids,
+            ...unknown.mutation_evidence_ids,
+            ...(unknown.resolution?.evidence_ids ?? []),
+        ];
+        for (const evidenceId of referencedEvidence)
+            if (!evidenceById.has(evidenceId))
+                throw new TypeError(`Residual unknown references missing evidence ${evidenceId}`);
+        for (const relationship of unknown.relationships)
+            if (!unknownById.has(relationship.unknown_id))
+                throw new TypeError(`Residual unknown references missing unknown ${relationship.unknown_id}`);
+        if (unknown.resolution?.disposition === "verified")
+            validateVerifiedResolution(unknown, evidenceById);
+    }
+    rejectDependencyCycles(unknownById);
+};
+const validateVerifiedResolution = (unknown, evidenceById) => {
+    if (unknown.contradicting_evidence_ids.length > 0)
+        throw new TypeError(`Residual unknown ${unknown.unknown_id} retains contradicting evidence`);
+    const qualifies = unknown.resolution?.evidence_ids.some((evidenceId) => {
+        const evidence = evidenceById.get(evidenceId);
+        return (unknown.supporting_evidence_ids.includes(evidenceId) &&
+            evidence !== undefined &&
+            evidence.predicate_type !== "rea.residual-unknown-mutation/v1" &&
+            evidenceQualifies(unknown, evidence));
+    });
+    if (qualifies !== true)
+        throw new TypeError(`Residual unknown ${unknown.unknown_id} has no qualifying resolution evidence`);
+};
+const evidenceQualifies = (unknown, evidence) => {
+    if (unknown.required_authority !== null &&
+        evidence.authority !== unknown.required_authority)
+        return false;
+    const confidenceRank = { inferred: 1, derived: 2, observed: 3 };
+    if (confidenceRank[evidence.confidence] <
+        confidenceRank[unknown.required_confidence])
+        return false;
+    const requirement = unknown.required_environment;
+    if (requirement === null)
+        return true;
+    if (evidence.environment === null)
+        return false;
+    return ((requirement.id === null || requirement.id === evidence.environment.id) &&
+        (requirement.platform === null ||
+            requirement.platform === evidence.environment.platform) &&
+        (requirement.architecture === null ||
+            requirement.architecture === evidence.environment.architecture) &&
+        (requirement.isolation === null ||
+            requirement.isolation === evidence.environment.isolation));
+};
+const rejectDependencyCycles = (unknownById) => {
+    const visited = new Set();
+    const active = new Set();
+    const visit = (id) => {
+        if (active.has(id))
+            throw new TypeError("Residual unknown dependency graph contains a cycle");
+        if (visited.has(id))
+            return;
+        active.add(id);
+        const unknown = unknownById.get(id);
+        if (unknown === undefined)
+            throw new TypeError("Residual unknown dependency graph is inconsistent");
+        for (const relationship of unknown.relationships)
+            if (relationship.type === "depends-on")
+                visit(relationship.unknown_id);
+        active.delete(id);
+        visited.add(id);
+    };
+    for (const id of unknownById.keys())
+        visit(id);
+};
+/** Encode a validated bundle as byte-stable RFC 8785 canonical JSON. */
+export const serializeEvidenceBundle = (bundle) => {
+    const serialized = canonicalize(parseEvidenceBundle(bundle));
+    if (serialized === undefined)
+        throw new TypeError("Evidence bundle canonicalization failed");
+    return serialized;
+};
+const uniqueSorted = (values) => {
+    const unique = new Map();
+    for (const value of values)
+        unique.set(JSON.stringify(value), value);
+    return [...unique.entries()]
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([, value]) => value);
+};