@lapxo/bound 0.1.7 → 0.1.9

package/dist/host/native/native-program.js

@@ -0,0 +1,72 @@
+import { retainedProjection } from "./reading.js";
+import { fieldNames } from "./reading.js";
+import { sha256 as sha } from "../hash.js";
+/** A program alias is a Root selection, never PATH.
+ * This verifies a finite implementation before entry; it executes nothing.
+ * The runtime hook must still verify each reached member before loading it. */
+import { isAbsolute, resolve, relative } from 'node:path';
+import { realpathSync } from 'node:fs';
+import { authenticateSignedPort, nativeParentInputBytes, canonicalJson } from "./reading.js";
+import { readBounded } from "./generated.js";
+const fail = (why) => { throw Error('REFUSE·native program ' + why); };
+const keys = fieldNames;
+const verified = new WeakMap();
+export function verifyNativeProgram(root, coordinate, parent, runtimeBinding) {
+    const authenticated = authenticateSignedPort(root, coordinate), p = authenticated.profile;
+    if (!p || keys(p) !== 'alias,condition,coordinate,entry,interpreter,limits,members,profile,root,selector' || p.profile !== 'host-native-program@1' || p.coordinate !== coordinate || typeof p.alias !== 'string' || !p.alias.length || p.alias.includes('\0') || typeof p.condition !== 'string' || !p.condition.length)
+        fail('selection absent/unknown');
+    if (keys(p.selector ?? {}) !== 'binding,implementation,port' || canonicalJson(p.selector) !== canonicalJson({ port: parent.port, binding: parent.binding, implementation: parent.implementation }))
+        fail('selection differs from parent');
+    if (keys(p.limits ?? {}) !== 'bytes,members' || !Number.isSafeInteger(p.limits.members) || p.limits.members < 1 || !Number.isSafeInteger(p.limits.bytes) || p.limits.bytes < 1 || p.limits.bytes > nativeParentInputBytes(root, parent))
+        fail('implementation resource absent/exceeds Root');
+    if ([parent.identity, parent.instrument, parent.policy, parent.authority, parent.implementation].some(d => typeof d !== 'string' || !/^sha256:[0-9a-f]{64}$/.test(d)))
+        fail('parent identity absent');
+    if (!Array.isArray(p.members) || p.members.length > p.limits.members || typeof p.root !== 'string' || isAbsolute(p.root) || p.root.split('/').some(s => !s || s === '.' || s === '..') || !p.interpreter || typeof p.interpreter.path !== 'string' || isAbsolute(p.interpreter.path) || p.interpreter.path !== runtimeBinding.coordinate || keys(p.interpreter) !== 'bytes,digest,path' || !Number.isSafeInteger(p.interpreter.bytes) || p.interpreter.bytes < 1)
+        fail('interpreter/implementation context absent');
+    // This binding comes from the private prepared host image, not the program's
+    // declaration. Matching a path alone cannot identify an implementation.
+    if (!runtimeBinding || runtimeBinding.path !== parent.runtime || runtimeBinding.digest !== p.interpreter.digest || !parent.inputs.some(p => p[1] === runtimeBinding.digest))
+        fail('interpreter differs from parent image');
+    let bytes = p.interpreter.bytes;
+    if (bytes > p.limits.bytes)
+        fail('interpreter byte resource');
+    const coordinates = new Set();
+    for (const m of p.members) {
+        if (!m || keys(m) !== 'bytes,coordinate,digest' || typeof m.coordinate !== 'string' || !m.coordinate.length || isAbsolute(m.coordinate) || m.coordinate.includes('\\') || m.coordinate.split('/').some(x => !x || x === '.' || x === '..') || coordinates.has(m.coordinate) || !/^sha256:[0-9a-f]{64}$/.test(m.digest) || !Number.isSafeInteger(m.bytes) || m.bytes < 0)
+            fail('member identity ambiguous');
+        coordinates.add(m.coordinate);
+        bytes += m.bytes;
+        if (bytes > p.limits.bytes)
+            fail('implementation byte resource');
+    }
+    // All declarations and aggregate resources are checked before reading files.
+    if (!coordinates.has(p.entry) || !/^sha256:[0-9a-f]{64}$/.test(p.interpreter.digest))
+        fail('entry/interpreter digest absent');
+    const physical = (path) => { try {
+        return realpathSync(path);
+    }
+    catch {
+        return fail('selected member absent ' + path);
+    } };
+    const entryMount = runtimeBinding.members.find(m => m.coordinate === p.root + '/' + p.entry);
+    if (!entryMount)
+        return fail('entry mount absent from host image');
+    const levels = p.entry.split('/').length;
+    let physicalRoot = physical(entryMount.path);
+    for (let i = 0; i < levels; i++)
+        physicalRoot = resolve(physicalRoot, '..');
+    const interpreter = physical(runtimeBinding.path);
+    const interpreterBytes = readBounded(interpreter, p.interpreter.bytes);
+    if (interpreterBytes.length !== p.interpreter.bytes || sha(interpreterBytes) !== p.interpreter.digest)
+        fail('interpreter bytes differ');
+    const members = p.members.map(m => { const mounted = runtimeBinding.members.find(one => one.coordinate === p.root + '/' + m.coordinate); if (!mounted)
+        return fail('member absent from actual host image ' + m.coordinate); const path = physical(mounted.path), r = relative(physicalRoot, path); if (r === '..' || r.startsWith('../') || isAbsolute(r))
+        fail('member outside selected implementation'); const b = readBounded(path, m.bytes); if (b.length !== m.bytes || sha(b) !== m.digest)
+        fail('member bytes differ ' + m.coordinate); return { path, digest: m.digest }; });
+    const handle = Object.freeze({ identity: sha(canonicalJson([authenticated.line, parent.identity])) });
+    verified.set(handle, { alias: p.alias, interpreter, interpreterDigest: p.interpreter.digest, entry: physical(resolve(physicalRoot, p.entry)), root: physicalRoot, members, condition: p.condition });
+    return handle;
+}
+/** Only the guarded instrument can obtain this from a verified opaque handle.
+ * Put it in the signed native image; never accept it from a world proposal. */
+export const nativeProgramProjection = retainedProjection(verified, fail);

