rea-agents 4.0.1 → 5.0.0

package/dist/application/android/AndroidAnalysisService.js

@@ -0,0 +1,37 @@
+import { parseBinaryTarget } from "../BinaryTargetResolver.js";
+import { androidRequestSchema, } from "../../domain/android/androidAnalysis.js";
+import { AnalysisCancelledError, AnalysisInputError, } from "../../domain/analysisErrorCore.js";
+import { createEvidence } from "../../domain/evidence.js";
+import { jsonObjectSchema } from "../../domain/jsonValue.js";
+import { err, ok } from "../../domain/result.js";
+/** Shared CLI/MCP admission, execution and Evidence composition for Android. */
+export class AndroidAnalysisService {
+    provider;
+    constructor(provider) {
+        this.provider = provider;
+    }
+    /** Inspect a caller-selected APK and retain producing-provider provenance inline. */
+    async execute(operation, input, options) {
+        if (options?.signal?.aborted === true)
+            return err(new AnalysisCancelledError(operation));
+        const request = androidRequestSchema.safeParse({ operation, input });
+        if (!request.success)
+            return err(new AnalysisInputError(operation, { cause: request.error }));
+        const target = await parseBinaryTarget(request.data.input.path);
+        if (!target.ok)
+            return target;
+        const executed = await this.provider.execute(target.value, request.data, options);
+        if (!executed.ok)
+            return executed;
+        const execution = executed.value;
+        return ok(createEvidence(execution.subject ?? target.value, execution.provider, {
+            operation,
+            parameters: jsonObjectSchema.parse(request.data.input),
+            result: execution.result,
+            rawResult: execution.rawResult,
+            limitations: execution.limitations,
+            locations: execution.locations,
+            confidence: operation === "inspect_android_method" ? "derived" : "observed",
+        }));
+    }
+}

package/dist/application/{AndroidApplicationService.js → android/AndroidApplicationService.js}

