rea-agents 6.2.0 → 6.4.0

package/dist/domain/process/processCaptureExample.js

@@ -56,6 +56,49 @@ export const EMPTY_PROCESS_CAPTURE_EXAMPLE = {
     files_after: [],
     filesystem_effects: [],
     truncated: false,
+    truncation_details: {
+        raw_terminal: {
+            budget_bytes: 1_000_000,
+            observed_bytes: 0,
+            retained_bytes: 0,
+            observed_frames: 0,
+            retained_frames: 0,
+        },
+        rendered_terminal: {
+            budget_bytes: 1_000_000,
+            observed_bytes: 0,
+            retained_bytes: 0,
+            observed_frames: 0,
+            retained_frames: 0,
+        },
+        filesystem_before: {
+            files_limit: 10_000,
+            depth_limit: 16,
+            enumeration_truncated: false,
+            enumeration_reasons: [],
+            hash_budget_bytes: 10_000_000,
+            hashed_bytes: 0,
+            hash_omissions: [],
+        },
+        filesystem_after: {
+            files_limit: 10_000,
+            depth_limit: 16,
+            enumeration_truncated: false,
+            enumeration_reasons: [],
+            hash_budget_bytes: 10_000_000,
+            hashed_bytes: 0,
+            hash_omissions: [],
+        },
+        process: {
+            sample_limit: 1_000,
+            sampling_partial: false,
+            retained_samples: 0,
+            sample_limit_reached: false,
+            sampling_failures: 0,
+            first_sampling_failure: null,
+            coverage: "sampled",
+        },
+    },
     limitations: [],
     residual_unknowns: [],
     cleanup: {
@@ -63,3 +106,27 @@ export const EMPTY_PROCESS_CAPTURE_EXAMPLE = {
         temporary_root: "removed",
     },
 };
+const finalizedScenario = { ...scenario, finalization_ms: 1_500 };
+const finalizedComparisonContract = { finalization_ms: 1_500 };
+/** Valid capture of a timeout that finalized: SIGTERM delivered, exit observed. */
+export const FINALIZED_PROCESS_CAPTURE_EXAMPLE = {
+    ...EMPTY_PROCESS_CAPTURE_EXAMPLE,
+    manifest: {
+        ...EMPTY_PROCESS_CAPTURE_EXAMPLE.manifest,
+        scenario: finalizedScenario,
+        comparison_contract: finalizedComparisonContract,
+        full_scenario_sha256: digestProcessCommitment(finalizedScenario),
+        comparison_contract_sha256: digestProcessCommitment(finalizedComparisonContract),
+    },
+    exit: {
+        code: null,
+        signal: 0,
+        reason: "timeout",
+        finalization: {
+            requested_ms: 1_500,
+            elapsed_ms: 12,
+            exit_code: 0,
+            signals: [{ signal: "SIGTERM", sent_at_ms: 0, delivery: "signaled" }],
+        },
+    },
+};

package/dist/domain/process/processCaptureValidation.js

@@ -64,6 +64,83 @@ const validateEventJournal = (capture, require) => {
     require(journal.length ===
         expectedSize, "event_journal", "nonempty journal must reference every captured observation");
 };
+/**
+ * The committed comparison contract carries `finalization_ms` exactly when the
+ * committed scenario does, with the same value. Independent of the exit, so a
+ * partial capture with an unavailable exit is still checked.
+ */
+export const finalizationManifestIssue = (committedScenario, committedComparison) => committedScenario !== undefined &&
+    committedComparison !== undefined &&
+    committedScenario["finalization_ms"] !==
+        committedComparison["finalization_ms"]
+    ? "comparison_contract finalization_ms must match the committed scenario"
+    : undefined;
+/** Ensure incomplete exit and sibling finalization observations preserve one fact. */
+export const finalizationAgreementIssue = (exitFinalization, observedFinalization) => exitFinalization !== undefined &&
+    observedFinalization !== undefined &&
+    JSON.stringify(exitFinalization) !== JSON.stringify(observedFinalization)
+    ? "exit finalization and finalization observation must agree"
+    : undefined;
+/**
+ * Cross-field rule for `exit.finalization`, shared by complete and partial
+ * captures. Returns the violated rule, or undefined when the record is
+ * consistent.
+ */
+export const finalizationConsistencyIssue = (exit, committedScenario, committedComparison, options) => {
+    const manifestIssue = finalizationManifestIssue(committedScenario, committedComparison);
+    if (manifestIssue !== undefined)
+        return manifestIssue;
+    const finalization = exit?.finalization ?? options?.finalization;
+    if (finalization === undefined) {
+        // A deadline that fired under a committed interval must have attempted
+        // finalization; cancellation before the deadline legitimately has none.
+        const committed = committedScenario?.["finalization_ms"];
+        return (exit?.reason === "timeout" || exit?.reason === "idle_timeout") &&
+            typeof committed === "number" &&
+            committed > 0
+            ? "a deadline exit under a committed finalization_ms requires finalization evidence"
+            : undefined;
+    }
+    if (exit?.reason === "exited")
+        return "finalization requires a deadline exit reason";
+    const first = finalization.signals[0];
+    if (first?.signal !== "SIGTERM")
+        return "finalization signals must start with SIGTERM";
+    const killIndexes = finalization.signals.flatMap(({ signal }, index) => signal === "SIGKILL" ? [index] : []);
+    if (killIndexes.length > 1 ||
+        (killIndexes[0] !== undefined &&
+            killIndexes[0] !== finalization.signals.length - 1))
+        return "finalization may contain at most one final SIGKILL";
+    if (!finalization.signals.every(({ sent_at_ms }, index) => {
+        const previous = finalization.signals[index - 1];
+        return previous === undefined || sent_at_ms >= previous.sent_at_ms;
+    }))
+        return "finalization signal attempt times must not decrease";
+    if (finalization.signals.filter(({ signal }) => signal === "SIGTERM").length !==
+        1)
+        return "finalization must attempt SIGTERM exactly once";
+    const kill = finalization.signals.find(({ signal }) => signal === "SIGKILL");
+    if (kill !== undefined &&
+        kill.sent_at_ms < finalization.requested_ms &&
+        exit !== undefined &&
+        exit.reason !== "cancelled")
+        return "finalization SIGKILL cannot precede the requested interval";
+    if (finalization.elapsed_ms === null && options?.allowNullElapsedMs !== true)
+        return "finalization requires an observed elapsed_ms";
+    if (finalization.exit_code !== null &&
+        exit?.signal !== undefined &&
+        exit.signal !== null &&
+        exit.signal !== 0)
+        return "finalization exit_code requires an exit not caused by a signal";
+    if (finalization.elapsed_ms !== null &&
+        finalization.elapsed_ms <
+            (finalization.signals.at(-1)?.sent_at_ms ?? first.sent_at_ms))
+        return "finalization elapsed_ms cannot precede the last signal attempt";
+    if (committedScenario !== undefined &&
+        committedScenario["finalization_ms"] !== finalization.requested_ms)
+        return "finalization must match the committed finalization_ms";
+    return undefined;
+};
 const validateLifecycle = (capture, require) => {
     require(capture.filesystem_checkpoints.map(({ name }) => name).join(",") ===
         "before,after_settlement", "filesystem_checkpoints", "capture must include initial and final filesystem snapshots");
@@ -73,11 +150,11 @@ const validateLifecycle = (capture, require) => {
     require(capture.exit.reason === "exited" ||
         capture.exit.code ===
             null, "exit", "deadline termination cannot declare a normal exit code");
+    const finalizationIssue = finalizationConsistencyIssue(capture.exit, capture.manifest.scenario, capture.manifest.comparison_contract);
+    require(finalizationIssue === undefined, "exit", finalizationIssue ?? "");
 };
 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 ===
@@ -134,7 +211,10 @@ const validateCoverage = (capture, require) => {
             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");
+                omission.remaining_budget_bytes <= coverage.hash_budget_bytes &&
+                (omission.reason === "file_unavailable"
+                    ? omission.system_code !== null
+                    : omission.system_code === null)), `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)

package/dist/domain/process/processComparison.js

@@ -202,19 +202,6 @@ const differingContractFields = (left, right) => [...new Set([...Object.keys(lef
     !Object.hasOwn(right, field) ||
     canonicalize(left[field]) !== canonicalize(right[field]))
     .sort();
-const truncatedComparison = () => ({
-    status: "truncated",
-    terminal: "truncated",
-    interaction: "truncated",
-    exit: "truncated",
-    filesystem: "truncated",
-    process: "truncated",
-    first_divergence: {
-        status: "unknown",
-        reason: "At least one capture is truncated.",
-    },
-    limitations: ["At least one capture is truncated."],
-});
 const applyTraceVerdict = (dimensions, specification, trace, captures) => {
     const traceShowsDifference = processTraceOutcomesDiffer(trace);
     const traceStatus = trace.verdict === "unknown"
@@ -275,16 +262,6 @@ const compareDimensions = (left, right, sameNormalization) => {
  */
 export const compareProcessCaptures = (left, right, options = {}) => {
     assertComparable(left, right, options);
-    if ((left.truncated && left.truncation_details === undefined) ||
-        (right.truncated && right.truncation_details === undefined)) {
-        const truncated = truncatedComparison();
-        return options.traceSpecification === undefined
-            ? truncated
-            : {
-                ...truncated,
-                trace: compareProcessTraces(left, right, options.traceSpecification),
-            };
-    }
     const sameNormalization = sameJsonValue(left.normalization, right.normalization);
     const exactDimensions = compareDimensions(left, right, sameNormalization);
     const trace = options.traceSpecification === undefined

package/dist/domain/process/processScenario.js

@@ -2,9 +2,15 @@ import { createHash } from "node:crypto";
 import canonicalize from "canonicalize";
 import { z } from "zod";
 const positiveBudget = z.number().int().safe().positive();
+/**
+ * Maximum xterm backing cells for one visible-plus-scrollback buffer. Each
+ * xterm BufferLine stores three Uint32 words per cell (12 MB at this cap),
+ * before row objects, serialization strings, and retained frame copies.
+ */
+export const PROCESS_TERMINAL_CELL_BUDGET = 1_000_000;
 const timedEventBase = { at_ms: z.number().int().safe().nonnegative() };
 const reservedRunIdEnvironmentName = "REA_PROCESS_RUN_ID";
-const ENVIRONMENT_NAME_CHARACTER = "[^=\\u0000]";
+const ENVIRONMENT_NAME_CHARACTER = "[^=\\x00]";
 /**
  * Nonempty environment names other than the reserved run identifier. The
  * exclusion is spelled as a complement instead of a negative look-ahead,
@@ -18,7 +24,7 @@ const environmentNamePattern = (reserved) => {
         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}`;
+        const choice = `[^=\\x00${character}]${ENVIRONMENT_NAME_CHARACTER}*|${character}${rest}`;
         rest = index === 0 ? choice : `(?:${choice})?`;
     }
     return new RegExp(`^(?:${rest})$`, "u");
@@ -33,7 +39,8 @@ const environmentName = z
 });
 const childProcessString = z
     .string()
