rea-agents 2.2.0 → 2.4.0

package/dist/contracts/toolOutputSchemaGroups.js

@@ -18,6 +18,7 @@ import { changedBehaviorResultSchema } from "../domain/changedBehavior.js";
 import { callPathResultSchema } from "../domain/callPath.js";
 import { staticRuntimeCorrelationResultSchema } from "../domain/staticRuntimeCorrelation.js";
 import { reconstructionVerificationResultSchema } from "../domain/reconstructionVerification.js";
+import { replayMachineRunOutputSchema } from "../domain/replayMachineRun.js";
 import { analysisErrorProjectionSchema } from "./errorSchemas.js";
 import { addressList, addressedEntry, bounded, containingProcedureResolution, functionDossierOutput, graphNode, lifecycleResultOf, nullableText, pageOutput, procedureIdentity, procedureInfoOutput, evidenceResultOf as resultOf, searchPageOutput, segmentOutput, sessionProvider, providerIdentity, toolAvailability, symbolDiscoveryOutput, targetFormatSchema, targetKindSchema, } from "./toolOutputSchemaPrimitives.js";
 /** Exact structured-content schemas shared by direct analysis providers. */
@@ -271,4 +272,5 @@ export const sessionOutputSchemas = {
         truthVerified: z.boolean(),
         unknown: residualUnknownSchema,
     })),
+    run_replay_machine: lifecycleResultOf(replayMachineRunOutputSchema),
 };

package/dist/contracts/toolOutputSchemaPrimitives.js

