firedrill-run 2.2.4 → 3.0.0

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

@@ -0,0 +1,257 @@
+import { api } from './auth.js';
+import { auth, choosePaged, interactive, line, query } from './configuration.js';
+import { CliError } from './http.js';
+import { selectOne } from './prompts.js';
+import { selectedWorld } from './world-access.js';
+import { identifier } from './world-contracts.js';
+import { readSavedRecords } from './saved-records.js';
+const kinds = { workflows: 'workflow', events: 'event', rules: 'rule', collections: 'collection' };
+const number = (value) => new Intl.NumberFormat().format(value);
+const quote = (value) => `'${value.replaceAll("'", "'\\''")}'`;
+const pathName = (entry) => entry.kind === 'alternative' ? `Alternative ${entry.number}` : 'Reference path';
+function nextCommand(context, action, args, page, search) {
+    return `firedrill inspect ${action}${args.length ? ' ' + args.map(quote).join(' ') : ''} --world ${context.world} --workspace ${context.workspace} --page ${page}${search ? ' --search ' + quote(search) : ''}`;
+}
+function summary(value) {
+    const result = [`${value.name}\n${value.id} · Revision ${value.revision}${value.current ? '' : ' · Historical declaration'}`];
+    if (value.kind === 'collection') {
+        result.push('Declared agent schema, not observed database records or relationships.');
+        if (value.content.declared_record_count !== null && value.content.declared_record_count !== undefined)
+            result.push(`Declared records: ${number(value.content.declared_record_count)}`);
+        if (value.content.schema_presentation_complete !== true)
+            result.push('Some authored fields may be omitted or redacted in this saved declaration.');
+    }
+    else if (value.kind === 'rule') {
+        result.push(value.content.statement ?? 'No rule statement was retained.');
+        result.push(value.content.origin === 'derived' && value.provenance.origin === 'derived' ? 'Identified from the agent contract. Not observed behavior.'
+            : value.content.origin === 'generated' && value.provenance.origin === 'generated' ? 'Proposed rule. Not observed behavior.' : 'Origin is shown in the retained source metadata.');
+    }
+    else if (value.kind === 'workflow' && value.content.schema === 'firedrill.workflow.v1') {
+        result.push(`${number(value.content.path_count ?? 0)} authored reference paths. Actual runs can take a different valid path.`);
+    }
+    else if (value.kind === 'event' && value.content.schema === 'firedrill.event-schedule.v1') {
+        result.push(`${number(value.content.event_count ?? 0)} scheduled record changes across ${number(value.content.advance_count ?? 0)} turn boundaries.`, `Schedule start: ${value.content.start_at ?? 'Not recorded'}`, 'These are authored positions, not elapsed time or proof of application.');
+    }
+    else
+        result.push('Inspectable path or schedule metadata was not retained.');
+    if (!value.source_current)
+        result.push("This declaration does not match the world's current source revision.");
+    if (value.provenance.source_revision)
+        result.push(`Source revision: ${value.provenance.source_revision}`);
+    if (value.provenance.source_path)
+        result.push(`Source path: ${value.provenance.source_path}${value.provenance.line_start ? ':' + value.provenance.line_start : ''}`);
+    if (value.content.gaps?.length)
+        result.push(...value.content.gaps);
+    return result.join('\n\n');
+}
+function entryText(entry, view) {
+    if (view === 'paths' && 'scenario_name' in entry)
+        return `${entry.position}. ${entry.scenario_name}\n${pathName(entry)} · ${number(entry.step_count)} steps`;
+    if (view === 'steps' && 'tool' in entry)
+        return `${entry.position}. ${entry.tool || 'Operation name not recorded'}\nInputs: ${entry.input_fields.join(', ') || 'None declared'}\nTrusted state fields: ${entry.trusted_fields.join(', ') || 'None declared'}`
+            + ((entry.input_field_count ?? 0) > (entry.input_fields?.length ?? 0) || (entry.trusted_field_count ?? 0) > (entry.trusted_fields?.length ?? 0) ? '\nSome field names are omitted in this view.' : '');
+    if (view !== 'events' || !('offset_ms' in entry))
+        throw new CliError('declaration_response_invalid', 'The declaration response does not match its selected view. Open it again.');
+    return `${entry.id}\n${entry.action} · ${entry.collection}\nBefore turn ${number(entry.before_turn + 1)} · Offset ${number(entry.offset_ms)} ms\nKey fields: ${entry.key_fields.join(', ') || 'None'}\nChanged fields: ${entry.value_fields.join(', ') || 'None'}`
+        + ((entry.key_field_count ?? 0) > (entry.key_fields?.length ?? 0) || (entry.value_field_count ?? 0) > (entry.value_fields?.length ?? 0) ? '\nSome field names are omitted in this view.' : '')
+        + (entry.condition ? `\nCondition: ${entry.condition.exists ? 'Matching record in' : 'Record absent from'} ${entry.condition.collection}\nCondition key fields: ${entry.condition.key_fields.join(', ')}\nMatching fields: ${entry.condition.match_fields.join(', ') || 'None'}\nChecked before each conversation turn from this offset until applied.`
+            + (entry.condition.key_field_count > entry.condition.key_fields.length || entry.condition.match_field_count > entry.condition.match_fields.length ? '\nSome condition field names are omitted in this view.' : '') : '');
+}
+async function entries(context, id, path, options, output) {
+    if (path !== undefined && !/^[1-9][0-9]{0,8}$/.test(path))
+        throw new CliError('arguments_invalid', 'Use the original positive path position from the workflow.', 2);
+    const page = await api(`${context.prefix}/items/${id}/entries?${query(options)}${path ? '&path=' + path : ''}`, auth(context, options));
+    const text = page.results.map(row => entryText(row, page.view)).join('\n\n') || 'No matching entries.';
+    output('world_declaration_entries', page, `${text}\n\nDeclaration revision ${page.revision}.${!page.current ? ' Historical declaration.' : ''}${!page.source_current ? " Does not match the world's current source revision." : ''}\nPage ${page.page}, ${number(page.count)} matching entries.${page.next
+        ? '\nContinue: ' + nextCommand(context, 'entries', [id, ...(path ? [path] : [])], page.page + 1, options.search ?? '') : ''}`);
+    return page;
+}
+async function choosePath(context, item, options) {
+    let page = 1, search = options.search ?? '';
+    while (true) {
+        const result = await api(`${context.prefix}/items/${item.id}/entries?page=${page}&q=${encodeURIComponent(search)}`, auth(context, options));
+        if (result.view !== 'paths')
+            throw new CliError('declaration_response_invalid', 'The workflow response is not a path page. Open it again.');
+        const choices = result.results.map(row => ({ value: String(row.position), label: row.scenario_name ?? '', detail: `${pathName(row)} · ${number(row.step_count ?? 0)} steps` }));
+        if (page > 1)
+            choices.push({ value: 'previous', label: 'Previous page', detail: '' });
+        if (result.next)
+            choices.push({ value: 'next', label: 'Next page', detail: '' });
+        choices.push({ value: 'search', label: 'Search scenario paths', detail: '' }, { value: 'done', label: 'Done', detail: '' });
+        const selected = await selectOne('Scenario path', choices, options.signal);
+        if (selected === 'done')
+            return null;
+        if (selected === 'previous') {
+            page -= 1;
+            continue;
+        }
+        if (selected === 'next') {
+            page += 1;
+            continue;
+        }
+        if (selected === 'search') {
+            search = await line('Find a scenario (blank for all)', 200, options.signal);
+            page = 1;
+            continue;
+        }
+        const row = result.results.find(value => String(value.position) === selected);
+        if (row)
+            return row;
+        throw new CliError('selection_changed', 'The selected path changed. Open the workflow again.', 2);
+    }
+}
+async function readItem(context, id, options) {
+    const item = await api(`${context.prefix}/items/${identifier(id)}`, auth(context, options));
+    if (!['workflow', 'event', 'rule', 'collection'].includes(item.kind))
+        throw new CliError('selection_invalid', 'Inspect a workflow, rule, event schedule or collection. Use connections for service details.', 2);
+    return item;
+}
+function schemaPath(raw) {
+    try {
+        if (raw && raw.length > 65536)
+            throw new Error();
+        const value = raw ? JSON.parse(raw) : [];
+        if (!Array.isArray(value) || value.length > 32 || value.some(part => typeof part !== 'string' || part.length > 4096
+            || /[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/.test(part)))
+            throw new Error();
+        return value;
+    }
+    catch {
+        throw new CliError('arguments_invalid', 'Use a JSON array of original schema path segments, or omit it for the root.', 2);
+    }
+}
+async function schemaEntries(context, id, path, options, output) {
+    const value = await api(`${context.prefix}/items/${identifier(id)}/schema?${query(options)}&path=${encodeURIComponent(JSON.stringify(path))}`, auth(context, options));
+    if (value.item_id !== id || JSON.stringify(value.path) !== JSON.stringify(path))
+        throw new CliError('collection_schema_changed', 'The schema could not be confirmed. Open it again.', 2);
+    const text = value.node.type === 'object' || value.node.type === 'array'
+        ? value.results.map(row => `${row.segment} · ${row.type}${row.type === 'object' || row.type === 'array' ? ''
+            : '\n' + (typeof row.value === 'string' ? row.value : JSON.stringify(row.value))}${row.omitted ? '\nValue shortened.' : ''}`).join('\n\n') || 'No matching fields.'
+        : (typeof value.node.value === 'string' ? value.node.value : JSON.stringify(value.node.value)) + (value.node.omitted ? '\nValue shortened.' : '');
+    output('world_collection_schema', value, `${text}\n\nDeclared schema revision ${value.revision}.${!value.current ? ' Historical declaration.' : ''}${!value.source_current ? ' Source revision changed.' : ''}${!value.presentation_complete ? '\nSome authored fields may be omitted or redacted.' : ''}\nPage ${value.page}, ${number(value.count)} matching fields.${value.next
+        ? '\nContinue: ' + nextCommand(context, 'schema', [id, JSON.stringify(path)], value.page + 1, options.search ?? '') : ''}`);
+    return value;
+}
+async function chooseSchema(context, item, options, output) {
+    if (!item.content.schema_type || item.content.schema_type === 'missing')
+        return;
+    let path = [], page = 1, search = '';
+    while (true) {
+        const value = await schemaEntries(context, item.id, path, { ...options, page: String(page), search }, output);
+        if (value.revision !== item.revision)
+            throw new CliError('collection_schema_changed', 'The schema changed. Open the collection again.', 2);
+        const choices = value.results.filter(row => row.type === 'object' || row.type === 'array').map((row, index) => ({ value: `field:${index}`, label: row.segment, detail: row.type }));
+        const fields = value.results.filter(row => row.type === 'object' || row.type === 'array');
+        if (path.length)
+            choices.push({ value: 'back', label: 'Back to parent', detail: '' }, { value: 'root', label: 'Schema root', detail: '' });
+        if (page > 1)
+            choices.push({ value: 'previous', label: 'Previous page', detail: '' });
+        if (value.next)
+            choices.push({ value: 'next', label: 'Next page', detail: '' });
+        if (value.node.type === 'object' || value.node.type === 'array')
+            choices.push({ value: 'search', label: 'Find a field', detail: '' });
+        choices.push({ value: 'done', label: 'Done', detail: '' });
+        const selected = await selectOne('Schema', choices, options.signal);
+        if (selected === 'done')
+            return;
+        if (selected === 'previous') {
+            page -= 1;
+            continue;
+        }
+        if (selected === 'next') {
+            page += 1;
+            continue;
+        }
+        if (selected === 'search') {
+            search = await line('Find a field (blank for all)', 200, options.signal);
+            page = 1;
+            continue;
+        }
+        if (selected === 'root')
+            path = [];
+        else if (selected === 'back')
+            path = path.slice(0, -1);
+        else {
+            const field = fields[Number(selected.slice(6))];
+            if (!field)
+                throw new CliError('selection_changed', 'The schema field changed. Open it again.', 2);
+            path = [...path, field.segment];
+        }
+        page = 1;
+        search = '';
+    }
+}
+export async function inspectCommand(args, options, output) {
+    query(options);
+    if (/[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/.test(options.search ?? '')) {
+        throw new CliError('arguments_invalid', 'Use search text without terminal control characters.', 2);
+    }
+    const action = args[0] ?? 'choose';
+    if (action === 'data' || action === 'capture') {
+        const captured = action === 'capture';
+        if (args.length < (captured ? 3 : 2) || args.length > (captured ? 5 : 4))
+            throw new CliError('arguments_invalid', 'Use inspect data <capture> [collection] [row-position] or inspect capture <session> <capture> [collection] [row-position].', 2);
+        const context = await selectedWorld({ workspace: options.workspace, world: options.world, expectedOwner: options.expectedOwner,
+            interactive: interactive(options), signal: options.signal, openBrowser: options.openBrowser });
+        const capture = identifier(args[captured ? 2 : 1]);
+        const prefix = captured ? `${context.prefix}/runtime-sessions/${identifier(args[1])}/observations/${capture}` : context.prefix;
+        return readSavedRecords(prefix, capture, args[captured ? 3 : 2], args[captured ? 4 : 3], { actor: context.owner, workspace: context.workspace, signal: options.signal, page: options.page, search: options.search, json: options.json }, `firedrill inspect ${captured ? 'capture ' + identifier(args[1]) : 'data'} ${capture} --world ${context.world} --workspace ${context.workspace}`, output);
+    }
+    if (!['choose', 'show', 'entries', 'schema', ...Object.keys(kinds)].includes(action)
+        || Object.hasOwn(kinds, action) && args.length !== 1 || action === 'show' && args.length !== 2
+        || ['entries', 'schema'].includes(action) && (args.length < 2 || args.length > 3) || action === 'choose' && args.length) {
+        throw new CliError('arguments_invalid', 'Use inspect, inspect workflows|rules|events|collections, inspect show <id>, inspect entries <id> [path], or inspect schema <id> [JSON path].', 2);
+    }
+    if (action === 'choose' && !interactive(options))
+        throw new CliError('selection_required', 'Use inspect workflows|rules|events|collections or show|entries|schema <id> with --json for automation.', 2);
+    if (action === 'show' && (options.page !== undefined || options.search !== undefined))
+        throw new CliError('arguments_invalid', 'Page and search apply to a list, not a single summary.', 2);
+    if (action === 'choose' && options.page !== undefined)
+        throw new CliError('arguments_invalid', 'Use the page choices in guided inspection, or pass a declaration list command with --page.', 2);
+    if (action === 'entries' && args[2] !== undefined && !/^[1-9][0-9]{0,8}$/.test(args[2]))
+        throw new CliError('arguments_invalid', 'Use the original positive path position from the workflow.', 2);
+    if (['show', 'entries', 'schema'].includes(action))
+        identifier(args[1]);
+    const selectedSchemaPath = action === 'schema' ? schemaPath(args[2]) : [];
+    const context = await selectedWorld({ workspace: options.workspace, world: options.world, expectedOwner: options.expectedOwner,
+        interactive: interactive(options), signal: options.signal, openBrowser: options.openBrowser });
+    if (Object.hasOwn(kinds, action)) {
+        const page = await api(`${context.prefix}/items?kind=${kinds[action]}&${query(options)}`, auth(context, options));
+        output('world_declarations', page, (page.results.map(row => `${row.name}\n${row.id} · Revision ${row.revision}`).join('\n\n') || 'No matching declarations.')
+            + `\n\nPage ${page.page}, ${number(page.count)} matching declarations.${page.next ? '\nContinue: ' + nextCommand(context, action, [], page.page + 1, options.search ?? '') : ''}`);
+        return;
+    }
+    if (action === 'show') {
+        const item = await readItem(context, args[1], options);
+        output('world_declaration', item, summary(item));
+        return;
+    }
+    if (action === 'entries') {
+        await entries(context, identifier(args[1]), args[2], options, output);
+        return;
+    }
+    if (action === 'schema') {
+        await schemaEntries(context, identifier(args[1]), selectedSchemaPath, options, output);
+        return;
+    }
+    const kind = await selectOne('Inspect world', [{ value: 'workflow', label: 'Workflows' }, { value: 'rule', label: 'Rules' }, { value: 'event', label: 'Event schedules' }, { value: 'collection', label: 'Declared collection schemas' }], options.signal);
+    const selected = await choosePaged('Declaration', `${context.prefix}/items?kind=${kind}`, context, options, item => ({ label: item.name, detail: `Revision ${item.revision}` }));
+    if (!selected)
+        return;
+    const item = await readItem(context, selected.id, options);
+    output('world_declaration', item, summary(item));
+    if (item.kind === 'collection') {
+        await chooseSchema(context, item, options, output);
+        return;
+    }
+    if (item.kind === 'rule')
+        return;
+    if (item.kind === 'event') {
+        await entries(context, item.id, undefined, { ...options, page: '1', search: '' }, output);
+        return;
+    }
+    let path;
+    while ((path = await choosePath(context, item, options))) {
+        await entries(context, item.id, String(path.position), { ...options, page: '1', search: '' }, output);
+    }
+}

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

@@ -0,0 +1,103 @@
+import { randomUUID } from 'node:crypto';
+import { api, openBrowser } from './auth.js';
+import { CliError } from './http.js';
+import { selectedWorkspace, selectedWorld } from './world-access.js';
+import { identifier } from './world-contracts.js';
+import { selectOne } from './prompts.js';
+import { workspaceLink } from './browser-links.js';
+import { rememberRecipe, retainedRecipe } from './recipe-intents.js';
+import { recipeNameMatches, recipeMatches, recipePageMatches, recipeRequestMatches } from '../../contracts/world-recipe-contracts.js';
+export async function worldRecipes(args, options, output, selected) {
+    const action = args[0] ?? 'list', interactive = !options.json && !!process.stdin.isTTY && !!process.stderr.isTTY;
+    if (!['list', 'save', 'request', 'show', 'use', 'archive'].includes(action) || args.length > 2
+        || ['list', 'save'].includes(action) && args.length > 1 || !['list', 'save'].includes(action) && args.length !== 2
+        || options.name !== undefined && action !== 'save' || options.request !== undefined && action !== 'save'
+        || options.approve !== undefined && !['save', 'archive'].includes(action)
+        || (options.page !== undefined || options.search !== undefined) && action !== 'list'
+        || options.world !== undefined && !selected && !['save', 'request'].includes(action))
+        throw new CliError('arguments_invalid', 'Use recipes list|save|request <request-key>|show <id>|use <id>|archive <id>.', 2);
+    const scope = selected ?? await selectedWorkspace({ workspace: options.workspace, interactive, signal: options.signal, openBrowser: options.openBrowser });
+    const auth = { actor: scope.owner, workspace: scope.workspace, signal: options.signal }, base = `/api/workspaces/${scope.workspace}/world-recipes`;
+    const read = (row) => { if (!recipeMatches(row, scope.workspace))
+        throw new CliError('world_recipe_unconfirmed', 'The saved recipe could not be confirmed. Inspect its original request before saving another.'); return row; };
+    const confirm = async (message) => {
+        if (options.approve)
+            return;
+        if (!interactive || !await selectOne(message, [{ value: false, label: 'Not now' }, { value: true, label: 'Approve' }], options.signal))
+            throw new CliError('recipe_approval_required', 'Review the recipe metadata, then use --approve-change. No simulation has started.', 2);
+    };
+    if (action === 'list') {
+        const page = Number(options.page ?? '1'), search = options.search ?? '';
+        if (!Number.isSafeInteger(page) || page < 1 || page > 999999999 || search.length > 200)
+            throw new CliError('query_invalid', 'Choose a valid page and a shorter recipe search.', 2);
+        const row = await api(`${base}?${new URLSearchParams({ page: String(page), q: search })}`, auth);
+        if (!recipePageMatches(row, scope.workspace, page))
+            throw new CliError('world_recipe_unconfirmed', 'This recipe page could not be confirmed.');
+        output('world_recipes', row, row.results.map(one => `${one.id}  ${one.name}  ${one.available ? 'Current' : 'Review changed inputs'}`).join('\n') || 'No saved world recipes.');
+        return;
+    }
+    if (action === 'save') {
+        const world = selected ?? await selectedWorld({ workspace: scope.workspace, world: options.world, expectedOwner: scope.owner,
+            interactive, signal: options.signal, openBrowser: options.openBrowser });
+        let body, key = options.request ? identifier(options.request) : randomUUID();
+        if (options.request) {
+            const key = identifier(options.request);
+            const previous = await api(world.prefix + `/recipe-requests/${key}`, auth);
+            if (!recipeRequestMatches(previous, scope.workspace, world.world, key))
+                throw new CliError('world_recipe_unconfirmed', 'The original recipe request could not be confirmed.');
+            if (previous.recipe) {
+                if (options.name !== undefined && previous.recipe.name !== options.name.trim())
+                    throw new CliError('world_recipe_original_metadata_required', 'This original request saved a different recipe name. It was not changed.', 2);
+                output('world_recipe', previous.recipe, `Saved recipe ${previous.recipe.id}. No target execution started.`);
+                return;
+            }
+            const original = await retainedRecipe(world, key);
+            if (!original || options.name !== undefined && options.name.trim() !== original.body.name)
+                throw new CliError('world_recipe_original_metadata_required', 'This device does not retain the exact original save metadata. Inspect recipes request with its original key; a newer prepared world was not substituted.', 2);
+            body = original.body;
+        }
+        else {
+            const prepared = await api(world.prefix + '/preparation', auth);
+            const name = options.name?.trim() || prepared.name;
+            if (!recipeNameMatches(name))
+                throw new CliError('recipe_name_invalid', 'Use a short recipe name without credentials or private URLs.', 2);
+            body = { name, world_revision: prepared.basis.world_revision, configuration_revision: prepared.basis.config_revision };
+        }
+        output('world_recipe_review', { world_id: world.world, ...body, execution_started: false }, `${body.name}: world ${body.world_revision}, configuration ${body.configuration_revision}. Reuse does not preserve a running process or grant account access.`);
+        await confirm('Save this private prepared recipe for future simulation setup?');
+        await rememberRecipe(world, key, body);
+        output('world_recipe_request', { request_key: key }, `Recipe request ${key}. Retain it to continue the same save.`);
+        const row = read(await api(world.prefix + '/recipes', { ...auth, method: 'POST', idempotencyKey: key, body }));
+        if (row.world_id !== world.world || row.name !== body.name || row.world_revision !== body.world_revision
+            || row.configuration_revision !== body.configuration_revision)
+            throw new CliError('world_recipe_unconfirmed', 'Inspect the original recipe save before changing its inputs.');
+        output('world_recipe', row, `Saved recipe ${row.id}. No target execution started.`);
+        return;
+    }
+    if (action === 'request') {
+        const world = selected ?? await selectedWorld({ workspace: scope.workspace, world: options.world, expectedOwner: scope.owner,
+            interactive, signal: options.signal, openBrowser: options.openBrowser });
+        const key = identifier(args[1]), previous = await api(world.prefix + `/recipe-requests/${key}`, auth);
+        if (!recipeRequestMatches(previous, scope.workspace, world.world, key))
+            throw new CliError('world_recipe_unconfirmed', 'The original recipe request could not be confirmed.');
+        output('world_recipe_request', previous, previous.recipe ? `Saved recipe ${previous.recipe.id}.` : 'No save is retained for this original request. No simulation was started.');
+        return;
+    }
+    const id = identifier(args[1]), row = read(await api(`${base}/${id}`, auth));
+    if (row.id !== id)
+        throw new CliError('world_recipe_unconfirmed', 'The saved recipe identity could not be confirmed.');
+    if (action === 'show') {
+        output('world_recipe', row, `${row.name}: ${row.available ? 'current prepared version' : 'review changed or unavailable inputs'}.`);
+        return;
+    }
+    if (action === 'archive') {
+        await confirm('Archive this saved recipe? Its world and simulation history remain unchanged.');
+        await api(`${base}/${id}`, { ...auth, method: 'DELETE' });
+        output('world_recipe_archived', { id }, 'Recipe archived.');
+        return;
+    }
+    if (!row.available || !row.setup_path)
+        throw new CliError('world_recipe_changed', 'This recipe no longer matches the world. Review the current world before using its setup.', 2);
+    const url = workspaceLink(scope.workspace, row.setup_path), opened = !options.json && options.openBrowser ? await openBrowser(url) : false;
+    output('world_recipe_setup', { recipe: row, world_id: row.world_id, url, opened, execution_started: false }, `Simulation setup: ${url}\nFrom the terminal, new simulations use firedrill plan, apply and run. Current permissions and a reviewed credit budget are still required.`);
+}

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

@@ -0,0 +1,241 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, open, opendir, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { performance } from 'node:perf_hooks';
+import { api } from './auth.js';
+import { privateDirectory } from './credentials.js';
+import { CliError } from './http.js';
+import { identifier } from './world-contracts.js';
+const PAGE_SIZE = 25, ACCEPTANCE_READ_LIMIT = 25;
+const invalid = () => new CliError('request_journal_invalid', 'The original request metadata needs attention. It was not discarded or repeated.');
+const prefix = (context) => `request-${identifier(context.owner)}-${identifier(context.workspace)}-${identifier(context.world)}-`;
+const requestPath = (context, key) => `${context.prefix}/requests/${identifier(key)}?actor_id=${identifier(context.owner)}`;
+function validBasis(basis) {
+    return !!basis && Object.keys(basis).sort().join(',') === 'config_revision,source_id,world_revision'
+        && typeof basis.source_id === 'string' && identifier(basis.source_id) === basis.source_id
+        && [basis.world_revision, basis.config_revision].every(one => Number.isSafeInteger(one) && one > 0);
+}
+function canonical(value) {
+    if (typeof value === 'number' && !Number.isSafeInteger(value))
+        throw new CliError('request_invalid', 'Use an exact integer in this request.');
+    if (value === null || typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return '[' + value.map(canonical).join(',') + ']';
+    if (value && typeof value === 'object')
+        return '{' + Object.keys(value).sort().map(key => JSON.stringify(key) + ':' + canonical(value[key])).join(',') + '}';
+    throw new CliError('request_invalid', 'The world request contains an unsupported value.');
+}
+async function pathFor(context, key) {
+    return join(await privateDirectory(), `${prefix(context)}${identifier(key)}.json`);
+}
+async function retain(context, command) {
+    const result = { schema: 'firedrill.native-world-intent.v1', key: randomUUID(), owner: context.owner,
+        workspace: context.workspace, world: context.world, kind: command.kind,
+        digest: createHash('sha256').update(canonical(command)).digest('hex'), basis: command.basis, created_at: new Date().toISOString() };
+    const file = await open(await pathFor(context, result.key), 'wx', 0o600);
+    try {
+        await file.writeFile(JSON.stringify(result));
+        await file.sync();
+    }
+    finally {
+        await file.close();
+    }
+    // Only scope/key/digest/source basis are on disk. Message text, token and target evidence
+    // are never written to this journal. A lost initial reply remains unknown.
+    return result;
+}
+async function loadIntent(context, key) {
+    const path = await pathFor(context, key);
+    let stat;
+    try {
+        stat = await lstat(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || stat.size > 4096
+        || process.getuid && stat.uid !== process.getuid())
+        throw invalid();
+    let file;
+    try {
+        file = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+    try {
+        const actual = await file.stat();
+        if (!actual.isFile() || actual.nlink !== 1 || actual.size !== stat.size || actual.size > 4096 || actual.dev !== stat.dev || actual.ino !== stat.ino
+            || process.getuid && actual.uid !== process.getuid() || process.platform !== 'win32' && (actual.mode & 0o077) !== 0)
+            throw new Error();
+        const bytes = Buffer.alloc(4097);
+        const { bytesRead } = await file.read(bytes, 0, bytes.length, 0);
+        if (bytesRead !== actual.size || bytesRead > 4096)
+            throw new Error();
+        const item = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes.subarray(0, bytesRead)));
+        if (item.schema !== 'firedrill.native-world-intent.v1' || item.owner !== context.owner || item.workspace !== context.workspace
+            || item.world !== context.world || item.key !== identifier(key)
+            || !['message', 'build', 'stop_response', 'cancel_build', 'proposal'].includes(item.kind)
+            || typeof item.created_at !== 'string' || !Number.isFinite(Date.parse(item.created_at))
+            || !/^[a-f0-9]{64}$/.test(item.digest) || !validBasis(item.basis))
+            throw new Error();
+        return item;
+    }
+    catch {
+        throw invalid();
+    }
+    finally {
+        await file.close();
+    }
+}
+async function* intentKeys(context, signal) {
+    const scope = prefix(context), directory = await opendir(await privateDirectory());
+    for await (const entry of directory) {
+        signal?.throwIfAborted();
+        if (!entry.name.startsWith(scope) || !entry.name.endsWith('.json'))
+            continue;
+        const key = entry.name.slice(scope.length, -5);
+        if (!entry.isFile() || identifier(key) !== key)
+            throw invalid();
+        yield key;
+    }
+}
+export async function requestPage(context, after, signal) {
+    const cursor = after === undefined ? undefined : identifier(after), selected = [];
+    // Hold at most one page and its sentinel, not the private directory/history.
+    for await (const key of intentKeys(context, signal)) {
+        if (cursor && key <= cursor || selected.includes(key))
+            continue;
+        const position = selected.findIndex(value => key < value);
+        selected.splice(position < 0 ? selected.length : position, 0, key);
+        if (selected.length > PAGE_SIZE + 1)
+            selected.pop();
+    }
+    const results = [];
+    for (const key of selected.slice(0, PAGE_SIZE)) {
+        signal?.throwIfAborted();
+        results.push(await lookup(context, key, signal));
+    }
+    return { results, page_size: PAGE_SIZE, order: 'request_id',
+        next_after: selected.length > PAGE_SIZE ? selected[PAGE_SIZE - 1] : null };
+}
+function checked(context, key, result, original) {
+    if (!result || result.schema !== 'firedrill.world-command-receipt.v1' || result.actor_id !== context.owner
+        || result.workspace_id !== context.workspace || result.world_id !== context.world || result.request_key !== identifier(key)
+        || !['not_retained', 'pending', 'accepted', 'withdrawn', 'refused'].includes(result.state))
+        throw invalid();
+    if (['pending', 'accepted', 'refused'].includes(result.state)) {
+        if (!result.kind || !['message', 'build', 'stop_response', 'cancel_build', 'proposal'].includes(result.kind)
+            || typeof result.request_digest !== 'string' || !/^[a-f0-9]{64}$/.test(result.request_digest) || !validBasis(result.basis)
+            || original && (result.request_digest !== original.digest || result.kind !== original.kind
+                || canonical(result.basis) !== canonical(original.basis)))
+            throw invalid();
+    }
+    if (result.state === 'accepted') {
+        const receipt = result.receipt;
+        if (!receipt || typeof receipt !== 'object' || Array.isArray(receipt))
+            throw invalid();
+        const uuid = (value) => typeof value === 'string' && identifier(value) === value;
+        if (result.kind === 'message' && (!uuid(receipt.message_id) || !uuid(receipt.conversation_id))
+            || result.kind === 'build' && !uuid(receipt.job_id)
+            || result.kind === 'proposal' && (!uuid(receipt.proposal_id) || receipt.job_id !== null && !uuid(receipt.job_id)
+                || !['applied', 'dismissed', 'queued', 'delivering', 'delivered', 'applying', 'not_applied', 'unknown'].includes(receipt.state ?? ''))
+            || result.kind === 'stop_response' && receipt.state !== 'stop_requested'
+            || result.kind === 'cancel_build' && typeof receipt.state !== 'string')
+            throw invalid();
+    }
+    return result;
+}
+export async function lookup(context, key, signal) {
+    const original = await loadIntent(context, key);
+    const result = checked(context, key, await api(requestPath(context, key), { actor: context.owner, workspace: context.workspace, signal }), original);
+    if (['accepted', 'withdrawn', 'refused'].includes(result.state))
+        await unlink(await pathFor(context, key)).catch(error => { if (error.code !== 'ENOENT')
+            throw error; });
+    return result;
+}
+export async function withdraw(context, key, signal) {
+    const original = await loadIntent(context, key);
+    let result;
+    try {
+        result = checked(context, key, await api(requestPath(context, key), { method: 'DELETE', actor: context.owner, workspace: context.workspace, signal }), original);
+    }
+    catch (error) {
+        signal?.throwIfAborted();
+        if (!(error instanceof CliError) || !['connection_uncertain', 'response_unavailable', 'world_request_accepted'].includes(error.code))
+            throw error;
+        // Recover only by GET. A lost withdrawal reply is never another DELETE.
+        result = await lookup(context, key, signal);
+    }
+    if (['accepted', 'withdrawn', 'refused'].includes(result.state))
+        await unlink(await pathFor(context, key)).catch(error => { if (error.code !== 'ENOENT')
+            throw error; });
+    return result;
+}
+export async function submit(context, command, signal, report) {
+    let acceptanceReads = 0;
+    for await (const key of intentKeys(context, signal)) {
+        if (acceptanceReads >= ACCEPTANCE_READ_LIMIT)
+            throw new CliError('world_request_review_required', `More saved requests need a current receipt. Request ${key} has no confirmed receipt. No new action was submitted.`);
+        acceptanceReads += 1;
+        const state = await lookup(context, key, signal);
+        if (state.state === 'pending' || state.state === 'not_retained') {
+            report(state);
+            throw new CliError('world_request_unresolved', `Resolve request ${key} with request status or withdraw before sending another action.`);
+        }
+    }
+    // The browser and terminal share the same server-side request lane. This is
+    // a bounded metadata read, never a recovered message/body or another PUT.
+    const page = await api(`${context.prefix}/requests?actor_id=${identifier(context.owner)}&state=pending`, { actor: context.owner, workspace: context.workspace, signal });
+    if (!page || !Array.isArray(page.results) || page.results.length > 1 || page.has_more !== false)
+        throw invalid();
+    if (page.results.length) {
+        const previous = checked(context, page.results[0].request_key, page.results[0], null);
+        if (previous.state !== 'pending')
+            throw invalid();
+        report(previous);
+        throw new CliError('world_request_unresolved', `Resolve request ${previous.request_key} with request status or withdraw before sending another action.`);
+    }
+    signal.throwIfAborted();
+    if (!validBasis(command.basis))
+        throw invalid();
+    const intent = await retain(context, command);
+    report({ schema: 'firedrill.world-command-receipt.v1', actor_id: context.owner, workspace_id: context.workspace,
+        world_id: context.world, basis: command.basis, request_key: intent.key, kind: command.kind,
+        state: 'not_retained', request_digest: intent.digest });
+    let current;
+    try {
+        current = checked(context, intent.key, await api(requestPath(context, intent.key), { method: 'PUT', body: command, actor: context.owner, workspace: context.workspace, signal }), intent);
+    }
+    catch (error) {
+        // Even an unobserved acceptance is recovered by READ only. An absent read
+        // is not proof that the original command will never arrive.
+        if (signal.aborted)
+            throw error;
+        current = await lookup(context, intent.key, signal);
+        if (current.state === 'not_retained') {
+            throw new CliError('world_request_uncertain', `Request ${intent.key} has no retained receipt yet. Inspect or withdraw that exact request; it was not resubmitted.`);
+        }
+    }
+    if (current.request_digest && current.request_digest !== intent.digest)
+        throw new CliError('request_identity_changed', 'The saved request identity changed. No action was repeated.');
+    const deadline = performance.now() + 30000;
+    while (current.state === 'pending' && performance.now() < deadline) {
+        report(current);
+        await sleep(1000, undefined, { signal });
+        current = await lookup(context, intent.key, signal);
+    }
+    if (['accepted', 'withdrawn', 'refused'].includes(current.state)) {
+        await unlink(await pathFor(context, intent.key)).catch(error => { if (error.code !== 'ENOENT')
+            throw error; });
+    }
+    report(current);
+    return current;
+}