package/dist/host/native/node-jobs.d.ts

@@ -0,0 +1,84 @@
+import type { CommandPort } from '@lapxo/topos/contract';
+import type { Declaration } from './loader.ts';
+import { type Handoff } from './jobs.ts';
+export interface Location {
+    member: string;
+    path: string;
+    kind: 'binary' | 'module' | 'data';
+}
+export interface NodeImage {
+    cwd: string;
+    condition: string;
+    runtime: string;
+    preload?: string;
+    nativePreloadMembers: readonly string[];
+    commandPort?: CommandPort;
+    hostLoader?: {
+        declaration: Declaration;
+        entries: readonly string[];
+        preload: string;
+    };
+    locations: readonly Location[];
+}
+/** Observation of a completed inner command. A nonzero exit is data, never
+ * silently converted into effect success; its meaning belongs to the reader. */
+export interface CapturedCommand {
+    exitStatus: number;
+    stdout: string;
+    stderr: string;
+}
+export interface PreparedNodeImage {
+    readonly identity: string;
+}
+/** Image/runtime condition and locations are instrument-admitted inputs, selected
+ * before requests. Condition includes trusted Node builtins/platform libraries;
+ * a binary's file digest alone does not seal every dynamic platform library. */
+export declare function prepareNodeImage(input: Handoff, inputImage: NodeImage): PreparedNodeImage;
+/** Exact expectations from the same opaque host image used by execution. */
+export declare function plannedJobs(handle: PreparedNodeImage, request: Uint8Array): readonly {
+    id: string;
+    identity: string;
+}[];
+/** Instrument-only producer lineage from the SAME private planned job used by
+ * executeJobs. No fixture may invent an identity or reset shared custody. */
+export interface ParentExecution {
+    identity: string;
+    port: string;
+    binding: string;
+    implementation: string;
+    instrument: string;
+    policy: string;
+    authority: string;
+    inputs: readonly (readonly [string, string])[];
+    environment: readonly (readonly [string, string])[];
+    argv: readonly string[];
+    cwd: string;
+    runtime: string;
+    timeoutMs: number;
+    responseBytes: number;
+}
+export declare function plannedParentExecutions(handle: PreparedNodeImage, request: Uint8Array): readonly ParentExecution[];
+/** Root-owned execution resource, constructed from authenticated producer selection
+ * under the authority guard. This is not a packet verifier or world callback. */
+export interface RootJobCustody {
+    open(parent: ParentExecution): Promise<{
+        assertClosed(): void;
+        close(): Promise<void>;
+        descendant?: unknown;
+    }>;
+}
+/** No partial member escapes a failed batch. Uses the existing bounded async
+ * child-group executor; worker launcher is itself an exact selected module. */
+export declare function executeJobs(handle: PreparedNodeImage, request: Uint8Array, options: {
+    phase: 'act' | 'selection' | 'help' | 'check' | 'preview' | 'sign';
+    signal?: AbortSignal;
+    trace?: (event: {
+        id: string;
+        phase: 'start' | 'end';
+    }) => void;
+    custody?: RootJobCustody;
+}): Promise<readonly {
+    id: string;
+    identity: string;
+    responses: readonly CapturedCommand[];
+}[]>;

