@lapxo/bound 0.1.8 → 0.2.0

package/dist/host/native/control-bridge.js

@@ -0,0 +1,110 @@
+import { sha256 as digest } from "../hash.js";
+/** Root-fixed synchronous transport. It retains no grants or command results. */
+import { Worker, isMainThread } from 'node:worker_threads';
+import { readBoundedFile } from "./bounded-file.js";
+import { remainingDeadlineMs } from "./deadline.js";
+const FixedWorker = Worker;
+const HEADER_BYTES = 32;
+let controlWorkerOccupied = false;
+export function createFixedControlBridge(inputBinding) {
+    // @1 is one main-thread control worker per OS process, never a WorldWorker grant.
+    if (!isMainThread)
+        throw Error('REFUSE·Root control transport requires main-thread realm');
+    const refuse = (why) => { throw Error('REFUSE·Root control transport ' + why); };
+    const integer = (value) => Number.isSafeInteger(value) && value > 0;
+    const sourceBytes = inputBinding.workerBytes;
+    const workerSelection = Object.freeze({ ...inputBinding.worker });
+    if (!(sourceBytes instanceof Uint8Array) || !workerSelection.coordinate || !integer(workerSelection.bytes) || sourceBytes.byteLength !== workerSelection.bytes)
+        refuse('selected worker bytes/type bound differs before copy');
+    const binding = Object.freeze({ ...inputBinding,
+        endpoint: Object.freeze({ ...inputBinding.endpoint }), resources: Object.freeze({ ...inputBinding.resources }),
+        runtime: Object.freeze({ ...inputBinding.runtime }), worker: workerSelection,
+        workerBytes: Buffer.from(sourceBytes) });
+    const { endpoint, resources, runtime, worker: selected } = binding;
+    if (!selected.coordinate || !integer(selected.bytes) || binding.workerBytes.byteLength !== selected.bytes || digest(binding.workerBytes) !== selected.digest)
+        refuse('selected worker bytes differ');
+    if (runtime.path !== process.execPath || !integer(runtime.bytes) || digest(readBoundedFile(runtime.path, runtime.bytes, runtime.path)) !== runtime.digest)
+        refuse('selected runtime bytes differ');
+    if (![endpoint.timeoutMs, endpoint.responseBytes, endpoint.deadlineMs, binding.deadlineMs].every(integer) || binding.deadlineMs > endpoint.deadlineMs)
+        refuse('parent time/byte resource absent or widened');
+    // host-control-transport@1 encodes each byte length in a signed Int32 cell.
+    // Refuse an incompatible declaration; never wrap or clamp its bound.
+    if (resources.inputBytes > 2147483647 || resources.outputBytes > 2147483647)
+        refuse('host-control-transport@1 signed Int32 length representation');
+    const sharedBytes = HEADER_BYTES + resources.inputBytes + resources.outputBytes;
+    if (!Object.values(resources).every(integer) || !Number.isSafeInteger(sharedBytes) || resources.inputBytes > endpoint.responseBytes || resources.outputBytes > endpoint.responseBytes || sharedBytes > resources.sharedBytes)
+        refuse('shared/input/output resource absent or exceeded');
+    const remainingMs = Math.min(endpoint.timeoutMs, binding.deadlineMs - Date.now());
+    if (remainingMs <= 0)
+        refuse('parent deadline');
+    const deadline = process.hrtime.bigint() + BigInt(remainingMs) * 1000000n;
+    const remaining = remainingDeadlineMs.bind(undefined, deadline);
+    if (controlWorkerOccupied)
+        refuse('one live main-thread control worker resource exhausted');
+    let shared;
+    try {
+        shared = new SharedArrayBuffer(sharedBytes);
+    }
+    catch {
+        return refuse('shared resource allocation');
+    }
+    const header = new Int32Array(shared, 0, 8), input = new Uint8Array(shared, HEADER_BYTES, resources.inputBytes), output = new Uint8Array(shared, HEADER_BYTES + resources.inputBytes, resources.outputBytes);
+    // Independently sealed bytes are immutable here. A payload cannot select a path or verifier.
+    const code = Buffer.from(binding.workerBytes).toString('base64');
+    controlWorkerOccupied = true;
+    let worker;
+    try {
+        worker = new FixedWorker(new URL('data:text/javascript;base64,' + code), { execArgv: [], env: {}, workerData: { endpoint: { ...endpoint }, deadlineMs: binding.deadlineMs, shared, inputBytes: resources.inputBytes, outputBytes: resources.outputBytes } });
+    }
+    catch {
+        controlWorkerOccupied = false;
+        return refuse('worker construction interrupted');
+    }
+    let termination;
+    const stop = () => termination ?? (termination = worker.terminate().finally(() => { controlWorkerOccupied = false; }));
+    worker.once('exit', () => { controlWorkerOccupied = false; });
+    worker.unref();
+    let red, closed = false, sequence = 0;
+    const fail = (why) => { red ?? (red = 'REFUSE·Root control transport ' + why); void stop(); throw Error(red); };
+    // Error events still need a listener when a synchronous wait prevents JS callbacks.
+    worker.on('error', error => { red ?? (red = 'REFUSE·Root control transport worker interrupted: ' + error.message); });
+    if (Atomics.load(header, 5) !== 1 && Atomics.wait(header, 5, 0, remaining()) === 'timed-out')
+        fail('startup deadline/interruption');
+    return {
+        exchange(frame) {
+            if (red)
+                throw Error(red);
+            if (closed)
+                fail('closed');
+            if (remaining() <= 0)
+                fail('parent deadline');
+            if (typeof frame !== 'string' || !frame.length || Buffer.byteLength(frame, 'utf8') > resources.inputBytes)
+                fail('request bytes before copy');
+            const bytes = Buffer.from(frame, 'utf8');
+            if (Atomics.load(header, 0) !== 0 || sequence >= 2147483647)
+                fail('overlapping request/sequence');
+            input.set(bytes);
+            Atomics.store(header, 2, bytes.length);
+            Atomics.store(header, 1, ++sequence);
+            Atomics.store(header, 0, 1);
+            worker.postMessage(sequence);
+            if (Atomics.wait(header, 0, 1, remaining()) === 'timed-out' || remaining() <= 0)
+                fail('deadline/interruption');
+            const state = Atomics.load(header, 0), length = Atomics.load(header, 3);
+            if (length < 1 || length > resources.outputBytes)
+                fail('reply bytes');
+            let reply;
+            try {
+                reply = new TextDecoder('utf-8', { fatal: true }).decode(output.slice(0, length));
+            }
+            catch {
+                return fail('reply encoding');
+            }
+            if (state !== 2)
+                fail(reply);
+            Atomics.store(header, 0, 0);
+            return reply;
+        },
+        async close() { closed = true; await stop(); }
+    };
+}

