@velum-labs/routekit-eval-setup 1.4.0 → 1.5.0

package/dist/adapters/repository-review-evidence.js

@@ -0,0 +1,632 @@
+import { createHash } from "node:crypto";
+const MAXIMUM_JSON_BYTES = 16 * 1024 * 1024;
+const digest = (text) => createHash("sha256").update(JSON.stringify(text), "utf8").digest("hex");
+const bytes = (value) => Buffer.byteLength(JSON.stringify(value), "utf8");
+const spliceContext = (base, prefix, suffix) => {
+    const end = base.length - suffix;
+    return {
+        startLine: base.slice(0, prefix).split("\n").length,
+        endLine: base.slice(0, end).split("\n").length,
+        immediatelyBefore: base.slice(Math.max(0, prefix - 120), prefix),
+        immediatelyAfter: base.slice(end, end + 120)
+    };
+};
+export const REPOSITORY_REVIEW_EVIDENCE_INSTRUCTIONS = `The input uses routekit-lossless-review-json-v1.
+Decode evidence before reviewing it. Null, booleans, numbers, and strings represent themselves.
+Every original object is ["object", [[key, encodedValue], ...]], and every original array is
+["array", [encodedValue, ...]]. ["text", digest] resolves a string from texts. A text entry is
+["literal", exactString] or ["splice", baseDigest, prefixChars, suffixChars, replacement, context].
+For a splice, retain the first prefixChars and last suffixChars of the literal base string and
+insert replacement between them. Character counts use JavaScript UTF-16 code units, not UTF-8 bytes.
+The verified context gives one-based start/end lines in the base and up to 120 characters immediately
+before and after the replaced range, so you can locate the changed code without counting characters.
+Digests are SHA-256 of UTF-8 JSON.stringify(exactString). The host verified exact reconstruction.
+All original fields, source, controls, and evidence are retained. Evidence-inventory paths address
+the decoded original object; the encoding does not change those paths or their meaning.`;
+/** Factor full-file variants without weakening or truncating the review evidence. */
+export function encodeRepositoryReviewEvidenceV1(input, sourceBases) {
+    let size = 0;
+    const frequencies = new Map();
+    const addBytes = (count) => {
+        size += count;
+        if (size > MAXIMUM_JSON_BYTES)
+            throw new Error("review evidence exceeds the 16MiB encoding bound");
+    };
+    const normalize = (value, depth = 0) => {
+        if (depth > 128)
+            throw new Error("review evidence exceeds the encoding depth bound");
+        if (value === null || typeof value === "boolean" || typeof value === "number") {
+            const normalized = typeof value === "number" && !Number.isFinite(value) ? null : value;
+            addBytes(bytes(normalized));
+            return normalized;
+        }
+        if (typeof value === "string") {
+            const length = bytes(value);
+            addBytes(length);
+            if (length >= 256)
+                frequencies.set(value, (frequencies.get(value) ?? 0) + 1);
+            return value;
+        }
+        if (Array.isArray(value)) {
+            if (typeof value.toJSON === "function")
+                throw new Error("review evidence requires plain JSON arrays without toJSON transformations");
+            addBytes(2 + Math.max(0, value.length - 1));
+            return value.map((entry) => normalize(entry === undefined ? null : entry, depth + 1));
+        }
+        if (typeof value === "object" && value !== null) {
+            const prototype = Object.getPrototypeOf(value);
+            if ((prototype !== Object.prototype && prototype !== null) ||
+                typeof value.toJSON === "function")
+                throw new Error("review evidence requires plain JSON objects without toJSON transformations");
+            const entries = Object.entries(value).filter(([, entry]) => entry !== undefined);
+            addBytes(2 + Math.max(0, entries.length - 1));
+            return Object.fromEntries(entries.map(([key, entry]) => {
+                addBytes(bytes(key) + 1);
+                return [key, normalize(entry, depth + 1)];
+            }));
+        }
+        throw new Error("review evidence must be JSON serializable");
+    };
+    const original = normalize(input);
+    const originalJson = JSON.stringify(original);
+    if (originalJson !== JSON.stringify(input))
+        throw new Error("review evidence normalization changed its JSON serialization");
+    const bases = [...new Set(sourceBases)].map((content) => ({ content, key: digest(content) }));
+    if (bases.reduce((total, base) => total + Buffer.byteLength(base.content), 0) > MAXIMUM_JSON_BYTES)
+        throw new Error("review source bases exceed the 16MiB encoding bound");
+    const texts = Object.create(null);
+    const textKeys = new Map();
+    for (const [content, frequency] of frequencies) {
+        const key = digest(content);
+        const contentBytes = bytes(content);
+        let best;
+        for (const base of bases) {
+            let prefix = 0;
+            while (prefix < content.length &&
+                prefix < base.content.length &&
+                content.charCodeAt(prefix) === base.content.charCodeAt(prefix))
+                prefix += 1;
+            let suffix = 0;
+            while (suffix < content.length - prefix &&
+                suffix < base.content.length - prefix &&
+                content.charCodeAt(content.length - suffix - 1) ===
+                    base.content.charCodeAt(base.content.length - suffix - 1))
+                suffix += 1;
+            const entry = [
+                "splice",
+                base.key,
+                prefix,
+                suffix,
+                content.slice(prefix, content.length - suffix),
+                spliceContext(base.content, prefix, suffix)
+            ];
+            const length = bytes(entry);
+            if (length + 160 < contentBytes && (best === undefined || length < best.size))
+                best = { base, entry, size: length };
+        }
+        if (best !== undefined) {
+            texts[best.base.key] = ["literal", best.base.content];
+            // A base must remain literal even if it also occurs in the evidence.
+            if (texts[key]?.[0] !== "literal")
+                texts[key] = best.entry;
+            textKeys.set(content, key);
+        }
+        else if (frequency > 1) {
+            texts[key] = ["literal", content];
+            textKeys.set(content, key);
+        }
+    }
+    const encode = (value) => {
+        if (typeof value === "string") {
+            const key = textKeys.get(value);
+            return key === undefined ? value : ["text", key];
+        }
+        if (Array.isArray(value))
+            return ["array", value.map(encode)];
+        if (typeof value === "object" && value !== null)
+            return ["object", Object.entries(value).map(([key, entry]) => [key, encode(entry)])];
+        return value;
+    };
+    const packet = {
+        encoding: "routekit-lossless-review-json-v1",
+        texts,
+        evidence: encode(original)
+    };
+    if (JSON.stringify(decodeRepositoryReviewEvidenceV1(packet)) !== originalJson)
+        throw new Error("review evidence did not reconstruct exactly");
+    return packet;
+}
+/** Host-side integrity check; the reviewer receives the same reconstruction rules. */
+export function decodeRepositoryReviewEvidenceV1(packet) {
+    if (packet.encoding !== "routekit-lossless-review-json-v1")
+        throw new Error("unknown review evidence encoding");
+    const text = (key) => {
+        const entry = packet.texts[key];
+        if (entry === undefined)
+            throw new Error("review text reference is missing");
+        let value;
+        if (entry[0] === "literal")
+            value = entry[1];
+        else {
+            const [, baseKey, prefix, suffix, replacement, context] = entry;
+            const base = packet.texts[baseKey];
+            if (base?.[0] !== "literal" ||
+                digest(base[1]) !== baseKey ||
+                !Number.isSafeInteger(prefix) ||
+                !Number.isSafeInteger(suffix) ||
+                prefix < 0 ||
+                suffix < 0 ||
+                prefix + suffix > base[1].length)
+                throw new Error("review text splice has an invalid base or overlapping ranges");
+            if (JSON.stringify(context) !== JSON.stringify(spliceContext(base[1], prefix, suffix)))
+                throw new Error("review text splice context does not match its source range");
+            value = base[1].slice(0, prefix) + replacement + base[1].slice(base[1].length - suffix);
+        }
+        if (digest(value) !== key)
+            throw new Error("review text digest mismatch");
+        return value;
+    };
+    const decode = (node) => {
+        if (!Array.isArray(node))
+            return node;
+        const tagged = node;
+        switch (tagged[0]) {
+            case "text":
+                return text(tagged[1]);
+            case "array":
+                return tagged[1].map(decode);
+            case "object":
+                return Object.fromEntries(tagged[1].map(([key, entry]) => [key, decode(entry)]));
+            default:
+                throw new Error("unknown review evidence node");
+        }
+    };
+    return decode(packet.evidence);
+}
+export const REPOSITORY_REVIEW_EVIDENCE_V2_INSTRUCTIONS = `The input uses routekit-lossless-review-json-v2.
+Decode evidence before reviewing it. Null, booleans, numbers, and strings represent themselves.
+["a", ...items] represents an original array of decoded items. ["r", shapeIndex, ...values]
+represents an original object: zip shapes[shapeIndex] with the decoded values, in the given order.
+For example, shapes[0]=["solutionId","outcome"] and ["r",0,"candidate-a","fail"] represents
+{"solutionId":"candidate-a","outcome":"fail"}. Every original array or object has an explicit tag.
+["s", index] resolves exactly strings[index]. ["j", ...parts] concatenates decoded string
+parts without adding or removing spaces or delimiters. These joins factor repetitive diagnostics and evidence paths;
+the individual outcome, duration, error, and other evidence fields remain available.
+["n", index] resolves exactly nodes[index]. These shared arrays and objects avoid repeating
+identical fixtures and control overlays across the proposal and executed evidence. A node may
+refer only to earlier node entries. Every occurrence reconstructs the complete original subtree.
+["t", index] resolves texts[index], a [digest, entry] pair. An entry is ["literal", exactString]
+or ["splice", baseDigest, prefixChars, suffixChars, replacement, context]. Locate the literal base
+by its digest in texts. Retain its first prefixChars and last suffixChars, inserting replacement
+between them. Counts use JavaScript UTF-16 code units. The verified context gives one-based start/end
+lines and up to 120 characters immediately before and after the replacement.
+A ["patch", baseDigest, hunks] entry applies separated edits to the exact resolved base string.
+Each hunk is [startChars, endChars, exactReplacement, context]. Offsets are zero-based UTF-16,
+end-exclusive, ordered, nonoverlapping ranges in the ORIGINAL base. Preserve all text between
+ranges; insert each replacement once. Context verifies the original source lines and neighboring
+text. A base may itself be encoded; text dependencies are acyclic and the host validates every digest.
+Text digests are SHA-256
+of UTF-8 JSON.stringify(exactString). originalDigest binds the complete decoded original JSON.
+The host verified exact reconstruction. No source, control, observation, or evidence-inventory entry
+was omitted. Evidence-inventory paths address the decoded original object, with unchanged meaning.`;
+// Delimited execution diagnostics contain many stable fields and a few changing
+// measurements. Preserve every delimiter and byte; never split multiline code.
+const diagnosticParts = (value) => {
+    if (value.includes("\n"))
+        return [value];
+    if (value.length > 120 && (value.match(/;/gu)?.length ?? 0) >= 3)
+        return value.match(/[^;]*(?:;|$)/gu)?.filter((part) => part.length > 0) ?? [value];
+    const slash = value.lastIndexOf("/");
+    if (slash > 12 && /^[0-9]+$/u.test(value.slice(slash + 1)))
+        return [value.slice(0, slash + 1), value.slice(slash + 1)];
+    return [value];
+};
+/** Unique line anchors retain distant unchanged regions without synthesizing source. */
+const sourceHunks = (base, changed) => {
+    const lines = (text) => [...text.matchAll(/[^\n]*\n|[^\n]+$/gu)].map((match) => ({
+        text: match[0],
+        start: match.index,
+        end: match.index + match[0].length
+    }));
+    const before = lines(base);
+    const after = lines(changed);
+    const unique = (values) => {
+        const indexes = new Map();
+        values.forEach((line, index) => {
+            if (line.text.trim().length >= 8)
+                indexes.set(line.text, indexes.has(line.text) ? -1 : index);
+        });
+        return indexes;
+    };
+    const beforeIndexes = unique(before);
+    const afterIndexes = unique(after);
+    const pairs = [];
+    for (const [text, afterIndex] of afterIndexes) {
+        const beforeIndex = beforeIndexes.get(text);
+        if (afterIndex >= 0 && beforeIndex !== undefined && beforeIndex >= 0)
+            pairs.push({ before: beforeIndex, after: afterIndex });
+    }
+    pairs.sort((left, right) => left.after - right.after);
+    const tails = [];
+    const previous = [];
+    pairs.forEach((pair, index) => {
+        let low = 0;
+        let high = tails.length;
+        while (low < high) {
+            const middle = (low + high) >>> 1;
+            if (pairs[tails[middle]].before < pair.before)
+                low = middle + 1;
+            else
+                high = middle;
+        }
+        previous[index] = low === 0 ? -1 : tails[low - 1];
+        tails[low] = index;
+    });
+    const anchors = [];
+    for (let index = tails.at(-1) ?? -1; index >= 0; index = previous[index])
+        anchors.push(pairs[index]);
+    anchors.reverse();
+    const hunks = [];
+    const add = (start, end, replacement) => {
+        const original = base.slice(start, end);
+        if (original === replacement)
+            return;
+        let prefix = 0;
+        while (prefix < original.length &&
+            prefix < replacement.length &&
+            original.charCodeAt(prefix) === replacement.charCodeAt(prefix))
+            prefix += 1;
+        let suffix = 0;
+        while (suffix < original.length - prefix &&
+            suffix < replacement.length - prefix &&
+            original.charCodeAt(original.length - suffix - 1) ===
+                replacement.charCodeAt(replacement.length - suffix - 1))
+            suffix += 1;
+        const hunk = [
+            start + prefix,
+            end - suffix,
+            replacement.slice(prefix, replacement.length - suffix),
+            spliceContext(base, start + prefix, base.length - end + suffix)
+        ];
+        const last = hunks.at(-1);
+        if (last !== undefined && hunk[0] - last[1] < 512) {
+            const joined = [
+                last[0],
+                hunk[1],
+                last[2] + base.slice(last[1], hunk[0]) + hunk[2],
+                spliceContext(base, last[0], base.length - hunk[1])
+            ];
+            if (bytes(joined) <= bytes(last) + bytes(hunk)) {
+                hunks[hunks.length - 1] = joined;
+                return;
+            }
+        }
+        hunks.push(hunk);
+    };
+    let baseStart = 0;
+    let changedStart = 0;
+    for (const anchor of anchors) {
+        const left = before[anchor.before];
+        const right = after[anchor.after];
+        add(baseStart, left.start, changed.slice(changedStart, right.start));
+        baseStart = left.end;
+        changedStart = right.end;
+    }
+    add(baseStart, base.length, changed.slice(changedStart));
+    return hunks;
+};
+/** Lossless row and string dictionaries keep full observed populations reviewable. */
+export function encodeRepositoryReviewEvidenceV2(input, sourceBases) {
+    const original = encodeRepositoryReviewEvidenceV1(input, sourceBases);
+    const texts = Object.entries(original.texts);
+    const textIndexes = new Map(texts.map(([key], index) => [key, index]));
+    const sourceCandidates = [];
+    const resolvedOriginal = (key) => decodeRepositoryReviewEvidenceV1({
+        ...original,
+        evidence: ["text", key]
+    });
+    for (const [index, [key, entry]] of texts.entries()) {
+        const content = resolvedOriginal(key);
+        let best = entry;
+        if (content.includes("\n") && content.length >= 512) {
+            const candidates = entry[0] === "splice"
+                ? [
+                    { key: entry[1], content: resolvedOriginal(entry[1]) },
+                    ...sourceCandidates.filter((candidate) => candidate.key !== entry[1])
+                ]
+                : sourceCandidates;
+            for (const candidate of candidates) {
+                const patch = [
+                    "patch",
+                    candidate.key,
+                    sourceHunks(candidate.content, content)
+                ];
+                if (bytes(patch) < bytes(best))
+                    best = patch;
+            }
+        }
+        texts[index] = [key, best];
+        // Only original literals become bases, in their original order. Existing
+        // splices refer to those literals; new literal dependencies point backwards.
+        if (entry[0] === "literal" && content.includes("\n") && content.length >= 512)
+            sourceCandidates.push({ key, content });
+    }
+    const inlineTexts = new Map();
+    const factorInline = (node) => {
+        if (typeof node === "string" && node.includes("\n") && node.length >= 512) {
+            if (inlineTexts.has(node))
+                return;
+            const key = digest(node);
+            const existing = textIndexes.get(key);
+            if (existing !== undefined) {
+                inlineTexts.set(node, existing);
+                return;
+            }
+            let best;
+            for (const candidate of sourceCandidates) {
+                const patch = ["patch", candidate.key, sourceHunks(candidate.content, node)];
+                if (bytes(patch) + 100 < bytes(node) && (best === undefined || bytes(patch) < bytes(best)))
+                    best = patch;
+            }
+            if (best !== undefined) {
+                inlineTexts.set(node, texts.length);
+                textIndexes.set(key, texts.length);
+                texts.push([key, best]);
+            }
+        }
+        else if (Array.isArray(node)) {
+            const tagged = node;
+            if (tagged[0] === "object")
+                for (const [, entry] of tagged[1])
+                    factorInline(entry);
+            if (tagged[0] === "array")
+                for (const entry of tagged[1])
+                    factorInline(entry);
+        }
+    };
+    factorInline(original.evidence);
+    const frequencies = new Map();
+    const count = (node) => {
+        if (typeof node === "string") {
+            for (const part of diagnosticParts(node))
+                frequencies.set(part, (frequencies.get(part) ?? 0) + 1);
+        }
+        else if (Array.isArray(node)) {
+            const tagged = node;
+            if (tagged[0] === "object")
+                for (const [, entry] of tagged[1])
+                    count(entry);
+            if (tagged[0] === "array")
+                for (const entry of tagged[1])
+                    count(entry);
+        }
+    };
+    count(original.evidence);
+    const strings = [...frequencies]
+        .filter(([text, frequency]) => frequency > 1 && text.length >= 12)
+        .map(([text]) => text);
+    const stringIndexes = new Map(strings.map((text, index) => [text, index]));
+    const shapes = [];
+    const shapeIndexes = new Map();
+    const encodeString = (value) => {
+        const index = stringIndexes.get(value);
+        return index === undefined ? value : ["s", index];
+    };
+    const encode = (node) => {
+        if (typeof node === "string") {
+            const textIndex = inlineTexts.get(node);
+            if (textIndex !== undefined)
+                return ["t", textIndex];
+            const literal = encodeString(node);
+            const parts = diagnosticParts(node);
+            if (parts.length === 1)
+                return literal;
+            const joined = ["j", ...parts.map(encodeString)];
+            return bytes(joined) < bytes(literal) ? joined : literal;
+        }
+        if (!Array.isArray(node))
+            return node;
+        const tagged = node;
+        if (tagged[0] === "text")
+            return ["t", textIndexes.get(tagged[1])];
+        if (tagged[0] === "array")
+            return ["a", ...tagged[1].map(encode)];
+        const keys = tagged[1].map(([key]) => key);
+        const signature = JSON.stringify(keys);
+        let index = shapeIndexes.get(signature);
+        if (index === undefined) {
+            index = shapes.length;
+            shapeIndexes.set(signature, index);
+            shapes.push(keys);
+        }
+        return ["r", index, ...tagged[1].map(([, entry]) => encode(entry))];
+    };
+    const expandedEvidence = encode(original.evidence);
+    const subtreeCounts = new Map();
+    const countSubtrees = (node) => {
+        if (!Array.isArray(node))
+            return;
+        const tagged = node;
+        const signature = JSON.stringify(tagged);
+        if (signature.length >= 96)
+            subtreeCounts.set(signature, (subtreeCounts.get(signature) ?? 0) + 1);
+        for (const child of tagged)
+            countSubtrees(child);
+    };
+    countSubtrees(expandedEvidence);
+    const nodes = [];
+    const nodeIndexes = new Map();
+    const share = (node) => {
+        if (!Array.isArray(node))
+            return node;
+        const tagged = node;
+        const signature = JSON.stringify(tagged);
+        const existing = nodeIndexes.get(signature);
+        if (existing !== undefined)
+            return ["n", existing];
+        const shared = tagged[0] === "r"
+            ? ["r", tagged[1], ...tagged.slice(2).map(share)]
+            : tagged[0] === "a"
+                ? ["a", ...tagged.slice(1).map(share)]
+                : tagged[0] === "j"
+                    ? ["j", ...tagged.slice(1).map(share)]
+                    : tagged;
+        if ((subtreeCounts.get(signature) ?? 0) > 1) {
+            const index = nodes.length;
+            nodes.push(shared);
+            nodeIndexes.set(signature, index);
+            return ["n", index];
+        }
+        return shared;
+    };
+    const evidence = share(expandedEvidence);
+    const packet = {
+        encoding: "routekit-lossless-review-json-v2",
+        originalDigest: digest(JSON.stringify(input)),
+        texts,
+        shapes,
+        strings,
+        nodes,
+        evidence
+    };
+    if (JSON.stringify(decodeRepositoryReviewEvidenceV2(packet)) !== JSON.stringify(input))
+        throw new Error("compact review evidence did not reconstruct exactly");
+    return packet;
+}
+/** Reject malformed tables and any change to the complete reconstructed evidence. */
+export function decodeRepositoryReviewEvidenceV2(packet) {
+    if (packet.encoding !== "routekit-lossless-review-json-v2")
+        throw new Error("unknown compact review evidence encoding");
+    if (bytes(packet) > MAXIMUM_JSON_BYTES)
+        throw new Error("compact review evidence exceeds the 16MiB encoding bound");
+    const indexed = (table, index, name) => {
+        if (typeof index !== "number" ||
+            !Number.isSafeInteger(index) ||
+            index < 0 ||
+            index >= table.length)
+            throw new Error(`compact review ${name} reference is missing`);
+        return table[index];
+    };
+    if (new Set(packet.texts.map(([key]) => key)).size !== packet.texts.length)
+        throw new Error("compact review text keys must be unique");
+    const textTable = new Map(packet.texts);
+    const resolvedTexts = new Map();
+    const resolving = new Set();
+    const resolveText = (key, depth = 0) => {
+        const cached = resolvedTexts.get(key);
+        if (cached !== undefined)
+            return cached;
+        if (depth > 128 || resolving.has(key))
+            throw new Error("compact review text dependencies must be bounded and acyclic");
+        const entry = textTable.get(key);
+        if (entry === undefined)
+            throw new Error("compact review text base is missing");
+        resolving.add(key);
+        let value;
+        if (entry[0] === "literal")
+            value = entry[1];
+        else {
+            const base = resolveText(entry[1], depth + 1);
+            const hunks = entry[0] === "splice"
+                ? [[entry[2], base.length - entry[3], entry[4], entry[5]]]
+                : entry[0] === "patch"
+                    ? entry[2]
+                    : (() => {
+                        throw new Error("unknown compact review text entry");
+                    })();
+            let cursor = 0;
+            let expandedCharacters = 0;
+            const parts = [];
+            for (const [start, end, replacement, context] of hunks) {
+                if (!Number.isSafeInteger(start) ||
+                    !Number.isSafeInteger(end) ||
+                    start < cursor ||
+                    end < start ||
+                    end > base.length ||
+                    typeof replacement !== "string" ||
+                    JSON.stringify(context) !== JSON.stringify(spliceContext(base, start, base.length - end)))
+                    throw new Error("compact review source edits have invalid ranges or source context");
+                expandedCharacters += start - cursor + replacement.length;
+                if (expandedCharacters > MAXIMUM_JSON_BYTES)
+                    throw new Error("compact review source text exceeds the expanded size bound");
+                parts.push(base.slice(cursor, start), replacement);
+                cursor = end;
+            }
+            if (expandedCharacters + base.length - cursor > MAXIMUM_JSON_BYTES)
+                throw new Error("compact review source text exceeds the expanded size bound");
+            parts.push(base.slice(cursor));
+            value = parts.join("");
+        }
+        if (digest(value) !== key)
+            throw new Error("compact review text digest mismatch");
+        resolving.delete(key);
+        resolvedTexts.set(key, value);
+        return value;
+    };
+    const literalTexts = Object.fromEntries(packet.texts.map(([key]) => [key, ["literal", resolveText(key)]]));
+    let expandedNodes = 0;
+    const expand = (node, depth = 0, nodeCeiling = packet.nodes.length) => {
+        if (++expandedNodes > 1_000_000)
+            throw new Error("compact review evidence exceeds the expanded-node bound");
+        if (depth > 128)
+            throw new Error("compact review evidence exceeds the encoding depth bound");
+        if (!Array.isArray(node)) {
+            if (node !== null &&
+                typeof node !== "boolean" &&
+                typeof node !== "number" &&
+                typeof node !== "string")
+                throw new Error("compact review requires tagged objects and arrays");
+            return node;
+        }
+        const tagged = node;
+        switch (tagged[0]) {
+            case "a":
+                return ["array", tagged.slice(1).map((value) => expand(value, depth + 1, nodeCeiling))];
+            case "r": {
+                const keys = indexed(packet.shapes, tagged[1], "shape");
+                const values = tagged.slice(2);
+                if (keys.length !== values.length ||
+                    keys.some((key) => typeof key !== "string") ||
+                    new Set(keys).size !== keys.length)
+                    throw new Error("compact review row does not match a unique object shape");
+                return [
+                    "object",
+                    keys.map((key, index) => [key, expand(values[index], depth + 1, nodeCeiling)])
+                ];
+            }
+            case "t":
+                if (tagged.length !== 2)
+                    throw new Error("compact review text reference is malformed");
+                return ["text", indexed(packet.texts, tagged[1], "text")[0]];
+            case "s": {
+                if (tagged.length !== 2)
+                    throw new Error("compact review string reference is malformed");
+                const value = indexed(packet.strings, tagged[1], "string");
+                if (typeof value !== "string")
+                    throw new Error("compact review string must be literal");
+                return value;
+            }
+            case "n": {
+                if (tagged.length !== 2 || typeof tagged[1] !== "number" || tagged[1] >= nodeCeiling)
+                    throw new Error("compact review node references must be acyclic and point backwards");
+                return expand(indexed(packet.nodes, tagged[1], "node"), depth, tagged[1]);
+            }
+            case "j": {
+                const parts = tagged.slice(1).map((part) => expand(part, depth + 1, nodeCeiling));
+                if (parts.some((part) => typeof part !== "string"))
+                    throw new Error("compact review joins require only literal string parts");
+                return parts.join("");
+            }
+            default:
+                throw new Error("unknown compact review evidence node");
+        }
+    };
+    const value = decodeRepositoryReviewEvidenceV1({
+        encoding: "routekit-lossless-review-json-v1",
+        texts: literalTexts,
+        evidence: expand(packet.evidence)
+    });
+    if (digest(JSON.stringify(value)) !== packet.originalDigest)
+        throw new Error("compact review original evidence digest mismatch");
+    return value;
+}

package/dist/adapters/repository-seed-selection.d.ts

@@ -0,0 +1,7 @@
+import type { RepositoryBehaviorMapV1, RepositoryChangeEpisodeV1 } from "../repository-behavior-protocol.js";
+/** Retrieval heuristic only; executable qualification and dimension critics remain mandatory. */
+export declare function rankRepositorySeedCandidatesV1(map: RepositoryBehaviorMapV1, requestedDimension: string): readonly {
+    readonly episode: RepositoryChangeEpisodeV1;
+    readonly relevance: number;
+    readonly matchedTerms: readonly string[];
+}[];