firedrill-run 2.2.5 → 3.0.1

package/dist/cli/src/runner-session-channel.js

@@ -0,0 +1,377 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { CliError } from './http.js';
+import { identifier } from './world-contracts.js';
+/** Native controller pipe only. Not a public API, URL proxy or model tool. */
+export const SESSION_FRAME_SCHEMA = 'firedrill.local-session-frame.v1';
+const MAX_DOCUMENT = 16 * 1024 ** 2, CHUNK = 16384, HASH = /^[a-f0-9]{64}$/;
+const record = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const sha = (body) => createHash('sha256').update(body).digest('hex');
+const unavailable = () => new CliError('local_session_observation_unavailable', 'The local world did not return a confirmed observation. No command was retried.');
+const invalid = () => new CliError('local_session_identity_changed', 'The local world response did not match its saved session.');
+function exact(value, fields) {
+    if (Object.keys(value).sort().join(',') !== [...fields].sort().join(','))
+        throw invalid();
+}
+/**
+ * One request at a time, independent of concurrent private model frames.
+ * Loss is not replay permission. Command UUID/hash recovery uses result(), not
+ * another publication or a replacement world. The enclosing runner retains its
+ * current device/session/lease authority and owns container teardown separately.
+ */
+export class LocalSessionChannel {
+    pending = null;
+    stopped = false;
+    closing = false;
+    released = false;
+    closingObserved;
+    resolveClosing;
+    rejectClosing;
+    onAbort = () => this.close();
+    operation;
+    session;
+    emit;
+    signal;
+    inspectObservation;
+    constructor(operation, session, emit, signal, inspectObservation) {
+        this.operation = operation;
+        this.session = session;
+        this.emit = emit;
+        this.signal = signal;
+        this.inspectObservation = inspectObservation;
+        identifier(operation);
+        identifier(session);
+        this.closingObserved = new Promise((resolve, reject) => { this.resolveClosing = resolve; this.rejectClosing = reject; });
+        void this.closingObserved.catch(() => undefined);
+        signal.addEventListener('abort', this.onAbort, { once: true });
+        if (signal.aborted)
+            this.close();
+    }
+    get isClosing() { return this.closing; }
+    get isReleased() { return this.released; }
+    /** Resolves only for the actual native closing frame, never elapsed time. */
+    waitClosing() { return this.closingObserved; }
+    async release() {
+        if (!this.closing)
+            throw unavailable();
+        const result = await this.request({ action: 'release' });
+        exact(result, ['released']);
+        if (result.released !== true)
+            throw invalid();
+        this.released = true;
+        this.close();
+    }
+    close() {
+        this.stopped = true;
+        if (!this.closing)
+            this.rejectClosing(unavailable());
+        this.signal.removeEventListener('abort', this.onAbort);
+        const pending = this.pending;
+        this.pending = null;
+        if (pending) {
+            clearTimeout(pending.timer);
+            for (const part of pending.parts)
+                part.fill(0);
+            pending.parts = [];
+            pending.reject(unavailable());
+        }
+    }
+    async request(value) {
+        if (this.stopped || this.signal.aborted || this.pending || this.closing
+            && ['publish', 'checkpoint_open', 'checkpoint_chunk', 'checkpoint_finish'].includes(String(value.action)))
+            throw unavailable();
+        const body = Buffer.from(JSON.stringify(value));
+        if (!body.length || body.length > MAX_DOCUMENT)
+            throw invalid();
+        const requestId = randomUUID();
+        const promise = new Promise((resolve, reject) => {
+            const timer = setTimeout(() => this.close(), 90000);
+            this.pending = { id: requestId, size: null, sha256: null, sequence: 0, bytes: 0, parts: [], resolve, reject, timer };
+        });
+        // An abort can arrive while private input chunks are still being written.
+        // Mark the promise handled immediately; the real caller still awaits it.
+        void promise.catch(() => undefined);
+        const send = (kind, fields = {}) => this.emit({ schema: SESSION_FRAME_SCHEMA,
+            id: this.operation, request_id: requestId, kind, ...fields });
+        try {
+            await send('request_start', { length: body.length, sha256: sha(body) });
+            let sequence = 0;
+            for (let offset = 0; offset < body.length; offset += CHUNK) {
+                if (this.stopped || this.signal.aborted)
+                    throw unavailable();
+                await send('request_chunk', { sequence: sequence++, data: body.subarray(offset, offset + CHUNK).toString('base64') });
+            }
+            await send('request_end', { sequence });
+        }
+        catch {
+            this.close();
+            throw unavailable();
+        }
+        finally {
+            body.fill(0);
+        }
+        // A confirmed unavailable observation is not a broken transport or a
+        // reason to close the world. The owner may read the ORIGINAL command again.
+        return await promise;
+    }
+    async accept(value) {
+        try {
+            await this.readFrame(value);
+        }
+        catch {
+            this.close();
+            throw invalid();
+        }
+    }
+    async readFrame(value) {
+        if (this.stopped || this.signal.aborted || !record(value))
+            throw invalid();
+        const frame = value, pending = this.pending;
+        if (frame.schema === SESSION_FRAME_SCHEMA && frame.kind === 'closing') {
+            exact(frame, ['schema', 'kind', 'id', 'session_id']);
+            if (this.closing || frame.id !== this.operation || frame.session_id !== this.session)
+                throw invalid();
+            this.closing = true;
+            this.resolveClosing();
+            return;
+        }
+        if (frame.schema !== SESSION_FRAME_SCHEMA || frame.id !== this.operation || !pending || frame.request_id !== pending.id)
+            throw invalid();
+        const base = ['schema', 'kind', 'id', 'request_id'];
+        if (frame.kind === 'response_start') {
+            exact(frame, [...base, 'length', 'sha256']);
+            if (pending.size !== null || !Number.isSafeInteger(frame.length) || Number(frame.length) < 1 || Number(frame.length) > MAX_DOCUMENT
+                || typeof frame.sha256 !== 'string' || !HASH.test(frame.sha256))
+                throw invalid();
+            pending.size = Number(frame.length);
+            pending.sha256 = frame.sha256;
+            return;
+        }
+        if (pending.size === null)
+            throw invalid();
+        if (frame.kind === 'response_chunk') {
+            exact(frame, [...base, 'sequence', 'data']);
+            if (frame.sequence !== pending.sequence || typeof frame.data !== 'string' || !frame.data.length
+                || frame.data.length > 4 * Math.ceil(CHUNK / 3))
+                throw invalid();
+            const body = Buffer.from(frame.data, 'base64');
+            if (!body.length || body.length > CHUNK || body.toString('base64') !== frame.data || pending.bytes + body.length > pending.size)
+                throw invalid();
+            pending.parts.push(body);
+            pending.bytes += body.length;
+            pending.sequence++;
+            await this.emit({ schema: SESSION_FRAME_SCHEMA, id: this.operation, request_id: pending.id,
+                kind: 'response_ack', sequence: frame.sequence });
+            return;
+        }
+        exact(frame, [...base, 'sequence']);
+        if (frame.kind !== 'response_end' || frame.sequence !== pending.sequence || pending.bytes !== pending.size)
+            throw invalid();
+        const bytes = Buffer.concat(pending.parts, pending.bytes);
+        let result;
+        try {
+            if (sha(bytes) !== pending.sha256)
+                throw invalid();
+            result = JSON.parse(bytes.toString('utf8'));
+        }
+        finally {
+            bytes.fill(0);
+            for (const part of pending.parts)
+                part.fill(0);
+            pending.parts = [];
+        }
+        if (!record(result) || typeof result.ok !== 'boolean')
+            throw invalid();
+        if (!result.ok) {
+            exact(result, ['ok', 'code']);
+            if (result.code !== 'local_session_observation_unavailable')
+                throw invalid();
+            clearTimeout(pending.timer);
+            this.pending = null;
+            pending.reject(unavailable());
+            return;
+        }
+        exact(result, ['ok', 'data']);
+        if (!record(result.data))
+            throw invalid();
+        clearTimeout(pending.timer);
+        this.pending = null;
+        pending.resolve(result.data);
+    }
+    async observe() {
+        const result = await this.request({ action: 'observe' });
+        exact(result, ['schema', 'operation_id', 'session_id', 'status', 'launch']);
+        if (result.schema !== 'firedrill.world-session-observation.v1' || result.operation_id !== this.operation
+            || result.session_id !== this.session || result.status !== null && !record(result.status)
+            || result.launch !== null && !record(result.launch))
+            throw invalid();
+        const observation = result;
+        this.inspectObservation?.(observation);
+        return observation;
+    }
+    async finalObservation() {
+        if (!this.closing)
+            throw unavailable();
+        const result = await this.request({ action: 'final_observation' });
+        exact(result, ['schema', 'operation_id', 'session_id', 'status_json', 'status_reference', 'launch']);
+        if (result.schema !== 'firedrill.local-world-final-observation.v1' || result.operation_id !== this.operation
+            || result.session_id !== this.session || result.launch !== null && !record(result.launch))
+            throw invalid();
+        const reference = result.status_reference;
+        let status = null, statusBytes = null;
+        try {
+            if (reference === null) {
+                if (result.status_json !== null)
+                    throw invalid();
+            }
+            else {
+                if (!record(reference))
+                    throw invalid();
+                exact(reference, ['schema', 'size', 'sha256']);
+                if (reference.schema !== 'firedrill.local-world-final-reference.v1' || !Number.isSafeInteger(reference.size)
+                    || Number(reference.size) < 1 || Number(reference.size) > 8 * 1024 ** 2
+                    || typeof reference.sha256 !== 'string' || !HASH.test(reference.sha256)
+                    || typeof result.status_json !== 'string' || !/^[\x00-\x7f]*$/.test(result.status_json))
+                    throw invalid();
+                statusBytes = Buffer.from(result.status_json, 'ascii');
+                if (statusBytes.length !== reference.size || sha(statusBytes) !== reference.sha256)
+                    throw invalid();
+                const parsed = JSON.parse(statusBytes.toString('ascii'));
+                if (!record(parsed))
+                    throw invalid();
+                status = parsed;
+            }
+            const observation = { schema: 'firedrill.world-session-observation.v1', session_id: this.session,
+                operation_id: this.operation, status, launch: result.launch };
+            this.inspectObservation?.(observation);
+            return { observation, reference: reference, statusBytes };
+        }
+        catch {
+            statusBytes?.fill(0);
+            throw invalid();
+        }
+    }
+    command(result, commandId) {
+        if (result.schema !== 'firedrill.world-session-command-observation.v1' || result.operation_id !== this.operation
+            || result.session_id !== this.session || result.command_id !== commandId || !Number.isSafeInteger(result.sequence) || Number(result.sequence) < 1
+            || typeof result.command_sha256 !== 'string' || !HASH.test(result.command_sha256)
+            || !['queued', 'accepted', 'observed', 'not_dispatched', 'unknown', 'stop_requested'].includes(String(result.state)))
+            throw invalid();
+        return result;
+    }
+    async publish(commandBytes, body) {
+        if (!commandBytes.length || commandBytes.length > 65536 || body.length > 8 * 1024 ** 2)
+            throw invalid();
+        let document;
+        try {
+            document = JSON.parse(commandBytes.toString('utf8'));
+        }
+        catch {
+            throw invalid();
+        }
+        if (!record(document) || typeof document.command_id !== 'string' || identifier(document.command_id) !== document.command_id
+            || document.operation_id !== this.operation || document.session_id !== this.session)
+            throw invalid();
+        const result = this.command(await this.request({ action: 'publish', command: commandBytes.toString('base64'), body: body.toString('base64') }), document.command_id);
+        if (result.command_sha256 !== sha(commandBytes) || result.sequence !== document.sequence)
+            throw invalid();
+        return result;
+    }
+    /** Fixed native checkpoint input, streamed without a host archive file. It is
+     * not command publication; the enclosing original-owner transport commits
+     * publication only after the complete hash and native transfer are confirmed. */
+    async checkpointInput(commandBytes, read) {
+        if (!commandBytes.length || commandBytes.length > 65536)
+            throw invalid();
+        let document;
+        try {
+            document = JSON.parse(commandBytes.toString('utf8'));
+        }
+        catch {
+            throw invalid();
+        }
+        if (!record(document) || document.kind !== 'checkpoint_load' || document.session_id !== this.session
+            || document.operation_id !== this.operation || typeof document.command_id !== 'string'
+            || identifier(document.command_id) !== document.command_id || !record(document.request)
+            || !Number.isSafeInteger(document.request.size) || Number(document.request.size) < 1 || Number(document.request.size) > 512 * 1024 ** 2
+            || typeof document.request.sha256 !== 'string' || !HASH.test(document.request.sha256))
+            throw invalid();
+        const commandId = document.command_id, size = Number(document.request.size), digest = document.request.sha256;
+        const opened = await this.request({ action: 'checkpoint_open', command: commandBytes.toString('base64') });
+        exact(opened, ['command_id', 'size', 'sha256']);
+        if (opened.command_id !== commandId || opened.size !== size || opened.sha256 !== digest)
+            throw invalid();
+        const hash = createHash('sha256');
+        for (let offset = 0; offset < size; offset += 65536) {
+            this.signal.throwIfAborted();
+            const length = Math.min(65536, size - offset), raw = await read(offset, length);
+            try {
+                if (!Buffer.isBuffer(raw) || raw.length !== length)
+                    throw invalid();
+                hash.update(raw);
+                const part = await this.request({ action: 'checkpoint_chunk', command_id: commandId, offset, data: raw.toString('base64') });
+                exact(part, ['command_id', 'offset']);
+                if (part.command_id !== commandId || part.offset !== offset + length)
+                    throw invalid();
+            }
+            finally {
+                raw.fill(0);
+            }
+        }
+        if (hash.digest('hex') !== digest)
+            throw invalid();
+        const finished = await this.request({ action: 'checkpoint_finish', command_id: commandId });
+        exact(finished, ['command_id', 'size', 'sha256', 'ready']);
+        if (finished.command_id !== commandId || finished.size !== size || finished.sha256 !== digest || finished.ready !== true)
+            throw invalid();
+    }
+    async result(commandId) {
+        return this.command(await this.request({ action: 'result', command_id: identifier(commandId) }), commandId);
+    }
+    async openFile(commandId, part) {
+        commandId = identifier(commandId);
+        const result = await this.request({ action: 'file_open', command_id: commandId, part });
+        exact(result, ['file_id', 'command_id', 'part', 'size', 'sha256']);
+        if (typeof result.file_id !== 'string' || identifier(result.file_id) !== result.file_id || result.command_id !== commandId || result.part !== part
+            || !Number.isSafeInteger(result.size) || Number(result.size) < 1 || Number(result.size) > 544 * 1024 ** 2
+            || typeof result.sha256 !== 'string' || !HASH.test(result.sha256))
+            throw invalid();
+        return this.file(result.file_id, Number(result.size), result.sha256);
+    }
+    /** Original private native matcher packet. Never log, persist or upload to GCS. */
+    async openNativeFilters(contextSha256) {
+        if (!HASH.test(contextSha256))
+            throw invalid();
+        const result = await this.request({ action: 'native_filters_open' });
+        exact(result, ['file_id', 'part', 'size', 'sha256', 'context_sha256', 'scope']);
+        if (typeof result.file_id !== 'string' || identifier(result.file_id) !== result.file_id || result.part !== 'native_filters'
+            || result.scope !== 'native_database_credentials' || result.context_sha256 !== contextSha256
+            || !Number.isSafeInteger(result.size) || Number(result.size) < 1 || Number(result.size) > 64 * 1024 ** 2
+            || typeof result.sha256 !== 'string' || !HASH.test(result.sha256))
+            throw invalid();
+        return this.file(result.file_id, Number(result.size), result.sha256);
+    }
+    file(fileId, size, sha256) {
+        let closed = false;
+        return { id: fileId, size, sha256, read: async (offset, length) => {
+                if (closed || !Number.isSafeInteger(offset) || !Number.isSafeInteger(length) || offset < 0 || length < 1 || length > CHUNK || offset + length > size)
+                    throw invalid();
+                const response = await this.request({ action: 'file_chunk', file_id: fileId, offset, length });
+                exact(response, ['file_id', 'offset', 'length', 'sha256', 'data']);
+                if (response.file_id !== fileId || response.offset !== offset || response.length !== length || typeof response.data !== 'string'
+                    || response.data.length > 4 * Math.ceil(CHUNK / 3))
+                    throw invalid();
+                const bytes = Buffer.from(response.data, 'base64');
+                if (bytes.length !== length || bytes.toString('base64') !== response.data || sha(bytes) !== response.sha256)
+                    throw invalid();
+                return bytes;
+            }, close: async () => {
+                if (closed)
+                    return;
+                closed = true;
+                const response = await this.request({ action: 'file_close', file_id: fileId });
+                exact(response, ['file_id', 'closed']);
+                if (response.file_id !== fileId || response.closed !== true)
+                    throw invalid();
+            } };
+    }
+}