package/dist/host/native/node-jobs.js

@@ -0,0 +1,187 @@
+import { sha256 as digest } from "../hash.js";
+/** Host-only controlled Node adapter; pure planning remains in planner.ts. */
+import { realpathSync } from 'node:fs';
+import { isAbsolute } from 'node:path';
+import { readBoundedFile } from "./bounded-file.js";
+import { executeLot } from "./command.js";
+import { moduleClosure } from "./module-closure.js";
+import { planJobs } from "./jobs.js";
+const refuse = (why) => { throw Error('REFUSE·job adapter ' + why); };
+const fileDigest = (path, limit) => { try {
+    return digest(readBoundedFile(path, limit, path));
+}
+catch {
+    return refuse('image member absent ' + path);
+} };
+const capturedCommand = (value) => { if (!value || typeof value !== 'object' || Array.isArray(value))
+    return false; const v = value; return Object.keys(v).sort().join(',') === 'exitStatus,stderr,stdout' && Number.isSafeInteger(v.exitStatus) && v.exitStatus >= 0 && typeof v.stdout === 'string' && typeof v.stderr === 'string'; };
+const admittedImages = new WeakMap();
+/** Image/runtime condition and locations are instrument-admitted inputs, selected
+ * before requests. Condition includes trusted Node builtins/platform libraries;
+ * a binary's file digest alone does not seal every dynamic platform library. */
+export function prepareNodeImage(input, inputImage) {
+    if (!inputImage?.commandPort)
+        refuse('missing admitted command port');
+    if (!inputImage || !isAbsolute(inputImage.cwd) || !inputImage.condition)
+        refuse('missing admitted Node image condition');
+    const host = { ...input, budget: { ...input.budget }, members: input.members.map(m => ({ ...m, bytes: new Uint8Array(m.bytes) })), loads: input.loads.map(e => ({ ...e, target: typeof e.target === 'string' ? e.target : { ...e.target } })), bindings: input.bindings.map(b => ({ ...b, places: [...b.places], args: [...b.args], inputs: [...b.inputs], environment: b.environment.map(p => [...p]), limits: { ...b.limits } })) };
+    // Validate all declarations and member bytes without any world proposal/launch.
+    planJobs(host, new TextEncoder().encode('[]'), digest);
+    const members = new Map(host.members.map(m => [m.coordinate, m])), locations = new Map();
+    let actualBytes = 0;
+    for (const member of host.members) {
+        actualBytes += member.bytes.length;
+        if (actualBytes > host.budget.bytes)
+            refuse('image byte resources');
+    }
+    const runtimeLocation = inputImage.locations.find(l => l.member === inputImage.runtime);
+    if (!runtimeLocation || realpathSync(runtimeLocation.path) !== realpathSync(process.execPath))
+        refuse('runtime differs from executing interpreter');
+    for (const location of inputImage.locations) {
+        if (locations.has(location.member) || !members.has(location.member) || !isAbsolute(location.path) || !['binary', 'module', 'data'].includes(location.kind))
+            refuse('unknown/duplicate image location ' + location.member);
+        if (fileDigest(location.path, host.budget.bytes) !== members.get(location.member).digest)
+            refuse('image bytes differ ' + location.member);
+        locations.set(location.member, { ...location });
+    }
+    if (locations.size !== members.size)
+        refuse('image omitted handed member');
+    const texts = new Map([...members].filter(([c]) => locations.get(c).kind === 'module' || c.endsWith('.json')).map(([c, m]) => { let source; try {
+        source = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(m.bytes);
+    }
+    catch {
+        return refuse('invalid text member ' + c);
+    } return [c, { source, digest: m.digest }]; }));
+    const snapshot = { identity: digest(new TextEncoder().encode(JSON.stringify([...members].map(([c, m]) => [c, m.digest]).sort()) + '\n')), entry: '', members: texts };
+    if (!inputImage.runtime || locations.get(inputImage.runtime)?.kind !== 'binary')
+        refuse('selected Node runtime absent');
+    if (inputImage.preload !== undefined && locations.get(inputImage.preload)?.kind !== 'module')
+        refuse('selected Node preloader absent');
+    if (!Array.isArray(inputImage.nativePreloadMembers) || (inputImage.preload !== undefined && !inputImage.nativePreloadMembers.includes(inputImage.preload)) || new Set(inputImage.nativePreloadMembers).size !== inputImage.nativePreloadMembers.length || inputImage.nativePreloadMembers.some(c => !members.has(c)))
+        refuse('native preloader members not handed');
+    const nativePreloadMembers = [...inputImage.nativePreloadMembers];
+    const proofs = new Map();
+    for (const binding of host.bindings) {
+        if (locations.get(binding.program)?.kind !== 'module' || binding.interpreter !== inputImage.runtime)
+            refuse('unsupported raw binary profile ' + binding.id);
+        if (binding.kind === 'process' && binding.entry !== undefined)
+            refuse('process entry unsupported ' + binding.id);
+        const roots = [binding.program, ...(binding.entry ? [binding.entry] : [])].filter(c => locations.get(c).kind === 'module');
+        if (!roots.length && locations.get(binding.program).kind !== 'binary')
+            refuse('unsupported program member ' + binding.program);
+        if (binding.interpreter && locations.get(binding.interpreter).kind !== 'binary')
+            refuse('interpreter is not a selected binary');
+        if (binding.kind === 'worker' && (!binding.entry || locations.get(binding.entry).kind !== 'module'))
+            refuse('worker entry is not a selected module');
+        const reached = roots.flatMap(entry => moduleClosure({ ...snapshot, entry }, () => undefined));
+        const declaredTargets = new Set([inputImage.preload, binding.program, binding.interpreter, binding.entry, ...binding.inputs, ...host.loads.map(e => typeof e.target === 'string' ? e.target : '')].filter(Boolean));
+        for (const reading of reached)
+            if (!declaredTargets.has(reading.coordinate))
+                refuse('literal module dependency not declared ' + reading.coordinate);
+        proofs.set(binding.id, JSON.stringify(reached));
+    }
+    host.policy = digest(new TextEncoder().encode(JSON.stringify([host.policy, 'captured-command/1', inputImage.condition, inputImage.runtime, inputImage.preload, nativePreloadMembers.map(c => [c, members.get(c).digest]), snapshot.identity, inputImage.commandPort ?? null, [...proofs]]) + '\n'));
+    const handle = Object.freeze({ identity: digest(new TextEncoder().encode(JSON.stringify([host.place, host.policy, snapshot.identity]))) });
+    admittedImages.set(handle, { handoff: host, image: { cwd: inputImage.cwd, condition: inputImage.condition, runtime: inputImage.runtime, preload: inputImage.preload, nativePreloadMembers, ...(inputImage.hostLoader ? { hostLoader: inputImage.hostLoader } : {}), ...(inputImage.commandPort ? { commandPort: { ...inputImage.commandPort, closure: [...inputImage.commandPort.closure], environment: [...inputImage.commandPort.environment] } } : {}), locations: [...locations.values()] }, locations, proofs, snapshot });
+    return handle;
+}
+/** Exact expectations from the same opaque host image used by execution. */
+export function plannedJobs(handle, request) { const ready = admittedImages.get(handle); if (!ready)
+    return refuse('unknown prepared host image'); return planJobs(ready.handoff, request, digest).map(({ id, identity }) => ({ id, identity })); }
+function parentExecution(ready, job) { const port = ready.image.commandPort; if (!port)
+    return refuse('producer requires declared parent port'); return { identity: job.identity, port: port.coordinate, binding: job.id, implementation: job.program[1], instrument: ready.handoff.instrument, policy: ready.handoff.policy, authority: ready.handoff.authoritySnapshot, inputs: job.edges.map(e => [e.target, e.digest]).filter((p, i, all) => all.findIndex(q => q[0] === p[0]) === i), environment: job.environment, argv: invocation(ready, job).args, cwd: ready.image.cwd, runtime: ready.locations.get(ready.image.runtime).path, timeoutMs: Math.min(port.timeoutMs, job.limits.timeMs), responseBytes: Math.min(port.responseBytes, job.limits.responseBytes) }; }
+export function plannedParentExecutions(handle, request) { const ready = admittedImages.get(handle); if (!ready)
+    return refuse('unknown prepared host image'); return planJobs(ready.handoff, request, digest).map(job => parentExecution(ready, job)); }
+const invocation = (ready, job) => {
+    const program = ready.locations.get(job.program[0]), interpreter = job.interpreter && ready.locations.get(job.interpreter[0]);
+    if (!interpreter)
+        return { command: program.path, args: [...job.args], cwd: ready.image.cwd };
+    const host = ready.image.hostLoader;
+    if (!host)
+        return refuse('fixed loader envelope absent');
+    const url = new URL(host.preload);
+    url.searchParams.set('bytes', String(ready.handoff.budget.bytes));
+    const envelope = Buffer.from(JSON.stringify({ format: 'native-image-envelope/1', entries: host.entries, declaration: host.declaration, execution: { runtime: ready.locations.get(ready.image.runtime).path, cwd: ready.image.cwd, mounts: ready.image.locations.map(location => ({ coordinate: location.member, path: location.path, kind: location.kind })) } }));
+    return { command: interpreter.path, args: ['--import', url.href, ...(ready.image.preload ? ['--import', ready.locations.get(ready.image.preload).path] : []), program.path, ...(job.kind === 'worker' ? [ready.locations.get(job.entry[0]).path] : []), ...job.args], cwd: ready.image.cwd, hostEnvelope: envelope, envelopeBytes: ready.handoff.budget.bytes };
+};
+/** No partial member escapes a failed batch. Uses the existing bounded async
+ * child-group executor; worker launcher is itself an exact selected module. */
+export async function executeJobs(handle, request, options) {
+    const ready = admittedImages.get(handle);
+    if (!ready)
+        return refuse('unknown prepared host image');
+    const { phase, signal, trace } = options;
+    if (phase !== 'act')
+        refuse('invocation forbidden during ' + phase);
+    if (signal?.aborted)
+        refuse('interrupted before batch');
+    const jobs = planJobs(ready.handoff, request, digest);
+    // Complete batch and all locations are verified before invoking any program.
+    for (const member of ready.handoff.members) {
+        const loc = ready.locations.get(member.coordinate);
+        if (fileDigest(loc.path, ready.handoff.budget.bytes) !== member.digest)
+            refuse('image bytes differ ' + member.coordinate);
+    }
+    if (!jobs.length)
+        return [];
+    const slots = Math.min(...jobs.map(j => j.limits.slots)), controller = new AbortController(), abort = controller.abort.bind(controller, undefined);
+    signal?.addEventListener('abort', abort, { once: true });
+    if (signal?.aborted)
+        abort();
+    const results = new Array(jobs.length);
+    let next = 0;
+    let primary;
+    const work = async () => {
+        while (!controller.signal.aborted) {
+            const index = next++;
+            if (index >= jobs.length)
+                return;
+            const job = jobs[index], fixed = invocation(ready, job), implementation = job.program[1], port = { ...ready.image.commandPort, timeoutMs: Math.min(ready.image.commandPort.timeoutMs, job.limits.timeMs), responseBytes: Math.min(ready.image.commandPort.responseBytes, job.limits.responseBytes) };
+            const proofFor = () => { for (const edge of job.edges) {
+                const loc = ready.locations.get(edge.target);
+                if (!loc || fileDigest(loc.path, ready.handoff.budget.bytes) !== edge.digest)
+                    return 'unmeasured';
+            } const roots = [job.program[0], ...(job.entry ? [job.entry[0]] : [])].filter(c => ready.locations.get(c).kind === 'module'); const actual = JSON.stringify(roots.flatMap(entry => moduleClosure({ ...ready.snapshot, entry }, () => undefined))); return actual === ready.proofs.get(job.id) ? 'verified' : 'unmeasured'; };
+            trace?.({ id: job.id, phase: 'start' });
+            let custody;
+            try {
+                if (options.custody)
+                    custody = await options.custody.open(parentExecution(ready, job));
+                if (!custody)
+                    return refuse('native descendant custody missing ' + job.id);
+                const envelope = JSON.parse(Buffer.from(fixed.hostEnvelope).toString('utf8'));
+                envelope.descendant = custody.descendant;
+                if (!envelope.descendant)
+                    return refuse('fixed descendant envelope absent ' + job.id);
+                const guarded = { ...fixed, hostEnvelope: Buffer.from(JSON.stringify(envelope)) };
+                const result = await executeLot({ port, lot: { identity: job.identity, requests: [new TextDecoder().decode(job.payload)] }, phase, signal: controller.signal, environment: Object.fromEntries(job.environment), host: { admitsDeclaration: p => JSON.stringify(p) === JSON.stringify(port), covers: c => c === port.coordinate && ready.handoff.bindings.find(b => b.id === job.id).places.includes(ready.handoff.place), verifies: d => ready.handoff.members.some(m => m.digest === d && fileDigest(ready.locations.get(m.coordinate).path, ready.handoff.budget.bytes) === d), resolve: () => guarded, loaderClosure: (_p, actual) => JSON.stringify(actual) === JSON.stringify(guarded) ? proofFor() : 'unmeasured' }, accepts: (response, index) => index === 0 && capturedCommand(response) });
+                custody?.assertClosed();
+                results[index] = { id: job.id, identity: job.identity, responses: result.members };
+            }
+            catch (error) {
+                if (primary === undefined)
+                    primary = error;
+                controller.abort();
+                throw error;
+            }
+            finally {
+                await custody?.close();
+                trace?.({ id: job.id, phase: 'end' });
+            }
+        }
+    };
+    try {
+        const settled = await Promise.allSettled(Array.from({ length: Math.min(slots, jobs.length) }, work));
+        if (primary !== undefined)
+            throw primary;
+        const failed = settled.find(x => x.status === 'rejected');
+        if (failed?.status === 'rejected')
+            throw failed.reason;
+        if (controller.signal.aborted || results.some(x => x === undefined) || results.filter(Boolean).length !== jobs.length)
+            refuse('interrupted/incomplete batch');
+        return results;
+    }
+    finally {
+        signal?.removeEventListener('abort', abort);
+    }
+}

