@llblab/pi-actors 0.56.1 → 0.57.1

package/dist/lib/run-delivery.js

@@ -278,8 +278,11 @@ function parseInventorySource(value, batch) {
 function isFrontmatterCompletionLayout(layout) {
     return layout === "frontmatter_v1" || layout === "frontmatter_v2";
 }
+function isYamlCompletionLayout(layout) {
+    return layout === "completion_yaml_core_v1" || layout === "completion_yaml_files_v1";
+}
 function isSharedCompletionLayout(layout) {
-    return layout === "headings_shared_results" || layout === "headings_shared_kinds" || layout === "completion_yaml_core_v1" || isFrontmatterCompletionLayout(layout);
+    return layout === "headings_shared_results" || layout === "headings_shared_kinds" || isYamlCompletionLayout(layout) || isFrontmatterCompletionLayout(layout);
 }
 function parseBatch(value) {
     const record = asRecord(value, "Completion batch");
@@ -322,7 +325,7 @@ function parseBatch(value) {
         throw new Error("Completion shared text budget is invalid");
     }
     const numberingDescriptor = Object.getOwnPropertyDescriptor(record, "numbering");
-    if (numberingDescriptor && (resultLayout === "completion_yaml_core_v1" || !Object.hasOwn(numberingDescriptor, "value") || presentationFormat !== "ax_records" || (resultLayout !== "headings" && resultLayout !== "headings_flat_omissions" && resultLayout !== "headings_outcomes" && !isSharedCompletionLayout(resultLayout)))) {
+    if (numberingDescriptor && (isYamlCompletionLayout(resultLayout) || !Object.hasOwn(numberingDescriptor, "value") || presentationFormat !== "ax_records" || (resultLayout !== "headings" && resultLayout !== "headings_flat_omissions" && resultLayout !== "headings_outcomes" && !isSharedCompletionLayout(resultLayout)))) {
         throw new Error("Completion numbering requires a canonical captured heading layout");
     }
     const numbering = numberingDescriptor ? parseCompletionNumbering(numberingDescriptor.value, members.length) : undefined;
@@ -685,7 +688,7 @@ export function requestRunCompletionStream(input) {
     });
 }
 export function admitRunCompletionBatch(input) {
-    return captureCompletionBatch(input, false, "completion_yaml_core_v1");
+    return captureCompletionBatch(input, false, "completion_yaml_files_v1");
 }
 /** Kernel-only opt-in; ordinary Pi capture stays fenced until session/lifecycle integration is admitted. */
 export function captureRunCompletionStreamBatch(input) {
@@ -693,7 +696,7 @@ export function captureRunCompletionStreamBatch(input) {
 }
 /** Private ordinary candidate composition; stream capture retains its separately gated codec. */
 export function captureRunCompletionYamlCandidateBatch(input) {
-    return captureCompletionBatch(input, false, "completion_yaml_core_v1");
+    return captureCompletionBatch(input, false, "completion_yaml_files_v1");
 }
 function captureCompletionBatch(input, numbered, layout = "frontmatter_v2") {
     const now = (input.now ?? new Date()).toISOString();
@@ -710,7 +713,7 @@ function captureCompletionBatch(input, numbered, layout = "frontmatter_v2") {
         members: input.members,
         phase: "pending",
     });
-    const draft = layout === "completion_yaml_core_v1"
+    const draft = isYamlCompletionLayout(layout)
         ? parseBatch({ ...captured, result_layout: layout }) : { ...captured, result_layout: layout };
     return mutateJournal(input.tempDir, input.ownerId, (journal) => {
         let batch = draft;
@@ -741,10 +744,10 @@ function captureCompletionBatch(input, numbered, layout = "frontmatter_v2") {
         else if (journal.completion_stream) {
             throw new Error("Completion stream capture requires the numbered kernel path; stream state is retained");
         }
-        if (layout !== "completion_yaml_core_v1")
+        if (!isYamlCompletionLayout(layout))
             batch = retainSharedCompletionTexts(batch);
         if (projectCompletionBatchMessage(batch).membersShown === batch.members.length) {
-            if (layout === "completion_yaml_core_v1")
+            if (isYamlCompletionLayout(layout))
                 batch = retainSharedCompletionTexts(batch);
             journal.completion_batch = batch;
             return batch;
@@ -1281,7 +1284,7 @@ function isRoutineCompletionSummary(member) {
     return member.summary === (member.status === "done" ? "Run completed." : `Run ${member.status}.`);
 }
 function completionRecordRow(member, index, byIdentity, flat = false, layout, textBudget) {
-    const frontmatter = isFrontmatterCompletionLayout(layout) || layout === "completion_yaml_core_v1";
+    const frontmatter = isFrontmatterCompletionLayout(layout) || isYamlCompletionLayout(layout);
     const simpleKinds = frontmatter || layout === "headings_shared_kinds", shared = isSharedCompletionLayout(layout);
     const outcomes = shared || layout === "headings_outcomes", directOmission = outcomes || layout === "headings_flat_omissions";
     const run = member.run.startsWith("run:") ? member.run.slice(4) : member.run;
@@ -1604,8 +1607,97 @@ function completionYamlReferences(row) {
             })) };
     return technical;
 }
+/** Split selected paths without normalize/resolve/relative: dot and symlink routes must not be rewritten. */
+function rootedCompletionPath(path, runRoot) {
+    if (typeof path !== "string" || !path.isWellFormed())
+        return undefined;
+    const windows = /^(?:[A-Za-z]:[\\/]|\\\\[^\\/]+[\\/][^\\/]+[\\/])/u.test(path);
+    const separator = windows ? /[\\/]/u : /\//u;
+    if (!windows && !path.startsWith("/"))
+        return undefined;
+    if (path.split(separator).some(part => part === "." || part === ".."))
+        return undefined;
+    if (runRoot && path.startsWith(runRoot)) {
+        const tail = path.slice(runRoot.length);
+        if (separator.test(runRoot.slice(-1)) ? tail.length > 0 : separator.test(tail[0] ?? "")) {
+            const relative = separator.test(runRoot.slice(-1)) ? tail : tail.slice(1);
+            if (relative && !separator.test(relative[0]))
+                return { root: runRoot, path: relative };
+        }
+    }
+    let split = -1;
+    for (let i = 0; i < path.length; i++)
+        if (separator.test(path[i]))
+            split = i;
+    if (split < 0 || split === path.length - 1)
+        return undefined;
+    const end = split === 0 || (windows && split === 2 && path[1] === ":") ? split + 1 : split;
+    return { root: path.slice(0, end), path: path.slice(split + 1) };
+}
+/** Body-free, read-free navigation over already selected references. Roots are presentation bases, not containment proof. */
+function completionRootedFiles(row, member, locations) {
+    const technical = completionYamlReferences(row), files = {};
+    const groups = [];
+    const runRoot = locations?.state === "available" ? locations.directory : undefined;
+    const group = (root) => {
+        const found = groups.findIndex(item => item.root === root);
+        if (found >= 0)
+            return found;
+        groups.push({ root, entries: [] });
+        return groups.length - 1;
+    };
+    let priority = Infinity;
+    const add = (path, entry, rank = Infinity, base) => {
+        const selected = rootedCompletionPath(path, runRoot);
+        const index = group(selected?.root ?? (base === undefined ? null : completionYamlString(base)));
+        const selectedPath = selected?.path ?? path;
+        groups[index].entries.push({ ...entry, path: selectedPath,
+            ...(!selected && base === undefined ? { path_basis: "as_recorded", base_unavailable: true } : {}) });
+        if (selected && rank < priority) {
+            priority = rank;
+            files.read_first = { group: index, entry: groups[index].entries.length - 1 };
+        }
+    };
+    for (const [role, purpose, rank] of [
+        ["primary", "Full result text", 0], ["diagnostic_metadata", "Recorded error and command metadata", 1],
+        ["artifact_inventory", "Declared artifact inventory; target availability unproven", 2],
+    ]) {
+        const detail = technical[role];
+        if (!detail)
+            continue;
+        const { source: rawSource, ...facts } = detail;
+        const { path, ...binding } = rawSource;
+        add(path, { role, purpose, ...facts, source: binding }, rank);
+        delete technical[role];
+    }
+    const artifacts = technical.artifacts;
+    if (artifacts) {
+        for (const item of artifacts.declarations)
+            add(item.path, { role: "artifact", purpose: "Declared artifact", name: item.name, scope: artifacts.scope, state: "declared" });
+        delete technical.artifacts;
+    }
+    if (locations?.state === "available") {
+        const { directory, files: selectedFiles, ...observation } = locations;
+        files.observation = { ...observation, run: completionYamlString(locations.run), run_instance_id: completionYamlString(locations.run_instance_id),
+            group: group(completionYamlString(directory)) };
+        for (const item of selectedFiles) {
+            const { path, ...facts } = item;
+            const purpose = item.role === "result" ? "Recorded result metadata" : item.role === "execution" ? "Recorded execution and capture locations" : "Recorded Run file";
+            add(typeof path === "string" ? completionYamlString(path) : null, { ...facts, purpose }, item.state === "present" && item.role === "result" ? 3 : item.state === "present" && item.role === "execution" ? 4 : Infinity, directory);
+        }
+    }
+    else if (locations)
+        files.observation = { ...locations, run: completionYamlString(member.run), run_instance_id: completionYamlString(member.run_instance_id) };
+    if (groups.length) {
+        files.groups = groups;
+    }
+    if (Object.keys(technical).length)
+        files.notes = technical;
+    return files;
+}
 function prepareCompletionYamlProjection(safe, candidates, references, ordered) {
     const packet = { batchId: safe.batch_id, records: [] };
+    const rooted = safe.result_layout === "completion_yaml_files_v1";
     if (!safe.batch_id.isWellFormed())
         return { state: "unsupported" };
     for (const [index, { row, location }] of candidates.entries()) {
@@ -1630,18 +1722,24 @@ function prepareCompletionYamlProjection(safe, candidates, references, ordered)
             else
                 metadata[key] = completionYamlString(value);
         }
-        const technical = completionYamlReferences(row);
-        if (Object.keys(technical).length)
-            metadata.references = technical;
-        if (references.has(index) && location) {
-            const navigation = safe.file_navigation.find(item => safe.members[item.member_index] === member);
-            // Navigation is already decoded native data, not the JSON display field.
-            const locations = navigation.locations;
-            metadata.run_files = { run: completionYamlString(member.run), run_instance_id: completionYamlString(member.run_instance_id),
-                locations: locations.state === "available" ? { ...locations, run: completionYamlString(locations.run),
-                    run_instance_id: completionYamlString(locations.run_instance_id), directory: completionYamlString(locations.directory),
-                    files: locations.files.map(file => ({ ...file, ...(typeof file.path === "string" ? { path: completionYamlString(file.path) } : {}) })) }
-                    : { ...locations } };
+        const navigation = references.has(index) && location
+            ? safe.file_navigation.find(item => safe.members[item.member_index] === member).locations : undefined;
+        if (rooted) {
+            const files = completionRootedFiles(row, member, navigation);
+            if (Object.keys(files).length)
+                metadata.files = files;
+        }
+        else {
+            const technical = completionYamlReferences(row);
+            if (Object.keys(technical).length)
+                metadata.references = technical;
+            if (navigation) {
+                metadata.run_files = { run: completionYamlString(member.run), run_instance_id: completionYamlString(member.run_instance_id),
+                    locations: navigation.state === "available" ? { ...navigation, run: completionYamlString(navigation.run),
+                        run_instance_id: completionYamlString(navigation.run_instance_id), directory: completionYamlString(navigation.directory),
+                        files: navigation.files.map(file => ({ ...file, ...(typeof file.path === "string" ? { path: completionYamlString(file.path) } : {}) })) }
+                        : { ...navigation } };
+            }
         }
         const parts = [];
         const add = (part) => { if (parts.length)
@@ -1650,13 +1748,22 @@ function prepareCompletionYamlProjection(safe, candidates, references, ordered)
             if (piece.block) {
                 if (!piece.text.isWellFormed())
                     return { state: "unsupported" };
-                add(piece.block === "body" ? { body: piece.text } : { marker: piece.text });
+                if (rooted && piece.block === "marker" && !/^\[[0-9]+ characters omitted\]$/u.test(piece.text)) {
+                    metadata.text_warnings ??= [];
+                    metadata.text_warnings.push(piece.text);
+                }
+                else
+                    add(piece.block === "body" ? { body: piece.text } : { marker: piece.text });
             }
-        if (safe.file_navigation !== undefined && !references.has(index))
-            add({ marker: "Run-file reference omitted (packet byte limit)." });
+        if (safe.file_navigation !== undefined && !references.has(index)) {
+            if (rooted)
+                metadata.run_files_omission = { reason: "packet_byte_limit", shown: 0, omitted: 1, total: 1 };
+            else
+                add({ marker: "Run-file reference omitted (packet byte limit)." });
+        }
         packet.records.push({ metadata, parts });
     }
-    const service = {};
+    const service = rooted ? { header_layout: "rooted_files_v1" } : {};
     const omitted = safe.members.length - candidates.length;
     if (omitted) {
         service.omitted_results = omitted;
@@ -1676,8 +1783,11 @@ function prepareCompletionYamlProjection(safe, candidates, references, ordered)
         if (safe.numbering.kind === "unavailable")
             service.numbering_unavailable = safe.numbering.reason;
     }
-    if (safe.inventory_source)
-        service.result_inventory = { ...safe.inventory_source, path: completionYamlString(safe.inventory_source.path) };
+    if (safe.inventory_source) {
+        const path = rooted ? rootedCompletionPath(safe.inventory_source.path) : undefined;
+        service.result_inventory = { ...safe.inventory_source,
+            ...(path ? { root: path.root, path: path.path } : { path: completionYamlString(safe.inventory_source.path) }) };
+    }
     if (Object.keys(service).length)
         packet.service = service;
     const chunks = [];
@@ -1737,7 +1847,7 @@ export function projectRunCompletionYamlPrototype(batch) {
         throw error;
     }
 }
-function projectCompletionRecords(safe, assembler = safe.result_layout === "completion_yaml_core_v1" ? "yaml" : "legacy") {
+function projectCompletionRecords(safe, assembler = isYamlCompletionLayout(safe.result_layout) ? "yaml" : "legacy") {
     const frontmatter = isFrontmatterCompletionLayout(safe.result_layout) || assembler === "yaml";
     const shared = isSharedCompletionLayout(safe.result_layout);
     const maxBytes = shared ? Limits.RUN_COMPLETION_MODEL_MAX_BYTES : Limits.RUN_DELIVERY_MODEL_MAX_BYTES;
@@ -2024,7 +2134,7 @@ export function projectRunCompletionBatchPresentation(batch) {
     if (safe.presentation_format !== "ax_records" && safe.presentation_format !== "ax_records_v3")
         return { content: projectCompletionBatchMessage(safe).message };
     const result = safe.result_layout !== undefined ? projectCompletionRecords(safe) : projectRetainedRecordCompletionBatch(safe);
-    if (safe.result_layout === "completion_yaml_core_v1")
+    if (isYamlCompletionLayout(safe.result_layout))
         return { content: result.message, presentation: Object.freeze({
                 format: "completion_yaml_core_v1", content_sha256: createHash("sha256").update(result.message).digest("hex"),
             }) };
@@ -2192,10 +2302,14 @@ export function readRunCompletionPresentation(content, value) {
             hint.content_sha256 !== createHash("sha256").update(content).digest("hex"))
             return full;
         const segments = [];
+        const rooted = core.packet.service?.header_layout === "rooted_files_v1";
+        const facts = Object.fromEntries(Object.entries(core.packet.service ?? {}).filter(([key]) => key !== "header_layout"));
         for (const [index, record] of core.packet.records.entries()) {
             if (index)
                 segments.push({ kind: "separator", text: "\n" });
-            const metadata = Object.fromEntries(Object.entries(record.metadata).filter(([key]) => key !== "references" && key !== "run_files"));
+            const metadata = Object.fromEntries(Object.entries(record.metadata).filter(([key]) => rooted || (key !== "references" && key !== "run_files")));
+            if (rooted && index === 0 && Object.keys(facts).length)
+                metadata.delivery = facts;
             const header = renderYamlMetadata(metadata, completionYamlMaxBytes);
             if (header.state !== "available")
                 return full;
@@ -2203,13 +2317,13 @@ export function readRunCompletionPresentation(content, value) {
             for (const part of record.parts)
                 segments.push("body" in part ? { kind: "body", text: part.body } : { kind: "marker", text: part.marker });
         }
-        if (core.packet.service) {
-            const service = renderYamlMetadata(core.packet.service, completionYamlMaxBytes);
+        if (core.packet.service && (!rooted || !core.packet.records.length)) {
+            const service = renderYamlMetadata(rooted ? facts : core.packet.service, completionYamlMaxBytes);
             if (service.state !== "available")
                 return full;
             if (segments.length)
                 segments.push({ kind: "separator", text: "\n" });
-            segments.push({ kind: "service", text: service.text.replace(/\n$/u, "") });
+            segments.push({ kind: rooted ? "header" : "service", text: service.text.replace(/\n$/u, "") });
         }
         return { text: segments.map(segment => segment.text).join("\n"), compact: true, records: true, yaml: true,
             segments: Object.freeze(segments.map(segment => Object.freeze(segment))) };

package/dist/lib/run-ui-runtime.js

@@ -12,26 +12,21 @@ import * as Pi from "./pi.js";
 import * as RunDelivery from "./run-delivery.js";
 import * as RunDeliveryLineage from "./run-delivery-lineage.js";
 import * as RunIndex from "./runs-index.js";
-import { formatLiteralBlock, formatMarkdownField } from "./tools-response.js";
+import { formatYamlNotice } from "./tools-response.js";
 function formatSteerDiagnosticMessage(eventId, stage, message) {
-    const fields = [formatMarkdownField("event", eventId), formatMarkdownField("attention", "steer"),
-        formatMarkdownField("stage", stage), formatMarkdownField("result", stage === "admission" ? "remains retryable" : "request failed")];
-    if (stage === "delivery")
-        fields.push(formatMarkdownField("delivery", "unconfirmed"), formatMarkdownField("presentation", "unconfirmed"));
     let end = Math.min(message.length, 240);
     const last = message.charCodeAt(end - 1), next = message.charCodeAt(end);
     if (last >= 0xd800 && last <= 0xdbff && next >= 0xdc00 && next <= 0xdfff)
         end -= 1;
     const preview = message.slice(0, end), clipped = end < message.length;
-    if (Buffer.from(preview).toString("utf8") !== preview) {
-        fields.push(formatMarkdownField("diagnostic", "unavailable"), formatMarkdownField("diagnostic_reason", "malformed legacy preview"), formatMarkdownField("diagnostic_omission", "[omitted: unknown]"));
-    }
-    else {
-        fields.push(formatMarkdownField("diagnostic", preview + (clipped ? "…" : "")));
-        if (clipped)
-            fields.push(formatMarkdownField("diagnostic_omission", "[omitted: unknown]"));
-    }
-    return fields.join("\n");
+    // The 240-pair-aligned preview and its explicit unknown-loss marker are unchanged; only metadata is YAML.
+    const diagnostic = Buffer.from(preview).toString("utf8") !== preview
+        ? { diagnostic: "unavailable", diagnostic_reason: "malformed legacy preview", diagnostic_omission: "[omitted: unknown]" }
+        : { diagnostic: preview + (clipped ? "…" : ""), ...(clipped ? { diagnostic_omission: "[omitted: unknown]" } : {}) };
+    return formatYamlNotice({ event: eventId, attention: "steer", stage,
+        result: stage === "admission" ? "remains retryable" : "request failed",
+        ...(stage === "delivery" ? { delivery: "unconfirmed", presentation: "unconfirmed" } : {}),
+        ...diagnostic });
 }
 /** Transcript-only view of the exact delivered content; never re-read a Run or infer body labels. */
 export function registerRunCompletionRenderer(pi) {
@@ -162,8 +157,7 @@ export function createRunUiRuntime(deps) {
         }
         const message = error instanceof Error ? error.message : String(error);
         try {
-            expectedContext.ui.notify([formatMarkdownField("callback", label), formatMarkdownField("result", "failed"),
-                formatMarkdownField("diagnostic", message)].join("\n"), "error");
+            expectedContext.ui.notify(formatYamlNotice({ callback: label, result: "failed", diagnostic: message }), "error");
         }
         catch {
             /* stale context or unavailable UI */
@@ -327,9 +321,8 @@ export function createRunUiRuntime(deps) {
                 const key = `${batch.batch_id}:${evidence.status}:${evidence.reason ?? ""}`;
                 if (!completionDiagnostics.has(key)) {
                     completionDiagnostics.add(key);
-                    ctx.ui.notify("\n" + [formatMarkdownField("batch", batch.batch_id), formatMarkdownField("stage", "completion recovery"),
-                        formatMarkdownField("evidence", evidence.status), formatMarkdownField("phase", "pending"),
-                        formatMarkdownField("reason", evidence.reason ?? "conflicting session evidence")].join("\n"), "warning");
+                    ctx.ui.notify("\n" + formatYamlNotice({ batch: batch.batch_id, stage: "completion recovery",
+                        evidence: evidence.status, phase: "pending", reason: evidence.reason ?? "conflicting session evidence" }), "warning");
                 }
                 return true;
             }
@@ -413,9 +406,8 @@ export function createRunUiRuntime(deps) {
                     const key = `${steer.steer_id}:${evidence.status}:${evidence.reason ?? ""}`;
                     if (!steerDiagnostics.has(key)) {
                         steerDiagnostics.add(key);
-                        ctx.ui.notify([formatMarkdownField("event", steer.event_id), formatMarkdownField("attention", "steer"),
-                            formatMarkdownField("stage", "recovery"), formatMarkdownField("evidence", evidence.status),
-                            formatMarkdownField("phase", "queued"), formatMarkdownField("reason", evidence.reason ?? "conflicting session evidence")].join("\n"), "warning");
+                        ctx.ui.notify(formatYamlNotice({ event: steer.event_id, attention: "steer", stage: "recovery",
+                            evidence: evidence.status, phase: "queued", reason: evidence.reason ?? "conflicting session evidence" }), "warning");
                     }
                     continue;
                 }
@@ -681,11 +673,10 @@ export function createRunUiRuntime(deps) {
             if (teardown.failed === 0 || !ctx)
                 return;
             try {
-                ctx.ui.notify([formatMarkdownField("stage", "shutdown teardown"), formatMarkdownField("killed", String(teardown.killed)),
-                    formatMarkdownField("failed", String(teardown.failed)), formatMarkdownField("skipped", String(teardown.skipped)),
-                    formatMarkdownField("discovery_failed", String(teardown.discoveryFailed)),
-                    formatMarkdownField("summary", teardown.summaryPath == null ? "unavailable" : formatLiteralBlock(teardown.summaryPath)),
-                    formatMarkdownField("basis", "teardown report; not scope closure")].join("\n"), "warning");
+                ctx.ui.notify(formatYamlNotice({ stage: "shutdown teardown", killed: teardown.killed,
+                    failed: teardown.failed, skipped: teardown.skipped, discovery_failed: teardown.discoveryFailed,
+                    summary: teardown.summaryPath ?? "unavailable",
+                    basis: "teardown report; not scope closure" }), "warning");
             }
             catch {
                 /* stale shutdown context */

package/dist/lib/runs-process-windows-mi.d.ts

@@ -43,4 +43,75 @@ export declare function decodeProvenanceBinding(value: unknown): {
     readonly reason: 'invalid_binding';
 };
 export declare function decodeResponse(bytes: Uint8Array, profile: unknown, pids: unknown): DecodeOutcome;
+/**
+ * Complete-helper manifest claim. Bounded reading, exact-key schema and closed lexemes only; a valid
+ * manifest is integrity/provenance input, never executable authenticity, an approved asset or activation.
+ */
+type HelperManifest = {
+    readonly helper_version: string;
+    readonly architecture: 'windows-x64';
+    readonly protocol: 'native-mi-v1';
+    readonly profiles: readonly ['scalar', 'shared'];
+    readonly native_source_sha256: string;
+    readonly executable_bytes: number;
+    readonly executable_sha256: string;
+    readonly toolchain: {
+        readonly compiler: string;
+        readonly sdk: string;
+        readonly build_arguments: readonly string[];
+    };
+    readonly dependencies: readonly string[];
+    readonly originating_source_commit: string;
+    readonly originating_build_job: string;
+};
+type ManifestUnusable = {
+    readonly kind: 'unusable';
+    readonly reason: 'oversize_manifest' | 'invalid_manifest' | 'unsupported_manifest';
+};
+/** Bounded complete-manifest reader: one strict UTF-8 JSON document with an exact reviewed shape. */
+export declare function readHelperManifest(bytes: Uint8Array): {
+    readonly kind: 'manifest_unadmitted';
+    readonly manifest: HelperManifest;
+} | ManifestUnusable;
+type HelperAssetLocation = {
+    readonly kind: 'located';
+    readonly helper_version: string;
+    readonly manifest_url: URL;
+    readonly executable_url: URL;
+};
+/**
+ * Fixed versioned package-relative lookup. Never searches cwd, PATH or caller locations: the only base is
+ * the sibling `native/` directory of this module's own `lib/` (source) or `dist/lib/` (compiled) home.
+ */
+export declare function resolveHelperAsset(moduleUrl: unknown, runtime: unknown, helperVersion: unknown): HelperAssetLocation | {
+    readonly kind: 'unusable';
+    readonly reason: 'unsupported_location' | 'unsupported_target' | 'unsupported_version';
+};
+/** Injected bounded reader: exact bytes for one fixed URL or nothing. Never a path, cwd or PATH lookup. */
+export type HelperAssetReader = (url: URL, maximumBytes: number) => Uint8Array | undefined;
+type HelperAssetOutcome = {
+    readonly kind: 'asset_verified_unadmitted';
+    readonly manifest: HelperManifest;
+    readonly executable_sha256: string;
+    readonly executable_bytes: number;
+} | {
+    readonly kind: 'unusable';
+    readonly reason: 'missing_manifest' | 'oversize_manifest' | 'invalid_manifest' | 'unsupported_manifest' | 'version_mismatch' | 'missing_asset' | 'oversize_asset' | 'size_mismatch' | 'digest_mismatch';
+};
+/** Trusted exact-byte selection: bounded manifest read, exact declared size, then exact SHA-256 match. */
+export declare function loadHelperAsset(location: HelperAssetLocation, read: HelperAssetReader): HelperAssetOutcome;
+type HelperInvocation = {
+    readonly kind: 'invocation_unadmitted';
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly options: {
+        readonly shell: false;
+        readonly windowsHide: true;
+    };
+} | {
+    readonly kind: 'unusable';
+    readonly reason: 'unsupported_executable' | 'invalid_query';
+};
+/** Shell-free invocation spec only: no spawn, retry, fallback or execution-policy bypass. */
+export declare function helperInvocation(executablePath: unknown, profile: unknown, pids: unknown): HelperInvocation;
 export {};

package/dist/lib/runs-process-windows-mi.js

@@ -1,6 +1,13 @@
-// Owns: Bounded raw MI wire decoding, query inputs and unadmitted provenance fragments, subordinate to process acquisition.
-// Excludes: Identity construction/digest/comparison, status/liveness/lifecycle/publication/admission,
-// fallback, native invocation and asset loading. Decoded data never admits a representation profile.
+// Owns: Bounded raw MI wire decoding, query inputs, unadmitted provenance fragments, and unrouted
+// helper manifest/asset verification plus a shell-free invocation spec, subordinate to process acquisition.
+// Excludes: Identity construction/digest/comparison, status/liveness/lifecycle/publication/admission, fallback,
+// process spawning and package inventory. No production reader imports this owner; decoded data, verified
+// asset bytes and the invocation spec never admit a representation profile, architecture or activation.
+import { createHash } from 'node:crypto';
+const MANIFEST_MAX_BYTES = 32 * 1024;
+const EXECUTABLE_MAX_BYTES = 8 * 1024 * 1024;
+const HELPER_VERSION = /^(?:0|[1-9][0-9]{0,5})\.(?:0|[1-9][0-9]{0,5})\.(?:0|[1-9][0-9]{0,5})$/u;
+const MODULE_FILE = /\/lib\/runs-process-windows-mi\.(?:ts|js)$/u;
 export function queryArguments(profile, pids) {
     if ((profile !== 'scalar' && profile !== 'shared') || !Array.isArray(pids) ||
         pids.length < 1 || pids.length > 64 || (profile === 'scalar' && pids.length !== 1))
@@ -112,3 +119,139 @@ export function decodeResponse(bytes, profile, pids) {
         return { kind: 'unusable', reason: 'unsupported_optional_fields' };
     return { kind: 'decoded_unadmitted', rows };
 }
+function boundedText(bytes, maximumBytes) {
+    if (!(bytes instanceof Uint8Array) || bytes.byteLength > maximumBytes)
+        return undefined;
+    if (bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf)
+        return undefined;
+    try {
+        return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    }
+    catch {
+        return undefined;
+    }
+}
+function boundedLexemes(value, maximum) {
+    if (!Array.isArray(value) || value.length > maximum)
+        return undefined;
+    const selected = [];
+    for (const item of value) {
+        if (typeof item !== 'string' || item.length === 0 || item.length > 128 || !/^[\x20-\x7e]+$/.test(item) || selected.includes(item))
+            return undefined;
+        selected.push(item);
+    }
+    return selected;
+}
+/** Bounded complete-manifest reader: one strict UTF-8 JSON document with an exact reviewed shape. */
+export function readHelperManifest(bytes) {
+    const invalid = { kind: 'unusable', reason: 'invalid_manifest' };
+    if (!(bytes instanceof Uint8Array) || bytes.byteLength > MANIFEST_MAX_BYTES)
+        return { kind: 'unusable', reason: 'oversize_manifest' };
+    const text = boundedText(bytes, MANIFEST_MAX_BYTES);
+    if (text === undefined)
+        return invalid;
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        return invalid;
+    }
+    if (!exactKeys(value, ['helper_version', 'architecture', 'protocol', 'profiles', 'native_source_sha256',
+        'executable_bytes', 'executable_sha256', 'toolchain', 'dependencies', 'originating_source_commit', 'originating_build_job']))
+        return invalid;
+    const { helper_version, architecture, protocol, profiles, native_source_sha256, executable_bytes, executable_sha256, toolchain, dependencies, originating_source_commit, originating_build_job } = value;
+    if (typeof helper_version !== 'string' || !HELPER_VERSION.test(helper_version) ||
+        architecture !== 'windows-x64' || protocol !== 'native-mi-v1' ||
+        !Array.isArray(profiles) || profiles.length !== 2 || profiles[0] !== 'scalar' || profiles[1] !== 'shared')
+        return { kind: 'unusable', reason: 'unsupported_manifest' };
+    if (typeof native_source_sha256 !== 'string' || !/^[0-9a-f]{64}$/.test(native_source_sha256) ||
+        typeof executable_sha256 !== 'string' || !/^[0-9a-f]{64}$/.test(executable_sha256) ||
+        typeof originating_source_commit !== 'string' || !/^[0-9a-f]{40}$/.test(originating_source_commit) ||
+        typeof originating_build_job !== 'string' || !/^[1-9][0-9]*$/.test(originating_build_job) ||
+        typeof executable_bytes !== 'number' || !Number.isSafeInteger(executable_bytes) || executable_bytes <= 0)
+        return invalid;
+    if (executable_bytes > EXECUTABLE_MAX_BYTES)
+        return { kind: 'unusable', reason: 'unsupported_manifest' };
+    if (!exactKeys(toolchain, ['compiler', 'sdk', 'build_arguments']))
+        return invalid;
+    const compiler = boundedLexemes([toolchain.compiler], 1)?.[0];
+    const sdk = boundedLexemes([toolchain.sdk], 1)?.[0];
+    const buildArguments = boundedLexemes(toolchain.build_arguments, 32);
+    const dependencyNames = boundedLexemes(dependencies, 32);
+    if (compiler === undefined || sdk === undefined || buildArguments === undefined || dependencyNames === undefined)
+        return invalid;
+    // Fresh primitive claims only; the caller still owns target/version/source-digest policy.
+    return {
+        kind: 'manifest_unadmitted',
+        manifest: {
+            helper_version, architecture: 'windows-x64', protocol: 'native-mi-v1', profiles: ['scalar', 'shared'],
+            native_source_sha256, executable_bytes, executable_sha256,
+            toolchain: { compiler, sdk, build_arguments: buildArguments }, dependencies: dependencyNames,
+            originating_source_commit, originating_build_job,
+        },
+    };
+}
+/**
+ * Fixed versioned package-relative lookup. Never searches cwd, PATH or caller locations: the only base is
+ * the sibling `native/` directory of this module's own `lib/` (source) or `dist/lib/` (compiled) home.
+ */
+export function resolveHelperAsset(moduleUrl, runtime, helperVersion) {
+    let url;
+    try {
+        url = new URL(String(moduleUrl));
+    }
+    catch {
+        return { kind: 'unusable', reason: 'unsupported_location' };
+    }
+    if (url.protocol !== 'file:' || !MODULE_FILE.test(url.pathname))
+        return { kind: 'unusable', reason: 'unsupported_location' };
+    const target = runtime;
+    if (target?.platform !== 'win32' || target?.arch !== 'x64')
+        return { kind: 'unusable', reason: 'unsupported_target' };
+    if (typeof helperVersion !== 'string' || !HELPER_VERSION.test(helperVersion))
+        return { kind: 'unusable', reason: 'unsupported_version' };
+    const directory = `../native/windows-mi/win32-x64/${helperVersion}/`;
+    return {
+        kind: 'located', helper_version: helperVersion,
+        manifest_url: new URL(`${directory}manifest.json`, url),
+        executable_url: new URL(`${directory}helper.exe`, url),
+    };
+}
+/** Trusted exact-byte selection: bounded manifest read, exact declared size, then exact SHA-256 match. */
+export function loadHelperAsset(location, read) {
+    const manifestBytes = read(location.manifest_url, MANIFEST_MAX_BYTES + 1);
+    if (manifestBytes === undefined)
+        return { kind: 'unusable', reason: 'missing_manifest' };
+    if (manifestBytes.byteLength > MANIFEST_MAX_BYTES)
+        return { kind: 'unusable', reason: 'oversize_manifest' };
+    const reading = readHelperManifest(manifestBytes);
+    if (reading.kind === 'unusable')
+        return { kind: 'unusable', reason: reading.reason };
+    const { manifest } = reading;
+    if (manifest.helper_version !== location.helper_version)
+        return { kind: 'unusable', reason: 'version_mismatch' };
+    // One extra byte detects growth; a shorter read can never satisfy the declared size.
+    const executableBytes = read(location.executable_url, manifest.executable_bytes + 1);
+    if (executableBytes === undefined)
+        return { kind: 'unusable', reason: 'missing_asset' };
+    if (executableBytes.byteLength > manifest.executable_bytes)
+        return { kind: 'unusable', reason: 'oversize_asset' };
+    if (executableBytes.byteLength !== manifest.executable_bytes)
+        return { kind: 'unusable', reason: 'size_mismatch' };
+    const digest = createHash('sha256').update(executableBytes).digest('hex');
+    if (digest !== manifest.executable_sha256)
+        return { kind: 'unusable', reason: 'digest_mismatch' };
+    return { kind: 'asset_verified_unadmitted', manifest, executable_sha256: digest, executable_bytes: executableBytes.byteLength };
+}
+/** Shell-free invocation spec only: no spawn, retry, fallback or execution-policy bypass. */
+export function helperInvocation(executablePath, profile, pids) {
+    if (typeof executablePath !== 'string' || executablePath.length === 0 || executablePath.length > 4096 ||
+        !/^[A-Za-z]:[\\/][^\x00\r\n"]*\.exe$/.test(executablePath))
+        return { kind: 'unusable', reason: 'unsupported_executable' };
+    const query = queryArguments(profile, pids);
+    if (!query)
+        return { kind: 'unusable', reason: 'invalid_query' };
+    return { kind: 'invocation_unadmitted', command: executablePath, args: query,
+        options: { shell: false, windowsHide: true } };
+}