package/dist/cli/src/runner-trial-completion.js

@@ -0,0 +1,34 @@
+import { CliError } from './http.js';
+import { localContainerCompletion } from './runner-container.js';
+import { syncClosingReceipt } from './runner-completion.js';
+import { localTrialCollection } from './runner-trial-journal.js';
+/** Close exact execution authority before bulk evidence synchronization. No new
+ * claim, model, target, Docker lookup or inferred resource deletion belongs here.
+ */
+export async function syncLocalTrialCompletion(scope, operation, signal, options = {}) {
+    const saved = await localContainerCompletion(scope, operation, 'trial');
+    let evidence = null;
+    if (saved.document.resource_state === 'removed') {
+        try {
+            const collection = await localTrialCollection(scope, operation), journal = collection.journal;
+            if (journal.owner.job !== saved.job || journal.owner.attempt !== saved.attempt || journal.owner.device !== saved.device
+                || journal.owner.request !== saved.request || journal.manifest_sha256 !== saved.manifestSha256
+                || JSON.stringify(journal.observation.launch) !== JSON.stringify(saved.document.launch)
+                || JSON.stringify(journal.observation.status) !== JSON.stringify(saved.document.status))
+                throw new CliError('local_trial_closing_identity_changed', 'Drill closing evidence does not match its exact saved container. No result was claimed.');
+            // Close authority promptly using the exact private checkpoint. The cloud
+            // verifies every declared page/hash before publication; rereading all
+            // evidence here must not extend execution permission or miss its window.
+            signal.throwIfAborted();
+            evidence = { schema: 'firedrill.local-trial-aggregate.v1', execution_id: journal.execution_id,
+                pages: journal.pages, event_offset: journal.event_offset, artifact_offset: journal.artifact_offset,
+                artifacts_retained: journal.artifacts_retained, page_chain_sha256: journal.page_chain_sha256,
+                collection_complete: journal.stage === 'local_collected' };
+        }
+        catch (error) {
+            if (error?.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    return syncClosingReceipt(scope, { ...saved, document: { ...saved.document, evidence } }, signal, options);
+}