-    .regex(/^[^\u0000]*$/u, "Values passed to operating-system APIs cannot contain NUL");
+    .regex(/^[^\x00]*$/u, "Values passed to operating-system APIs cannot contain NUL");
+const fitsProcessTerminalCellBudget = (columns, rows, scrollback) => rows + scrollback <= Math.floor(PROCESS_TERMINAL_CELL_BUDGET / columns);
 export const normalizationSchema = z.object({
     paths: z.boolean(),
     pids: z.boolean(),
@@ -60,11 +67,17 @@ const committedScenarioEvents = (events, includeSensitiveInputLength) => events.
     }
     : event);
 /** Build the caller-selected scenario projection committed by process-capture Evidence. */
-export const processScenarioCommitment = (scenario, executableSha256) => ({
-    ...scenario,
-    events: committedScenarioEvents(scenario.events, true),
-    executable_sha256: executableSha256 ?? null,
-});
+export const processScenarioCommitment = (scenario, executableSha256) => {
+    // A zero interval is today's immediate kill; leaving it out keeps the
+    // committed identity of every scenario that predates the field unchanged.
+    const { finalization_ms: finalizationMs, ...committed } = scenario;
+    return {
+        ...committed,
+        ...(finalizationMs > 0 ? { finalization_ms: finalizationMs } : {}),
+        events: committedScenarioEvents(scenario.events, true),
+        executable_sha256: executableSha256 ?? null,
+    };
+};
 /** Project observation settings shared by capture and reconstruction. */
 export const processComparisonContract = (scenario) => ({
     working_directory: scenario.working_directory,
@@ -79,11 +92,18 @@ export const processComparisonContract = (scenario) => ({
     timeout_ms: scenario.timeout_ms,
     idle_timeout_ms: scenario.idle_timeout_ms,
     settle_ms: scenario.settle_ms,
+    ...(scenario.finalization_ms > 0
+        ? { finalization_ms: scenario.finalization_ms }
+        : {}),
     limits: scenario.limits,
     normalization: scenario.normalization,
     ...(scenario.normalization.ports
         ? { port_normalization_version: "contextual-endpoints-v2" }
         : {}),
+    ...(scenario.normalization.patterns.length > 0
+        ? { pattern_normalization_version: "literal-replacements-v1" }
+        : {}),
+    rendered_line_format: "trailing-spaces-trimmed-v1",
 });
 /**
  * Boundary schema for one bounded process experiment.
@@ -102,8 +122,9 @@ export const processScenarioSchema = z
         .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),
+        scrollback: z.number().int().safe().nonnegative().default(1_000),
     })
+        .describe("The visible terminal and scrollback together must use at most 1,000,000 xterm renderer cells: columns × (rows + scrollback). Resize events use the same scrollback and limit.")
         .default({ columns: 80, rows: 24, scrollback: 1_000 }),
     events: z
         .array(z.discriminatedUnion("type", [
@@ -129,6 +150,13 @@ export const processScenarioSchema = z
     timeout_ms: positiveBudget.default(30_000),
     idle_timeout_ms: positiveBudget.default(30_000),
     settle_ms: z.number().int().safe().nonnegative().default(100),
+    finalization_ms: z
+        .number()
+        .int()
+        .safe()
+        .nonnegative()
+        .default(0)
+        .describe("Milliseconds a target may keep running after SIGTERM when timeout_ms or idle_timeout_ms fires, before SIGKILL; 0 sends SIGKILL immediately. Both signals reach the captured root only while its launch-time start identity still matches; cancellation ends the run at once."),
     limits: z
         .strictObject({
         output_bytes: positiveBudget.default(1_000_000),
@@ -169,6 +197,23 @@ export const processScenarioSchema = z
     }),
 })
     .superRefine((scenario, context) => {
+    // Each budget is a safe integer, but their sum is not checked anywhere
+    // else. BigInt keeps the comparison exact beyond the representable range.
+    const lifecycleBudget = BigInt(scenario.timeout_ms) +
+        BigInt(scenario.finalization_ms) +
+        BigInt(scenario.settle_ms);
+    if (lifecycleBudget > BigInt(Number.MAX_SAFE_INTEGER))
+        context.addIssue({
+            code: "custom",
+            message: `timeout_ms + finalization_ms + settle_ms must stay at or below ${String(Number.MAX_SAFE_INTEGER)} ms, the largest total exactly representable as a JavaScript number`,
+            path: ["timeout_ms"],
+        });
+    if (!fitsProcessTerminalCellBudget(scenario.terminal.columns, scenario.terminal.rows, scenario.terminal.scrollback))
+        context.addIssue({
+            code: "custom",
+            path: ["terminal"],
+            message: `terminal columns × (rows + scrollback) must not exceed ${String(PROCESS_TERMINAL_CELL_BUDGET)} renderer cells`,
+        });
     for (let index = 1; index < scenario.events.length; index += 1) {
         const event = scenario.events[index];
         const previous = scenario.events[index - 1];
@@ -180,7 +225,14 @@ export const processScenarioSchema = z
             });
         }
     }
-    for (const event of scenario.events) {
+    for (const [index, event] of scenario.events.entries()) {
+        if (event.type === "resize" &&
+            !fitsProcessTerminalCellBudget(event.columns, event.rows, scenario.terminal.scrollback))
+            context.addIssue({
+                code: "custom",
+                path: ["events", index],
+                message: `resize event at ${String(event.at_ms)} ms exceeds the ${String(PROCESS_TERMINAL_CELL_BUDGET)}-cell renderer budget with the selected scrollback`,
+            });
         if (event.at_ms > scenario.timeout_ms) {
             context.addIssue({
                 code: "custom",

package/dist/domain/process/processTraceEvaluation.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { processSourceTruncated } from "./processCaptureCoverage.js";
-import { processObservationLocationSchema, projectProcessObservation, } from "./processObservation.js";
-import { canonicalTraceJson, comparableTracePayload, processTraceCardinalityBounds, } from "./processTraceSpecification.js";
+import { comparableProcessObservationPayload, processObservationLocationSchema, projectProcessObservation, } from "./processObservation.js";
+import { canonicalTraceJson, processTraceCardinalityBounds, } from "./processTraceSpecification.js";
 const identifierSchema = z.string().regex(/^[A-Za-z][A-Za-z0-9._\x2d]{0,63}$/u);
 const matchedEventSchema = z.strictObject({
     event_id: identifierSchema,
@@ -121,10 +121,10 @@ const matchRecords = (records, specification) => {
     for (const event of specification.events) {
         const ignoredFields = event.ignore_fields ?? [];
         ignoredFieldsBySource.set(event.source, ignoredFields);
-        eventsByKey.set(`${event.source}\0${canonicalTraceJson(comparableTracePayload(event.exact, ignoredFields))}`, event);
+        eventsByKey.set(`${event.source}\0${canonicalTraceJson(comparableProcessObservationPayload(event.exact, ignoredFields))}`, event);
     }
     for (const record of records) {
-        const match = eventsByKey.get(`${record.source}\0${canonicalTraceJson(comparableTracePayload(record.payload, ignoredFieldsBySource.get(record.source)))}`);
+        const match = eventsByKey.get(`${record.source}\0${canonicalTraceJson(comparableProcessObservationPayload(record.payload, ignoredFieldsBySource.get(record.source)))}`);
         if (match === undefined)
             return failure({
                 kind: "predicate",

package/dist/domain/process/processTraceSpecification.js

@@ -86,8 +86,6 @@ export const canonicalTraceJson = (value) => {
         throw new TypeError("Trace specification contains a non-JSON value");
     return serialized;
 };
-/** Remove only explicitly declared schedule metadata before exact matching. */
-export const comparableTracePayload = (value, ignoredFields = []) => comparableProcessObservationPayload(value, ignoredFields);
 export const processTraceCardinalityBounds = (cardinality) => {
     switch (cardinality.kind) {
         case "required":
@@ -352,7 +350,7 @@ export const processTraceSpecificationSchema = specificationShapeSchema.superRef
                 message: "exact payload must omit every ignored schedule field",
                 path: ["events", index, "exact"],
             });
-        const predicate = `${event.source}\0${canonicalTraceJson(comparableTracePayload(event.exact, ignoredFields))}`;
+        const predicate = `${event.source}\0${canonicalTraceJson(comparableProcessObservationPayload(event.exact, ignoredFields))}`;
         if (predicates.has(predicate))
             context.addIssue({
                 code: "custom",

package/dist/domain/propertyListKeys.js

@@ -2,7 +2,9 @@ import { parse } from "plist";
 /** The dictionary key REA results cannot carry: validation strips it. */
 const PROTOTYPE_KEY = "__proto__";
 /** Limitation for results whose source plist held `__proto__` entries. */
-export const omittedPrototypeKeysLimitation = (count) => `${String(count)} dictionary ${count === 1 ? "entry" : "entries"} keyed __proto__ ${count === 1 ? "was" : "were"} omitted because REA results cannot represent that key.`;
+export const omittedPrototypeKeysLimitation = (count) => count === null
+    ? "Dictionary entries keyed __proto__ were omitted because REA results cannot represent that key."
+    : `${String(count)} dictionary ${count === 1 ? "entry" : "entries"} keyed __proto__ ${count === 1 ? "was" : "were"} omitted because REA results cannot represent that key.`;
 const withoutKey = (value, key) => {
     let omitted = 0;
     const strip = (item) => {

package/dist/domain/providerCleanupError.js

@@ -7,8 +7,12 @@ export class ProviderCleanupError extends ProviderAdapterError {
     constructor(providerId, resources, diagnostics, 
     /** Identify the operation owning these resources; binary callers retain their default. */
     options) {
-        const { operation = "close_binary", ...errorOptions } = options ?? {};
-        super(providerId, operation, { ...errorOptions, diagnostics });
+        const { operation = "close_binary", partialObservation, ...errorOptions } = options ?? {};
+        super(providerId, operation, {
+            ...errorOptions,
+            ...(partialObservation === undefined ? {} : { partialObservation }),
+            diagnostics,
+        });
         this.cleanupResources = [...resources];
     }
 }

package/dist/domain/reconstructionCoverage.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import canonicalize from "canonicalize";
 import { z } from "zod";
+import { compareUnicodeCodePoints, compositeKey, } from "./unicodeCodePointOrder.js";
 import { evidenceBundleSchema, parseEvidenceBundle } from "./evidenceBundle.js";
 import { evaluateReconstructionClaims, evaluateReconstructionPackageProofs, evaluateReconstructionSurfaces, evaluateReconstructionCoverageRisks, recommendedReconstructionProbes, } from "./reconstructionCoverageEvaluation.js";
 import { digestSchema } from "./../domain/digests.js";
@@ -315,7 +316,7 @@ const closureStatus = (reasons) => {
         return "unknown";
     return "partial";
 };
-const reasonOrder = (left, right) => `${left.code}:${left.subject_id}`.localeCompare(`${right.code}:${right.subject_id}`);
+const reasonOrder = (left, right) => compareUnicodeCodePoints(compositeKey([left.code, left.subject_id]), compositeKey([right.code, right.subject_id]));
 const digest = (value) => {
     const encoded = canonicalize(value);
     if (encoded === undefined)

package/dist/domain/reconstructionUnknowns.js

@@ -1,4 +1,5 @@
 import { uniqueSorted } from "./canonicalOrdering.js";
+import { compareUnicodeCodePoints, compositeKey, } from "./unicodeCodePointOrder.js";
 /** Select the latest revision of each residual unknown. */
 export const reconstructionUnknownHeads = (revisions) => {
     const heads = new Map();
@@ -44,7 +45,7 @@ export const reconstructionClaimUnknowns = (heads, comparisonId, sourceIds) => {
         const unknown = heads.get(id);
         return unknown === undefined ? [] : [unknown];
     })
-        .sort((left, right) => left.unknown_id.localeCompare(right.unknown_id, "en"));
+        .sort((left, right) => compareUnicodeCodePoints(left.unknown_id, right.unknown_id));
 };
 /** Aggregate deterministic probes for unresolved claims. */
 export const reconstructionProbes = (results, heads) => {
@@ -57,7 +58,7 @@ export const reconstructionProbes = (results, heads) => {
         const probes = unknowns.flatMap(({ recommended_probes: items }) => items);
         const candidates = probes.length > 0 ? probes : [defaultProbe(result.kind)];
         for (const probe of candidates) {
-            const key = `${probe.operation}\0${probe.rationale}`;
+            const key = compositeKey([probe.operation, probe.rationale]);
             const current = output.get(key) ?? {
                 ...probe,
                 claim_ids: [],
@@ -71,7 +72,7 @@ export const reconstructionProbes = (results, heads) => {
             output.set(key, current);
         }
     }
-    const sorted = [...output.values()].sort((left, right) => `${left.operation}\0${left.rationale}`.localeCompare(`${right.operation}\0${right.rationale}`, "en"));
+    const sorted = [...output.values()].sort((left, right) => compareUnicodeCodePoints(compositeKey([left.operation, left.rationale]), compositeKey([right.operation, right.rationale])));
     return sorted;
 };
 const defaultProbe = (kind) => kind === "behavioral"

package/dist/domain/reconstructionVerification.js

@@ -4,6 +4,7 @@ import { z } from "zod";
 import { artifactComparisonResultSchema } from "./artifactComparison.js";
 import { artifactInventoryResultSchema } from "./artifactGraph.js";
 import { uniqueSorted } from "./canonicalOrdering.js";
+import { compareUnicodeCodePoints } from "./unicodeCodePointOrder.js";
 import { comparisonSourceEvidenceSides } from "./comparisonSourceEvidence.js";
 import { parseEvidence } from "./evidence.js";
 import { parseEvidenceBundle } from "./evidenceBundle.js";
@@ -42,7 +43,7 @@ export const verifyReconstruction = (specificationInput, bundleInput) => {
     const heads = reconstructionUnknownHeads(bundle.unknowns);
     const results = specification.claims
         .map((claim) => evaluateClaim(claim, records, heads))
-        .sort((left, right) => left.claim_id.localeCompare(right.claim_id, "en"));
+        .sort((left, right) => compareUnicodeCodePoints(left.claim_id, right.claim_id));
     const failed = count(results, "fail");
     const unresolved = count(results, "unknown");
     const probes = reconstructionProbes(results, heads);
@@ -51,7 +52,7 @@ export const verifyReconstruction = (specificationInput, bundleInput) => {
         status: failed > 0 ? "fail" : unresolved > 0 ? "unknown" : "pass",
         specification_sha256: digest({
             ...specification,
-            claims: [...specification.claims].sort((left, right) => left.claim_id.localeCompare(right.claim_id, "en")),
+            claims: [...specification.claims].sort((left, right) => compareUnicodeCodePoints(left.claim_id, right.claim_id)),
         }),
         summary: {
             total: results.length,

package/dist/domain/referenceSourceGraph.js

@@ -1,6 +1,8 @@
 import { posix } from "node:path";
 import { z } from "zod";
-import { canonicalDigest, canonicalJson } from "./comparisonSemantics.js";
+import { canonicalJson } from "./comparisonSemantics.js";
+import { digestCanonicalValue } from "./canonicalDigest.js";
+import { createReferenceSourcePathLookup, isPortableAbsoluteReferenceTarget, } from "./referenceSourcePathIdentity.js";
 import { compareUnicodeCodePoints } from "./unicodeCodePointOrder.js";
 import { digestSchema } from "./../domain/digests.js";
 import { prefixedDigestSchema } from "./../domain/digests.js";
@@ -66,13 +68,10 @@ const sourceDirectorySchema = z.strictObject({
 const symlinkTargetSchema = z
     .string()
     .min(1)
-    .refine((target) => isPortableAbsoluteSymlinkTarget(target) ||
+    .refine((target) => isPortableAbsoluteReferenceTarget(target) ||
     (!target.startsWith("/") &&
         !target.includes("\\") &&
         posix.normalize(target) === target), "Expected a normalized POSIX symlink target");
-const isPortableAbsoluteSymlinkTarget = (target) => target.startsWith("/") ||
-    /^[A-Za-z]:[\\/]/u.test(target) ||
-    /^\\\\[^\\/]+[\\/][^\\/]+/u.test(target);
 const sourceSymlinkSchema = z.union([
     z.strictObject({
         ...entryBaseShape,
@@ -104,17 +103,22 @@ const parseFailureSchema = z.strictObject({
     parser: z.string().min(1),
     reason: boundedTextSchema,
 });
-const exclusionSchema = z.strictObject({
-    path: relativePathSchema,
-    reason: z.enum([
-        "configured-secret",
-        "symlink-escape",
-        "size-limit",
-        "inventory-limit",
-        "unreadable",
-        "caller-excluded",
-    ]),
-});
+const exclusionSchema = z.discriminatedUnion("reason", [
+    z.strictObject({
+        path: relativePathSchema,
+        reason: z.enum([
+            "configured-secret",
+            "project-ignored",
+            "default-ignored",
+            "caller-excluded",
+        ]),
+        pattern: boundedTextSchema,
+    }),
+    z.strictObject({
+        path: relativePathSchema,
+        reason: z.enum(["symlink-escape", "unreadable"]),
+    }),
+]);
 const vcsSchema = z
     .discriminatedUnion("kind", [
     z.strictObject({
@@ -230,12 +234,13 @@ const checkRelationships = (graph, paths, context) => {
     }
 };
 const checkSymlinks = (graph, paths, context) => {
+    const lookupPath = createReferenceSourcePathLookup(paths);
     for (const [index, entry] of graph.entries.entries()) {
         if (entry.kind !== "symlink")
             continue;
         if (entry.target === null)
             continue;
-        const absolute = isPortableAbsoluteSymlinkTarget(entry.target);
+        const absolute = isPortableAbsoluteReferenceTarget(entry.target);
         if ((entry.target_state === "external" && !absolute) ||
             (entry.target_state === "internal" && absolute))
             context.addIssue({
@@ -246,7 +251,10 @@ const checkSymlinks = (graph, paths, context) => {
         if (entry.target_state !== "internal")
             continue;
         const resolved = posix.normalize(posix.join(posix.dirname(entry.path), entry.target));
-        if (resolved.startsWith("../") || resolved === ".." || !paths.has(resolved))
+        if (resolved.startsWith("../") ||
+            resolved === ".." ||
+            // The inventory root is implicit rather than an entry with path ".".
+            (resolved !== "." && lookupPath.resolve(resolved) === undefined))
             context.addIssue({
                 code: "custom",
                 message: "Internal symlink target must resolve to an inventoried entry",
@@ -283,7 +291,7 @@ function checkGraphInvariants(graph, context) {
     checkSortedUnique(graph.manifests, "manifests", context);
     checkSortedUnique(graph.relationships.map(relationshipKey), "relationships", context);
     checkSortedUnique(graph.parse_failures.map(historicalSourceParseFailureKey), "parse_failures", context);
-    checkSortedUnique(graph.exclusions.map(({ path, reason }) => `${path}\u0000${reason}`), "exclusions", context);
+    checkSortedUnique(graph.exclusions.map((exclusion) => `${exclusion.path}\u0000${exclusion.reason}\u0000${"pattern" in exclusion ? exclusion.pattern : ""}`), "exclusions", context);
     if (canonicalJson(graph.languages, "Reference source graph") !==
         canonicalJson(historicalSourceLanguages(graph.entries), "Reference source graph"))
         context.addIssue({
@@ -331,7 +339,7 @@ const rootCommitment = (entries, exclusions) => ({
     }),
     exclusions,
 });
-const computeRootSha256 = (entries, exclusions) => canonicalDigest(rootCommitment(entries, exclusions), "Reference source graph");
+const computeRootSha256 = (entries, exclusions) => digestCanonicalValue(rootCommitment(entries, exclusions), "Reference source graph");
 /** Build and internally commit a normalized historical source graph. */
 export const createHistoricalSourceGraph = (input) => {
     const parsed = historicalSourceGraphInputSchema.parse(input);
@@ -343,7 +351,7 @@ export const createHistoricalSourceGraph = (input) => {
 /** Parse a graph and reject stale or caller-invented root commitments. */
 export const parseHistoricalSourceGraph = (input) => historicalSourceGraphSchema.parse(input);
 /** Compute a deterministic graph commitment containing no absolute root path. */
-export const computeHistoricalSourceGraphSha256 = (input) => canonicalDigest(parseHistoricalSourceGraph(input), "Reference source graph");
+export const computeHistoricalSourceGraphSha256 = (input) => digestCanonicalValue(parseHistoricalSourceGraph(input), "Reference source graph");
 /** Build a deterministic, relocation-independent manifest for a source graph. */
 export const createHistoricalSourceManifest = (input) => {
     const graph = parseHistoricalSourceGraph(input);
@@ -358,14 +366,15 @@ export const createHistoricalSourceManifest = (input) => {
     };
     return historicalSourceManifestBaseSchema.parse({
         ...semantic,
-        manifest_id: `hsm_${canonicalDigest(semantic, "Reference source graph")}`,
+        manifest_id: `hsm_${digestCanonicalValue(semantic, "Reference source graph")}`,
     });
 };
 /** Parse and verify a historical source manifest's semantic identifier. */
 export const parseHistoricalSourceManifest = (input) => {
     const manifest = historicalSourceManifestBaseSchema.parse(input);
     const { manifest_id: manifestId, ...semantic } = manifest;
-    if (`hsm_${canonicalDigest(semantic, "Reference source graph")}` !== manifestId)
+    if (`hsm_${digestCanonicalValue(semantic, "Reference source graph")}` !==
+        manifestId)
         throw new TypeError("Historical source manifest identifier does not match");
     return manifest;
 };