mirror of
https://github.com/morluto/rea.git
synced 2026-11-16 03:33:25 +00:00
* 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.
723 lines
25 KiB
TypeScript
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);
|
|
};
|