firedrill-run 2.2.4 → 3.0.0

package/dist/cli/src/world-creation.js

@@ -0,0 +1,201 @@
+import { randomUUID } from 'node:crypto';
+import { open } from 'node:fs/promises';
+import { join } from 'node:path';
+import { api } from './auth.js';
+import { privateDirectory } from './credentials.js';
+import { CliError, releaseClosed } from './http.js';
+import { choosePaged, interactive } from './configuration.js';
+import { selectOne, terminalText } from './prompts.js';
+import { ownedSourceMetadataFile, readSourceMetadata, writeSourceMetadata } from './source-connection.js';
+import { withBootstrapProcessLock } from './bootstrap-process-lock.js';
+import { selectedWorkspace } from './world-access.js';
+import { identifier } from './world-contracts.js';
+const invalid = () => new CliError('world_creation_unconfirmed', 'The original world request needs attention. No replacement world or build was started.', 2);
+const location = async (scope, key) => join(await privateDirectory(), `world-create-${identifier(scope.owner)}-${identifier(scope.workspace)}-${identifier(key)}.json`);
+const activeLocation = async (scope, agent) => join(await privateDirectory(), `world-create-active-${identifier(scope.owner)}-${identifier(scope.workspace)}-${identifier(agent)}.json`);
+const access = (scope, signal) => ({ actor: scope.owner, workspace: scope.workspace, signal });
+const base = (intent) => `/api/workspaces/${intent.workspace}/agents/${intent.agent}`;
+const body = (intent) => ({ actor_id: intent.owner, source_id: intent.source });
+const requestPath = (intent) => `${base(intent)}/world-requests/${intent.key}`;
+async function readFile(path) {
+    const file = await ownedSourceMetadataFile(path, 4096);
+    try {
+        return await readSourceMetadata(file, 4096);
+    }
+    finally {
+        await file.close();
+    }
+}
+async function retained(scope, key) {
+    const value = await readFile(await location(scope, key));
+    if (!value || value.schema !== 'firedrill.local-world-creation.v1' || value.owner !== scope.owner
+        || value.workspace !== scope.workspace || value.key !== identifier(key) || typeof value.dispatched !== 'boolean'
+        || Object.keys(value).sort().join(',') !== 'agent,dispatched,key,owner,schema,source,workspace')
+        throw invalid();
+    identifier(value.agent);
+    identifier(value.source);
+    return value;
+}
+async function active(scope, agent) {
+    let value;
+    try {
+        value = await readFile(await activeLocation(scope, agent));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+    if (!value || value.schema !== 'firedrill.local-world-active.v1' || value.owner !== scope.owner
+        || value.workspace !== scope.workspace || value.agent !== agent || typeof value.key !== 'string'
+        || Object.keys(value).sort().join(',') !== 'agent,key,owner,schema,workspace')
+        throw invalid();
+    return retained(scope, identifier(value.key));
+}
+async function saveNew(intent) {
+    try {
+        const file = await open(await location(intent, intent.key), 'wx', 0o600);
+        try {
+            await file.writeFile(JSON.stringify(intent));
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        const original = await retained(intent, intent.key);
+        if (original.agent !== intent.agent || original.source !== intent.source)
+            throw invalid();
+        intent.dispatched = original.dispatched;
+    }
+    await writeSourceMetadata(await activeLocation(intent, intent.agent), { schema: 'firedrill.local-world-active.v1',
+        owner: intent.owner, workspace: intent.workspace, agent: intent.agent, key: intent.key });
+}
+function checked(value, intent) {
+    if (!value || value.schema !== 'firedrill.world-creation.v1' || value.actor_id !== intent.owner
+        || value.workspace_id !== intent.workspace || value.agent_id !== intent.agent || value.source_id !== intent.source
+        || value.request_key !== intent.key || !['not_received', 'accepted', 'withdrawn'].includes(value.state)
+        || typeof value.resource_available !== 'boolean'
+        || value.state === 'accepted' && (!value.world_id || identifier(value.world_id) !== value.world_id)
+        || value.state !== 'accepted' && (value.world_id !== null || value.resource_available)
+        || (value.resource_available ? value.detail_url !== `/worlds/${value.world_id}` : value.detail_url !== null))
+        throw invalid();
+    return value;
+}
+async function lookup(intent, signal) {
+    return checked(await api(`${requestPath(intent)}?${new URLSearchParams(body(intent))}`, access(intent, signal)), intent);
+}
+function show(value, output) {
+    output(value, value.state === 'accepted' && value.resource_available
+        ? `World created: ${value.world_id}\nInspect it with firedrill worlds ${value.world_id}. No build or simulation started.`
+        : value.state === 'accepted' ? 'The original world is no longer available. No replacement was created.'
+            : value.state === 'withdrawn' ? 'The unsent world request was withdrawn. A delayed request cannot create it.'
+                : `World request ${value.request_key} is not yet confirmed. It may still arrive.\nCheck: firedrill worlds creation ${value.request_key}`);
+}
+async function approve(options, label, confirmLabel = 'Create world') {
+    if (options.approve)
+        return;
+    if (!interactive(options))
+        throw new CliError('world_creation_approval_required', 'Review the agent source and use --approve-change to create a world. No build or simulation will start.', 2);
+    if (!await selectOne(label, [{ value: false, label: 'Cancel' }, { value: true, label: confirmLabel }], options.signal))
+        throw new CliError('canceled', 'No world request was submitted.', 130);
+}
+async function submit(intent, options, output, explicitContinuation = false) {
+    let current = await lookup(intent, options.signal);
+    if (current.state !== 'not_received') {
+        show(current, output);
+        return current;
+    }
+    if (intent.dispatched && !explicitContinuation) {
+        show(current, output);
+        throw new CliError('world_creation_pending', `Inspect or continue the original request with firedrill worlds continue-creation ${intent.key}. No request was repeated.`, 2);
+    }
+    intent.dispatched = true;
+    await writeSourceMetadata(await location(intent, intent.key), intent);
+    output({ phase: 'world_request_prepared', request_key: intent.key, agent_id: intent.agent, source_id: intent.source }, `World request ${intent.key}. Recovery: firedrill worlds creation ${intent.key}.`);
+    try {
+        current = checked(await api(`${base(intent)}/worlds`, { ...access(intent, options.signal),
+            method: 'POST', body: body(intent), idempotencyKey: intent.key }), intent);
+    }
+    catch (error) {
+        if (options.signal.aborted || releaseClosed(error))
+            throw error;
+        // A lost write response permits a read of the same intent, not another POST.
+        current = await lookup(intent, options.signal);
+        if (current.state === 'not_received') {
+            show(current, output);
+            throw new CliError('world_creation_pending', `Creation is not confirmed. Check the original request ${intent.key}; do not start a replacement.`, 2);
+        }
+    }
+    show(current, output);
+    return current;
+}
+export async function createWorld(options, output, selectedAgent, scope) {
+    const context = scope ?? await selectedWorkspace({ ...options, interactive: interactive(options) });
+    let agentId = selectedAgent ? identifier(selectedAgent) : undefined;
+    if (!agentId && interactive(options))
+        agentId = (await choosePaged('Agent', `/api/workspaces/${context.workspace}/agents`, context, options, row => ({ label: row.name, detail: row.source_label })))?.id;
+    if (!agentId)
+        throw new CliError('agent_required', 'Use worlds new <agent> or select a saved agent interactively.', 2);
+    const agent = identifier(agentId);
+    return withBootstrapProcessLock(join(await privateDirectory(), `world-create-lock-${context.owner}-${context.workspace}-${agent}`), options.signal, async (signal) => {
+        const currentOptions = { ...options, signal };
+        const previous = options.request ? await retained(context, identifier(options.request)).catch(error => {
+            if (error.code === 'ENOENT')
+                return null;
+            throw error;
+        }) : await active(context, agent);
+        if (previous) {
+            if (previous.agent !== agent)
+                throw invalid();
+            const receipt = await lookup(previous, signal);
+            if (receipt.state === 'not_received')
+                return submit(previous, currentOptions, output);
+            if (options.request || !interactive(options)) {
+                show(receipt, output);
+                return receipt;
+            }
+            const next = await selectOne('World', [{ value: 'existing', label: receipt.resource_available ? 'Continue with the existing world' : 'Show the original request' },
+                { value: 'new', label: 'Create another world', detail: 'Separate state using the agent’s current source.' }], signal);
+            if (next === 'existing') {
+                show(receipt, output);
+                return receipt;
+            }
+        }
+        const saved = await api(`/api/workspaces/${context.workspace}/agents/${agent}`, access(context, signal));
+        if (saved.id !== agent || !saved.source?.id)
+            throw new CliError('agent_source_required', 'This agent has no connected source. Finish its source connection first.', 2);
+        const source = identifier(saved.source.id);
+        await approve(currentOptions, `Create a world for ${terminalText(saved.name)}? Source: ${terminalText(saved.source.label)} · ${terminalText(saved.source.revision)}. No build starts.`);
+        const intent = { ...context, schema: 'firedrill.local-world-creation.v1', key: options.request ? identifier(options.request) : randomUUID(),
+            agent, source, dispatched: false };
+        await saveNew(intent);
+        return submit(intent, currentOptions, output);
+    });
+}
+export async function worldCreationCommand(args, options, output) {
+    if (args.length !== 2 || !['creation', 'continue-creation', 'withdraw-creation'].includes(args[0]) || options.request)
+        throw invalid();
+    const scope = await selectedWorkspace({ ...options, interactive: interactive(options) });
+    const key = identifier(args[1]), original = await retained(scope, key);
+    return withBootstrapProcessLock(join(await privateDirectory(), `world-create-lock-${scope.owner}-${scope.workspace}-${original.agent}`), options.signal, async (signal) => {
+        const currentOptions = { ...options, signal }, intent = await retained(scope, key);
+        const value = await lookup(intent, signal);
+        if (args[0] === 'creation' || value.state !== 'not_received') {
+            show(value, output);
+            return value;
+        }
+        await approve(currentOptions, args[0] === 'continue-creation' ? 'Continue the exact original world request?' : 'Withdraw the unsent world request?', args[0] === 'continue-creation' ? 'Continue original request' : 'Withdraw request');
+        if (args[0] === 'continue-creation')
+            return submit(intent, currentOptions, output, true);
+        const withdrawn = checked(await api(requestPath(intent), { ...access(scope, signal), method: 'DELETE', body: body(intent) }), intent);
+        const observed = await lookup(intent, signal);
+        if (withdrawn.state !== observed.state || withdrawn.world_id !== observed.world_id)
+            throw invalid();
+        show(observed, output);
+        return observed;
+    });
+}

package/dist/cli/src/world-datasets.js

@@ -0,0 +1,207 @@
+import { randomUUID } from 'node:crypto';
+import { createInterface } from 'node:readline/promises';
+import { api } from './auth.js';
+import { CliError } from './http.js';
+import { selectOne, terminalText } from './prompts.js';
+import { datasetRecipeFile } from './tool-datasets.js';
+import { identifier } from './world-contracts.js';
+import { selectedWorld } from './world-access.js';
+import { exportDataset } from './dataset-export.js';
+import { datasetReads } from './dataset-reads.js';
+import { datasetRead, datasetMatches, datasetEdits } from './dataset-contracts.js';
+import { worldSessionMatches, worldSessionRequestMatches, worldSessionsPageMatches } from '../../contracts/session-contracts.js';
+const text = (row) => `${row.id}  ${terminalText(row.name)} · version ${row.version} · ${row.state}\n${row.edit_count} saved edits`
+    + (row.problem ? '\n' + terminalText(row.problem) : '') + '\nSaving edits does not change a running world.';
+async function question(title, signal) {
+    const prompt = createInterface({ input: process.stdin, output: process.stderr, terminal: false });
+    try {
+        return (await prompt.question(title, { signal })).trim();
+    }
+    finally {
+        prompt.close();
+    }
+}
+export async function worldDatasetCommand(args, options, output) {
+    const action = args[0] ?? 'list', save = action === 'save', start = action === 'start', write = save || start || action === 'withdraw';
+    // Opening a managed world session is retired (FIR-504); start-status still reads an original opening request.
+    if (start)
+        throw new CliError('legacy_launch_retired', 'Opening a managed world session is retired. Saved dataset versions and original opening requests (datasets start-status) stay readable. Nothing was sent.', 2);
+    if (!['list', 'show', 'document', 'export', 'request', 'save', 'withdraw', 'start', 'start-status'].includes(action) || args.length > (save ? 3 : 2)
+        || !save && options.file !== undefined || !save && !start && options.request !== undefined || !write && options.approve !== undefined
+        || action !== 'export' && (options.into !== undefined || options.approveDownload !== undefined)
+        || action !== 'list' && (options.page !== undefined || options.search !== undefined)
+        || options.page !== undefined && !/^[1-9][0-9]{0,8}$/.test(options.page) || (options.search?.length ?? 0) > 200) {
+        throw new CliError('arguments_invalid', 'Use datasets list [capture], show|document <version>, export [version] --into <file.json>, request <request>, save [capture] [name] --file <edits.json>, withdraw <version>, start [version], or start-status <request>.', 2);
+    }
+    const tty = !options.json && Boolean(process.stdin.isTTY && process.stderr.isTTY);
+    const scope = await selectedWorld({ ...options, interactive: tty });
+    const auth = { actor: scope.owner, workspace: scope.workspace, signal: options.signal };
+    const identity = { actor: scope.owner, workspace: scope.workspace, world: scope.world };
+    const reads = datasetReads(scope.prefix, scope, options.signal), selectedScope = { ...identity, kind: 'world' };
+    if (action === 'export')
+        return exportDataset(scope.prefix, args[1], scope, options, output);
+    const showSession = (row) => output('world_dataset_session', row, `Session: ${row.id}\n${terminalText(row.state)}\n`
+        + (row.starting_data ? `${row.starting_data.edit_count} starting-data edits applied at ${row.starting_data.applied_at}; ${row.starting_data.rows_affected} rows directly affected.`
+            : 'Starting-data application has not been confirmed.') + (row.problem ? '\n' + terminalText(row.problem) : ''));
+    if (action === 'start-status') {
+        const key = identifier(args[1] ?? '');
+        const result = await api(`${scope.prefix}/runtime-session-request?request_key=${key}`, auth);
+        if (!worldSessionRequestMatches(result, identity, key))
+            throw new CliError('world_session_recovery_unavailable', 'The original request could not be confirmed. No session was started.', 2);
+        output('world_dataset_session_request', result, `Request: ${key}\n${terminalText(result.state)}`);
+        if (result.session)
+            showSession(result.session);
+        return;
+    }
+    if (start) {
+        let id = args[1];
+        if (!id && tty) {
+            let page = 1;
+            while (!id) {
+                const result = await reads.page({ startable: true, page });
+                const choices = result.results.filter(one => one.kind === 'world' && one.can_start_session).map(one => ({ value: one.id,
+                    label: `${one.name} · Version ${one.version}`, detail: `${one.edit_count} starting-data edits` }));
+                choices.unshift({ value: 'cancel', label: 'Cancel', detail: 'No session will be opened.' });
+                if (page > 1)
+                    choices.push({ value: 'previous', label: 'Previous page', detail: '' });
+                if (result.next)
+                    choices.push({ value: 'next', label: 'Next page', detail: '' });
+                const choice = await selectOne('Starting data for a managed world session', choices, options.signal);
+                if (choice === 'cancel')
+                    throw new CliError('canceled', 'No world session was opened.', 130);
+                if (choice === 'next')
+                    page += 1;
+                else if (choice === 'previous')
+                    page -= 1;
+                else
+                    id = identifier(choice);
+            }
+        }
+        id = identifier(id ?? '');
+        const key = identifier(options.request ?? randomUUID());
+        if (options.request) {
+            const receipt = await api(`${scope.prefix}/runtime-session-request?request_key=${key}`, auth);
+            if (!worldSessionRequestMatches(receipt, identity, key) || receipt.withdrawn || receipt.session && receipt.session.dataset_id !== id)
+                throw new CliError('world_session_recovery_unavailable', 'The original request is withdrawn or belongs to different data. No replacement was started.', 2);
+            if (receipt.session) {
+                identifier(receipt.session.id);
+                showSession(receipt.session);
+                return;
+            }
+            if (receipt.state !== 'not_observed')
+                throw new CliError('world_session_pending', `Inspect datasets start-status ${key} before retrying. No replacement was started.`, 2);
+        }
+        const dataset = await reads.detail(id);
+        if (dataset.kind !== 'world' || !dataset.available || !dataset.can_start_session)
+            throw new CliError('world_dataset_base_changed', 'Choose retained starting data for this exact prepared world. No session was opened.', 2);
+        const current = await api(`${scope.prefix}/runtime-sessions?state=active&page_size=1`, auth);
+        if (!worldSessionsPageMatches(current, identity, 'active'))
+            throw new CliError('world_session_scope_invalid', 'The current opening scope could not be confirmed. No session was queued.', 2);
+        if (current.opening_restriction) {
+            throw new CliError('world_session_opening_restricted', terminalText(current.opening_restriction), 2);
+        }
+        const selected = current.opening_scope;
+        if (!selected || !Number.isSafeInteger(selected.world_revision) || selected.world_revision < 1
+            || !Number.isSafeInteger(selected.configuration_revision) || selected.configuration_revision < 0
+            || !Number.isSafeInteger(selected.duration_seconds) || selected.duration_seconds < 1 || selected.duration_seconds > 2147483647
+            || selected.real_connections_count !== 0 || typeof selected.source_revision !== 'string' || !selected.source_revision.length) {
+            throw new CliError('world_session_scope_invalid', 'The current isolated world and starting-data scope could not be confirmed. No session was opened.', 2);
+        }
+        output('world_dataset_session_scope', { world_id: scope.world, dataset_id: id, name: dataset.name, version: dataset.version,
+            duration_seconds: selected.duration_seconds, real_connections_count: 0 }, `${terminalText(dataset.name)} · Version ${dataset.version}\nManaged session: ${selected.duration_seconds} seconds. Startup uses the agent's approved runtime. No real tool accounts are included.`);
+        const approved = options.approve || tty && await selectOne('Open a managed world session?', [{ value: false, label: 'Cancel' }, { value: true, label: 'Open session with saved data' }], options.signal);
+        if (!approved)
+            throw new CliError('dataset_consent_required', 'Use --approve-dataset to open a managed session with this saved data. No session was queued.', 2);
+        const body = { world_revision: selected.world_revision, configuration_revision: selected.configuration_revision,
+            source_id: identifier(selected.source_id), source_revision: selected.source_revision, duration_seconds: selected.duration_seconds, dataset_id: id };
+        output('world_dataset_session_intent', { request_key: key, world_id: scope.world, dataset_id: id }, `Request: ${key}\nIf interrupted, use datasets start-status ${key}. Do not submit a replacement request.`);
+        const row = await api(`${scope.prefix}/runtime-sessions`, { ...auth, method: 'POST', idempotencyKey: key, body });
+        if (!worldSessionMatches(row, identity, { key, body })) {
+            throw new CliError('world_session_acceptance_unconfirmed', `Read datasets start-status ${key}. The returned session identity could not be confirmed.`, 2);
+        }
+        const receipt = await api(`${scope.prefix}/runtime-session-request?request_key=${key}`, auth);
+        if (!worldSessionRequestMatches(receipt, identity, key, body) || receipt.withdrawn || !receipt.session || receipt.session.id !== row.id)
+            throw new CliError('world_session_acceptance_unconfirmed', `Read datasets start-status ${key}. Original acceptance could not be confirmed.`, 2);
+        showSession(receipt.session);
+        return;
+    }
+    if (action === 'list') {
+        const result = await reads.page({ page: Number(options.page ?? 1), query: options.search, source: args[1] ? identifier(args[1]) : undefined });
+        output('world_datasets', result, (result.results.map(text).join('\n\n') || 'No matching datasets in this world.')
+            + `\nPage ${result.page}, ${result.count} matching datasets.${result.next ? ` Use --page ${result.page + 1} with the same capture and search to continue.` : ''}`);
+        return;
+    }
+    if (['show', 'document', 'request'].includes(action)) {
+        const key = identifier(args[1] ?? ''), document = action === 'document';
+        const row = action === 'request' ? await reads.original(key) : await reads.detail(key);
+        if (document) {
+            const value = await reads.document(row);
+            output('world_dataset_document', value, JSON.stringify(value, null, 2));
+        }
+        else
+            output('world_dataset', row, text(row));
+        return;
+    }
+    if (action === 'withdraw') {
+        const key = identifier(args[1] ?? ''), row = await reads.detail(key);
+        const approved = options.approve || tty && await selectOne(`Withdraw ${terminalText(row.name)} version ${row.version}? Other versions and running worlds stay unchanged.`, [{ value: false, label: 'Cancel' }, { value: true, label: 'Withdraw version' }], options.signal);
+        if (!approved)
+            throw new CliError('dataset_consent_required', 'Use --approve-dataset to withdraw this exact version. No change was submitted.', 2);
+        const result = await api(`${scope.prefix}/datasets/${key}`, { ...auth, method: 'DELETE' });
+        datasetRead(result, datasetMatches(result, selectedScope, { id: key, digest: row.request_digest, withdrawn: true }));
+        output('world_dataset', result, text(result));
+        return;
+    }
+    let capture = args[1];
+    if (!capture) {
+        const world = await api(`${scope.prefix}/preparation`, auth);
+        if (!world.starting_data.available || !world.starting_data.id)
+            throw new CliError('world_dataset_base_unavailable', 'This world has no retained starting-data capture. No file was uploaded.', 2);
+        capture = world.starting_data.id;
+    }
+    capture = identifier(capture);
+    const name = args[2] ?? (tty ? await question('Dataset name: ', options.signal) : '');
+    if (!name || name !== name.trim() || name.length > 120 || /[\u0000-\u001f\u007f-\u009f]/.test(name))
+        throw new CliError('world_dataset_name_required', 'Provide a dataset name of up to 120 characters.', 2);
+    const path = options.file ?? (tty ? await question('Dataset edits JSON path: ', options.signal) : '');
+    if (!path)
+        throw new CliError('world_dataset_file_required', 'Provide --file <edits.json>. No file was read or uploaded.', 2);
+    const catalog = await reads.page({ source: capture });
+    const maximum = catalog.capacity?.recipe_bytes;
+    if (!Number.isSafeInteger(maximum) || maximum < 1 || maximum > 8 * 1024 * 1024)
+        throw new CliError('world_dataset_capacity_invalid', 'Dataset transport capacity is unavailable. No file was read.', 2);
+    const input = await datasetRecipeFile(path, maximum, options.signal);
+    let edits = input, previous = null;
+    if (input && typeof input === 'object' && !Array.isArray(input)) {
+        const value = input;
+        if (value.schema === 'firedrill.world-dataset.v1') {
+            if (value.world_id !== scope.world || value.observation_id !== capture)
+                throw new CliError('world_dataset_base_invalid', 'This export belongs to different starting data. No edits were submitted.', 2);
+            edits = value.edits;
+        }
+        else if (Object.keys(value).every(key => ['edits', 'previous_version_id'].includes(key)) && Array.isArray(value.edits)) {
+            edits = value.edits;
+            if (value.previous_version_id !== null && value.previous_version_id !== undefined)
+                previous = identifier(String(value.previous_version_id));
+        }
+        else
+            throw new CliError('world_dataset_file_invalid', 'Use an edit array, an exported world dataset or edits with an optional previous_version_id.', 2);
+    }
+    if (!datasetEdits(edits))
+        throw new CliError('world_dataset_file_invalid', 'Use a typed edit array. Keep exact integer and decimal values as strings; unsafe numeric values are not rewritten.', 2);
+    const body = { observation_id: capture, previous_version_id: previous, name, edits, save_consent: true };
+    if (Buffer.byteLength(JSON.stringify(body)) > maximum)
+        throw new CliError('world_dataset_capacity', 'These edits exceed dataset transport capacity.', 2);
+    const approved = options.approve || tty && await selectOne(`Save ${edits.length} synthetic-data edits as a private version? This will not change a running world.`, [{ value: false, label: 'Cancel' }, { value: true, label: 'Save dataset' }], options.signal);
+    if (!approved)
+        throw new CliError('dataset_consent_required', 'Use --approve-dataset to save the selected edits. No edits were submitted.', 2);
+    const key = identifier(options.request ?? randomUUID());
+    output('world_dataset_intent', { request_key: key, world_id: scope.world, observation_id: capture, name }, `Request: ${key}\nIf interrupted, use datasets request ${key}. Keep the original file and request ID; do not submit a replacement.`);
+    const row = await api(`${scope.prefix}/datasets`, { ...auth, method: 'POST', body, idempotencyKey: key });
+    const selection = { key, source: capture, previous, name, editCount: edits.length };
+    datasetRead(row, datasetMatches(row, selectedScope, selection));
+    const recorded = await reads.original(key, { ...selection, id: row.id, digest: row.request_digest });
+    output('world_dataset', recorded, text(recorded));
+    if (['failed', 'withdrawn'].includes(recorded.state))
+        throw new CliError('world_dataset_not_saved', recorded.problem ?? 'The original dataset save did not complete.', 2);
+}