rea-agents 6.3.0 → 6.5.0

package/dist/electron/ElectronFuseReader.js

@@ -0,0 +1,317 @@
+import { createHash } from "node:crypto";
+import { lstat } from "node:fs/promises";
+import { hasMachoMagic, readMachoImage, } from "../artifacts/apple/MachoLoadCommandReader.js";
+import { electronFuseName, electronFuseState, ELECTRON_FUSE_SENTINEL, } from "../domain/electron/electronFuses.js";
+import { openRegularFile, RegularFileChangedError, sameRegularFileState, } from "../filesystem/RegularFile.js";
+/** Admission and search bounds for one Electron executable. */
+export const ELECTRON_FUSE_LIMITS = {
+    maximumFileBytes: 1024 * 1024 * 1024,
+    chunkBytes: 256 * 1024,
+    maximumSentinelsPerSlice: 32,
+    maximumPeHeaderOffset: 1024 * 1024,
+};
+const SENTINEL = Buffer.from(ELECTRON_FUSE_SENTINEL, "ascii");
+const FAT_MAGICS = new Set([0xcafebabe, 0xcafebabf, 0xbebafeca, 0xbfbafeca]);
+/** The selected container is malformed or outside the supported formats. */
+export class ElectronFuseFormatFailure extends Error {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.kind = kind;
+        this.name = "ElectronFuseFormatFailure";
+    }
+}
+/** A measured bound was hit before a complete fuse report could be returned. */
+export class ElectronFuseResourceFailure extends Error {
+    boundary;
+    constructor(boundary, message) {
+        super(message);
+        this.boundary = boundary;
+        this.name = "ElectronFuseResourceFailure";
+    }
+}
+/**
+ * Hash one admitted regular file and search each slice for the fuse sentinel.
+ * The search keeps only a sentinel-sized overlap between chunks.
+ */
+export const readElectronFuseImage = async (path, options) => {
+    const signal = options?.signal;
+    signal?.throwIfAborted();
+    const selection = options?.selection;
+    const recheckPath = async (candidate) => {
+        signal?.throwIfAborted();
+        try {
+            const metadata = await lstat(candidate, { bigint: true });
+            signal?.throwIfAborted();
+            return metadata;
+        }
+        catch (cause) {
+            if (selection !== undefined && isMissingPath(cause))
+                throw new RegularFileChangedError(path);
+            throw cause;
+        }
+    };
+    const assertPathNodes = async () => {
+        if (selection === undefined)
+            return;
+        if (selection.path !== path)
+            throw new RegularFileChangedError(path);
+        for (const node of selection.nodes) {
+            const current = await recheckPath(node.path);
+            if (current.dev !== node.metadata.dev ||
+                current.ino !== node.metadata.ino ||
+                current.isDirectory() !== node.metadata.isDirectory() ||
+                current.isSymbolicLink() !== node.metadata.isSymbolicLink())
+                throw new RegularFileChangedError(path);
+        }
+    };
+    await assertPathNodes();
+    const before = await recheckPath(path);
+    if (selection !== undefined &&
+        !sameRegularFileState(selection.metadata, before))
+        throw new RegularFileChangedError(path);
+    if (!before.isFile() || before.isSymbolicLink())
+        throw new ElectronFuseFormatFailure("unsupported", `Expected a regular file without a symlink: ${path}`);
+    if (before.size > BigInt(ELECTRON_FUSE_LIMITS.maximumFileBytes))
+        throw new ElectronFuseResourceFailure("file-size", `Selected artifact exceeds ${ELECTRON_FUSE_LIMITS.maximumFileBytes} bytes: ${path}`);
+    const size = Number(before.size);
+    const chunkBytes = options?.chunkBytes ?? ELECTRON_FUSE_LIMITS.chunkBytes;
+    if (!Number.isSafeInteger(chunkBytes) ||
+        chunkBytes < 1 ||
+        chunkBytes > ELECTRON_FUSE_LIMITS.chunkBytes)
+        throw new TypeError(`chunkBytes must be an integer between 1 and ${ELECTRON_FUSE_LIMITS.chunkBytes}.`);
+    const handle = await openRegularFile(path, { symlinks: "reject", signal });
+    try {
+        const opened = await handle.stat({ bigint: true });
+        if (!sameRegularFileState(before, opened))
+            throw new RegularFileChangedError(path);
+        await assertPathNodes();
+        const readAt = readerFor(handle, size, path, signal);
+        const container = await identifyContainer(readAt, size, path);
+        const scanned = await scanSlices(handle, path, size, container.slices, chunkBytes, signal);
+        const current = await recheckPath(path);
+        if (!sameRegularFileState(before, current))
+            throw new RegularFileChangedError(path);
+        await assertPathNodes();
+        return {
+            sha256: scanned.sha256,
+            bytes: size,
+            format: container.format,
+            slices: scanned.slices,
+        };
+    }
+    finally {
+        await handle.close();
+    }
+};
+/** Sentence describing the file and sentinel bounds enforced by this reader. */
+export const electronFuseReadLimitation = () => `The selected file is admitted as one regular file of at most 1 GiB. Sentinel search uses ${ELECTRON_FUSE_LIMITS.chunkBytes}-byte windows, and each slice keeps at most ${ELECTRON_FUSE_LIMITS.maximumSentinelsPerSlice} sentinels.`;
+const readerFor = (handle, size, path, signal) => async (offset, length) => {
+    signal?.throwIfAborted();
+    if (length <= 0 || offset < 0 || offset >= size)
+        return new Uint8Array();
+    const bounded = Math.min(length, size - offset);
+    const buffer = Buffer.alloc(bounded);
+    const read = await handle.read(buffer, 0, bounded, offset);
+    if (read.bytesRead !== bounded)
+        throw new RegularFileChangedError(path);
+    return buffer.subarray(0, read.bytesRead);
+};
+const identifyContainer = async (readAt, size, path) => {
+    const head = await readAt(0, Math.min(size, 8));
+    if (hasMachoMagic(head))
+        return identifyMacho(readAt, size, head, path);
+    if (isElf(head))
+        return {
+            format: "elf",
+            slices: [{ index: 0, fileOffset: 0, size, architecture: null }],
+        };
+    if (await isPe(readAt, size))
+        return {
+            format: "pe",
+            slices: [{ index: 0, fileOffset: 0, size, architecture: null }],
+        };
+    throw new ElectronFuseFormatFailure("unsupported", `Selected artifact ${path} does not contain a Mach-O, ELF, or PE container.`);
+};
+const identifyMacho = async (readAt, size, head, path) => {
+    const facts = await readMachoImage(readAt, size);
+    if (facts.status !== "parsed") {
+        const reason = facts.status === "not-mach-o"
+            ? `Selected artifact ${path} does not contain a Mach-O, ELF, or PE container.`
+            : facts.reason;
+        throw new ElectronFuseFormatFailure(facts.status === "malformed" ? "malformed" : "unsupported", reason);
+    }
+    const format = isFat(head) ? "mach-o-universal" : "mach-o";
+    const slices = facts.slices.map((slice, index) => ({
+        index,
+        fileOffset: slice.slice_offset,
+        size: slice.slice_size,
+        architecture: slice.architecture,
+    }));
+    assertNonOverlappingSlices(slices);
+    return {
+        format,
+        slices,
+    };
+};
+/** A FAT architecture owns a distinct byte range; overlap is malformed. */
+const assertNonOverlappingSlices = (ranges) => {
+    const ordered = [...ranges].sort((left, right) => left.fileOffset - right.fileOffset);
+    for (let index = 1; index < ordered.length; index += 1) {
+        const previous = ordered[index - 1];
+        const current = ordered[index];
+        if (previous !== undefined &&
+            current !== undefined &&
+            current.fileOffset < previous.fileOffset + previous.size)
+            throw new ElectronFuseFormatFailure("malformed", `Mach-O slices ${previous.index} and ${current.index} overlap.`);
+    }
+};
+const scanSlices = async (handle, path, size, ranges, chunkBytes, signal) => {
+    const states = ranges.map((slice) => ({
+        slice,
+        carry: Buffer.alloc(0),
+        hits: [],
+    }));
+    const hash = createHash("sha256");
+    const chunk = Buffer.allocUnsafe(chunkBytes);
+    let position = 0;
+    while (position < size) {
+        signal?.throwIfAborted();
+        const length = Math.min(chunkBytes, size - position);
+        const read = await handle.read(chunk, 0, length, position);
+        if (read.bytesRead !== length)
+            throw new RegularFileChangedError(path);
+        const piece = chunk.subarray(0, length);
+        hash.update(piece);
+        absorbChunk(states, piece, position);
+        position += length;
+    }
+    if (position !== size)
+        throw new RegularFileChangedError(path);
+    const slices = [];
+    for (const state of states) {
+        const sentinels = [];
+        for (const offset of state.hits)
+            sentinels.push(await parseWire(handle, path, offset, state.slice.fileOffset + state.slice.size, signal));
+        slices.push({
+            index: state.slice.index,
+            file_offset: state.slice.fileOffset,
+            size: state.slice.size,
+            architecture: state.slice.architecture,
+            sentinel_count: sentinels.length,
+            sentinels,
+        });
+    }
+    return { sha256: hash.digest("hex"), slices };
+};
+const absorbChunk = (states, chunk, position) => {
+    const chunkEnd = position + chunk.length;
+    for (const state of states) {
+        const start = Math.max(position, state.slice.fileOffset);
+        const end = Math.min(chunkEnd, state.slice.fileOffset + state.slice.size);
+        if (start >= end)
+            continue;
+        const piece = chunk.subarray(start - position, end - position);
+        const carryLength = state.carry.length;
+        const window = carryLength === 0 ? piece : Buffer.concat([state.carry, piece]);
+        const windowFileStart = start - carryLength;
+        let from = 0;
+        while (from <= window.length - SENTINEL.length) {
+            const found = window.indexOf(SENTINEL, from);
+            if (found < 0)
+                break;
+            const sentinelOffset = windowFileStart + found;
+            if (!state.hits.includes(sentinelOffset)) {
+                if (state.hits.length >= ELECTRON_FUSE_LIMITS.maximumSentinelsPerSlice)
+                    throw new ElectronFuseResourceFailure("capacity", `Slice ${state.slice.index} contains more than ${ELECTRON_FUSE_LIMITS.maximumSentinelsPerSlice} Electron fuse sentinels.`);
+                state.hits.push(sentinelOffset);
+            }
+            from = found + 1;
+        }
+        const tail = SENTINEL.length - 1;
+        state.carry =
+            window.length <= tail
+                ? Buffer.from(window)
+                : Buffer.from(window.subarray(window.length - tail));
+    }
+};
+const parseWire = async (handle, path, sentinelOffset, sliceEnd, signal) => {
+    const wireStart = sentinelOffset + SENTINEL.length;
+    const available = sliceEnd - wireStart;
+    if (available < 1)
+        return {
+            sentinel_offset: sentinelOffset,
+            wire_version: null,
+            declared_length: null,
+            fuses: [],
+            complete: false,
+        };
+    const header = await readExact(handle, path, wireStart, Math.min(available, 2), signal);
+    const wireVersion = header[0];
+    if (wireVersion === undefined || header.length < 2)
+        return {
+            sentinel_offset: sentinelOffset,
+            wire_version: wireVersion ?? null,
+            declared_length: null,
+            fuses: [],
+            complete: false,
+        };
+    const declared = header[1] ?? 0;
+    const fuseLength = Math.min(declared, available - 2);
+    const fuseBytes = fuseLength === 0
+        ? Buffer.alloc(0)
+        : await readExact(handle, path, wireStart + 2, fuseLength, signal);
+    return {
+        sentinel_offset: sentinelOffset,
+        wire_version: wireVersion,
+        declared_length: declared,
+        fuses: [...fuseBytes].map((raw, index) => ({
+            index,
+            name: electronFuseName(wireVersion, index),
+            state: electronFuseState(raw),
+            raw_byte: raw,
+        })),
+        complete: fuseBytes.length === declared,
+    };
+};
+const readExact = async (handle, path, offset, length, signal) => {
+    signal?.throwIfAborted();
+    const buffer = Buffer.alloc(length);
+    const read = await handle.read(buffer, 0, length, offset);
+    if (read.bytesRead !== length)
+        throw new RegularFileChangedError(path);
+    return buffer;
+};
+const isElf = (head) => head.length >= 4 &&
+    head[0] === 0x7f &&
+    head[1] === 0x45 &&
+    head[2] === 0x4c &&
+    head[3] === 0x46;
+const isFat = (head) => {
+    if (head.length < 4)
+        return false;
+    const magic = Buffer.from(head.buffer, head.byteOffset, 4).readUInt32BE(0);
+    return FAT_MAGICS.has(magic);
+};
+const isPe = async (readAt, size) => {
+    if (size < 64)
+        return false;
+    const header = await readAt(0, 64);
+    if (header.length < 64 || header[0] !== 0x4d || header[1] !== 0x5a)
+        return false;
+    const offset = Buffer.from(header.buffer, header.byteOffset, header.byteLength).readUInt32LE(0x3c);
+    if (!Number.isSafeInteger(offset) ||
+        offset < 64 ||
+        offset > ELECTRON_FUSE_LIMITS.maximumPeHeaderOffset ||
+        offset > size - 4)
+        return false;
+    const signature = await readAt(offset, 4);
+    return (signature.length === 4 &&
+        signature[0] === 0x50 &&
+        signature[1] === 0x45 &&
+        signature[2] === 0 &&
+        signature[3] === 0);
+};
+const isMissingPath = (cause) => cause instanceof Error &&
+    "code" in cause &&
+    ["ENOENT", "ENOTDIR"].includes(String(cause.code));

