firedrill-run 2.2.5 → 3.0.0

package/dist/cli/src/runner-evidence-erasure.js

@@ -0,0 +1,351 @@
+import { constants } from 'node:fs';
+import { lstat, open, opendir, rmdir, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { privateDirectory } from './credentials.js';
+import { CliError } from './http.js';
+import { identifier } from './world-contracts.js';
+import { selectOne } from './prompts.js';
+import { localEvidenceContexts, withLocalContainerCompletion } from './runner-container.js';
+import { forgetWorldEvidence, pruneWorldEvidence } from './runner-world-erasure.js';
+import { lockLocalEvidence, privateEvidenceMetadata, readEvidencePolicy, writeEvidencePolicy } from './runner-evidence-retention.js';
+const uuid = '[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}';
+const index = '(0|[1-9][0-9]{0,15})';
+const temporary = new RegExp('^(receipt|cloud-receipts)\\.json\\.' + uuid + '\\.tmp$');
+const invalid = () => new CliError('local_evidence_erasure_identity', 'The exact private evidence identity or generated file set could not be confirmed. Unknown files and original cleanup records were not removed.');
+const record = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const count = (v) => typeof v === 'number' && Number.isSafeInteger(v) && v >= 0;
+const same = (v, expected) => ['owner', 'workspace', 'device', 'job', 'request', 'lease', 'attempt']
+    .every(key => v[key] === expected[key]);
+const MAX_PASS = 1000;
+async function selected(operation, options) {
+    operation = identifier(operation);
+    let result;
+    for await (const row of localEvidenceContexts(operation, options.workspace, undefined, options.signal)) {
+        if (result)
+            throw invalid();
+        result = row;
+    }
+    if (!result)
+        throw invalid();
+    return result;
+}
+async function directory(path) {
+    const before = await lstat(path, { bigint: true }).catch(error => { if (error.code === 'ENOENT')
+        return null; throw error; });
+    if (!before)
+        return null;
+    if (!before.isDirectory() || before.isSymbolicLink() || before.mode & 63n || process.getuid && before.uid !== BigInt(process.getuid()))
+        throw invalid();
+    const held = await open(path, constants.O_RDONLY | (constants.O_DIRECTORY ?? 0) | (constants.O_NOFOLLOW ?? 0));
+    const actual = await held.stat({ bigint: true });
+    if (actual.dev !== before.dev || actual.ino !== before.ino) {
+        await held.close();
+        throw invalid();
+    }
+    const check = async () => {
+        const current = await lstat(path, { bigint: true });
+        if (!current.isDirectory() || current.isSymbolicLink() || current.dev !== actual.dev || current.ino !== actual.ino
+            || current.mode & 63n || process.getuid && current.uid !== BigInt(process.getuid()))
+            throw invalid();
+    };
+    return { check, sync: () => held.sync(), close: () => held.close() };
+}
+async function header(path, kind, identity, hasPolicy) {
+    const value = await privateEvidenceMetadata(join(path, 'receipt.json')).catch(error => {
+        if (error.code === 'ENOENT' && hasPolicy)
+            return null;
+        throw error;
+    });
+    if (value === null)
+        return null;
+    if (!record(value) || value.manifest_sha256 !== identity.manifest_sha256)
+        throw invalid();
+    if (kind === 'live') {
+        if (value.schema !== 'firedrill.local-trial-live-journal.v2' || value.job_id !== identity.job
+            || value.lease_id !== identity.lease || value.attempt_id !== identity.attempt
+            || !count(value.events) || !count(value.queued) || !count(value.artifact_count))
+            throw invalid();
+    }
+    else if (!record(value.owner) || !same(value.owner, identity) || value.owner.purpose !== identity.purpose
+        || value.schema !== (kind === 'validation' ? 'firedrill.local-evidence-journal.v1' : 'firedrill.local-trial-journal.v1')
+        || kind === 'trial' && (!count(value.pages) || !count(value.artifact_offset) || !count(value.artifacts_retained)))
+        throw invalid();
+    return value;
+}
+function maximum(name, kind, saved) {
+    const pending = temporary.exec(name);
+    if (name === 'receipt.json' || pending && (pending[1] === 'receipt' || kind === 'trial')
+        || kind === 'trial' && name === 'cloud-receipts.json')
+        return 65536;
+    if (kind === 'validation') {
+        if (['native.zip', 'native.partial'].includes(name))
+            return 128 * 1024 ** 2;
+        if (['operations.json', 'operations.partial'].includes(name))
+            return 8 * 1024 ** 2;
+        throw invalid();
+    }
+    const artifact = new RegExp('^' + index + '\\.bin(\\.json|\\.partial)?$').exec(name);
+    if (artifact) {
+        const bound = saved && (kind === 'live' ? saved.artifact_count : saved.artifact_offset);
+        if (!count(Number(artifact[1])) || bound !== null && bound !== undefined && (!count(bound) || Number(artifact[1]) > bound))
+            throw invalid();
+        return artifact[2] === '.json' ? 8192 : 512 * 1024 ** 2;
+    }
+    const event = new RegExp('^(page|event|queue)-' + index + '\\.json$').exec(name);
+    if (event && (kind === 'trial' ? event[1] === 'page' : ['event', 'queue'].includes(event[1]))) {
+        const bound = saved && (event[1] === 'page' ? saved.pages : event[1] === 'event' ? saved.events : saved.queued);
+        if (!count(Number(event[2])) || bound !== null && bound !== undefined && (!count(bound) || Number(event[2]) > bound))
+            throw invalid();
+        return event[1] === 'queue' ? 256 : event[1] === 'page' ? 4 * 1024 ** 2 : 2 * 1024 ** 2;
+    }
+    throw invalid();
+}
+async function privateFile(path, maximumBytes) {
+    const before = await lstat(path, { bigint: true });
+    if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1n || before.mode & 63n || before.size > BigInt(maximumBytes)
+        || process.getuid && before.uid !== BigInt(process.getuid()))
+        throw invalid();
+    const file = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+        const actual = await file.stat({ bigint: true });
+        if (actual.dev !== before.dev || actual.ino !== before.ino || actual.size !== before.size)
+            throw invalid();
+        return actual;
+    }
+    finally {
+        await file.close();
+    }
+}
+async function erase(context, signal, automatic) {
+    if (context.purpose === 'world_session')
+        throw invalid();
+    const use = await lockLocalEvidence(context, context.operation);
+    try {
+        return await withLocalContainerCompletion(context, context.operation, context.purpose, async (saved, containerSignal) => {
+            signal = AbortSignal.any([signal, use.signal, containerSignal]);
+            signal.throwIfAborted();
+            use.assertHeld();
+            const identity = { owner: context.owner, workspace: context.workspace, device: saved.device, job: saved.job, request: saved.request,
+                lease: saved.lease, attempt: saved.attempt, manifest_sha256: saved.manifestSha256, purpose: context.purpose };
+            let policy = await readEvidencePolicy(context, context.operation);
+            if (policy && (!same(policy, identity) || policy.manifest_sha256 !== identity.manifest_sha256 || policy.purpose !== identity.purpose))
+                throw invalid();
+            if (policy?.state === 'removed')
+                return { state: 'removed', already_removed: true, file_count: policy.removed_files };
+            if (automatic && (!policy || policy.expires_at === null))
+                throw new CliError('local_evidence_retention_missing', 'Legacy evidence requires explicit forget; no expiry was invented.');
+            if (automatic && policy?.state === 'retained' && Date.parse(policy.expires_at) > Date.now())
+                return { state: 'kept', already_removed: false, file_count: 0 };
+            const root = await privateDirectory(), suffix = [context.owner, context.workspace, context.operation].map(identifier).join('-');
+            const targets = identity.purpose === 'validation' ? [{ path: join(root, 'evidence-' + suffix), kind: 'validation' }]
+                : [{ path: join(root, 'trial-' + suffix), kind: 'trial' }, { path: join(root, 'trial-live-' + suffix), kind: 'live' }];
+            // Validate headers and cloud synchronization before automatic deletion.
+            // Explicit forget can discard unsynced bytes only after user consent.
+            if (automatic && policy?.state !== 'removing') {
+                const primary = await header(targets[0].path, targets[0].kind, identity, true);
+                if (!primary || identity.purpose === 'validation' && (primary.stage !== 'cloud_retained' || !record(primary.cloud)
+                    || !record(primary.document) || !record(primary.document.receipt)
+                    || primary.cloud.size !== primary.document.receipt.size || primary.cloud.sha256 !== primary.document.receipt.sha256))
+                    throw new CliError('local_evidence_sync_unresolved', 'Expired evidence has no confirmed cloud retention. Use explicit forget to discard it, or inspect original recovery metadata.');
+                if (identity.purpose === 'trial') {
+                    const sync = await privateEvidenceMetadata(join(targets[0].path, 'cloud-receipts.json'));
+                    if (primary.stage !== 'local_collected' || !record(sync) || sync.schema !== 'firedrill.local-trial-sync.v2'
+                        || sync.operation_id !== identity.lease || sync.job_id !== identity.job || sync.manifest_sha256 !== identity.manifest_sha256
+                        || sync.state !== 'cloud_staged' || sync.pending !== null || sync.reports_retained !== primary.pages
+                        || sync.artifacts_retained !== primary.artifacts_retained)
+                        throw new CliError('local_evidence_sync_unresolved', 'Expired drill evidence is not confirmed fully staged in the cloud. It was not automatically discarded.');
+                }
+            }
+            // A durable metadata tombstone prevents any later collector or sync from
+            // recreating data, including after an interrupted or legacy erasure.
+            const first = !policy;
+            policy = policy ?? { ...identity, schema: 'firedrill.local-evidence-policy.v1', expires_at: null, state: 'removing',
+                removed_files: 0, removal_started_at: new Date().toISOString(), finished_at: null, directory_cursor: 0, pending_file: null };
+            policy = { ...policy, state: 'removing', removal_started_at: policy.removal_started_at ?? new Date().toISOString() };
+            // Constant-size parent/header validation only. Individual file validation
+            // is bounded below; no full preflight/history rescan precedes each pass.
+            for (const target of targets) {
+                const held = await directory(target.path);
+                if (!held)
+                    continue;
+                try {
+                    await header(target.path, target.kind, identity, !first);
+                    await held.check();
+                }
+                finally {
+                    await held.close();
+                }
+            }
+            await writeEvidencePolicy(policy, first);
+            let removed = 0, pending = false;
+            for (let position = policy.directory_cursor; position < targets.length; position++) {
+                const target = targets[position];
+                const held = await directory(target.path);
+                if (!held) {
+                    if (policy.pending_file)
+                        throw invalid();
+                    policy.directory_cursor = position + 1;
+                    await writeEvidencePolicy(policy);
+                    continue;
+                }
+                try {
+                    const metadata = await header(target.path, target.kind, identity, true);
+                    const complete = async (intent) => {
+                        signal.throwIfAborted();
+                        use.assertHeld();
+                        await held.check();
+                        if (intent.directory !== target.kind || intent.name === 'receipt.json')
+                            throw invalid();
+                        const path = join(target.path, intent.name), limit = maximum(intent.name, target.kind, metadata);
+                        if (intent.size > limit)
+                            throw invalid();
+                        const actual = await privateFile(path, limit).catch(error => { if (error.code === 'ENOENT')
+                            return null; throw error; });
+                        if (actual && (actual.dev.toString() !== intent.device || actual.ino.toString() !== intent.inode || actual.size !== BigInt(intent.size)))
+                            throw invalid();
+                        if (actual) {
+                            signal.throwIfAborted();
+                            use.assertHeld();
+                            await held.check();
+                            const current = await lstat(path, { bigint: true });
+                            if (current.dev !== actual.dev || current.ino !== actual.ino || current.size !== actual.size || current.isSymbolicLink() || current.nlink !== 1n)
+                                throw invalid();
+                            await unlink(path);
+                        }
+                        await held.sync();
+                        if (!Number.isSafeInteger(policy.removed_files + 1))
+                            throw invalid();
+                        policy.removed_files++;
+                        policy.pending_file = null;
+                        // Durable per-file completion. After a crash, a still-pending exact
+                        // inode is either unlinked once or its absence is reconciled once.
+                        await writeEvidencePolicy(policy);
+                        removed++;
+                    };
+                    if (policy.pending_file)
+                        await complete(policy.pending_file);
+                    for await (const item of await opendir(target.path, { bufferSize: 32 })) {
+                        signal.throwIfAborted();
+                        await held.check();
+                        if (item.name === 'receipt.json')
+                            continue; // Keep recovery metadata until every payload is removed.
+                        if (['sync.lock', 'cloud-sync.lock', 'owner.lock'].includes(item.name))
+                            throw new CliError('local_evidence_owned', 'An original evidence transfer still owns this operation. Its lock was not removed.');
+                        if (removed >= MAX_PASS) {
+                            pending = true;
+                            break;
+                        }
+                        const path = join(target.path, item.name), before = await privateFile(path, maximum(item.name, target.kind, metadata));
+                        policy.pending_file = { directory: target.kind, name: item.name, device: before.dev.toString(), inode: before.ino.toString(), size: Number(before.size) };
+                        signal.throwIfAborted();
+                        use.assertHeld();
+                        await held.check();
+                        await writeEvidencePolicy(policy); // Original intent BEFORE unlink.
+                        await complete(policy.pending_file);
+                    }
+                    if (!pending) {
+                        // Keep the bounded non-secret original summary for closing/hash
+                        // recovery, not raw event/page/artifact bytes. This never restores
+                        // raw access: the permanent removal tombstone fences every reader.
+                        let retainedMetadata = false;
+                        for await (const item of await opendir(target.path, { bufferSize: 32 })) {
+                            if (item.name !== 'receipt.json') {
+                                pending = true;
+                                break;
+                            }
+                            await privateFile(join(target.path, item.name), 65536);
+                            retainedMetadata = true;
+                        }
+                        await held.check();
+                        await held.sync();
+                        if (!pending) {
+                            if (!retainedMetadata)
+                                await rmdir(target.path);
+                            policy.directory_cursor = position + 1;
+                            await writeEvidencePolicy(policy);
+                        }
+                    }
+                    await held.sync();
+                }
+                finally {
+                    await held.close();
+                }
+                if (pending)
+                    break;
+            }
+            if (!pending)
+                policy = { ...policy, state: 'removed', finished_at: new Date().toISOString() };
+            await writeEvidencePolicy(policy);
+            return { state: policy.state, already_removed: false, file_count: policy.removed_files };
+        });
+    }
+    finally {
+        await use.close();
+    }
+}
+export async function forgetLocalEvidence(operation, options, output) {
+    const context = await selected(operation, options);
+    if (context.purpose === 'world_session')
+        return forgetWorldEvidence(operation, options, output);
+    if (!options.approve) {
+        if (options.json || !process.stdin.isTTY || !process.stderr.isTTY)
+            throw new CliError('local_evidence_erasure_consent', 'Use --discard-evidence after reviewing this exact operation. Unsynchronized local evidence cannot be recovered; cloud records are unchanged.', 2);
+        if (!await selectOne('Remove private local evidence for ' + context.operation + '?', [{ value: false, label: 'Keep evidence' },
+            { value: true, label: 'Remove local evidence', detail: 'Unsynchronized bytes cannot be recovered. Original container cleanup metadata and cloud reports remain.' }], options.signal))
+            return output({ state: 'kept', operation_id: context.operation }, 'Private local evidence kept.');
+    }
+    const receipt = await erase(context, options.signal, false);
+    output({ schema: 'firedrill.local-evidence-erasure.v1', operation_id: context.operation, workspace_id: context.workspace,
+        purpose: context.purpose, ...receipt, cloud_data_changed: false, filesystem_backup_erasure_attested: false }, receipt.state === 'removing' ? 'A bounded evidence removal pass finished. Repeat this exact forget command to continue. Cloud records are unchanged.'
+        : 'Exact private evidence bytes removed. Non-secret original recovery metadata and cloud records are unchanged. Filesystem backups are not covered.');
+}
+export async function inspectLocalEvidence(operation, options, output) {
+    const context = await selected(operation, { ...options, approve: false });
+    if (context.purpose === 'world_session')
+        return output({ operation_id: context.operation, purpose: context.purpose,
+            metadata_only: true, cloud_data_changed: false }, 'Manual-world evidence uses its original encrypted journal. Inspect its saved session or exact forget command.');
+    const policy = await readEvidencePolicy(context, context.operation);
+    output({ operation_id: context.operation, purpose: context.purpose, workspace_id: context.workspace, metadata_only: true,
+        policy: policy ? { state: policy.state, expires_at: policy.expires_at, removed_files: policy.removed_files, finished_at: policy.finished_at,
+            directory_cursor: policy.directory_cursor, pending_file: policy.pending_file ? { directory: policy.pending_file.directory, name: policy.pending_file.name } : null } : null,
+        retention_state: !policy ? 'legacy_policy_missing' : policy.state !== 'retained' ? policy.state : policy.expires_at === null
+            ? 'legacy_policy_missing' : Date.parse(policy.expires_at) <= Date.now() ? 'expired' : 'within_policy', cloud_data_changed: false }, !policy ? 'Older private evidence has no frozen retention policy. Raw reads and uploads are disabled. Explicit forget remains available after original cleanup.'
+        : `Private evidence: ${policy.state}; expiry ${policy.expires_at ?? 'not established'}. ${policy.state === 'removing' ? 'Continue the same original forget command. ' : ''}This metadata does not establish cloud retention or target outcome.`);
+}
+export async function pruneLocalEvidence(options, output) {
+    // Preserve the established encrypted manual-world path, then reconcile only
+    // validation/trial originals with finite policy and confirmed cleanup/sync.
+    await pruneWorldEvidence(options, output);
+    let inspected = 0, removed = 0, kept = 0, deferred = 0;
+    for await (const context of localEvidenceContexts(undefined, options.workspace, (operation, code) => {
+        deferred++;
+        output({ state: 'deferred', operation_id: operation, code, metadata_only: true }, `${operation}: ${code}. Nothing was removed.`);
+    }, options.signal)) {
+        if (context.purpose === 'world_session')
+            continue;
+        options.signal.throwIfAborted();
+        inspected++;
+        try {
+            const result = await erase(context, options.signal, true);
+            if (result.state === 'kept')
+                kept++;
+            else if (result.state === 'removed')
+                removed++;
+            else
+                deferred++;
+            if (result.state !== 'kept')
+                output({ operation_id: context.operation, purpose: context.purpose, ...result, cloud_data_changed: false }, `${context.operation}: ${result.state}. Cloud records and cleanup metadata are unchanged.`);
+        }
+        catch (error) {
+            if (!(error instanceof CliError) && error.code !== 'ENOENT')
+                throw error;
+            deferred++;
+            const code = error instanceof CliError ? error.code : 'local_evidence_sync_unresolved';
+            output({ operation_id: context.operation, state: 'deferred', code, metadata_only: true }, `${context.operation}: ${code}. Removal is not confirmed complete. Inspect its original metadata; cloud records are unchanged.`);
+        }
+        if (inspected % 250 === 0)
+            output({ schema: 'firedrill.local-evidence-prune-progress.v1', inspected, removed, kept, deferred }, `Inspected ${inspected} original local receipts using bounded metadata batches.`);
+    }
+    output({ schema: 'firedrill.local-evidence-prune.v1', inspected, removed, kept, deferred, bounded: true,
+        cloud_data_changed: false, filesystem_backup_erasure_attested: false }, `Validation/drill evidence: ${removed} removed, ${kept} within policy, ${deferred} require explicit attention. Interrupted bounded removals can continue with the same original operation.`);
+}