package/dist/host/native/control-selection.d.ts

@@ -0,0 +1,29 @@
+import { type RootStanding, type PortProfile } from './reading.ts';
+export interface HostControlProfile {
+    readonly profile: 'host-control-transport@1';
+    readonly realm: 'main-thread';
+    readonly coordinate: string;
+    readonly selector: {
+        readonly port: string;
+        readonly implementation: string;
+    };
+    readonly worker: {
+        readonly coordinate: string;
+        readonly digest: string;
+        readonly bytes: number;
+    };
+    readonly runtime: {
+        readonly coordinate: string;
+        readonly digest: string;
+    };
+    readonly limits: {
+        readonly workersPerProcess: 1;
+        readonly inFlight: 1;
+        readonly sharedBytes: number;
+    };
+}
+export interface HostControlSelection {
+    readonly line: string;
+    readonly profile: HostControlProfile;
+}
+export declare function selectedHostControl(root: RootStanding, parent: PortProfile): HostControlSelection | undefined;

package/dist/host/native/control-selection.js

@@ -0,0 +1,32 @@
+/** Optional Root-selected control transport. This is fixed host machinery,
+ * never a world's worker permission or a change to producer message/work caps.
+ * One retained control worker belongs only to the main thread of each process;
+ * other Node realms keep the existing bounded fixed-client transport. */
+import { parsedLine as parse } from "../../fold/claims.js";
+import { authenticateSignedPort } from "./reading.js";
+const fail = (why) => { throw Error('REFUSE·host control ' + why); };
+const keys = (value) => value && typeof value === 'object' && !Array.isArray(value) ? Object.keys(value).sort().join(',') : '';
+const digest = (value) => typeof value === 'string' && /^sha256:[a-f0-9]{64}$/.test(value);
+export function selectedHostControl(root, parent) {
+    const coordinate = [parent.port.coordinate, 'control'].join('/'), rows = root.live.filter(line => { const got = parse(line); return got.kind === 'fact' && got.value.fields.scope === coordinate; });
+    if (!rows.length)
+        return undefined;
+    const selected = authenticateSignedPort(root, coordinate), profile = selected.profile, parsed = parse(selected.line);
+    if (parsed.kind !== 'fact' || parsed.value.fields.by !== root.signer.id)
+        fail('selection is not Root signed ' + coordinate);
+    if (keys(profile) !== 'coordinate,limits,profile,realm,runtime,selector,worker' || profile.profile !== 'host-control-transport@1' || profile.realm !== 'main-thread' || profile.coordinate !== coordinate || keys(profile.selector) !== 'implementation,port' || profile.selector.port !== parent.port.coordinate || profile.selector.implementation !== parent.port.implementation)
+        fail('profile selector differs ' + coordinate);
+    if (keys(profile.worker) !== 'bytes,coordinate,digest' || !/^native\/executor\/(?:dist|src)\/host\/native\/control-bridge-worker\.(?:js|ts)$/.test(profile.worker.coordinate) || !digest(profile.worker.digest) || !Number.isSafeInteger(profile.worker.bytes) || profile.worker.bytes < 1)
+        fail('fixed worker binding absent ' + coordinate);
+    const runtime = parent.selection.members.find(member => member.coordinate === parent.selection.runtime);
+    if (keys(profile.runtime) !== 'coordinate,digest' || !runtime || profile.runtime.coordinate !== runtime.coordinate || profile.runtime.digest !== runtime.digest)
+        fail('fixed runtime selection differs ' + coordinate);
+    if (keys(profile.limits) !== 'inFlight,sharedBytes,workersPerProcess' || profile.limits.workersPerProcess !== 1 || profile.limits.inFlight !== 1 || !Number.isSafeInteger(profile.limits.sharedBytes) || profile.limits.sharedBytes < 32)
+        fail('named resource invalid ' + coordinate);
+    if (!Number.isSafeInteger(parent.port.responseBytes) || parent.port.responseBytes < 1 || parent.port.responseBytes > 2147483647)
+        fail('message cap outside declared signed Int32 representation ' + coordinate);
+    const required = 32 + 2 * parent.port.responseBytes;
+    if (!Number.isSafeInteger(required) || profile.limits.sharedBytes < required)
+        fail('shared resource cannot preserve message caps ' + coordinate);
+    return Object.freeze({ line: selected.line, profile });
+}

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