@@ -1,6 +1,6 @@
-import { androidApplicationProjectionInputSchema, projectAndroidApplication, } from "../domain/androidApplication.js";
-import { ANDROID_APPLICATION_PROVIDER } from "./InvestigationProviders.js";
-import { projectInventoryEvidence } from "./InventoryProjectionEvidence.js";
+import { androidApplicationProjectionInputSchema, projectAndroidApplication, } from "../../domain/android/androidApplication.js";
+import { ANDROID_APPLICATION_PROVIDER } from "../InvestigationProviders.js";
+import { projectInventoryEvidence } from "../InventoryProjectionEvidence.js";
 const OPERATION = "project_android_application_graph";
 /** Project authenticated APK inventory Evidence into Android application Evidence. */
 export const projectAndroidApplicationEvidence = (rawInput) => {

package/dist/application/{AppleApplicationService.js → apple/AppleApplicationService.js}

@@ -1,8 +1,8 @@
-import { appleApplicationProjectionInputSchema, projectAppleApplication, } from "../domain/appleApplication.js";
-import { APPLE_APPLICATION_PROVIDER } from "./InvestigationProviders.js";
-import { projectInventoryEvidence } from "./InventoryProjectionEvidence.js";
+import { appleApplicationProjectionInputSchema, projectAppleApplication, } from "../../domain/apple/appleApplication.js";
+import { APPLE_APPLICATION_PROVIDER } from "../InvestigationProviders.js";
+import { projectInventoryEvidence } from "../InventoryProjectionEvidence.js";
 const OPERATION = "project_apple_application_graph";
-/** Project authenticated IPA inventory Evidence into Apple application evidence. */
+/** Project authenticated IPA or macOS app inventory Evidence into Apple application evidence. */
 export const projectAppleApplicationEvidence = (rawInput) => {
     return projectInventoryEvidence({
         rawInput,
@@ -11,7 +11,7 @@ export const projectAppleApplicationEvidence = (rawInput) => {
         operation: OPERATION,
         predicateType: "rea.apple-application-graph",
         provider: APPLE_APPLICATION_PROVIDER,
-        subjectFormat: () => "ipa",
+        subjectFormat: (first) => first.subject?.format ?? "unknown",
         protocolError: "Apple application projection produced an invalid result",
     });
 };

package/dist/application/{AnalysisClientCleanup.js → binary/AnalysisClientCleanup.js}

@@ -1,5 +1,5 @@
-import { ProviderCleanupError } from "../domain/providerCleanupError.js";
-import { err, ok } from "../domain/result.js";
+import { ProviderCleanupError } from "../../domain/providerCleanupError.js";
+import { err, ok } from "../../domain/result.js";
 /** Close one provider client and normalize unexpected adapter rejection. */
 export const closeAnalysisClient = async (client, providerId, options = {}) => {
     try {

package/dist/application/{AnalysisProviderEvaluation.js → binary/AnalysisProviderEvaluation.js}

@@ -1,7 +1,7 @@
-import { analysisProfileSchema, } from "../domain/analysisProfile.js";
-import { AnalysisCancelledError } from "../domain/errors.js";
-import { jsonObjectSchema } from "../domain/jsonValue.js";
-import { err, ok } from "../domain/result.js";
+import { analysisProfileSchema, } from "../../domain/analysisProfile.js";
+import { AnalysisCancelledError } from "../../domain/analysisErrorCore.js";
+import { jsonObjectSchema } from "../../domain/jsonValue.js";
+import { err, ok } from "../../domain/result.js";
 import { ABORTED, waitForAbortable } from "./AbortablePromise.js";
 /** Resolve and validate one provider profile without starting its client. */
 export const evaluateAnalysisProviderCandidate = async (candidate, status, target, signal) => {
@@ -14,7 +14,8 @@ export const evaluateAnalysisProviderCandidate = async (candidate, status, targe
             return err(new AnalysisCancelledError("open_binary"));
         resolved = resolution;
     }
-    catch {
+    catch (cause) {
+        void cause;
         return ok(rejectedProfile(candidate, status, "Provider profile resolution threw"));
     }
     if (signalIsAborted(signal))
@@ -38,7 +39,8 @@ export const evaluateAnalysisProviderCandidate = async (candidate, status, targe
             return ok(rejectedProfile(candidate, status, "Resolved analysis profile has mismatched provider identity"));
         return ok({ candidate, status, profile, compatibility });
     }
-    catch {
+    catch (cause) {
+        void cause;
         return ok(rejectedProfile(candidate, status, "Provider returned an invalid analysis profile"));
     }
 };

package/dist/application/{AnalysisProviderRegistry.js → binary/AnalysisProviderRegistry.js}

@@ -1,7 +1,8 @@
-import { analysisProviderIdSchema, analysisProviderSelectorSchema, } from "../contracts/providerSelection.js";
-import { AnalysisCancelledError, ProviderSelectionError, } from "../domain/errors.js";
-import { jsonObjectSchema } from "../domain/jsonValue.js";
-import { err, ok } from "../domain/result.js";
+import { analysisProviderIdSchema, analysisProviderSelectorSchema, } from "../../contracts/providerSelection.js";
+import { AnalysisCancelledError } from "../../domain/analysisErrorCore.js";
+import { ProviderSelectionError, } from "../../domain/providerSelectionError.js";
+import { jsonObjectSchema } from "../../domain/jsonValue.js";
+import { err, ok } from "../../domain/result.js";
 import { evaluateAnalysisProviderCandidate, } from "./AnalysisProviderEvaluation.js";
 /**
  * Discover and select overlapping deep providers without starting their clients.

package/dist/application/{AnalysisSnapshotCache.js → binary/AnalysisSnapshotCache.js}

@@ -1,7 +1,9 @@
-import { EvidenceIntegrityError, NoBinaryOpenError, } from "../domain/errors.js";
-import { err, ok } from "../domain/result.js";
-import { analysisQueryId, createAnalysisSnapshotEntry, snapshotBinding, snapshotMatchesProfile, snapshotMatchesTarget, snapshotTarget, parseAnalysisSnapshot, } from "../domain/analysisSnapshot.js";
-import { GENERATED_MCP_TOOL_CATALOG } from "../generatedMcpToolCatalog.js";
+import { EvidenceIntegrityError } from "../../domain/evidenceErrors.js";
+import { NoBinaryOpenError } from "../../domain/configurationErrors.js";
+import {} from "../../domain/analysisErrorBase.js";
+import { err, ok } from "../../domain/result.js";
+import { analysisQueryId, createAnalysisSnapshotEntry, snapshotBinding, snapshotMatchesProfile, snapshotMatchesTarget, snapshotTarget, parseAnalysisSnapshot, } from "../../domain/analysisSnapshot.js";
+import { OFFICIAL_TOOL_CONTRACTS } from "../../contracts/officialToolContracts.js";
 const STATEFUL_OPERATIONS = new Set([
     "health",
     "current_address",
@@ -19,9 +21,7 @@ const CURSOR_DEFAULT_OPERATIONS = new Set([
     "prev_address",
     "xrefs",
 ]);
-const DOCUMENT_SCOPED_OPERATIONS = new Set(GENERATED_MCP_TOOL_CATALOG.filter(({ kind }) => kind === "official-proxy")
-    .map(({ name }) => name)
-    .filter((name) => name !== "current_document" &&
+const DOCUMENT_SCOPED_OPERATIONS = new Set(OFFICIAL_TOOL_CONTRACTS.map(({ name }) => name).filter((name) => name !== "current_document" &&
     name !== "list_documents" &&
     name !== "set_current_document"));
 /** Whether an operation is immutable and independent of provider UI state. */
@@ -31,6 +31,7 @@ export const isSnapshotCacheable = (operation, descriptor, parameters) => !STATE
     (!CURSOR_DEFAULT_OPERATIONS.has(operation) ||
         typeof parameters.address === "string") &&
     descriptor?.effects.mutatesArtifact === false &&
+    descriptor.cachePolicy !== "live" &&
     descriptor.effects.mayWriteFilesystem === false &&
     descriptor.effects.changesPermissions === false;
 /** Bounded in-memory cache for one immutable binary identity. */

package/dist/application/{AnalysisSnapshotFiles.js → binary/AnalysisSnapshotFiles.js}

@@ -1,7 +1,7 @@
-import { parseAnalysisSnapshot, serializeAnalysisSnapshot, } from "../domain/analysisSnapshot.js";
-import { EvidenceFileError, EvidenceIntegrityError } from "../domain/errors.js";
-import { err, ok } from "../domain/result.js";
-import { readJsonFile, writeTextFile } from "./JsonFiles.js";
+import { parseAnalysisSnapshot, serializeAnalysisSnapshot, } from "../../domain/analysisSnapshot.js";
+import { EvidenceFileError, EvidenceIntegrityError, } from "../../domain/evidenceErrors.js";
+import { err, ok } from "../../domain/result.js";
+import { readJsonFile, writeTextFile } from "../JsonFiles.js";
 /** Read and validate an analysis snapshot from the caller's path. */
 export const readAnalysisSnapshot = async (path) => {
     const loaded = await readJsonFile(path);

package/dist/application/{BinarySession.js → binary/BinarySession.js}

@@ -1,17 +1,20 @@
 import { randomUUID } from "node:crypto";
-import { analysisProfilesEqual, } from "../domain/analysisProfile.js";
-import { AnalysisCancelledError, } from "../domain/errors.js";
-import { err, ok } from "../domain/result.js";
-import { createEvidence } from "../domain/evidence.js";
-import { GENERATED_MCP_TOOL_CATALOG } from "../generatedMcpToolCatalog.js";
+import { analysisProfilesEqual, } from "../../domain/analysisProfile.js";
+import { AnalysisCancelledError } from "../../domain/analysisErrorCore.js";
+import {} from "../../domain/analysisErrorBase.js";
+import { err, ok } from "../../domain/result.js";
+import { createEvidence } from "../../domain/evidence.js";
+import { OFFICIAL_TOOL_CONTRACTS } from "../../contracts/officialToolContracts.js";
+import { ENHANCED_TOOL_CONTRACTS } from "../../contracts/enhancedToolContracts.js";
 import { SessionProviderRouter, } from "./SessionProviderRouter.js";
+import { InvestigationRecords } from "../investigation/InvestigationRecords.js";
 import { BinarySessionRecords } from "./BinarySessionRecords.js";
 import { binarySessionStatus } from "./BinarySessionStatus.js";
 import { resolveSessionOpen, } from "./BinarySessionOpen.js";
 import { bindExecutionTarget, commitExecutionProfile, prepareSessionExecution, } from "./BinarySessionExecution.js";
 import { closeAnalysisClient } from "./AnalysisClientCleanup.js";
-const OFFICIAL_OPERATIONS = new Set(GENERATED_MCP_TOOL_CATALOG.filter(({ kind }) => kind === "official-proxy").map(({ name }) => name));
-const ENHANCED_OPERATIONS = new Set(GENERATED_MCP_TOOL_CATALOG.filter(({ kind }) => kind === "enhanced").map(({ name }) => name));
+const OFFICIAL_OPERATIONS = new Set(OFFICIAL_TOOL_CONTRACTS.map(({ name }) => name));
+const ENHANCED_OPERATIONS = new Set(ENHANCED_TOOL_CONTRACTS.map(({ name }) => name));
 /**
  * Owns the single active target shared by CLI and MCP adapters.
  *
@@ -26,8 +29,8 @@ export class BinarySession extends BinarySessionRecords {
     #providerRouter;
     #runtimeUnavailability = new Map();
     #availabilityListeners = new Set();
-    constructor(providerRouter) {
-        super();
+    constructor(providerRouter, records = new InvestigationRecords()) {
+        super(records);
         this.#providerRouter = providerRouter;
     }
     /** Identify the provider producing evidence for this session. */
@@ -58,6 +61,14 @@ export class BinarySession extends BinarySessionRecords {
             ? profile.provider
             : selected);
     }
+    /** External live state cannot be replayed by a direct or composed CLI workflow. */
+    allowsSnapshotReplay(operation) {
+        const capabilities = this.#active?.route.capabilities;
+        const descriptor = capabilities?.get(operation);
+        if (descriptor !== undefined)
+            return descriptor.cachePolicy !== "live";
+        return ![...(capabilities?.values() ?? [])].some(({ cachePolicy }) => cachePolicy === "live");
+    }
     /** Return the selected immutable profile, optionally scoped to an operation. */
     analysisProfile(operation) {
         const profile = this.#active?.profile;
@@ -318,12 +329,16 @@ export class BinarySession extends BinarySessionRecords {
         for (const listener of this.#availabilityListeners) {
             try {
                 const notification = listener();
-                if (notification !== undefined)
+                if (notification !== undefined) {
+                    // best-effort cleanup: async observer notifications must not reject
+                    // unhandled; state transitions and other listeners continue.
                     void notification.catch(() => undefined);
+                }
             }
-            catch {
+            catch (cause) {
                 // External observers are best-effort notifications. Contain only the
                 // callback failure so state transitions and other listeners continue.
+                void cause;
             }
         }
     }

package/dist/application/{BinarySessionComposition.js → binary/BinarySessionComposition.js}

@@ -1,3 +1,4 @@
+import { InvestigationRecords } from "../investigation/InvestigationRecords.js";
 import { AnalysisProviderRegistry } from "./AnalysisProviderRegistry.js";
 import { BinarySession } from "./BinarySession.js";
 import { SessionProviderRouter } from "./SessionProviderRouter.js";
@@ -7,4 +8,4 @@ import { SessionProviderRouter } from "./SessionProviderRouter.js";
  */
 export const composeBinarySession = (registry, auxiliaryProviders = []) => new BinarySession(registry instanceof SessionProviderRouter
     ? registry
-    : SessionProviderRouter.selectable(registry, auxiliaryProviders));
+    : SessionProviderRouter.selectable(registry, auxiliaryProviders), new InvestigationRecords());

package/dist/application/{BinarySessionExecution.js → binary/BinarySessionExecution.js}

@@ -1,5 +1,8 @@
-import { AnalysisCapabilityUnavailableError, NoBinaryOpenError, ProviderAdapterError, } from "../domain/errors.js";
-import { err, ok } from "../domain/result.js";
+import { AnalysisCapabilityUnavailableError } from "../../domain/analysisErrorCore.js";
+import { NoBinaryOpenError } from "../../domain/configurationErrors.js";
+import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
+import {} from "../../domain/analysisErrorBase.js";
+import { err, ok } from "../../domain/result.js";
 import { isSnapshotCacheable } from "./AnalysisSnapshotCache.js";
 /** Resolve capability, profile, and snapshot state before invoking a provider. */
 export const prepareSessionExecution = (input) => {
@@ -56,9 +59,11 @@ export const bindExecutionTarget = (result, operation, target) => {
     };
     if (result.value.subject !== null &&
         result.value.subject.sha256 !== target.sha256 &&
-        !isArtifactInventorySubject(operation, result.value.subject, target))
+        !isArtifactBundleSubject(operation, result.value.subject, target))
         return err(new ProviderAdapterError(result.value.provider.id, `${operation}:subject`));
     return ok({ ...result.value, subject: result.value.subject ?? subject });
 };
-const isArtifactInventorySubject = (operation, subject, target) => (operation === "inventory_artifact" || operation === "inspect_artifact") &&
+const isArtifactBundleSubject = (operation, subject, target) => (operation === "inventory_artifact" ||
+    operation === "inspect_artifact" ||
+    operation === "extract_artifact") &&
     subject.path === (target.sourcePath ?? target.path);

package/dist/application/{BinarySessionOpen.js → binary/BinarySessionOpen.js}

@@ -1,13 +1,14 @@
-import { snapshotMatchesBinding, snapshotMatchesTarget, snapshotTarget, } from "../domain/analysisSnapshot.js";
-import { parseBinaryTarget } from "./BinaryTargetResolver.js";
-import {} from "../domain/binaryTarget.js";
-import { EvidenceIntegrityError, } from "../domain/errors.js";
-import { err } from "../domain/result.js";
+import { snapshotMatchesBinding, snapshotMatchesTarget, snapshotTarget, } from "../../domain/analysisSnapshot.js";
+import { parseBinaryTarget } from "../BinaryTargetResolver.js";
+import {} from "../../domain/binaryTarget.js";
+import { EvidenceIntegrityError } from "../../domain/evidenceErrors.js";
+import {} from "../../domain/analysisErrorBase.js";
+import { err } from "../../domain/result.js";
 import { SessionProviderRouter } from "./SessionProviderRouter.js";
 /** Parse a target, resolve its provider route, and validate snapshot binding. */
 export const resolveSessionOpen = async (input) => {
     const { router, current, path, options, stagedSnapshotMatches } = input;
-    const parsed = await parseBinaryTarget(path, process.cwd(), process.arch, options.targetKind);
+    const parsed = await parseBinaryTarget(path, process.cwd(), process.arch, options.targetKind, options.formatHint);
     if (!parsed.ok)
         return parsed;
     const target = parsed.value;

package/dist/application/{BinarySessionRecords.js → binary/BinarySessionRecords.js}

@@ -1,41 +1,46 @@
-import { createEvidence } from "../domain/evidence.js";
-import { evidenceBundleForTarget } from "../domain/evidenceBundle.js";
-import { EvidenceIntegrityError, } from "../domain/errors.js";
-import { err, ok } from "../domain/result.js";
+import { evidenceBundleForTarget } from "../../domain/evidenceBundle.js";
+import { EvidenceIntegrityError } from "../../domain/evidenceErrors.js";
+import {} from "../../domain/analysisErrorBase.js";
+import {} from "../../domain/unknownRegistryError.js";
+import { err, ok } from "../../domain/result.js";
 import { AnalysisSnapshotCache } from "./AnalysisSnapshotCache.js";
-import { EvidenceLedger } from "./EvidenceLedger.js";
-import { UNKNOWN_REGISTRY_PROVIDER, unknownEvidenceLinks, unknownMutationEvidence, } from "./UnknownEvidence.js";
-/** Owns session evidence, snapshots, and residual unknowns. */
+import { InvestigationRecords } from "../investigation/InvestigationRecords.js";
+/** Binary snapshot owner and compatibility facade for composed investigation records. */
 export class BinarySessionRecords {
-    #evidence = new EvidenceLedger();
+    #records;
     #snapshot = new AnalysisSnapshotCache();
     #snapshotInvalidated = false;
     #snapshotListeners = new Set();
+    constructor(records = new InvestigationRecords()) {
+        this.#records = records;
+    }
     /** Observe changes to the mutable current analysis snapshot resource. */
     onAnalysisSnapshotChanged(listener) {
         this.#snapshotListeners.add(listener);
         return () => this.#snapshotListeners.delete(listener);
     }
     recordEvidence(evidence) {
-        const recorded = this.#evidence.record(evidence);
+        const recorded = this.#records.recordEvidence(evidence);
         if (recorded.ok && recorded.value === "added")
             this.#emitSnapshotChanged();
         return recorded;
     }
     hasEvidence(evidenceId) {
-        return this.#evidence.has(evidenceId);
+        return this.#records.hasEvidence(evidenceId);
     }
     evidenceById(evidenceId) {
-        return this.#evidence.get(evidenceId);
+        return this.#records.evidenceById(evidenceId);
     }
     exportEvidenceBundle() {
-        return this.#evidence.export();
+        return this.#records.exportEvidenceBundle();
     }
     importEvidenceBundle(bundle) {
-        const imported = this.#evidence.import(bundle);
+        const imported = this.#records.mergeEvidenceBundle(bundle);
         if (!imported.ok)
             return imported;
-        if (imported.value.changed)
+        if (imported.value.metadataChanged)
+            this.invalidateSnapshot();
+        else if (imported.value.changed)
             this.#emitSnapshotChanged();
         return ok(imported.value.recordsAdded);
     }
@@ -48,8 +53,8 @@ export class BinarySessionRecords {
         if (target !== undefined && profile === undefined)
             return err(new EvidenceIntegrityError("Analysis snapshots require a concrete provider analysis profile"));
         return this.#snapshot.export(target, profile, target === undefined
-            ? this.#evidence.export()
-            : evidenceBundleForTarget(this.#evidence.export(), target.sha256));
+            ? this.#records.exportEvidenceBundle()
+            : evidenceBundleForTarget(this.#records.exportEvidenceBundle(), target.sha256));
     }
     importAnalysisSnapshot(snapshot) {
         const active = this.activeAnalysisBinding();
@@ -58,7 +63,7 @@ export class BinarySessionRecords {
         const imported = this.#snapshot.import(snapshot, active === undefined
             ? undefined
             : { target: active.target, profile: active.profile }, (bundle) => {
-            const imported = this.#evidence.import(bundle);
+            const imported = this.#records.mergeEvidenceBundle(bundle);
             return imported.ok ? ok(imported.value.recordsAdded) : imported;
         });
         if (imported.ok)
@@ -95,7 +100,7 @@ export class BinarySessionRecords {
         this.#emitSnapshotChanged();
     }
     clearSessionRecords() {
-        this.#evidence.clear();
+        this.#records.clear();
         this.#snapshot.clear();
         this.#snapshotInvalidated = false;
         this.#emitSnapshotChanged();
@@ -105,53 +110,42 @@ export class BinarySessionRecords {
             try {
                 const notification = listener();
                 if (notification !== undefined)
-                    void notification.catch(() => undefined);
+                    void notification.catch((cause) => {
+                        // best-effort cleanup: async observer notifications must not reject unhandled.
+                        void cause;
+                    });
             }
-            catch {
+            catch (cause) {
                 // External resource observers are best-effort; one callback must not
                 // make a committed evidence mutation appear to fail.
+                void cause;
             }
         }
     }
     recordUnknown(input) {
         const target = this.activeAnalysisBinding()?.target;
-        const recorded = this.#evidence.recordUnknown(input, unknownMutationEvidence(target, input));
+        const recorded = this.#records.recordUnknown(input, target);
         if (recorded.ok)
             this.#emitSnapshotChanged();
         return recorded;
     }
     recordEvidenceWithUnknown(evidence, input) {
-        const recorded = this.#evidence.recordWithUnknown(evidence, input, unknownMutationEvidence(undefined, input));
+        const recorded = this.#records.recordEvidenceWithUnknown(evidence, input);
         if (recorded.ok)
             this.#emitSnapshotChanged();
         return recorded;
     }
     updateUnknown(input) {
         const target = this.activeAnalysisBinding()?.target;
-        const evidence = createEvidence(target, UNKNOWN_REGISTRY_PROVIDER, {
-            predicateType: "rea.residual-unknown-mutation",
-            operation: "update_unknown",
-            parameters: {
-                unknown_id: input.unknown_id,
-                expected_revision: input.expected_revision,
-            },
-            result: { action: "update", status: input.status },
-            confidence: "derived",
-            authority: "analyst-inference",
-            evidenceLinks: unknownEvidenceLinks(input),
-            limitations: [
-                "Registry mutation evidence records analyst intent, not proof of the answer.",
-            ],
-        });
-        const updated = this.#evidence.updateUnknown(input, evidence);
+        const updated = this.#records.updateUnknown(input, target);
         if (updated.ok)
             this.#emitSnapshotChanged();
         return updated;
     }
     listUnknowns(filters = {}) {
-        return this.#evidence.listUnknowns(filters);
+        return this.#records.listUnknowns(filters);
     }
     verifyUnknownResolution(unknownId) {
-        return this.#evidence.verifyUnknownResolution(unknownId);
+        return this.#records.verifyUnknownResolution(unknownId);
     }
 }

package/dist/application/{CompositeProvider.js → binary/CompositeProvider.js}

@@ -1,5 +1,5 @@
-import { AnalysisCapabilityUnavailableError } from "../domain/errors.js";
-import { err, ok } from "../domain/result.js";
+import { AnalysisCapabilityUnavailableError } from "../../domain/analysisErrorCore.js";
+import { err, ok } from "../../domain/result.js";
 import { closeAnalysisClient } from "./AnalysisClientCleanup.js";
 /** Synthetic compatibility identity for a deterministic provider set. */
 export const compositeProviderIdentity = (identities) => ({

package/dist/application/{LazyAnalysisProvider.js → binary/LazyAnalysisProvider.js}

@@ -1,5 +1,7 @@
-import { AnalysisCancelledError, AnalysisError, ProviderAdapterError, } from "../domain/errors.js";
-import { err } from "../domain/result.js";
+import { AnalysisCancelledError } from "../../domain/analysisErrorCore.js";
+import { AnalysisError } from "../../domain/analysisErrorBase.js";
+import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
+import { err } from "../../domain/result.js";
 import { ABORTED, waitForAbortable } from "./AbortablePromise.js";
 const isAborted = (signal) => signal?.aborted === true;
 /**
@@ -16,11 +18,11 @@ export class LazyAnalysisProvider {
         this.#capabilityDescriptors = options.capabilities;
         this.#loadProvider = options.load;
     }
-    /** Return generated provider identity without loading its implementation. */
+    /** Return source-declared provider identity without loading its implementation. */
     identity() {
         return this.#providerIdentity;
     }
-    /** Return generated capability metadata without loading its implementation. */
+    /** Return source-declared capability metadata without loading its implementation. */
     capabilities() {
         return this.#capabilityDescriptors;
     }

package/dist/application/{SessionProviderRouter.js → binary/SessionProviderRouter.js}

@@ -1,7 +1,10 @@
-import { analysisProfileSchema, } from "../domain/analysisProfile.js";
-import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, ProviderAdapterError, ProviderSelectionError, } from "../domain/errors.js";
-import { jsonObjectSchema } from "../domain/jsonValue.js";
-import { err, ok } from "../domain/result.js";
+import { analysisProfileSchema, } from "../../domain/analysisProfile.js";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, } from "../../domain/analysisErrorCore.js";
+import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
+import { ProviderSelectionError } from "../../domain/providerSelectionError.js";
+import {} from "../../domain/analysisErrorBase.js";
+import { jsonObjectSchema } from "../../domain/jsonValue.js";
+import { err, ok } from "../../domain/result.js";
 import { AnalysisProviderRegistry, } from "./AnalysisProviderRegistry.js";
 import { ABORTED, waitForAbortable } from "./AbortablePromise.js";
 import { CompositeProvider, compositeProviderIdentity, } from "./CompositeProvider.js";

package/dist/application/firmware/FirmwareAnalysisPort.js

@@ -0,0 +1 @@
+export {};

package/dist/application/firmware/FirmwareAnalysisService.js

@@ -0,0 +1,35 @@
+import { firmwareRequestSchema, } from "../../domain/firmware/firmwareAnalysis.js";
+import { AnalysisCancelledError, AnalysisInputError, AnalysisOutputError, } from "../../domain/analysisErrorCore.js";
+import { createEvidence } from "../../domain/evidence.js";
+import { jsonObjectSchema } from "../../domain/jsonValue.js";
+import { err, ok } from "../../domain/result.js";
+/** Shared CLI/MCP validation and Evidence composition for arbitrary firmware files. */
+export class FirmwareAnalysisService {
+    provider;
+    constructor(provider) {
+        this.provider = provider;
+    }
+    /** Execute an explicit inspection or extraction and preserve its producing identity. */
+    async execute(operation, input, options) {
+        if (options?.signal?.aborted === true)
+            return err(new AnalysisCancelledError(operation));
+        const parsed = firmwareRequestSchema.safeParse({ operation, input });
+        if (!parsed.success)
+            return err(new AnalysisInputError(operation, { cause: parsed.error }));
+        const executed = await this.provider.execute(parsed.data, options);
+        if (!executed.ok)
+            return executed;
+        const execution = executed.value;
+        if (execution.subject === null)
+            return err(new AnalysisOutputError(operation, "Firmware execution did not bind its source artifact"));
+        return ok(createEvidence(execution.subject, execution.provider, {
+            operation,
+            parameters: jsonObjectSchema.parse(parsed.data.input),
+            result: execution.result,
+            rawResult: execution.rawResult,
+            locations: execution.locations,
+            limitations: execution.limitations,
+            confidence: "observed",
+        }));
+    }
+}

package/dist/application/{EvidenceLedger.js → investigation/EvidenceLedger.js}

@@ -1,9 +1,10 @@
 import canonicalize from "canonicalize";
-import { createEvidenceBundle, parseEvidenceBundle, validateResidualUnknownAddition, } from "../domain/evidenceBundle.js";
-import { EvidenceIntegrityError, UnknownRegistryError, } from "../domain/errors.js";
-import { parseEvidence } from "../domain/evidence.js";
-import { createResidualUnknown, updateResidualUnknown, } from "../domain/residualUnknown.js";
-import { err, ok } from "../domain/result.js";
+import { createEvidenceBundle, parseEvidenceBundle, validateResidualUnknownAddition, } from "../../domain/evidenceBundle.js";
+import { EvidenceIntegrityError } from "../../domain/evidenceErrors.js";
+import { UnknownRegistryError } from "../../domain/unknownRegistryError.js";
+import { parseEvidence } from "../../domain/evidence.js";
+import { createResidualUnknown, updateResidualUnknown, } from "../../domain/residualUnknown.js";
+import { err, ok } from "../../domain/result.js";
 /** Session-owned set of immutable evidence records. */
 export class EvidenceLedger {
     #records = new Map();
@@ -40,11 +41,47 @@ export class EvidenceLedger {
                 cause,
             }));
         }
+        // A record-only bundle cannot change the already-valid unknown graph. The
+        // bundle parser has validated every incoming record and its manifests, so
+        // checking ID conflicts and committing only the additions preserves the
+        // atomic merge without rebuilding and reparsing the entire ledger.
+        if (bundle.unknowns.length === 0) {
+            const additions = new Map();
+            const replacements = new Map();
+            let metadataChanged = false;
+            for (const evidence of bundle.records) {
+                const existing = this.#records.get(evidence.evidence_id);
+                if (existing !== undefined) {
+                    if (!recordsAgree(existing, evidence))
+                        return err(new EvidenceIntegrityError("Conflicting evidence record"));
+                    if (canonicalize(existing) !== canonicalize(evidence)) {
+                        replacements.set(evidence.evidence_id, evidence);
+                        metadataChanged = true;
+                    }
+                    continue;
+                }
+                additions.set(evidence.evidence_id, evidence);
+            }
+            for (const [id, evidence] of replacements)
+                this.#records.set(id, evidence);
+            for (const [id, evidence] of additions)
+                this.#records.set(id, evidence);
+            return ok({
+                recordsAdded: additions.size,
+                unknownsAdded: 0,
+                changed: additions.size > 0 || metadataChanged,
+                metadataChanged,
+            });
+        }
         const pending = new Map(this.#records);
+        let metadataChanged = false;
         for (const evidence of bundle.records) {
             const existing = pending.get(evidence.evidence_id);
             if (existing !== undefined && !recordsAgree(existing, evidence))
                 return err(new EvidenceIntegrityError("Conflicting evidence record"));
+            if (existing !== undefined &&
+                canonicalize(existing) !== canonicalize(evidence))
+                metadataChanged = true;
             pending.set(evidence.evidence_id, evidence);
         }
         const pendingUnknowns = new Map(this.#unknownRevisions);
@@ -72,7 +109,8 @@ export class EvidenceLedger {
         return ok({
             recordsAdded: added,
             unknownsAdded,
-            changed: added > 0 || unknownsAdded > 0,
+            changed: added > 0 || unknownsAdded > 0 || metadataChanged,
+            metadataChanged,
         });
     }
     /** Export records in deterministic, semantically irrelevant ID order. */

package/dist/application/investigation/InvestigationRecordPort.js

@@ -0,0 +1 @@
+export {};