Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
fix(artifacts): compare inventories using declared coverage (#2214)
Thang Luu45a3509db34e
diff --git a/docs/mcp-contracts.md b/docs/mcp-contracts.mdindex a2708511c..307d323df 100644--- a/docs/mcp-contracts.md+++ b/docs/mcp-contracts.md@@ -21,6 +21,31 @@ directly to `compare_functions`, and `inspect_artifact` Evidence to`compare_artifacts`. Use `get_evidence_bundle` when the task needs broaderretained session history or an explicit bundle for transfer.+Artifact inventories declare `coverage.scope` (`root` or `container-entries`)+and `coverage.status` (`complete` or `unknown`) independently of diagnostic+wording. Comparison requires matching scopes, complete graph members and complete+traversal coverage before concluding equality. A fully observed root without+container children can be `unchanged`; its scope notice stays in `limitations`+without creating a gap. Content and executable metadata changes still produce+root deltas. Missing graph members yield `truncated`; unknown traversal coverage+or unavailable occurrence hashes retain uncertainty. Integrity mismatches remain+contradictions. Static artifact equality does not establish unchanged runtime+behavior.++Exhausted traversals with deliberately omitted filesystem entries retain+`unknown` coverage and identify each omitted path/type in `limitations`; FIFO,+socket and device entries are not opened. Case-distinct archive members remain+separate observations. Their case-insensitive materialization diagnostic does+not reduce traversal coverage when both spellings were read.++Current output also retains `coverage_status` (`complete` or `partial`) for existing clients, derived from the scoped traversal status. The owning parser normalizes retained `coverage_status` records to scoped coverage and rejects conflicting declarations.++The coverage field is optional when reading older retained Evidence. The owning+inventory parser recognizes historical REA scope notices for compatibility;+unfamiliar legacy limitations remain conservative. Typed records do not derive+coverage from limitation text. Pages from one inventory must carry the same+coverage declaration.+Function dossiers can declare per-facet coverage in the optional`normalized_result.facet_availability` map. Each supplied facet is either`{ "available": true }` or `{ "available": false, "reason": "..." }`.diff --git a/src/artifacts/ArtifactReader.ts b/src/artifacts/ArtifactReader.tsindex f072dd35c..ad40de57d 100644--- a/src/artifacts/ArtifactReader.ts+++ b/src/artifacts/ArtifactReader.ts@@ -1,5 +1,8 @@import type { Readable } from "node:stream";-import type { ArtifactCommand } from "../domain/artifactGraph.js";+import type {+ ArtifactCommand,+ ArtifactInventoryCoverage,+} from "../domain/artifactGraph.js";import type { ZipPackageFormat } from "../domain/zipPackageFormat.js";import type {AnalysisCleanupObservation,@@ -90,10 +93,36 @@ export const sameArtifactEntry = (entry.sourceIdentity?.mtimeNs === produced.sourceIdentity?.mtimeNs &&entry.sourceIdentity?.ctimeNs === produced.sourceIdentity?.ctimeNs;+/** One entry or subtree deliberately excluded from a traversal. */+export interface ArtifactTraversalOmission {+ readonly path: string;+ readonly kind:+ | "fifo"+ | "socket"+ | "block-device"+ | "character-device"+ | "unsupported"+ | "directory-descendants";+}++/** Facts from an exhausted traversal, separate from entry content certainty. */+export interface ArtifactReaderTraversal {+ readonly status: ArtifactInventoryCoverage["status"];+ readonly limitations: readonly string[];+}++/** Per-iterator observation sink; adapters report intentional omissions without shared state. */+export interface ArtifactTraversalOptions {+ readonly onOmission?: (omission: ArtifactTraversalOmission) => void;+}+/** Read-only adapter over one directory, archive, or virtual container. */export interface ArtifactReader {readonly format: "directory" | ZipPackageFormat | "asar" | "file";- entries(signal?: AbortSignal): AsyncIterable<ArtifactEntry>;+ entries(+ signal?: AbortSignal,+ options?: ArtifactTraversalOptions,+ ): AsyncIterable<ArtifactEntry>;open(entry: ArtifactEntry, signal?: AbortSignal): Promise<Readable>;provenance(): readonly ArtifactCommand[];close(): Promise<void>;diff --git a/src/artifacts/DirectoryArtifactReader.ts b/src/artifacts/DirectoryArtifactReader.tsindex 4a1d67135..399bf979b 100644--- a/src/artifacts/DirectoryArtifactReader.ts+++ b/src/artifacts/DirectoryArtifactReader.ts@@ -14,12 +14,18 @@ import {sameArtifactSourceIdentity,type ArtifactEntry,type ArtifactReader,+ type ArtifactTraversalOmission,+ type ArtifactTraversalOptions,} from "./ArtifactReader.js";import { hostExecutableMarking } from "./hostExecutableMarking.js";import { OwnedDirectoryHandle } from "../filesystem/OwnedDirectoryHandle.js";import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";import { readFileHandleChunks } from "../filesystem/readFileHandleChunks.js";+interface DirectoryTraversalOptions extends ArtifactTraversalOptions {+ readonly descendInto?: (path: string) => boolean;+}+/** Non-symlink-following directory reader. */export class DirectoryArtifactReader implements ArtifactReader {readonly format = "directory" as const;@@ -35,9 +41,11 @@ export class DirectoryArtifactReader implements ArtifactReader {/** Enumerate entries, optionally restricting descent while retaining directories. */async *entries(signal?: AbortSignal,- descendInto?: (path: string) => boolean,+ selection?: DirectoryTraversalOptions | ((path: string) => boolean),): AsyncIterable<ArtifactEntry> {const root = await this.#resolveRoot();+ const options =+ typeof selection === "function" ? { descendInto: selection } : selection;const pending = [root];while (pending.length > 0) {abortIfNeeded(signal);@@ -50,7 +58,7 @@ export class DirectoryArtifactReader implements ArtifactReader {directory,pending,signal,- descendInto,+ options,))yield entry;await withDirectoryIoContext("inspect directory", directory, () =>@@ -75,7 +83,7 @@ export class DirectoryArtifactReader implements ArtifactReader {directory: string,pending: string[],signal?: AbortSignal,- descendInto?: (path: string) => boolean,+ options?: DirectoryTraversalOptions,): AsyncIterable<ArtifactEntry> {const root = await this.#resolveRoot();const handle = new OwnedDirectoryHandle(@@ -103,10 +111,16 @@ export class DirectoryArtifactReader implements ArtifactReader {);const path = relative(root, absolute).split(sep).join("/");const entry = artifactEntry(path, absolute, metadata);- if (entry === undefined) continue;+ if (entry === undefined) {+ options?.onOmission?.({ path, kind: unsupportedEntryKind(metadata) });+ continue;+ }yield entry;- if (entry.kind === "directory" && (descendInto?.(path) ?? true))- childDirectories.push(absolute);+ if (entry.kind === "directory") {+ if (options?.descendInto?.(path) ?? true)+ childDirectories.push(absolute);+ else options?.onOmission?.({ path, kind: "directory-descendants" });+ }}} catch (cause: unknown) {traversal = {@@ -256,6 +270,19 @@ export class DirectoryArtifactReader implements ArtifactReader {}}+const unsupportedEntryKind = (+ metadata: BigIntStats,+): ArtifactTraversalOmission["kind"] =>+ metadata.isFIFO()+ ? "fifo"+ : metadata.isSocket()+ ? "socket"+ : metadata.isBlockDevice()+ ? "block-device"+ : metadata.isCharacterDevice()+ ? "character-device"+ : "unsupported";+const artifactEntry = (path: string,absolute: string,diff --git a/src/artifacts/NativeDmgArtifactReader.ts b/src/artifacts/NativeDmgArtifactReader.tsindex 801ee4daf..93c12ece3 100644--- a/src/artifacts/NativeDmgArtifactReader.ts+++ b/src/artifacts/NativeDmgArtifactReader.ts@@ -8,6 +8,7 @@ import {ArtifactReaderFailure,type ArtifactEntry,type ArtifactReader,+ type ArtifactTraversalOptions,} from "./ArtifactReader.js";import { DirectoryArtifactReader } from "./DirectoryArtifactReader.js";import {@@ -149,13 +150,24 @@ export class NativeDmgArtifactReader implements ArtifactReader {this.host = host ?? createSystemHost(environment);}- async *entries(signal?: AbortSignal): AsyncIterable<ArtifactEntry> {+ async *entries(+ signal?: AbortSignal,+ options?: ArtifactTraversalOptions,+ ): AsyncIterable<ArtifactEntry> {await this.#ensureAttached(signal);const directory = this.#directory;if (directory === undefined)throw new ArtifactReaderFailure("unavailable", "DMG is not attached");const prefix = basename(this.path);- const entries = directory.entries(signal)[Symbol.asyncIterator]();+ const entries = directory+ .entries(signal, {+ onOmission: (omission) =>+ options?.onOmission?.({+ ...omission,+ path: `${prefix}/${omission.path}`,+ }),+ })+ [Symbol.asyncIterator]();try {for (;;) {if (this.#closed) return;diff --git a/src/artifacts/inventory/reader.ts b/src/artifacts/inventory/reader.tsindex f195eac27..749b6e0b5 100644--- a/src/artifacts/inventory/reader.ts+++ b/src/artifacts/inventory/reader.ts@@ -1,5 +1,8 @@import { AsarArtifactReader } from "../AsarArtifactReader.js";-import type { ArtifactReader } from "../ArtifactReader.js";+import type {+ ArtifactReader,+ ArtifactReaderTraversal,+} from "../ArtifactReader.js";import { DirectoryArtifactReader } from "../DirectoryArtifactReader.js";import { MachOSliceArtifactReader } from "../MachOSliceArtifactReader.js";import { NativeDmgArtifactReader } from "../NativeDmgArtifactReader.js";@@ -7,7 +10,6 @@ import { ZipArtifactReader } from "../ZipArtifactReader.js";import type {ArtifactInventoryCoverage,ArtifactOccurrence,- IntegrityContradiction,} from "../../domain/artifactGraph.js";import {isZipPackageFormat,@@ -40,42 +42,47 @@ export const createReader = (}};-/** Classify source coverage and preserve its user-facing explanation once. */-export const inventoryAssessment = (+/** Decide traversal scope and availability once, independently of diagnostic wording. */+export const inventoryCoverage = (format: ArtifactOccurrence["artifact_format"],reader: ArtifactReader | undefined,- integrityContradictions: readonly IntegrityContradiction[],- caseCollisionLimitation: string | undefined,+ traversal: ArtifactReaderTraversal,): {- readonly coverage_status: ArtifactInventoryCoverage;+ readonly coverage: ArtifactInventoryCoverage;readonly limitations: string[];} => {- let coverageStatus: ArtifactInventoryCoverage = "complete";- const limitations: string[] = [];- if (reader !== undefined) {- if (isZipPackageFormat(reader.format))- limitations.push(ZIP_NON_ENTRY_TAIL_LIMITATION);- } else if (format === "dmg" || format === "pkg") {- coverageStatus = "partial";- limitations.push(- `${format.toUpperCase()} root hash is observed; child inventory requires a native macOS adapter.`,- );- } else if (format === "mach-o-universal" && process.platform !== "darwin") {- coverageStatus = "partial";- limitations.push(- "Universal Mach-O slices require the native macOS lipo adapter.",- );- } else {- // The graph's modeled scope is the root itself for recognized leaf formats.- limitations.push("Artifact has no child container entries.");- }- if (caseCollisionLimitation !== undefined) {- coverageStatus = "partial";- limitations.push(caseCollisionLimitation);- }- if (integrityContradictions.length > 0)- limitations.push(- `${String(integrityContradictions.length)} integrity contradiction(s) were recorded; mismatched content is observed-untrusted.`,- );- return { coverage_status: coverageStatus, limitations };+ if (reader !== undefined)+ return {+ coverage: { scope: "container-entries", status: traversal.status },+ limitations: [+ ...(isZipPackageFormat(reader.format)+ ? [ZIP_NON_ENTRY_TAIL_LIMITATION]+ : []),+ ...traversal.limitations,+ ],+ };+ // dmg and pkg reach here only after classifyRootFormat matched their bytes.+ if (format === "dmg" || format === "pkg")+ return {+ coverage: { scope: "container-entries", status: "unknown" },+ limitations: [+ `${format.toUpperCase()} root hash is observed; child inventory requires a native macOS adapter.`,+ ],+ };+ if (format === "mach-o-universal")+ return {+ coverage: { scope: "container-entries", status: "unknown" },+ limitations: [+ "Universal Mach-O slices require the native macOS lipo adapter.",+ ],+ };+ if (isZipPackageFormat(format) || format === "directory" || format === "asar")+ return {+ coverage: { scope: "container-entries", status: "unknown" },+ limitations: [`${format} child inventory reader is unavailable.`],+ };+ return {+ coverage: { scope: "root", status: "complete" },+ limitations: ["Artifact has no child container entries."],+ };};diff --git a/src/artifacts/inventory/scanCanonical.ts b/src/artifacts/inventory/scanCanonical.tsindex d5234bdf6..2c8679e21 100644--- a/src/artifacts/inventory/scanCanonical.ts+++ b/src/artifacts/inventory/scanCanonical.ts@@ -10,6 +10,7 @@ import type { RootInventorySource } from "./classify.js";import {ArtifactReaderFailure,type ArtifactReader,+ type ArtifactReaderTraversal,} from "../ArtifactReader.js";import type { ArtifactResourceOwner } from "../ArtifactResourceScope.js";import {@@ -40,7 +41,7 @@ import {hashStableRootArtifact,hashStableRootArtifactHandle,} from "./hashStableRootArtifact.js";-import { createReader, inventoryAssessment } from "./reader.js";+import { createReader, inventoryCoverage } from "./reader.js";import {scanReader,type PendingIntegrityContradiction,@@ -99,6 +100,7 @@ export const scanCanonicalArtifactInventoryInScope = async (occurrences,pendingContradictions,caseCollisionLimitation,+ traversal,} = await scanReader(reader, ownedReaders, options.signal, integrity);outcome = {kind: "completed",@@ -115,6 +117,7 @@ export const scanCanonicalArtifactInventoryInScope = async (occurrences,pendingContradictions,caseCollisionLimitation,+ traversal,}),};} catch (cause: unknown) {@@ -196,6 +199,7 @@ interface SnapshotBuildInput {readonly occurrences: MutableOccurrence[];readonly pendingContradictions: PendingIntegrityContradiction[];readonly caseCollisionLimitation: string | undefined;+ readonly traversal: ArtifactReaderTraversal;}const buildInventorySnapshot = async (@@ -268,12 +272,7 @@ const buildInventorySnapshot = async (orderedOccurrences,orderedEdges,});- const assessment = inventoryAssessment(- rootFormat,- reader,- integrityContradictions,- input.caseCollisionLimitation,- );+ const traversal = inventoryCoverage(rootFormat, reader, input.traversal);return {manifest,nodes: orderedNodes,@@ -281,8 +280,14 @@ const buildInventorySnapshot = async (edges: orderedEdges,provenance: reader?.provenance() ?? [],integrity_contradictions: integrityContradictions,- coverage_status: assessment.coverage_status,- limitations: assessment.limitations,+ coverage: traversal.coverage,+ coverage_status:+ traversal.coverage.status === "complete" ? "complete" : "partial",+ limitations: buildLimitations(+ traversal.limitations,+ integrityContradictions,+ input.caseCollisionLimitation,+ ),};};@@ -395,3 +400,17 @@ const buildManifest = ({occurrence_count: orderedOccurrences.length,edge_count: orderedEdges.length,});++const buildLimitations = (+ scopeLimitations: readonly string[],+ integrityContradictions: readonly IntegrityContradiction[],+ caseCollisionLimitation: string | undefined,+): string[] => [+ ...scopeLimitations,+ ...(caseCollisionLimitation === undefined ? [] : [caseCollisionLimitation]),+ ...(integrityContradictions.length === 0+ ? []+ : [+ `${String(integrityContradictions.length)} integrity contradiction(s) were recorded; mismatched content is observed-untrusted.`,+ ]),+];diff --git a/src/artifacts/inventory/scanReader.ts b/src/artifacts/inventory/scanReader.tsindex 6873b14d7..38b67d843 100644--- a/src/artifacts/inventory/scanReader.ts+++ b/src/artifacts/inventory/scanReader.ts@@ -9,9 +9,12 @@ import {ArtifactReaderFailure,type ArtifactEntry,type ArtifactReader,+ type ArtifactReaderTraversal,+ type ArtifactTraversalOmission,} from "../ArtifactReader.js";import { AsarArtifactReader } from "../AsarArtifactReader.js";import type { ArtifactNode } from "../../domain/artifactGraph.js";+import { compareUnicodeCodePoints } from "../../domain/unicodeCodePointOrder.js";import {classifyArtifactContent,classifyArtifactBytes,@@ -55,6 +58,7 @@ interface ScanContext {readonly registry: ArtifactPathRegistry;readonly expandedContainerIds: Set<string>;readonly ownedReaders: ArtifactReader[];+ readonly omissions: ArtifactTraversalOmission[];}export const scanReader = async (@@ -67,6 +71,7 @@ export const scanReader = async (readonly occurrences: MutableOccurrence[];readonly pendingContradictions: PendingIntegrityContradiction[];readonly caseCollisionLimitation: string | undefined;+ readonly traversal: ArtifactReaderTraversal;}> => {const { nodes, occurrences, pendingContradictions } = emptyScan();if (reader === undefined)@@ -75,6 +80,7 @@ export const scanReader = async (occurrences,pendingContradictions,caseCollisionLimitation: undefined,+ traversal: { status: "complete", limitations: [] },};const context: ScanContext = {reader,@@ -87,6 +93,7 @@ export const scanReader = async (registry: new ArtifactPathRegistry(),expandedContainerIds: new Set<string>(),ownedReaders,+ omissions: [],};await visitArtifactEntries(context, reader, "");// Archive directories may appear after their children. Resolve containment@@ -101,9 +108,37 @@ export const scanReader = async (occurrences,pendingContradictions,caseCollisionLimitation: annotateEnglishUnicodeCaseCollisions(occurrences),+ traversal: {+ status: context.omissions.length === 0 ? "complete" : "unknown",+ limitations: [+ ...new Set(+ context.omissions.map(+ ({ path, kind }) =>+ `Artifact traversal omitted ${kind} at ${JSON.stringify(path)}.`,+ ),+ ),+ ].sort(compareUnicodeCodePoints),+ },};};+const inventoryEntries = (+ context: ScanContext,+ reader: ArtifactReader,+ prefix: string,+): AsyncIterator<ArtifactEntry> =>+ reader+ .entries(context.signal, {+ onOmission: (omission) =>+ context.omissions.push({+ ...omission,+ path: normalizeArtifactPath(+ prefix.length === 0 ? omission.path : `${prefix}/${omission.path}`,+ ),+ }),+ })+ [Symbol.asyncIterator]();+const visitArtifactEntries = async (context: ScanContext,currentReader: ArtifactReader,@@ -117,7 +152,7 @@ const visitArtifactEntries = async ({reader: currentReader,prefix,- iterator: currentReader.entries(context.signal)[Symbol.asyncIterator](),+ iterator: inventoryEntries(context, currentReader, prefix),},];let failure: { readonly cause: unknown } | undefined;@@ -191,7 +226,7 @@ const visitArtifactEntries = async (stack.push({reader: nested,prefix: logicalPath,- iterator: nested.entries(context.signal)[Symbol.asyncIterator](),+ iterator: inventoryEntries(context, nested, logicalPath),});}}diff --git a/src/domain/android/androidApplication.ts b/src/domain/android/androidApplication.tsindex c46fb9661..99b20c321 100644--- a/src/domain/android/androidApplication.ts+++ b/src/domain/android/androidApplication.ts@@ -68,7 +68,7 @@ export const androidApplicationProjectionResultSchema = z.strictObject({// Count completeness is separate from the declared coverage status.inventory_complete: z.boolean(),}),- limitations: z.array(z.string().min(1)),+ limitations: z.array(z.string()),});export type AndroidApplicationProjectionInput = z.infer<@@ -99,7 +99,8 @@ export const projectAndroidApplication = ();const components = classified;const limitations = [- ...(!hasCompleteInventoryCoverage(inventory)+ ...inventory.limitations,+ ...(!hasCompleteInventoryCoverage(inventory, "container-entries")? ["Source inventory coverage is partial; absence is unknown."]: []),"Manifest, resource, signing, and bytecode semantics require a dedicated Android provider; this projection reports exact inventory paths and hashes only.",diff --git a/src/domain/apple/appleApplication.ts b/src/domain/apple/appleApplication.tsindex dfb34e3c5..6dac13f82 100644--- a/src/domain/apple/appleApplication.ts+++ b/src/domain/apple/appleApplication.ts@@ -94,7 +94,7 @@ export const appleApplicationProjectionResultSchema = z.strictObject({// Count completeness is separate from the declared coverage status.inventory_complete: z.boolean(),}),- limitations: z.array(z.string().min(1)),+ limitations: z.array(z.string()),});export type AppleApplicationProjectionInput = z.infer<@@ -169,18 +169,24 @@ export const projectAppleApplication = ();const uninventoriedImage =rootFormat === "dmg" && inventory.occurrences.length === 1;- const inventoryComplete = hasCompleteInventoryCoverage(inventory);+ const inventoryComplete = hasCompleteInventoryCoverage(+ inventory,+ "container-entries",+ );const complete = inventoryComplete && !uninventoriedImage;- const limitations = projectionLimitations({- complete: inventoryComplete,- uninventoriedImage,- roots,- bundles,- sidecars: entries.some(({ path }) => isSidecar(path)),- symlinks: entries.some(({ kind }) => kind === "symlink"),- unattributed,- bridgeCandidateCoverage: bridgeProjection.coverage,- });+ const limitations = [+ ...inventory.limitations,+ ...projectionLimitations({+ complete: inventoryComplete,+ uninventoriedImage,+ roots,+ bundles,+ sidecars: entries.some(({ path }) => isSidecar(path)),+ symlinks: entries.some(({ kind }) => kind === "symlink"),+ unattributed,+ bridgeCandidateCoverage: bridgeProjection.coverage,+ }),+ ];const withoutId = {root_sha256: inventory.manifest.root_sha256,root_format: rootFormat,diff --git a/src/domain/artifactComparison.ts b/src/domain/artifactComparison.tsindex 9d7a766af..72494136c 100644--- a/src/domain/artifactComparison.ts+++ b/src/domain/artifactComparison.ts@@ -104,13 +104,51 @@ export const compareArtifacts = (const right = parseArtifactInventoryEvidence(rightEvidence);const leftComplete = left.inventory.complete;const rightComplete = right.inventory.complete;- const leftCovered = hasCompleteInventoryCoverage(left.inventory);- const rightCovered = hasCompleteInventoryCoverage(right.inventory);+ const sameScope =+ left.inventory.coverage.scope === right.inventory.coverage.scope;+ const rootCoverageComplete =+ sameScope &&+ left.inventory.complete &&+ right.inventory.complete &&+ left.inventory.coverage.status === "complete" &&+ right.inventory.coverage.status === "complete";+ const entryCoverageComplete =+ rootCoverageComplete &&+ left.inventory.coverage.scope === "container-entries";+ const leftCovered =+ sameScope &&+ hasCompleteInventoryCoverage(left.inventory, left.inventory.coverage.scope);+ const rightCovered =+ sameScope &&+ hasCompleteInventoryCoverage(+ right.inventory,+ right.inventory.coverage.scope,+ );+ const fullyCovered =+ leftCovered &&+ rightCovered &&+ (entryCoverageComplete ||+ (rootCoverageComplete &&+ left.inventory.manifest.occurrence_count === 1 &&+ right.inventory.manifest.occurrence_count === 1));const limitations = [...left.inventory.limitations.map((item) => `Left: ${item}`),...right.inventory.limitations.map((item) => `Right: ${item}`),...(leftComplete ? [] : ["Left artifact inventory is incomplete."]),...(rightComplete ? [] : ["Right artifact inventory is incomplete."]),+ ...(sameScope ? [] : ["Artifact inventory scopes differ."]),+ ...(sameScope &&+ left.inventory.coverage.scope === "root" &&+ (left.inventory.manifest.occurrence_count > 1 ||+ right.inventory.manifest.occurrence_count > 1)+ ? ["Container entry coverage is unavailable for child paths."]+ : []),+ ...(left.inventory.coverage.status === "complete"+ ? []+ : ["Left artifact inventory traversal coverage is unknown."]),+ ...(right.inventory.coverage.status === "complete"+ ? []+ : ["Right artifact inventory traversal coverage is unknown."]),];const changes = compareOccurrences(left.inventory,@@ -119,7 +157,7 @@ export const compareArtifacts = (...left.evidence.map(({ evidence_id: id }) => id),...right.evidence.map(({ evidence_id: id }) => id),],- leftCovered && rightCovered,+ { root: rootCoverageComplete, entries: entryCoverageComplete },);applyRootHashChange(left.inventory, right.inventory, changes, [...left.evidence.map(({ evidence_id: id }) => id),@@ -129,7 +167,7 @@ export const compareArtifacts = (left.inventory,right.inventory,changes,- leftCovered && rightCovered,+ fullyCovered,);return artifactComparisonResultSchema.parse({status:@@ -139,7 +177,7 @@ export const compareArtifacts = (({ classification }) => classification === "contradiction",)? "contradiction"- : !leftCovered || !rightCovered+ : !fullyCovered? "unknown": changes.some(({ classification }) => classification === "unknown")? "unknown"@@ -158,7 +196,7 @@ const compareOccurrences = (left: InventorySet,right: InventorySet,evidenceLinks: readonly string[],- complete: boolean,+ coverage: { readonly root: boolean; readonly entries: boolean },): ArtifactChange[] => {const leftByPath = new Map(left.occurrences.map((item) => [item.logical_path, item]),@@ -187,7 +225,8 @@ const compareOccurrences = (rightNode: nodeFor(rightOccurrence, rightNodes),leftRelations: leftRelations.get(path) ?? [],rightRelations: rightRelations.get(path) ?? [],- complete,+ rootCovered: coverage.root,+ entriesCovered: coverage.entries,evidenceLinks,});if (change !== null) output.push(change);@@ -203,7 +242,8 @@ interface ClassifyPathInput {readonly rightNode: ArtifactNode | undefined;readonly leftRelations: readonly RelationProjection[];readonly rightRelations: readonly RelationProjection[];- readonly complete: boolean;+ readonly rootCovered: boolean;+ readonly entriesCovered: boolean;readonly evidenceLinks: readonly string[];}@@ -217,17 +257,18 @@ const buildArtifactChangeBase = (input: ClassifyPathInput) => ({});const classifyPresence = (input: ClassifyPathInput): ArtifactChange | null => {+ const covered = input.path === "." ? input.rootCovered : input.entriesCovered;if (input.leftOccurrence === undefined)return {...buildArtifactChangeBase(input),- classification: input.complete ? "added" : "unknown",- dimensions: [input.complete ? "content" : "availability"],+ classification: covered ? "added" : "unknown",+ dimensions: [covered ? "content" : "availability"],};if (input.rightOccurrence === undefined)return {...buildArtifactChangeBase(input),- classification: input.complete ? "removed" : "unknown",- dimensions: [input.complete ? "content" : "availability"],+ classification: covered ? "removed" : "unknown",+ dimensions: [covered ? "content" : "availability"],};return null;};diff --git a/src/domain/artifactGraph.ts b/src/domain/artifactGraph.tsindex 6b2709baa..5a804c8d6 100644--- a/src/domain/artifactGraph.ts+++ b/src/domain/artifactGraph.ts@@ -188,8 +188,11 @@ export const artifactGraphManifestSchema = z.object({edge_count: z.number().int().min(0),});-/** Whether the inventory producer covered its modeled child-entry scope. */-export const artifactInventoryCoverageSchema = z.enum(["complete", "partial"]);+/** Producer-owned traversal coverage; content certainty remains on each occurrence. */+export const artifactInventoryCoverageSchema = z.strictObject({+ scope: z.enum(["root", "container-entries"]),+ status: z.enum(["complete", "unknown"]),+});export type ArtifactInventoryCoverage = z.infer<typeof artifactInventoryCoverageSchema>;@@ -202,15 +205,19 @@ export const artifactInventoryResultSchema = z.object({edges: z.array(artifactEdgeSchema),provenance: z.array(artifactCommandSchema),integrity_contradictions: z.array(integrityContradictionSchema).default([]),+ // Omitted by older retained Evidence; the inventory parser owns its compatibility policy.+ coverage: artifactInventoryCoverageSchema.optional(),limitations: z.array(z.string()),/** Optional only for persisted inventory Evidence written before this field. */- coverage_status: artifactInventoryCoverageSchema.optional(),+ coverage_status: z.enum(["complete", "partial"]).optional(),});-/** Current inventory producers always classify the coverage they examined. */+/** Current producers always declare coverage; historical Evidence inputs may omit it. */export const artifactInventoryOutputSchema =- artifactInventoryResultSchema.extend({- coverage_status: artifactInventoryCoverageSchema,+ artifactInventoryResultSchema.safeExtend({+ coverage: artifactInventoryCoverageSchema,+ coverage_status:+ artifactInventoryResultSchema.shape.coverage_status.unwrap(),});export type ArtifactInventoryOutput = z.infer<typeof artifactInventoryOutputSchemadiff --git a/src/domain/artifactInventoryEvidence.ts b/src/domain/artifactInventoryEvidence.tsindex 213364816..5f95bdad6 100644--- a/src/domain/artifactInventoryEvidence.ts+++ b/src/domain/artifactInventoryEvidence.ts@@ -18,7 +18,10 @@ import {} from "./artifactIdentity.js";import { parseEvidence, type Evidence } from "./evidence.js";import { artifactInspectionResultSchema } from "./artifactInspection.js";-import { ZIP_NON_ENTRY_TAIL_LIMITATION } from "./zipPackageFormat.js";+import {+ isZipPackageFormat,+ ZIP_NON_ENTRY_TAIL_LIMITATION,+} from "./zipPackageFormat.js";/** Complete or partially assembled inventory used by comparison workflows. */export interface InventorySet {@@ -30,13 +33,17 @@ export interface InventorySet {readonly limitations: readonly string[];/** True when merged node, occurrence, and edge counts match the manifest. */readonly complete: boolean;- readonly coverage_status: ArtifactInventoryCoverage;+ readonly coverage: ArtifactInventoryCoverage;}/** Whether all graph members are present and the producer reports full coverage. */export const hasCompleteInventoryCoverage = (inventory: InventorySet,-): boolean => inventory.complete && inventory.coverage_status === "complete";+ requiredScope: ArtifactInventoryCoverage["scope"],+): boolean =>+ inventory.complete &&+ inventory.coverage.scope === requiredScope &&+ inventory.coverage.status === "complete";export interface ParsedInventorySet {readonly evidence: readonly Evidence[];@@ -132,11 +139,14 @@ const assembleInventoryResults = (const first = pages[0];if (first === undefined)throw new TypeError("Artifact inventory requires Evidence pages");- const coverageStatuses = new Set(pages.map(resolveInventoryCoverageStatus));- if (coverageStatuses.size !== 1)- throw new TypeError("Artifact inventory pages disagree on coverage status");- const coverageStatus = [...coverageStatuses][0]!;const manifestJson = canonicalJson(first.manifest, "Artifact inventory");+ const coverageJson = canonicalJson(+ {+ coverage: first.coverage ?? null,+ coverage_status: first.coverage_status ?? null,+ },+ "Artifact inventory coverage",+ );const nodes = new Map<string, ArtifactNode>();const occurrences = new Map<string, ArtifactOccurrence>();const paths = new Map<string, ArtifactOccurrence>();@@ -144,6 +154,18 @@ const assembleInventoryResults = (for (const page of pages) {if (canonicalJson(page.manifest, "Artifact inventory") !== manifestJson)throw new TypeError("Artifact inventory pages do not share one manifest");+ if (+ canonicalJson(+ {+ coverage: page.coverage ?? null,+ coverage_status: page.coverage_status ?? null,+ },+ "Artifact inventory coverage",+ ) !== coverageJson+ )+ throw new TypeError(+ "Artifact inventory pages do not share one coverage declaration",+ );if (canonicalJson(page.integrity_contradictions, "Artifact inventory") !==canonicalJson(first.integrity_contradictions, "Artifact inventory")@@ -165,12 +187,11 @@ const assembleInventoryResults = (for (const edge of page.edges)mergeExact(edges, edge.edge_id, edge, "edge");}- const inventory = orderedInventory(- first,- pages,- { nodes, occurrences, edges },- coverageStatus,- );+ const inventory = orderedInventory(first, pages, {+ nodes,+ occurrences,+ edges,+ });if (inventory.complete) validateCompleteInventory(inventory);return inventory;};@@ -186,7 +207,6 @@ const orderedInventory = (ArtifactInventoryResult["edges"][number]>;},- coverageStatus: ArtifactInventoryCoverage,): InventorySet => {const nodes = [...values.nodes.values()].sort((left, right) =>compareUnicodeCodePoints(left.artifact_id, right.artifact_id),@@ -197,40 +217,78 @@ const orderedInventory = (const edges = [...values.edges.values()].sort((left, right) =>compareUnicodeCodePoints(left.edge_id, right.edge_id),);+ const limitations = [+ ...new Set(pages.flatMap((inventory) => inventory.limitations)),+ ].sort(compareUnicodeCodePoints);return {manifest: first.manifest,nodes,occurrences,edges,integrityContradictions: first.integrity_contradictions,- limitations: [- ...new Set(pages.flatMap((inventory) => inventory.limitations)),- ].sort(compareUnicodeCodePoints),+ limitations,+ coverage: resolveInventoryCoverage({ ...first, limitations }),complete:nodes.length === first.manifest.node_count &&occurrences.length === first.manifest.occurrence_count &&edges.length === first.manifest.edge_count,- coverage_status: coverageStatus,};};-const resolveInventoryCoverageStatus = (+// Normalize both retained coverage formats at this owning boundary.+const resolveInventoryCoverage = (inventory: ArtifactInventoryResult,): ArtifactInventoryCoverage => {- if (inventory.coverage_status !== undefined) return inventory.coverage_status;- // Older retained Evidence has no typed status. Keep only its known- // informational notices complete; unknown limitation text fails closed.- return inventory.limitations.every(isKnownNonCoverageNotice)- ? "complete"- : "partial";+ const legacy = legacyInventoryCoverage(+ inventory.manifest.root_format,+ inventory.limitations,+ inventory.integrity_contradictions.length,+ );+ if (inventory.coverage !== undefined) {+ if (+ inventory.coverage_status !== undefined &&+ (inventory.coverage.status === "complete") !==+ (inventory.coverage_status === "complete")+ )+ throw new TypeError(+ "Artifact inventory has conflicting coverage declarations",+ );+ return inventory.coverage;+ }+ return inventory.coverage_status === undefined+ ? legacy+ : {+ ...legacy,+ status:+ inventory.coverage_status === "complete" ? "complete" : "unknown",+ };};-const isKnownNonCoverageNotice = (limitation: string): boolean =>- limitation === "Artifact has no child container entries." ||- limitation === ZIP_NON_ENTRY_TAIL_LIMITATION ||- /^\d+ integrity contradiction\(s\) were recorded; mismatched content is observed-untrusted\.$/u.test(- limitation,- );+// Retained pre-coverage records cannot classify arbitrary prose. Recognize only+// the historical producer vocabulary here; unfamiliar diagnostics remain unknown.+const legacyInventoryCoverage = (+ format: ArtifactInventoryResult["manifest"]["root_format"],+ limitations: readonly string[],+ contradictionCount: number,+): ArtifactInventoryCoverage => ({+ scope:+ isZipPackageFormat(format) ||+ ["directory", "asar", "dmg", "pkg", "mach-o-universal"].includes(format)+ ? "container-entries"+ : "root",+ status: limitations.some(+ (limitation) =>+ limitation !== "Artifact has no child container entries." &&+ limitation !== ZIP_NON_ENTRY_TAIL_LIMITATION &&+ !(+ contradictionCount > 0 &&+ limitation ===+ `${String(contradictionCount)} integrity contradiction(s) were recorded; mismatched content is observed-untrusted.`+ ),+ )+ ? "unknown"+ : "complete",+});const validateCompleteInventory = (inventory: InventorySet): void => {const nodeIds = new Set(inventory.nodes.map(({ artifact_id: id }) => id));diff --git a/src/domain/artifactInventorySnapshot.ts b/src/domain/artifactInventorySnapshot.tsindex 2157c03ed..8626d7465 100644--- a/src/domain/artifactInventorySnapshot.ts+++ b/src/domain/artifactInventorySnapshot.ts@@ -7,7 +7,9 @@ import type {/** Immutable inventory produced by one complete artifact scan. */export interface ArtifactInventorySnapshot {- readonly coverage_status: ArtifactInventoryCoverage;+ readonly coverage_status: NonNullable<+ ArtifactInventoryResult["coverage_status"]+ >;readonly manifest: ArtifactInventoryResult["manifest"];readonly nodes: readonly ArtifactNode[];readonly occurrences: ArtifactInventoryResult["occurrences"];@@ -16,5 +18,6 @@ export interface ArtifactInventorySnapshot {ArtifactInventoryResult["provenance"][number]>;readonly integrity_contradictions: readonly IntegrityContradiction[];+ readonly coverage?: ArtifactInventoryCoverage;readonly limitations: readonly string[];}diff --git a/src/domain/harmony/harmonyApplication.ts b/src/domain/harmony/harmonyApplication.tsindex 71755e828..fff8429cb 100644--- a/src/domain/harmony/harmonyApplication.ts+++ b/src/domain/harmony/harmonyApplication.ts@@ -72,7 +72,7 @@ export const harmonyApplicationProjectionResultSchema = z.strictObject({// Count completeness is separate from the declared coverage status.inventory_complete: z.boolean(),}),- limitations: z.array(z.string().min(1)),+ limitations: z.array(z.string()),});export type HarmonyApplicationProjectionInput = z.infer<@@ -112,7 +112,8 @@ export const projectHarmonyApplication = (classified.native_libraries,);const limitations = [- ...(!hasCompleteInventoryCoverage(inventory)+ ...inventory.limitations,+ ...(!hasCompleteInventoryCoverage(inventory, "container-entries")? ["Source inventory coverage is partial; absence is unknown."]: []),...(unavailable.length > 0diff --git a/src/domain/mobileApplicationGraphProjection.ts b/src/domain/mobileApplicationGraphProjection.tsindex 93e4143c5..13bbe9545 100644--- a/src/domain/mobileApplicationGraphProjection.ts+++ b/src/domain/mobileApplicationGraphProjection.ts@@ -56,7 +56,8 @@ export const projectionCoverage = (inventory_complete: boolean;} => ({status:- hasCompleteInventoryCoverage(inventory) && budgetComplete+ hasCompleteInventoryCoverage(inventory, "container-entries") &&+ budgetComplete? ("complete-within-inventory" as const): ("partial" as const),inventory_complete: inventory.complete,diff --git a/tests/acceptance/applications/artifactComparisonCoverage.test.ts b/tests/acceptance/applications/artifactComparisonCoverage.test.tsnew file mode 100644index 000000000..db8660311--- /dev/null+++ b/tests/acceptance/applications/artifactComparisonCoverage.test.ts@@ -0,0 +1,432 @@+import { chmod, mkdir, writeFile } from "node:fs/promises";+import { createServer } from "node:net";+import { join } from "node:path";+import { TextReader, Uint8ArrayWriter, ZipWriter } from "@zip.js/zip.js";+import { expect } from "vitest";++import {+ artifactInventoryResultSchema,+ type ArtifactInventoryResult,+} from "../../../src/domain/artifactGraph.js";+import { artifactInspectionResultSchema } from "../../../src/domain/artifactInspection.js";+import {+ createEvidence,+ parseEvidence,+ type Evidence,+} from "../../../src/domain/evidence.js";+import { jsonValueSchema } from "../../../src/domain/jsonValue.js";+import { connectLocalToolsMcp } from "../../fixtures/localToolsMcp.js";+import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";+import { cliTest, type TestCli } from "../../support/cli/cliFixture.js";++const plist = (message: string) =>+ `<?xml version="1.0" encoding="UTF-8"?>\n<plist version="1.0"><dict><key>message</key><string>${message}</string></dict></plist>\n`;++const inventoryEvidence = (input: unknown): Evidence => {+ const inspection = parseEvidence(input);+ const inventory = artifactInspectionResultSchema+ .parse(inspection.normalized_result)+ .substeps.find(+ ({ evidence }) => evidence.operation === "inventory_artifact",+ )?.evidence;+ if (inventory === undefined) throw new Error("Expected inventory Evidence");+ return parseEvidence(inventory);+};++const inspectPair = async (+ cli: TestCli,+ leftPath: string,+ rightPath: string,+) => {+ const result = await cli.run({+ arguments: ["inspect-artifact", leftPath, "--json"],+ });+ expect(result.exitCode, `${result.stderr}\n${result.stdout}`).toBe(0);+ const left = inventoryEvidence(result.json);+ const { call } = await connectLocalToolsMcp();+ const opened = await call("open_binary", { path: rightPath });+ expect(opened.isError, JSON.stringify(opened)).not.toBe(true);+ const inspected = await call("inspect_artifact", {});+ expect(inspected.isError, JSON.stringify(inspected)).not.toBe(true);+ return { left, right: inventoryEvidence(inspected.structuredContent), call };+};++const assertCoverageControls = async ({+ left,+ right,+ inventory,+ compare,+}: {+ left: Evidence;+ right: Evidence;+ inventory: ArtifactInventoryResult;+ compare: (left: Evidence, right: Evidence) => Promise<Evidence>;+}) => {+ // Authenticated derived controls isolate missing members and genuine coverage+ // gaps; they do not claim that the complete plist producer omitted children.+ const derive = (result: unknown) =>+ createEvidence(+ {+ path: right.subject?.local_path ?? "",+ sha256: inventory.manifest.root_sha256,+ format: "plist",+ },+ right.provider,+ {+ operation: "inventory_artifact",+ parameters: {},+ result: jsonValueSchema.parse(result),+ confidence: "derived",+ authority: "shipped-artifact",+ },+ );+ const partial = await compare(left, derive({ ...inventory, nodes: [] }));+ expect(partial.normalized_result).toMatchObject({+ status: "truncated",+ summary: { unchanged: 0, unknown: 1 },+ });+ const reworded = await compare(+ left,+ derive({+ ...inventory,+ coverage: { scope: "root", status: "complete" },+ limitations: ["Root bytes observed; no container children are modeled."],+ }),+ );+ expect(reworded.normalized_result).toMatchObject({+ status: "unchanged",+ summary: { unchanged: 1, unknown: 0 },+ limitations: expect.arrayContaining([+ "Right: Root bytes observed; no container children are modeled.",+ ]),+ });+ const gap = await compare(+ left,+ derive({+ ...inventory,+ coverage: { scope: "root", status: "unknown" },+ coverage_status: "partial",+ limitations: [],+ }),+ );+ expect(gap.normalized_result).toMatchObject({+ status: "unknown",+ summary: { unchanged: 0, unknown: 1 },+ });+ const differentScope = await compare(+ left,+ derive({+ ...inventory,+ coverage: { scope: "container-entries", status: "complete" },+ }),+ );+ expect(differentScope.normalized_result).toMatchObject({+ status: "unknown",+ limitations: expect.arrayContaining(["Artifact inventory scopes differ."]),+ });++ const { coverage, coverage_status: _coverageStatus, ...legacy } = inventory;+ expect(coverage).toBeDefined();+ const retained = await compare(left, derive(legacy));+ expect(retained.normalized_result).toMatchObject({+ status: "unchanged",+ summary: { unchanged: 1, unknown: 0 },+ });+ for (const limitation of [+ "Child inventory is unavailable.",+ "Missing child observations; 1 integrity contradiction(s) were recorded.",+ ]) {+ const unfamiliarLegacy = await compare(+ left,+ derive({ ...legacy, limitations: [limitation] }),+ );+ expect(unfamiliarLegacy.normalized_result).toMatchObject({+ status: "unknown",+ summary: { unchanged: 0, unknown: 1 },+ });+ }+};++cliTest(+ "compares fully observed roots without inventing coverage gaps through CLI and MCP",+ async ({ cli }) => {+ const root = await createTestTempDirectory("rea-artifact-coverage-");+ const leftPath = join(root, "left.plist");+ const rightPath = join(root, "right.plist");+ await Promise.all([+ writeFile(leftPath, plist("hello")),+ writeFile(rightPath, plist("hello")),+ ]);+ const leftResult = await cli.run({+ arguments: ["inspect-artifact", leftPath, "--json"],+ });+ expect(leftResult.exitCode, leftResult.stderr).toBe(0);+ const left = inventoryEvidence(leftResult.json);+ const { call } = await connectLocalToolsMcp();+ const inspect = async (path: string) => {+ const opened = await call("open_binary", { path });+ expect(opened.isError, JSON.stringify(opened)).not.toBe(true);+ const result = await call("inspect_artifact", {});+ expect(result.isError, JSON.stringify(result)).not.toBe(true);+ return inventoryEvidence(result.structuredContent);+ };+ const compare = async (left: Evidence, right: Evidence) => {+ const result = await call("compare_artifacts", { left, right });+ expect(result.isError, JSON.stringify(result)).not.toBe(true);+ return parseEvidence(result.structuredContent);+ };+ const right = await inspect(rightPath);+ const inventory = artifactInventoryResultSchema.parse(+ right.normalized_result,+ );+ expect(inventory.coverage).toEqual({ scope: "root", status: "complete" });+ expect(inventory.manifest).toMatchObject({+ root_format: "plist",+ node_count: 1,+ occurrence_count: 1,+ edge_count: 0,+ });+ expect(inventory.limitations).toEqual([+ "Artifact has no child container entries.",+ ]);+ const equal = await compare(left, right);+ expect(equal.normalized_result).toMatchObject({+ status: "unchanged",+ summary: { unchanged: 1, unknown: 0 },+ changes: [],+ limitations: [+ "Left: Artifact has no child container entries.",+ "Right: Artifact has no child container entries.",+ ],+ });+ const behavior = await call("find_changed_behavior", {+ comparisons: [equal],+ });+ expect(behavior.isError, JSON.stringify(behavior)).not.toBe(true);+ expect(behavior.structuredContent).toMatchObject({+ normalized_result: {+ behavior_status: "unknown",+ summary: { unresolved: 0 },+ findings: { items: [] },+ limitations: expect.arrayContaining([+ "No process comparison Evidence was supplied.",+ ]),+ },+ });+ const unknowns = await call("list_unknowns", {+ domain: "artifact-comparison",+ });+ expect(unknowns.isError, JSON.stringify(unknowns)).not.toBe(true);+ expect(unknowns.structuredContent).toMatchObject({+ result: { items: [], total: 0 },+ });++ await writeFile(rightPath, plist("world"));+ const changed = await compare(left, await inspect(rightPath));+ expect(changed.normalized_result).toMatchObject({+ status: "changed",+ summary: { unchanged: 0, changed: 1, unknown: 0 },+ changes: [+ expect.objectContaining({ logical_path: ".", dimensions: ["content"] }),+ ],+ });++ const zipPaths = [join(root, "left.zip"), join(root, "right.zip")] as const;+ const writer = new ZipWriter(new Uint8ArrayWriter());+ await writer.add("same.txt", new TextReader("same"));+ const bytes = await writer.close();+ await Promise.all(zipPaths.map((path) => writeFile(path, bytes)));+ const zip = await compare(+ await inspect(zipPaths[0]),+ await inspect(zipPaths[1]),+ );+ expect(zip.normalized_result).toMatchObject({+ status: "unchanged",+ summary: { unchanged: 2, unknown: 0 },+ changes: [],+ });++ await assertCoverageControls({ left, right, inventory, compare });+ },+ 30_000,+);++cliTest.skipIf(process.platform === "win32")(+ "preserves executable metadata changes for fully observed plist roots",+ async ({ cli }) => {+ const root = await createTestTempDirectory("rea-artifact-mode-");+ const leftPath = join(root, "left.plist");+ const rightPath = join(root, "right.plist");+ await Promise.all([+ writeFile(leftPath, plist("hello")),+ writeFile(rightPath, plist("hello")),+ ]);+ await Promise.all([chmod(leftPath, 0o644), chmod(rightPath, 0o755)]);+ const result = await cli.run({+ arguments: ["inspect-artifact", leftPath, "--json"],+ });+ expect(result.exitCode, result.stderr).toBe(0);+ const left = inventoryEvidence(result.json);+ const { call } = await connectLocalToolsMcp();+ const opened = await call("open_binary", { path: rightPath });+ expect(opened.isError, JSON.stringify(opened)).not.toBe(true);+ const inspected = await call("inspect_artifact", {});+ expect(inspected.isError, JSON.stringify(inspected)).not.toBe(true);+ const right = inventoryEvidence(inspected.structuredContent);+ expect(right.subject?.digest.sha256).toBe(left.subject?.digest.sha256);+ const comparison = await call("compare_artifacts", { left, right });+ expect(comparison.isError, JSON.stringify(comparison)).not.toBe(true);+ expect(+ parseEvidence(comparison.structuredContent).normalized_result,+ ).toMatchObject({+ status: "changed",+ summary: { unchanged: 0, changed: 1, unknown: 0 },+ changes: [+ expect.objectContaining({+ logical_path: ".",+ dimensions: ["executable"],+ }),+ ],+ });+ },+ 30_000,+);++cliTest.skipIf(process.platform === "win32")(+ "retains traversal uncertainty when a directory omits special filesystem entries",+ async ({ cli, processes }) => {+ const root = await createTestTempDirectory("rea-gap-");+ const leftPath = join(root, "l.app"),+ rightPath = join(root, "r.app");+ await Promise.all([mkdir(leftPath), mkdir(rightPath)]);+ await Promise.all([+ writeFile(join(leftPath, "same.txt"), "same"),+ writeFile(join(rightPath, "same.txt"), "same"),+ ]);+ await Promise.all(+ [leftPath, rightPath].flatMap((path) => [+ writeFile(+ join(path, "Info.plist"),+ "<plist><dict><key>CFBundleExecutable</key><string>main.js</string></dict></plist>",+ ),+ writeFile(join(path, "main.js"), "export const value = 1;"),+ ]),+ );+ const fifo = await processes.run("mkfifo", [join(leftPath, "p")]);+ expect(fifo.exitCode, fifo.stderr).toBe(0);+ const socket = createServer();+ await new Promise<void>((resolve, reject) => {+ socket.once("error", reject);+ socket.listen(join(leftPath, "s"), resolve);+ });+ try {+ const { left, right, call } = await inspectPair(cli, leftPath, rightPath);+ const inventory = artifactInventoryResultSchema.parse(+ left.normalized_result,+ );+ expect(inventory.coverage).toEqual({+ scope: "container-entries",+ status: "unknown",+ });+ expect(inventory.limitations).toEqual(+ expect.arrayContaining([+ 'Artifact traversal omitted fifo at "p".',+ 'Artifact traversal omitted socket at "s".',+ ]),+ );+ const compared = await call("compare_artifacts", { left, right });+ expect(compared.isError, JSON.stringify(compared)).not.toBe(true);+ expect(+ parseEvidence(compared.structuredContent).normalized_result,+ ).toMatchObject({ status: "unknown", summary: { unchanged: 0 } });+ } finally {+ await new Promise<void>((resolve, reject) =>+ socket.close((cause) =>+ cause === undefined ? resolve() : reject(cause),+ ),+ );+ }+ },+ 30_000,+);++cliTest(+ "compares fully traversed case-distinct ZIP entries while retaining materialization limits",+ async ({ cli }) => {+ const root = await createTestTempDirectory("rea-case-coverage-");+ const leftPath = join(root, "left.zip"),+ rightPath = join(root, "right.zip");+ const writer = new ZipWriter(new Uint8ArrayWriter());+ await writer.add("A", new TextReader("upper"));+ await writer.add("a", new TextReader("lower"));+ const bytes = await writer.close();+ await Promise.all([+ writeFile(leftPath, bytes),+ writeFile(rightPath, bytes),+ ]);+ const { left, right, call } = await inspectPair(cli, leftPath, rightPath);+ const inventory = artifactInventoryResultSchema.parse(+ left.normalized_result,+ );+ expect(inventory.coverage).toEqual({+ scope: "container-entries",+ status: "complete",+ });+ expect(+ inventory.occurrences.map(({ logical_path }) => logical_path).sort(),+ ).toEqual([".", "A", "a"]);+ const compared = await call("compare_artifacts", { left, right });+ expect(compared.isError, JSON.stringify(compared)).not.toBe(true);+ expect(+ parseEvidence(compared.structuredContent).normalized_result,+ ).toMatchObject({+ status: "unchanged",+ summary: { unchanged: 3, unknown: 0 },+ changes: [],+ limitations: expect.arrayContaining([+ expect.stringContaining("case-insensitive destination"),+ ]),+ });+ },+ 30_000,+);++cliTest(+ "keeps unreadable encrypted ZIP content unknown with complete traversal",+ async ({ cli }) => {+ const root = await createTestTempDirectory("rea-encrypted-comparison-");+ const leftPath = join(root, "left.zip");+ const rightPath = join(root, "right.zip");+ const writer = new ZipWriter(new Uint8ArrayWriter());+ await writer.add("secret.txt", new TextReader("secret bytes"), {+ password: "fixture-password",+ });+ const bytes = await writer.close();+ await Promise.all([+ writeFile(leftPath, bytes),+ writeFile(rightPath, bytes),+ ]);+ const { left, right, call } = await inspectPair(cli, leftPath, rightPath);+ for (const evidence of [left, right])+ expect(+ artifactInventoryResultSchema.parse(evidence.normalized_result),+ ).toMatchObject({+ coverage: { scope: "container-entries", status: "complete" },+ occurrences: expect.arrayContaining([+ expect.objectContaining({+ logical_path: "secret.txt",+ hash_status: "unavailable",+ encrypted: true,+ }),+ ]),+ });+ const compared = await call("compare_artifacts", { left, right });+ expect(compared.isError, JSON.stringify(compared)).not.toBe(true);+ const result = parseEvidence(compared.structuredContent).normalized_result;+ expect(result).toMatchObject({+ status: "unknown",+ summary: { unknown: expect.any(Number) },+ });+ expect(result).toHaveProperty("summary.unknown", 1);+ },+);diff --git a/tests/boundary/filesystem/android/application.test.ts b/tests/boundary/filesystem/android/application.test.tsindex 28fa4d8c8..01a5901c8 100644--- a/tests/boundary/filesystem/android/application.test.ts+++ b/tests/boundary/filesystem/android/application.test.ts@@ -228,7 +228,7 @@ describe("case-distinct APK resource names", () => {await runProviderAnalysis(path, "inventory_artifact", {}),);expect(inventory.normalized_result).toMatchObject({- coverage_status: "partial",+ coverage_status: "complete",});const result = projectAndroidApplicationEvidence({inventory_evidence: [inventory],@@ -238,11 +238,11 @@ describe("case-distinct APK resource names", () => {);expect(projection.root_format).toBe("apk");expect(projection.coverage).toEqual({- status: "partial",+ status: "complete-within-inventory",inventory_complete: true,});- expect(projection.limitations).toContain(- "Source inventory coverage is partial; absence is unknown.",+ expect(projection.limitations.join(" ")).toContain(+ "case-insensitive destination",);expect(projection.components.manifests).toHaveLength(1);expect(projection.components.dex).toHaveLength(1);diff --git a/tests/boundary/filesystem/appleApplication.test.ts b/tests/boundary/filesystem/appleApplication.test.tsindex 00ef24ba5..31c395b55 100644--- a/tests/boundary/filesystem/appleApplication.test.ts+++ b/tests/boundary/filesystem/appleApplication.test.ts@@ -75,7 +75,7 @@ async function createCompleteAppleProjection() {}describe("Apple application projection", () => {- it("keeps a case-colliding real IPA inventory partial", async () => {+ it("retains complete traversal and case-collision limits for a real IPA", async () => {const root = await createTestTempDirectory("rea-apple-case-collision-");const path = join(root, "CaseCollision.ipa");const writer = new ZipWriter(new Uint8ArrayWriter());@@ -93,7 +93,7 @@ describe("Apple application projection", () => {await runProviderAnalysis(path, "inventory_artifact", {}),);expect(inventory.normalized_result).toMatchObject({- coverage_status: "partial",+ coverage_status: "complete",});const result = projectAppleApplicationEvidence({inventory_evidence: [inventory],@@ -103,11 +103,11 @@ describe("Apple application projection", () => {);expect(projection.coverage).toEqual({- status: "partial",+ status: "complete-within-inventory",inventory_complete: true,});- expect(projection.limitations).toContain(- "Source inventory coverage is partial; absence is unknown.",+ expect(projection.limitations.join(" ")).toContain(+ "case-insensitive destination",);});diff --git a/tests/boundary/filesystem/artifactComparison.test.ts b/tests/boundary/filesystem/artifactComparison.test.tsindex ca40596d3..f298c28dd 100644--- a/tests/boundary/filesystem/artifactComparison.test.ts+++ b/tests/boundary/filesystem/artifactComparison.test.ts@@ -77,7 +77,11 @@ describe("leaf artifact comparison", () => {// Persisted inventory Evidence predates coverage_status. The known leaf// notice remains complete when normalized at the inventory boundary.const parsed = artifactInventoryResultSchema.parse(left.normalized_result);- const { coverage_status: _coverageStatus, ...legacyInventory } = parsed;+ const {+ coverage: _coverage,+ coverage_status: _coverageStatus,+ ...legacyInventory+ } = parsed;const legacy = createEvidence({path: left.subject!.local_path,@@ -157,7 +161,7 @@ describe("artifact inventory coverage", () => {const graph = artifactInventoryResultSchema.parse(complete.normalized_result,);- const partial = createEvidence(+ const contradictory = createEvidence({path: complete.subject!.local_path,sha256: complete.subject!.digest.sha256,@@ -168,6 +172,29 @@ describe("artifact inventory coverage", () => {operation: "inventory_artifact",parameters: {},result: jsonValueSchema.parse({ ...graph, coverage_status: "partial" }),+ confidence: "derived",+ authority: "shipped-artifact",+ },+ );+ expect(() => parseArtifactInventoryEvidence(contradictory)).toThrow(+ "Artifact inventory has conflicting coverage declarations",+ );++ const { coverage: _coverage, ...legacyStatusGraph } = graph;+ const partial = createEvidence(+ {+ path: complete.subject!.local_path,+ sha256: complete.subject!.digest.sha256,+ format: complete.subject!.format,+ },+ PROVIDER,+ {+ operation: "inventory_artifact",+ parameters: {},+ result: jsonValueSchema.parse({+ ...legacyStatusGraph,+ coverage_status: "partial",+ }),confidence: "observed",authority: "shipped-artifact",},@@ -180,7 +207,8 @@ describe("artifact inventory coverage", () => {summary: { unchanged: 0, unknown: 1 },});- const { coverage_status: _coverageStatus, ...legacyGraph } = graph;+ const { coverage_status: _coverageStatus, ...legacyGraph } =+ legacyStatusGraph;const unknownLegacy = createEvidence({path: complete.subject!.local_path,@@ -219,6 +247,7 @@ describe("artifact inventory coverage", () => {const fragmentGraph = artifactInventoryResultSchema.parse(fragment.normalized_result,);+ const { coverage: _coverage, ...legacyFragmentGraph } = fragmentGraph;const mixed = createEvidence({path: fragment.subject!.local_path,@@ -230,7 +259,7 @@ describe("artifact inventory coverage", () => {operation: "inventory_artifact",parameters: fragment.parameters,result: jsonValueSchema.parse({- ...fragmentGraph,+ ...legacyFragmentGraph,coverage_status: "partial",}),confidence: "derived",@@ -239,7 +268,7 @@ describe("artifact inventory coverage", () => {);expect(() =>parseArtifactInventoryEvidence([firstFragment, mixed]),- ).toThrow("Artifact inventory pages disagree on coverage status");+ ).toThrow("Artifact inventory pages do not share one coverage declaration");});});@@ -314,6 +343,61 @@ describe("artifact comparison", () => {});describe("artifact comparison completeness", () => {+ it("does not infer child changes from root-only coverage", async () => {+ const root = await createTestTempDirectory("rea-artifact-root-coverage-");+ const leftPath = join(root, "left.app");+ const rightPath = join(root, "right.app");+ await Promise.all([mkdir(leftPath), mkdir(rightPath)]);+ await Promise.all([+ writeFile(join(leftPath, "left-only.txt"), "left"),+ writeFile(join(rightPath, "right-only.txt"), "right"),+ ]);+ const [left, right] = await Promise.all([+ observe(leftPath),+ observe(rightPath),+ ]);+ const rootOnly = (evidence: Awaited<ReturnType<typeof observe>>) => {+ const inventory = artifactInventoryResultSchema.parse(+ evidence.normalized_result,+ );+ return createEvidence(+ {+ path: evidence.subject?.local_path ?? "",+ sha256: inventory.manifest.root_sha256,+ format: inventory.manifest.root_format,+ },+ PROVIDER,+ {+ operation: "inventory_artifact",+ parameters: {},+ result: jsonValueSchema.parse({+ ...inventory,+ coverage: { scope: "root", status: "complete" },+ }),+ confidence: "derived",+ authority: "shipped-artifact",+ },+ );+ };+ const compared = compareArtifacts(rootOnly(left), rootOnly(right));+ expect(compared.status).toBe("unknown");+ expect(compared.summary).toMatchObject({ added: 0, removed: 0 });+ expect(+ compared.changes+ .filter(({ logical_path }) => logical_path !== ".")+ .map(({ logical_path, classification }) => ({+ logical_path,+ classification,+ })),+ ).toEqual([+ { logical_path: "left-only.txt", classification: "unknown" },+ { logical_path: "right-only.txt", classification: "unknown" },+ ]);+ expect(compared.limitations).toContain(+ "Container entry coverage is unavailable for child paths.",+ );+ });+it("compares every graph member for inventories larger than 500 entries", async () => {const root = await createTestTempDirectory("rea-artifact-pages-");const entryCount = 501;@@ -415,6 +499,30 @@ describe("artifact comparison completeness", () => {evidence_links: citations,})),});+ const fragment = leftFragments[0];+ if (fragment === undefined) throw new Error("Expected inventory fragments");+ const conflictingScope = createEvidence(+ {+ path: leftPath,+ sha256: left.subject?.digest.sha256 ?? "",+ format: "directory",+ },+ PROVIDER,+ {+ operation: "inventory_artifact",+ parameters: {},+ result: jsonValueSchema.parse({+ ...artifactInventoryResultSchema.parse(fragment.normalized_result),+ coverage: { scope: "root", status: "complete" },+ }),+ },+ );+ expect(() =>+ compareArtifacts(+ [conflictingScope, ...leftFragments.slice(1)],+ rightFragments,+ ),+ ).toThrow(/coverage declaration/u);}, 15_000);it("rejects non-inventory and tampered Evidence", async () => {diff --git a/tests/boundary/filesystem/artifactInventoryRegularRoot.test.ts b/tests/boundary/filesystem/artifactInventoryRegularRoot.test.tsindex 9ea26cfda..05e6a0e1a 100644--- a/tests/boundary/filesystem/artifactInventoryRegularRoot.test.ts+++ b/tests/boundary/filesystem/artifactInventoryRegularRoot.test.ts@@ -52,3 +52,22 @@ it("rejects a root path replaced between its initial stat and open", async () =>message: `Root artifact changed before inventory: ${path}`,});});++it("keeps unavailable container traversal distinct from observed root bytes", async () => {+ const root = await createTestTempDirectory("rea-artifact-root-scope-");+ const path = join(root, "fixture.pkg");+ // The recognized XAR prefix selects PKG inventory; no child decoder is installed.+ await writeFile(path, Buffer.from("xar!fixture"));+ const inventory = await inventoryArtifact(path);+ expect(inventory.manifest).toMatchObject({+ root_format: "pkg",+ node_count: 1,+ occurrence_count: 1,+ edge_count: 0,+ });+ expect(inventory.occurrences[0]?.hash_status).toBe("verified");+ expect(inventory.coverage).toEqual({+ scope: "container-entries",+ status: "unknown",+ });+});diff --git a/tests/boundary/filesystem/harmony/application.test.ts b/tests/boundary/filesystem/harmony/application.test.tsindex b2870e6c5..a50c440e9 100644--- a/tests/boundary/filesystem/harmony/application.test.ts+++ b/tests/boundary/filesystem/harmony/application.test.ts@@ -214,7 +214,7 @@ describe("HarmonyOS packaging boundaries", () => {});describe("HarmonyOS inventory coverage", () => {- it("keeps a case-colliding inventory partial in the application projection", async () => {+ it("retains complete traversal and case-collision limits in the application projection", async () => {const path = await writeApplicationZip("rea-harmony-case-collision-","Fixture.hap",@@ -225,7 +225,7 @@ describe("HarmonyOS inventory coverage", () => {);const inventory = await inventoryApplicationPackage(path);expect(inventory.normalized_result).toMatchObject({- coverage_status: "partial",+ coverage_status: "complete",});const projection = requireDeterministicProjection(@@ -234,11 +234,11 @@ describe("HarmonyOS inventory coverage", () => {harmonyApplicationProjectionResultSchema,);expect(projection.coverage).toEqual({- status: "partial",+ status: "complete-within-inventory",inventory_complete: true,});- expect(projection.limitations).toContain(- "Source inventory coverage is partial; absence is unknown.",+ expect(projection.limitations.join(" ")).toContain(+ "case-insensitive destination",);});diff --git a/tests/boundary/mcp/artifactMcp.inlineInventory.test.ts b/tests/boundary/mcp/artifactMcp.inlineInventory.test.tsindex de78af9d0..fa0481ac7 100644--- a/tests/boundary/mcp/artifactMcp.inlineInventory.test.ts+++ b/tests/boundary/mcp/artifactMcp.inlineInventory.test.ts@@ -254,8 +254,11 @@ const assertHistoricalInventory = async (const { archive, parent, inventoryEvidence, graph } = input;// Historical records may omit a later inventory field. Input parsing must// not insert defaults inside that authenticated child Evidence.- const { integrity_contradictions: _contradictions, ...legacyInventory } =- graph;+ const {+ integrity_contradictions: _contradictions,+ coverage: _coverage,+ ...legacyInventory+ } = graph;const legacyTarget = {path: archive,sha256: graph.manifest.root_sha256,@@ -275,6 +278,9 @@ const assertHistoricalInventory = async (expect(legacyInspection.substeps[0]?.evidence.normalized_result,).not.toHaveProperty("integrity_contradictions");+ expect(+ legacyInspection.substeps[0]?.evidence.normalized_result,+ ).not.toHaveProperty("coverage");const legacyParent = createEvidence(legacyTarget, parent.provider, {operation: "inspect_artifact",parameters: {},diff --git a/tests/boundary/mcp/artifactMcp.test.ts b/tests/boundary/mcp/artifactMcp.test.tsindex da8a586d2..96ba07283 100644--- a/tests/boundary/mcp/artifactMcp.test.ts+++ b/tests/boundary/mcp/artifactMcp.test.ts@@ -1,5 +1,7 @@import { parseMcpToolError } from "../../fixtures/mcpToolError.js";-import { parseEvidence } from "../../../src/domain/evidence.js";+import { createEvidence, parseEvidence } from "../../../src/domain/evidence.js";+import { jsonValueSchema } from "../../../src/domain/jsonValue.js";+import { artifactInventoryResultSchema } from "../../../src/domain/artifactGraph.js";import { ok as resultOk } from "../../../src/domain/result.js";import { mkdir, readFile, rm, writeFile } from "node:fs/promises";import { join } from "node:path";@@ -98,20 +100,6 @@ it.each([20_000,);-const artifactInventoryResultSchema = z.object({- occurrences: z.array(- z.object({ logical_path: z.string(), hash_status: z.string() }),- ),- integrity_contradictions: z.array(- z.object({- logical_path: z.string(),- declared_sha256: z.string(),- observed_sha256: z.string(),- trust: z.literal("observed-untrusted"),- }),- ),-});-it("extracts an active archive through MCP when requested", async () => {const root = await createTestTempDirectory("rea-artifact-extract-mcp-");const archive = join(root, "fixture.zip");@@ -318,6 +306,30 @@ it("records an explicitly continued mismatch, preserves verified siblings, and n}),]),});+ const { coverage: _coverage, ...legacyInventory } = inventory;+ const historical = createEvidence(+ { path: archive, sha256: inventory.manifest.root_sha256, format: "asar" },+ compact.provider,+ {+ operation: "inventory_artifact",+ parameters: {},+ result: jsonValueSchema.parse(legacyInventory),+ },+ );+ const retainedComparison = await client.callTool({+ name: "compare_artifacts",+ arguments: { left: evidence, right: historical },+ });+ expect(+ retainedComparison.isError,+ JSON.stringify(retainedComparison),+ ).not.toBe(true);+ expect(+ toolEvidence(retainedComparison.structuredContent).normalized_result,+ ).toMatchObject({+ status: "contradiction",+ summary: { unchanged: 2, contradiction: 2, unknown: 0 },+ });} finally {await Promise.allSettled([client.close(), server.close(), session.close()]);}diff --git a/tests/boundary/providers/native/nativeDmgArtifactReader.test.ts b/tests/boundary/providers/native/nativeDmgArtifactReader.test.tsindex 5d6af987d..72d11abec 100644--- a/tests/boundary/providers/native/nativeDmgArtifactReader.test.ts+++ b/tests/boundary/providers/native/nativeDmgArtifactReader.test.ts@@ -17,6 +17,7 @@ import { execFileOutput } from "../../../../src/process/ExecFileOutput.js";import {ArtifactReaderFailure,type ArtifactEntry,+ type ArtifactTraversalOmission,} from "../../../../src/artifacts/ArtifactReader.js";import { ArtifactResourceScope } from "../../../../src/artifacts/ArtifactResourceScope.js";import { DirectoryArtifactReader } from "../../../../src/artifacts/DirectoryArtifactReader.js";@@ -473,10 +474,10 @@ describe("native DMG traversal shutdown", () => {.mockImplementation(async function* (this: DirectoryArtifactReader,signal?: AbortSignal,- descendInto?: (path: string) => boolean,+ selection?: Parameters<DirectoryArtifactReader["entries"]>[1],) {const iterator = originalEntries- .call(this, signal, descendInto)+ .call(this, signal, selection)[Symbol.asyncIterator]();try {for (;;) {@@ -606,9 +607,20 @@ describe("native DMG artifact reader", () => {undefined,host,);+ if (mountPoint === undefined) throw new Error("expected mounted directory");+ if (process.platform !== "win32")+ await execFileOutput("mkfifo", [join(mountPoint, "special.pipe")]);const entries = [];- for await (const entry of reader.entries()) entries.push(entry.path);+ const omissions: ArtifactTraversalOmission[] = [];+ for await (const entry of reader.entries(undefined, {+ onOmission: (omission) => omissions.push(omission),+ }))+ entries.push(entry.path);expect(entries).toContain("image.dmg/Fixture/hello.txt");+ if (process.platform !== "win32")+ expect(omissions).toEqual([+ { path: "image.dmg/Fixture/special.pipe", kind: "fifo" },+ ]);const provenance = reader.provenance();const first = provenance[0];if (first === undefined) throw new Error("expected attachment provenance");