@@ -0,0 +1,5 @@
+import { type RootStanding, type PortProfile } from './reading.ts';
+import type { RootJobCustody, NodeImage } from './node-jobs.ts';
+import type { Handoff } from './jobs.ts';
+import type { LogicalLoader } from './image.ts';
+export declare function nativeRootJobCustody(root: RootStanding, profile: PortProfile, handoff: Handoff, image: NodeImage, logical: LogicalLoader): RootJobCustody;

package/dist/host/native/custody.js

@@ -0,0 +1,91 @@
+/** Fixed Root constructor for finite descendant custody. It selects only current
+ * authenticated Root records matching the already planned native parent job.
+ */
+import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, extname } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { createHash } from 'node:crypto';
+import { parse } from '@lapxo/topos/wire';
+import { processOf, ownRoot } from "../../observe/runner.js";
+import { selectedHostControl } from "./control-selection.js";
+import { readBoundedFile } from "./bounded-file.js";
+import { authenticateSignedPort } from "./reading.js";
+import { createProducerJobCustody } from "./generated-custodian.js";
+const fail = (why) => { throw Error('REFUSE·native custody ' + why); };
+const sha = (raw) => 'sha256:' + createHash('sha256').update(raw).digest('hex');
+export function nativeRootJobCustody(root, profile, handoff, image, logical) {
+    const data = logical.members.map(member => { const location = image.locations.find(loc => loc.member === member.coordinate); if (!location)
+        return fail('literal member absent'); return { path: location.path, digest: member.digest }; }), libraries = logical.libraries.map(lib => { const location = image.locations.find(loc => loc.member === lib.manifest); if (!location)
+        return fail('library absent'); return { name: lib.name, manifest: location.path, coordinate: lib.manifest }; });
+    const candidates = root.live.flatMap(line => { const row = parse(line); if (row.kind !== 'fact' || !row.value.fields.scope.startsWith('port/'))
+        return []; let p; try {
+        p = JSON.parse(row.value.fields.about ?? '');
+    }
+    catch {
+        return [];
+    } return p?.selector?.port === profile.port.coordinate ? [{ coordinate: row.value.fields.scope, profile: p }] : []; });
+    return { async open(parent) {
+            const matching = candidates.filter(candidate => candidate.profile.selector.binding === parent.binding && candidate.profile.selector.implementation === parent.implementation);
+            const producers = matching.filter(candidate => candidate.profile.profile === 'host-generated-executable@3');
+            if (producers.length !== 1)
+                return fail('requires one current Root producer for ' + parent.binding);
+            const selected = producers[0];
+            authenticateSignedPort(root, selected.coordinate);
+            const control = selectedHostControl(root, profile);
+            const implementation = fileURLToPath(new URL('./generated' + extname(new URL(import.meta.url).pathname), import.meta.url)), implementationBytes = readBoundedFile(implementation, root.budget.bytes, implementation);
+            const runtime = image.locations.find(location => location.member === image.runtime), runtimeMember = handoff.members.find(member => member.coordinate === image.runtime);
+            if (!runtime || !runtimeMember)
+                return fail('fixed actual runtime absent');
+            const binaries = matching.filter(candidate => ['host-native-binary@1', 'host-native-binary-origin@1'].includes(candidate.profile.profile)).map(candidate => { const p = candidate.profile, location = image.locations.find(loc => loc.member === p.entry?.path), member = handoff.members.find(m => m.coordinate === p.entry?.path); if (!location || !member)
+                return fail('binary outside actual selected image'); return { coordinate: candidate.coordinate, privateBinding: { coordinate: member.coordinate, path: location.path, digest: member.digest } }; });
+            const programs = matching.filter(candidate => candidate.profile.profile === 'host-native-program@1').map(candidate => ({ coordinate: candidate.coordinate, runtimeBinding: { coordinate: image.runtime, path: runtime.path, digest: runtimeMember.digest, members: image.locations.map(location => ({ coordinate: location.member, path: location.path })) } }));
+            const directory = mkdtempSync(join(tmpdir(), 'bound-native-custody-')), contextFile = join(directory, 'context.json'), configFile = join(directory, 'loader.json');
+            let acquired;
+            try {
+                const service = createProducerJobCustody({ root, coordinate: selected.coordinate, implementationBytes, snapshot: { budget: { members: handoff.budget.members, bytes: handoff.budget.bytes }, members: data, libraries, builtins: logical.builtins, platform: logical.platform }, nativeImplementations: new Set(logical.members.map(member => member.digest)), directory, contextFile, nativeBinaries: binaries, programSelections: programs });
+                acquired = await service.open(parent);
+                const client = processOf('custodian'), clientBytes = readBoundedFile(client, parent.responseBytes, client), preload = new URL(pathToFileURL(processOf('native-descendant')).href);
+                preload.searchParams.set('config', configFile);
+                preload.searchParams.set('bytes', String(handoff.budget.bytes));
+                let controlEnvelope;
+                if (control) {
+                    const worker = control.profile.worker, path = join(ownRoot(), worker.coordinate.slice('native/executor/'.length)), raw = readBoundedFile(path, worker.bytes, worker.coordinate);
+                    if (raw.length !== worker.bytes || sha(raw) !== worker.digest)
+                        return fail('sealed control worker bytes differ');
+                    if (control.profile.runtime.coordinate !== image.runtime || control.profile.runtime.digest !== runtimeMember.digest)
+                        return fail('sealed control runtime differs');
+                    const shared = 32 + 2 * parent.responseBytes;
+                    if (!Number.isSafeInteger(shared) || shared > control.profile.limits.sharedBytes)
+                        return fail('shared control resource absent');
+                    controlEnvelope = { profileLine: control.line, realm: control.profile.realm, worker: { ...worker, path }, resources: { inputBytes: parent.responseBytes, outputBytes: parent.responseBytes, sharedBytes: control.profile.limits.sharedBytes } };
+                }
+                const config = { ...(controlEnvelope ? { control: controlEnvelope } : {}), members: data, libraries, builtins: logical.builtins, platform: logical.platform, executableDigests: logical.members.filter(member => /\.(?:[mc]?js|ts)$/.test(member.coordinate)).map(member => member.digest), metadataDigests: logical.members.filter(member => member.coordinate.endsWith('.json')).map(member => member.digest), inputBytes: handoff.budget.bytes, runtimeBytes: runtimeMember.bytes.byteLength, clientBytes: clientBytes.length, contextBytes: parent.responseBytes, custodian: { contextFile, client, runtime: runtime.path, preload: preload.href, runtimeDigest: runtimeMember.digest, clientDigest: sha(clientBytes) } };
+                // Loader metadata describes the authenticated input image, not the command's
+                // stdout. Its declared input budget stays separate from responseBytes.
+                const raw = Buffer.from(JSON.stringify(config));
+                if (raw.length > handoff.budget.bytes)
+                    return fail('operational descendant envelope bytes');
+                writeFileSync(configFile, raw, { flag: 'wx', mode: 0o400 });
+                // The URL carries an independently fixed expected digest of the private host
+                // envelope. This is operational custody, never authority from JSON.
+                preload.searchParams.set('digest', sha(raw));
+                config.custodian.preload = preload.href;
+                // The recursive preload URL excludes its own digest while writing the file;
+                // its fixed child validates the exact file before installing any hook.
+                const descendant = { ...config, custodian: { ...config.custodian, preload: preload.href } };
+                const held = acquired;
+                return { descendant, assertClosed: () => held.assertClosed(), async close() { try {
+                        await held.close();
+                    }
+                    finally {
+                        rmSync(directory, { recursive: true, force: true });
+                    } } };
+            }
+            catch (error) {
+                await acquired?.close();
+                rmSync(directory, { recursive: true, force: true });
+                throw error;
+            }
+        } };
+}

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

