firedrill-run 2.2.4 → 3.0.0

package/dist/cli/src/native/png.js

@@ -0,0 +1,159 @@
+/**
+ * Metadata-free PNG for root's `client-masked-png-v1` screenshot profile
+ * (Plan20 W12, root `native_image_evidence.py`, 2026-11-10).
+ *
+ * Root accepts only a bounded 8-bit RGB or RGBA, non-interlaced PNG made of
+ * IHDR, contiguous IDAT and IEND, with nothing after IEND: no text, EXIF, color
+ * profile, physical size, animation or private chunk. A browser's PNG carries
+ * some of those, so the capture is re-encoded here: its scanlines are inflated,
+ * checked against the declared dimensions and filter types, and deflated again
+ * into one IDAT. Pixels are not changed, so this removes metadata only; it is
+ * not redaction. Masking happens before capture (drivers/playwright.ts).
+ */
+import { deflateSync, inflateSync } from 'node:zlib';
+/** Root's image bounds. */
+export const PNG_MAX_BYTES = 2 * 1024 * 1024;
+export const PNG_MAX_EDGE = 4096;
+export const PNG_MAX_PIXELS = 8_000_000;
+const PNG_MIN_BYTES = 45;
+const MAX_INPUT_BYTES = 64 * 1024 * 1024;
+const MAX_CHUNKS = 4096;
+const SIGNATURE = Uint8Array.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+const CRC_TABLE = (() => {
+    const table = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        table[n] = c >>> 0;
+    }
+    return table;
+})();
+function crc32(parts) {
+    let c = 0xffffffff;
+    for (const part of parts)
+        for (let i = 0; i < part.length; i++)
+            c = CRC_TABLE[(c ^ part[i]) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+}
+function chunk(type, data) {
+    const kind = Buffer.from(type, 'latin1');
+    const out = Buffer.alloc(12 + data.length);
+    out.writeUInt32BE(data.length, 0);
+    kind.copy(out, 4);
+    Buffer.from(data.buffer, data.byteOffset, data.byteLength).copy(out, 8);
+    out.writeUInt32BE(crc32([kind, data]), 8 + data.length);
+    return out;
+}
+/**
+ * The same image as a metadata-free PNG within root's bounds, or null when the
+ * input is not a well-formed 8-bit RGB/RGBA non-interlaced PNG, is too large
+ * once re-encoded, or exceeds the dimension limits. Never throws.
+ */
+export function metadataFreePng(input) {
+    try {
+        if (!(input instanceof Uint8Array) || input.byteLength < PNG_MIN_BYTES || input.byteLength > MAX_INPUT_BYTES)
+            return null;
+        const body = Buffer.from(input.buffer, input.byteOffset, input.byteLength);
+        if (!body.subarray(0, 8).equals(SIGNATURE))
+            return null;
+        let offset = 8, chunks = 0, header = null, ended = false, dataEnded = false;
+        let width = 0, height = 0, channels = 0;
+        const compressed = [];
+        while (offset < body.length && !ended) {
+            if (++chunks > MAX_CHUNKS || offset + 12 > body.length)
+                return null;
+            const size = body.readUInt32BE(offset);
+            const end = offset + 12 + size;
+            if (size > 0x7fffffff || end > body.length)
+                return null;
+            const kind = body.subarray(offset + 4, offset + 8);
+            const data = body.subarray(offset + 8, end - 4);
+            if (crc32([kind, data]) !== body.readUInt32BE(end - 4))
+                return null;
+            const name = kind.toString('latin1');
+            if (!/^[A-Za-z]{4}$/.test(name))
+                return null;
+            // Transparency and animation affect displayed pixels, not just metadata.
+            // Dropping them could expose RGB values that were previously invisible.
+            if (['tRNS', 'acTL', 'fcTL', 'fdAT'].includes(name))
+                return null;
+            if (compressed.length && name !== 'IDAT')
+                dataEnded = true;
+            if (chunks === 1) {
+                if (name !== 'IHDR' || size !== 13)
+                    return null;
+                width = data.readUInt32BE(0);
+                height = data.readUInt32BE(4);
+                const [depth, color, compression, filter, interlace] = [data[8], data[9], data[10], data[11], data[12]];
+                if (width < 1 || height < 1 || width > PNG_MAX_EDGE || height > PNG_MAX_EDGE || width * height > PNG_MAX_PIXELS
+                    || depth !== 8 || (color !== 2 && color !== 6) || compression !== 0 || filter !== 0 || interlace !== 0)
+                    return null;
+                channels = color === 2 ? 3 : 4;
+                header = Buffer.from(data);
+            }
+            else if (name === 'IDAT') {
+                if (dataEnded)
+                    return null;
+                compressed.push(data);
+            }
+            else if (name === 'IEND') {
+                if (size !== 0)
+                    return null;
+                ended = true;
+            }
+            else if (name === 'PLTE') {
+                // A suggested palette for a truecolor image: optional, dropped.
+            }
+            else if (name.charCodeAt(0) < 0x61) {
+                // Any other critical chunk changes how the image decodes: refuse rather than guess.
+                return null;
+            }
+            // Ancillary chunks (text, EXIF, color profile, physical size, time, private) are dropped.
+            offset = end;
+        }
+        if (!ended || offset !== body.length || !header || compressed.length === 0)
+            return null;
+        const expected = height * (1 + width * channels);
+        const pixels = inflateSync(Buffer.concat(compressed), { maxOutputLength: expected + 1 });
+        if (pixels.length !== expected)
+            return null;
+        const stride = 1 + width * channels;
+        for (let row = 0; row < height; row++)
+            if (pixels[row * stride] > 4)
+                return null;
+        const out = Buffer.concat([Buffer.from(SIGNATURE), chunk('IHDR', header), chunk('IDAT', deflateSync(pixels, { level: 9 })),
+            chunk('IEND', new Uint8Array(0))]);
+        return out.length >= PNG_MIN_BYTES && out.length <= PNG_MAX_BYTES ? new Uint8Array(out) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Whether bytes already have root's metadata-free shape (signature, IHDR first, one IDAT run, IEND last). */
+export function isMetadataFreePng(bytes) {
+    if (!(bytes instanceof Uint8Array) || bytes.byteLength < PNG_MIN_BYTES || bytes.byteLength > PNG_MAX_BYTES)
+        return false;
+    const body = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    if (!body.subarray(0, 8).equals(SIGNATURE))
+        return false;
+    let offset = 8, index = 0, seenData = false, dataEnded = false;
+    while (offset < body.length) {
+        if (offset + 12 > body.length)
+            return false;
+        const size = body.readUInt32BE(offset);
+        const end = offset + 12 + size;
+        if (end > body.length)
+            return false;
+        const name = body.subarray(offset + 4, offset + 8).toString('latin1');
+        if (index === 0 ? name !== 'IHDR' || size !== 13 : name === 'IDAT' ? dataEnded : name !== 'IEND' || size !== 0 || !seenData || end !== body.length)
+            return false;
+        if (name === 'IDAT')
+            seenData = true;
+        else if (index > 0)
+            dataEnded = true;
+        offset = end;
+        index++;
+    }
+    return dataEnded;
+}

package/dist/cli/src/native/ports.js

@@ -0,0 +1,43 @@
+/**
+ * Loopback port allocation (Plan20 W09).
+ *
+ * The operating system picks a free port on 127.0.0.1; the listener is closed
+ * before the port is returned, so another local process could take it before the
+ * service binds. Readiness checks surface that case as a readiness failure.
+ */
+import { createServer } from 'node:net';
+import { CliError } from '../http.js';
+const unavailable = () => new CliError('native_port_unavailable', 'A free loopback port could not be reserved. No service was started on it.');
+/** Bind 127.0.0.1:0, read the assigned port, release it and return the port number. */
+export async function allocateLoopbackPort(signal) {
+    signal?.throwIfAborted();
+    const server = createServer(socket => socket.destroy());
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (error, port = 0) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+            server.off('error', onError);
+            const done = () => error ? reject(error) : resolve(port);
+            if (server.listening)
+                server.close(() => done());
+            else
+                done();
+        };
+        const onError = () => finish(unavailable());
+        const onAbort = () => finish(new CliError('canceled', 'Port allocation was canceled. No service was started.', 130));
+        const timer = setTimeout(onError, 5000);
+        server.once('error', onError);
+        signal?.addEventListener('abort', onAbort, { once: true });
+        server.listen({ host: '127.0.0.1', port: 0, exclusive: true }, () => {
+            const address = server.address();
+            if (!address || typeof address !== 'object' || !Number.isSafeInteger(address.port) || address.port < 1)
+                finish(unavailable());
+            else
+                finish(null, address.port);
+        });
+    });
+}