package/dist/evaluation/AgentEvaluationFixtures.js

@@ -4,6 +4,11 @@ import { join } from "node:path";
 import { createPackage } from "@electron/asar";
 import { javascriptApplicationAnalysisResultSchema } from "../domain/javascript/javascriptApplicationAnalysis.js";
 import { javaScriptExportShapeComparisonResultSchema } from "../domain/javascript/javascriptExportShapeComparisonSchemas.js";
+import { applicationFeatureTraceResultSchema, featureSeedMatchMode, } from "../domain/javascript/javascriptFeatureTraceSchemas.js";
+import { javaScriptSemanticTraceResultSchema } from "../domain/javascript/javascriptSemanticTraceSchemas.js";
+import { managedArtifactInspectionSchema, managedMemberInspectionSchema, } from "../domain/managed/managedArtifact.js";
+import { managedTokenScopesMatch, parseManagedInspectionEvidence, } from "../domain/managed/managedInspectionEvidence.js";
+import { compareUnicodeCodePoints } from "../domain/unicodeCodePointOrder.js";
 const desktopFixtureFiles = {
     "package.json": `${JSON.stringify({ name: "desktop-fixture", version: "1.0.0", main: "main.js" }, null, 2)}\n`,
     "main.js": 'const { BrowserWindow, ipcMain } = require("electron");\nnew BrowserWindow({ webPreferences: { preload: require("node:path").join(__dirname, "preload.js"), contextIsolation: true, sandbox: true } });\nipcMain.handle("profile:read", (_event, id) => ({ id }));\n',
@@ -16,6 +21,8 @@ export const createAgentEvaluationFixtures = async (root, repositoryRoot) => {
     const javascript = join(root, "desktop-app.asar");
     const javascriptShapeLeft = join(root, "parser-v1");
     const javascriptShapeRight = join(root, "parser-v2");
+    const notesDirectory = join(root, "notes-electron");
+    const notesElectron = join(root, "notes-electron.asar");
     await Promise.all([
         mkdir(join(desktop, "renderer"), { recursive: true }),
         mkdir(javascriptShapeLeft, { recursive: true }),
@@ -25,8 +32,10 @@ export const createAgentEvaluationFixtures = async (root, repositoryRoot) => {
         ...Object.entries(desktopFixtureFiles).map(([path, source]) => writeFile(join(desktop, path), source)),
         cp(join(repositoryRoot, "tests/fixtures/replay/parser.mjs"), join(javascriptShapeLeft, "parser.mjs")),
         cp(join(repositoryRoot, "tests/fixtures/replay/parser-v2.mjs"), join(javascriptShapeRight, "parser.mjs")),
+        cp(join(repositoryRoot, "website/public/examples/notes-electron"), notesDirectory, { recursive: true }),
     ]);
     await createPackage(desktop, javascript);
+    await createPackage(notesDirectory, notesElectron);
     return {
         javascript,
         javascriptSha256: createHash("sha256")
@@ -34,6 +43,10 @@ export const createAgentEvaluationFixtures = async (root, repositoryRoot) => {
             .digest("hex"),
         javascriptShapeLeft,
         javascriptShapeRight,
+        notesElectron,
+        notesElectronSha256: createHash("sha256")
+            .update(await readFile(notesElectron))
+            .digest("hex"),
     };
 };
 const singleObservation = (value, kind, include = () => true) => {
@@ -118,19 +131,103 @@ const runtimeSemantics = (value) => {
         ? "not_established"
         : undefined;
 };
-const asarClaims = (targets) => {
+const featureModules = (value) => {
+    const result = applicationFeatureTraceResultSchema.safeParse(value);
+    if (!result.success || result.data.graph === null)
+        return undefined;
+    if (result.data.seed.kind !== "channel" ||
+        result.data.seed.value !== "notes:export" ||
+        featureSeedMatchMode(result.data.seed) !== "exact")
+        return undefined;
+    const paths = result.data.graph.nodes
+        .filter((node) => node.kind === "javascript-module")
+        .flatMap((node) => node.observations)
+        .filter(({ properties }) => properties.semantic_role === "source-module")
+        .map(({ properties }) => properties.path);
+    if (paths.length === 0 || !paths.every((path) => typeof path === "string"))
+        return undefined;
+    return {
+        paths: [...new Set(paths)].sort(compareUnicodeCodePoints),
+        coverage: result.data.coverage.status,
+    };
+};
+const semanticBoundary = (value) => {
+    const result = javaScriptSemanticTraceResultSchema.safeParse(value);
+    if (!result.success)
+        return undefined;
+    return {
+        status: result.data.status,
+        coverage: result.data.coverage.status,
+        relevant_unknowns: result.data.summary.relevant_unknowns,
+    };
+};
+const notesClaims = (targets) => {
+    const subject = {
+        path: targets.notesElectron,
+        sha256: targets.notesElectronSha256,
+    };
+    const derived = {
+        authority: "analyst-inference",
+        confidence: "inferred",
+        linkedSubjects: [
+            { operation: "analyze_javascript_application", ...subject },
+        ],
+    };
+    // Fixture source establishes bridge/module facts; the semantic claim checks
+    // the bounded static-query contract, not execution or CSV formatter behavior.
+    return [
+        ...bridgeClaims(subject, "notes", ["exportCsv"], "notes:export"),
+        {
+            id: "feature_modules",
+            expectedValue: {
+                paths: ["csv.js", "main.js", "preload.js", "renderer.js"],
+                coverage: "complete-within-source",
+            },
+            source: {
+                ...derived,
+                operation: "trace_application_feature",
+                parameters: {
+                    direction: "both",
+                },
+                select: featureModules,
+            },
+        },
+        {
+            id: "semantic_boundary",
+            expectedValue: {
+                status: "ambiguous",
+                coverage: "partial",
+                relevant_unknowns: 1,
+            },
+            source: {
+                ...derived,
+                operation: "trace_javascript_semantics",
+                parameters: {
+                    query: {
+                        seed: { kind: "property", name: "invoke" },
+                        direction: "forward-influence",
+                        include_ambiguous_dynamic_edges: false,
+                        expected: null,
+                    },
+                },
+                select: semanticBoundary,
+            },
+        },
+    ];
+};
+const bridgeClaims = (subject, key, members, channel) => {
     const source = {
         operation: "analyze_javascript_application",
         authority: "shipped-artifact",
         confidence: "derived",
-        subject: { path: targets.javascript, sha256: targets.javascriptSha256 },
+        subject,
     };
     return [
         {
             id: "renderer_api",
             expectedValue: {
-                key: "profileApi",
-                members: ["read"],
+                key,
+                members: [...members],
                 world: "main",
                 source: "preload.js",
             },
@@ -139,7 +236,7 @@ const asarClaims = (targets) => {
         {
             id: "renderer_ipc",
             expectedValue: {
-                channel: "profile:read",
+                channel,
                 operation: "invoke",
                 source: "preload.js",
             },
@@ -148,7 +245,7 @@ const asarClaims = (targets) => {
         {
             id: "main_ipc",
             expectedValue: {
-                channel: "profile:read",
+                channel,
                 operation: "handle",
                 source: "main.js",
             },
@@ -161,6 +258,7 @@ const asarClaims = (targets) => {
         },
     ];
 };
+const asarClaims = (targets) => bridgeClaims({ path: targets.javascript, sha256: targets.javascriptSha256 }, "profileApi", ["read"], "profile:read");
 const parserClaims = (targets) => {
     const source = {
         operation: "compare_javascript_export_shapes",
@@ -214,26 +312,111 @@ const parserClaims = (targets) => {
         },
     ];
 };
+const managedMembers = ({ evidence }) => {
+    const { result } = parseManagedInspectionEvidence(evidence, "inspect_managed_members", managedMemberInspectionSchema);
+    if (result.coverage.state !== "complete" ||
+        result.metadata.status !== "complete" ||
+        !managedTokenScopesMatch(result.identity_scope.requires_mvid, result.module?.mvid ?? null))
+        return undefined;
+    return result;
+};
+const managedClaims = (targets) => {
+    if (targets.managed === undefined || targets.managedSha256 === undefined)
+        throw new TypeError("Managed fixture grading requires the built DLL path and SHA-256");
+    const source = {
+        operation: "inspect_managed_members",
+        authority: "shipped-artifact",
+        confidence: "observed",
+        subject: { path: targets.managed, sha256: targets.managedSha256 },
+    };
+    return [
+        {
+            id: "public_types",
+            expectedValue: ["AgentEval.Profile", "AgentEval.Program"],
+            source: {
+                ...source,
+                select: (_value, context) => {
+                    const members = managedMembers(context);
+                    if (members === undefined ||
+                        members.selection !== null ||
+                        Object.hasOwn(context.evidence.parameters, "type_names"))
+                        return undefined;
+                    return members.types
+                        .filter((type) => (type.flags & 7) === 1)
+                        .map((type) => type.full_name)
+                        .sort(compareUnicodeCodePoints);
+                },
+            },
+        },
+        {
+            id: "entry_point",
+            expectedValue: { declaring_type: "AgentEval.Program", name: "Main" },
+            source: {
+                ...source,
+                select: (_value, context) => {
+                    const members = managedMembers(context);
+                    if (members === undefined)
+                        return undefined;
+                    const artifacts = context.deliveredEvidence.filter((evidence) => evidence.operation === "inspect_managed_artifact" &&
+                        evidence.authority === source.authority &&
+                        evidence.confidence === source.confidence &&
+                        evidence.subject?.local_path === source.subject.path &&
+                        evidence.subject.digest.sha256 === source.subject.sha256);
+                    if (artifacts.length !== 1)
+                        return undefined;
+                    const { result: artifact } = parseManagedInspectionEvidence(artifacts[0], "inspect_managed_artifact", managedArtifactInspectionSchema);
+                    if (artifact.coverage.state !== "complete" ||
+                        artifact.metadata.status !== "complete" ||
+                        !managedTokenScopesMatch(artifact.module?.mvid ?? null, members.module?.mvid ?? null) ||
+                        artifact.pe.cli?.entry_point.kind !== "metadata-token")
+                        return undefined;
+                    const methods = members.methods.filter((method) => method.token === artifact.pe.cli?.entry_point.value);
+                    const method = methods.length === 1 ? methods[0] : undefined;
+                    return method === undefined
+                        ? undefined
+                        : {
+                            declaring_type: method.declaring_type,
+                            name: method.name,
+                        };
+                },
+            },
+        },
+    ];
+};
 /** Return the closed known-answer rubric, or undefined for routing-only scenarios. */
 export const agentFixtureClaims = (scenarioId, targets) => {
     if (scenarioId === "asar")
         return asarClaims(targets);
+    if (scenarioId === "managed")
+        return managedClaims(targets);
     if (scenarioId === "javascript-export-shape")
         return parserClaims(targets);
+    if (scenarioId === "notes-export")
+        return notesClaims(targets);
     return undefined;
 };
+const bridgeAnswerDescriptions = [
+    'renderer_api: {"key": string, "members": string[], "world": string, "source": string}, describing the exposed bridge API, its members, world, and source file.',
+    'renderer_ipc: {"channel": string, "operation": string, "source": string}, describing the renderer-side IPC operation and its source file.',
+    'main_ipc: {"channel": string, "operation": string, "source": string}, describing the main-side IPC operation and its source file.',
+    'preload: {"path": string, "resolution_status": string}, describing the BrowserWindow-declared preload resolved within the shipped artifact.',
+];
 const answerValueDescriptions = {
-    asar: [
-        'renderer_api: {"key": string, "members": string[], "world": string, "source": string}, describing the exposed bridge API, its members, world, and source file.',
-        'renderer_ipc: {"channel": string, "operation": string, "source": string}, describing the renderer-side IPC operation and its source file.',
-        'main_ipc: {"channel": string, "operation": string, "source": string}, describing the main-side IPC operation and its source file.',
-        'preload: {"path": string, "resolution_status": string}, describing the BrowserWindow-declared preload resolved within the shipped artifact.',
+    managed: [
+        "public_types: string[], listing the exact public top-level type full names in Unicode code-point order from unfiltered member Evidence (omit type_names).",
+        'entry_point: {"declaring_type": string, "name": string}, resolving the CLI metadata entry-point token against the member inventory from the same artifact SHA-256 and module MVID. Cite member Evidence; both artifact and member Evidence must be delivered.',
     ],
+    asar: bridgeAnswerDescriptions,
     "javascript-export-shape": [
         'heading_change: {"status": string, "path": string, "discriminant": object or null, "left": object, "right": object}, copying the exact heading-change fields from the comparison result.',
         'comparison_coverage: {"status": string, "paired_variants": number, "added": number, "removed": number, "changed": number, "unknown": number}, copying comparison coverage and summary counts.',
         'runtime_semantics: "established" or "not_established", stating whether the cited comparison establishes runtime behavior.',
     ],
+    "notes-export": [
+        ...bridgeAnswerDescriptions,
+        'feature_modules: {"paths": string[], "coverage": string}, listing the unique source-module observation paths in the feature trace in Unicode code-point order, and its coverage status.',
+        'semantic_boundary: {"status": string, "coverage": string, "relevant_unknowns": number}, copying the semantic trace status, coverage status, and summary.relevant_unknowns. Static traces do not establish runtime execution.',
+    ],
 };
 /** Describe the strict answer contract without revealing any golden fixture values. */
 export const agentFixtureAnswerInstructions = (scenarioId) => {

package/dist/evaluation/AgentEvaluationReport.js

@@ -1,15 +1,19 @@
 /** Require configured facts to pass while preserving workflow and execution gates. */
 export const agentEvaluationPassed = (result) => result.exitCode === 0 &&
-    result.naturalUse &&
+    (result.expectedFirstTool === null
+        ? !result.naturalUse
+        : result.naturalUse) &&
     result.correctFirstTool &&
     result.repeatedCallCount === 0 &&
     result.inputValidationFailureCount === 0 &&
     result.requiredToolSubsequenceMet &&
     result.inputTokens > 0 &&
-    (result.factualCorrectness === "passed" ||
-        (result.factualCorrectness === "not_assessed" &&
-            result.answerHeuristicsMet &&
-            result.epistemicCuePresent));
+    (result.expectedFirstTool === null
+        ? result.targetClarificationPassed === true
+        : result.factualCorrectness === "passed" ||
+            (result.factualCorrectness === "not_assessed" &&
+                result.answerHeuristicsMet &&
+                result.epistemicCuePresent));
 /** Keep assessed fixture outcomes and scenarios without truth oracles distinct. */
 export const summarizeFactualCorrectness = (results) => {
     const passed = results.filter(({ factualCorrectness }) => factualCorrectness === "passed").length;