jev-agent-tools 0.2.0 → 0.3.0

package/dist/core/ask-references.js

@@ -9,108 +9,185 @@ function unquote(value) {
                 return parsed;
         }
         catch {
-            return value.slice(1, -1);
+            /* retain the literal selector */
         }
     }
     return value.slice(1, -1).replace(/\\(['\\])/g, "$1");
 }
-function looksLikePath(value) {
-    if (/\s/.test(value) || /^(?:[a-z]+:|www\.)/i.test(value))
-        return false;
-    if (!/[A-Za-z_]/.test(value) ||
-        /^(?:state|docs?|files|files_before)\./.test(value))
-        return false;
-    if (/^(?:e\.g|i\.e|Node\.js|Next\.js|Vue\.js)$/i.test(value))
-        return false;
-    return (/^(?:\.?\.?\/)?[\w.@+-]+(?:\/[\w.@+-]+)+$/.test(value) ||
-        /^[\w@+-][\w.@+-]*\.(?:[cm]?[jt]sx?|py|json|jsonc|ya?ml|toml|ini|cfg|conf|md|mdx|txt|rst|html?|css|scss|sql|sh|bash|rs|go|java|rb|php|c|h|cpp|hpp|vue|svelte|xml|csv|env|lock)$/i.test(value) ||
-        /^\.[A-Za-z][\w.-]*$/.test(value) ||
-        /^(?:README|LICENSE|LICENCE|Makefile|Dockerfile|CHANGELOG|AGENTS|CLAUDE)(?:\.[\w-]+)?$/.test(value));
+function normalized(path) {
+    return path.replace(/\\/g, "/").replace(/^(?:\.\/)+/, "");
+}
+function forbidden(path) {
+    return (/^(?:\/|[A-Za-z]:|[a-z][a-z\d+.-]*:\/\/)/i.test(path) ||
+        path.split(/[\\/]/).some((part) => part === ".." || part === ".git"));
+}
+function explicitPaths(text) {
+    const references = new Map();
+    for (const match of text.matchAll(fileSelector)) {
+        const reference = unquote(match[2] ?? "");
+        const side = match[1];
+        references.set(JSON.stringify([side, reference]), { reference, side });
+    }
+    return [...references.values()];
 }
-/** Explicit paths only: numbers, dates and URLs are not evidence references. */
+/** Lexical discovery hints, never requirements. Ordinary member expressions are excluded. */
 export function citedPaths(text) {
-    const found = new Set();
-    const withoutUrls = text.replace(/\b(?:[a-z][a-z\d+.-]*:\/\/|www\.)[^\s<>"'`]+/gi, " ");
-    const withoutSelectors = withoutUrls.replace(fileSelector, (_whole, _root, quoted) => {
-        found.add(unquote(quoted));
-        return " ";
-    });
-    const withoutFields = withoutSelectors.replace(selector, (value) => value.includes("[") || /^(?:state|docs?|files|files_before)\./.test(value)
+    const found = new Set(explicitPaths(text).map(({ reference }) => reference));
+    const cleaned = text
+        .replace(/\b(?:[a-z][a-z\d+.-]*:\/\/|www\.)[^\s<>"'`]+/gi, " ")
+        .replace(fileSelector, " ")
+        .replace(selector, (value) => value.includes("[") ||
+        /^(?:state|output|docs?|files|files_before)\./.test(value)
         ? " "
         : value);
-    const unquoted = withoutFields.replace(/`([^`\n]+)`|"([^"\n]+)"|'([^'\n]+)'/g, (_whole, backtick, double, single) => {
-        const value = backtick ?? double ?? single ?? "";
-        if (looksLikePath(value)) {
-            found.add(value);
-            return " ";
-        }
-        return value;
-    });
-    for (const match of unquoted.matchAll(/[\w.@+-]+(?:\/[\w.@+-]+)*/g)) {
-        const value = match[0].replace(/[.,;:!?]+$/, "");
-        if (looksLikePath(value) &&
-            (!value.includes("/") ||
-                looksLikePath(value.slice(value.lastIndexOf("/") + 1))))
+    for (const match of cleaned.matchAll(/`([^`\n]+)`|"([^"\n]+)"|'([^'\n]+)'/g)) {
+        const value = match[1] ?? match[2] ?? match[3] ?? "";
+        if (/^(?:[\w@+-]+\/)+[\w.@+-]+$/.test(value))
             found.add(value);
     }
+    for (const match of cleaned.matchAll(/\b(?:README|LICENSE|LICENCE|Makefile|Dockerfile|CHANGELOG|AGENTS|CLAUDE)(?:\.[\w-]+)?\b/g))
+        found.add(match[0]);
+    for (const match of cleaned.matchAll(/(?:\.?\.?\/)?[\w@+-]+(?:\/[\w.@+-]+)*\.(?:[cm]?[jt]sx?|py|jsonc?|ya?ml|toml|ini|cfg|conf|mdx?|txt|rst|html?|css|scss|sql|sh|bash|rs|go|java|rb|php|cpp|hpp|vue|svelte|xml|csv|lock)\b/g)) {
+        const start = match.index ?? 0;
+        if ((start && /[\w.]/.test(cleaned[start - 1] ?? "")) ||
+            /^(?:Node|Next|Vue)\.js$/i.test(match[0]))
+            continue;
+        found.add(match[0]);
+    }
     return [...found];
 }
 function questionText(question) {
-    const criteria = question.criteria;
     return [
         question.instructions,
-        ...(criteria ? Object.values(criteria) : []),
+        ...Object.values(question.criteria ?? {}),
     ].join("\n");
 }
 function readingTexts(plan) {
     return plan.readings.map((reading) => ({
         id: reading.id,
+        about: plan.asks[reading.askIndex]?.about,
         text: [reading.id, reading.twin, ...Object.values(reading.controls ?? {})]
             .flatMap((id) => id && plan.questions[id] ? [questionText(plan.questions[id])] : [])
             .join("\n"),
     }));
 }
-function normalized(path) {
-    return path.replace(/^(?:\.\/)+/, "");
-}
-export function resolveAskReferences(plan, note, files, inventory) {
-    const references = new Set(readingTexts(plan).flatMap(({ text }) => citedPaths(text)));
-    for (const reference of citedPaths(note ?? ""))
-        references.add(reference);
-    const paths = [...new Set([...inventory, ...Object.keys(files)])];
-    const exact = new Map(paths.map((path) => [normalized(path), path]));
-    const selected = new Set(Object.keys(files).map(normalized));
+export function resolveAskReferences(plan, note, evidence, inventory) {
+    const index = evidence.files !== null && typeof evidence.files === "object"
+        ? evidence
+        : { files: evidence };
+    const supplied = [
+        ...new Set([
+            ...Object.keys(index.files),
+            ...Object.keys(index.files_before ?? {}),
+        ]),
+    ].sort();
+    const currentKnown = [...new Set(inventory)].sort();
+    const beforeKnown = [
+        ...new Set([...inventory, ...(index.beforeInventory ?? [])]),
+    ].sort();
+    const selected = new Set(supplied.map(normalized));
+    const versions = new Set([
+        ...Object.keys(index.files).map((path) => `files:${normalized(path)}`),
+        ...Object.keys(index.files_before ?? {}).map((path) => `files_before:${normalized(path)}`),
+    ]);
     const additions = [];
     const unresolved = [];
-    for (const reference of references) {
-        if (Object.hasOwn(files, reference))
-            continue;
-        const key = normalized(reference);
-        const direct = exact.get(key);
-        const matches = direct
-            ? [direct]
-            : paths.filter((path) => normalized(path).endsWith(`/${key}`));
-        if (matches.length !== 1) {
-            unresolved.push({
-                reference,
-                reason: `${reference} is cited but missing from state (${matches.length ? "ambiguous path" : "not found"})`,
-            });
-            continue;
-        }
-        const path = matches[0];
-        if (path === undefined)
-            continue;
-        if (!selected.has(normalized(path)) && selected.size >= ASK_MAX_FILES) {
-            unresolved.push({
+    const invalid = [];
+    const aliases = Object.create(null);
+    const sources = [
+        ...readingTexts(plan).map(({ id, text, about }) => ({
+            text: `${about ?? ""}\n${text}`,
+            scope: id,
+            origin: "question",
+            output: about === "output",
+        })),
+        {
+            text: note ?? "",
+            scope: "global",
+            origin: "note",
+            output: false,
+        },
+    ];
+    for (const source of sources) {
+        const explicit = explicitPaths(source.text);
+        const explicitNames = new Set(explicit.map(({ reference }) => reference));
+        const references = [
+            ...explicit.map((ref) => ({ ...ref, required: true })),
+            ...(source.output
+                ? []
+                : citedPaths(source.text)
+                    .filter((reference) => !explicitNames.has(reference))
+                    .map((reference) => ({
+                    reference,
+                    side: "files",
+                    required: false,
+                }))),
+        ];
+        for (const ref of references) {
+            const { reference, required, side } = ref;
+            const known = side === "files_before" ? beforeKnown : currentKnown;
+            const facts = {
                 reference,
-                reason: `${reference} is cited but missing from state (ASK_MAX_FILES limit: ${ASK_MAX_FILES})`,
-            });
-            continue;
+                required,
+                side,
+                origin: source.origin,
+                scope: source.scope,
+            };
+            if (forbidden(reference)) {
+                if (required)
+                    invalid.push({
+                        ...facts,
+                        reason: `Path not permitted: ${reference}`,
+                    });
+                continue;
+            }
+            const key = normalized(reference);
+            // Directory-bearing explicit paths are exact, never suffix fallbacks.
+            const exact = supplied.find((path) => normalized(path) === key);
+            const abbreviated = !key.includes("/");
+            let matches = exact ? [exact] : [];
+            if (!matches.length && abbreviated) {
+                const alias = index.aliases && Object.hasOwn(index.aliases, reference)
+                    ? index.aliases[reference]
+                    : undefined;
+                if (alias !== undefined)
+                    matches = (typeof alias === "string" ? [alias] : [...alias]).filter((path) => supplied.includes(path));
+                if (!matches.length)
+                    matches = supplied.filter((path) => normalized(path).endsWith(`/${key}`));
+            }
+            if (!matches.length)
+                matches = known.filter((path) => normalized(path) === key);
+            if (!matches.length && abbreviated)
+                matches = known.filter((path) => normalized(path).endsWith(`/${key}`));
+            if (matches.length !== 1) {
+                if (required)
+                    unresolved.push({
+                        ...facts,
+                        reason: `${reference} is required but missing from state (${matches.length ? "ambiguous path" : "not found"})`,
+                    });
+                continue;
+            }
+            const path = matches[0];
+            if (path === undefined)
+                continue;
+            aliases[reference] = path;
+            const identity = normalized(path);
+            const version = `${side}:${identity}`;
+            if (versions.has(version))
+                continue;
+            if (!selected.has(identity) && selected.size >= ASK_MAX_FILES) {
+                unresolved.push({
+                    ...facts,
+                    reason: `${reference} omitted (ASK_MAX_FILES limit: ${ASK_MAX_FILES})`,
+                });
+                continue;
+            }
+            selected.add(identity);
+            versions.add(version);
+            additions.push({ ...facts, path });
         }
-        selected.add(normalized(path));
-        additions.push({ reference, path });
     }
-    return { additions, unresolved };
+    return { additions, unresolved, aliases, invalid };
 }
 function object(value) {
     return value !== null && typeof value === "object";
@@ -126,69 +203,76 @@ function unpack(value) {
     }
 }
 function empty(value) {
-    return (value === null ||
+    return (value === undefined ||
+        value === null ||
         (typeof value === "string" && value.trim() === "") ||
         (object(value) && Object.keys(value).length === 0));
 }
 function emptyReference(text, state) {
-    // File references can be plain paths, not just selectors.
-    const files = state.files;
-    if (object(files)) {
-        for (const reference of citedPaths(text)) {
-            if (Object.hasOwn(files, reference) && empty(files[reference]))
-                return reference;
-        }
-    }
+    const metadata = object(state.evidence) ? state.evidence : {};
+    const aliases = object(metadata.aliases) ? metadata.aliases : {};
     for (const match of text.matchAll(selector)) {
         const parts = [
             ...match[0].matchAll(/[A-Za-z_$][\w$]*|"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|\d+/g),
         ].map(([part]) => (/^["']/.test(part) ? unquote(part) : part));
         const root = parts[0];
-        if (root === undefined)
+        if (!root)
             continue;
-        let value;
-        let offset;
-        if (root === "state") {
-            value = state;
-            offset = 1;
-        }
-        else if (Object.hasOwn(state, root)) {
-            value = state[root];
-            offset = 1;
-        }
-        else
+        if (!["state", "output", "files", "files_before"].includes(root) &&
+            !Object.hasOwn(state, root))
             continue;
-        let present = true;
-        for (const part of parts.slice(offset)) {
+        if (!/[.[]/.test(match[0]) && text.trim() !== match[0].trim())
+            continue;
+        let value = root === "state"
+            ? Object.hasOwn(state, "state")
+                ? state.state
+                : state
+            : state[root];
+        const tail = parts.slice(1);
+        if ((root === "files" || root === "files_before") &&
+            tail[0] &&
+            object(value) &&
+            !Object.hasOwn(value, tail[0])) {
+            const alias = Object.hasOwn(aliases, tail[0])
+                ? aliases[tail[0]]
+                : undefined;
+            if (typeof alias === "string")
+                tail[0] = alias;
+        }
+        for (const part of tail) {
             value = unpack(value);
-            if (!object(value) || !Object.hasOwn(value, part)) {
-                present = false;
-                break;
-            }
-            value = value[part];
+            value =
+                object(value) && Object.hasOwn(value, part) ? value[part] : undefined;
         }
-        // A file absent from the base proves creation; it is not empty evidence.
-        if (root === "files_before" && value === null)
+        // null before is admitted only by the base reader for a tracked-tree absence.
+        if (root === "files_before" &&
+            value === null &&
+            typeof state.base_sha === "string" &&
+            state.base_sha.length > 0)
             continue;
-        if (present && empty(unpack(value)))
+        if (empty(root === "files" || root === "files_before" ? value : unpack(value)))
             return match[0].trim();
     }
     return undefined;
 }
 export function blockedAskReadings(plan, state, unresolved, note) {
     const blocked = new Map();
-    const notePaths = new Set(citedPaths(note ?? ""));
     const noteEmpty = emptyReference(note ?? "", state);
-    for (const { id, text } of readingTexts(plan)) {
-        const paths = new Set(citedPaths(text));
-        const missing = unresolved.find(({ reference }) => paths.has(reference) || notePaths.has(reference));
+    for (const { id, text, about } of readingTexts(plan)) {
+        const explicit = new Set(explicitPaths(`${about ?? ""}\n${text}`).map(({ reference }) => reference));
+        const missing = unresolved.find((ref) => ref.required !== false &&
+            (ref.scope === "global" ||
+                ref.scope === id ||
+                (ref.scope === undefined && explicit.has(ref.reference))));
         if (missing) {
             blocked.set(id, missing.reason);
             continue;
         }
-        const reference = noteEmpty ?? emptyReference(text, state);
+        const reference = noteEmpty ??
+            (about ? emptyReference(about, state) : undefined) ??
+            emptyReference(text, state);
         if (reference)
-            blocked.set(id, `${reference} is empty`);
+            blocked.set(id, `${reference} is missing or empty`);
     }
     return blocked;
 }

package/dist/core/asks.js

@@ -335,8 +335,7 @@ export function readAsks(plan, answers, reversed = {}) {
                 .join("; ");
             result.push({
                 label: r.label,
-                value: { head: "unjudged", p: 0 },
-                band: "unsure",
+                unjudged: true,
                 reason: `${reason}; ${r.missing}`,
                 uncalibrated: r.uncalibrated,
             });
@@ -350,7 +349,22 @@ export function readAsks(plan, answers, reversed = {}) {
                 : undefined;
             result.push({
                 label: level ? `${r.label} ${JSON.stringify(level)}` : r.label,
+                source: answer.source,
+                ...(answer.type === "bool" ? { publicResult: answer.p >= 0.5 } : {}),
                 answer,
+                rawValues: answer.type === "bool"
+                    ? [
+                        {
+                            label: "bool",
+                            value: answer.p >= 0.5,
+                            probability: { status: "known", value: answer.p },
+                        },
+                    ]
+                    : Object.entries(answer.probabilities).map(([label, value]) => ({
+                        label,
+                        value: label,
+                        probability: { status: "known", value },
+                    })),
                 uncalibrated: r.uncalibrated,
             });
             continue;
@@ -404,13 +418,22 @@ export function readAsks(plan, answers, reversed = {}) {
             }
         }
         if (Object.values(r.controls ?? {}).some((id) => answers[id]?.type !== "bool")) {
-            band = "unsure";
-            reason =
-                "coherence control unjudged; no verdict: rerun with decisive evidence";
+            result.push({
+                label: r.label,
+                unjudged: true,
+                reason: "required coherence control has no valid bool response",
+                missing: r.missing,
+            });
+            continue;
         }
         if (!r.twin && Object.hasOwn(reversed, r.id) && !second) {
-            band = "unsure";
-            reason = `reverse-order control unjudged; no verdict: ${r.missing}`;
+            result.push({
+                label: r.label,
+                unjudged: true,
+                reason: "required reverse-order control unjudged",
+                missing: r.missing,
+            });
+            continue;
         }
         const firstMerged = merged(original, r.kind === "verify");
         const secondMerged = second
@@ -422,6 +445,54 @@ export function readAsks(plan, answers, reversed = {}) {
                 ? `${r.label} ${JSON.stringify(r.options[head])}`
                 : r.label,
             answer: { ...answer, probabilities: p, choice: head },
+            source: answer.source,
+            rawValues: Object.entries(original).map(([label, value]) => ({
+                label,
+                value: label,
+                probability: { status: "known", value },
+            })),
+            reportControls: [
+                ...members.slice(1).map(([id, label]) => ({
+                    id,
+                    label,
+                    answer: answers[id],
+                    kind: "cross_check",
+                })),
+                ...(!r.twin && reversed[r.id]
+                    ? [
+                        {
+                            id: `${r.id}:reverse`,
+                            label: "reverse order",
+                            answer: reversed[r.id],
+                            kind: "order",
+                        },
+                    ]
+                    : []),
+            ].flatMap(({ id, label, answer: a, kind }) => {
+                if (!a || a.type === "unjudged" || !a.source)
+                    return [];
+                return [
+                    {
+                        id,
+                        kind,
+                        source: a.source,
+                        outcome: label,
+                        rawValues: a.type === "bool"
+                            ? [
+                                {
+                                    label,
+                                    value: a.p >= 0.5,
+                                    probability: { status: "known", value: a.p },
+                                },
+                            ]
+                            : Object.entries(a.probabilities).map(([key, value]) => ({
+                                label: key,
+                                value: key,
+                                probability: { status: "known", value },
+                            })),
+                    },
+                ];
+            }),
             value: { head, p: mass },
             band,
             reason,

package/dist/core/locate.js

@@ -11,13 +11,13 @@ export function sectionState(path, goal, sections, outline = false) {
         })),
     };
 }
-export function sectionStateFits(path, goal, sections, outline = false) {
+export function sectionStateFits(path, goal, sections, outline = false, maxChars = STATE_MAX_CHARS) {
     return (sections.length < CHOICE_MAX_OPTIONS &&
         JSON.stringify(sectionState(path, goal, sections, outline)).length <=
-            STATE_MAX_CHARS);
+            maxChars);
 }
 /** Every planned block has at least two sections and fits its full-text refinement budget. */
-export function sectionOutline(path, goal, sections) {
+export function sectionOutline(path, goal, sections, maxChars = STATE_MAX_CHARS) {
     const base = JSON.stringify(sectionState(path, goal, [])).length;
     const costs = new Map(sections.map((section) => [
         section,
@@ -31,16 +31,16 @@ export function sectionOutline(path, goal, sections) {
     ]));
     const fits = (items) => items.length < CHOICE_MAX_OPTIONS &&
         base + items.reduce((sum, item) => sum + (costs.get(item) ?? 0) + 1, 0) <=
-            STATE_MAX_CHARS;
+            maxChars;
     const groups = [];
     let current = [], currentSize = base;
     for (const section of sections) {
         const length = (costs.get(section) ?? 0) + 1;
-        if (base + length > STATE_MAX_CHARS)
+        if (base + length > maxChars)
             return [];
         const owner = section.label.split(".")[0], previousOwner = current.at(-1)?.label.split(".")[0];
         if (current.length &&
-            (currentSize + length > STATE_MAX_CHARS ||
+            (currentSize + length > maxChars ||
                 current.length + 1 >= CHOICE_MAX_OPTIONS ||
                 (current.length >= 2 &&
                     section.label.includes(".") &&
@@ -98,9 +98,9 @@ export function sectionOutline(path, goal, sections) {
     }));
 }
 /** JSON-escaped budget, allocated equally then redistributed to larger blocks. */
-export function outlineEvidence(path, goal, blocks) {
+export function outlineEvidence(path, goal, blocks, maxChars = STATE_MAX_CHARS) {
     const overhead = JSON.stringify(sectionState(path, goal, blocks.map((block) => ({ ...block, text: "" })))).length;
-    let remaining = Math.max(0, STATE_MAX_CHARS - overhead);
+    let remaining = Math.max(0, maxChars - overhead);
     const allocations = blocks.map(() => 0);
     let active = blocks.map((_, index) => index);
     while (remaining > 0 && active.length) {

package/dist/core/output.js

@@ -38,6 +38,15 @@ export function buildEnvelope(input) {
         .map((control) => control.fact)
         .join("; ");
     for (const item of input.answers ?? []) {
+        if (item.unjudged) {
+            lines.push({
+                type: "unjudged",
+                label: item.label,
+                reason: item.reason ?? "required group answer missing",
+                next: item.missing ?? "inspect the available evidence without a judgment",
+            });
+            continue;
+        }
         const value = displayValue(item);
         const initial = item.band ?? (input.policy ?? askBand)(value, item);
         const band = initial === "verdict" && failed ? "unsure" : initial;
@@ -54,6 +63,14 @@ export function buildEnvelope(input) {
             value,
             band,
             uncalibrated: item.uncalibrated ?? false,
+            ...((item.source ?? item.answer?.source)
+                ? { source: item.source ?? item.answer?.source }
+                : {}),
+            ...(item.publicResult !== undefined
+                ? { publicResult: item.publicResult }
+                : {}),
+            ...(item.rawValues ? { rawValues: item.rawValues } : {}),
+            ...(item.reportControls ? { reportControls: item.reportControls } : {}),
             ...(reason ? { reason } : {}),
             ...(item.orderDependent !== undefined
                 ? { orderDependent: item.orderDependent }