package/dist/cli/src/runner-evidence-privacy.js

@@ -0,0 +1,37 @@
+import { CliError } from './http.js';
+/** Transient comparison values only. Never persist these buffers in a journal. */
+export function evidenceNeedles(configuration) {
+    const values = new Set(), names = configuration.control.secret_variable_names;
+    if (!Array.isArray(names) || names.some(name => typeof name !== 'string'))
+        throw new CliError('local_evidence_invalid', 'The evidence privacy policy is unavailable.');
+    for (const phase of ['build', 'runtime'])
+        for (const name of names) {
+            const value = configuration.target_phases[phase][String(name)];
+            if (value)
+                values.add(value);
+        }
+    for (const item of configuration.model_channels)
+        values.add(item.token);
+    for (const item of configuration.voice_channels)
+        values.add(item.token);
+    for (const item of configuration.real_channels) {
+        values.add(item.token);
+        for (const marker of Object.values(item.markers))
+            values.add(marker);
+    }
+    if (configuration.participant_channel)
+        values.add(configuration.participant_channel.token);
+    const result = [];
+    for (const value of values) {
+        const quoted = JSON.stringify(value).slice(1, -1);
+        for (const item of [value, quoted, quoted.replace(/[\u007f-\uffff]/g, char => '\\u' + char.charCodeAt(0).toString(16).padStart(4, '0')),
+            Buffer.from(value).toString('base64')])
+            result.push(Buffer.from(item));
+    }
+    return result.filter(item => item.length);
+}
+export function assertEvidencePrivacy(body, blocked) {
+    if (blocked.some(value => body.includes(value)) || /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----|\b(?:sk-ant-api\d+-|gh[pousr]_|github_pat_|xox[baprs]-)[A-Za-z0-9_-]{16,}/.test(body.toString('latin1'))) {
+        throw new CliError('local_evidence_private_value', 'A private value was found in evidence. It was not uploaded.');
+    }
+}

