rea-agents 6.0.0 → 6.2.0

package/dist/domain/process/processCaptureParsing.js

@@ -1,5 +1,4 @@
 import { processCaptureSchema, } from "./processCapture.js";
-import { z } from "zod";
 const verifiedCaptures = new WeakSet();
 const isVerifiedCapture = (capture) => verifiedCaptures.has(capture);
 const attachProof = (capture) => {
@@ -8,41 +7,9 @@ const attachProof = (capture) => {
         return capture;
     throw new TypeError("Process Capture proof ownership failed");
 };
-const recordSchema = z.record(z.string(), z.unknown());
-const LEGACY_EXECUTABLE_IDENTITY_REASON = "Legacy v3 capture did not distinguish selected and launch executable digests";
-const migrateLegacyV3Capture = (input) => {
-    const capture = recordSchema.safeParse(input);
-    if (!capture.success)
-        return input;
-    const manifest = recordSchema.safeParse(capture.data.manifest);
-    if (!manifest.success)
-        return input;
-    if (manifest.data.provider_version !== "3" ||
-        "selected_executable_sha256" in manifest.data ||
-        "executable_identity" in manifest.data ||
-        "legacy_executable_sha256" in manifest.data)
-        return input;
-    const { executable_sha256 } = manifest.data;
-    if (typeof executable_sha256 !== "string" ||
-        !/^[a-f0-9]{64}$/u.test(executable_sha256))
-        return input;
-    return {
-        ...capture.data,
-        manifest: {
-            ...manifest.data,
-            selected_executable_sha256: null,
-            executable_sha256: null,
-            executable_identity: {
-                state: "unknown",
-                reason: LEGACY_EXECUTABLE_IDENTITY_REASON,
-            },
-            legacy_executable_sha256: executable_sha256,
-        },
-    };
-};
 /** Parse unknown input and reject invalid commitments or semantics. */
 export const parseProcessCapture = (input) => {
-    const parsed = processCaptureSchema.safeParse(migrateLegacyV3Capture(input));
+    const parsed = processCaptureSchema.safeParse(input);
     if (parsed.success)
         return attachProof(parsed.data);
     const issues = parsed.error.issues.flatMap((issue) => issue.code === "custom"

package/dist/domain/process/processCaptureValidation.js

@@ -1,22 +1,13 @@
 import { digestProcessCommitment } from "./processScenario.js";
+import { hasCaptureTruncation } from "./processCaptureCoverage.js";
 const orderedTimestamps = (values) => values.every((value, index) => {
     const previous = values[index - 1];
     return previous === undefined || value.at_ms >= previous.at_ms;
 });
 const validateCommitments = (capture, require) => {
     const { manifest } = capture;
-    if (manifest.legacy_executable_sha256 !== undefined) {
-        require(manifest.selected_executable_sha256 === null &&
-            manifest.executable_sha256 === null &&
-            manifest.executable_identity.state === "unknown" &&
-            manifest.executable_identity.reason !== null &&
-            manifest.scenario.executable_sha256 ===
-                manifest.legacy_executable_sha256, "manifest.legacy_executable_sha256", "legacy executable digest must remain distinct from unknown selected and launch digests");
-    }
-    else {
-        require(manifest.scenario.executable_sha256 ===
-            manifest.selected_executable_sha256, "manifest.selected_executable_sha256", "selected executable commitment does not match the scenario projection");
-    }
+    require(manifest.scenario.executable_sha256 ===
+        manifest.selected_executable_sha256, "manifest.selected_executable_sha256", "selected executable commitment does not match the scenario projection");
     require(manifest.executable_identity.state === "path_metadata_unchanged"
         ? manifest.executable_sha256 === manifest.selected_executable_sha256 &&
             manifest.executable_identity.reason === null
@@ -48,7 +39,7 @@ const validateOrdering = (capture, require) => {
         require(orderedTimestamps(values), name, "timestamps must be ordered");
 };
 const validateEventJournal = (capture, require) => {
-    const journal = capture.event_journal ?? [];
+    const journal = capture.event_journal;
     if (journal.length === 0)
         return;
     const sizes = {
@@ -83,6 +74,82 @@ const validateLifecycle = (capture, require) => {
         capture.exit.code ===
             null, "exit", "deadline termination cannot declare a normal exit code");
 };
+const validateCoverage = (capture, require) => {
+    const details = capture.truncation_details;
+    if (details === undefined)
+        return;
+    require(details.process.retained_samples === capture.process_samples.length &&
+        details.process.retained_samples <= details.process.sample_limit &&
+        details.process.sampling_partial ===
+            (details.process.sample_limit_reached ||
+                details.process.sampling_failures > 0) &&
+        (details.process.sampling_failures === 0) ===
+            (details.process.first_sampling_failure ===
+                null), "truncation_details.process", "sampling coverage must agree with retained samples and observed failures");
+    require(capture.truncated ===
+        hasCaptureTruncation(details), "truncation_details", "aggregate truncation must match producer coverage");
+    for (const [name, retention, count, bytes] of [
+        [
+            "raw_terminal",
+            details.raw_terminal,
+            capture.frames.length,
+            capture.frames.reduce((total, frame) => total + Buffer.byteLength(frame.raw_data ?? frame.data), 0),
+        ],
+        [
+            "rendered_terminal",
+            details.rendered_terminal,
+            capture.rendered_frames.length,
+            capture.rendered_frames.reduce((total, frame) => frame.lines.reduce((sum, line) => sum + Buffer.byteLength(line), total + Buffer.byteLength(frame.serialized_state)), 0),
+        ],
+    ]) {
+        // Whole frames are retained or omitted, so retained bytes are exactly the
+        // retained frames' bytes, and nothing is unretained when no frame was omitted.
+        require(retention.retained_frames === count &&
+            retention.observed_frames >= count &&
+            retention.retained_bytes === bytes &&
+            retention.observed_bytes >= retention.retained_bytes &&
+            (retention.observed_frames > count ||
+                retention.observed_bytes === retention.retained_bytes) &&
+            retention.retained_bytes <=
+                retention.budget_bytes, `truncation_details.${name}`, "retained observations and budget accounting do not agree");
+    }
+    for (const [name, coverage, files, checkpoint] of [
+        [
+            "filesystem_before",
+            details.filesystem_before,
+            capture.files_before,
+            capture.filesystem_checkpoints[0],
+        ],
+        [
+            "filesystem_after",
+            details.filesystem_after,
+            capture.files_after,
+            capture.filesystem_checkpoints[1],
+        ],
+    ]) {
+        const unhashedFiles = new Map(files
+            .filter((file) => file.type === "file" && file.sha256 === null)
+            .map((file) => [file.path, file]));
+        require(coverage.hash_omissions.length === unhashedFiles.size &&
+            new Set(coverage.hash_omissions.map(({ path }) => path)).size ===
+                unhashedFiles.size &&
+            coverage.hash_omissions.every((omission) => unhashedFiles.get(omission.path)?.size === omission.size_bytes &&
+                omission.remaining_budget_bytes <= coverage.hash_budget_bytes), `truncation_details.${name}.hash_omissions`, "every retained regular file without a digest must have one matching omission reason");
+        require(coverage.hashed_bytes ===
+            files
+                .filter((file) => file.type === "file" && file.sha256 !== null)
+                .reduce((sum, file) => sum + file.size, 0) &&
+            coverage.hashed_bytes <= coverage.hash_budget_bytes &&
+            files.length <=
+                coverage.files_limit, `truncation_details.${name}`, "filesystem budget accounting does not match retained observations");
+        require(coverage.enumeration_truncated ===
+            coverage.enumeration_reasons.length > 0 &&
+            checkpoint?.truncated ===
+                (coverage.enumeration_truncated ||
+                    coverage.hash_omissions.length >
+                        0), `truncation_details.${name}`, "filesystem checkpoint truncation must match enumeration and digest coverage");
+    }
+};
 /** Recompute commitments and cross-field invariants without side effects. */
 export const collectProcessCaptureIssues = (capture) => {
     const issues = [];
@@ -94,5 +161,6 @@ export const collectProcessCaptureIssues = (capture) => {
     validateOrdering(capture, require);
     validateEventJournal(capture, require);
     validateLifecycle(capture, require);
+    validateCoverage(capture, require);
     return issues;
 };

package/dist/domain/process/processComparison.js

@@ -1,8 +1,14 @@
 import canonicalize from "canonicalize";
 import { z } from "zod";
+import { processSourceTruncated } from "./processCaptureCoverage.js";
+import { comparableTerminalFrame } from "./processObservation.js";
+import { AnalysisInputError } from "../analysisErrorCore.js";
 import { jsonValueSchema } from "../jsonValue.js";
-import { compareProcessTraces, processTraceOutcomesDiffer, processTraceComparisonResultSchema, } from "./processTraceComparison.js";
+import {} from "./processTraceSpecification.js";
+import { processTraceComparisonResultSchema } from "./processTraceEvaluation.js";
 import { dimensionsForTraceSources, traceCoversObservedDimension, } from "./processTraceDimensionProjection.js";
+import { compareProcessTraces, processTraceOutcomesDiffer, } from "./processTraceComparison.js";
+const OPERATION = "compare_process_captures";
 /** Comparison classification that never equates incomplete evidence. */
 export const comparisonStatusSchema = z.enum([
     "unchanged",
@@ -70,7 +76,10 @@ export const processCaptureComparisonSchema = z
         });
 });
 const terminalObservations = (capture) => [
-    ...capture.frames.map((frame) => ({ kind: "raw", ...frame })),
+    ...capture.frames.map((frame) => ({
+        kind: "raw",
+        ...comparableTerminalFrame(frame),
+    })),
     ...capture.rendered_frames.map((frame) => ({
         kind: "rendered",
         ...frame,
@@ -152,15 +161,47 @@ const chooseFirstDivergence = (candidates) => {
 };
 const assertComparable = (left, right, options) => {
     if (left.manifest.comparison_contract_sha256 !==
-        right.manifest.comparison_contract_sha256)
-        throw new TypeError("Process captures have incompatible comparison contracts");
+        right.manifest.comparison_contract_sha256) {
+        const fields = differingContractFields(left.manifest.comparison_contract, right.manifest.comparison_contract);
+        throw new AnalysisInputError(OPERATION, undefined, [
+            {
+                path: ["right"],
+                reason: "invalid_value",
+                message: `Process captures have incompatible comparison contracts${fields.length === 0 ? "" : `; these scenario fields differ: ${fields.join(", ")}`}. Capture both scenarios with the same values for these fields, then compare them.`,
+                expected: fields,
+            },
+        ]);
+    }
     if (options.maxCaptureAgeMs === undefined)
         return;
     const maxCaptureAgeMs = options.maxCaptureAgeMs;
     const now = (options.now ?? Date.now)();
-    if ([left, right].some(({ manifest }) => now - Date.parse(manifest.completed_at) > maxCaptureAgeMs))
-        throw new TypeError("Process capture exceeds max_capture_age_ms");
+    const stale = [
+        ["left", left],
+        ["right", right],
+    ].flatMap(([side, { manifest }]) => {
+        const age = now - Date.parse(manifest.completed_at);
+        return age > maxCaptureAgeMs
+            ? [
+                `${side} completed at ${manifest.completed_at} (${String(age)} ms ago)`,
+            ]
+            : [];
+    });
+    if (stale.length > 0)
+        throw new AnalysisInputError(OPERATION, undefined, [
+            {
+                path: ["max_capture_age_ms"],
+                reason: "out_of_range",
+                message: `Process capture exceeds max_capture_age_ms ${String(maxCaptureAgeMs)}: ${stale.join("; ")}. Recapture the stale scenario or raise max_capture_age_ms.`,
+            },
+        ]);
 };
+/** Name top-level contract fields whose canonical values differ. */
+const differingContractFields = (left, right) => [...new Set([...Object.keys(left), ...Object.keys(right)])]
+    .filter((field) => !Object.hasOwn(left, field) ||
+    !Object.hasOwn(right, field) ||
+    canonicalize(left[field]) !== canonicalize(right[field]))
+    .sort();
 const truncatedComparison = () => ({
     status: "truncated",
     terminal: "truncated",
@@ -207,19 +248,23 @@ const applyTraceVerdict = (dimensions, specification, trace, captures) => {
     };
 };
 const compareDimensions = (left, right, sameNormalization) => {
-    const classify = (scope, leftValues, rightValues) => !sameNormalization || hasUnknown(left, scope) || hasUnknown(right, scope)
+    const classify = (scope, leftValues, rightValues, source) => !sameNormalization ||
+        hasUnknown(left, scope) ||
+        hasUnknown(right, scope) ||
+        processSourceTruncated(left, source) ||
+        processSourceTruncated(right, source)
         ? "unknown"
         : classifyCollection(leftValues, rightValues);
     return {
-        terminal: classify("terminal", terminalObservations(left), terminalObservations(right)),
-        interaction: classify("interaction", left.interaction_events, right.interaction_events),
+        terminal: classify("terminal", terminalObservations(left), terminalObservations(right), "terminal_rendered"),
+        interaction: classify("interaction", left.interaction_events, right.interaction_events, "interaction"),
         exit: hasUnknown(left, "exit") || hasUnknown(right, "exit")
             ? "unknown"
             : sameJsonValue({ exit: left.exit, settlement: left.settlement }, { exit: right.exit, settlement: right.settlement })
                 ? "unchanged"
                 : "changed",
-        filesystem: classify("filesystem", filesystemObservations(left), filesystemObservations(right)),
-        process: classify("process", left.process_samples, right.process_samples),
+        filesystem: classify("filesystem", filesystemObservations(left), filesystemObservations(right), "filesystem"),
+        process: classify("process", left.process_samples, right.process_samples, "process"),
     };
 };
 /**
@@ -230,7 +275,8 @@ const compareDimensions = (left, right, sameNormalization) => {
  */
 export const compareProcessCaptures = (left, right, options = {}) => {
     assertComparable(left, right, options);
-    if (left.truncated || right.truncated) {
+    if ((left.truncated && left.truncation_details === undefined) ||
+        (right.truncated && right.truncation_details === undefined)) {
         const truncated = truncatedComparison();
         return options.traceSpecification === undefined
             ? truncated
@@ -250,25 +296,32 @@ export const compareProcessCaptures = (left, right, options = {}) => {
             left,
             right,
         ]);
-    const divergenceCandidates = PROCESS_COMPARISON_DIMENSIONS.map((dimension) => firstCollectionDivergence(dimension, processDimensionObservations(left, dimension), processDimensionObservations(right, dimension)));
+    const divergenceCandidates = PROCESS_COMPARISON_DIMENSIONS.map((dimension) => dimensions[dimension] === "unknown"
+        ? null
+        : firstCollectionDivergence(dimension, processDimensionObservations(left, dimension), processDimensionObservations(right, dimension)));
     const observedFirstDivergence = chooseFirstDivergence(divergenceCandidates.map((candidate) => candidate !== null &&
         trace?.verdict === "equivalent" &&
         dimensions[candidate.dimension] === "unchanged"
         ? null
         : candidate));
-    const firstDivergence = trace?.verdict === "equivalent" &&
-        deriveProcessComparisonStatus(PROCESS_COMPARISON_DIMENSIONS.map((dimension) => dimensions[dimension])) === "unchanged"
-        ? { status: "none" }
-        : observedFirstDivergence.status === "found"
-            ? observedFirstDivergence
-            : !sameNormalization ||
-                left.residual_unknowns.length > 0 ||
-                right.residual_unknowns.length > 0
-                ? {
-                    status: "unknown",
-                    reason: "Residual unknowns prevent proving that no divergence occurred.",
-                }
-                : observedFirstDivergence;
+    const firstDivergence = left.truncated || right.truncated
+        ? {
+            status: "unknown",
+            reason: "Incomplete observations prevent locating the first divergence; unaffected dimensions retain their comparisons.",
+        }
+        : trace?.verdict === "equivalent" &&
+            deriveProcessComparisonStatus(PROCESS_COMPARISON_DIMENSIONS.map((dimension) => dimensions[dimension])) === "unchanged"
+            ? { status: "none" }
+            : observedFirstDivergence.status === "found"
+                ? observedFirstDivergence
+                : !sameNormalization ||
+                    left.residual_unknowns.length > 0 ||
+                    right.residual_unknowns.length > 0
+                    ? {
+                        status: "unknown",
+                        reason: "Residual unknowns prevent proving that no divergence occurred.",
+                    }
+                    : observedFirstDivergence;
     const observedStatus = deriveProcessComparisonStatus(PROCESS_COMPARISON_DIMENSIONS.map((dimension) => dimensions[dimension]));
     return {
         status: observedStatus,

package/dist/domain/process/processObservation.js

@@ -1,5 +1,11 @@
 import { z } from "zod";
 import { jsonValueSchema } from "../jsonValue.js";
+/** Project normalized PTY facts without source text used only for audit. */
+export const comparableTerminalFrame = (frame) => ({
+    sequence: frame.sequence,
+    at_ms: frame.at_ms,
+    data: frame.data,
+});
 /** Process-capture observation families shared by live drivers and trace assertions. */
 export const processObservationSourceSchema = z.enum([
     "terminal_raw",
@@ -67,11 +73,13 @@ export const processObservationSubject = (source, value) => {
 const projectedRecord = (capture, location) => {
     const projected = (() => {
         switch (location.collection) {
-            case "frames":
+            case "frames": {
+                const frame = capture.frames[location.index];
                 return {
                     source: "terminal_raw",
-                    value: capture.frames[location.index],
+                    value: frame === undefined ? undefined : comparableTerminalFrame(frame),
                 };
+            }
             case "rendered_frames":
                 return {
                     source: "terminal_rendered",

package/dist/domain/process/processScenario.js

@@ -4,17 +4,36 @@ import { z } from "zod";
 const positiveBudget = z.number().int().safe().positive();
 const timedEventBase = { at_ms: z.number().int().safe().nonnegative() };
 const reservedRunIdEnvironmentName = "REA_PROCESS_RUN_ID";
+const ENVIRONMENT_NAME_CHARACTER = "[^=\\u0000]";
+/**
+ * Nonempty environment names other than the reserved run identifier. The
+ * exclusion is spelled as a complement instead of a negative look-ahead,
+ * because RE2 and Rust schema validators reject look-around and would refuse
+ * every tool in the advertised catalog.
+ */
+const environmentNamePattern = (reserved) => {
+    // After the complete reserved name, at least one more character is needed.
+    let rest = `${ENVIRONMENT_NAME_CHARACTER}+`;
+    for (let index = reserved.length - 1; index >= 0; index -= 1) {
+        const character = reserved[index] ?? "";
+        // Diverge here, match the next reserved character, or (after a nonempty
+        // prefix) end the name early.
+        const choice = `[^=\\u0000${character}]${ENVIRONMENT_NAME_CHARACTER}*|${character}${rest}`;
+        rest = index === 0 ? choice : `(?:${choice})?`;
+    }
+    return new RegExp(`^(?:${rest})$`, "u");
+};
 const environmentName = z
     .string()
     .min(1, "Environment names must not be empty")
-    .regex(/^(?!REA_PROCESS_RUN_ID(?![\s\S]))[^=\0]+$/u, {
+    .regex(environmentNamePattern(reservedRunIdEnvironmentName), {
     error: (issue) => issue.input === reservedRunIdEnvironmentName
         ? `${reservedRunIdEnvironmentName} is reserved by the process adapter`
         : "Environment names cannot contain '=' or NUL",
 });
 const childProcessString = z
     .string()
-    .regex(/^[^\0]*$/u, "Values passed to operating-system APIs cannot contain NUL");
+    .regex(/^[^\u0000]*$/u, "Values passed to operating-system APIs cannot contain NUL");
 export const normalizationSchema = z.object({
     paths: z.boolean(),
     pids: z.boolean(),
@@ -62,13 +81,16 @@ export const processComparisonContract = (scenario) => ({
     settle_ms: scenario.settle_ms,
     limits: scenario.limits,
     normalization: scenario.normalization,
+    ...(scenario.normalization.ports
+        ? { port_normalization_version: "contextual-endpoints-v2" }
+        : {}),
 });
 /**
  * Boundary schema for one bounded process experiment.
  * Defaults are part of the evidence contract and must remain deterministic.
  */
 export const processScenarioSchema = z
-    .object({
+    .strictObject({
     executable: childProcessString.min(1),
     arguments: z.array(childProcessString).default([]),
     working_directory: childProcessString.default("."),
@@ -77,7 +99,7 @@ export const processScenarioSchema = z
         .array(childProcessString.min(1))
         .default([]),
     terminal: z
-        .object({
+        .strictObject({
         columns: z.number().int().min(1).max(65_535).default(80),
         rows: z.number().int().min(1).max(65_535).default(24),
         scrollback: z.number().int().min(0).default(1_000),
@@ -85,19 +107,19 @@ export const processScenarioSchema = z
         .default({ columns: 80, rows: 24, scrollback: 1_000 }),
     events: z
         .array(z.discriminatedUnion("type", [
-        z.object({
+        z.strictObject({
             ...timedEventBase,
             type: z.literal("input"),
             data: z.string(),
             sensitive: z.boolean().default(false),
         }),
-        z.object({
+        z.strictObject({
             ...timedEventBase,
             type: z.literal("resize"),
             columns: z.number().int().min(1).max(65_535),
             rows: z.number().int().min(1).max(65_535),
         }),
-        z.object({
+        z.strictObject({
             ...timedEventBase,
             type: z.literal("signal"),
             signal: z.enum(["SIGINT", "SIGTERM", "SIGKILL"]),
@@ -108,7 +130,7 @@ export const processScenarioSchema = z
     idle_timeout_ms: positiveBudget.default(30_000),
     settle_ms: z.number().int().safe().nonnegative().default(100),
     limits: z
-        .object({
+        .strictObject({
         output_bytes: positiveBudget.default(1_000_000),
         files: positiveBudget.default(10_000),
         file_bytes: positiveBudget.default(10_000_000),
@@ -124,14 +146,16 @@ export const processScenarioSchema = z
         filesystem_depth: 16,
     }),
     normalization: z
-        .object({
+        .strictObject({
         paths: z.boolean().default(false),
         pids: z.boolean().default(true),
         ports: z.boolean().default(true),
         time_bucket_ms: positiveBudget.default(10),
         patterns: z
-            .array(z.object({
-            pattern: z.string(),
+            .array(z.strictObject({
+            pattern: z
+                .string()
+                .describe("Literal text to replace in captured output; not a regular expression."),
             replacement: z.string(),
         }))
             .default([]),
@@ -144,7 +168,6 @@ export const processScenarioSchema = z
         patterns: [],
     }),
 })
-    .strict()
     .superRefine((scenario, context) => {
     for (let index = 1; index < scenario.events.length; index += 1) {
         const event = scenario.events[index];

package/dist/domain/process/processTraceComparison.js

@@ -1,7 +1,5 @@
 import { evaluateProcessTraceSide, processTraceComparisonResultSchema, } from "./processTraceEvaluation.js";
 import { processTraceSpecificationSchema, } from "./processTraceSpecification.js";
-export { processTraceComparisonResultSchema, } from "./processTraceEvaluation.js";
-export { processTraceSpecificationSchema, } from "./processTraceSpecification.js";
 /** Compare two captures against an explicit finite trace language. */
 export const compareProcessTraces = (left, right, specificationInput) => {
     const specification = processTraceSpecificationSchema.parse(specificationInput);

package/dist/domain/process/processTraceDimensionProjection.js

@@ -1,4 +1,4 @@
-/** Map declared trace sources to legacy process-comparison dimensions. */
+/** Map declared trace sources to process-comparison dimensions. */
 export const dimensionsForTraceSources = (sources) => {
     const dimensions = new Set();
     for (const source of sources) {

package/dist/domain/process/processTraceEvaluation.js

@@ -1,11 +1,11 @@
 import { z } from "zod";
+import { processSourceTruncated } from "./processCaptureCoverage.js";
 import { processObservationLocationSchema, projectProcessObservation, } from "./processObservation.js";
 import { canonicalTraceJson, comparableTracePayload, processTraceCardinalityBounds, } from "./processTraceSpecification.js";
-const identifierSchema = z.string().regex(/^[A-Za-z][A-Za-z0-9._-]{0,63}$/u);
-const locationSchema = processObservationLocationSchema;
+const identifierSchema = z.string().regex(/^[A-Za-z][A-Za-z0-9._\x2d]{0,63}$/u);
 const matchedEventSchema = z.strictObject({
     event_id: identifierSchema,
-    location: locationSchema,
+    location: processObservationLocationSchema,
 });
 const sideResultShape = {
     satisfied_constraints: z.array(z.string()),
@@ -36,7 +36,7 @@ const diagnosticSchema = z.strictObject({
     side: z.enum(["left", "right"]),
     message: z.string(),
     event_ids: z.array(identifierSchema),
-    locations: z.array(locationSchema),
+    locations: z.array(processObservationLocationSchema),
 });
 /** Structured verdict for one declared process trace language. */
 export const processTraceComparisonResultSchema = z.strictObject({
@@ -56,11 +56,11 @@ const scopesFor = (sources) => new Set([...sources].map((source) => {
         return "process";
     return "interaction";
 }));
-const unknownSide = () => ({
+const unknownSide = (rawTrace = []) => ({
     status: "unknown",
     matched_variant: null,
     satisfied_constraints: [],
-    raw_trace: [],
+    raw_trace: rawTrace,
 });
 const failure = (input) => ({
     result: {
@@ -102,7 +102,7 @@ const evaluateFiniteTrace = (ids, specification) => {
 };
 const collectRecords = (capture, sources) => {
     const records = [];
-    for (const location of capture.event_journal ?? []) {
+    for (const location of capture.event_journal) {
         const record = projectProcessObservation(capture, location);
         if (record !== null && sources.has(record.source))
             records.push({
@@ -296,10 +296,9 @@ const evaluateMatchedTrace = (trace, specification) => {
 export const evaluateProcessTraceSide = (capture, specification) => {
     const sources = new Set(specification.events.map(({ source }) => source));
     const relevantScopes = scopesFor(sources);
-    if (capture.truncated ||
-        capture.residual_unknowns.some(({ scope }) => relevantScopes.has(scope)))
-        return { result: unknownSide(), diagnostic: null };
-    if ((capture.event_journal ?? []).length === 0)
+    const incomplete = [...sources].some((source) => processSourceTruncated(capture, source)) ||
+        capture.residual_unknowns.some(({ scope }) => relevantScopes.has(scope));
+    if (capture.event_journal.length === 0)
         return {
             result: unknownSide(),
             diagnostic: {
@@ -310,6 +309,11 @@ export const evaluateProcessTraceSide = (capture, specification) => {
             },
         };
     const matched = matchRecords(collectRecords(capture, sources), specification);
+    if (incomplete)
+        return {
+            result: unknownSide("rawTrace" in matched ? matched.rawTrace : matched.result.raw_trace),
+            diagnostic: null,
+        };
     return "rawTrace" in matched
         ? evaluateMatchedTrace(matched, specification)
         : matched;

package/dist/domain/process/processTraceSpecification.js

@@ -1,10 +1,9 @@
 import canonicalize from "canonicalize";
 import { z } from "zod";
+import { IDENTIFIER_PATTERN } from "../stringPatterns.js";
 import { jsonValueSchema } from "../jsonValue.js";
 import { comparableProcessObservationPayload, processObservationSourceSchema, } from "./processObservation.js";
-const identifierSchema = z.string().regex(/^[A-Za-z][A-Za-z0-9._-]*$/u);
-/** Process observation families admitted by a declared trace specification. */
-export const processTraceSourceSchema = processObservationSourceSchema;
+const identifierSchema = z.string().regex(IDENTIFIER_PATTERN);
 const cardinalitySchema = z.discriminatedUnion("kind", [
     z.strictObject({ kind: z.literal("required") }),
     z.strictObject({ kind: z.literal("optional") }),
@@ -25,7 +24,7 @@ const cardinalitySchema = z.discriminatedUnion("kind", [
 ]);
 const eventDeclarationSchema = z.strictObject({
     id: identifierSchema,
-    source: processTraceSourceSchema,
+    source: processObservationSourceSchema,
     exact: jsonValueSchema,
     ignore_fields: z
         .array(z.enum([

package/dist/domain/propertyListKeys.js

@@ -39,7 +39,7 @@ const XML_ENTITIES = {
  * Unicode stays as written: comments and CDATA may hold such text literally,
  * and the XML decoder rejects it anywhere else.
  */
-const decodeXmlText = (text) => text.replace(/&(?:#x([\da-f]+)|#(\d+)|([a-z]+));/giu, (entity, hex, decimal, name) => {
+export const decodeXmlText = (text) => text.replace(/&(?:#x([\da-f]+)|#(\d+)|([a-z]+));/giu, (entity, hex, decimal, name) => {
     const codePoint = hex !== undefined
         ? parseInt(hex, 16)
         : decimal !== undefined

package/dist/domain/propertyListXmlText.js

@@ -0,0 +1,19 @@
+/** Decode BOM-aware XML plist text with fatal byte validation. */
+export const decodeXmlPlistText = (bytes) => {
+    const encoding = bytes[0] === 0xff && bytes[1] === 0xfe
+        ? "utf-16le"
+        : bytes[0] === 0xfe && bytes[1] === 0xff
+            ? "utf-16be"
+            : "utf-8";
+    const text = new TextDecoder(encoding, { fatal: true }).decode(bytes);
+    const declaration = /^<\?xml\s[^?]*\bencoding\s*=\s*["']([^"']+)["']/u.exec(text)?.[1];
+    const declared = declaration?.toLowerCase();
+    if (declared !== undefined &&
+        !["utf-8", "utf-16", "utf-16le", "utf-16be"].includes(declared))
+        throw new TypeError(`Unsupported XML encoding declaration: ${declaration}. Supported encodings are UTF-8 and BOM-marked UTF-16 in either byte order.`);
+    if (declared !== undefined &&
+        declared !== encoding &&
+        !(encoding !== "utf-8" && declared === "utf-16"))
+        throw new TypeError("XML encoding declaration disagrees with its bytes");
+    return text;
+};

package/dist/domain/providerAdapterError.js

@@ -1,14 +1,16 @@
-import { AnalysisError } from "./analysisErrorBase.js";
+import { AnalysisError, } from "./analysisErrorBase.js";
 /** A provider adapter failed outside its more precise typed variants. */
 export class ProviderAdapterError extends AnalysisError {
     providerId;
     operation;
     _tag = "ProviderAdapterError";
+    userMessage;
     diagnostics;
     constructor(providerId, operation, options = {}) {
         super(`Provider ${providerId} adapter failed during ${operation}`, options);
         this.providerId = providerId;
         this.operation = operation;
+        this.userMessage = options.userMessage;
         this.diagnostics =
             options.diagnostics === undefined
                 ? undefined