rea-agents 6.4.0 → 6.5.0

package/dist/domain/referenceSourceGraph.js

@@ -11,7 +11,7 @@ const relativePathSchema = z
     .string()
     .min(1)
     .refine((path) => !path.startsWith("/") &&
-    !path.includes("\\") &&
+    !path.includes("\0") &&
     path
         .split("/")
         .every((part) => part !== "" && part !== "." && part !== ".."), "Expected a normalized relative POSIX path without traversal");
@@ -68,10 +68,9 @@ const sourceDirectorySchema = z.strictObject({
 const symlinkTargetSchema = z
     .string()
     .min(1)
-    .refine((target) => isPortableAbsoluteReferenceTarget(target) ||
-    (!target.startsWith("/") &&
-        !target.includes("\\") &&
-        posix.normalize(target) === target), "Expected a normalized POSIX symlink target");
+    .refine((target) => !target.includes("\0") &&
+    (isPortableAbsoluteReferenceTarget(target) ||
+        (!target.startsWith("/") && posix.normalize(target) === target)), "Expected a normalized POSIX symlink target");
 const sourceSymlinkSchema = z.union([
     z.strictObject({
         ...entryBaseShape,
@@ -90,6 +89,10 @@ const sourceEntrySchema = z.union([
     sourceFileSchema,
     sourceDirectorySchema,
     sourceSymlinkSchema,
+    z.strictObject({
+        ...entryBaseShape,
+        kind: z.literal("unknown"),
+    }),
 ]);
 const sourceRelationshipSchema = z.strictObject({
     from_path: relativePathSchema,
@@ -106,6 +109,9 @@ const parseFailureSchema = z.strictObject({
 const exclusionSchema = z.discriminatedUnion("reason", [
     z.strictObject({
         path: relativePathSchema,
+        entry_kind: z
+            .enum(["file", "directory", "symlink", "other", "unknown"])
+            .exactOptional(),
         reason: z.enum([
             "configured-secret",
             "project-ignored",
@@ -116,6 +122,9 @@ const exclusionSchema = z.discriminatedUnion("reason", [
     }),
     z.strictObject({
         path: relativePathSchema,
+        entry_kind: z
+            .enum(["file", "directory", "symlink", "other", "unknown"])
+            .exactOptional(),
         reason: z.enum(["symlink-escape", "unreadable"]),
     }),
 ]);
@@ -235,12 +244,39 @@ const checkRelationships = (graph, paths, context) => {
 };
 const checkSymlinks = (graph, paths, context) => {
     const lookupPath = createReferenceSourcePathLookup(paths);
+    const excludedPaths = createReferenceSourcePathLookup(graph.exclusions.map(({ path }) => path));
+    const excludedKinds = new Map();
+    for (const { path, entry_kind } of graph.exclusions) {
+        const kinds = excludedKinds.get(path) ?? new Set();
+        kinds.add(entry_kind);
+        excludedKinds.set(path, kinds);
+    }
     for (const [index, entry] of graph.entries.entries()) {
         if (entry.kind !== "symlink")
             continue;
         if (entry.target === null)
             continue;
-        const absolute = isPortableAbsoluteReferenceTarget(entry.target);
+        const resolved = posix.normalize(posix.join(posix.dirname(entry.path), entry.target));
+        const escapesRoot = resolved.startsWith("../") || resolved === "..";
+        // The root is implicit; every other internal target needs an exact or
+        // uniquely Unicode-equivalent recorded inventory identity.
+        const inventoried = resolved === "." || lookupPath.resolve(resolved) !== undefined;
+        const exactExcluded = excludedPaths.resolve(resolved);
+        let excluded = exactExcluded !== undefined;
+        for (let candidate = posix.dirname(resolved); candidate !== "." && candidate !== "/"; candidate = posix.dirname(candidate)) {
+            const excludedAncestor = excludedPaths.resolve(candidate);
+            if (excludedAncestor === undefined)
+                continue;
+            const kinds = excludedKinds.get(excludedAncestor);
+            if (kinds?.size !== 1 || !kinds.has("directory")) {
+                excluded = false;
+                break;
+            }
+            excluded = true;
+        }
+        const ownedRelativeTarget = !entry.target.startsWith("/") && !escapesRoot && inventoried;
+        const absolute = isPortableAbsoluteReferenceTarget(entry.target) &&
+            !(entry.target_state === "internal" && ownedRelativeTarget);
         if ((entry.target_state === "external" && !absolute) ||
             (entry.target_state === "internal" && absolute))
             context.addIssue({
@@ -250,14 +286,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 === ".." ||
-            // The inventory root is implicit rather than an entry with path ".".
-            (resolved !== "." && lookupPath.resolve(resolved) === undefined))
+        if (escapesRoot || (!inventoried && !excluded))
             context.addIssue({
                 code: "custom",
-                message: "Internal symlink target must resolve to an inventoried entry",
+                message: "Internal symlink target must resolve to an inventoried entry or a recorded exclusion",
                 path: ["entries", index, "target"],
             });
     }
@@ -268,7 +300,8 @@ const checkCompleteInventory = (graph, context) => {
     const partialEntry = graph.entries.some((entry) => entry.limitations.length > 0 ||
         (entry.kind === "file" && entry.content_state !== "hashed") ||
         (entry.kind === "directory" && entry.tree_state !== "enumerated") ||
-        (entry.kind === "symlink" && entry.target_state !== "internal"));
+        (entry.kind === "symlink" && entry.target_state !== "internal") ||
+        entry.kind === "unknown");
     const partialRelationship = graph.relationships.some(({ parse_state, resolution }) => parse_state !== "parsed" ||
         ["unresolved", "unknown"].includes(resolution));
     if (!partialEntry &&
@@ -335,6 +368,11 @@ const rootCommitment = (entries, exclusions) => ({
                     target: entry.target,
                     target_state: entry.target_state,
                 };
+            case "unknown":
+                return {
+                    kind: entry.kind,
+                    path: entry.path,
+                };
         }
     }),
     exclusions,

package/dist/domain/referenceSourceImportParsing.js

@@ -1,19 +1,18 @@
-import { parse } from "@babel/parser";
 import { traverseJavaScriptAst } from "./javascript/javascriptSemanticTraversal.js";
-import { parserPluginsForPath } from "./javascript/javascriptSourceParser.js";
+import { parseRecoveredJavaScript, parserPluginsForPath, } from "./javascript/javascriptSourceParser.js";
 import { unshadowedReferenceSourceRequireCalls } from "./referenceSourceRequireBindings.js";
+import { isRelativeJavaScriptModuleSpecifier } from "./javascript/javascriptModuleSpecifier.js";
 import { isCallExpression, isExportAllDeclaration, isExportNamedDeclaration, isIdentifier, isImport, isImportDeclaration, isImportExpression, isMemberExpression, isStringLiteral, isTSExternalModuleReference, isTSImportEqualsDeclaration, isTSModuleDeclaration, } from "@babel/types";
-const codeSourceLanguages = new Set(["JavaScript", "TypeScript", "JSX", "TSX"]);
+export const PARSEABLE_REFERENCE_SOURCE_LANGUAGES = new Set(["JavaScript", "TypeScript", "JSX", "TSX"]);
 const safeModuleName = (node) => {
     if (isStringLiteral(node))
         return node.value;
     return undefined;
 };
 const resolveSpecifier = (specifier) => {
-    if (specifier.startsWith(".") || specifier.startsWith("/"))
+    if (isRelativeJavaScriptModuleSpecifier(specifier) ||
+        specifier.startsWith("/"))
         return "internal";
-    if (specifier.startsWith("node:") || specifier.startsWith("data:"))
-        return "external";
     return "external";
 };
 const isModuleExpression = (expression) => isStringLiteral(expression) || isCallExpression(expression);
@@ -174,27 +173,30 @@ const parseWithBabel = (path, source, language) => {
     void language;
     const plugins = parserPluginsForPath(path);
     try {
-        const ast = parse(source, {
-            sourceType: "unambiguous",
+        const { file: ast, moduleOnlyErrors } = parseRecoveredJavaScript(source, path, {
             allowImportExportEverywhere: false,
             allowReturnOutsideFunction: true,
             allowUndeclaredExports: true,
-            errorRecovery: true,
             plugins,
         });
-        return { ast, reasons: ast.errors.map((error) => error.message) };
+        return {
+            ast,
+            reasons: ast.errors.map((error) => error.message),
+            moduleOnlyErrors,
+        };
     }
     catch (cause) {
         return {
             ast: undefined,
             reasons: [cause instanceof Error ? cause.message : "Parse failed"],
+            moduleOnlyErrors: [],
         };
     }
 };
 /** Parse ESM/CommonJS imports and dynamic imports from source bytes. */
 export const parseReferenceSourceImports = (path, bytes, language) => {
-    if (language !== null && !codeSourceLanguages.has(language))
-        return { relationships: [], parse_failures: [] };
+    if (language !== null && !PARSEABLE_REFERENCE_SOURCE_LANGUAGES.has(language))
+        return { relationships: [], parse_failures: [], limitations: [] };
     let source;
     try {
         source = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
@@ -209,9 +211,15 @@ export const parseReferenceSourceImports = (path, bytes, language) => {
                     reason: "Source bytes are not valid UTF-8; import targets were not parsed.",
                 },
             ],
+            limitations: [],
         };
     }
-    const { ast, reasons } = parseWithBabel(path, source, language);
+    const { ast, reasons, moduleOnlyErrors } = parseWithBabel(path, source, language);
+    const limitations = moduleOnlyErrors.length === 0
+        ? []
+        : [
+            `Strict-mode errors apply only if this file is an ES module: ${moduleOnlyErrors.join("; ")}`,
+        ];
     const parseFailures = reasons.map((reason) => ({
         path,
         parser: "babel",
@@ -221,6 +229,7 @@ export const parseReferenceSourceImports = (path, bytes, language) => {
         return {
             relationships: [],
             parse_failures: parseFailures,
+            limitations,
         };
     }
     const relationships = [];
@@ -234,5 +243,6 @@ export const parseReferenceSourceImports = (path, bytes, language) => {
                 : relationship.parse_state,
         })),
         parse_failures: parseFailures,
+        limitations,
     };
 };

package/dist/domain/referenceSourcePathIdentity.js

@@ -1,3 +1,4 @@
+import { posix } from "node:path";
 /**
  * Reference inventories retain filesystem spelling. Prefer that exact identity;
  * canonical Unicode equivalence is a fallback only when it identifies one entry.
@@ -10,10 +11,19 @@ export const createReferenceSourcePathLookup = (paths) => {
         canonical.set(key, canonical.has(key) ? null : path);
     }
     const equivalent = (path) => canonical.get(path.normalize("NFC")) ?? undefined;
+    const resolve = (path) => exact.has(path) ? path : equivalent(path);
     return {
-        resolve: (path) => (exact.has(path) ? path : equivalent(path)),
+        resolve,
         resolveCandidates: (candidates) => candidates.find((path) => exact.has(path)) ??
             candidates.map(equivalent).find((path) => path !== undefined),
+        resolveAncestor: (path) => {
+            for (let candidate = path; candidate !== "." && candidate !== "/"; candidate = posix.dirname(candidate)) {
+                const found = resolve(candidate);
+                if (found !== undefined)
+                    return found;
+            }
+            return undefined;
+        },
     };
 };
 /** Symlink evidence can originate on a different OS from the graph reader. */

package/dist/domain/referenceSourceRequireBindings.js

@@ -2,6 +2,7 @@ import * as t from "@babel/types";
 import { analyzeParsedJavaScriptReferences } from "./javascript/javascriptSemanticAnalysis.js";
 import { semanticBindingId, semanticScopeId, } from "./javascript/javascriptSemanticState.js";
 import { traverseJavaScriptAst } from "./javascript/javascriptSemanticTraversal.js";
+import { isExplicitModuleSourcePath, } from "./javascript/javascriptSourceParser.js";
 /**
  * Keep calls that resolve either to Node's CommonJS wrapper loader or to a
  * direct ESM `createRequire(import.meta.url)` binding. The shared lexical
@@ -14,7 +15,10 @@ export const unshadowedReferenceSourceRequireCalls = (file, path) => {
         reference,
     ]));
     const programRequireBinding = semanticBindingId(semanticScopeId("program", file.program), "require");
-    const allowsUnboundRequire = !isExplicitModuleSource(path);
+    // Syntax alone cannot establish Node's runtime mode: `.js` depends on its
+    // package scope, and `.ts` may be compiled with a CommonJS module target.
+    // Keep unmarked paths runtime-unknown and preserve candidate require edges.
+    const allowsUnboundRequire = !isExplicitModuleSourcePath(path);
     const hasTopLevelVarRequire = allowsUnboundRequire && hasUninitializedTopLevelVarRequire(file.program);
     const createRequireBinding = directCreateRequireBinding(file.program, references);
     const requireLoaderWasWritten = [...references.values()].some((reference) => reference.name === "require" &&
@@ -51,17 +55,6 @@ const contains = (container, node) => typeof container.start === "number" &&
     typeof node.end === "number" &&
     container.start <= node.start &&
     node.end <= container.end;
-const isExplicitModuleSource = (path) => {
-    const lower = path.toLowerCase();
-    if (lower.endsWith(".mjs") || lower.endsWith(".mts"))
-        return true;
-    if (lower.endsWith(".cjs") || lower.endsWith(".cts"))
-        return false;
-    // Syntax alone cannot establish Node's runtime mode: `.js` depends on its
-    // package scope, and `.ts` may be compiled with a CommonJS module target.
-    // Keep unmarked paths runtime-unknown and preserve candidate require edges.
-    return false;
-};
 const hasUninitializedTopLevelVarRequire = (program) => {
     let found = false;
     let initialized = false;

package/dist/domain/referenceSourceSummary.js

@@ -0,0 +1,92 @@
+import { createHistoricalSourceManifest, } from "./referenceSourceGraph.js";
+const outlineEntry = (entry) => {
+    if (entry.kind !== "file")
+        return entry;
+    return {
+        path: entry.path,
+        kind: entry.kind,
+        language: entry.language,
+        size: entry.size,
+        content_state: entry.content_state,
+        classifications: entry.classifications,
+        limitations: entry.limitations,
+    };
+};
+/** Project one committed inventory without rereading or reinterpreting source. */
+export const createHistoricalSourceSummary = (graph, outlineDepth) => {
+    const manifest = createHistoricalSourceManifest(graph);
+    const counts = {
+        entries: graph.entries.length,
+        files: 0,
+        directories: 0,
+        symlinks: 0,
+        unknown: 0,
+        relationships: graph.relationships.length,
+        parse_failures: graph.parse_failures.length,
+        exclusions: graph.exclusions.length,
+    };
+    const contentStates = {
+        hashed: 0,
+        "redacted-secret": 0,
+        excluded: 0,
+        unreadable: 0,
+        unknown: 0,
+    };
+    const treeStates = {
+        enumerated: 0,
+        partial: 0,
+        excluded: 0,
+        unreadable: 0,
+        unknown: 0,
+    };
+    let knownBytes = 0n;
+    let unknownSizeFiles = 0;
+    const outline = [];
+    for (const entry of graph.entries) {
+        if (entry.kind === "file") {
+            counts.files += 1;
+            contentStates[entry.content_state] += 1;
+            if (entry.size === null)
+                unknownSizeFiles += 1;
+            else
+                knownBytes += BigInt(entry.size);
+        }
+        else if (entry.kind === "directory") {
+            counts.directories += 1;
+            treeStates[entry.tree_state] += 1;
+        }
+        else if (entry.kind === "symlink")
+            counts.symlinks += 1;
+        else
+            counts.unknown += 1;
+        // Canonical entries already use Unicode code-point order; filtering preserves it.
+        if (entry.path.split("/").length <= outlineDepth)
+            outline.push(outlineEntry(entry));
+    }
+    return {
+        schema: "HistoricalSourceSummary",
+        authority: graph.authority,
+        root_alias: graph.root_alias,
+        manifest,
+        inventory_state: graph.inventory_state,
+        provenance: graph.provenance,
+        vcs: graph.vcs,
+        languages: graph.languages,
+        manifests: graph.manifests,
+        counts,
+        file_content_states: contentStates,
+        directory_tree_states: treeStates,
+        file_sizes: {
+            // Decimal text keeps large totals exact; this covers only known inventoried sizes.
+            known_bytes: knownBytes.toString(),
+            unknown_file_count: unknownSizeFiles,
+        },
+        exclusions: graph.exclusions,
+        limitations: graph.limitations,
+        outline: {
+            depth: outlineDepth,
+            entries: outline,
+            omitted_entry_count: graph.entries.length - outline.length,
+        },
+    };
+};

package/dist/domain/relationshipCoverage.js

@@ -0,0 +1,44 @@
+import { z } from "zod";
+const diagnostics = z.array(z.string().min(1)).min(1).exactOptional();
+const completeCoverage = z.strictObject({
+    status: z.literal("complete"),
+    diagnostics,
+});
+const limitedDirections = z.union([
+    z.tuple([z.literal("callers")]).check(z.minLength(1), z.maxLength(1)),
+    z.tuple([z.literal("callees")]).check(z.minLength(1), z.maxLength(1)),
+    z
+        .tuple([z.literal("callers"), z.literal("callees")])
+        .check(z.minLength(2), z.maxLength(2)),
+]);
+const partialCoverage = z.strictObject({
+    status: z.literal("partial"),
+    limitations: z.array(z.string().min(1)).min(1),
+    limited_directions: limitedDirections.exactOptional(),
+    diagnostics,
+});
+const unknownCoverage = z.strictObject({
+    status: z.literal("unknown"),
+    reason: z.string().min(1),
+    limited_directions: limitedDirections.exactOptional(),
+    diagnostics,
+});
+/** Explicit coverage state for a provider's observed caller/callee set. */
+export const relationshipCoverageSchema = z.discriminatedUnion("status", [
+    completeCoverage,
+    partialCoverage,
+    unknownCoverage,
+]);
+/** Reasons the observed relationship inventory cannot establish completeness. */
+export const relationshipCoverageLimitations = (coverage) => {
+    switch (coverage?.status) {
+        case undefined:
+            return ["Provider did not report relationship coverage."];
+        case "complete":
+            return [];
+        case "partial":
+            return coverage.limitations;
+        case "unknown":
+            return [coverage.reason];
+    }
+};

package/dist/domain/residualUnknown.js

@@ -3,10 +3,11 @@ import canonicalize from "canonicalize";
 import { z } from "zod";
 import { compareUnicodeCodePoints, compositeKey, } from "./unicodeCodePointOrder.js";
 import { prefixedDigestSchema } from "./../domain/digests.js";
+import { functionComparisonDimensionNameSchema } from "./functionComparisonSchemas.js";
 const evidenceIdSchema = prefixedDigestSchema("ev");
 const unknownIdSchema = prefixedDigestSchema("unk");
 const text = z.string().trim().min(1);
-const environmentRequirementSchema = z.object({
+const environmentRequirementSchema = z.strictObject({
     id: z.string().min(1).nullable(),
     platform: z.string().min(1).nullable(),
     architecture: z.string().min(1).nullable(),
@@ -14,28 +15,53 @@ const environmentRequirementSchema = z.object({
         .enum(["none", "process", "container", "virtual-machine"])
         .nullable(),
 });
-const probeSchema = z.object({
+const stableUnknownId = (question, domain, scopeDigest, comparisonConclusionScope) => `unk_${createHash("sha256")
+    .update(canonicalJson({
+    domain: domain.trim(),
+    question: question.replace(/\s+/gu, " ").trim(),
+    scope_digest: scopeDigest,
+    ...(comparisonConclusionScope === undefined
+        ? {}
+        : { comparison_conclusion_scope: comparisonConclusionScope }),
+}))
+    .digest("hex")}`;
+const probeSchema = z.strictObject({
     operation: z.string().min(1),
     rationale: text,
 });
-const relationshipSchema = z.object({
+const comparisonConclusionScopeSchema = z
+    .object({
+    comparison_evidence_id: evidenceIdSchema,
+    dimensions: z
+        .array(z.union([z.literal("overall"), functionComparisonDimensionNameSchema]))
+        .min(1),
+})
+    .strict()
+    .superRefine(({ dimensions }, context) => {
+    if (!sameOrderedValues(dimensions, sortedUnique(dimensions)))
+        context.addIssue({
+            code: "custom",
+            message: "Comparison dimensions must be sorted and unique",
+        });
+});
+const relationshipSchema = z.strictObject({
     type: z.enum(["depends-on", "related-to", "contradicts"]),
     unknown_id: unknownIdSchema,
 });
 const resolutionSchema = z.discriminatedUnion("disposition", [
-    z.object({
+    z.strictObject({
         disposition: z.literal("verified"),
         rationale: text,
         evidence_ids: z.array(evidenceIdSchema).min(1),
     }),
-    z.object({
+    z.strictObject({
         disposition: z.enum(["withdrawn", "out-of-scope"]),
         rationale: text,
         evidence_ids: z.array(evidenceIdSchema),
     }),
 ]);
 /** Strict durable record for one unresolved or evidence-qualified question. */
-const residualUnknownObjectSchema = z.object({
+const residualUnknownObjectSchema = z.strictObject({
     unknown_id: unknownIdSchema,
     revision: z.number().int().min(1),
     previous_revision_digest: z
@@ -57,6 +83,7 @@ const residualUnknownObjectSchema = z.object({
     ]),
     severity: z.enum(["low", "medium", "high", "critical"]),
     domain: text,
+    comparison_conclusion_scope: comparisonConclusionScopeSchema.exactOptional(),
     supporting_evidence_ids: z.array(evidenceIdSchema),
     contradicting_evidence_ids: z.array(evidenceIdSchema),
     required_authority: z
@@ -75,12 +102,13 @@ const residualUnknownObjectSchema = z.object({
     resolution: resolutionSchema.nullable(),
     mutation_evidence_ids: z.array(evidenceIdSchema).min(1),
 });
-export const residualUnknownSchema = residualUnknownObjectSchema.superRefine((value, context) => {
-    if (computeRevisionDigest(value) !== value.revision_digest)
+const refineRevision = (value, context) => {
+    if (value.unknown_id !==
+        stableUnknownId(value.question, value.domain, value.scope_digest, value.comparison_conclusion_scope))
         context.addIssue({
             code: "custom",
-            message: "Residual unknown revision digest does not match",
-            path: ["revision_digest"],
+            message: "Residual unknown ID does not match its immutable identity",
+            path: ["unknown_id"],
         });
     if ((value.revision === 1) !== (value.previous_revision_digest === null))
         context.addIssue({
@@ -117,6 +145,23 @@ export const residualUnknownSchema = residualUnknownObjectSchema.superRefine((va
                 code: "custom",
                 message: "Evidence IDs must be unique",
             });
+    if (value.comparison_conclusion_scope !== undefined &&
+        ![
+            ...value.supporting_evidence_ids,
+            ...value.contradicting_evidence_ids,
+        ].includes(value.comparison_conclusion_scope.comparison_evidence_id))
+        context.addIssue({
+            code: "custom",
+            message: "Scoped comparison Evidence must support or contradict the unknown",
+            path: ["comparison_conclusion_scope"],
+        });
+    if (value.comparison_conclusion_scope !== undefined &&
+        value.domain !== "function-comparison")
+        context.addIssue({
+            code: "custom",
+            message: "Comparison conclusion scope requires function-comparison domain",
+            path: ["comparison_conclusion_scope"],
+        });
     const contradictingEvidence = new Set(value.contradicting_evidence_ids);
     if (value.supporting_evidence_ids.some((id) => contradictingEvidence.has(id)))
         context.addIssue({
@@ -130,7 +175,20 @@ export const residualUnknownSchema = residualUnknownObjectSchema.superRefine((va
             message: "Relationships must be unique",
             path: ["relationships"],
         });
+};
+const residualUnknownValidatedSchema = residualUnknownObjectSchema.superRefine((value, context) => {
+    if (computeRevisionDigest(value) !== value.revision_digest)
+        context.addIssue({
+            code: "custom",
+            message: "Residual unknown revision digest does not match",
+            path: ["revision_digest"],
+        });
+    refineRevision(value, context);
 });
+export const residualUnknownSchema = residualUnknownValidatedSchema;
+const generatedRevisionSchema = residualUnknownObjectSchema
+    .omit({ revision_digest: true })
+    .superRefine(refineRevision);
 /** Input for deterministic creation of one residual unknown. */
 export const recordUnknownInputSchema = residualUnknownObjectSchema
     .omit({
@@ -167,28 +225,30 @@ export const updateUnknownInputSchema = z.strictObject({
 });
 /** Create stable identity from immutable question and domain fields. */
 export const createResidualUnknown = (input, mutationEvidenceId, scopeDigest) => {
-    const question = input.question.replace(/\s+/gu, " ");
-    const identity = canonicalJson({
-        domain: input.domain,
-        question,
-        scope_digest: scopeDigest,
-    });
+    const question = input.question.replace(/\s+/gu, " ").trim();
+    const domain = input.domain.trim();
+    const comparisonConclusionScope = input.comparison_conclusion_scope === undefined
+        ? undefined
+        : {
+            comparison_evidence_id: input.comparison_conclusion_scope.comparison_evidence_id,
+            dimensions: input.comparison_conclusion_scope.dimensions,
+        };
     const revision = {
-        unknown_id: `unk_${createHash("sha256").update(identity).digest("hex")}`,
+        unknown_id: stableUnknownId(question, domain, scopeDigest, comparisonConclusionScope),
         revision: 1,
         previous_revision_digest: null,
         scope_digest: scopeDigest,
         question,
         status: input.contradicting_evidence_ids.length > 0 ? "contradicted" : "open",
-        domain: input.domain,
+        domain,
+        ...(comparisonConclusionScope === undefined
+            ? {}
+            : { comparison_conclusion_scope: comparisonConclusionScope }),
         ...projectRevisionDetails(input),
         resolution: null,
         mutation_evidence_ids: [mutationEvidenceId],
     };
-    return residualUnknownSchema.parse({
-        ...revision,
-        revision_digest: computeRevisionDigest(revision),
-    });
+    return createRevision(revision);
 };
 /** Apply a complete, revision-guarded replacement while preserving identity. */
 export const updateResidualUnknown = (current, input, mutationEvidenceId) => {
@@ -200,6 +260,9 @@ export const updateResidualUnknown = (current, input, mutationEvidenceId) => {
         question: current.question,
         status: input.status,
         domain: current.domain,
+        ...(current.comparison_conclusion_scope === undefined
+            ? {}
+            : { comparison_conclusion_scope: current.comparison_conclusion_scope }),
         ...projectRevisionDetails(input),
         resolution: input.resolution,
         mutation_evidence_ids: sortedUnique([
@@ -207,10 +270,12 @@ export const updateResidualUnknown = (current, input, mutationEvidenceId) => {
             mutationEvidenceId,
         ]),
     };
-    return residualUnknownSchema.parse({
-        ...revision,
-        revision_digest: computeRevisionDigest(revision),
-    });
+    return createRevision(revision);
+};
+/** Validate and normalize owned revision fields before computing their digest. */
+const createRevision = (value) => {
+    const revision = generatedRevisionSchema.parse(value);
+    return { ...revision, revision_digest: computeRevisionDigest(revision) };
 };
 const projectRevisionDetails = (input) => ({
     severity: input.severity,
@@ -234,4 +299,6 @@ const canonicalJson = (value) => {
     return serialized;
 };
 const sortedUnique = (values) => [...new Set(values)].sort(compareUnicodeCodePoints);
+const sameOrderedValues = (left, right) => left.length === right.length &&
+    left.every((value, index) => value === right[index]);
 const sortedRelationships = (values) => [...values].sort((left, right) => compareUnicodeCodePoints(compositeKey([left.type, left.unknown_id]), compositeKey([right.type, right.unknown_id])));