@withtruing/companion 0.13.2 → 0.14.0

package/dist/whole-read-runner.js

@@ -0,0 +1,945 @@
+import { createHash } from 'node:crypto';
+import crossSpawn from 'cross-spawn';
+import { enumerateBuildTree, readBuildBlob, resolveLocalBuildCommit, WholeReadGitError } from './whole-read-git.js';
+export { WHOLE_READ_COMPANION_CAPABILITIES } from './whole-read-claims.js';
+import { WholeReadTransportError } from './text-model.js';
+import { decodeCanonicalBlob } from './whole-read/decode.js';
+import { collectInventory } from './whole-read/inventory-collector.js';
+import { DRAFT_PROMPT_VERSION, MERGE_PROMPT_INSTRUCTIONS, MERGE_PROMPT_VERSION, createDraftPromptFromNotes, draftClaimsSchema, mergeDraftClaims, mergeDraftClaimsSchema, planModuleDraft, validateDraftClaims, } from './whole-read/drafting.js';
+import { assembleGroupingPrompt, GROUPING_SCHEMA_VERSION, GroupingValidationError, groupingResultSchema, validateGroupingResult, } from './whole-read/grouping.js';
+import { createGroupingPrompt } from './whole-read/grouping-prompt.js';
+import { validateReadNotes, readNotesSchema } from './whole-read/notes.js';
+import { collectionDigest, encodeCollection } from './whole-read/pages.js';
+import { WHOLE_READ_PHASE_POLICY } from './whole-read/phase-policy.js';
+import { assembleReadPrompt, createReadPrompt, READ_PROMPT_VERSION } from './whole-read/read-prompt.js';
+import { sanitizeBuildMetadata } from './whole-read/sanitize.js';
+import { assembleWholeReadPrompt, deliveredCanonicalSlice, planUnits, WHOLE_READ_PACKING_VERSION } from './whole-read/packing.js';
+import { CLAIM_CHECK_PROMPT_VERSION, claimCheckVerdictSchema, prepareClaimCheck, validateClaimCheck, } from './whole-read/checks.js';
+import { runPrdUnit } from './whole-read/prd-build.js';
+import { createRelationshipPrompt, RELATIONSHIP_PROMPT_VERSION, relationshipTypingSchema, validateRelationshipTypingResult, } from './whole-read/relationship-mapping.js';
+const SHA = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+const COMMAND_TIMEOUT_MS = 120_000;
+export function assignmentRouteReadinessCode(route) {
+    return route === 'local' || route === 'github_companion' ? 'ready' : 'companion_update_required';
+}
+/** Selects only the acquisition route sealed into the assignment by the owner. */
+export async function acquireAssignedSource(input) {
+    if (assignmentRouteReadinessCode(input.route) === 'companion_update_required')
+        return undefined;
+    if (input.route === 'local')
+        return input.acquireLocal();
+    if (input.route === 'github_companion')
+        return input.acquireGithubCompanion();
+    return undefined;
+}
+function runGitCommand(cwd, args, signal) {
+    if (signal.aborted)
+        return Promise.reject(new WholeReadGitError('cancelled'));
+    return new Promise((resolve, reject) => {
+        let child;
+        try {
+            child = crossSpawn('git', [...args], {
+                cwd,
+                env: {
+                    ...process.env,
+                    GIT_NO_REPLACE_OBJECTS: '1',
+                    GIT_NO_LAZY_FETCH: '1',
+                    GIT_OPTIONAL_LOCKS: '0',
+                    GIT_TERMINAL_PROMPT: '0',
+                    GCM_INTERACTIVE: 'never',
+                },
+                stdio: ['ignore', 'pipe', 'pipe'],
+                windowsHide: true,
+            });
+        }
+        catch {
+            reject(new WholeReadGitError('git_unavailable'));
+            return;
+        }
+        const stdout = [];
+        let bytes = 0;
+        let settled = false;
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            signal.removeEventListener('abort', abort);
+            if (error)
+                reject(error);
+            else
+                resolve({ stdout: Buffer.concat(stdout, bytes).toString('utf8') });
+        };
+        const abort = () => { child.kill('SIGKILL'); finish(new WholeReadGitError('cancelled')); };
+        signal.addEventListener('abort', abort, { once: true });
+        child.stdout?.on('data', (chunk) => {
+            bytes += chunk.length;
+            if (bytes > 16 * 1024 * 1024) {
+                child.kill('SIGKILL');
+                finish(new WholeReadGitError('resource_limit'));
+            }
+            else
+                stdout.push(chunk);
+        });
+        child.stderr?.on('data', () => undefined);
+        child.on('error', () => finish(new WholeReadGitError('git_unavailable')));
+        child.on('close', (code, closeSignal) => {
+            if (!settled)
+                finish(code === 0 && closeSignal === null
+                    ? undefined : new WholeReadGitError('snapshot_unavailable'));
+        });
+        const timer = setTimeout(() => {
+            child.kill('SIGKILL');
+            finish(new WholeReadGitError('resource_limit'));
+        }, COMMAND_TIMEOUT_MS);
+    });
+}
+function source(repoPath, commit, verification) {
+    return {
+        repoPath,
+        commit,
+        verification,
+        entries: (signal) => enumerateBuildTree(repoPath, commit, signal),
+        readBlob: (blobId, signal) => readBuildBlob(repoPath, blobId, signal),
+        release: async () => undefined,
+    };
+}
+/** Resolve the selected local branch and reject any assignment for a different commit. */
+export async function acquireLocalSource(input) {
+    if (!SHA.test(input.snapshotSha))
+        throw new WholeReadGitError('snapshot_unavailable');
+    const commit = await resolveLocalBuildCommit(input.repoPath, input.branch, input.signal);
+    if (commit !== input.snapshotSha)
+        throw new WholeReadGitError('snapshot_unavailable');
+    return source(input.repoPath, commit, { lsRemoteVerified: true, exactCommitFetched: true });
+}
+/** Fetch exactly one requested object into an attempt-owned bare repository, without checkout. */
+export async function acquireGithubCompanionSource(input) {
+    if (!SHA.test(input.snapshotSha) || !input.repositoryUrl
+        || input.repositoryUrl.startsWith('-') || input.repositoryUrl.includes('\0')) {
+        throw new WholeReadGitError('snapshot_unavailable');
+    }
+    const run = input.runGit ?? runGitCommand;
+    await run(input.lease.path, ['init', '--bare', input.lease.bareRepositoryPath], input.signal);
+    await run(input.lease.path, ['ls-remote', '--exit-code', input.repositoryUrl], input.signal);
+    await run(input.lease.path, [
+        '--git-dir', input.lease.bareRepositoryPath,
+        'fetch', '--no-tags', '--depth=1', input.repositoryUrl, input.snapshotSha,
+    ], input.signal);
+    const type = await run(input.lease.path, [
+        '--git-dir', input.lease.bareRepositoryPath, 'cat-file', '-t', input.snapshotSha,
+    ], input.signal);
+    const resolved = await run(input.lease.path, [
+        '--git-dir', input.lease.bareRepositoryPath, 'rev-parse', '--verify', `${input.snapshotSha}^{commit}`,
+    ], input.signal);
+    if (type.stdout.trim() !== 'commit' || resolved.stdout.trim() !== input.snapshotSha) {
+        throw new WholeReadGitError('snapshot_unavailable');
+    }
+    return source(input.lease.bareRepositoryPath, input.snapshotSha, { lsRemoteVerified: true, exactCommitFetched: true });
+}
+function parseJson(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        throw new TypeError('build_input_invalid');
+    }
+}
+function assertInputDigest(claim) {
+    const actual = `sha256:${createHash('sha256').update(claim.inputRefsJson, 'utf8').digest('hex')}`;
+    if (actual !== claim.inputDigest)
+        throw new TypeError('build_input_invalid');
+}
+function entryId(buildId, pathBase64) {
+    return `entry_${createHash('sha256').update(`${buildId}\0${pathBase64}`, 'utf8').digest('hex').slice(0, 32)}`;
+}
+function legacyEntryId(pathBase64) {
+    return `entry_${createHash('sha256').update(pathBase64).digest('hex').slice(0, 32)}`;
+}
+function entriesById(buildId, entries) {
+    const result = new Map();
+    for (const entry of entries) {
+        result.set(entryId(buildId, entry.pathBase64), entry);
+        result.set(legacyEntryId(entry.pathBase64), entry);
+    }
+    return result;
+}
+async function tree(sourceHandle, signal) {
+    const entries = [];
+    for await (const entry of sourceHandle.entries(signal))
+        entries.push(entry);
+    return entries;
+}
+async function sendCollection(claim, kind, collectionId, records, transport, usage, metadata, preparedPages) {
+    const pages = preparedPages ?? [...encodeCollection(records)];
+    for (const page of pages)
+        await transport.putPage(claim, page);
+    const digest = collectionDigest(pages, { collectionId, kind });
+    const sealed = await transport.seal(claim, {
+        collectionId,
+        kind,
+        pageCount: pages.length,
+        transportCount: pages.reduce((count, page) => count + page.recordCount, 0),
+        logicalCount: records.length,
+        digest,
+    });
+    return transport.accept(claim, {
+        resultDigest: digest,
+        resultRefJson: sealed.resultRefJson,
+        usage,
+        ...(metadata ? {
+            ...(metadata.model ? { model: metadata.model } : {}),
+            finishReason: metadata.finishReason,
+            usageAvailable: metadata.usageAvailable,
+        } : {}),
+    });
+}
+async function runInventory(claim, dependencies) {
+    const { source: sourceHandle, transport, signal } = required(dependencies);
+    assertInputDigest(claim);
+    const refs = parseJson(claim.inputRefsJson);
+    if (!refs.sourceId)
+        throw new TypeError('build_input_invalid');
+    const entries = await tree(sourceHandle, signal);
+    const collectionId = `inventory:${claim.attemptId}`;
+    const blobs = new Map();
+    for (const entry of entries) {
+        if (entry.mode === '160000')
+            continue;
+        try {
+            blobs.set(entry.blobId, { bytes: await sourceHandle.readBlob(entry.blobId, signal) });
+        }
+        catch (error) {
+            blobs.set(entry.blobId, { acquisitionFailure: {
+                    code: error instanceof WholeReadGitError ? error.code : 'blob_unavailable', source: 'git',
+                } });
+        }
+    }
+    const collected = collectInventory({ sourceId: refs.sourceId, collectionId, entries, blobs });
+    return sendCollection(claim, 'inventory', collectionId, collected.records, transport, { status: 'unavailable' }, undefined, collected.pages);
+}
+async function runPlanning(claim, dependencies) {
+    const { source: sourceHandle, transport, signal } = required(dependencies);
+    assertInputDigest(claim);
+    const protocol = parseJson(claim.inputRefsJson).protocolVersion;
+    if (protocol === 'whole-read-draft-plan-request@1') {
+        const refs = parseJson(claim.inputRefsJson);
+        if (refs.packingVersion !== WHOLE_READ_PACKING_VERSION || refs.promptVersion !== DRAFT_PROMPT_VERSION
+            || sourceHandle.commit !== refs.snapshotSha || !refs.laneId
+            || !Number.isSafeInteger(refs.planRevision) || refs.planRevision < 1
+            || !Number.isSafeInteger(refs.inventoryRevision) || refs.inventoryRevision < 1
+            || !Number.isSafeInteger(refs.maxPromptCharacters) || refs.maxPromptCharacters < 1
+            || !Number.isSafeInteger(refs.maxOutputTokens) || refs.maxOutputTokens < 1
+            || !Number.isSafeInteger(refs.thinkingAllowanceTokens) || refs.thinkingAllowanceTokens < 0
+            || !Number.isSafeInteger(refs.outputTokensPerItem) || refs.outputTokensPerItem < 1
+            || !Array.isArray(refs.groups) || refs.groups.length === 0)
+            throw new TypeError('build_input_invalid');
+        const inventory = await tree(sourceHandle, signal);
+        const byId = entriesById(claim.buildId, inventory);
+        const groups = [];
+        for (const group of refs.groups) {
+            if (!group.groupId || typeof group.label !== 'string' || !group.moduleId || !group.writeKey
+                || !Array.isArray(group.members) || group.members.length === 0 || !Array.isArray(group.notes)) {
+                throw new TypeError('build_input_invalid');
+            }
+            const sources = [];
+            for (const requested of group.members) {
+                const entry = byId.get(requested.entryId);
+                if (!entry || entry.pathDisplay !== requested.path || entry.blobId !== requested.blobId
+                    || entry.mode === '160000' || requested.inventoryRevision !== refs.inventoryRevision) {
+                    throw new TypeError('build_input_invalid');
+                }
+                const bytes = await sourceHandle.readBlob(entry.blobId, signal);
+                if (bytes.byteLength !== requested.bytes
+                    || companionGitObjectId(bytes, requested.blobId.length) !== requested.blobId) {
+                    throw new TypeError('canonical_source_invalid');
+                }
+                const decoded = decodeCanonicalBlob(bytes);
+                if (decoded.status !== 'decoded')
+                    throw new TypeError('canonical_source_invalid');
+                const notes = group.notes.filter((note) => note.entryId === requested.entryId);
+                if (!notes.length)
+                    throw new TypeError('build_input_invalid');
+                sources.push({ path: requested.path, entry: { entryId: requested.entryId, path: requested.path,
+                        blobId: requested.blobId, inventoryRevision: requested.inventoryRevision, decoded }, notes });
+            }
+            groups.push({ groupId: group.groupId, plan: planModuleDraft({ groupId: group.groupId,
+                    groupLabel: group.label, sources, maxPromptCharacters: refs.maxPromptCharacters,
+                    maxOutputTokens: refs.maxOutputTokens, thinkingAllowanceTokens: refs.thinkingAllowanceTokens,
+                    outputTokensPerItem: refs.outputTokensPerItem }) });
+        }
+        const result = { protocolVersion: 'whole-read-draft-plan-result@1', laneId: refs.laneId,
+            planRevision: refs.planRevision, inventoryRevision: refs.inventoryRevision, groups };
+        if (!sanitizeBuildMetadata(result).ok)
+            throw new TypeError('unsafe_model_output');
+        const collectionId = `draft-plan:${claim.attemptId}`;
+        const records = [{ collectionId, collectionKind: 'progress',
+                semanticId: `${refs.laneId}:${refs.planRevision}`, recordKind: 'progress',
+                payload: result }];
+        return sendCollection(claim, 'progress', collectionId, records, transport, { status: 'unavailable' });
+    }
+    const refs = parseJson(claim.inputRefsJson);
+    const prompt = createReadPrompt();
+    if (refs.protocolVersion !== 'whole-read-plan-request@1' || refs.packingVersion !== WHOLE_READ_PACKING_VERSION
+        || refs.promptVersion !== prompt.version || !refs.passId || !refs.laneId
+        || !Number.isSafeInteger(refs.planRevision) || refs.planRevision < 1
+        || !Number.isSafeInteger(refs.ordinal) || refs.ordinal < 0
+        || !Number.isSafeInteger(refs.inventoryRevision) || refs.inventoryRevision < 1
+        || !Number.isSafeInteger(refs.maxOutputTokens) || refs.maxOutputTokens < 1
+        || !Number.isSafeInteger(refs.outputTokensPerItem) || refs.outputTokensPerItem < 1
+        || !Array.isArray(refs.entries) || refs.entries.length === 0)
+        throw new TypeError('build_input_invalid');
+    const inventory = await tree(sourceHandle, signal);
+    const byId = entriesById(claim.buildId, inventory);
+    const plannedEntries = [];
+    for (const requested of refs.entries) {
+        const entry = byId.get(requested.entryId);
+        if (!entry || entry.pathDisplay !== requested.path || entry.blobId !== requested.blobId
+            || entry.mode === '160000')
+            throw new TypeError('build_input_invalid');
+        const decoded = decodeCanonicalBlob(await sourceHandle.readBlob(entry.blobId, signal));
+        if (decoded.status !== 'decoded')
+            throw new TypeError('canonical_source_invalid');
+        plannedEntries.push({ ...requested, inventoryRevision: refs.inventoryRevision, decoded });
+    }
+    const batches = [plannedEntries.filter((entry) => !entry.held),
+        ...plannedEntries.filter((entry) => entry.held).map((entry) => [entry])]
+        .filter((batch) => batch.length > 0);
+    const plans = batches.map((entries, index) => planUnits({
+        passId: index === 0 ? refs.passId : `${refs.passId}:held:${entries[0].entryId}`,
+        entries, prompt, numberLines: true, outputEnvelope: 'per_item',
+        maxOutputTokens: refs.maxOutputTokens, outputTokensPerItem: refs.outputTokensPerItem
+    }));
+    const plan = { packingVersion: WHOLE_READ_PACKING_VERSION,
+        units: plans.flatMap((item) => item.units), failures: plans.flatMap((item) => item.failures),
+        setAside: plans.flatMap((item) => item.setAside), remainingEnvelope: {
+            unitCount: plans.reduce((sum, item) => sum + item.remainingEnvelope.unitCount, 0),
+            promptCharacters: plans.reduce((sum, item) => sum + item.remainingEnvelope.promptCharacters, 0),
+            outputTokens: plans.reduce((sum, item) => sum + item.remainingEnvelope.outputTokens, 0),
+        } };
+    if (!sanitizeBuildMetadata({ plan }).ok)
+        throw new TypeError('unsafe_model_output');
+    const collectionId = `plan:${claim.attemptId}`;
+    const records = [{ collectionId, collectionKind: 'progress',
+            semanticId: refs.passId, recordKind: 'progress', payload: {
+                protocolVersion: 'whole-read-plan-result@1', passId: refs.passId, laneId: refs.laneId,
+                planRevision: refs.planRevision, ordinal: refs.ordinal, plan,
+            } }];
+    return sendCollection(claim, 'progress', collectionId, records, transport, { status: 'unavailable' });
+}
+function sourceLike(value, source) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const cards = value.cards;
+    if (!Array.isArray(cards))
+        return false;
+    const prose = [];
+    for (const card of cards) {
+        if (!card || typeof card !== 'object')
+            continue;
+        const record = card;
+        if (typeof record.summary === 'string')
+            prose.push(record.summary);
+        if (Array.isArray(record.usesHint))
+            prose.push(...record.usesHint.filter((hint) => typeof hint === 'string'));
+    }
+    const withoutLinePrefixes = (text) => text.replace(/(^|\n)\s*\d+(?:\[fragment \d+\])?\| /g, '$1');
+    return prose.some((text) => text.length >= 24
+        && source.some((item) => item.includes(text) || item.includes(withoutLinePrefixes(text))));
+}
+function backendSource(backend) {
+    if (backend === 'api-key' || backend === 'anthropic' || backend === 'anthropic_api')
+        return 'anthropic_api';
+    if (backend === 'cli' || backend === 'claude_cli')
+        return 'claude_cli';
+    return 'codex';
+}
+function safeMetadata(metadata, requestedModel, usageAvailable, source) {
+    const actualModel = metadata?.model ?? requestedModel;
+    const finishReason = metadata?.finishReason ?? null;
+    if (!/^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$/.test(actualModel)
+        || (finishReason !== null && !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$/.test(finishReason))
+        || (metadata !== undefined && metadata.usageAvailable !== usageAvailable)) {
+        throw new WholeReadTransportError('capability_failure', source);
+    }
+    return { model: actualModel, finishReason, usageAvailable };
+}
+export function structuredWholeReadFailure(error) {
+    if (!(error instanceof WholeReadTransportError) || error.code === 'cancelled')
+        return null;
+    return {
+        code: error.code,
+        source: error.source,
+        ...(error.resetAt ? { resetAt: error.resetAt } : {}),
+        ...(error.retryAfterMs === undefined ? {} : { retryAfterMs: error.retryAfterMs }),
+        ...(error.category === undefined ? {} : { category: error.category }),
+    };
+}
+function structuredValidationFailure(claim, error) {
+    const message = error instanceof Error ? error.message : '';
+    const codes = new Set([
+        'check_result_invalid', 'claim_check_input_invalid', 'claim_check_citation_invalid',
+        'claim_check_result_invalid', 'relationship_result_invalid',
+    ]);
+    if (!codes.has(message))
+        return null;
+    return { code: message, source: backendSource(claim.backend) };
+}
+function preSendFailure(claim, error) {
+    const message = error instanceof Error ? error.message : '';
+    if (message === 'canonical_source_invalid')
+        return { code: message, source: 'companion' };
+    const phase = claim.kind === 'draft' ? 'draft' : claim.kind === 'check' ? 'check'
+        : claim.kind === 'group' ? 'grouping' : claim.kind === 'relationship' ? 'relationship' : null;
+    if (!phase)
+        return null;
+    if (message === 'build_reservation_required') {
+        return { code: `${phase}_attempt_invalid`, source: 'companion' };
+    }
+    if (message === 'build_input_invalid' || message === 'snapshot_unavailable') {
+        return { code: `${phase}_input_invalid`, source: 'companion' };
+    }
+    const code = error && typeof error === 'object' && 'code' in error
+        ? error.code : undefined;
+    if (phase === 'draft' && (code === 'draft_note_invalid' || code === 'draft_input_invalid')) {
+        return { code, source: 'companion' };
+    }
+    return null;
+}
+async function runRead(claim, dependencies) {
+    const reservation = claim.reservation;
+    if (!reservation || !claim.consentId || reservation.attemptId !== claim.attemptId
+        || reservation.consentId !== claim.consentId || reservation.unitKind !== claim.kind
+        || reservation.inputTokens !== claim.reservedInputTokens
+        || reservation.outputTokens !== claim.reservedOutputTokens) {
+        throw new TypeError('build_reservation_required');
+    }
+    const { source: sourceHandle, transport, signal } = required(dependencies);
+    if (!dependencies.backend || !claim.model)
+        throw new TypeError('build_backend_unavailable');
+    const model = claim.model;
+    assertInputDigest(claim);
+    const refs = parseJson(claim.inputRefsJson);
+    if (refs.protocolVersion !== 'whole-read-unit-plan@1'
+        || refs.packingVersion !== WHOLE_READ_PACKING_VERSION || refs.promptVersion !== READ_PROMPT_VERSION
+        || !Array.isArray(refs.items)
+        || refs.items.length === 0 || !Array.isArray(refs.contextRefs))
+        throw new TypeError('build_input_invalid');
+    const entries = await tree(sourceHandle, signal);
+    const byId = entriesById(claim.buildId, entries);
+    const legacyIds = refs.items.every((item) => {
+        const entry = byId.get(item.entryId);
+        return entry !== undefined && item.entryId === legacyEntryId(entry.pathBase64);
+    });
+    const byBlob = new Map();
+    for (const entry of entries)
+        byBlob.set(entry.blobId, [...(byBlob.get(entry.blobId) ?? []), entry]);
+    const validation = [];
+    const deliveredItems = [];
+    for (const item of refs.items) {
+        const entry = byId.get(item.entryId) ?? (byBlob.get(item.blobId)?.length === 1 ? byBlob.get(item.blobId)[0] : undefined);
+        if (!entry || entry.pathDisplay !== item.path || entry.blobId !== item.blobId
+            || entry.mode === '160000')
+            throw new TypeError('build_input_invalid');
+        const decoded = decodeCanonicalBlob(await sourceHandle.readBlob(item.blobId, signal));
+        if (decoded.status !== 'decoded')
+            throw new TypeError('canonical_source_invalid');
+        validation.push({ item, decoded });
+        const overlap = item.overlapSpans[0];
+        deliveredItems.push({ entryId: item.entryId, primarySpan: item.primarySpan,
+            primaryText: deliveredCanonicalSlice(decoded, item.primarySpan.startByte, item.primarySpan.endByte),
+            ...(overlap ? { overlapText: deliveredCanonicalSlice(decoded, overlap.startByte, overlap.endByte) } : {}),
+        });
+    }
+    const promptDefinition = createReadPrompt(refs.contexts ?? []);
+    const unit = { unitId: claim.unitId, items: refs.items, contextRefs: refs.contextRefs,
+        promptVersion: refs.promptVersion, promptHash: refs.promptHash,
+        promptCharacters: refs.promptCharacters, outputTokens: refs.outputTokens };
+    const prompt = assembleReadPrompt({ unit, prompt: promptDefinition, deliveredItems });
+    const reply = await dependencies.backend({ prompt, schema: readNotesSchema,
+        phase: 'read', model, maxTokens: claim.reservedOutputTokens, signal });
+    const metadata = safeMetadata(reply.metadata, model, reply.usage !== null, backendSource(claim.backend));
+    if (metadata.finishReason === 'max_tokens') {
+        throw new WholeReadTransportError('output_truncated', backendSource(claim.backend));
+    }
+    if (!sanitizeBuildMetadata(reply.result).ok || sourceLike(reply.result, deliveredItems.flatMap((item) => [item.primaryText, item.overlapText ?? ''])))
+        throw new TypeError('unsafe_model_output');
+    const accepted = validateReadNotes({
+        result: reply.result,
+        items: validation,
+        inventory: entries.map((entry) => ({ entryId: legacyIds
+                ? legacyEntryId(entry.pathBase64) : entryId(claim.buildId, entry.pathBase64), path: entry.pathDisplay })),
+        dependencies: refs.dependencies ?? [],
+        importEdges: refs.importEdges ?? [],
+    });
+    if (!sanitizeBuildMetadata(accepted).ok)
+        throw new TypeError('unsafe_model_output');
+    const collectionId = `notes:${claim.attemptId}`;
+    const records = accepted.notes.map((note) => ({
+        collectionId, collectionKind: 'notes', semanticId: note.noteId, recordKind: 'note',
+        payload: note,
+    }));
+    const usage = reply.usage
+        ? { status: 'measured', inputTokens: reply.usage.inputTokens, outputTokens: reply.usage.outputTokens }
+        : { status: 'unavailable' };
+    return sendCollection(claim, 'notes', collectionId, records, transport, usage, metadata);
+}
+function groupingPrompt(refs) {
+    const definition = createGroupingPrompt();
+    if (refs.promptVersion !== definition.version || refs.contextRefs.length
+        || refs.members.some((member, index) => member.item !== index + 1
+            || member.record.item !== member.item))
+        throw new TypeError('build_input_invalid');
+    const prompt = assembleGroupingPrompt(definition, refs.members.map((member) => member.record));
+    if (prompt.length !== refs.promptCharacters
+        || `sha256:${createHash('sha256').update(prompt).digest('hex')}` !== refs.promptHash) {
+        throw new TypeError('build_input_invalid');
+    }
+    return prompt;
+}
+function validateGrouping(refs, result, members = refs.members) {
+    const expectedIds = new Set(members.map((member) => member.identity));
+    return refs.stage === 'first_level'
+        ? validateGroupingResult({ stage: 'first_level', notes: refs.notes.filter((item) => expectedIds.has(item.noteId)),
+            members, result })
+        : validateGroupingResult({ stage: 'merge', groups: refs.groups.filter((item) => expectedIds.has(item.groupId)),
+            members, result });
+}
+function groupingCorrectionPrompt(refs, accepted) {
+    const missing = new Set(accepted.missingItems);
+    return `Some items were missing from a grouping answer. Put each of these items into one of the existing groups, or a new one.\n`
+        + `Existing group labels: ${JSON.stringify(accepted.groups.map((group) => group.label))}\n`
+        + `Return only {"groups":[{"label":"...","members":[1]}]}. Use the item numbers shown below.\n`
+        + `<missing-members>\n${JSON.stringify(refs.members.filter((member) => missing.has(member.item))
+            .map((member) => member.record))}\n</missing-members>`;
+}
+function mergeGrouping(refs, first, correction) {
+    const itemByIdentity = new Map(refs.members.map((member) => [member.identity, member.item]));
+    const groups = first.groups.map((group) => ({ label: group.label,
+        members: group.memberIds.map((id) => itemByIdentity.get(id)).filter((item) => item !== undefined) }));
+    for (const group of correction.groups) {
+        const members = group.memberIds.map((id) => itemByIdentity.get(id)).filter((item) => item !== undefined);
+        const existing = groups.find((candidate) => candidate.label === group.label);
+        if (existing)
+            existing.members.push(...members);
+        else
+            groups.push({ label: group.label, members });
+    }
+    return validateGrouping(refs, { groups });
+}
+async function runGrouping(claim, dependencies) {
+    const reservation = claim.reservation;
+    if (!reservation || !claim.consentId || reservation.attemptId !== claim.attemptId
+        || reservation.consentId !== claim.consentId || reservation.unitKind !== claim.kind
+        || reservation.inputTokens !== claim.reservedInputTokens
+        || reservation.outputTokens !== claim.reservedOutputTokens) {
+        throw new TypeError('build_reservation_required');
+    }
+    if (!dependencies.backend || !dependencies.transport || !dependencies.signal || !claim.model) {
+        throw new TypeError('build_backend_unavailable');
+    }
+    assertInputDigest(claim);
+    const refs = parseJson(claim.inputRefsJson);
+    if (refs.protocolVersion !== 'whole-read-grouping-unit@2' || refs.schemaVersion !== GROUPING_SCHEMA_VERSION
+        || (refs.stage !== 'first_level' && refs.stage !== 'merge') || !Array.isArray(refs.members)
+        || !Array.isArray(refs.notes) || !Array.isArray(refs.groups) || !Array.isArray(refs.contextRefs)
+        || !Number.isSafeInteger(refs.outputTokens) || refs.outputTokens < 1) {
+        throw new TypeError('build_input_invalid');
+    }
+    const reply = await dependencies.backend({ prompt: groupingPrompt(refs),
+        schema: groupingResultSchema, phase: 'grouping', model: claim.model,
+        maxTokens: claim.reservedOutputTokens, signal: dependencies.signal });
+    const metadata = safeMetadata(reply.metadata, claim.model, reply.usage !== null, backendSource(claim.backend));
+    if (metadata.finishReason === 'max_tokens') {
+        throw new WholeReadTransportError('output_truncated', backendSource(claim.backend));
+    }
+    let accepted = validateGrouping(refs, reply.result);
+    let correctionUsage = null;
+    let corrected = false;
+    if (accepted.missingItems.length && reply.usage
+        && reply.usage.outputTokens < claim.reservedOutputTokens) {
+        corrected = true;
+        const missing = new Set(accepted.missingItems);
+        const members = refs.members.filter((member) => missing.has(member.item));
+        const correction = await dependencies.backend({ prompt: groupingCorrectionPrompt(refs, accepted),
+            schema: groupingResultSchema, phase: 'grouping', model: claim.model,
+            maxTokens: claim.reservedOutputTokens - reply.usage.outputTokens, signal: dependencies.signal });
+        correctionUsage = correction.usage;
+        try {
+            accepted = mergeGrouping(refs, accepted, validateGrouping(refs, correction.result, members));
+        }
+        catch (error) {
+            if (!(error instanceof GroupingValidationError))
+                throw error;
+        }
+    }
+    const collectionId = `groups:${claim.attemptId}`;
+    const records = accepted.groups.map((group) => ({ collectionId,
+        collectionKind: 'groups', semanticId: group.groupId, recordKind: 'group',
+        payload: group }));
+    const usage = reply.usage && (!corrected || correctionUsage)
+        ? { status: 'measured', inputTokens: reply.usage.inputTokens + (correctionUsage?.inputTokens ?? 0),
+            outputTokens: reply.usage.outputTokens + (correctionUsage?.outputTokens ?? 0) }
+        : { status: 'unavailable' };
+    return sendCollection(claim, 'groups', collectionId, records, dependencies.transport, usage, metadata);
+}
+function companionGitObjectId(bytes, length) {
+    return createHash(length === 64 ? 'sha256' : 'sha1')
+        .update(`blob ${bytes.byteLength}\0`).update(bytes).digest('hex');
+}
+function draftRefs(claim) {
+    const refs = parseJson(claim.inputRefsJson);
+    if (refs.protocolVersion !== 'whole-read-drafting-unit@1'
+        || (refs.stage !== 'leaf' && refs.stage !== 'merge') || !refs.groupId || !refs.moduleId
+        || !refs.writeKey || !SHA.test(refs.snapshotSha) || typeof refs.groupLabel !== 'string'
+        || typeof refs.persist !== 'boolean' || !Array.isArray(refs.notes) || !Array.isArray(refs.claims)
+        || !Array.isArray(refs.items) || !Array.isArray(refs.contextRefs)
+        || refs.promptVersion !== (refs.stage === 'leaf' ? DRAFT_PROMPT_VERSION : MERGE_PROMPT_VERSION)
+        || !/^sha256:[0-9a-f]{64}$/.test(refs.promptHash)
+        || !Number.isSafeInteger(refs.promptCharacters) || refs.promptCharacters < 1
+        || !Number.isSafeInteger(refs.outputTokens) || refs.outputTokens < 1
+        || (refs.stage === 'leaf' && (refs.items.length === 0 || refs.notes.length === 0))
+        || (refs.stage === 'merge' && (refs.claims.length === 0 || refs.items.length !== 0))) {
+        throw new TypeError('build_input_invalid');
+    }
+    return refs;
+}
+function draftingMergePrompt(refs) {
+    const definition = { version: MERGE_PROMPT_VERSION, instructions: MERGE_PROMPT_INSTRUCTIONS,
+        schema: JSON.stringify(mergeDraftClaimsSchema), context: [] };
+    const prompt = assembleWholeReadPrompt(definition, [{ ref: 'claims', text: JSON.stringify(refs.claims) }], [], { numberLines: false });
+    if (refs.promptVersion !== definition.version || prompt.length !== refs.promptCharacters
+        || `sha256:${createHash('sha256').update(prompt).digest('hex')}` !== refs.promptHash) {
+        throw new TypeError('build_input_invalid');
+    }
+    return prompt;
+}
+function sourceLikeClaims(value, source) {
+    if (!value || typeof value !== 'object' || !Array.isArray(value.claims))
+        return false;
+    return value.claims.some((claim) => {
+        const claimText = claim?.text;
+        return typeof claimText === 'string' && claimText.length >= 24
+            && source.some((text) => text.includes(claimText));
+    });
+}
+async function runDrafting(claim, dependencies) {
+    const reservation = claim.reservation;
+    if (!reservation || !claim.consentId || reservation.attemptId !== claim.attemptId
+        || reservation.consentId !== claim.consentId || reservation.unitKind !== 'draft'
+        || reservation.inputTokens !== claim.reservedInputTokens
+        || reservation.outputTokens !== claim.reservedOutputTokens) {
+        throw new TypeError('build_reservation_required');
+    }
+    if (!dependencies.backend || !dependencies.transport || !dependencies.signal || !claim.model) {
+        throw new TypeError('build_backend_unavailable');
+    }
+    assertInputDigest(claim);
+    const refs = draftRefs(claim);
+    let prompt;
+    let sources = [];
+    let unit;
+    let deliveredText = [];
+    if (refs.stage === 'leaf') {
+        if (!dependencies.source || dependencies.source.commit !== refs.snapshotSha) {
+            throw new TypeError('snapshot_unavailable');
+        }
+        const entries = await tree(dependencies.source, dependencies.signal);
+        const byId = entriesById(claim.buildId, entries);
+        const notesByEntry = new Map();
+        for (const note of refs.notes)
+            notesByEntry.set(note.entryId, [...(notesByEntry.get(note.entryId) ?? []), note]);
+        const decoded = new Map();
+        const delivered = [];
+        for (const item of refs.items) {
+            const entry = byId.get(item.entryId);
+            if (!entry || entry.pathDisplay !== item.path || entry.blobId !== item.blobId || entry.mode === '160000'
+                || !notesByEntry.has(item.entryId))
+                throw new TypeError('build_input_invalid');
+            let canonical = decoded.get(item.entryId);
+            if (!canonical) {
+                const bytes = await dependencies.source.readBlob(item.blobId, dependencies.signal);
+                if (companionGitObjectId(bytes, item.blobId.length) !== item.blobId) {
+                    throw new TypeError('canonical_source_invalid');
+                }
+                const value = decodeCanonicalBlob(bytes);
+                if (value.status !== 'decoded')
+                    throw new TypeError('canonical_source_invalid');
+                canonical = { path: entry.pathDisplay, decoded: value, blobId: entry.blobId };
+                decoded.set(item.entryId, canonical);
+            }
+            const overlap = item.overlapSpans[0];
+            delivered.push({ item,
+                primaryText: deliveredCanonicalSlice(canonical.decoded, item.primarySpan.startByte, item.primarySpan.endByte),
+                ...(overlap ? { overlapText: deliveredCanonicalSlice(canonical.decoded, overlap.startByte, overlap.endByte) } : {}) });
+        }
+        sources = [...decoded].map(([id, value]) => ({ path: value.path,
+            entry: { entryId: id, path: value.path, blobId: value.blobId,
+                inventoryRevision: refs.items.find((item) => item.entryId === id).inventoryRevision,
+                decoded: value.decoded },
+            notes: notesByEntry.get(id) }));
+        if (sources.some((source) => source.notes.some((note) => note.inventoryRevision !== source.entry.inventoryRevision
+            || note.path !== source.path || note.blobId !== source.entry.blobId))) {
+            throw new TypeError('build_input_invalid');
+        }
+        const definition = createDraftPromptFromNotes(refs.groupLabel, refs.notes);
+        const contexts = definition.context.filter((context) => refs.contextRefs.includes(context.ref));
+        prompt = assembleWholeReadPrompt(definition, contexts, delivered, { numberLines: true });
+        if (refs.promptVersion !== definition.version || prompt.length !== refs.promptCharacters
+            || `sha256:${createHash('sha256').update(prompt).digest('hex')}` !== refs.promptHash) {
+            throw new TypeError('build_input_invalid');
+        }
+        unit = { unitId: claim.unitId, items: refs.items, contextRefs: refs.contextRefs,
+            promptVersion: refs.promptVersion, promptHash: refs.promptHash,
+            promptCharacters: refs.promptCharacters, outputTokens: refs.outputTokens };
+        deliveredText = delivered.flatMap((item) => [item.primaryText, item.overlapText ?? '']);
+    }
+    else
+        prompt = draftingMergePrompt(refs);
+    const reply = await dependencies.backend({ prompt,
+        schema: refs.stage === 'leaf' ? draftClaimsSchema : mergeDraftClaimsSchema,
+        phase: refs.stage === 'leaf' ? 'drafting_leaf' : 'drafting_merge',
+        model: claim.model,
+        maxTokens: claim.reservedOutputTokens,
+        signal: dependencies.signal });
+    const metadata = safeMetadata(reply.metadata, claim.model, reply.usage !== null, backendSource(claim.backend));
+    if (metadata.finishReason === 'max_tokens') {
+        throw new WholeReadTransportError('output_truncated', backendSource(claim.backend));
+    }
+    if (!sanitizeBuildMetadata(reply.result).ok
+        || (refs.stage === 'leaf' && sourceLikeClaims(reply.result, deliveredText))) {
+        throw new TypeError('unsafe_model_output');
+    }
+    const claims = refs.stage === 'leaf'
+        ? validateDraftClaims({ result: reply.result, unit: unit, sources })
+        : mergeDraftClaims({ claims: refs.claims, result: reply.result, complete: refs.persist });
+    if (!sanitizeBuildMetadata({ claims }).ok)
+        throw new TypeError('unsafe_model_output');
+    const collectionId = `claims:${claim.attemptId}`;
+    const records = claims.map((draft) => ({ collectionId, collectionKind: 'claims',
+        semanticId: draft.claimId, recordKind: 'claim', payload: draft }));
+    const usage = reply.usage
+        ? { status: 'measured', inputTokens: reply.usage.inputTokens, outputTokens: reply.usage.outputTokens }
+        : { status: 'unavailable' };
+    return sendCollection(claim, 'claims', collectionId, records, dependencies.transport, usage, metadata);
+}
+async function runCheck(claim, dependencies) {
+    const reservation = claim.reservation;
+    if (!reservation || !claim.consentId || reservation.attemptId !== claim.attemptId
+        || reservation.consentId !== claim.consentId || reservation.unitKind !== 'check'
+        || reservation.inputTokens !== claim.reservedInputTokens
+        || reservation.outputTokens !== claim.reservedOutputTokens) {
+        throw new TypeError('build_reservation_required');
+    }
+    const { source: sourceHandle, transport, signal } = required(dependencies);
+    if (!dependencies.backend || !claim.model)
+        throw new TypeError('build_backend_unavailable');
+    assertInputDigest(claim);
+    const refs = parseJson(claim.inputRefsJson);
+    if (refs.protocolVersion !== 'whole-read-check-unit@1' || refs.promptVersion !== CLAIM_CHECK_PROMPT_VERSION
+        || typeof refs.issuanceRef !== 'string' || !refs.issuanceRef.trim()
+        || !refs.subject || !['claim', 'note_use'].includes(refs.subject.kind)
+        || !Array.isArray(refs.entries) || refs.entries.length === 0 || !Array.isArray(refs.acceptedCoverage)
+        || !Number.isSafeInteger(refs.maxPromptCharacters) || refs.maxPromptCharacters < 1
+        || !Number.isSafeInteger(refs.outputTokens) || refs.outputTokens < 1) {
+        throw new TypeError('build_input_invalid');
+    }
+    const entries = await tree(sourceHandle, signal);
+    const byId = entriesById(claim.buildId, entries);
+    const checkEntries = [];
+    for (const expected of refs.entries) {
+        const item = byId.get(expected.entryId);
+        if (!item || item.pathDisplay !== expected.path || item.blobId !== expected.blobId
+            || item.mode === '160000' || expected.state !== 'read')
+            throw new TypeError('build_input_invalid');
+        const bytes = await sourceHandle.readBlob(item.blobId, signal);
+        if (companionGitObjectId(bytes, item.blobId.length) !== item.blobId) {
+            throw new TypeError('canonical_source_invalid');
+        }
+        checkEntries.push({ ...expected, bytes });
+    }
+    const prepared = prepareClaimCheck({ claim: refs.subject.claim, entries: checkEntries,
+        acceptedCoverage: refs.acceptedCoverage, acquisitionHost: 'companion',
+        maxPromptCharacters: refs.maxPromptCharacters });
+    let result;
+    let usage = { status: 'measured', inputTokens: 0, outputTokens: 0 };
+    let metadata;
+    if (prepared.status === 'not_established')
+        result = prepared.result;
+    else {
+        const reply = await dependencies.backend({ prompt: prepared.prompt,
+            schema: claimCheckVerdictSchema, phase: 'support_check', model: claim.model,
+            maxTokens: WHOLE_READ_PHASE_POLICY.support_check.maxOutputTokens, signal });
+        metadata = safeMetadata(reply.metadata, claim.model, reply.usage !== null, backendSource(claim.backend));
+        if (metadata.finishReason === 'max_tokens') {
+            throw new WholeReadTransportError('output_truncated', backendSource(claim.backend));
+        }
+        result = validateClaimCheck({ prepared, result: reply.result });
+        usage = reply.usage ? { status: 'measured', inputTokens: reply.usage.inputTokens,
+            outputTokens: reply.usage.outputTokens } : { status: 'unavailable' };
+    }
+    if (!sanitizeBuildMetadata(result).ok)
+        throw new TypeError('unsafe_model_output');
+    const collectionId = `checks:${claim.attemptId}`;
+    const payload = { subjectKind: refs.subject.kind, claimId: result.claimId,
+        verdict: result.verdict, reason: result.reason, evidence: result.evidence };
+    const records = [{ collectionId, collectionKind: 'progress',
+            semanticId: result.claimId, recordKind: 'progress', payload: payload }];
+    return sendCollection(claim, 'progress', collectionId, records, transport, usage, metadata);
+}
+async function runPrd(claim, dependencies) {
+    const reservation = claim.reservation;
+    if (!reservation || !claim.consentId || reservation.attemptId !== claim.attemptId
+        || reservation.consentId !== claim.consentId || reservation.unitKind !== 'prd'
+        || reservation.inputTokens !== claim.reservedInputTokens
+        || reservation.outputTokens !== claim.reservedOutputTokens) {
+        throw new TypeError('build_reservation_required');
+    }
+    if (!dependencies.backend || !dependencies.transport || !dependencies.signal || !claim.model) {
+        throw new TypeError('build_backend_unavailable');
+    }
+    assertInputDigest(claim);
+    const unit = parseJson(claim.inputRefsJson);
+    const response = await runPrdUnit(unit, claim.model, dependencies.signal, dependencies.backend);
+    const metadata = safeMetadata({ model: response.model ?? claim.model,
+        finishReason: response.finishReason ?? null, usageAvailable: response.usage !== null }, claim.model, response.usage !== null, backendSource(claim.backend));
+    if (metadata.finishReason === 'max_tokens') {
+        throw new WholeReadTransportError('output_truncated', backendSource(claim.backend));
+    }
+    const collectionId = `prd:${claim.attemptId}`;
+    const records = [{ collectionId, collectionKind: 'claims', semanticId: 'header',
+            recordKind: 'claim', payload: { recordType: 'header', phase: response.result.phase,
+                lanes: response.result.lanes,
+                unmatchedSectionIds: response.result.unmatchedSectionIds } }, ...response.result.claims.map((item) => ({
+            collectionId, collectionKind: 'claims', semanticId: item.claimId, recordKind: 'claim', payload: {
+                recordType: 'claim', claimId: item.claimId, laneKey: item.laneKey, text: item.text,
+                citations: item.citations, status: item.status,
+                statusSectionId: item.statusCitation?.sectionId ?? null,
+                statusStartChar: item.statusCitation?.startChar ?? null, statusEndChar: item.statusCitation?.endChar ?? null,
+                verdict: item.verdict,
+            },
+        }))];
+    const usage = response.usage
+        ? { status: 'measured', inputTokens: response.usage.inputTokens, outputTokens: response.usage.outputTokens }
+        : { status: 'unavailable' };
+    return sendCollection(claim, 'claims', collectionId, records, dependencies.transport, usage, metadata);
+}
+async function runRelationships(claim, dependencies) {
+    const reservation = claim.reservation;
+    if (!reservation || !claim.consentId || reservation.attemptId !== claim.attemptId
+        || reservation.consentId !== claim.consentId || reservation.unitKind !== 'relationship'
+        || reservation.inputTokens !== claim.reservedInputTokens
+        || reservation.outputTokens !== claim.reservedOutputTokens) {
+        throw new TypeError('build_reservation_required');
+    }
+    if (!dependencies.backend || !dependencies.transport || !dependencies.signal || !claim.model) {
+        throw new TypeError('build_backend_unavailable');
+    }
+    assertInputDigest(claim);
+    const refs = parseJson(claim.inputRefsJson);
+    if (refs.protocolVersion !== 'whole-read-relationship-unit@1'
+        || refs.promptVersion !== RELATIONSHIP_PROMPT_VERSION || !Array.isArray(refs.candidates)
+        || refs.candidates.length === 0 || !Array.isArray(refs.contexts)
+        || refs.candidates.some((candidate) => !candidate?.candidateId?.trim()
+            || !candidate.sourceModuleId?.trim() || !candidate.targetModuleId?.trim())
+        || new Set(refs.candidates.map((candidate) => candidate.candidateId)).size !== refs.candidates.length
+        || !Number.isSafeInteger(refs.promptCharacters) || refs.promptCharacters < 1
+        || !Number.isSafeInteger(refs.outputTokens) || refs.outputTokens < 1) {
+        throw new TypeError('build_input_invalid');
+    }
+    const definition = createRelationshipPrompt(refs.contexts);
+    const prompt = assembleWholeReadPrompt(definition, refs.contexts, [], { numberLines: false });
+    if (prompt.length !== refs.promptCharacters
+        || `sha256:${createHash('sha256').update(prompt).digest('hex')}` !== refs.promptHash) {
+        throw new TypeError('build_input_invalid');
+    }
+    const reply = await dependencies.backend({ prompt,
+        schema: relationshipTypingSchema, phase: 'relationships', model: claim.model,
+        maxTokens: WHOLE_READ_PHASE_POLICY.relationships.maxOutputTokens, signal: dependencies.signal });
+    const metadata = safeMetadata(reply.metadata, claim.model, reply.usage !== null, backendSource(claim.backend));
+    if (metadata.finishReason === 'max_tokens') {
+        throw new WholeReadTransportError('output_truncated', backendSource(claim.backend));
+    }
+    const relationships = validateRelationshipTypingResult(refs.candidates, reply.result);
+    if (!sanitizeBuildMetadata({ relationships }).ok)
+        throw new TypeError('unsafe_model_output');
+    const collectionId = `relationships:${claim.attemptId}`;
+    const records = relationships.map((relationship) => ({ collectionId,
+        collectionKind: 'progress', semanticId: relationship.candidateId, recordKind: 'progress',
+        payload: relationship }));
+    const usage = reply.usage
+        ? { status: 'measured', inputTokens: reply.usage.inputTokens,
+            outputTokens: reply.usage.outputTokens }
+        : { status: 'unavailable' };
+    return sendCollection(claim, 'progress', collectionId, records, dependencies.transport, usage, metadata);
+}
+function required(dependencies) {
+    if (!dependencies.source || !dependencies.transport || !dependencies.signal) {
+        throw new TypeError('whole_read_runner_invalid');
+    }
+    return { source: dependencies.source, transport: dependencies.transport, signal: dependencies.signal };
+}
+/** Closed dispatch: unknown build kinds fail here and can never reach the legacy generic runner. */
+export async function dispatchWholeReadClaim(claim, dependencies) {
+    let requestSent = false;
+    let usageUnavailable = false;
+    const measuredUsage = { status: 'measured', inputTokens: 0, outputTokens: 0 };
+    const wrapped = dependencies.backend ? { ...dependencies,
+        backend: async (request) => {
+            requestSent = true;
+            try {
+                const reply = await dependencies.backend(request);
+                if (reply.usage) {
+                    measuredUsage.inputTokens += reply.usage.inputTokens;
+                    measuredUsage.outputTokens += reply.usage.outputTokens;
+                }
+                else
+                    usageUnavailable = true;
+                return reply;
+            }
+            catch (error) {
+                usageUnavailable = true;
+                throw error;
+            }
+        } } : dependencies;
+    try {
+        if (claim.kind === 'inventory') {
+            return await (dependencies.inventory ? dependencies.inventory(claim) : runInventory(claim, dependencies));
+        }
+        if (claim.kind === 'plan') {
+            return await (dependencies.planning ? dependencies.planning(claim) : runPlanning(claim, dependencies));
+        }
+        if (claim.kind === 'read') {
+            return await (dependencies.read ? dependencies.read(claim) : runRead(claim, wrapped));
+        }
+        if (claim.kind === 'group') {
+            return await (dependencies.grouping ? dependencies.grouping(claim) : runGrouping(claim, wrapped));
+        }
+        if (claim.kind === 'draft') {
+            return await (dependencies.drafting ? dependencies.drafting(claim) : runDrafting(claim, wrapped));
+        }
+        if (claim.kind === 'check') {
+            return await (dependencies.checks ? dependencies.checks(claim) : runCheck(claim, wrapped));
+        }
+        if (claim.kind === 'prd') {
+            return await (dependencies.prd ? dependencies.prd(claim) : runPrd(claim, wrapped));
+        }
+        if (claim.kind === 'relationship') {
+            return await (dependencies.relationships
+                ? dependencies.relationships(claim) : runRelationships(claim, wrapped));
+        }
+        return { status: 'build_task_kind_unsupported' };
+    }
+    catch (error) {
+        const code = error && typeof error === 'object' && 'code' in error
+            ? error.code : undefined;
+        const validationFailure = claim.kind === 'draft' && typeof code === 'string'
+            && /^(?:draft|merge)_/.test(code)
+            ? { code, source: 'companion' } : null;
+        const failure = structuredWholeReadFailure(error) ?? structuredValidationFailure(claim, error) ?? validationFailure
+            ?? (!requestSent ? preSendFailure(claim, error) : null);
+        if (failure && dependencies.transport?.fail)
+            return dependencies.transport.fail(claim, failure, !requestSent ? measuredUsage : usageUnavailable ? undefined : measuredUsage);
+        throw error;
+    }
+}