mirror of
https://github.com/morluto/rea.git
synced 2026-11-22 14:35:45 +00:00
trace_dylib_resolution Evidence named the slice the session happened to open, not what was traced. On Apple silicon, `rea trace-dylib-resolution /bin/ls --architecture x86_64` returned a subject selecting the arm64e slice (offset 65536, architecture "arm64") while its parameters and roots said x86_64. Whole-file traces of universal images and app bundle traces also carried that host slice. Root cause: the artifact provider built the execution without a subject, and bindExecutionTarget binds such an execution, like any subject that names the target's own bytes without a selection, to the open target's selection. A provider had no way to state that an observation covers the whole file. EvidenceSubjectTarget.selection now accepts null, meaning the observation selects nothing even though a session opened one slice. bindExecutionTarget already inherited a selection only when none was stated; its comment now says so. The trace states selection: null. This matches inspect-binary-hardening and the other whole-file inspectors, which already record no selection for a universal image. Validation (macOS arm64, Node 24.22.1): - New CLI boundary regression: a universal arm64 + x86_64 tool, traced whole and with --architecture x86_64, has a subject with no architecture or selection and the expected roots. Before this change the subject carried the opened slice. - dylibResolutionCli and dylibResolutionMcp: 44 passed, 2 skipped. - Suites that exercise subject binding (binarySession, analysisEvidenceAdapterParity, artifactMcp, bundleResourceRootCliMcp, appleBundleTraversalCoverage, AppBundleResourceRoot, ArtifactComparisonEvidence): 144 passed, 1 skipped. - evidence, BinarySession and ArtifactProvider unit tests: 186 passed. - Real /bin/ls trace with --architecture x86_64: subject selection and architecture null, roots [x86_64]. Format, typecheck, lint and architecture guards pass. Not changed: inspect-macho, inspect-signature and inspect-native-dispatch-metadata also record the opened slice for a universal image; whether each examines only that slice was not checked. Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
672 lines
24 KiB
TypeScript
672 lines
24 KiB
TypeScript
import {
|
|
admitEvidenceRecordFormat,
|
|
EVIDENCE_FORMAT_REVISION,
|
|
evidenceFormatSchema,
|
|
} from "./evidenceFormat.js";
|
|
import { isDeepStrictEqual } from "node:util";
|
|
import { basename } from "node:path";
|
|
import { z } from "zod";
|
|
|
|
import { withEvidenceSubjectDeclaration } from "./evidenceSubject.js";
|
|
|
|
import { digestCanonicalValue } from "./canonicalDigest.js";
|
|
import { canonicalJsonDigestSteps } from "./canonicalJsonDigestSteps.js";
|
|
import { nulFreeStringSchema } from "./localPath.js";
|
|
import {
|
|
binaryTargetIdentity,
|
|
fileTargetSelectionSchema,
|
|
nonFileTargetIdentitySchema,
|
|
sessionTargetIdentitySchema,
|
|
unknownTargetIdentitySchema,
|
|
type NonFileTargetIdentity,
|
|
sameTargetIdentity,
|
|
type FileTargetIdentity,
|
|
type FileTargetSelection,
|
|
type TargetIdentity,
|
|
} from "./targetIdentity.js";
|
|
|
|
import {
|
|
analysisProfileSchema,
|
|
type AnalysisProfileCommitment,
|
|
} from "./analysisProfile.js";
|
|
import type { BinaryArchitecture, BinaryTarget } from "./binaryTargetTypes.js";
|
|
import {
|
|
jsonObjectSchema,
|
|
jsonValueSchema,
|
|
jsonValueValidationIssue,
|
|
jsonValueValidationSteps,
|
|
type JsonValue,
|
|
} from "./jsonValue.js";
|
|
import {
|
|
freezeJsonSnapshot,
|
|
freezeOwnedJsonTreeSnapshot,
|
|
canBorrowParsedJsonSnapshot,
|
|
immutableJsonSnapshotMember,
|
|
isImmutableJsonSnapshot,
|
|
} from "./immutableJson.js";
|
|
import { digestSchema, prefixedDigestSchema } from "./../domain/digests.js";
|
|
import {
|
|
relationshipCoverageSchema,
|
|
type RelationshipCoverage,
|
|
} from "./relationshipCoverage.js";
|
|
|
|
/** Predicate shared by ordinary provider analysis observations. */
|
|
export const ANALYSIS_EVIDENCE_PREDICATE = "rea.analysis";
|
|
|
|
/** Provider identity schema shared by evidence-bearing persistence formats. */
|
|
export const providerSchema = z.strictObject({
|
|
id: z.string().min(1),
|
|
name: z.string().min(1),
|
|
version: z.string().nullable(),
|
|
});
|
|
/** Formats whose identity carries each selection kind. */
|
|
const SELECTION_FORMATS: Readonly<
|
|
Record<FileTargetSelection["kind"], readonly string[]>
|
|
> = {
|
|
"entry-point": ["raw-binary", "gamecube-dol"],
|
|
"esp-flash": ["esp-flash-image"],
|
|
"universal-slice": ["mach-o-universal"],
|
|
};
|
|
/** The file identity an Evidence subject commits to, with its format-owned declaration. */
|
|
const subjectIdentitySchema = withEvidenceSubjectDeclaration(
|
|
z.strictObject({
|
|
kind: z.literal("file"),
|
|
sha256: digestSchema,
|
|
selection: fileTargetSelectionSchema.nullable(),
|
|
}),
|
|
).superRefine((identity, context) => {
|
|
if (
|
|
identity.selection !== null &&
|
|
!SELECTION_FORMATS[identity.selection.kind].includes(identity.format)
|
|
)
|
|
context.addIssue({
|
|
code: "custom",
|
|
path: ["selection"],
|
|
message: `A ${identity.selection.kind} selection does not apply to format ${identity.format}`,
|
|
});
|
|
});
|
|
const fileSubjectSchema = z.strictObject({
|
|
/** The committed target identity; the remaining members are display facts. */
|
|
identity: subjectIdentitySchema,
|
|
name: z.string().min(1),
|
|
local_path: nulFreeStringSchema,
|
|
});
|
|
/** A debugger session whose launch file is validated like a file subject. */
|
|
const sessionSubjectIdentitySchema = sessionTargetIdentitySchema.extend({
|
|
target: z.union([subjectIdentitySchema, unknownTargetIdentitySchema]),
|
|
});
|
|
/** A subject that names no file (a URL, process, session, or unknown target) has no file display facts. */
|
|
const nonFileSubjectSchema = z.strictObject({
|
|
identity: z.union([
|
|
nonFileTargetIdentitySchema,
|
|
sessionSubjectIdentitySchema,
|
|
]),
|
|
name: z.null(),
|
|
local_path: z.null(),
|
|
});
|
|
const subjectSchema = z.union([fileSubjectSchema, nonFileSubjectSchema]);
|
|
/** The Evidence subject, for persistence formats that embed one. */
|
|
export const evidenceSubjectSchema = subjectSchema;
|
|
/** Source location attached to an evidence observation. */
|
|
/** Source-location schema shared by evidence-bearing persistence formats. */
|
|
export const evidenceLocationSchema = z.discriminatedUnion("kind", [
|
|
z.strictObject({ kind: z.literal("address"), address: z.string().min(1) }),
|
|
z.strictObject({
|
|
kind: z.literal("address-range"),
|
|
start: z.string().min(1),
|
|
end: z.string().min(1),
|
|
}),
|
|
z.strictObject({ kind: z.literal("artifact-path"), path: z.string().min(1) }),
|
|
z.strictObject({
|
|
kind: z.literal("file-offset"),
|
|
offset: z.int().min(0),
|
|
}),
|
|
z.strictObject({
|
|
kind: z.literal("file-offset-range"),
|
|
start: z.int().min(0),
|
|
end: z.int().min(0),
|
|
}),
|
|
]);
|
|
|
|
/** Source authority vocabulary owned by Evidence and reused by its consumers. */
|
|
export const evidenceAuthoritySchema = z.enum([
|
|
"shipped-artifact",
|
|
"controlled-replay",
|
|
"historical-reference",
|
|
"external-service",
|
|
"analyst-inference",
|
|
]);
|
|
|
|
const executionEnvironmentSchema = z.strictObject({
|
|
id: z.string().min(1),
|
|
platform: z.string().min(1),
|
|
architecture: z.string().min(1),
|
|
isolation: z.enum(["none", "process", "container", "virtual-machine"]),
|
|
});
|
|
const callerInputPathsSchema = z.record(
|
|
nulFreeStringSchema,
|
|
z.union([nulFreeStringSchema, z.array(nulFreeStringSchema)]),
|
|
);
|
|
/** Caller-selected auxiliary paths, retaining ordered repeated options. */
|
|
export type CallerInputPaths = Readonly<
|
|
Record<string, string | readonly string[]>
|
|
>;
|
|
|
|
const evidenceBaseSchema = z
|
|
.object({
|
|
evidence_id: prefixedDigestSchema("ev"),
|
|
/** Selects the reader; not part of the committed content. */
|
|
evidence_format: evidenceFormatSchema,
|
|
subject: subjectSchema,
|
|
provider: providerSchema,
|
|
analysis_profile: analysisProfileSchema.nullable(),
|
|
predicate_type: z.string().min(1),
|
|
operation: z.string().min(1),
|
|
parameters: jsonObjectSchema,
|
|
/** Verbatim selected path; present only when the request selected one directly. */
|
|
caller_input_path: nulFreeStringSchema
|
|
.exactOptional()
|
|
.describe("Verbatim direct-request path; not part of semantic identity."),
|
|
caller_input_paths: callerInputPathsSchema
|
|
.exactOptional()
|
|
.describe(
|
|
"Verbatim auxiliary input paths keyed by argument name; repeated selections retain their order. Caller assertions are outside semantic identity.",
|
|
),
|
|
raw_result: jsonValueSchema.nullable(),
|
|
normalized_result: jsonValueSchema,
|
|
confidence: z.enum(["observed", "derived", "inferred"]),
|
|
authority: evidenceAuthoritySchema,
|
|
environment: executionEnvironmentSchema.nullable(),
|
|
limitations: z.array(z.string()),
|
|
relationship_coverage: relationshipCoverageSchema.nullable(),
|
|
locations: z.array(evidenceLocationSchema),
|
|
evidence_links: z.array(prefixedDigestSchema("ev")),
|
|
})
|
|
.strict();
|
|
|
|
/** Require a reported analysis profile to identify the observation provider. */
|
|
export const validateAnalysisProfileProvider = (
|
|
evidence: Pick<
|
|
z.infer<typeof evidenceBaseSchema>,
|
|
"analysis_profile" | "provider"
|
|
>,
|
|
context: z.RefinementCtx,
|
|
): void => {
|
|
const profile = evidence.analysis_profile;
|
|
if (
|
|
profile !== null &&
|
|
(profile.provider.id !== evidence.provider.id ||
|
|
profile.provider.name !== evidence.provider.name ||
|
|
profile.provider.version !== evidence.provider.version)
|
|
)
|
|
context.addIssue({
|
|
code: "custom",
|
|
path: ["analysis_profile", "provider"],
|
|
message: "Analysis profile provider does not match Evidence provider",
|
|
});
|
|
};
|
|
|
|
/** Strict, provider-neutral record for one successful public observation. */
|
|
export const evidenceSchema = evidenceBaseSchema.superRefine(
|
|
validateAnalysisProfileProvider,
|
|
);
|
|
|
|
const authenticatedEvidenceSchema = evidenceSchema.superRefine(
|
|
(evidence, context) => {
|
|
const { evidence_id: evidenceId, ...withoutId } = evidence;
|
|
if (computeEvidenceId(withoutId) !== evidenceId)
|
|
context.addIssue({
|
|
code: "custom",
|
|
path: ["evidence_id"],
|
|
message: "Evidence semantic identifier does not match its record",
|
|
});
|
|
},
|
|
);
|
|
|
|
/** Complete observation whose normalized payload retains its operation-specific type. */
|
|
type EvidenceSchemaValue = z.infer<typeof evidenceSchema>;
|
|
export type Evidence<Result extends JsonValue = JsonValue> =
|
|
EvidenceSchemaValue & {
|
|
readonly normalized_result: Result;
|
|
};
|
|
const immutableEvidenceSnapshots = new WeakMap<object, Evidence>();
|
|
const immutableResultSchema = z
|
|
.custom<JsonValue>(isImmutableJsonSnapshot)
|
|
.superRefine((value, context) => {
|
|
const issue = jsonValueValidationIssue(value);
|
|
if (issue !== undefined)
|
|
context.addIssue({ code: "custom", message: issue });
|
|
});
|
|
export type EvidenceLocation = z.infer<typeof evidenceLocationSchema>;
|
|
|
|
/** Candidate local artifact identity validated by the Evidence subject schema. */
|
|
export interface EvidenceSubjectTarget {
|
|
readonly path: string;
|
|
readonly sha256: string;
|
|
readonly format: z.infer<typeof subjectIdentitySchema>["format"];
|
|
readonly architecture?: BinaryArchitecture;
|
|
/**
|
|
* What the observation selected inside the bytes. Null selects nothing: the
|
|
* observation covers the whole file even when a session opened one slice of
|
|
* it. Absent also selects nothing, except that a session binds a subject
|
|
* naming its open target's bytes to that target's selection.
|
|
*/
|
|
readonly selection?: FileTargetSelection | null;
|
|
/** Preserve an existing Evidence subject's display name when deriving observations. */
|
|
readonly name?: string;
|
|
}
|
|
|
|
/** What a producer names as an Evidence subject: a file target, or a non-file identity such as a URL or an explicit unknown. */
|
|
export type EvidenceSubjectInput =
|
|
| EvidenceSubjectTarget
|
|
| BinaryTarget
|
|
| NonFileTargetIdentity;
|
|
|
|
type FileEvidenceSubject = z.infer<typeof fileSubjectSchema>;
|
|
|
|
/** Whether a subject names a file; only a file subject has display facts. */
|
|
const isFileSubject = (
|
|
subject: Evidence["subject"] | undefined,
|
|
): subject is FileEvidenceSubject => subject?.identity.kind === "file";
|
|
|
|
/** Preserve the complete file subject when deriving a new Evidence observation. */
|
|
export const evidenceSubjectTarget = (
|
|
subject: Evidence["subject"] | undefined,
|
|
): EvidenceSubjectTarget | undefined =>
|
|
!isFileSubject(subject)
|
|
? undefined
|
|
: {
|
|
path: subject.local_path,
|
|
sha256: subject.identity.sha256,
|
|
format: subject.identity.format,
|
|
name: subject.name,
|
|
...(subject.identity.architecture === null
|
|
? {}
|
|
: { architecture: subject.identity.architecture }),
|
|
...(subject.identity.selection === null
|
|
? {}
|
|
: { selection: subject.identity.selection }),
|
|
};
|
|
|
|
/** Name the same subject in a derived observation: the file target, or the same non-file identity. */
|
|
export const evidenceSubjectInput = (
|
|
subject: Evidence["subject"],
|
|
): EvidenceSubjectInput =>
|
|
isFileSubject(subject)
|
|
? (evidenceSubjectTarget(subject) as EvidenceSubjectTarget)
|
|
: (subject.identity as NonFileTargetIdentity);
|
|
|
|
/** The one projection of a producer's subject input into its target identity. */
|
|
export const evidenceSubjectTargetIdentity = (
|
|
target: EvidenceSubjectTarget | BinaryTarget,
|
|
): FileTargetIdentity =>
|
|
"kind" in target
|
|
? binaryTargetIdentity(target)
|
|
: {
|
|
kind: "file",
|
|
sha256: target.sha256,
|
|
format: target.format,
|
|
architecture: target.architecture ?? null,
|
|
selection: target.selection ?? null,
|
|
};
|
|
|
|
/** Rebind a matching immutable artifact subject to the caller's selected path. */
|
|
export const rebindEvidenceSubjectTargetPath = (
|
|
subject: EvidenceSubjectTarget,
|
|
target: EvidenceSubjectTarget | BinaryTarget,
|
|
): EvidenceSubjectTarget =>
|
|
sameTargetIdentity(
|
|
evidenceSubjectTargetIdentity(subject),
|
|
evidenceSubjectTargetIdentity(target),
|
|
)
|
|
? { ...subject, path: target.path }
|
|
: subject;
|
|
|
|
/** The one builder of a persisted Evidence subject from a producer's target. */
|
|
export const evidenceSubject = (
|
|
target: EvidenceSubjectInput,
|
|
): Evidence["subject"] =>
|
|
subjectSchema.parse(
|
|
"path" in target
|
|
? {
|
|
identity: evidenceSubjectTargetIdentity(target),
|
|
name:
|
|
("name" in target ? target.name : undefined) ??
|
|
(basename(target.path) || "artifact"),
|
|
local_path: target.path,
|
|
}
|
|
: { identity: target, name: null, local_path: null },
|
|
);
|
|
|
|
/** The target identity an Evidence record commits to; absent only for a partial record. */
|
|
export const evidenceTargetIdentity = (evidence: {
|
|
readonly subject?: Evidence["subject"] | undefined;
|
|
}): TargetIdentity | null => evidence.subject?.identity ?? null;
|
|
|
|
/** The file identity an Evidence record names, when its subject is a file. */
|
|
export const evidenceFileTarget = (evidence: {
|
|
readonly subject?: Evidence["subject"] | undefined;
|
|
}): FileTargetIdentity | undefined => {
|
|
const identity = evidenceTargetIdentity(evidence);
|
|
return identity?.kind === "file" ? identity : undefined;
|
|
};
|
|
|
|
/** Display facts beside the subject identity; never part of the Evidence ID. */
|
|
export const evidenceSubjectDisplay = (evidence: {
|
|
readonly subject?: Evidence["subject"] | undefined;
|
|
}): { readonly name: string; readonly local_path: string } | undefined => {
|
|
const subject = evidence.subject;
|
|
return isFileSubject(subject)
|
|
? { name: subject.name, local_path: subject.local_path }
|
|
: undefined;
|
|
};
|
|
|
|
export type EvidenceAuthority = z.infer<typeof evidenceAuthoritySchema>;
|
|
type ExecutionEnvironment = z.infer<typeof executionEnvironmentSchema>;
|
|
|
|
export type EvidenceProvider = Readonly<z.output<typeof providerSchema>>;
|
|
|
|
/** Payloads admitted and snapshotted by the ordinary Evidence constructor. */
|
|
export interface EvidenceObservationInput {
|
|
readonly predicateType?: string;
|
|
readonly operation: string;
|
|
readonly parameters: unknown;
|
|
readonly result: unknown;
|
|
readonly analysisProfile?: AnalysisProfileCommitment;
|
|
readonly rawResult?: unknown;
|
|
readonly confidence?: "observed" | "derived" | "inferred";
|
|
readonly authority?: EvidenceAuthority;
|
|
readonly environment?: ExecutionEnvironment | null;
|
|
readonly limitations?: readonly string[];
|
|
readonly relationshipCoverage?: RelationshipCoverage;
|
|
readonly locations?: readonly EvidenceLocation[];
|
|
readonly evidenceLinks?: readonly string[];
|
|
}
|
|
|
|
/** Producer facts that already promise JSON, including cooperative Evidence input. */
|
|
export interface EvidenceObservation extends EvidenceObservationInput {
|
|
readonly parameters: Readonly<Record<string, JsonValue>>;
|
|
readonly result: JsonValue;
|
|
readonly rawResult?: JsonValue;
|
|
}
|
|
|
|
type EvidenceWithoutId = Omit<EvidenceSchemaValue, "evidence_id">;
|
|
|
|
/** Content committed by an Evidence ID, excluding local request/display metadata. */
|
|
export const evidenceSemanticContent = (
|
|
evidence: EvidenceWithoutId,
|
|
): Record<string, JsonValue> => ({
|
|
subject: evidence.subject.identity,
|
|
provider: evidence.provider,
|
|
analysis_profile: evidence.analysis_profile,
|
|
predicate_type: evidence.predicate_type,
|
|
operation: evidence.operation,
|
|
parameters: evidence.parameters,
|
|
raw_result: evidence.raw_result,
|
|
normalized_result: evidence.normalized_result,
|
|
confidence: evidence.confidence,
|
|
authority: evidence.authority,
|
|
environment: evidence.environment,
|
|
limitations: evidence.limitations,
|
|
relationship_coverage: evidence.relationship_coverage,
|
|
locations: evidence.locations,
|
|
evidence_links: evidence.evidence_links,
|
|
});
|
|
|
|
/** Hash semantic content, including raw results and excluding local metadata. */
|
|
const computeEvidenceId = (evidence: EvidenceWithoutId): string =>
|
|
`ev_${digestCanonicalValue(evidenceSemanticContent(evidence), "Evidence")}`;
|
|
|
|
/** Parse evidence and reject a syntactically valid but tampered semantic ID. */
|
|
export const parseEvidence = (input: unknown): Evidence => {
|
|
const immutable =
|
|
typeof input === "object" && input !== null
|
|
? immutableEvidenceSnapshots.get(input)
|
|
: undefined;
|
|
if (immutable !== undefined) return immutable;
|
|
admitEvidenceRecordFormat(input);
|
|
return authenticatedEvidenceSchema.parse(input);
|
|
};
|
|
|
|
/** Evidence owns all presentation metadata excluded from its semantic identity. */
|
|
export const evidenceDisplayMetadataAgree = (
|
|
left: Evidence,
|
|
right: Evidence,
|
|
): boolean =>
|
|
left.subject?.name === right.subject?.name &&
|
|
left.subject?.local_path === right.subject?.local_path &&
|
|
left.caller_input_path === right.caller_input_path &&
|
|
isDeepStrictEqual(left.caller_input_paths, right.caller_input_paths);
|
|
|
|
/** Authenticate and seal a ledger-owned snapshot; external mutable values are copied first. */
|
|
export const immutableEvidence = (input: unknown): Evidence => {
|
|
const parsed = parseEvidence(input);
|
|
return rememberImmutableEvidence(
|
|
canBorrowParsedJsonSnapshot(input, parsed) ? input : parsed,
|
|
);
|
|
};
|
|
|
|
/** Rebind display path metadata when an authenticated record names this target. */
|
|
export const rebindEvidenceToTargetPath = (
|
|
evidence: Evidence,
|
|
target: EvidenceSubjectTarget,
|
|
): Evidence => {
|
|
const subject = evidence.subject;
|
|
if (!isFileSubject(subject)) return evidence;
|
|
if (
|
|
!sameTargetIdentity(subject.identity, evidenceSubjectTargetIdentity(target))
|
|
)
|
|
return evidence;
|
|
if (
|
|
target.path === subject.local_path &&
|
|
(target.name === undefined || target.name === subject.name)
|
|
)
|
|
return evidence;
|
|
const reboundSubject = subjectSchema.parse({
|
|
...subject,
|
|
name: target.name ?? (basename(target.path) || "artifact"),
|
|
local_path: target.path,
|
|
});
|
|
const reboundEvidence = { ...evidence, subject: reboundSubject };
|
|
if (!isImmutableEvidence(evidence)) return immutableEvidence(reboundEvidence);
|
|
|
|
// The original authenticated Evidence owns immutable payloads. Only the
|
|
// small display subject and envelope are new, so preserve those payloads
|
|
// without reparsing a potentially large analysis result.
|
|
return rememberReboundEvidence(evidence, reboundEvidence);
|
|
};
|
|
|
|
/** Bind the exact selected request path without changing semantic identity or stored history. */
|
|
export const withEvidenceCallerInputPath = (
|
|
evidence: Evidence,
|
|
rawPath: string | undefined,
|
|
additionalPaths?: CallerInputPaths,
|
|
): Evidence => {
|
|
const callerInputPath =
|
|
rawPath === undefined ? undefined : nulFreeStringSchema.parse(rawPath);
|
|
const owned = immutableEvidence(evidence);
|
|
const paths =
|
|
additionalPaths === undefined
|
|
? undefined
|
|
: callerInputPathsSchema.parse(additionalPaths);
|
|
const samePaths =
|
|
paths === undefined || isDeepStrictEqual(owned.caller_input_paths, paths);
|
|
if (
|
|
(callerInputPath === undefined ||
|
|
owned.caller_input_path === callerInputPath) &&
|
|
samePaths
|
|
)
|
|
return owned;
|
|
// The authenticated source owns its immutable payloads. Only this small
|
|
// envelope changes, so replay does not copy a document-sized result.
|
|
const rebound = {
|
|
...owned,
|
|
...(callerInputPath === undefined
|
|
? {}
|
|
: { caller_input_path: callerInputPath }),
|
|
...(paths === undefined ? {} : { caller_input_paths: paths }),
|
|
};
|
|
return rememberReboundEvidence(owned, rebound);
|
|
};
|
|
|
|
/** Carry the source's sealing proof before sealing only the changed envelope. */
|
|
const rememberReboundEvidence = (
|
|
source: Evidence,
|
|
rebound: Evidence,
|
|
): Evidence => {
|
|
// Each own member belongs to an authenticated immutable source. Register
|
|
// these shared roots so sealing the envelope never walks their payloads.
|
|
for (const key of Object.keys(source))
|
|
immutableJsonSnapshotMember(source, key);
|
|
return rememberImmutableEvidence(rebound);
|
|
};
|
|
|
|
/** Recognize authenticated Evidence whose complete reachable JSON data is immutable. */
|
|
export const isImmutableEvidence = (evidence: Evidence): boolean =>
|
|
immutableEvidenceSnapshots.has(evidence);
|
|
|
|
const rememberImmutableEvidence = (evidence: Evidence): Evidence => {
|
|
freezeJsonSnapshot(evidence);
|
|
immutableEvidenceSnapshots.set(evidence, evidence);
|
|
return evidence;
|
|
};
|
|
|
|
/** Ownership policy for the freshly parsed Evidence snapshot. */
|
|
export interface EvidenceCreationOptions {
|
|
readonly immutable?: boolean;
|
|
/** Selected spelling is recorded only when this target matches the subject. */
|
|
readonly callerTarget?: BinaryTarget | null | undefined;
|
|
}
|
|
|
|
/** Admit payloads into deterministic Evidence bound to an immutable artifact subject. */
|
|
export const createEvidence = (
|
|
target: EvidenceSubjectInput,
|
|
provider: EvidenceProvider,
|
|
observation: EvidenceObservationInput,
|
|
options?: EvidenceCreationOptions,
|
|
): Evidence => {
|
|
const { normalized, sharedResult } = normalizeEvidenceObservation(
|
|
target,
|
|
provider,
|
|
observation,
|
|
options?.callerTarget,
|
|
);
|
|
const evidence = {
|
|
...normalized,
|
|
evidence_id: computeEvidenceId(normalized),
|
|
};
|
|
// Seal this already parsed, exclusively owned snapshot without authenticating
|
|
// or copying its payload again, including later partial-error delivery.
|
|
if (sharedResult || options?.immutable === true) {
|
|
// The normalizer's JSON parser clones mutable payloads into trees and only
|
|
// borrows previously sealed roots. No graph-sized sealing scratch is needed.
|
|
freezeOwnedJsonTreeSnapshot(evidence);
|
|
immutableEvidenceSnapshots.set(evidence, evidence);
|
|
}
|
|
return evidence;
|
|
};
|
|
|
|
/** Create Evidence from owned immutable JSON while exposing cooperative computation steps. */
|
|
export function* createImmutableEvidenceSteps(
|
|
target: EvidenceSubjectInput,
|
|
provider: EvidenceProvider,
|
|
observation: EvidenceObservation,
|
|
): Generator<void, Evidence> {
|
|
if (!isImmutableJsonSnapshot(observation.result))
|
|
throw new TypeError(
|
|
"Cooperative Evidence requires an authenticated immutable result",
|
|
);
|
|
// The envelope parser below retains its usual diagnostics, using the completed
|
|
// immutable validation rather than traversing the payload synchronously again.
|
|
yield* jsonValueValidationSteps(observation.result);
|
|
const { normalized } = normalizeEvidenceObservation(
|
|
target,
|
|
provider,
|
|
observation,
|
|
);
|
|
const digest = yield* canonicalJsonDigestSteps(
|
|
evidenceSemanticContent(normalized),
|
|
);
|
|
return rememberImmutableEvidence({
|
|
...normalized,
|
|
evidence_id: `ev_${digest}`,
|
|
});
|
|
}
|
|
|
|
/** Borrow input collections for admission. */
|
|
export const evidenceEnvelopeForAdmission = (
|
|
target: EvidenceSubjectInput,
|
|
provider: EvidenceProvider,
|
|
observation: EvidenceObservationInput,
|
|
callerTarget?: EvidenceCreationOptions["callerTarget"],
|
|
) => {
|
|
const subject = evidenceSubject(target);
|
|
const callerInputPath =
|
|
callerTarget?.callerInputPath !== undefined &&
|
|
isFileSubject(subject) &&
|
|
subject.local_path === callerTarget.path &&
|
|
sameTargetIdentity(subject.identity, binaryTargetIdentity(callerTarget))
|
|
? callerTarget.callerInputPath
|
|
: undefined;
|
|
return {
|
|
...(callerInputPath === undefined
|
|
? {}
|
|
: { caller_input_path: callerInputPath }),
|
|
evidence_id: `ev_${"0".repeat(64)}`,
|
|
evidence_format: EVIDENCE_FORMAT_REVISION,
|
|
subject,
|
|
provider: {
|
|
id: provider.id,
|
|
name: provider.name,
|
|
version: provider.version,
|
|
},
|
|
analysis_profile: observation.analysisProfile ?? null,
|
|
predicate_type: observation.predicateType ?? ANALYSIS_EVIDENCE_PREDICATE,
|
|
operation: observation.operation,
|
|
parameters: observation.parameters,
|
|
raw_result: observation.rawResult ?? null,
|
|
normalized_result: observation.result,
|
|
confidence: observation.confidence ?? "observed",
|
|
// Only a subject that names an identified target can support shipment
|
|
// authority; an unknown target names no artifact and claims none.
|
|
authority:
|
|
observation.authority ??
|
|
(subject.identity.kind === "unknown"
|
|
? "analyst-inference"
|
|
: "shipped-artifact"),
|
|
environment: observation.environment ?? null,
|
|
limitations: observation.limitations ?? [],
|
|
...(observation.relationshipCoverage === undefined
|
|
? { relationship_coverage: null }
|
|
: { relationship_coverage: observation.relationshipCoverage }),
|
|
locations: observation.locations ?? [],
|
|
evidence_links: observation.evidenceLinks ?? [],
|
|
};
|
|
};
|
|
|
|
const normalizeEvidenceObservation = (
|
|
target: EvidenceSubjectInput,
|
|
provider: EvidenceProvider,
|
|
observation: EvidenceObservationInput,
|
|
callerTarget?: EvidenceCreationOptions["callerTarget"],
|
|
) => {
|
|
const envelope = evidenceEnvelopeForAdmission(
|
|
target,
|
|
provider,
|
|
observation,
|
|
callerTarget,
|
|
);
|
|
const sharedResult =
|
|
typeof observation.result === "object" &&
|
|
observation.result !== null &&
|
|
isImmutableJsonSnapshot(observation.result);
|
|
const selectedSchema = sharedResult
|
|
? evidenceSchema.safeExtend({ normalized_result: immutableResultSchema })
|
|
: evidenceSchema;
|
|
const normalized = selectedSchema.parse(envelope);
|
|
// The envelope has already been parsed into an independent snapshot. Only
|
|
// its derived identifier changes here; parsing again clones the full payload
|
|
// and recomputes the same digest while the previous snapshot is still live.
|
|
return { normalized, sharedResult };
|
|
};
|