package/dist/host/native/node-launch.d.ts

@@ -0,0 +1,72 @@
+/** Parse the actual Node launch without rewriting argv or evaluating text.
+ * Selection/authority and generated-member sealing belong to the Root host.
+ * This is a deliberately finite native profile, not a JS sandbox. */
+export type NodeLaunch = {
+    kind: 'eval';
+    mode: 'commonjs' | 'module';
+    text: string;
+    args: readonly string[];
+    imports: readonly string[];
+} | {
+    kind: 'file';
+    entry: string;
+    args: readonly string[];
+    imports: readonly string[];
+    test: boolean;
+};
+export declare function nodeLaunch(args: readonly string[]): NodeLaunch;
+import type { NativeProgramProjection } from './native-program.ts';
+export interface SelectedInterpreter {
+    readonly path: string;
+    readonly digest: string;
+}
+export interface NativeProgramLaunch {
+    readonly interpreter: string;
+    readonly interpreterDigest: string;
+    readonly entry: string;
+    readonly args: readonly string[];
+}
+/** Only an exact, unique declared alias selects a native program. No PATH,
+ * filename heuristics, option rewriting or consumer-specific names occur here. */
+export declare function projectNativeProgramLaunch(programs: readonly NativeProgramProjection[], program: string, args: readonly string[], runtime: SelectedInterpreter): NativeProgramLaunch;
+export interface NativeProgramParent {
+    readonly parent: string;
+    readonly root: string;
+    readonly members: readonly {
+        readonly path: string;
+        readonly digest: string;
+    }[];
+}
+/** Select a package-resolution context only for the exact reached parent member.
+ * Root must validate the supplied parent digest against actual bytes first.
+ * Node still performs actual resolution; Root checks the returned target digest
+ * before handing it back. Merely sharing a path prefix grants no membership. */
+export declare function selectNativeProgramParent(programs: readonly NativeProgramProjection[], parent: {
+    readonly path: string;
+    readonly digest: string;
+}): NativeProgramParent;
+/** The fixed host receives this record only from the actual Root custodian's
+ * retained before-fork evidence. This projection grants no new executable. */
+export interface NativeEvalActual {
+    readonly argv: readonly string[];
+    readonly rootPrefix: readonly string[];
+    readonly cwd: string;
+    readonly environment: readonly (readonly [string, string])[];
+    readonly runtime: string;
+}
+export interface NativeEvalParent {
+    readonly url: string;
+    readonly context: string;
+    readonly digest: string;
+    readonly mode: 'module' | 'commonjs';
+}
+import type { DerivedExecutable } from './generated.ts';
+export declare function retainedNativeEvalMatches(record: DerivedExecutable, actual: NativeEvalActual): boolean;
+/** Exact Node CLI eval origin, not a file-pattern exception. A different URL
+ * continues through ordinary physical-parent verification and refuses if absent.
+ * Node's module and CommonJS CLI forms have distinct observed synthetic names. */
+export declare function nativeEvalParent(record: DerivedExecutable, actual: NativeEvalActual): NativeEvalParent;
+/** Non-authoritative discovery from Node's actual runtime options only. A false
+ * result confers no permission: physical-parent/load checks remain unchanged.
+ * Before-fork argv validation and exact retained-record matching are separate. */
+export declare function actualNodeEvalOptions(execArgv: readonly string[]): boolean;