@@ -0,0 +1,12 @@
+/** Remaining monotonic lease, rounded up for host APIs that accept milliseconds. */
+export declare function remainingDeadlineMs(deadline: bigint): number;
+interface Clock {
+    readonly now: () => bigint;
+    readonly schedule: (callback: () => void, delayMs: number) => unknown;
+    readonly cancel: (handle: unknown) => void;
+}
+/** The admitted deadline is never clamped to the platform timer range. Each
+ * timer is merely a wake-up slice; expiry checks the original monotonic clock.
+ * Injected clock exists only for deterministic platform-boundary vectors. */
+export declare function scheduleDeadline(deadline: bigint, expire: () => void, clock?: Clock): () => void;
+export {};

package/dist/host/native/deadline.js

@@ -0,0 +1,28 @@
+const TIMER_MAX_MS = 2147483647;
+/** Remaining monotonic lease, rounded up for host APIs that accept milliseconds. */
+export function remainingDeadlineMs(deadline) {
+    return Math.max(0, Number((deadline - process.hrtime.bigint() + 999999n) / 1000000n));
+}
+const native = { now: () => process.hrtime.bigint(), schedule: (callback, delay) => setTimeout(callback, delay), cancel: handle => clearTimeout(handle) };
+/** The admitted deadline is never clamped to the platform timer range. Each
+ * timer is merely a wake-up slice; expiry checks the original monotonic clock.
+ * Injected clock exists only for deterministic platform-boundary vectors. */
+export function scheduleDeadline(deadline, expire, clock = native) {
+    let active = true, handle;
+    const arm = () => {
+        if (!active)
+            return;
+        const remaining = deadline - clock.now();
+        if (remaining <= 0n) {
+            active = false;
+            expire();
+            return;
+        }
+        const ceilMs = (remaining + 999999n) / 1000000n;
+        const slice = ceilMs > BigInt(TIMER_MAX_MS) ? TIMER_MAX_MS : Number(ceilMs);
+        handle = clock.schedule(arm, slice);
+    };
+    arm();
+    return () => { active = false; if (handle !== undefined)
+        clock.cancel(handle); };
+}

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

@@ -0,0 +1 @@
+export declare function installDescendantBoundary(config: any): void;