firedrill-run 2.2.5 → 3.0.1

package/dist/cli/src/runner-world-collector.js

@@ -0,0 +1,159 @@
+import { createHash } from 'node:crypto';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { CliError } from './http.js';
+import { executeLocalWorldSession } from './runner-container.js';
+import { withLocalJobInputs } from './runner-ownership.js';
+import { LocalWorldCommandDelivery } from './runner-world-commands.js';
+import { LocalWorldJournal } from './runner-world-journal.js';
+const invalid = () => new CliError('local_world_collection_unconfirmed', 'The original local world journal is incomplete. No target was restarted or cloud completion claimed.');
+async function retain(journal, label, body, signal) {
+    if (!body.length || body.length > 12 * 1024 ** 2)
+        throw invalid();
+    const parts = [];
+    for (let offset = 0, index = 0; offset < body.length; offset += 1024 ** 2, index++) {
+        signal.throwIfAborted();
+        const part = body.subarray(offset, offset + 1024 ** 2);
+        await journal.put(label + '-part-' + index, part);
+        parts.push({ size: part.length, sha256: createHash('sha256').update(part).digest('hex') });
+    }
+    const metadata = Buffer.from(JSON.stringify({ schema: 'firedrill.local-world-journal-file.v1',
+        size: body.length, sha256: createHash('sha256').update(body).digest('hex'), parts }));
+    try {
+        await journal.put(label + '-metadata', metadata);
+    }
+    finally {
+        metadata.fill(0);
+    }
+}
+function collector(configuration) {
+    let commandEvidencePending = false;
+    return {
+        async run(owner, actual, channel, signal) {
+            if (actual !== configuration || actual.control.schema !== 'firedrill.world-session.v1')
+                throw invalid();
+            const delivery = new LocalWorldCommandDelivery(owner, configuration, channel, signal);
+            try {
+                while (!channel.isClosing) {
+                    try {
+                        const command = await delivery.next();
+                        if (command) {
+                            commandEvidencePending = true;
+                            const result = command.publication_key === null ? await delivery.deliver(command) : await delivery.recover(command);
+                            commandEvidencePending = !['observed', 'not_dispatched', 'unknown', 'stop_requested'].includes(result.state);
+                        }
+                    }
+                    catch (error) {
+                        if (!channel.isClosing || !(error instanceof CliError) || !['local_world_claim_changed', 'local_world_command_unavailable',
+                            'local_world_evidence_unavailable', 'local_world_file_unavailable', 'local_session_observation_unavailable'].includes(error.code))
+                            throw error;
+                        // Closing can revoke the execution claim while an original file
+                        // transfer is pending. Keep the actual closed journal, not an
+                        // execution retry, extended lease or invented cloud receipt.
+                        commandEvidencePending = true;
+                    }
+                    if (!channel.isClosing)
+                        await Promise.race([sleep(500, undefined, { signal }), channel.waitClosing()]);
+                }
+                await channel.waitClosing();
+            }
+            finally {
+                await delivery.close();
+            }
+        },
+        async collect(owner, observation, final, signal) {
+            if (configuration.control.schema !== 'firedrill.world-session.v1' || observation.operation_id !== owner.lease
+                || final.observation.operation_id !== owner.lease || final.observation.session_id !== owner.session.session_id)
+                throw invalid();
+            const journal = await LocalWorldJournal.acquire(owner, configuration.manifest_sha256, { existingOnly: true });
+            signal = AbortSignal.any([signal, journal.signal]);
+            try {
+                const context = Buffer.from(configuration.control.evidence_context_sha256);
+                try {
+                    if (context.length !== 64 || !/^[a-f0-9]{64}$/.test(context.toString('ascii')))
+                        throw invalid();
+                    await journal.put('evidence-context', context);
+                }
+                finally {
+                    context.fill(0);
+                }
+                if (final.reference) {
+                    if (!final.statusBytes || final.statusBytes.length !== final.reference.size
+                        || createHash('sha256').update(final.statusBytes).digest('hex') !== final.reference.sha256)
+                        throw invalid();
+                    await retain(journal, 'final-native-status', final.statusBytes, signal);
+                }
+                else if (final.statusBytes !== null)
+                    throw invalid();
+                const body = Buffer.from(JSON.stringify(observation));
+                try {
+                    await retain(journal, 'final-container-observation', body, signal);
+                }
+                finally {
+                    body.fill(0);
+                }
+                const result = { schema: 'firedrill.local-world-collection.v1', session_id: owner.session.session_id,
+                    operation_id: owner.lease, manifest_sha256: configuration.manifest_sha256, stage: 'local_collected',
+                    native_status_retained: final.reference !== null, command_evidence_pending: commandEvidencePending,
+                    cloud_completion_recorded: false, provenance: 'customer_device' };
+                const receipt = Buffer.from(JSON.stringify(result));
+                try {
+                    await journal.put('local-collection', receipt);
+                }
+                finally {
+                    receipt.fill(0);
+                }
+                return result;
+            }
+            finally {
+                await journal.close();
+            }
+        },
+    };
+}
+/** Original current-claim manual-world consumer, shared by session opening and
+ * explicit execution of a web-admitted assignment. Finite closing/evidence
+ * recovery remains separate. This never claims a target trial or assessment.
+ */
+export async function retainLocalWorldSession(context, device, job, request, signal) {
+    let operation, result, executionError;
+    try {
+        result = await withLocalJobInputs(context, device, job, request, 'world_session', signal, async (owner, inputs, configuration, active) => {
+            if (owner.purpose !== 'world_session' || !owner.evidenceUpload)
+                throw invalid();
+            operation = owner.lease;
+            return executeLocalWorldSession(owner, inputs, configuration, collector(configuration), active);
+        });
+    }
+    catch (error) {
+        executionError = error;
+    }
+    const { syncLocalWorldCompletion } = await import('./runner-world-completion.js');
+    let closing;
+    let evidenceRecovery;
+    if (operation) {
+        try {
+            closing = await syncLocalWorldCompletion(context, operation, AbortSignal.timeout(30000));
+        }
+        catch (error) {
+            if (!executionError)
+                throw error;
+        }
+    }
+    if (operation && closing?.received && !closing.settled) {
+        try {
+            const { syncLocalWorldEvidence } = await import('./runner-world-evidence-sync.js');
+            await syncLocalWorldEvidence(context, operation, AbortSignal.timeout(30000));
+            closing = await syncLocalWorldCompletion(context, operation, AbortSignal.timeout(30000));
+        }
+        catch (error) {
+            // The original cleanup receipt is already accepted. Keep it visible when
+            // optional private-file recovery is interrupted or no longer authorized.
+            evidenceRecovery = { state: 'unconfirmed', code: error instanceof CliError ? error.code : 'local_world_evidence_unconfirmed' };
+        }
+    }
+    if (executionError)
+        throw executionError;
+    if (!result || !closing)
+        throw invalid();
+    return { ...result, closing, ...(evidenceRecovery ? { evidence_recovery: evidenceRecovery } : {}) };
+}