package/dist/cli/src/native/readiness.js

@@ -0,0 +1,139 @@
+/**
+ * Drill readiness evidence (root `execution-readiness.v1`, Plan20 FIR-492).
+ *
+ * Root admits a drill (`starting` -> `ready`) on its own, after the client
+ * commits one signed readiness record (role `driver.started`) and the single
+ * `driver.started` observation that references it. This module assembles what
+ * that record attests, from what this client actually observed:
+ *  - every declared service exactly once, with its launch identity and
+ *    ownership: launched for this drill (`owned`), already running
+ *    (`attached`), or launched once for the campaign's local run (`owned_run`);
+ *  - the entry service's probe in the kind root requires for the driver
+ *    profile (the driver attests it), and for other services the 2xx status of
+ *    their approved HTTP readiness check, or that they are running;
+ *  - one committed `state.observed` record per local state domain, naming its
+ *    exact declared reset.
+ *
+ * Probe digests (agreed with root on Slack 2026-11-10; signed device
+ * observations, not platform probes): jsonl_handshake hashes the exact stdout
+ * line that matched the approved readiness text, UTF-8, without its line
+ * terminator; function_import the exact pinned wrapper bytes (equal to the
+ * descriptor adapter digest), only once the wrapper started; browser_document the
+ * document serialization a throwaway context returned after navigating to the
+ * approved start path; signed_event_handshake the exact body bytes of the approved
+ * HTTP readiness response. Raw content is never uploaded. Nothing unobserved is
+ * upgraded into success: a local domain without a reset, or a service that is
+ * not running, refuses readiness instead. Observation-only domains are not reset
+ * and are not listed.
+ */
+import { CliError } from '../http.js';
+import { READINESS_MAX_RESETS, READINESS_MAX_SERVICES, nativeError } from './contracts.js';
+export const READINESS_ERRORS = {
+    /** A declared service is not running locally when the drill must become ready. */
+    service_missing: 'native_readiness_service_missing',
+    /** A shared launched service has no local-run launch identity to report it under. */
+    run_service: 'native_readiness_run_service',
+    /** Too many services or local state domains for root's evidence inspection. */
+    limit: 'native_readiness_limit',
+    /** A local domain's reset evidence record was refused or dropped, so readiness cannot cite it. */
+    evidence_missing: 'native_readiness_evidence_missing',
+};
+/**
+ * The local state domains root requires reset evidence for, checked before
+ * anything starts: each must have a reset this client performs. A local domain
+ * without one (declared `unavailable`, or a fresh session that does not reset
+ * its kind) can never be admitted, so the drill is refused up front.
+ */
+export function readinessDomains(descriptor, statePlan) {
+    if (descriptor.services.length > READINESS_MAX_SERVICES) {
+        throw new CliError(READINESS_ERRORS.limit, `The service admits at most ${READINESS_MAX_SERVICES} declared services per drill. No drill was started.`);
+    }
+    const actions = new Map(statePlan.actions.map((action) => [action.alias, action]));
+    const local = [];
+    for (const domain of descriptor.state_domains) {
+        if (domain.location !== 'local')
+            continue;
+        const action = actions.get(domain.alias);
+        if (!action || (action.action !== 'fresh-session' && action.action !== 'fresh-process' && action.action !== 'approved-hook')) {
+            throw nativeError('state_unsupported', `Local state domain "${domain.alias}" has no reset this client performs, and the service admits a drill only with reset evidence for every local domain. No drill was started.`);
+        }
+        local.push(action);
+    }
+    if (local.length > READINESS_MAX_RESETS) {
+        throw new CliError(READINESS_ERRORS.limit, `The service admits at most ${READINESS_MAX_RESETS} local state domains per drill. No drill was started.`);
+    }
+    return local;
+}
+/**
+ * The `state.observed` content for one local domain's reset, once services and
+ * hooks ran. A hook or fresh process that did not apply throws (the drill never
+ * claims a reset it did not see); a fresh session is applied as each session
+ * opens, so it is recorded as scheduled for every driver session of this drill.
+ */
+export function resetEvidence(action, tracker, freshLaunch) {
+    const base = { type: 'state.reset', domain: action.alias, reset: action.reset, hook_sha256: action.descriptor_hook_sha256 };
+    if (action.action === 'approved-hook') {
+        const run = tracker.hookRuns.find((entry) => entry.domain_alias === action.alias);
+        if (!run || run.result !== 'applied')
+            throw new CliError('native_state_reset_failed', `The reset hook for "${action.alias}" did not apply. No drill step was sent.`);
+        return { ...base, result: 'applied', exit_code: run.exit_code, duration_ms: run.duration_ms };
+    }
+    if (action.action === 'fresh-process') {
+        const launchId = freshLaunch(action.service_alias);
+        const applied = tracker.coverage().some((entry) => entry.alias === action.alias && entry.result === 'applied');
+        if (!applied || !launchId) {
+            throw new CliError('native_state_reset_failed', `"${action.alias}" was not reset: its service did not start as a fresh copy for this drill.`);
+        }
+        return { ...base, result: 'applied', service: action.service_alias, launch_id: launchId };
+    }
+    return { ...base, result: 'scheduled', scope: 'each-driver-session' };
+}
+/**
+ * Every declared service as it stands now, in descriptor order, for the
+ * readiness record. Throws when one is not running or cannot be reported
+ * truthfully (a shared launched service outside a registered local run).
+ */
+export function readinessServices(descriptor, plan, handles, driver, entryProbe, drillKey, runService) {
+    const driverOwned = new Map((driver.ownedProcesses?.() ?? []).map((item) => [item.alias, item]));
+    const services = [];
+    for (const { alias } of descriptor.services) {
+        const probe = (handle) => {
+            if (alias === descriptor.entry_service)
+                return entryProbe;
+            const ready = handle?.ready() ?? null;
+            return ready?.kind === 'http' && ready.status_code >= 200 && ready.status_code <= 299
+                ? { kind: 'http', status_code: ready.status_code } : { kind: 'process', observation: 'running' };
+        };
+        const owned = driverOwned.get(alias);
+        if (owned) {
+            if (owned.exit !== null)
+                throw nativeError('process_exited', `Service ${alias} exited before the drill became ready.`);
+            services.push({ service: alias, launch_id: owned.launch_id, ownership: 'owned', run_id: null, probe: probe(null) });
+            continue;
+        }
+        const handle = handles.get(alias);
+        if (!handle || handle.ready() === null) {
+            const planned = plan.services.some((service) => service.alias === alias);
+            throw new CliError(READINESS_ERRORS.service_missing, planned
+                ? `Service ${alias} is not running, so the drill cannot become ready.`
+                : `Declared service ${alias} is not in the approved plan, so the drill cannot become ready. Approve a plan that runs or attaches it.`);
+        }
+        if (handle.mode === 'attach') {
+            services.push({ service: alias, launch_id: handle.launchId, ownership: 'attached', run_id: null, probe: probe(handle) });
+            continue;
+        }
+        if (handle.exit() !== null)
+            throw nativeError('process_exited', `Service ${alias} exited before the drill became ready.`);
+        if (handle.drillKey === drillKey) {
+            services.push({ service: alias, launch_id: handle.launchId, ownership: 'owned', run_id: null, probe: probe(handle) });
+            continue;
+        }
+        // Launched once for the run and shared by its drills: reported only under the run's registered identity.
+        const run = runService(alias);
+        if (!run || run.launch_id !== handle.launchId) {
+            throw new CliError(READINESS_ERRORS.run_service, `Shared service ${alias} has no launch registered in this campaign's local run, so the drill cannot become ready.`);
+        }
+        services.push({ service: alias, launch_id: run.launch_id, ownership: 'owned_run', run_id: run.run_id, probe: probe(handle) });
+    }
+    return services;
+}

