rea-agents 2.1.0 → 2.3.0

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/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);

package/dist/domain/javascriptApplicationAnalysis.js

@@ -1,6 +1,7 @@
 import { isAbsolute } from "node:path";
 import { z } from "zod";
 import { javascriptApplicationGraphSchema } from "./javascriptApplicationGraph.js";
+import { javaScriptSemanticGraphSchema } from "./javascriptSemanticGraph.js";
 const MAX_GRAPH_NODES = 100_000;
 const MAX_GRAPH_EDGES = 200_000;
 const countSchema = z.number().int().min(0).max(Number.MAX_SAFE_INTEGER);
@@ -140,8 +141,8 @@ const reconstructionStatisticsSchema = z.strictObject({
     parse_failures: countSchema,
     truncated_scopes: countSchema,
 });
-/** Strict high-level result returned inside Evidence v2. */
-export const javascriptApplicationAnalysisResultSchema = z.strictObject({
+/** Legacy structural JavaScript application analysis result. */
+export const javaScriptApplicationAnalysisResultV1Schema = z.strictObject({
     schema_version: z.literal(1),
     input_path: z.string().min(1).max(16_384),
     format: z.enum(["asar", "directory"]),
@@ -153,3 +154,44 @@ export const javascriptApplicationAnalysisResultSchema = z.strictObject({
     statistics: reconstructionStatisticsSchema,
     limitations: z.array(z.string().min(1).max(4_096)).max(1_000),
 });
+/** JavaScript application analysis with an authenticated semantic companion. */
+export const javaScriptApplicationAnalysisResultV2Schema = javaScriptApplicationAnalysisResultV1Schema
+    .extend({
+    schema_version: z.literal(2),
+    semantic_graph: javaScriptSemanticGraphSchema,
+})
+    .superRefine((result, context) => {
+    if (result.semantic_graph.application_graph_id !== result.graph.graph_id)
+        context.addIssue({
+            code: "custom",
+            path: ["semantic_graph", "application_graph_id"],
+            message: "Semantic graph must commit the containing application graph",
+        });
+    if (result.semantic_graph.root_artifact_sha256 !==
+        result.root_artifact_sha256)
+        context.addIssue({
+            code: "custom",
+            path: ["semantic_graph", "root_artifact_sha256"],
+            message: "Semantic graph must commit the containing root artifact",
+        });
+    const applicationNodeIds = new Set(result.graph.nodes.map(({ node_id }) => node_id));
+    for (const [nodeIndex, node] of result.semantic_graph.nodes.entries())
+        for (const [identifierIndex, identifier,] of node.application_node_ids.entries())
+            if (!applicationNodeIds.has(identifier))
+                context.addIssue({
+                    code: "custom",
+                    path: [
+                        "semantic_graph",
+                        "nodes",
+                        nodeIndex,
+                        "application_node_ids",
+                        identifierIndex,
+                    ],
+                    message: "Semantic node references an absent application node",
+                });
+});
+/** Strict versioned high-level result returned inside Evidence v2. */
+export const javascriptApplicationAnalysisResultSchema = z.discriminatedUnion("schema_version", [
+    javaScriptApplicationAnalysisResultV1Schema,
+    javaScriptApplicationAnalysisResultV2Schema,
+]);

package/dist/domain/javascriptExportShapeComparison.js

@@ -0,0 +1,145 @@
+import { compareCodePoints } from "./javascriptApplicationGraph.js";
+import { digestExportShapeValue } from "./javascriptExportShapeComparisonIdentity.js";
+import { javaScriptExportShapeComparisonResultSchema, } from "./javascriptExportShapeComparisonSchemas.js";
+import { retainJavaScriptExportShapes, selectJavaScriptExport, } from "./javascriptExportShapeSelection.js";
+import { buildJavaScriptExportShapeChanges, compareJavaScriptExportShapeChanges, hasPartialJavaScriptExportPropertyCoverage, pairJavaScriptExportShapeVariants, } from "./javascriptExportShapeVariants.js";
+/** Compare exact selected export return shapes without executing JavaScript. */
+export const compareJavaScriptExportShapes = (input) => {
+    const left = selectJavaScriptExport(input.left, input.limits.max_candidate_exports);
+    const right = selectJavaScriptExport(input.right, input.limits.max_candidate_exports);
+    const leftRetained = retainJavaScriptExportShapes(left, input.limits.max_return_variants);
+    const rightRetained = retainJavaScriptExportShapes(right, input.limits.max_return_variants);
+    const pairing = pairJavaScriptExportShapeVariants(leftRetained.shapes, rightRetained.shapes);
+    const evidenceLinks = evidencePair(input.left.evidenceId, input.right.evidenceId);
+    const allChanges = buildJavaScriptExportShapeChanges({
+        leftSelection: left,
+        rightSelection: right,
+        pairing,
+        leftShapes: leftRetained.shapes,
+        rightShapes: rightRetained.shapes,
+        evidenceLinks,
+    }).sort(compareJavaScriptExportShapeChanges);
+    const changes = allChanges.slice(0, input.limits.max_changes);
+    const omittedChanges = allChanges.length - changes.length;
+    const coverage = comparisonCoverage({
+        input,
+        left,
+        right,
+        leftRetained,
+        rightRetained,
+        pairing,
+        allChanges,
+        omittedChanges,
+    });
+    const limitations = comparisonLimitations(left, right, coverage.status);
+    const semantic = {
+        schema_version: 1,
+        left: left.selection,
+        right: right.selection,
+        summary: summarize(allChanges),
+        changes,
+        coverage,
+        evidence_links: evidenceLinks,
+        limitations,
+        runtime_validation: {
+            recommended_tool: "run_controlled_replay",
+            automatically_started: false,
+            required_for: "runtime-semantics",
+        },
+    };
+    return javaScriptExportShapeComparisonResultSchema.parse({
+        ...semantic,
+        comparison_id: `jesc_${digestExportShapeValue(semantic)}`,
+    });
+};
+const comparisonCoverage = (context) => {
+    const leftSource = context.left.projection?.return_shape_coverage;
+    const rightSource = context.right.projection?.return_shape_coverage;
+    const omittedCandidates = context.left.selection.omitted_candidates +
+        context.right.selection.omitted_candidates;
+    const truncated = comparisonTruncated(context, omittedCandidates);
+    const partial = comparisonPartial(context);
+    return {
+        status: truncated
+            ? "truncated"
+            : partial
+                ? "partial"
+                : "complete-within-inputs",
+        left_graph_status: context.input.left.graph.coverage.status,
+        right_graph_status: context.input.right.graph.coverage.status,
+        paired_variants: context.pairing.pairs.length,
+        unpaired_left_variants: context.pairing.unpairedLeft.length,
+        unpaired_right_variants: context.pairing.unpairedRight.length,
+        omitted_left_variants: context.leftRetained.omitted,
+        omitted_right_variants: context.rightRetained.omitted,
+        left_source_omitted_variants: leftSource?.omitted_return_sites ?? null,
+        right_source_omitted_variants: rightSource?.omitted_return_sites ?? null,
+        left_omitted_fields: leftSource?.omitted_fields ?? 0,
+        right_omitted_fields: rightSource?.omitted_fields ?? 0,
+        left_omitted_property_coverage: leftSource?.omitted_property_coverage ?? 0,
+        right_omitted_property_coverage: rightSource?.omitted_property_coverage ?? 0,
+        omitted_candidates: omittedCandidates,
+        omitted_changes: context.omittedChanges,
+    };
+};
+const comparisonTruncated = (context, omittedCandidates) => context.leftRetained.omitted > 0 ||
+    context.rightRetained.omitted > 0 ||
+    omittedCandidates > 0 ||
+    context.omittedChanges > 0 ||
+    sourceProjectionTruncated(context.left) ||
+    sourceProjectionTruncated(context.right);
+const sourceProjectionTruncated = (selection) => {
+    const coverage = selection.projection?.return_shape_coverage;
+    if (coverage === undefined)
+        return false;
+    return (coverage.status === "truncated" ||
+        coverage.omitted_fields > 0 ||
+        coverage.omitted_property_coverage > 0 ||
+        coverage.projection_complete === false);
+};
+const comparisonPartial = (context) => selectionPartial(context.left) ||
+    selectionPartial(context.right) ||
+    context.input.left.graph.coverage.status !== "complete" ||
+    context.input.right.graph.coverage.status !== "complete" ||
+    hasPartialJavaScriptExportPropertyCoverage(context.leftRetained.shapes) ||
+    hasPartialJavaScriptExportPropertyCoverage(context.rightRetained.shapes) ||
+    context.pairing.unpairedLeft.length > 0 ||
+    context.pairing.unpairedRight.length > 0 ||
+    context.allChanges.some(({ status }) => status === "unknown");
+const selectionPartial = (selection) => {
+    const coverage = selection.projection?.return_shape_coverage;
+    return (selection.selection.status !== "selected" ||
+        !selection.observationComplete ||
+        coverage?.status !== "complete" ||
+        coverage.projection_complete !== true);
+};
+const comparisonLimitations = (left, right, status) => uniqueSorted([
+    "Return shapes are inferred from inert syntax and do not prove runtime behavior.",
+    "Return variants are paired only by unique exact literal discriminants, never by source order.",
+    "Dynamic values, incomplete object coverage, and ambiguous variants remain unknown.",
+    "Controlled replay is recommended separately for runtime semantics and was not started.",
+    ...left.limitations,
+    ...right.limitations,
+    ...(status === "truncated"
+        ? [
+            "Comparison output or source return-shape recovery reached an explicit limit.",
+        ]
+        : []),
+    ...(status === "partial"
+        ? [
+            "At least one selector, graph, return shape, or property boundary is incomplete.",
+        ]
+        : []),
+]);
+const summarize = (changes) => ({
+    added: countStatus(changes, "added"),
+    removed: countStatus(changes, "removed"),
+    changed: countStatus(changes, "changed"),
+    unknown: countStatus(changes, "unknown"),
+});
+const countStatus = (changes, status) => changes.filter((change) => change.status === status).length;
+const evidencePair = (left, right) => [
+    left,
+    right,
+];
+const uniqueSorted = (values) => [...new Set(values)].sort(compareCodePoints);

package/dist/domain/javascriptExportShapeComparisonIdentity.js

@@ -0,0 +1,11 @@
+import { createHash } from "node:crypto";
+import canonicalize from "canonicalize";
+/** Canonically encode one export-shape comparison value. */
+export const canonicalExportShapeValue = (value) => {
+    const encoded = canonicalize(value);
+    if (encoded === undefined)
+        throw new TypeError("JavaScript export shape comparison could not canonicalize data");
+    return encoded;
+};
+/** Derive one deterministic SHA-256 comparison identifier component. */
+export const digestExportShapeValue = (value) => createHash("sha256").update(canonicalExportShapeValue(value)).digest("hex");