package/dist/cli/src/runner-evidence-retention.js

@@ -0,0 +1,161 @@
+import { constants } from 'node:fs';
+import { lstat, open, rename } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { privateDirectory } from './credentials.js';
+import { CliError } from './http.js';
+import { identifier } from './world-contracts.js';
+import { processLifetimeLock } from './runner-process-lock.js';
+const HASH = /^[a-f0-9]{64}$/;
+const fail = () => new CliError('local_evidence_retention_invalid', 'This operation’s private evidence policy could not be confirmed. No evidence was read, uploaded or removed.');
+const missing = () => new CliError('local_evidence_retention_missing', 'This older local evidence has no frozen retention policy. Only metadata inspection and explicit runner evidence forget are available; no new expiry or upload authority was invented.');
+const expired = () => new CliError('local_evidence_expired', 'Local evidence retention ended. Use runner evidence forget for this exact operation. No target is run to reconstruct it.');
+const object = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const date = (value) => typeof value === 'string' && Number.isSafeInteger(Date.parse(value));
+const identity = (value) => {
+    for (const key of ['owner', 'workspace', 'device', 'job', 'request', 'lease', 'attempt'])
+        identifier(value[key]);
+    if (!['validation', 'trial'].includes(value.purpose) || !HASH.test(value.manifest_sha256))
+        throw fail();
+    return value;
+};
+const same = (left, right) => ['owner', 'workspace', 'device', 'job', 'request', 'lease', 'attempt', 'purpose', 'manifest_sha256']
+    .every(key => left[key] === right[key]);
+const prefix = (scope, operation) => [identifier(scope.owner), identifier(scope.workspace), identifier(operation)].join('-');
+const policyPath = async (scope, operation) => join(await privateDirectory(), `evidence-policy-${prefix(scope, operation)}.json`);
+/** Metadata files never contain target evidence, credentials or customer paths. */
+export async function privateEvidenceMetadata(path, maximum = 65536) {
+    const before = await lstat(path);
+    if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1 || before.mode & 0o077 || before.size > maximum
+        || process.getuid && before.uid !== process.getuid())
+        throw fail();
+    const file = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+        const actual = await file.stat();
+        if (actual.dev !== before.dev || actual.ino !== before.ino || actual.size !== before.size)
+            throw fail();
+        const body = await file.readFile('utf8'), after = await file.stat();
+        if (actual.size !== after.size || actual.mtimeMs !== after.mtimeMs || actual.ctimeMs !== after.ctimeMs)
+            throw fail();
+        return JSON.parse(body);
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            throw error;
+        throw fail();
+    }
+    finally {
+        await file.close();
+    }
+}
+export function frozenEvidenceRetention(owner, manifest, expiresAt) {
+    if (!date(expiresAt))
+        throw missing();
+    const value = { schema: 'firedrill.local-evidence-retention.v1', owner: owner.owner, workspace: owner.workspace,
+        device: owner.device, job: owner.job, request: owner.request, lease: owner.lease, attempt: owner.attempt, purpose: owner.purpose,
+        manifest_sha256: manifest, expires_at: expiresAt };
+    identity(value);
+    assertEvidenceRetentionCurrent(value);
+    return value;
+}
+export function assertEvidenceRetentionCurrent(value) {
+    identity(value);
+    if (value.schema !== 'firedrill.local-evidence-retention.v1' || !date(value.expires_at))
+        throw missing();
+    if (Date.parse(value.expires_at) <= Date.now())
+        throw expired();
+}
+export function evidenceRetentionSignal(value, signal) {
+    assertEvidenceRetentionCurrent(value);
+    return AbortSignal.any([signal, AbortSignal.timeout(Math.max(1, Math.min(2147483647, Date.parse(value.expires_at) - Date.now())))]);
+}
+export function retentionMatches(value, expected) {
+    return object(value) && Object.keys(value).sort().join(',') === 'attempt,device,expires_at,job,lease,manifest_sha256,owner,purpose,request,schema,workspace'
+        && value.schema === expected.schema && value.expires_at === expected.expires_at && same(value, expected);
+}
+export async function readEvidencePolicy(scope, operation) {
+    const path = await policyPath(scope, operation);
+    const value = await privateEvidenceMetadata(path).catch(error => { if (error.code === 'ENOENT')
+        return null; throw error; });
+    if (value === null)
+        return null;
+    if (!object(value) || Object.keys(value).sort().join(',') !== 'attempt,device,directory_cursor,expires_at,finished_at,job,lease,manifest_sha256,owner,pending_file,purpose,removal_started_at,removed_files,request,schema,state,workspace'
+        || value.schema !== 'firedrill.local-evidence-policy.v1' || value.owner !== scope.owner || value.workspace !== scope.workspace || value.lease !== operation
+        || !['retained', 'removing', 'removed'].includes(String(value.state)) || value.expires_at !== null && !date(value.expires_at)
+        || value.removal_started_at !== null && !date(value.removal_started_at) || value.finished_at !== null && !date(value.finished_at)
+        || !Number.isSafeInteger(value.removed_files) || Number(value.removed_files) < 0
+        || !Number.isSafeInteger(value.directory_cursor) || Number(value.directory_cursor) < 0
+        || Number(value.directory_cursor) > (value.purpose === 'validation' ? 1 : 2)
+        || value.pending_file !== null && (!object(value.pending_file)
+            || Object.keys(value.pending_file).sort().join(',') !== 'device,directory,inode,name,size'
+            || !['validation', 'trial', 'live'].includes(String(value.pending_file.directory))
+            || typeof value.pending_file.name !== 'string' || value.pending_file.name.length > 128 || /[\\/\0]/.test(value.pending_file.name)
+            || typeof value.pending_file.device !== 'string' || !/^[0-9]{1,32}$/.test(value.pending_file.device)
+            || typeof value.pending_file.inode !== 'string' || !/^[0-9]{1,32}$/.test(value.pending_file.inode)
+            || !Number.isSafeInteger(value.pending_file.size) || Number(value.pending_file.size) < 0 || Number(value.pending_file.size) > 512 * 1024 ** 2)
+        || value.state === 'retained' && (value.expires_at === null || value.removal_started_at !== null || value.finished_at !== null)
+        || value.state === 'retained' && (value.pending_file !== null || value.directory_cursor !== 0)
+        || value.state === 'removed' && (value.pending_file !== null || value.directory_cursor !== (value.purpose === 'validation' ? 1 : 2))
+        || value.state !== 'retained' && !date(value.removal_started_at) || value.state === 'removed' && !date(value.finished_at))
+        throw fail();
+    identity(value);
+    return value;
+}
+export async function writeEvidencePolicy(value, initial = false) {
+    identity(value);
+    const path = await policyPath(value, value.lease), pending = initial ? path : path + '.' + randomUUID() + '.tmp';
+    const file = await open(pending, 'wx', 0o600);
+    try {
+        await file.writeFile(JSON.stringify(value));
+        await file.sync();
+    }
+    finally {
+        await file.close();
+    }
+    if (!initial)
+        await rename(pending, path);
+    const parent = await open(await privateDirectory(), constants.O_RDONLY | (constants.O_DIRECTORY ?? 0));
+    try {
+        await parent.sync();
+    }
+    finally {
+        await parent.close();
+    }
+}
+/** Shared kernel ownership across collectors, sync and erasure. Persistent
+ * metadata files do not imply ownership after the broker process has exited. */
+export async function lockLocalEvidence(scope, operation) {
+    return processLifetimeLock(join(await privateDirectory(), `evidence-use-${prefix(scope, operation)}.lock`));
+}
+export async function acquireLocalEvidence(scope, operation, initialize) {
+    const lock = await lockLocalEvidence(scope, operation);
+    try {
+        let saved = await readEvidencePolicy(scope, operation);
+        if (!saved && initialize) {
+            if (initialize.owner !== scope.owner || initialize.workspace !== scope.workspace || initialize.lease !== operation)
+                throw fail();
+            assertEvidenceRetentionCurrent(initialize);
+            saved = { ...initialize, schema: 'firedrill.local-evidence-policy.v1', state: 'retained', removed_files: 0,
+                removal_started_at: null, finished_at: null, directory_cursor: 0, pending_file: null };
+            await writeEvidencePolicy(saved, true);
+        }
+        if (!saved)
+            throw missing();
+        if (saved.state !== 'retained')
+            throw new CliError('local_evidence_removal_started', 'Private evidence removal was already requested for this operation. Continue the exact forget command; no files were recreated.');
+        if (initialize && (!same(saved, initialize) || saved.expires_at !== initialize.expires_at))
+            throw fail();
+        if (!date(saved.expires_at))
+            throw missing();
+        const retention = { schema: 'firedrill.local-evidence-retention.v1', owner: saved.owner, workspace: saved.workspace,
+            device: saved.device, job: saved.job, request: saved.request, lease: saved.lease, attempt: saved.attempt, purpose: saved.purpose,
+            manifest_sha256: saved.manifest_sha256, expires_at: saved.expires_at };
+        assertEvidenceRetentionCurrent(retention);
+        lock.assertHeld();
+        return { retention, signal: lock.signal, assertCurrent: () => { lock.assertHeld(); assertEvidenceRetentionCurrent(retention); }, close: lock.close };
+    }
+    catch (error) {
+        await lock.close();
+        throw error;
+    }
+}