package/dist/host/native/node-launch.js

@@ -0,0 +1,159 @@
+const refuse = (why) => { throw Error('REFUSE·native descendant ' + why); };
+export function nodeLaunch(args) {
+    if (!Array.isArray(args) || args.some(s => typeof s !== 'string' || s.includes('\0')))
+        refuse('argv invalid');
+    let mode = 'commonjs', evalText, entry, test = false;
+    const imports = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--') {
+            entry = args[++i];
+            break;
+        }
+        if (arg === '--input-type=module') {
+            mode = 'module';
+            continue;
+        }
+        if (arg === '--input-type=commonjs') {
+            mode = 'commonjs';
+            continue;
+        }
+        if (arg === '--input-type') {
+            const value = args[++i];
+            if (value !== 'module' && value !== 'commonjs')
+                refuse('input type unsupported');
+            mode = value;
+            continue;
+        }
+        if (arg === '-e' || arg === '--eval') {
+            if (evalText !== undefined)
+                refuse('eval ambiguous');
+            evalText = args[++i];
+            if (evalText === undefined)
+                refuse('eval absent');
+            continue;
+        }
+        if (arg.startsWith('--eval=')) {
+            if (evalText !== undefined)
+                refuse('eval ambiguous');
+            evalText = arg.slice(7);
+            continue;
+        }
+        if (arg === '--import' || arg === '--require' || arg === '-r') {
+            const value = args[++i];
+            if (value === undefined)
+                refuse('preload absent');
+            imports.push(value);
+            continue;
+        }
+        if (arg.startsWith('--import=') || arg.startsWith('--require=')) {
+            imports.push(arg.slice(arg.indexOf('=') + 1));
+            continue;
+        }
+        if (arg === '--test') {
+            test = true;
+            continue;
+        }
+        if (arg.startsWith('--test-') || arg === '--experimental-strip-types' || arg === '--experimental-transform-types')
+            continue;
+        if (arg.startsWith('-'))
+            refuse('option unsupported ' + arg);
+        if (evalText !== undefined)
+            break;
+        entry = arg;
+        break;
+    }
+    if (evalText !== undefined) {
+        if (entry !== undefined)
+            refuse('eval plus executable file');
+        return { kind: 'eval', mode, text: evalText, args: [...args], imports };
+    }
+    if (!entry)
+        refuse(test ? 'implicit test discovery unsupported' : 'executable target absent');
+    return { kind: 'file', entry, args: [...args], imports, test };
+}
+/** Pure host glue. Inputs are projections obtained from verified opaque native
+ * program handles under Root's guard, never accepted from a world proposal.
+ * Selection names preserve argv; they confer no independent authority. */
+import { isAbsolute, resolve } from 'node:path';
+import { isSha256 } from "../hash.js";
+const programFail = (why) => { throw Error('REFUSE·native launch ' + why); };
+const digest = isSha256;
+const exactPath = (value) => typeof value === 'string' && isAbsolute(value) && resolve(value) === value;
+function graph(program) {
+    if (!program || typeof program.alias !== 'string' || !program.alias.length || !exactPath(program.interpreter) || !digest(program.interpreterDigest) || !exactPath(program.entry) || !exactPath(program.root) || !Array.isArray(program.members))
+        programFail('verified program projection absent');
+    const paths = new Set();
+    for (const member of program.members) {
+        if (!member || !exactPath(member.path) || !digest(member.digest) || paths.has(member.path))
+            programFail('program graph member ambiguous');
+        paths.add(member.path);
+    }
+    if (!paths.has(program.entry))
+        programFail('program entry not in selected graph');
+}
+/** Only an exact, unique declared alias selects a native program. No PATH,
+ * filename heuristics, option rewriting or consumer-specific names occur here. */
+export function projectNativeProgramLaunch(programs, program, args, runtime) {
+    if (!Array.isArray(programs) || typeof program !== 'string' || !program.length || !Array.isArray(args) || args.some(arg => typeof arg !== 'string' || arg.includes('\0')) || !runtime || !exactPath(runtime.path) || !digest(runtime.digest))
+        programFail('invocation context absent');
+    const matches = programs.filter(p => p?.alias === program);
+    if (matches.length !== 1)
+        programFail(matches.length ? 'program alias ambiguous ' + program : 'program alias undeclared ' + program);
+    const selected = matches[0];
+    graph(selected);
+    if (selected.interpreter !== runtime.path || selected.interpreterDigest !== runtime.digest)
+        programFail('selected interpreter differs');
+    return Object.freeze({ interpreter: selected.interpreter, interpreterDigest: selected.interpreterDigest, entry: selected.entry, args: Object.freeze([...args]) });
+}
+/** Select a package-resolution context only for the exact reached parent member.
+ * Root must validate the supplied parent digest against actual bytes first.
+ * Node still performs actual resolution; Root checks the returned target digest
+ * before handing it back. Merely sharing a path prefix grants no membership. */
+export function selectNativeProgramParent(programs, parent) {
+    if (!Array.isArray(programs) || !parent || !exactPath(parent.path) || !digest(parent.digest))
+        programFail('parent content context absent');
+    const matches = programs.filter(p => Array.isArray(p?.members) && p.members.some((m) => m?.path === parent.path && m.digest === parent.digest));
+    if (matches.length !== 1)
+        programFail(matches.length ? 'parent graph ambiguous' : 'parent not in selected graph');
+    const selected = matches[0];
+    graph(selected);
+    return Object.freeze({ parent: parent.path, root: selected.root, members: Object.freeze(selected.members.map((member) => Object.freeze({ ...member }))) });
+}
+import { createHash } from 'node:crypto';
+import { pathToFileURL } from 'node:url';
+import { canonicalJson } from "./reading.js";
+export function retainedNativeEvalMatches(record, actual) {
+    if (!record || record.kind !== 'derived-executable/1' || record.target?.kind !== 'eval' || !actual || !Array.isArray(actual.argv) || !Array.isArray(actual.rootPrefix) || !exactPath(actual.cwd) || !exactPath(actual.runtime) || !Array.isArray(actual.environment))
+        return false;
+    if (actual.rootPrefix.some((arg, i) => actual.argv[i] !== arg) || canonicalJson(actual.argv) !== canonicalJson(record.target.argv) || actual.cwd !== record.target.cwd || actual.cwd !== record.invocation.cwd || actual.runtime !== record.invocation.runtime || canonicalJson(actual.environment) !== canonicalJson(record.invocation.environment) || canonicalJson(actual.argv.slice(actual.rootPrefix.length)) !== canonicalJson(record.invocation.argv))
+        return false;
+    let launch;
+    try {
+        launch = nodeLaunch(actual.argv);
+    }
+    catch {
+        return false;
+    }
+    if (launch.kind !== 'eval' || launch.text !== record.target.text || launch.mode !== record.mode)
+        return false;
+    const bytes = Buffer.from(launch.text, 'utf8');
+    return bytes.toString('utf8') === launch.text && bytes.length === record.byteLength && 'sha256:' + createHash('sha256').update(bytes).digest('hex') === record.digest;
+}
+/** Exact Node CLI eval origin, not a file-pattern exception. A different URL
+ * continues through ordinary physical-parent verification and refuses if absent.
+ * Node's module and CommonJS CLI forms have distinct observed synthetic names. */
+export function nativeEvalParent(record, actual) {
+    if (!retainedNativeEvalMatches(record, actual))
+        programFail('actual eval differs from Root-retained context');
+    return Object.freeze({ url: record.mode === 'module' ? pathToFileURL(actual.cwd + '/').href + '[eval1]' : pathToFileURL(resolve(actual.cwd, '[eval]')).href, context: record.identity, digest: record.digest, mode: record.mode });
+}
+/** Non-authoritative discovery from Node's actual runtime options only. A false
+ * result confers no permission: physical-parent/load checks remain unchanged.
+ * Before-fork argv validation and exact retained-record matching are separate. */
+export function actualNodeEvalOptions(execArgv) { try {
+    return nodeLaunch(execArgv).kind === 'eval';
+}
+catch {
+    return false;
+} }