package/dist/cli/src/runner-world-command-evidence.js

@@ -0,0 +1,487 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { api } from './auth.js';
+import { CliError } from './http.js';
+import { identifier } from './world-contracts.js';
+import { historicalRunnerSigner, signRunnerRequest } from './runner-identity.js';
+import { localWorldClaimPath, localWorldClaimTime } from './runner-world-claim.js';
+import { LocalWorldJournal } from './runner-world-journal.js';
+import { localClosingReceiptMatches } from '../../contracts/local-evidence-contracts.js';
+import { localWorldIdentityMatches, LOCAL_WORLD_IDENTITY_KEYS } from '../../contracts/local-world-native-contracts.js';
+const PART = 1024 ** 2, CHUNK = 16384, MAX = 544 * 1024 ** 2, HASH = /^[a-f0-9]{64}$/;
+const FINISHED = ['observed', 'not_dispatched', 'unknown', 'stop_requested'];
+const KINDS = ['receipt', 'response', 'state', 'checkpoint'];
+const record = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const sha = (body) => createHash('sha256').update(body).digest('hex');
+const invalid = () => new CliError('local_world_evidence_changed', 'The original command evidence could not be confirmed. No agent action was repeated.');
+const exact = (value, keys) => Object.keys(value).sort().join(',') === [...keys].sort().join(',');
+function canonical(value) {
+    if (Array.isArray(value))
+        return '[' + value.map(canonical).join(',') + ']';
+    if (record(value))
+        return '{' + Object.keys(value).sort().map(key => JSON.stringify(key) + ':' + canonical(value[key])).join(',') + '}';
+    if (typeof value === 'number' && !Number.isFinite(value))
+        throw invalid();
+    const encoded = JSON.stringify(value);
+    if (encoded === undefined)
+        throw invalid();
+    return encoded;
+}
+const digest = (value) => sha(Buffer.from(canonical(value)));
+const name = (command, suffix) => 'command-' + identifier(command.id) + '-' + suffix;
+/** Original native observations/files only. Neither recovery nor uploading can
+ * publish a command or recreate a target. Disk holds encrypted chunks; the
+ * server separately validates the whole file and both private matcher sets.
+ */
+export class LocalWorldCommandEvidence {
+    owner;
+    manifest;
+    context;
+    channel;
+    journal;
+    signal;
+    closing;
+    constructor(owner, manifest, context, channel, journal, signal, closing = false) {
+        this.owner = owner;
+        this.manifest = manifest;
+        this.context = context;
+        this.channel = channel;
+        this.journal = journal;
+        this.signal = AbortSignal.any([signal, journal.signal]);
+        this.closing = closing;
+    }
+    static async open(owner, configuration, channel, signal) {
+        if (configuration.control.schema !== 'firedrill.world-session.v1')
+            throw invalid();
+        const journal = await LocalWorldJournal.acquire(owner, configuration.manifest_sha256, { existingOnly: true });
+        const context = configuration.control.evidence_context_sha256;
+        if (!HASH.test(context)) {
+            await journal.close();
+            throw invalid();
+        }
+        const raw = Buffer.from(context);
+        try {
+            await journal.put('evidence-context', raw);
+        }
+        catch (error) {
+            await journal.close();
+            throw error;
+        }
+        finally {
+            raw.fill(0);
+        }
+        return new LocalWorldCommandEvidence(owner, configuration.manifest_sha256, context, channel, journal, signal);
+    }
+    static async recover(owner, manifest, signal) {
+        const journal = await LocalWorldJournal.acquire(owner, manifest, { existingOnly: true });
+        let raw = null;
+        try {
+            raw = await journal.get('evidence-context');
+            const context = raw?.toString('ascii');
+            if (!raw || raw.length !== 64 || !context || !HASH.test(context))
+                throw invalid();
+            return new LocalWorldCommandEvidence(owner, manifest, context, null, journal, signal, true);
+        }
+        catch (error) {
+            await journal.close();
+            throw error;
+        }
+        finally {
+            raw?.fill(0);
+        }
+    }
+    async *commands() {
+        // Historical evidence is corroborated per original command, so publication
+        // need not sort or load the complete session before retaining its first file.
+        for await (const id of this.journal.commandIdentities(this.signal)) {
+            const raw = await this.journal.get('command-' + id + '-identity');
+            try {
+                if (!raw)
+                    throw invalid();
+                const value = JSON.parse(raw.toString('utf8'));
+                if (!record(value) || !exact(value, ['id', 'sequence', 'kind', 'sha256', 'not_after']) || value.id !== id
+                    || typeof value.sequence !== 'string' || !/^[1-9][0-9]{0,15}$/.test(value.sequence) || !Number.isSafeInteger(Number(value.sequence))
+                    || typeof value.kind !== 'string' || !/^[a-z_]{1,32}$/.test(value.kind) || typeof value.sha256 !== 'string' || !HASH.test(value.sha256)
+                    || typeof value.not_after !== 'string' || !Number.isFinite(Date.parse(value.not_after)))
+                    throw invalid();
+                yield value;
+            }
+            finally {
+                raw?.fill(0);
+            }
+        }
+    }
+    async retainFinalNative(reference) {
+        if (!this.closing || !Number.isSafeInteger(reference.size) || reference.size < 1 || reference.size > 8 * PART
+            || !HASH.test(reference.sha256))
+            throw invalid();
+        const owner = this.owner, auth = { actor: owner.owner, workspace: owner.workspace, signal: this.signal };
+        const path = localWorldClaimPath(owner) + '/world-final-status';
+        const closing = await api(localWorldClaimPath(owner) + '/completion', auth);
+        if (!localClosingReceiptMatches(closing, { ...owner, manifestSha256: this.manifest })
+            || closing.schema !== 'firedrill.local-completion-receipt.v1' || closing.job_id !== owner.job || closing.attempt_id !== owner.attempt
+            || closing.lease_id !== owner.lease || closing.request_key !== owner.request || closing.manifest_sha256 !== this.manifest
+            || closing.received !== true || closing.cleanup_recorded !== true || !HASH.test(closing.digest ?? '')
+            || closing.document?.schema !== 'firedrill.local-world-container-receipt.v1'
+            || closing.document.world_session.session_id !== owner.session.session_id
+            || closing.document.world_session.input_sha256 !== owner.session.input_sha256
+            || canonical(closing.document.evidence.native_status) !== canonical(reference))
+            throw invalid();
+        const check = (raw) => {
+            if (!record(raw) || !localWorldIdentityMatches(raw, owner, this.manifest)
+                || !exact(raw, [...LOCAL_WORLD_IDENTITY_KEYS.filter(key => key !== 'manifest_sha256'), 'schema', 'session_id', 'lease_id', 'manifest_sha256', 'input_sha256', 'closing_sha256',
+                    'state', 'artifact', 'provenance', 'independently_attested', 'server_time']) || raw.schema !== 'firedrill.local-world-final-receipt.v1'
+                || raw.session_id !== owner.session.session_id || raw.lease_id !== owner.lease || raw.manifest_sha256 !== this.manifest
+                || raw.input_sha256 !== owner.session.input_sha256 || raw.closing_sha256 !== closing.digest
+                || !['pending', 'retained', 'withheld', 'invalid', 'unavailable'].includes(String(raw.state))
+                || raw.provenance !== 'customer_device' || raw.independently_attested !== false
+                || typeof raw.server_time !== 'string' || !Number.isFinite(Date.parse(raw.server_time)))
+                throw invalid();
+            if (raw.state === 'retained') {
+                const item = raw.artifact;
+                if (!record(item) || !exact(item, ['id', 'size', 'sha256', 'generation']) || typeof item.id !== 'string'
+                    || identifier(item.id) !== item.id || item.size !== reference.size || item.sha256 !== reference.sha256
+                    || typeof item.generation !== 'string' || !/^[1-9][0-9]*$/.test(item.generation))
+                    throw invalid();
+            }
+            else if (raw.artifact !== null)
+                throw invalid();
+            return raw;
+        };
+        let receipt = check(await api(path, auth));
+        if (receipt.state !== 'pending')
+            return receipt;
+        if (closing.settled !== false)
+            throw invalid();
+        const metadata = await this.journal.get('final-native-status-metadata');
+        let body = null;
+        try {
+            if (!metadata)
+                throw new CliError('local_world_final_unavailable', 'The original final status was not saved locally. No execution was repeated.');
+            const value = JSON.parse(metadata.toString('utf8'));
+            if (!record(value) || !exact(value, ['schema', 'size', 'sha256', 'parts'])
+                || value.schema !== 'firedrill.local-world-journal-file.v1')
+                throw invalid();
+            const plan = { size: value.size, sha256: value.sha256, parts: value.parts };
+            this.checkMeta(plan, { ...reference, maximum: 8 * PART });
+            body = Buffer.alloc(reference.size);
+            let offset = 0;
+            for (let index = 0; index < plan.parts.length; index++) {
+                this.signal.throwIfAborted();
+                const part = await this.journal.get('final-native-status-part-' + index), expected = plan.parts[index];
+                try {
+                    if (!part || part.length !== expected.size || sha(part) !== expected.sha256)
+                        throw invalid();
+                    part.copy(body, offset);
+                    offset += part.length;
+                }
+                finally {
+                    part?.fill(0);
+                }
+            }
+            if (offset !== body.length || sha(body) !== reference.sha256)
+                throw invalid();
+            const signer = await historicalRunnerSigner(owner, owner.device, this.signal);
+            const payload = { schema: 'firedrill.local-world-final-write.v1', job_id: owner.job, attempt_id: owner.attempt,
+                lease_id: owner.lease, request_key: owner.request, device_key: owner.device, native_session_id: signer.nativeSession,
+                manifest_sha256: this.manifest, session_id: owner.session.session_id, input_sha256: owner.session.input_sha256,
+                context_sha256: this.context, closing_sha256: closing.digest, write_key: randomUUID(), sent_at_ms: Date.parse(receipt.server_time),
+                size: body.length, sha256: reference.sha256, content_base64: body.toString('base64') };
+            const proof = await signer.sign(payload);
+            try {
+                receipt = check(await api(path, { ...auth, method: 'POST', body: proof }));
+            }
+            catch (error) {
+                const observed = check(await api(path, auth));
+                if (observed.state === 'pending')
+                    throw error;
+                receipt = observed; // Read original write intent, never automatic resubmission.
+            }
+            return receipt;
+        }
+        finally {
+            metadata?.fill(0);
+            body?.fill(0);
+        }
+    }
+    async remember(command) {
+        const body = Buffer.from(canonical(Object.fromEntries(['id', 'sequence', 'kind', 'sha256', 'not_after'].map(key => [key, command[key]]))));
+        try {
+            await this.journal.put(name(command, 'identity'), body);
+        }
+        finally {
+            body.fill(0);
+        }
+    }
+    inspectObservation(command, value) {
+        if (!record(value) || value.schema !== 'firedrill.world-session-command-observation.v1' || value.session_id !== this.owner.session.session_id
+            || value.operation_id !== this.owner.lease || value.command_id !== command.id || value.command_sha256 !== command.sha256
+            || value.sequence !== Number(command.sequence) || !['queued', 'accepted', ...FINISHED].includes(String(value.state)))
+            throw invalid();
+        const finished = FINISHED.includes(String(value.state));
+        if (!exact(value, ['schema', 'session_id', 'operation_id', 'command_id', 'sequence', 'command_sha256', 'state', 'accepted_at', 'finished_at',
+            ...(finished ? ['code', 'response'] : [])])
+            || (value.state === 'queued' ? value.accepted_at !== null
+                : typeof value.accepted_at !== 'string' || !Number.isFinite(Date.parse(value.accepted_at)))
+            || (finished ? typeof value.finished_at !== 'string' || !Number.isFinite(Date.parse(value.finished_at)) : value.finished_at !== null)
+            || finished && (typeof value.code !== 'string' || !/^([a-z][a-z0-9_]{0,127})?$/.test(value.code)
+                || (value.state === 'observed' ? !record(value.response) : value.response !== null))
+            || finished && typeof value.accepted_at === 'string' && typeof value.finished_at === 'string'
+                && Date.parse(value.finished_at) < Date.parse(value.accepted_at))
+            throw invalid();
+        // Exact kind-specific native response validation remains server-owned. This
+        // declaration is not a successful outcome until that original API accepts it.
+    }
+    async saved(command) {
+        await this.remember(command);
+        const raw = await this.journal.get(name(command, 'terminal'));
+        if (!raw)
+            return null;
+        try {
+            if (raw.length > (['app_save', 'paired_save'].includes(command.kind) ? 2 * PART : 65536))
+                throw invalid();
+            const value = JSON.parse(raw.toString('utf8'));
+            this.inspectObservation(command, value);
+            if (!FINISHED.includes(value.state))
+                throw invalid();
+            return value;
+        }
+        finally {
+            raw.fill(0);
+        }
+    }
+    async request(command, input) {
+        this.signal.throwIfAborted();
+        const owner = this.owner;
+        let sent, nativeSession = owner.nativeSession, signer = null;
+        if (this.closing) {
+            const receipt = await api(localWorldClaimPath(owner) + '/completion', { actor: owner.owner, workspace: owner.workspace, signal: this.signal });
+            if (!localClosingReceiptMatches(receipt, { ...owner, manifestSha256: this.manifest })
+                || receipt.schema !== 'firedrill.local-completion-receipt.v1' || receipt.job_id !== owner.job || receipt.attempt_id !== owner.attempt
+                || receipt.lease_id !== owner.lease || receipt.request_key !== owner.request || receipt.manifest_sha256 !== this.manifest
+                || receipt.received !== true || receipt.cleanup_recorded !== true || receipt.settled !== false
+                || receipt.document?.schema !== 'firedrill.local-world-container-receipt.v1'
+                || receipt.document.world_session.session_id !== owner.session.session_id
+                || receipt.document.world_session.input_sha256 !== owner.session.input_sha256 || !Number.isFinite(Date.parse(receipt.server_time)))
+                throw invalid();
+            sent = Date.parse(receipt.server_time);
+            signer = await historicalRunnerSigner(owner, owner.device, this.signal);
+            nativeSession = signer.nativeSession;
+        }
+        else
+            sent = await localWorldClaimTime(owner, this.signal);
+        const base = { job_id: owner.job, attempt_id: owner.attempt, lease_id: owner.lease,
+            request_key: owner.request, device_key: owner.device, native_session_id: nativeSession, manifest_sha256: this.manifest,
+            session_id: owner.session.session_id, input_sha256: owner.session.input_sha256, command_id: command.id, command_sha256: command.sha256,
+            context_sha256: this.context, write_key: randomUUID(), sent_at_ms: sent };
+        let payload;
+        if (input.kind === 'observation') {
+            payload = this.closing ? { ...base, schema: 'firedrill.local-world-closing-command-result.v1', observation: input.observation }
+                : { ...base, schema: 'firedrill.local-world-command-result.v1', observation: input.observation };
+        }
+        else {
+            const file = { ...base, kind: input.fileKind, evidence_id: input.evidenceId, ...input.action };
+            payload = this.closing ? { ...file, schema: 'firedrill.local-world-closing-file-write.v1' }
+                : { ...file, schema: 'firedrill.local-world-file-write.v1' };
+        }
+        const suffix = input.kind === 'file' ? '/files/' + input.fileKind : '/evidence';
+        const proof = signer ? await signer.sign(payload) : await signRunnerRequest(owner, owner.device, payload, this.signal);
+        return api(localWorldClaimPath(owner) + (this.closing ? '/world-command-history/' : '/world-commands/') + identifier(command.id) + suffix, { actor: owner.owner, workspace: owner.workspace, signal: this.signal, method: 'POST', body: proof });
+    }
+    inspectReceipt(command, observation, raw) {
+        if (!record(raw) || !localWorldIdentityMatches(raw, this.owner, this.manifest)
+            || !exact(raw, [...LOCAL_WORLD_IDENTITY_KEYS, 'schema', 'evidence_id', 'command_id', 'session_id', 'lease_id', 'command_sha256', 'observation_sha256',
+                'native_state', 'state', 'required_files', 'files', 'server_time', 'provenance'])
+            || raw.schema !== 'firedrill.local-world-command-evidence-receipt.v1' || typeof raw.evidence_id !== 'string'
+            || identifier(raw.evidence_id) !== raw.evidence_id || raw.command_id !== command.id || raw.session_id !== this.owner.session.session_id
+            || raw.lease_id !== this.owner.lease || raw.command_sha256 !== command.sha256 || raw.observation_sha256 !== digest(observation)
+            || raw.native_state !== observation.state || !['observing', 'awaiting_files', 'finalized', 'unavailable'].includes(String(raw.state))
+            || !record(raw.required_files) || !Array.isArray(raw.files) || raw.files.length > 4 || typeof raw.server_time !== 'string'
+            || !Number.isFinite(Date.parse(raw.server_time)) || raw.provenance !== 'customer_device')
+            throw invalid();
+        const required = Object.keys(raw.required_files);
+        if (FINISHED.includes(observation.state) ? !required.includes('receipt') : required.length !== 0)
+            throw invalid();
+        if (required.some(kind => !KINDS.includes(kind)))
+            throw invalid();
+        for (const [kind, plan] of Object.entries(raw.required_files)) {
+            if (!record(plan) || !exact(plan, ['size', 'sha256', 'maximum']) || !Number.isSafeInteger(plan.maximum)
+                || Number(plan.maximum) < 1 || Number(plan.maximum) > MAX || kind === 'receipt' && Number(plan.maximum) > 2 * PART
+                || plan.size !== null && (!Number.isSafeInteger(plan.size) || Number(plan.size) < 1 || Number(plan.size) > Number(plan.maximum))
+                || plan.sha256 !== null && (typeof plan.sha256 !== 'string' || !HASH.test(plan.sha256))
+                || (plan.size === null) !== (plan.sha256 === null) || plan.size === null && kind !== 'receipt')
+                throw invalid();
+        }
+        if (raw.state === 'unavailable')
+            throw new CliError('local_world_evidence_unavailable', 'The original action has unavailable evidence. Inspect its saved report; do not repeat the action.');
+        const seen = new Set();
+        for (const file of raw.files) {
+            if (!record(file) || !exact(file, ['id', 'kind', 'size', 'sha256', 'state', 'received_parts', 'expires_at'])
+                || typeof file.id !== 'string' || identifier(file.id) !== file.id || !KINDS.includes(file.kind) || seen.has(file.kind)
+                || !raw.required_files[file.kind] || !Number.isSafeInteger(file.size) || file.size < 1 || file.size > MAX
+                || !HASH.test(file.sha256) || !['receiving', 'verifying', 'retained', 'withheld', 'refused', 'expired'].includes(file.state)
+                || !Array.isArray(file.received_parts) || new Set(file.received_parts).size !== file.received_parts.length
+                || file.received_parts.some(index => !Number.isSafeInteger(index) || index < 0 || index >= Math.ceil(file.size / PART))
+                || typeof file.expires_at !== 'string' || !Number.isFinite(Date.parse(file.expires_at)))
+                throw invalid();
+            const plan = raw.required_files[file.kind];
+            if (file.size > plan.maximum || plan.size !== null && file.size !== plan.size
+                || plan.sha256 !== null && file.sha256 !== plan.sha256)
+                throw invalid();
+            seen.add(file.kind);
+        }
+        return raw;
+    }
+    inspectFile(command, evidence, kind, metadata, raw) {
+        const count = metadata.parts.length;
+        if (!record(raw) || !localWorldIdentityMatches(raw, this.owner, this.manifest)
+            || !exact(raw, [...LOCAL_WORLD_IDENTITY_KEYS, 'schema', 'file_id', 'evidence_id', 'command_id', 'lease_id', 'kind', 'size', 'sha256', 'state',
+                'part_bytes', 'received_parts', 'expires_at', 'server_time', 'provenance']) || raw.schema !== 'firedrill.local-world-file-receipt.v1'
+            || typeof raw.file_id !== 'string' || identifier(raw.file_id) !== raw.file_id || raw.evidence_id !== evidence.evidence_id
+            || raw.command_id !== command.id || raw.lease_id !== this.owner.lease || raw.kind !== kind || raw.size !== metadata.size
+            || raw.sha256 !== metadata.sha256 || raw.part_bytes !== PART || !Array.isArray(raw.received_parts)
+            || new Set(raw.received_parts).size !== raw.received_parts.length || raw.received_parts.some(index => !Number.isSafeInteger(index) || index < 0 || index >= count)
+            || !['receiving', 'verifying', 'retained', 'withheld', 'refused', 'expired'].includes(String(raw.state)) || raw.provenance !== 'customer_device'
+            || typeof raw.server_time !== 'string' || !Number.isFinite(Date.parse(raw.server_time)) || typeof raw.expires_at !== 'string'
+            || !Number.isFinite(Date.parse(raw.expires_at)) || ['verifying', 'retained', 'withheld'].includes(String(raw.state)) && raw.received_parts.length !== count)
+            throw invalid();
+        if (['refused', 'expired'].includes(String(raw.state)))
+            throw new CliError('local_world_file_unavailable', 'The original command file is unavailable. No action was repeated.');
+        return raw;
+    }
+    checkMeta(metadata, plan) {
+        if (!record(metadata) || !exact(metadata, ['size', 'sha256', 'parts']) || !Number.isSafeInteger(metadata.size)
+            || Number(metadata.size) < 1 || Number(metadata.size) > plan.maximum || typeof metadata.sha256 !== 'string' || !HASH.test(metadata.sha256)
+            || plan.size !== null && metadata.size !== plan.size || plan.sha256 !== null && metadata.sha256 !== plan.sha256
+            || !Array.isArray(metadata.parts) || metadata.parts.length !== Math.ceil(Number(metadata.size) / PART))
+            throw invalid();
+        for (let index = 0; index < metadata.parts.length; index++) {
+            const part = metadata.parts[index];
+            if (!record(part) || !exact(part, ['size', 'sha256']) || part.size !== Math.min(PART, Number(metadata.size) - index * PART)
+                || typeof part.sha256 !== 'string' || !HASH.test(part.sha256))
+                throw invalid();
+        }
+    }
+    async collect(command, kind, plan) {
+        const prefix = name(command, kind), cached = await this.journal.get(prefix + '-metadata');
+        if (cached) {
+            try {
+                const metadata = JSON.parse(cached.toString('utf8'));
+                this.checkMeta(metadata, plan);
+                return metadata;
+            }
+            finally {
+                cached.fill(0);
+            }
+        }
+        if (this.closing || !this.channel)
+            throw new CliError('local_world_file_unavailable', 'These original command bytes are not in the saved local journal. No agent or native command was restarted.');
+        const file = await this.channel.openFile(command.id, kind), hash = createHash('sha256'), parts = [];
+        try {
+            if (file.size > plan.maximum || plan.size !== null && file.size !== plan.size || plan.sha256 !== null && file.sha256 !== plan.sha256)
+                throw invalid();
+            for (let offset = 0, index = 0; offset < file.size; offset += PART, index++) {
+                const body = Buffer.alloc(Math.min(PART, file.size - offset));
+                try {
+                    for (let position = 0; position < body.length; position += CHUNK) {
+                        this.signal.throwIfAborted();
+                        const chunk = await file.read(offset + position, Math.min(CHUNK, body.length - position));
+                        try {
+                            chunk.copy(body, position);
+                        }
+                        finally {
+                            chunk.fill(0);
+                        }
+                    }
+                    hash.update(body);
+                    parts.push({ size: body.length, sha256: sha(body) });
+                    await this.journal.put(prefix + '-part-' + index, body);
+                }
+                finally {
+                    body.fill(0);
+                }
+            }
+            if (hash.digest('hex') !== file.sha256)
+                throw invalid();
+            const metadata = { size: file.size, sha256: file.sha256, parts };
+            this.checkMeta(metadata, plan);
+            const raw = Buffer.from(JSON.stringify(metadata));
+            try {
+                await this.journal.put(prefix + '-metadata', raw);
+            }
+            finally {
+                raw.fill(0);
+            }
+            return metadata;
+        }
+        finally {
+            await file.close();
+        }
+    }
+    async transfer(command, evidence, kind, plan) {
+        const metadata = await this.collect(command, kind, plan);
+        const request = async (action) => this.inspectFile(command, evidence, kind, metadata, await this.request(command, { kind: 'file', fileKind: kind, evidenceId: evidence.evidence_id, action }));
+        let file = await request({ action: 'register', size: metadata.size, sha256: metadata.sha256 });
+        if (file.state === 'receiving') {
+            for (let index = 0; index < metadata.parts.length; index++) {
+                if (file.received_parts.includes(index))
+                    continue;
+                const body = await this.journal.get(name(command, kind) + '-part-' + index), part = metadata.parts[index];
+                if (!body)
+                    throw invalid();
+                try {
+                    if (body.length !== part.size || sha(body) !== part.sha256)
+                        throw invalid();
+                    file = await request({ action: 'chunk', index, size: body.length, sha256: part.sha256, content_base64: body.toString('base64') });
+                    if (!file.received_parts.includes(index))
+                        throw invalid();
+                }
+                finally {
+                    body.fill(0);
+                }
+            }
+            file = await request({ action: 'commit' });
+        }
+        while (file.state === 'verifying') {
+            await sleep(1000, undefined, { signal: this.signal }); // Real worker retention, never simulation progress.
+            file = await request({ action: 'status' });
+        }
+        if (!['retained', 'withheld'].includes(file.state))
+            throw invalid();
+    }
+    async retain(command, supplied) {
+        await this.remember(command);
+        this.inspectObservation(command, supplied);
+        const saved = await this.saved(command), observation = saved ?? supplied;
+        if (saved && FINISHED.includes(supplied.state) && digest(saved) !== digest(supplied))
+            throw invalid();
+        const raw = Buffer.from(JSON.stringify(observation));
+        try {
+            if (raw.length > (['app_save', 'paired_save'].includes(command.kind) ? 2 * PART : 65536))
+                throw invalid();
+            await this.journal.put(name(command, FINISHED.includes(observation.state) ? 'terminal' : 'observation'), raw, !FINISHED.includes(observation.state));
+        }
+        finally {
+            raw.fill(0);
+        }
+        const publish = async () => this.inspectReceipt(command, observation, await this.request(command, { kind: 'observation', observation }));
+        let evidence = await publish();
+        if (evidence.state === 'awaiting_files') {
+            for (const kind of KINDS)
+                if (evidence.required_files[kind])
+                    await this.transfer(command, evidence, kind, evidence.required_files[kind]);
+            evidence = await publish();
+            if (evidence.state !== 'finalized')
+                throw invalid();
+        }
+        const receipt = Buffer.from(JSON.stringify(evidence));
+        try {
+            await this.journal.put(name(command, 'cloud-receipt'), receipt, true);
+        }
+        finally {
+            receipt.fill(0);
+        }
+        return observation;
+    }
+    close() { return this.journal.close(); }
+}