@@ -27,6 +27,8 @@ export const targetFormatSchema = z.enum([
     "zip",
     "ipa",
     "apk",
+    "msix",
+    "appx",
     "asar",
     "dmg",
     "pkg",
@@ -44,6 +46,7 @@ const providerCapability = z.object({
     operation: z.string(),
     available: z.boolean(),
     reason: z.string().nullable(),
+    availability_code: z.enum(PROVIDER_REJECTION_CODES).nullable(),
     input_contract_version: z.number().int().min(1),
     output_contract_version: z.number().int().min(1),
     pagination: z.enum(["none", "offset", "cursor"]),
@@ -69,6 +72,45 @@ export const providerIdentity = z.object({
     name: z.string(),
     version: z.string().nullable(),
 });
+const processCoordinates = {
+    launcher_pid: z.number().int().min(1),
+    process_group_id: z.number().int().min(1),
+};
+const processLineageObservation = z.discriminatedUnion("status", [
+    z.object({
+        status: z.literal("unavailable"),
+        observed_at: z.iso.datetime(),
+        ...processCoordinates,
+        reason: z.string().min(1),
+    }),
+    z.object({
+        status: z.literal("verified"),
+        observed_at: z.iso.datetime(),
+        schema_version: z.literal(1),
+        ...processCoordinates,
+        launcher_parent_pid: z.number().int().min(0),
+        descendants: z.array(z.object({
+            pid: z.number().int().min(1),
+            parent_pid: z.number().int().min(0),
+            process_group_id: z.number().int().min(1),
+        })),
+    }),
+]);
+const analysisRun = z
+    .object({
+    run_id: z.string().uuid(),
+    process_lineage: z.discriminatedUnion("status", [
+        z.object({ status: z.literal("not_observed") }),
+        z.object({
+            status: z.literal("snapshots"),
+            snapshots: z.array(z.object({
+                provider: providerIdentity,
+                observation: processLineageObservation,
+            })),
+        }),
+    ]),
+})
+    .nullable();
 const providerRejectionCode = z.enum(PROVIDER_REJECTION_CODES);
 const providerDiagnostics = z.record(z.string(), z.json());
 const providerAvailability = z.discriminatedUnion("status", [
@@ -146,6 +188,7 @@ export const sessionProvider = z.object({
     provider: providerIdentity,
     providers: z.array(providerIdentity),
     capabilities: z.array(providerCapability),
+    analysis_run: analysisRun,
     analysis_provider_binding: z
         .object({
         provider: providerIdentity,

package/dist/doctorRuntime.js

@@ -1,12 +1,53 @@
 import { systemDoctorHost, } from "./application/Doctor.js";
+import { fileURLToPath } from "node:url";
 import { inspectSystemGhidraProvider } from "./ghidra/GhidraDoctor.js";
+import { selectLinuxPrivateDisplayStrategy } from "./hopper/LinuxPrivateDisplayProbe.js";
 import { parseConfig } from "./config.js";
 import { SystemJavaScriptReplayHost } from "./replay/SystemJavaScriptReplayHost.js";
 /** Compose provider diagnostics at the outer CLI adapter boundary. */
 export const createSystemDoctorHost = () => systemDoctorHost({
     providerInspections: async () => [await inspectSystemGhidraProvider()],
     javascriptReplayCheck: inspectJavaScriptReplay,
+    linuxDemoRuntimeCheck: inspectLinuxPrivateDisplay,
 });
+const HOPPER_DEMO_HELPER_PATH = fileURLToPath(new URL("../scripts/hopper-demo-x11.py", import.meta.url));
+const inspectLinuxPrivateDisplay = async () => {
+    const selection = await selectLinuxPrivateDisplayStrategy({
+        helperPath: HOPPER_DEMO_HELPER_PATH,
+    });
+    const value = selection.diagnostic;
+    const detail = [
+        `strategy=${selection.strategy}`,
+        `socket_directory=${value.socket_directory}`,
+        `mode=${value.socket_directory_mode ?? "unknown"}`,
+        `mount_read_only=${String(value.mount_read_only)}`,
+        `effective_mode=${value.effective_socket_directory_mode ?? "unknown"}`,
+        `effective_mount_read_only=${String(value.effective_mount_read_only)}`,
+        `wsl=${String(value.wsl)}`,
+    ].join("; ");
+    if (selection.ok)
+        return {
+            name: "hopper-demo-runtime",
+            ok: true,
+            classification: "healthy",
+            detail,
+            details: { private_display: { ...value } },
+        };
+    const missingDependency = value.failure_code === "runtime_dependency_unavailable" ||
+        value.failure_code === "x11_authorization_failed";
+    return {
+        name: "hopper-demo-runtime",
+        ok: false,
+        classification: missingDependency ? "missing_dependency" : "config_drift",
+        detail,
+        details: { private_display: { ...value } },
+        remediation: value.failure_code === "x11_socket_directory_unusable"
+            ? "Enable unprivileged user and mount namespaces, or provide a writable mode-1777 /tmp/.X11-unix directory. Do not mutate the current host mount with sudo; then rerun rea doctor --provider hopper."
+            : missingDependency
+                ? "Install Xvfb, xauth, Python 3, libX11, and libXtst, then rerun rea doctor --provider hopper."
+                : "Inspect the private-display diagnostic, correct the reported local condition, and rerun rea doctor --provider hopper.",
+    };
+};
 const inspectJavaScriptReplay = async () => {
     const config = parseConfig(process.env);
     if (!config.ok)

package/dist/domain/analysisErrorPresentation.js

@@ -5,9 +5,11 @@ export const analysisErrorRemediationAction = (error) => {
     if (error instanceof ReplayPlanStaleError)
         return "Review the rebuilt replay plan and explicitly approve its new digest.";
     if (error instanceof PermissionRequiredError)
-        return error.elicitationSupported
-            ? "Approve the exact missing scope, then retry the operation."
-            : "Add the exact missing scope beneath the administrator ceiling, then retry.";
+        return error.restartRequired
+            ? "Add the exact missing scope to the administrator configuration, then restart the registered MCP server or client."
+            : error.elicitationSupported
+                ? "Approve the exact missing scope, then retry the operation."
+                : "Add the exact missing scope beneath the administrator ceiling, then retry.";
     return analysisErrorUserMessage(error);
 };
 export const analysisErrorCategory = (error) => {

package/dist/domain/analysisErrorProjection.js

@@ -230,7 +230,13 @@ const providerErrorDetails = (error) => {
     if (error instanceof HopperRemoteError)
         return { provider_code: error.code, diagnostic_type: error.diagnosticType };
     if (error instanceof HopperProcessError && error.failureCode !== undefined)
-        return { failure_code: error.failureCode, exit_code: error.exitCode };
+        return {
+            failure_code: error.failureCode,
+            exit_code: error.exitCode,
+            ...(error.diagnostic === undefined
+                ? {}
+                : { diagnostics: { ...error.diagnostic } }),
+        };
     return undefined;
 };
 const lifecycleErrorDetails = (error) => {

package/dist/domain/analysisSnapshot.js

@@ -15,6 +15,8 @@ const formatSchema = z.enum([
     "zip",
     "ipa",
     "apk",
+    "msix",
+    "appx",
     "asar",
     "dmg",
     "pkg",

package/dist/domain/artifactGraph.js

@@ -45,6 +45,8 @@ const artifactFormatSchema = z.enum([
     "analysis-database",
     "ipa",
     "apk",
+    "msix",
+    "appx",
     "plist",
     "entitlements",
     "directory",

package/dist/domain/binaryTarget.js

@@ -6,6 +6,7 @@ import { extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { promisify } from "node:util";
 import { BinaryTargetError } from "./errors.js";
 import { err, ok } from "./result.js";
+import { zipPackageFormatForPath } from "./zipPackageFormat.js";
 const execFileAsync = promisify(execFile);
 /**
  * Resolve and classify a readable local target before a provider is selected.
@@ -71,11 +72,7 @@ const detectArtifactFormat = async (path, handle) => {
         magic[1] === 0x4b &&
         [0x03, 0x05, 0x07].includes(magic[2] ?? -1) &&
         [0x04, 0x06, 0x08].includes(magic[3] ?? -1)) {
-        return lower.endsWith(".ipa")
-            ? "ipa"
-            : lower.endsWith(".apk")
-                ? "apk"
-                : "zip";
+        return zipPackageFormatForPath(lower) ?? "zip";
     }
     const named = namedArtifactFormat(lower);
     if (named !== undefined)
@@ -104,7 +101,7 @@ const namedArtifactFormat = (lowerPath) => {
         return "source-map";
     return /\.(?:m?js|cjs)$/u.test(lowerPath) ? "javascript" : undefined;
 };
-const isArchiveFormat = (format) => ["zip", "ipa", "apk", "asar", "dmg", "pkg"].includes(format);
+const isArchiveFormat = (format) => ["zip", "ipa", "apk", "msix", "appx", "asar", "dmg", "pkg"].includes(format);
 const sha256Handle = async (handle) => {
     const hash = createHash("sha256");
     const chunk = Buffer.allocUnsafe(64 * 1024);

package/dist/domain/changedBehavior.js

@@ -63,24 +63,25 @@ export const changedBehaviorResultSchema = z.object({
 });
 const EXPECTED_PROVIDERS = {
     compare_process_captures: {
-        predicate: "rea.process-comparison/v3",
+        predicates: ["rea.process-comparison/v3", "rea.process-comparison/v4"],
         id: "rea-process",
         name: "REA deterministic process harness",
         version: "3",
     },
     compare_artifacts: {
-        predicate: "rea.artifact-comparison/v1",
+        predicates: ["rea.artifact-comparison/v1"],
         id: "rea-artifact-comparison",
         name: "REA artifact comparison",
         version: "1",
     },
     compare_functions: {
-        predicate: "rea.function-comparison/v1",
+        predicates: ["rea.function-comparison/v1"],
         id: "rea-function-comparison",
         name: "REA function comparison",
         version: "1",
     },
 };
+const acceptsPredicate = (expected, actual) => expected.some((predicate) => predicate === actual);
 /** Find observed runtime changes and separately report static change candidates. */
 export const findChangedBehavior = (comparisonsInput, offset, limit) => {
     const parsedInput = changedBehaviorInputSchema.parse({
@@ -141,7 +142,7 @@ const parseComparisonEvidence = (input) => {
     ])
         .parse(evidence.operation);
     const expected = EXPECTED_PROVIDERS[operation];
-    if (evidence.predicate_type !== expected.predicate ||
+    if (!acceptsPredicate(expected.predicates, evidence.predicate_type) ||
         evidence.provider.id !== expected.id ||
         evidence.provider.name !== expected.name ||
         evidence.provider.version !== expected.version ||

package/dist/domain/completionLedgerGeneration.js

@@ -0,0 +1,190 @@
+import { createHash } from "node:crypto";
+import canonicalize from "canonicalize";
+import { z } from "zod";
+import { createEvidenceCompletionLedger, evidenceCompletionRecordSchema, } from "./evidenceCompletionLedger.js";
+const identifierSchema = z.string().regex(/^[A-Za-z][A-Za-z0-9._-]{0,99}$/u);
+const digestSchema = z.string().regex(/^[a-f0-9]{64}$/u);
+const identitySchema = z.strictObject({
+    id: identifierSchema,
+    version: z.string().min(1).max(100),
+});
+const environmentSchema = z.strictObject({
+    platform: identifierSchema,
+    architecture: identifierSchema,
+    runtime: identifierSchema,
+    runtime_version: z.string().min(1).max(100),
+});
+const scenarioSchema = z.strictObject({
+    id: identifierSchema,
+    version: z.number().int().positive(),
+});
+const skillDigestSchema = z.strictObject({
+    skill_id: identifierSchema,
+    sha256: digestSchema,
+});
+const verifierRunSchema = z
+    .strictObject({
+    schema_version: z.literal(1),
+    run_id: z.string().uuid(),
+    verifier_pid: z.number().int().positive(),
+    parent_pid: z.number().int().nonnegative(),
+    process_lineage: z.discriminatedUnion("status", [
+        z.strictObject({
+            status: z.literal("verified"),
+            schema_version: z.literal(1),
+            observed_at: z.iso.datetime(),
+            launcher_pid: z.number().int().positive(),
+            launcher_parent_pid: z.number().int().nonnegative(),
+            process_group_id: z.number().int().positive(),
+            descendants: z.array(z.strictObject({
+                pid: z.number().int().positive(),
+                parent_pid: z.number().int().nonnegative(),
+                process_group_id: z.number().int().positive(),
+            })),
+        }),
+        z.strictObject({
+            status: z.literal("unavailable"),
+            observed_at: z.iso.datetime(),
+            launcher_pid: z.number().int().positive(),
+            launcher_parent_pid: z.number().int().nonnegative(),
+            process_group_id: z.number().int().positive().nullable(),
+            reason: z.string().min(1).max(500),
+        }),
+    ]),
+})
+    .superRefine((run, context) => {
+    if (run.process_lineage.launcher_pid !== run.verifier_pid)
+        context.addIssue({
+            code: "custom",
+            path: ["process_lineage", "launcher_pid"],
+            message: "Lineage launcher PID must identify the verifier process",
+        });
+    if (run.process_lineage.launcher_parent_pid !== run.parent_pid)
+        context.addIssue({
+            code: "custom",
+            path: ["process_lineage", "launcher_parent_pid"],
+            message: "Lineage parent PID must identify the verifier parent",
+        });
+});
+const reportClaimSchema = z.strictObject({
+    claim_id: identifierSchema,
+    scenario: scenarioSchema,
+    artifact_sha256s: z.array(digestSchema).max(100),
+    provider: identitySchema,
+    result_schema_version: z.number().int().positive(),
+    status: evidenceCompletionRecordSchema.shape.status,
+    evidence_ids: evidenceCompletionRecordSchema.shape.evidence_ids,
+});
+const completionVerifierReportObjectSchema = z.strictObject({
+    schema_version: z.literal(1),
+    verifier: identitySchema,
+    verifier_run: verifierRunSchema,
+    environment: environmentSchema,
+    claims: z.array(reportClaimSchema).min(1).max(10_000),
+});
+/** Strict output contract implemented by completion-aware verifiers. */
+export const completionVerifierReportSchema = completionVerifierReportObjectSchema.superRefine((report, context) => {
+    for (const [index, claim] of report.claims.entries())
+        if (claim.status === "pass" && claim.artifact_sha256s.length === 0)
+            context.addIssue({
+                code: "custom",
+                path: ["claims", index, "artifact_sha256s"],
+                message: "Passing claims must commit at least one artifact digest",
+            });
+});
+const manifestClaimSchema = reportClaimSchema.omit({
+    status: true,
+    evidence_ids: true,
+});
+const completionManifestObjectSchema = z.strictObject({
+    schema_version: z.literal(1),
+    manifest_id: z.string().regex(/^ecm_[a-f0-9]{64}$/u),
+    verifier: identitySchema,
+    environment: environmentSchema,
+    skill_digests: z.array(skillDigestSchema).min(1).max(100),
+    claims: z.array(manifestClaimSchema).min(1).max(10_000),
+});
+const compareIdentifiers = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+const isSortedUnique = (values) => values.every((value, index) => index === 0 || compareIdentifiers(values[index - 1] ?? "", value) < 0);
+const canonicalJson = (value) => {
+    const serialized = canonicalize(value);
+    if (serialized === undefined)
+        throw new TypeError("RFC 8785 canonicalization rejected completion metadata");
+    return serialized;
+};
+const computeManifestId = (manifest) => `ecm_${createHash("sha256").update(canonicalJson(manifest)).digest("hex")}`;
+const manifestIssues = (manifest, context) => {
+    if (!isSortedUnique(manifest.claims.map(({ claim_id }) => claim_id)))
+        context.addIssue({
+            code: "custom",
+            path: ["claims"],
+            message: "Manifest claims must be sorted by unique claim ID",
+        });
+    if (!isSortedUnique(manifest.skill_digests.map(({ skill_id }) => skill_id)))
+        context.addIssue({
+            code: "custom",
+            path: ["skill_digests"],
+            message: "Skill digests must be sorted by unique skill ID",
+        });
+    for (const [index, claim] of manifest.claims.entries())
+        if (!isSortedUnique(claim.artifact_sha256s))
+            context.addIssue({
+                code: "custom",
+                path: ["claims", index, "artifact_sha256s"],
+                message: "Artifact digests must be sorted and unique",
+            });
+    const { manifest_id: manifestId, ...projection } = manifest;
+    if (computeManifestId(projection) !== manifestId)
+        context.addIssue({
+            code: "custom",
+            path: ["manifest_id"],
+            message: "Completion manifest identifier does not match its content",
+        });
+};
+/** Canonical immutable commitments for one verifier run. */
+export const completionManifestSchema = completionManifestObjectSchema.superRefine(manifestIssues);
+const canonicalClaims = (claims) => claims
+    .map((claim) => ({
+    ...claim,
+    artifact_sha256s: [...claim.artifact_sha256s].sort(compareIdentifiers),
+    evidence_ids: [...claim.evidence_ids].sort(compareIdentifiers),
+}))
+    .sort((left, right) => compareIdentifiers(left.claim_id, right.claim_id));
+/** Generate canonical manifest and ledger artifacts from live verifier output. */
+export const createCompletionLedgerArtifacts = (input, skillDigests) => {
+    const report = completionVerifierReportSchema.parse(input);
+    const claims = canonicalClaims(report.claims);
+    if (!isSortedUnique(claims.map(({ claim_id }) => claim_id)))
+        throw new TypeError("Completion verifier claim IDs must be unique");
+    for (const claim of claims) {
+        if (!isSortedUnique(claim.artifact_sha256s))
+            throw new TypeError("Artifact digests must be unique per claim");
+        if (!isSortedUnique(claim.evidence_ids))
+            throw new TypeError("Evidence IDs must be unique per claim");
+    }
+    const skills = skillDigests
+        .map((skill) => skillDigestSchema.parse(skill))
+        .sort((left, right) => compareIdentifiers(left.skill_id, right.skill_id));
+    if (!isSortedUnique(skills.map(({ skill_id }) => skill_id)))
+        throw new TypeError("Completion skill IDs must be unique");
+    const projection = {
+        schema_version: 1,
+        verifier: report.verifier,
+        environment: report.environment,
+        skill_digests: skills,
+        claims: claims.map(({ status: _status, evidence_ids: _evidenceIds, ...claim }) => claim),
+    };
+    return {
+        manifest: completionManifestSchema.parse({
+            ...projection,
+            manifest_id: computeManifestId(projection),
+        }),
+        ledger: createEvidenceCompletionLedger(claims.map(({ claim_id, status, evidence_ids }) => ({
+            claim_id,
+            status,
+            evidence_ids,
+        }))),
+    };
+};
+/** Parse generated completion commitments and reject manual tampering. */
+export const parseCompletionManifest = (input) => completionManifestSchema.parse(input);

package/dist/domain/errors.js

@@ -1,5 +1,5 @@
 import { hopperStartupFailure, } from "./hopperStartupFailure.js";
-export { hopperStartupFailure };
+export { hopperStartupFailure, };
 export { projectAnalysisError } from "./analysisErrorProjection.js";
 /** Stable tags exposed by safe analysis-error projections. */
 const ANALYSIS_ERROR_TAGS = [
@@ -292,12 +292,14 @@ export class HopperRemoteError extends HopperError {
 /** The owned Hopper bridge stopped before its client was closed. */
 export class HopperProcessError extends HopperError {
     exitCode;
+    diagnostic;
     _tag = "HopperProcessError";
     failureCode;
     userMessage;
-    constructor(exitCode) {
+    constructor(exitCode, diagnostic) {
         super(`Hopper bridge stopped unexpectedly with code ${String(exitCode)}`);
         this.exitCode = exitCode;
+        this.diagnostic = diagnostic;
         const failure = hopperStartupFailure(exitCode);
         this.failureCode = failure?.code;
         this.userMessage = failure?.message;

package/dist/domain/evidence.js

@@ -22,6 +22,8 @@ const subjectSchema = z.object({
         "zip",
         "ipa",
         "apk",
+        "msix",
+        "appx",
         "asar",
         "dmg",
         "pkg",

package/dist/domain/evidenceCompletionLedger.js

@@ -0,0 +1,113 @@
+import { createHash } from "node:crypto";
+import canonicalize from "canonicalize";
+import { z } from "zod";
+const evidenceIdSchema = z.string().regex(/^ev_[a-f0-9]{64}$/u);
+const claimIdSchema = z.string().regex(/^[A-Za-z][A-Za-z0-9._-]{0,99}$/u);
+/** Terminal outcome recorded for one verifier claim. */
+export const evidenceCompletionStatusSchema = z.enum([
+    "pass",
+    "fail",
+    "unsupported",
+    "truncated",
+    "unknown",
+]);
+/** Strict evidence-linked result for one verifier claim. */
+export const evidenceCompletionRecordSchema = z.strictObject({
+    claim_id: claimIdSchema,
+    status: evidenceCompletionStatusSchema,
+    evidence_ids: z.array(evidenceIdSchema).min(1).max(100),
+});
+const completionSummarySchema = z.strictObject({
+    total: z.number().int().min(1).max(10_000),
+    pass: z.number().int().nonnegative(),
+    fail: z.number().int().nonnegative(),
+    unsupported: z.number().int().nonnegative(),
+    truncated: z.number().int().nonnegative(),
+    unknown: z.number().int().nonnegative(),
+    complete: z.boolean(),
+});
+const completionLedgerObjectSchema = z.strictObject({
+    schema_version: z.literal(1),
+    ledger_id: z.string().regex(/^ecl_[a-f0-9]{64}$/u),
+    records: z.array(evidenceCompletionRecordSchema).min(1).max(10_000),
+    summary: completionSummarySchema,
+});
+const compareIdentifiers = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+const isSortedUnique = (values) => values.every((value, index) => index === 0 || compareIdentifiers(values[index - 1] ?? "", value) < 0);
+const summarize = (records) => {
+    const counts = {
+        pass: 0,
+        fail: 0,
+        unsupported: 0,
+        truncated: 0,
+        unknown: 0,
+    };
+    for (const record of records)
+        counts[record.status] += 1;
+    return {
+        total: records.length,
+        ...counts,
+        complete: counts.pass === records.length,
+    };
+};
+const canonicalJson = (value) => {
+    const serialized = canonicalize(value);
+    if (serialized === undefined)
+        throw new TypeError("RFC 8785 canonicalization rejected the completion ledger");
+    return serialized;
+};
+const computeLedgerId = (records) => `ecl_${createHash("sha256")
+    .update(canonicalJson({ schema_version: 1, records }))
+    .digest("hex")}`;
+const ledgerIssues = (ledger, context) => {
+    if (!isSortedUnique(ledger.records.map((record) => record.claim_id)))
+        context.addIssue({
+            code: "custom",
+            path: ["records"],
+            message: "Completion records must be sorted by unique claim ID",
+        });
+    for (const [index, record] of ledger.records.entries())
+        if (!isSortedUnique(record.evidence_ids))
+            context.addIssue({
+                code: "custom",
+                path: ["records", index, "evidence_ids"],
+                message: "Evidence IDs must be sorted and unique",
+            });
+    if (JSON.stringify(summarize(ledger.records)) !== JSON.stringify(ledger.summary))
+        context.addIssue({
+            code: "custom",
+            path: ["summary"],
+            message: "Completion summary does not match its records",
+        });
+    if (computeLedgerId(ledger.records) !== ledger.ledger_id)
+        context.addIssue({
+            code: "custom",
+            path: ["ledger_id"],
+            message: "Completion ledger identifier does not match its records",
+        });
+};
+/** Strict path-free Evidence v2 completion ledger. */
+export const evidenceCompletionLedgerSchema = completionLedgerObjectSchema.superRefine(ledgerIssues);
+/** Build a canonical path-independent ledger from verifier claim outcomes. */
+export const createEvidenceCompletionLedger = (input) => {
+    const records = input
+        .map((record) => evidenceCompletionRecordSchema.parse(record))
+        .map((record) => ({
+        ...record,
+        evidence_ids: [...record.evidence_ids].sort(compareIdentifiers),
+    }))
+        .sort((left, right) => compareIdentifiers(left.claim_id, right.claim_id));
+    if (!isSortedUnique(records.map((record) => record.claim_id)))
+        throw new TypeError("Completion claim IDs must be unique");
+    for (const record of records)
+        if (!isSortedUnique(record.evidence_ids))
+            throw new TypeError("Completion Evidence IDs must be unique per claim");
+    return evidenceCompletionLedgerSchema.parse({
+        schema_version: 1,
+        ledger_id: computeLedgerId(records),
+        records,
+        summary: summarize(records),
+    });
+};
+/** Parse a completion ledger and reject non-canonical or tampered content. */
+export const parseEvidenceCompletionLedger = (input) => evidenceCompletionLedgerSchema.parse(input);

package/dist/domain/hopperStartupFailure.js

@@ -49,7 +49,16 @@ const failures = [
         "runtime_dependency_unavailable",
         "A Linux demo-session dependency is unavailable. Rerun rea setup --yes --install-hopper, then rea doctor.",
     ],
+    [
+        80,
+        "x11_socket_directory_unusable",
+        "REA cannot use the host X11 socket directory for a private display. Run rea doctor --provider hopper for exact mount and namespace diagnostics.",
+    ],
 ];
 const HOPPER_STARTUP_FAILURES = new Map(failures.map(([exitCode, code, message]) => [exitCode, { code, message }]));
 /** Return the stable public failure associated with a Linux demo adapter exit. */
 export const hopperStartupFailure = (exitCode) => exitCode === null ? undefined : HOPPER_STARTUP_FAILURES.get(exitCode);
+/** Return the adapter exit associated with one stable startup failure code. */
+export const hopperStartupExitCode = (code) => failures.find(([, candidate]) => candidate === code)?.[0];
+/** Narrow an untrusted diagnostic field to the public startup code union. */
+export const isHopperStartupFailureCode = (value) => failures.some(([, candidate]) => candidate === value);