package/dist/host/native/preload.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/host/native/preload.js

@@ -0,0 +1,45 @@
+/** Fixed instrument preload. FD3 is an instrument-created execution envelope,
+ * never world stdin or workerData. It introduces no key or command grant.
+ */
+import { readSync, closeSync } from 'node:fs';
+import { realpathSync } from 'node:fs';
+import { installDescendantBoundary } from "./descendants.js";
+import { installBoundary, installNativeResolutionReuse } from "./loader.js";
+const fail = (why) => { throw Error('REFUSE·native preload ' + why); };
+const limit = Number(new URL(import.meta.url).searchParams.get('bytes'));
+if (!Number.isSafeInteger(limit) || limit < 1)
+    fail('missing admitted envelope resources');
+const header = Buffer.alloc(8);
+let read = 0;
+while (read < header.length) {
+    const n = readSync(3, header, read, header.length - read, null);
+    if (!n)
+        fail('truncated host frame');
+    read += n;
+}
+const size = header.readBigUInt64BE();
+if (size > BigInt(limit))
+    fail('host envelope bytes exceeded');
+const raw = Buffer.alloc(Number(size));
+read = 0;
+while (read < raw.length) {
+    const n = readSync(3, raw, read, raw.length - read, null);
+    if (!n)
+        fail('truncated host envelope');
+    read += n;
+}
+if (readSync(3, Buffer.alloc(1), 0, 1, null) !== 0)
+    fail('host envelope has trailing bytes');
+closeSync(3);
+const frame = JSON.parse(raw.toString('utf8'));
+if (frame.format !== 'native-image-envelope/1' || !Array.isArray(frame.entries) || !frame.entries.includes(realpathSync(process.argv[1])))
+    fail('entry outside host image');
+if (frame.descendant)
+    installDescendantBoundary(frame.descendant);
+installNativeResolutionReuse(frame.declaration);
+if (frame.execution) {
+    const facade = Object.freeze({ ...frame.execution, preload: frame.descendant?.custodian?.preload, mounts: Object.freeze(frame.execution.mounts.map(mount => Object.freeze({ ...mount }))) });
+    Object.defineProperty(globalThis, Symbol.for('bound.native.execution@1'), { value: facade, writable: false, configurable: false });
+}
+const boundary = installBoundary({ ...frame.declaration, entry: realpathSync(process.argv[1]) });
+process.once('beforeExit', () => boundary.assertClosed());