package/dist/cli/src/native/reassessments.js

@@ -0,0 +1,206 @@
+/**
+ * Native reassessment (Plan20 R34; root `native_reassessment*.py`).
+ *
+ * A reassessment is a separately quoted and approved new evaluation of one
+ * finished drill's retained evidence:
+ *  - it never invokes the target again and never charges local compute;
+ *  - it never merges into the drill's original result or its quality cohorts;
+ *    each reassessment is its own attempt with its own criterion results.
+ *
+ * Root reviews it under the caller's request key and freezes a quote at once.
+ * Nothing is reserved or evaluated until `admit` names that exact quote with the
+ * human's consent. A reviewed reassessment can be cancelled; an admitted one
+ * cannot. Writes and the request-key read belong to the member who reviewed it.
+ */
+import { api } from '../auth.js';
+import { creditApprovalPolicy, withoutCreditPolicyKeys } from './credit-approval.js';
+import { CliError } from '../http.js';
+import { criterionRow } from './cloud-resources.js';
+export const REASSESSMENT_STATES = ['reviewed', 'evaluating', 'completed', 'cancelled'];
+const PAGE = 25;
+const SCHEMA = 'firedrill.native-reassessment.v1';
+/** Root's own bound on one reassessment's criteria. */
+const MAX_CRITERIA = 256;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const SHA256 = /^[0-9a-f]{64}$/;
+const RESPONSE_LIMIT = 4 * 1024 * 1024;
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const uuid = (value) => typeof value === 'string' && UUID.test(value);
+const count = (value, min = 0) => typeof value === 'number' && Number.isSafeInteger(value) && value >= min;
+const time = (value) => typeof value === 'string' && Number.isFinite(Date.parse(value));
+const text = (value, max) => typeof value === 'string' && value.length >= 1 && value.length <= max;
+const keys = (value) => Object.keys(value).sort().join(',');
+const lower = (value) => value.toLowerCase();
+const unconfirmed = (what) => new CliError('native_response_unconfirmed', `The ${what} response could not be confirmed. Nothing further was sent for it.`);
+const scoped = (scope, signal) => ({ actor: scope.owner, workspace: scope.workspace, signal, maximumResponseBytes: RESPONSE_LIMIT });
+const base = (scope, assignmentId) => `/api/workspaces/${scope.workspace}/native/assignments/${assignmentId}/reassessments`;
+/** A UUID argument exactly as Firedrill printed it, lowercased. */
+export function reassessmentId(value, label) {
+    if (!uuid(value))
+        throw new CliError('arguments_invalid', `Use the ${label} exactly as Firedrill printed it. Nothing was sent.`, 2);
+    return lower(value);
+}
+const ROW_KEYS = 'assignment_id,basis_id,completed_at,created_at,criteria_count,id,profile_changed,profile_comparison,profile_digest,quote,'
+    + 'request_key,source_basis_id,state';
+const COMPARISONS = ['same', 'different', 'unknown'];
+const QUOTE_KEYS = 'activity,credit_scale,denomination,estimated_quantities,estimated_units,execution_location,expires_at,id,maximum_units,organization_id,'
+    + 'resource_class,scope,scope_digest,tariff_digest,tariff_version,workspace_id';
+const PAGE_KEYS = 'count,next,page,page_size,previous,results';
+/**
+ * One reassessment exactly as root defines it:
+ *  - this drill's assignment, re-evaluating a basis other than its own;
+ *  - no basis or completion time while reviewed; its own basis once admitted
+ *    (evaluating), and a completion time as well once completed. A cancelled
+ *    one has neither (cancelled before admission) or both (stopped by root
+ *    after admission, before every criterion finished);
+ *  - the evaluator comparison agrees with profile_changed;
+ *  - a managed evaluation quote in this workspace, frozen to this reassessment,
+ *    its source basis and its evaluator profile, that never charges local compute.
+ * The quote scope's identity fields are checked; its digests of the original are root's.
+ */
+function reassessmentRow(scope, assignmentId) {
+    return (value) => {
+        const quote = object(value) ? value.quote : null;
+        const frozen = object(quote) ? quote.scope : null;
+        const quantities = object(quote) ? quote.estimated_quantities : null;
+        const based = object(value) && value.basis_id !== null;
+        const done = object(value) && value.completed_at !== null;
+        const lifecycle = !object(value) ? false
+            : value.state === 'reviewed' ? !based && !done
+                : value.state === 'evaluating' ? based && !done
+                    : value.state === 'completed' ? based && done
+                        : value.state === 'cancelled' && based === done;
+        if (!object(value) || keys(value) !== ROW_KEYS || !uuid(value.id) || value.assignment_id !== assignmentId
+            || !uuid(value.source_basis_id) || !(value.basis_id === null || uuid(value.basis_id)) || !lifecycle
+            || (value.basis_id !== null && lower(value.basis_id) === lower(value.source_basis_id))
+            || !uuid(value.request_key) || !time(value.created_at) || !(value.completed_at === null || time(value.completed_at))
+            || typeof value.profile_changed !== 'boolean' || !COMPARISONS.includes(value.profile_comparison)
+            || value.profile_changed !== (value.profile_comparison === 'different')
+            || typeof value.profile_digest !== 'string' || !SHA256.test(value.profile_digest)
+            || !count(value.criteria_count, 1) || value.criteria_count > MAX_CRITERIA
+            || !object(quote) || withoutCreditPolicyKeys(quote) !== QUOTE_KEYS || !uuid(quote.id) || quote.workspace_id !== lower(scope.workspace)
+            || !uuid(quote.organization_id) || quote.activity !== 'simulation' || quote.execution_location !== 'managed'
+            || !text(quote.resource_class, 64) || !text(quote.tariff_version, 64) || !text(quote.denomination, 64)
+            || typeof quote.scope_digest !== 'string' || !SHA256.test(quote.scope_digest)
+            || typeof quote.tariff_digest !== 'string' || !SHA256.test(quote.tariff_digest) || !count(quote.credit_scale, 1)
+            || !count(quote.estimated_units) || !count(quote.maximum_units) || quote.estimated_units > quote.maximum_units || !time(quote.expires_at)
+            || !object(quantities) || keys(quantities) !== 'work_units' || !count(quantities.work_units, 1)
+            || !object(frozen) || frozen.schema !== SCHEMA || frozen.component !== 'evaluation' || frozen.reassessment_id !== value.id
+            || frozen.assignment_id !== assignmentId || frozen.source_basis_id !== value.source_basis_id
+            || frozen.local_target_compute_charged !== false
+            || frozen.evaluation_profile_digest !== value.profile_digest)
+            throw unconfirmed('reassessment');
+        return {
+            id: lower(value.id), assignment_id: assignmentId, source_basis_id: lower(value.source_basis_id),
+            basis_id: value.basis_id === null ? null : lower(value.basis_id), request_key: lower(value.request_key),
+            state: value.state, created_at: value.created_at, completed_at: value.completed_at,
+            profile_changed: value.profile_changed, profile_comparison: value.profile_comparison,
+            profile_digest: value.profile_digest, criteria_count: value.criteria_count,
+            quote: { ...creditApprovalPolicy(quote), id: lower(quote.id), denomination: quote.denomination, credit_scale: quote.credit_scale, estimated_units: quote.estimated_units,
+                maximum_units: quote.maximum_units, expires_at: quote.expires_at, resource_class: quote.resource_class, work_units: quantities.work_units },
+        };
+    };
+}
+/** Root's exact page envelope for a 25-row page that was asked for. */
+function pageOf(raw, page, row, what) {
+    if (!object(raw) || keys(raw) !== PAGE_KEYS || !count(raw.count) || raw.page !== page || raw.page_size !== PAGE
+        || (raw.next !== null && typeof raw.next !== 'string') || (raw.previous !== null && typeof raw.previous !== 'string')
+        || !Array.isArray(raw.results) || raw.results.length > PAGE || (raw.next !== null) !== (page * PAGE < raw.count))
+        throw unconfirmed(what);
+    return { count: raw.count, page, next: raw.next, previous: raw.previous, results: raw.results.map(row) };
+}
+function pageNumber(value) {
+    const page = value ?? 1;
+    if (!count(page, 1))
+        throw new CliError('arguments_invalid', 'Use --page with a positive page number.', 2);
+    return page;
+}
+/** A drill's reassessments, newest first (25 per page), the reviewing member's and others'. */
+export async function listReassessments(scope, input) {
+    const assignmentId = reassessmentId(input.assignmentId, 'assignment id');
+    const page = pageNumber(input.page);
+    const raw = await api(`${base(scope, assignmentId)}?page=${page}&page_size=${PAGE}`, scoped(scope, input.signal));
+    return pageOf(raw, page, reassessmentRow(scope, assignmentId), 'reassessments');
+}
+/** One reassessment by id. */
+export async function getReassessment(scope, input) {
+    const assignmentId = reassessmentId(input.assignmentId, 'assignment id');
+    const id = reassessmentId(input.reassessmentId, 'reassessment id');
+    const row = reassessmentRow(scope, assignmentId)(await api(`${base(scope, assignmentId)}/${id}`, scoped(scope, input.signal)));
+    if (row.id !== id)
+        throw unconfirmed('reassessment');
+    return row;
+}
+/**
+ * Review a new evaluation of the drill's retained evidence from `basisId` (its
+ * original evaluation basis), under the caller's request key. Root freezes a
+ * quote; nothing is reserved or evaluated. The same key returns the same
+ * original review, and a different basis under it is refused by root.
+ */
+export async function reviewReassessment(scope, input) {
+    const assignmentId = reassessmentId(input.assignmentId, 'assignment id');
+    const basisId = reassessmentId(input.basisId, 'evaluation basis id');
+    const requestKey = reassessmentId(input.requestKey, 'request key');
+    const row = reassessmentRow(scope, assignmentId)(await api(base(scope, assignmentId), {
+        ...scoped(scope, input.signal), method: 'POST', body: { request_key: requestKey, basis_id: basisId }
+    }));
+    if (row.request_key !== requestKey || row.source_basis_id !== basisId)
+        throw unconfirmed('reassessment');
+    return row;
+}
+/** The caller's original review under this key, or null when root has none (which does not prove it will never arrive). */
+export async function recoverReassessment(scope, input) {
+    const assignmentId = reassessmentId(input.assignmentId, 'assignment id');
+    const requestKey = reassessmentId(input.requestKey, 'request key');
+    try {
+        const row = reassessmentRow(scope, assignmentId)(await api(`${base(scope, assignmentId)}/requests/${requestKey}`, scoped(scope, input.signal)));
+        if (row.request_key !== requestKey)
+            throw unconfirmed('reassessment');
+        return row;
+    }
+    catch (error) {
+        if (error instanceof CliError && error.httpStatus === 404)
+            return null;
+        throw error;
+    }
+}
+/**
+ * Admit a reviewed reassessment with exactly its quote, after the human
+ * approved it: root reserves up to that quote and starts the new evaluation.
+ * An already admitted one is returned unchanged, so a lost answer is recovered,
+ * never charged twice.
+ */
+export async function admitReassessment(scope, input) {
+    const assignmentId = reassessmentId(input.reassessment.assignment_id, 'assignment id');
+    const id = reassessmentId(input.reassessment.id, 'reassessment id');
+    const row = reassessmentRow(scope, assignmentId)(await api(`${base(scope, assignmentId)}/${id}/admit`, {
+        ...scoped(scope, input.signal), method: 'POST', body: { quote_id: input.reassessment.quote.id, reassess_consent: true, credit_approval: input.creditApproval === true }
+    }));
+    if (row.id !== id || row.quote.id !== input.reassessment.quote.id || (row.state !== 'evaluating' && row.state !== 'completed')) {
+        throw unconfirmed('reassessment');
+    }
+    return row;
+}
+/** Cancel a reviewed reassessment after the human's approval. Root refuses an admitted one; nothing is undone. */
+export async function cancelReassessment(scope, input) {
+    const assignmentId = reassessmentId(input.assignmentId, 'assignment id');
+    const id = reassessmentId(input.reassessmentId, 'reassessment id');
+    const row = reassessmentRow(scope, assignmentId)(await api(`${base(scope, assignmentId)}/${id}`, {
+        ...scoped(scope, input.signal), method: 'DELETE', body: { cancel_consent: true }
+    }));
+    if (row.id !== id || row.state !== 'cancelled')
+        throw unconfirmed('reassessment');
+    return row;
+}
+/**
+ * One page of a reassessment's own criterion results (25 per page), each on its
+ * own scale and never pooled with the original's. Empty until it is admitted,
+ * and empty for one that root stopped after admission.
+ */
+export async function listReassessmentCriteria(scope, input) {
+    const assignmentId = reassessmentId(input.assignmentId, 'assignment id');
+    const id = reassessmentId(input.reassessmentId, 'reassessment id');
+    const page = pageNumber(input.page);
+    const raw = await api(`${base(scope, assignmentId)}/${id}/criteria?page=${page}&page_size=${PAGE}`, scoped(scope, input.signal));
+    return pageOf(raw, page, criterionRow, 'reassessment criteria');
+}