Files
reverse-engineering-anything/src/domain/evidenceBundle.ts
T
morluto 63b0426e40 fix(errors): rethrow internal invariant violations from plist consumers and the native output projection (#11029)
* fix(plist): rethrow internal invariant violations from plist consumers

KeyedArchiveReader reported any non-limit decode failure as a format
failure, InterfaceBuilderAnalysis listed it as an invalid archive,
ReleaseExposureReader fell back to scanning raw bytes, and the native
plist parser reported it as provider output. An InternalInvariantError
is a REA defect, not evidence about the input, so each consumer now
rethrows it. The native parser's binary path now shares its one cause
projection instead of a duplicate.

* fix(native): rethrow internal invariant violations from the native output projection

nativeOutputFailure wrapped any producer failure as AnalysisOutputError,
so a REA defect thrown while reading a plist or dispatching a command was
reported as native output parsing. It now rethrows InternalInvariantError,
which reaches the provider's adapter-failure path with the invariant as
its cause.

* fix(artifacts): rethrow internal invariant violations from the shared artifact failure mapper

translateArtifactFailure turned every unrecognised cause into an
ArtifactOperationError with reason io, so the keyed-archive and
Interface Builder rethrows still reached users as artifact read
failures. The shared mapper now rethrows InternalInvariantError, and the
deferred client reports it as a ProviderAdapterError. Provider-level
tests drive both operations through that client.

* refactor(dotnet): report managed reader defects through invariantViolation (#11030)

* refactor(dotnet): report managed reader defects through invariantViolation

The managed readers threw plain TypeError and RangeError for states their
callers rule out: an allowance or method page outside the input schema, a
missing snapshot after identity admission, and a missing CLI header after
the caller already returned for it. These are REA defects, not malformed
targets, so they throw invariantViolation. The two CLI re-checks are gone:
the callers pass the CLI header they already narrowed. The dotnet
parser-plain-throw baseline drops from 6 to 0.

* refactor(providers): refuse unusable tool paths and record marker mismatches without throwing to their own catch (#11031)

* refactor(firmware): refuse unusable tool paths without throwing to its own catch

resolveFirmwareCommand threw a plain TypeError for a configured engine or
limiter path that is not a regular file, only to catch it in the next line
and wrap it as an unavailable capability. A helper now returns why a path
cannot run, and each caller builds the one refusal directly. Refusal
reasons are unchanged; the directory tests now pin them exactly. The
firmware parser-plain-throw baseline drops from 2 to 0.

* refactor(pwndbg): refuse unusable debugger paths without throwing to its own catch

inspectPwndbgCore threw plain Errors for a relative or wrong-kind
configured path only to catch them and wrap them as an unavailable
capability. A helper now returns why a path cannot be used, with any host
error as its cause, and the loop builds the one refusal. Cancellation
between host checks still propagates. Refusal reasons are unchanged. The
PwndbgCoreContext parser-plain-throw baseline entry is removed.

* refactor(pwntools): record a mismatched failure marker without throwing to its own catch

readPwntoolsFailureEvidence threw a plain Error when the private bridge
marker disagreed with the exit status, only to catch it and record its
message as the marker failure. The mismatch is now recorded directly. The
recorded evidence is unchanged; a unit test pins both the matching and
the mismatched marker. The PwntoolsResourceLimits parser-plain-throw
baseline entry is removed.

* fix(android): report an unobserved Java probe as a REA defect, not a Java refusal (#11032)

* fix(android): report an unobserved Java probe as a REA defect, not a Java refusal

When runOwnedCommand resolved without observing the completed run, the
probe threw a plain Error that its catch then classified as a Java
runtime refusal, telling the caller to review their launcher. The state
is a broken internal assumption, so the probe throws invariantViolation
and projects it as a jadx adapter failure. The JadxJavaProbe
parser-plain-throw baseline entry is removed.

* refactor(native): report native provider defects through invariantViolation (#11033)

* refactor(native): report native provider defects through invariantViolation

Native providers threw plain Error and TypeError for states their own
earlier steps rule out: a client with no target, a measured slice with no
selection, a read longer than requested, a decoder command without its
runtime, an LLDB root released before its children, and an IPS integer
fact from another reader. These are REA defects, so they throw
invariantViolation. NativeUiInterruptionControl no longer needs a throw:
recording the deadline interruption returns the interruption its error is
built from. Six native parser-plain-throw baseline entries drop.

* refactor(native): report malformed lipo, swift-demangle and UI helper output through ParseFailure (#11034)

* refactor(native): report malformed lipo and swift-demangle output through ParseFailure

The lipo and swift-demangle output parsers threw plain TypeError for
output that breaks their framing, and the lipo result classifier caught
every TypeError as malformed output, so a host TypeError from a REA defect
was reported as lipo output. Both parsers now throw malformedInput with
their own format, and the lipo classifier accepts ParseFailureError
instead of TypeError. Messages and the consumers' output and format
failure categories are unchanged. Four native parser-plain-throw
baseline entries drop.

* refactor(native): report the UI helper's non-JSON output through ParseFailure

The native UI helper runtime threw a plain Error when the helper's
stdout was not JSON. It now throws malformedInput with its own format and
the JSON failure as cause. The observation boundary still reports it as a
native-macos adapter failure with the same reason. The
NativeUiHelperRuntime parser-plain-throw baseline entry is removed.

* refactor(verify): keep process-lifecycle owners out of the parser plain-throw guard (#11035)

* refactor(verify): keep process-lifecycle owners out of the parser plain-throw guard

JadxWorkspaceRoot and PwntoolsDecoder sit in parser folders but own a
private helper process; their remaining plain throws report the helper's
startup, handshake and cleanup outcomes, not parse faults. The guard now
names them as process-lifecycle owners and leaves them out, so their
five baseline entries drop without inventing parse errors for process
failures.

* refactor(parsers): report the remaining artifact, il2cpp, model and domain defects through invariantViolation (#11036)

* refactor(parsers): report the remaining artifact, il2cpp, model and domain defects through invariantViolation

Nine plain Error, TypeError and RangeError throws in parser folders
reported broken internal assumptions or caller contracts (an
uninitialized ZIP or DMG reader, a missing scan result, a non-byte
stream chunk, an invalid traversal or marshal limit, a header count or
linking fact the reader itself should have produced, a misordered
Safetensors budget, an append after fingerprinting). None is an input
fault, and no catch site depends on their class. They now throw
invariantViolation with the same messages, and their parser-plain-throw
baseline entries drop.

* refactor(evidence): refuse an earlier Evidence format through ParseFailure (#11037)

* refactor(evidence): refuse an earlier Evidence format through ParseFailure

UnsupportedEvidenceFormatError restated the ParseFailure algebra as its
own TypeError subclass. The format owner now throws unsupportedInput for
the evidence-bundle format at the evidence_format field and exports the
predicate its consumers use. The bundle reader's unsupported-format kind
and message are unchanged. The snapshot reader surfaced only TypeError
messages, so it now also surfaces the format refusal and keeps its
recreate guidance; a boundary test pins that.

* refactor(native): report Mach-O reader and inspection defects through invariantViolation (#11042)

The Mach-O inspection plan reads the lipo, nm and dyld_info captures it
just ran, the dispatch metadata reader is called only for Mach-O
executables, and the command-name reader takes limits its callers
derive. A missing capture, a non-Mach-O target or a malformed limit is a
REA defect, not an input fault, so these six sites throw
invariantViolation with their existing messages instead of TypeError.
No catch site depends on their class. Their parser-plain-throw baseline
entries drop.

* fix(artifacts): join the Interface Builder cleanup failure to a catalog defect

When catalog work failed while the concurrent Interface Builder reader
failed to close, analyzeAppleAssetCatalogs built the primary through
translateArtifactFailure before joining cleanup. That mapper now rethrows
an InternalInvariantError, so a defect skipped the join and the reader's
retained resources were lost. The defect now becomes the artifact graph
provider's adapter failure at that site and joins the cleanup failure as
before.
2026-11-15 19:35:22 +08:00

723 lines
25 KiB
TypeScript

import { InvalidResidualUnknownGraphError } from "./residualUnknownGraphError.js";
import { withEvidenceSubjectDeclaration } from "./evidenceSubject.js";
import { digestSchema } from "./digests.js";
import { EvidenceIntegrityError } from "./evidenceErrors.js";
import {
AnalysisInputError,
type AnalysisInputIssue,
} from "./analysisErrorCore.js";
import { err, ok, type Result } from "./result.js";
import { describeValidationFailure } from "./validationFailure.js";
import { equalJsonText } from "./jsonSerialization.js";
import { z } from "zod";
import canonicalize from "canonicalize";
import { compareUnicodeCodePoints } from "./unicodeCodePointOrder.js";
import {
evidenceSchema,
immutableEvidence,
parseEvidence,
providerSchema,
type Evidence,
} from "./evidence.js";
import {
residualUnknownSchema,
type ResidualUnknown,
} from "./residualUnknown.js";
import { freezeJsonSnapshot } from "./immutableJson.js";
import {
admitEvidenceBundleFormat,
EVIDENCE_FORMAT_REVISION,
evidenceFormatSchema,
RECREATE_EVIDENCE_GUIDANCE,
isUnsupportedEvidenceFormat,
type UnsupportedEvidenceFormat,
} from "./evidenceFormat.js";
const artifactManifestBaseSchema = z.strictObject({
digest: z.strictObject({ sha256: digestSchema }),
});
const artifactManifestSchema = withEvidenceSubjectDeclaration(
artifactManifestBaseSchema,
);
const providerManifestSchema = providerSchema;
const environmentManifestSchema = evidenceSchema.shape.environment.unwrap();
const scenarioManifestSchema = z.strictObject({
evidence_id: evidenceSchema.shape.evidence_id,
operation: z.string().min(1),
authority: z.literal("controlled-replay"),
});
const captureManifestSchema = z.strictObject({
evidence_id: evidenceSchema.shape.evidence_id,
predicate_type: z.string().min(1),
});
export const evidenceBundleSchema = z.strictObject({
evidence_format: evidenceFormatSchema,
artifacts: z.array(artifactManifestSchema),
providers: z.array(providerManifestSchema),
environments: z.array(environmentManifestSchema),
scenarios: z.array(scenarioManifestSchema),
captures: z.array(captureManifestSchema),
unknowns: z.array(residualUnknownSchema),
records: z.array(evidenceSchema),
});
export type EvidenceBundle = z.infer<typeof evidenceBundleSchema>;
const immutableBundles = new WeakMap<object, EvidenceBundle>();
/** Recognize an authenticated sealed bundle without traversing or copying it. */
export const isImmutableEvidenceBundle = (
input: unknown,
): input is EvidenceBundle =>
typeof input === "object" && input !== null && immutableBundles.has(input);
/** Caller input has valid shape but is not in authenticated canonical form. */
class NonCanonicalEvidenceBundleError extends TypeError {
/** The top-level sections whose content differs from canonical form. */
constructor(readonly sections: readonly string[]) {
super(`Evidence bundle sections are not canonical: ${sections.join(", ")}`);
this.name = "NonCanonicalEvidenceBundleError";
}
}
/** Caller input lists the same Evidence record more than once. */
class DuplicateEvidenceRecordError extends TypeError {
constructor() {
super("Evidence bundle contains duplicate record IDs");
this.name = "DuplicateEvidenceRecordError";
}
}
/** Build and authenticate a sealed bundle while reusing immutable Evidence records. */
export const createImmutableEvidenceBundle = (
records: readonly Evidence[],
unknowns: readonly ResidualUnknown[] = [],
): EvidenceBundle => {
const checkedRecords = records.map(immutableEvidence);
if (
new Set(checkedRecords.map(({ evidence_id }) => evidence_id)).size !==
checkedRecords.length
)
throw new DuplicateEvidenceRecordError();
const checkedUnknowns = unknowns.map((unknown) =>
residualUnknownSchema.parse(unknown),
);
validateUnknownGraph(checkedUnknowns, checkedRecords);
const bundle = freezeJsonSnapshot(
createEvidenceBundle(checkedRecords, checkedUnknowns),
);
immutableBundles.set(bundle, bundle);
return bundle;
};
/** Project records into a deterministic bundle whose order has no semantics. */
export const createEvidenceBundle = (
records: readonly Evidence[],
unknowns: readonly ResidualUnknown[] = [],
): EvidenceBundle => {
const sortedRecords = [...records].sort((left, right) =>
compareUnicodeCodePoints(left.evidence_id, right.evidence_id),
);
return {
evidence_format: EVIDENCE_FORMAT_REVISION,
artifacts: uniqueSorted(
sortedRecords.flatMap(({ subject }) =>
subject === null
? []
: [
artifactManifestSchema.parse({
digest: subject.digest,
format: subject.format,
architecture: subject.architecture,
}),
],
),
),
providers: uniqueSorted(sortedRecords.map(({ provider }) => provider)),
environments: uniqueSorted(
sortedRecords.flatMap(({ environment }) =>
environment === null ? [] : [environment],
),
),
scenarios: sortedRecords.flatMap((evidence) =>
evidence.authority === "controlled-replay"
? [
{
evidence_id: evidence.evidence_id,
operation: evidence.operation,
authority: evidence.authority,
},
]
: [],
),
captures: sortedRecords.flatMap((evidence) =>
evidence.predicate_type === "rea.process-capture"
? [
{
evidence_id: evidence.evidence_id,
predicate_type: evidence.predicate_type,
},
]
: [],
),
unknowns: [...unknowns].sort(
(left, right) =>
compareUnicodeCodePoints(left.unknown_id, right.unknown_id) ||
left.revision - right.revision,
),
records: sortedRecords,
};
};
/** Retain target records, their linked sources, and eligible complete unknown histories. */
export const evidenceBundleForTarget = (
bundle: EvidenceBundle,
sha256: string,
): EvidenceBundle => {
const recordsById = new Map(
bundle.records.map((record) => [record.evidence_id, record]),
);
const histories = new Map<string, ResidualUnknown[]>();
for (const unknown of bundle.unknowns) {
const history = histories.get(unknown.unknown_id) ?? [];
history.push(unknown);
histories.set(unknown.unknown_id, history);
}
const retained = new Set<string>();
const dependents = new Map<string, Set<string>>();
const relationships = new Map<string, Set<string>>();
for (const [id, history] of histories) {
const eligible = history.every((unknown) => {
if (unknown.scope_digest !== sha256) return false;
const mutationEvidenceIds = new Set(unknown.mutation_evidence_ids);
return referencedEvidenceIds(unknown).every((evidenceId) => {
const record = recordsById.get(evidenceId);
// Mutation subjects record the target active at the time of an edit,
// which need not be the question's immutable investigation scope.
return (
record?.subject?.digest.sha256 === sha256 ||
(mutationEvidenceIds.has(evidenceId) &&
record?.predicate_type === "rea.residual-unknown-mutation")
);
});
});
if (!eligible) continue;
retained.add(id);
const relatedIds = new Set(
history.flatMap((unknown) =>
unknown.relationships.map(({ unknown_id }) => unknown_id),
),
);
relationships.set(id, relatedIds);
for (const relatedId of relatedIds) {
const references = dependents.get(relatedId) ?? new Set<string>();
references.add(id);
dependents.set(relatedId, references);
}
}
const pending: string[] = [];
for (const [id, relatedIds] of relationships)
if ([...relatedIds].some((relatedId) => !retained.has(relatedId)))
pending.push(id);
for (let index = 0; index < pending.length; index += 1) {
const id = pending[index];
if (id === undefined || !retained.delete(id)) continue;
for (const dependent of dependents.get(id) ?? []) pending.push(dependent);
}
const unknowns = bundle.unknowns.filter((unknown) =>
retained.has(unknown.unknown_id),
);
const mutationIds = new Set(
unknowns.flatMap(({ mutation_evidence_ids: ids }) => ids),
);
const selectedIds = new Set(
bundle.records
.filter(
(record) =>
record.subject?.digest.sha256 === sha256 ||
mutationIds.has(record.evidence_id),
)
.map((record) => record.evidence_id),
);
// Source Evidence may have no subject or describe a different artifact.
// Follow only explicit links from selected records, retaining missing links
// as missing rather than inventing or importing unrelated observations.
const pendingEvidence = [...selectedIds];
for (let index = 0; index < pendingEvidence.length; index += 1) {
const record = recordsById.get(pendingEvidence[index] ?? "");
for (const id of record?.evidence_links ?? []) {
if (!selectedIds.has(id) && recordsById.has(id)) {
selectedIds.add(id);
pendingEvidence.push(id);
}
}
}
return createEvidenceBundle(
bundle.records.filter((record) => selectedIds.has(record.evidence_id)),
unknowns,
);
};
export const referencedEvidenceIds = (
unknown: ResidualUnknown,
): readonly string[] => [
...unknown.supporting_evidence_ids,
...unknown.contradicting_evidence_ids,
...unknown.mutation_evidence_ids,
...(unknown.resolution?.evidence_ids ?? []),
];
type EvidenceBundleValidationFailure =
| UnsupportedEvidenceFormat
| z.ZodError
| DuplicateEvidenceRecordError
| InvalidResidualUnknownGraphError
| NonCanonicalEvidenceBundleError;
/** Expected source rejection, including authenticated standalone Evidence. */
export type EvidenceBundleFailure = {
readonly kind: "single-record" | "unsupported-format" | "invalid-bundle";
readonly message: string;
readonly cause: EvidenceBundleValidationFailure;
};
const describeEvidenceBundleFailure = (
input: unknown,
cause: EvidenceBundleValidationFailure,
): EvidenceBundleFailure => {
try {
const record = parseEvidence(input);
return {
kind: "single-record",
cause,
message: `Expected an Evidence bundle with records and manifest arrays, but this JSON is one Evidence record (${record.evidence_id}). Export a session bundle with the MCP export_evidence_bundle tool and supply that file.`,
};
} catch (recordFailure: unknown) {
if (!(recordFailure instanceof z.ZodError)) throw recordFailure;
// The format owner decides earlier bundles once; its message carries the
// recreate guidance instead of per-field schema failures.
if (isUnsupportedEvidenceFormat(cause))
return { kind: "unsupported-format", cause, message: cause.message };
return {
kind: "invalid-bundle",
cause,
message:
cause instanceof z.ZodError
? `Evidence bundle does not match the bundle schema ${describeValidationFailure(cause)}. Supply an unmodified bundle produced by this REA release. ${RECREATE_EVIDENCE_GUIDANCE}`
: `Evidence bundle validation failed: ${describeValidationFailure(cause)}. Recreate or re-export the bundle, then try again.`,
};
}
};
/** Parse records, verify semantic IDs, and reject inconsistent manifests. */
export const parseEvidenceBundle = (input: unknown): EvidenceBundle => {
return parseBundle(input, false);
};
/** Authenticate and seal snapshot-owned payloads, throwing validation failures. */
export const parseImmutableEvidenceBundle = (input: unknown): EvidenceBundle =>
parseBundle(input, true);
/** Read expected source failures as facts; implementation failures still throw. */
export const safeParseEvidenceBundle = (
input: unknown,
): Result<EvidenceBundle, EvidenceBundleFailure> => readBundle(input, false);
/** Authenticate and seal file-owned payloads once for downstream zero-copy reuse. */
export const safeParseImmutableEvidenceBundle = (
input: unknown,
): Result<EvidenceBundle, EvidenceBundleFailure> => readBundle(input, true);
const parseBundle = (input: unknown, seal: boolean): EvidenceBundle => {
if (typeof input === "object" && input !== null) {
const owned = immutableBundles.get(input);
if (owned !== undefined) return owned;
}
admitEvidenceBundleFormat(input);
return authenticateBundle(evidenceBundleSchema.parse(input), seal);
};
/**
* Refusal of one standalone Evidence record where a bundle is required; its
* `detected_kind` matches the file reader's `wrong-kind` fact.
*/
export const singleEvidenceRecordIssue = (
path: readonly (string | number)[],
message: string,
): AnalysisInputIssue => ({
path,
reason: "invalid_value",
message,
observed: { detected_kind: "evidence-record" },
});
/** Read a source bundle while preserving unexpected implementation failures. */
export const readEvidenceBundle = (
input: unknown,
context: {
readonly operation: string;
readonly path: readonly (string | number)[];
},
): Result<EvidenceBundle, AnalysisInputError | EvidenceIntegrityError> => {
const parsed = safeParseEvidenceBundle(input);
if (parsed.ok) return parsed;
const { cause, kind, message } = parsed.error;
if (kind === "single-record")
return err(
new AnalysisInputError(
context.operation,
{ cause, userMessage: message, remediationAction: message },
[singleEvidenceRecordIssue(context.path, message)],
),
);
return err(
new EvidenceIntegrityError(cause.message, {
cause,
userMessage: message,
}),
);
};
const readBundle = (
input: unknown,
seal: boolean,
): Result<EvidenceBundle, EvidenceBundleFailure> => {
try {
return ok(
seal ? parseImmutableEvidenceBundle(input) : parseEvidenceBundle(input),
);
} catch (cause: unknown) {
if (
!isUnsupportedEvidenceFormat(cause) &&
!(cause instanceof z.ZodError) &&
!(cause instanceof DuplicateEvidenceRecordError) &&
!(cause instanceof InvalidResidualUnknownGraphError) &&
!(cause instanceof NonCanonicalEvidenceBundleError)
)
throw cause;
return err(describeEvidenceBundleFailure(input, cause));
}
};
/** Authenticate evidence and bundle invariants after the bundle shape is parsed. */
export const authenticateParsedEvidenceBundle = (
parsed: EvidenceBundle,
): EvidenceBundle => authenticateBundle(parsed, false);
const authenticateBundle = (
parsed: EvidenceBundle,
seal: boolean,
): EvidenceBundle => {
const recordIds = parsed.records.map(({ evidence_id: id }) => id);
if (new Set(recordIds).size !== recordIds.length)
throw new DuplicateEvidenceRecordError();
validateUnknownGraph(parsed.unknowns, parsed.records);
const canonical = createEvidenceBundle(
parsed.records.map((record, index) => {
try {
if (!seal) return parseEvidence(record);
// Schema parsing gave this boundary exclusive ownership. Register only
// validated payloads before authenticating the complete record envelope.
record.normalized_result = freezeJsonSnapshot(record.normalized_result);
record.raw_result = freezeJsonSnapshot(record.raw_result);
return immutableEvidence(record);
} catch (cause: unknown) {
if (cause instanceof z.ZodError)
throw new z.ZodError(
cause.issues.map((issue) => ({
...issue,
path: ["records", index, ...issue.path],
})),
);
throw cause;
}
}),
parsed.unknowns,
);
if (!equalJsonText(parsed, canonical))
// Name only the sections that differ, so an unchanged section is not
// blamed for another section's ordering or content.
throw new NonCanonicalEvidenceBundleError(
(Object.keys(canonical) as (keyof EvidenceBundle)[]).filter(
(section) => !equalJsonText(parsed[section], canonical[section]),
),
);
if (seal) {
freezeJsonSnapshot(canonical);
immutableBundles.set(canonical, canonical);
}
return canonical;
};
const validateUnknownGraph = (
unknowns: readonly ResidualUnknown[],
records: readonly Evidence[],
): void => {
const evidenceById = new Map(
records.map((record) => [record.evidence_id, record]),
);
const histories = new Map<string, ResidualUnknown[]>();
for (const unknown of unknowns) {
const history = histories.get(unknown.unknown_id) ?? [];
history.push(unknown);
histories.set(unknown.unknown_id, history);
}
const unknownById = new Map<string, ResidualUnknown>();
for (const [id, unordered] of histories) {
const history = [...unordered].sort(
(left, right) => left.revision - right.revision,
);
for (const [index, revision] of history.entries()) {
if (revision.revision !== index + 1)
throw new InvalidResidualUnknownGraphError({
kind: "history_gap",
unknown_id: id,
});
if (
index > 0 &&
revision.previous_revision_digest !==
history[index - 1]?.revision_digest
)
throw new InvalidResidualUnknownGraphError({
kind: "revision_chain",
unknown_id: id,
});
}
const head = history.at(-1);
if (head === undefined)
throw new TypeError("Residual unknown revision history is empty");
unknownById.set(id, head);
}
for (const unknown of unknowns) {
for (const evidenceId of referencedEvidenceIds(unknown))
if (!evidenceById.has(evidenceId))
throw new InvalidResidualUnknownGraphError({
kind: "missing_evidence",
unknown_id: unknown.unknown_id,
evidence_id: evidenceId,
});
for (const relationship of unknown.relationships)
if (!unknownById.has(relationship.unknown_id))
throw new InvalidResidualUnknownGraphError({
kind: "missing_unknown",
unknown_id: unknown.unknown_id,
related_unknown_id: relationship.unknown_id,
});
if (unknown.resolution?.disposition === "verified")
validateVerifiedResolution(unknown, evidenceById);
}
rejectDependencyCycles(unknownById);
};
const validateVerifiedResolution = (
unknown: ResidualUnknown,
evidenceById: Pick<ReadonlyMap<string, Evidence>, "get">,
): void => {
if (unknown.contradicting_evidence_ids.length > 0)
throw new InvalidResidualUnknownGraphError({
kind: "contradicting_evidence",
unknown_id: unknown.unknown_id,
});
const qualifies = unknown.resolution?.evidence_ids.some((evidenceId) => {
const evidence = evidenceById.get(evidenceId);
return (
unknown.supporting_evidence_ids.includes(evidenceId) &&
evidence !== undefined &&
evidence.predicate_type !== "rea.residual-unknown-mutation" &&
evidenceQualifies(unknown, evidence)
);
});
if (qualifies !== true)
throw new InvalidResidualUnknownGraphError({
kind: "resolution_unproven",
unknown_id: unknown.unknown_id,
});
};
/**
* Validate one new residual-unknown revision against an already valid ledger.
* This keeps ordinary mutations proportional to the affected revision while
* full bundle imports continue to validate the complete graph.
*/
export const validateResidualUnknownAddition = (
unknown: ResidualUnknown,
evidenceById: Pick<ReadonlyMap<string, Evidence>, "get" | "has">,
currentHeads: ReadonlyMap<string, ResidualUnknown>,
): void => {
const current = currentHeads.get(unknown.unknown_id);
if (
current === undefined
? unknown.revision !== 1 || unknown.previous_revision_digest !== null
: unknown.revision !== current.revision + 1 ||
unknown.previous_revision_digest !== current.revision_digest
)
throw new InvalidResidualUnknownGraphError({
kind: "revision_chain",
unknown_id: unknown.unknown_id,
});
for (const evidenceId of referencedEvidenceIds(unknown))
if (!evidenceById.has(evidenceId))
throw new InvalidResidualUnknownGraphError({
kind: "missing_evidence",
unknown_id: unknown.unknown_id,
evidence_id: evidenceId,
});
for (const relationship of unknown.relationships)
if (
relationship.unknown_id !== unknown.unknown_id &&
!currentHeads.has(relationship.unknown_id)
)
throw new InvalidResidualUnknownGraphError({
kind: "missing_unknown",
unknown_id: unknown.unknown_id,
related_unknown_id: relationship.unknown_id,
});
if (unknown.resolution?.disposition === "verified")
validateVerifiedResolution(unknown, evidenceById);
// In a valid graph, no existing node can point to an absent ID. Since the
// schema rejects self-relations, a new node's outgoing edges cannot close a
// cycle; keep graph traversal for revisions of existing nodes only.
if (current !== undefined) {
const dependencies = unknown.relationships
.filter((relationship) => relationship.type === "depends-on")
.map(({ unknown_id }) => unknown_id);
if (
dependencies.length > 0 &&
reachesUnknown(dependencies, unknown.unknown_id, currentHeads, unknown)
)
throw new InvalidResidualUnknownGraphError({
kind: "dependency_cycle",
unknown_id: unknown.unknown_id,
});
}
};
const reachesUnknown = (
starts: readonly string[],
goal: string,
currentHeads: ReadonlyMap<string, ResidualUnknown>,
candidate: ResidualUnknown,
): boolean => {
const pending = [...starts];
const visited = new Set<string>();
while (pending.length > 0) {
const id = pending.pop();
if (id === undefined) break;
if (id === goal) return true;
if (visited.has(id)) continue;
visited.add(id);
const unknown =
id === candidate.unknown_id ? candidate : currentHeads.get(id);
if (unknown === undefined) continue;
for (const relationship of unknown.relationships)
if (relationship.type === "depends-on")
pending.push(relationship.unknown_id);
}
return false;
};
const evidenceQualifies = (
unknown: ResidualUnknown,
evidence: Evidence,
): boolean => {
if (
unknown.required_authority !== null &&
evidence.authority !== unknown.required_authority
)
return false;
const confidenceRank = { inferred: 1, derived: 2, observed: 3 } as const;
if (
confidenceRank[evidence.confidence] <
confidenceRank[unknown.required_confidence]
)
return false;
const requirement = unknown.required_environment;
if (requirement === null) return true;
if (evidence.environment === null) return false;
return (
(requirement.id === null || requirement.id === evidence.environment.id) &&
(requirement.platform === null ||
requirement.platform === evidence.environment.platform) &&
(requirement.architecture === null ||
requirement.architecture === evidence.environment.architecture) &&
(requirement.isolation === null ||
requirement.isolation === evidence.environment.isolation)
);
};
const rejectDependencyCycles = (
unknownById: ReadonlyMap<string, ResidualUnknown>,
): void => {
const visited = new Set<string>();
const active = new Set<string>();
const pending: {
readonly id: string;
readonly relationships: ResidualUnknown["relationships"];
nextRelationship: number;
}[] = [];
for (const root of unknownById.keys()) {
if (visited.has(root)) continue;
const rootUnknown = unknownById.get(root);
if (rootUnknown === undefined)
throw new TypeError("Residual unknown dependency graph is inconsistent");
active.add(root);
pending.push({
id: root,
relationships: rootUnknown.relationships,
nextRelationship: 0,
});
while (pending.length > 0) {
const frame = pending[pending.length - 1];
if (frame === undefined) break;
let descended = false;
while (frame.nextRelationship < frame.relationships.length) {
const relationship = frame.relationships[frame.nextRelationship];
frame.nextRelationship += 1;
if (relationship?.type !== "depends-on") continue;
const dependency = relationship.unknown_id;
if (active.has(dependency))
throw new InvalidResidualUnknownGraphError({
kind: "dependency_cycle",
unknown_id: dependency,
});
if (visited.has(dependency)) continue;
const unknown = unknownById.get(dependency);
if (unknown === undefined)
throw new TypeError(
"Residual unknown dependency graph is inconsistent",
);
active.add(dependency);
pending.push({
id: dependency,
relationships: unknown.relationships,
nextRelationship: 0,
});
descended = true;
break;
}
if (descended) continue;
pending.pop();
active.delete(frame.id);
visited.add(frame.id);
}
}
};
/** Encode a validated bundle as byte-stable RFC 8785 canonical JSON. */
export const serializeEvidenceBundle = (bundle: EvidenceBundle): string => {
const serialized = canonicalize(parseEvidenceBundle(bundle));
if (serialized === undefined)
throw new TypeError("Evidence bundle canonicalization failed");
return serialized;
};
const uniqueSorted = <Value>(values: readonly Value[]): Value[] => {
const unique = new Map<string, Value>();
for (const value of values) unique.set(JSON.stringify(value), value);
return [...unique.entries()]
.sort(([left], [right]) => compareUnicodeCodePoints(left, right))
.map(([, value]) => value);
};