@adminiumjs/adminium 0.1.0-rc.1

package/dist/llm/provider-resolver.js

@@ -0,0 +1,81 @@
+import { createProviderClient, DEFAULT_MAX_OUTPUT_TOKENS, ProviderError, validateResponse, } from '@adminium/llm';
+import { settingsRepo, snapshotsRepo } from '@adminium/meta';
+/**
+ * Per-provider `maxTokens` ceiling the `LLM_TRUNCATED` escalation raises to
+ * before counting a repair (§7.5). Conservative output caps for the chat
+ * contract each client speaks; a truncated reply retries once at this budget.
+ */
+export const PROVIDER_OUTPUT_CEILING = {
+    anthropic: 64_000,
+    openai: 16_384,
+    'openai-compatible': 32_000,
+    ollama: 32_000,
+    'adminium-managed': 64_000,
+};
+/** Build the production run resolver. */
+export function createProviderResolver(deps) {
+    const settings = settingsRepo(deps.meta);
+    const snapshots = snapshotsRepo(deps.meta);
+    const makeClient = deps.createClient ?? createProviderClient;
+    return async (run) => {
+        if (run.provider === null) {
+            throw new ProviderError({
+                provider: 'anthropic',
+                code: 'config',
+                message: `run ${run.id} has no provider recorded`,
+            });
+        }
+        const provider = run.provider;
+        const [storedKey, baseUrl, settingModel, maxOut] = await Promise.all([
+            settings.get('llm.apiKey'),
+            settings.get('llm.baseUrl'),
+            settings.get('llm.model'),
+            settings.get('llm.maxOutputTokens'),
+        ]);
+        const apiKey = decryptKey(storedKey, deps.keyCrypto);
+        const model = run.model ?? settingModel ?? '';
+        const maxTokens = maxOut ?? DEFAULT_MAX_OUTPUT_TOKENS;
+        const config = { provider, model, maxOutputTokens: maxTokens };
+        if (apiKey !== undefined)
+            config.apiKey = apiKey;
+        if (baseUrl !== null)
+            config.baseUrl = baseUrl;
+        const client = makeClient(config);
+        const snapshot = await snapshots.findById(run.snapshotId);
+        if (snapshot === null) {
+            throw new ProviderError({
+                provider,
+                code: 'config',
+                message: `run ${run.id} references a missing snapshot ${run.snapshotId}`,
+            });
+        }
+        const schemaIr = snapshot.schema;
+        const locales = (run.locales ?? ['en_US']);
+        const validate = (rawText) => validateResponse(rawText, {
+            snapshot: schemaIr,
+            locales,
+            allowedTemplates: deps.allowedTemplates,
+            allowedWidgets: deps.allowedWidgets,
+            ...(deps.allowedIcons !== undefined ? { allowedIcons: deps.allowedIcons } : {}),
+            runId: run.id,
+        });
+        return {
+            client,
+            provider,
+            model,
+            maxTokens,
+            maxTokensCeiling: Math.max(maxTokens, PROVIDER_OUTPUT_CEILING[provider]),
+            validate,
+        };
+    };
+}
+/**
+ * Decrypt the stored key. Tolerates a plaintext value (the settings-secret write
+ * path is still landing) by only decrypting recognizably-encrypted `enc:` tokens.
+ */
+function decryptKey(stored, crypto) {
+    if (stored === null || stored.length === 0)
+        return undefined;
+    return stored.startsWith('enc:') ? crypto.decrypt(stored) : stored;
+}
+//# sourceMappingURL=provider-resolver.js.map

package/dist/llm/provider-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-resolver.js","sourceRoot":"","sources":["../../src/llm/provider-resolver.ts"],"names":[],"mappings":"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"}

package/dist/llm/run-service.d.ts

@@ -0,0 +1,215 @@
+/**
+ * LLM run lifecycle service (06-llm-assist.md §7.4, §7.5, §9).
+ *
+ * The shared layer the direct-path runner (T08), the apply executor (T10b), and
+ * the `/api/v1/llm/*` routes (T11) all call. It owns:
+ *  - `createRun` — build the prompt (via the browser-safe `@adminium/llm`
+ *    `buildPrompt`) against the connection's snapshot IR + collected stats,
+ *    persist a `draft` run with its flattened `prompt_text` + `prompt_sha256`,
+ *    and (§9) keep `provider`/`model` NULL for BYO runs;
+ *  - `receiveResponse` — the BYO intake: validate a pasted chunk through the
+ *    shared `validateResponse` pipeline and advance the run (fatal → stays
+ *    `awaiting_response`; clean → `validated`);
+ *  - the §7.4 status machine (legal transitions + run immutability after a
+ *    terminal state).
+ *
+ * Architecture (01 §2.3): the transactional apply-EXECUTOR that writes overrides
+ * /pages lives in T10b, not here — this service persists run rows and validation
+ * outcomes only. Provider NETWORK calls belong to T08's job runner; this service
+ * performs none.
+ */
+import type { DatabaseModel, StatsResult } from '@adminium/engine';
+import { type AllowedVocabularies, type LlmResponseV1, type LlmRunStatus, type LlmValidationError, type LocaleCode, type ProviderId, type PromptArtifact, type RequestedSection, type Sampling, type ValidationResult } from '@adminium/llm';
+import { type LlmRun, type LlmRunReview, type MetaDb } from '@adminium/meta';
+import type { RunFailureError } from './direct-runner.js';
+/**
+ * Joins multiple flattened chunk prompts into the persisted `prompt_text` blob.
+ * Exported so the direct-path runner can split `prompt_text` back into the
+ * per-chunk `system`/`user` messages it sends (byte-identical to what BYO shows,
+ * §1 invariant 1).
+ */
+export declare const CHUNK_SEPARATOR = "\n\n=== NEXT PROMPT ===\n\n";
+/**
+ * §7.4 legal transitions. A terminal state has no outgoing edges, which is how
+ * run immutability after `applied` is enforced (any transition off it throws).
+ */
+export declare const LEGAL_RUN_TRANSITIONS: Readonly<Record<LlmRunStatus, readonly LlmRunStatus[]>>;
+export declare function canTransition(from: LlmRunStatus, to: LlmRunStatus): boolean;
+export declare class RunNotFoundError extends Error {
+    readonly runId: string;
+    name: string;
+    constructor(runId: string);
+}
+/** A mutating call targeted a run already in a terminal state (§7.4 immutability). */
+export declare class RunImmutableError extends Error {
+    readonly runId: string;
+    readonly status: LlmRunStatus;
+    name: string;
+    constructor(runId: string, status: LlmRunStatus);
+}
+export declare class InvalidRunTransitionError extends Error {
+    readonly runId: string;
+    readonly from: LlmRunStatus;
+    readonly to: LlmRunStatus;
+    name: string;
+    constructor(runId: string, from: LlmRunStatus, to: LlmRunStatus);
+}
+/**
+ * A BYO run was asked to record a provider/model — forbidden by the §9
+ * telemetry-free guarantee (BYO `provider`/`model` stay NULL, never recorded).
+ */
+export declare class ByoTelemetryError extends Error {
+    name: string;
+    constructor(message: string);
+}
+export interface CreateRunInput {
+    connectionId: string;
+    /** The snapshot the run is built and later validated against (§7.4). */
+    snapshotId: string;
+    /** The classified schema IR (from the snapshot). */
+    schemaIr: DatabaseModel;
+    /** Aggregate statistics (adapter `collectTableStats` output). */
+    stats: readonly StatsResult[];
+    /** Requested output locales; must include `en_US` (enforced by `buildPrompt`). */
+    locales: readonly LocaleCode[];
+    /** Requested decision groups (§4.4); empty ⇒ all sections. */
+    sections: readonly RequestedSection[];
+    /** Sampling opt-in (§4.2); `null` = sample-free (default). */
+    sampling: Sampling;
+    /** `provider` = direct API path, `byo` = copy-paste round-trip. */
+    mode: 'provider' | 'byo';
+    /** Direct path only. MUST be null/undefined for `byo` (§9). */
+    provider?: ProviderId | null;
+    /** Direct path only. MUST be null/undefined for `byo` (§9). */
+    model?: string | null;
+    /** `LLM_ALLOWED_TEMPLATES` / `LLM_ALLOWED_WIDGETS` from `@adminium/widgets`. */
+    allowed: AllowedVocabularies;
+    createdBy?: string | null;
+    /** Override the default input-token budget (§4.5). */
+    tokenBudget?: number;
+}
+export interface CreateRunResult {
+    run: LlmRun;
+    artifact: PromptArtifact;
+}
+/** BYO response intake — everything the shared validation pipeline needs (§7.2). */
+export interface ReceiveResponseInput {
+    /** Raw pasted/received text (a full JSON object, fences/prose tolerated). */
+    text: string;
+    /** 1-based chunk index (unchunked runs omit it). */
+    chunkIndex?: number;
+    /** The classified schema IR the run was built against (from the snapshot). */
+    snapshot: DatabaseModel;
+    /** `LLM_ALLOWED_TEMPLATES` — recommendable page-template ids. */
+    allowedTemplates: readonly string[];
+    /** `LLM_ALLOWED_WIDGETS` — the curated dashboard-widget subset. */
+    allowedWidgets: readonly string[];
+    /** Bundled lucide manifest for the icon-fallback warning (optional). */
+    allowedIcons?: ReadonlySet<string> | readonly string[];
+    /** Stats enabling pseudo-enum acceptance in referential checks (optional). */
+    stats?: readonly StatsResult[];
+    /** Tables present only as chunk context (§4.5). */
+    stubTables?: readonly string[];
+    /**
+     * Validate WITHOUT persisting anything: no `recordResponse`, no status
+     * transition, no chunk counted. The returned `run` is a projection of what the
+     * row WOULD have become, so callers can render the same summary they would
+     * from a real intake.
+     *
+     * This exists because `adminium apply-llm-response --dry-run` promises
+     * "Nothing was written" and validation is the only thing it can honestly do
+     * along the way: intake is a WRITE (it commits the response and flips the run
+     * to `validated`, after which the run can never take a different pasted
+     * response). Doing it and then printing "nothing was written" was the
+     * opposite of the flag. Chunked runs made it worse — a dry run of chunk 1
+     * consumed the slot, so a later real apply of chunk 1 could reach
+     * `chunksReceived === chunksTotal` with chunk 2 never pasted.
+     */
+    dryRun?: boolean;
+}
+export interface ReceiveResponseResult {
+    run: LlmRun;
+    /** The full validation result (errors + warnings + cleaned response). */
+    validation: ValidationResult;
+}
+export interface MarkFailedInput {
+    /** Preserved error list — validation failures and/or a provider transport error (§7.5). */
+    errors?: readonly RunFailureError[];
+    /** Token usage consumed before the failure (recorded for observability). */
+    tokensIn?: number | null;
+    tokensOut?: number | null;
+    durationMs?: number | null;
+}
+/** running → validated persistence for the direct path (T08). */
+export interface RecordDirectResultInput {
+    /** The merged (map-reduce) parsed response (§7.4 `parsed_response`). */
+    response: LlmResponseV1;
+    /** Chunks that validated cleanly (== chunksTotal on success). */
+    chunksReceived: number;
+    tokensIn: number;
+    tokensOut: number;
+    durationMs: number;
+    /** Accumulated per-item errors → `validation_status` `partial` vs `valid`. */
+    validationErrors?: readonly LlmValidationError[] | null;
+}
+export interface MarkAppliedInput {
+    appliedBy?: string | null;
+    /** True when some suggestions were rejected in review → `partially_applied`. */
+    partial?: boolean;
+    review?: LlmRunReview;
+}
+export interface RunServiceDeps {
+    meta: MetaDb;
+    /** Clock override — tests. */
+    now?: () => number;
+}
+export declare function createRunService(deps: RunServiceDeps): {
+    getRun: (runId: string) => Promise<LlmRun | null>;
+    listRuns: (connectionId: string) => Promise<LlmRun[]>;
+    /**
+     * Build the prompt and persist a `draft` run. For BYO runs `provider`/`model`
+     * are forced NULL (§9); passing either is a {@link ByoTelemetryError}. The run
+     * id equals the runId embedded in the prompt (§7.4).
+     */
+    createRun(input: CreateRunInput): Promise<CreateRunResult>;
+    /** draft → running (direct path; T08 calls this before the provider call). */
+    markRunning(runId: string): Promise<LlmRun>;
+    /** draft → awaiting_response (BYO; the run now waits for a pasted response). */
+    markAwaitingResponse(runId: string): Promise<LlmRun>;
+    /**
+     * BYO intake (§7.2): validate a pasted chunk against the run's snapshot and
+     * requested locales. A fatal error keeps the run in `awaiting_response` (the
+     * user can fix and re-paste); a clean parse advances it to `validated` once
+     * every chunk is received.
+     */
+    receiveResponse(runId: string, input: ReceiveResponseInput): Promise<ReceiveResponseResult>;
+    /**
+     * Persist the accepted/rejected suggestion-id lists (§8.3). Allowed once the
+     * run is `validated` and before it terminates; survives reload for re-review.
+     */
+    recordReview(runId: string, review: LlmRunReview): Promise<LlmRun>;
+    /**
+     * validated → applied | partially_applied. The transactional overrides/pages
+     * writes are the apply-EXECUTOR's job (T10b); this only stamps the terminal
+     * run row (and, optionally, the final review).
+     */
+    markApplied(runId: string, input?: MarkAppliedInput): Promise<LlmRun>;
+    /**
+     * running → validated for the direct path (T08). Records the merged parsed
+     * response, token usage and wall-clock duration; `validation_status` is
+     * `partial` when per-item errors survived, else `valid` (§7.4).
+     */
+    recordDirectResult(runId: string, input: RecordDirectResultInput): Promise<LlmRun>;
+    /**
+     * Bump `chunks_received` on a still-`running` chunked run (§7.5 map phase
+     * progress). Best-effort — swallows the terminal/immutable case so a
+     * cancellation racing the update never resurrects a discarded run.
+     */
+    recordChunkProgress(runId: string, chunksReceived: number): Promise<void>;
+    /** running | awaiting_response → failed (repair exhausted / provider error, §7.5). */
+    markFailed(runId: string, input?: MarkFailedInput): Promise<LlmRun>;
+    /** Abandon a non-terminal run (user cancel) → discarded. */
+    discard(runId: string): Promise<LlmRun>;
+};
+export type RunService = ReturnType<typeof createRunService>;
+//# sourceMappingURL=run-service.d.ts.map

package/dist/llm/run-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-service.d.ts","sourceRoot":"","sources":["../../src/llm/run-service.ts"],"names":[],"mappings":"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"}

package/dist/llm/run-service.js

@@ -0,0 +1,343 @@
+/**
+ * LLM run lifecycle service (06-llm-assist.md §7.4, §7.5, §9).
+ *
+ * The shared layer the direct-path runner (T08), the apply executor (T10b), and
+ * the `/api/v1/llm/*` routes (T11) all call. It owns:
+ *  - `createRun` — build the prompt (via the browser-safe `@adminium/llm`
+ *    `buildPrompt`) against the connection's snapshot IR + collected stats,
+ *    persist a `draft` run with its flattened `prompt_text` + `prompt_sha256`,
+ *    and (§9) keep `provider`/`model` NULL for BYO runs;
+ *  - `receiveResponse` — the BYO intake: validate a pasted chunk through the
+ *    shared `validateResponse` pipeline and advance the run (fatal → stays
+ *    `awaiting_response`; clean → `validated`);
+ *  - the §7.4 status machine (legal transitions + run immutability after a
+ *    terminal state).
+ *
+ * Architecture (01 §2.3): the transactional apply-EXECUTOR that writes overrides
+ * /pages lives in T10b, not here — this service persists run rows and validation
+ * outcomes only. Provider NETWORK calls belong to T08's job runner; this service
+ * performs none.
+ */
+import { createHash } from 'node:crypto';
+import { buildPrompt, isTerminalRunStatus, PROMPT_VERSION, validateResponse, } from '@adminium/llm';
+import { llmRunsRepo, newId } from '@adminium/meta';
+/**
+ * Joins multiple flattened chunk prompts into the persisted `prompt_text` blob.
+ * Exported so the direct-path runner can split `prompt_text` back into the
+ * per-chunk `system`/`user` messages it sends (byte-identical to what BYO shows,
+ * §1 invariant 1).
+ */
+export const CHUNK_SEPARATOR = '\n\n=== NEXT PROMPT ===\n\n';
+/**
+ * §7.4 legal transitions. A terminal state has no outgoing edges, which is how
+ * run immutability after `applied` is enforced (any transition off it throws).
+ */
+export const LEGAL_RUN_TRANSITIONS = {
+    draft: ['running', 'awaiting_response', 'failed', 'discarded'],
+    running: ['validated', 'failed', 'discarded'],
+    awaiting_response: ['validated', 'failed', 'discarded'],
+    validated: ['applied', 'partially_applied', 'discarded'],
+    applied: [],
+    partially_applied: [],
+    failed: [],
+    discarded: [],
+};
+export function canTransition(from, to) {
+    return LEGAL_RUN_TRANSITIONS[from].includes(to);
+}
+// ─── Errors ──────────────────────────────────────────────────────────────────
+export class RunNotFoundError extends Error {
+    runId;
+    name = 'RunNotFoundError';
+    constructor(runId) {
+        super(`llm run not found: ${runId}`);
+        this.runId = runId;
+    }
+}
+/** A mutating call targeted a run already in a terminal state (§7.4 immutability). */
+export class RunImmutableError extends Error {
+    runId;
+    status;
+    name = 'RunImmutableError';
+    constructor(runId, status) {
+        super(`llm run ${runId} is ${status} and immutable`);
+        this.runId = runId;
+        this.status = status;
+    }
+}
+export class InvalidRunTransitionError extends Error {
+    runId;
+    from;
+    to;
+    name = 'InvalidRunTransitionError';
+    constructor(runId, from, to) {
+        super(`illegal llm run transition ${from} → ${to} (run ${runId})`);
+        this.runId = runId;
+        this.from = from;
+        this.to = to;
+    }
+}
+/**
+ * A BYO run was asked to record a provider/model — forbidden by the §9
+ * telemetry-free guarantee (BYO `provider`/`model` stay NULL, never recorded).
+ */
+export class ByoTelemetryError extends Error {
+    name = 'ByoTelemetryError';
+    constructor(message) {
+        super(message);
+    }
+}
+// ─── Service ─────────────────────────────────────────────────────────────────
+export function createRunService(deps) {
+    const runs = llmRunsRepo(deps.meta);
+    const now = deps.now ?? Date.now;
+    async function findOrThrow(runId) {
+        const run = await runs.findById(runId);
+        if (run === null)
+            throw new RunNotFoundError(runId);
+        return run;
+    }
+    function assertTransition(run, to) {
+        if (isTerminalRunStatus(run.status))
+            throw new RunImmutableError(run.id, run.status);
+        if (!canTransition(run.status, to)) {
+            throw new InvalidRunTransitionError(run.id, run.status, to);
+        }
+    }
+    /** Move `runId` to `to`, guarding on its current status so the write is atomic. */
+    async function transition(run, to) {
+        assertTransition(run, to);
+        const ok = await runs.updateStatus(run.id, to, { expected: run.status, at: now() });
+        if (!ok) {
+            // The row changed under us (concurrent transition) — re-read and reject.
+            const fresh = await findOrThrow(run.id);
+            throw new InvalidRunTransitionError(run.id, fresh.status, to);
+        }
+        return findOrThrow(run.id);
+    }
+    return {
+        getRun: (runId) => runs.findById(runId),
+        listRuns: (connectionId) => runs.listForConnection(connectionId),
+        /**
+         * Build the prompt and persist a `draft` run. For BYO runs `provider`/`model`
+         * are forced NULL (§9); passing either is a {@link ByoTelemetryError}. The run
+         * id equals the runId embedded in the prompt (§7.4).
+         */
+        async createRun(input) {
+            if (input.mode === 'byo') {
+                if ((input.provider ?? null) !== null || (input.model ?? null) !== null) {
+                    throw new ByoTelemetryError('BYO runs must not record a provider or model (06-llm-assist.md §9).');
+                }
+            }
+            const id = newId('run');
+            const artifact = buildPrompt({
+                snapshotId: input.snapshotId,
+                schemaIr: input.schemaIr,
+                stats: input.stats,
+                locales: input.locales,
+                sections: input.sections,
+                sampling: input.sampling,
+                runId: id,
+            }, {
+                allowed: input.allowed,
+                ...(input.tokenBudget !== undefined ? { tokenBudget: input.tokenBudget } : {}),
+            });
+            const promptText = artifact.chunks.map((chunk) => chunk.byo).join(CHUNK_SEPARATOR);
+            const promptHash = createHash('sha256').update(promptText).digest('hex');
+            const run = await runs.create({
+                id,
+                connectionId: input.connectionId,
+                snapshotId: input.snapshotId,
+                mode: input.mode,
+                provider: input.mode === 'byo' ? null : input.provider ?? null,
+                model: input.mode === 'byo' ? null : input.model ?? null,
+                promptVersion: PROMPT_VERSION,
+                promptHash,
+                promptText,
+                sections: artifact.sections,
+                locales: input.locales,
+                sampling: input.sampling,
+                chunksTotal: artifact.chunks.length,
+                chunksReceived: 0,
+                status: 'draft',
+                createdBy: input.createdBy ?? null,
+            }, now());
+            return { run, artifact };
+        },
+        /** draft → running (direct path; T08 calls this before the provider call). */
+        async markRunning(runId) {
+            const run = await findOrThrow(runId);
+            return transition(run, 'running');
+        },
+        /** draft → awaiting_response (BYO; the run now waits for a pasted response). */
+        async markAwaitingResponse(runId) {
+            const run = await findOrThrow(runId);
+            return transition(run, 'awaiting_response');
+        },
+        /**
+         * BYO intake (§7.2): validate a pasted chunk against the run's snapshot and
+         * requested locales. A fatal error keeps the run in `awaiting_response` (the
+         * user can fix and re-paste); a clean parse advances it to `validated` once
+         * every chunk is received.
+         */
+        async receiveResponse(runId, input) {
+            const run = await findOrThrow(runId);
+            if (isTerminalRunStatus(run.status))
+                throw new RunImmutableError(run.id, run.status);
+            if (run.status !== 'awaiting_response') {
+                throw new InvalidRunTransitionError(run.id, run.status, 'validated');
+            }
+            const validation = validateResponse(input.text, {
+                snapshot: input.snapshot,
+                locales: (run.locales ?? ['en_US']),
+                allowedTemplates: input.allowedTemplates,
+                allowedWidgets: input.allowedWidgets,
+                ...(input.allowedIcons !== undefined ? { allowedIcons: input.allowedIcons } : {}),
+                ...(input.stats !== undefined ? { stats: input.stats } : {}),
+                ...(input.stubTables !== undefined ? { stubTables: input.stubTables } : {}),
+                runId: run.id,
+            });
+            const dryRun = input.dryRun === true;
+            if (validation.response === undefined) {
+                // Fatal (stage 1–4): stays awaiting_response, errors preserved (§7.2/§7.5).
+                if (dryRun) {
+                    return {
+                        run: {
+                            ...run,
+                            validationStatus: 'invalid',
+                            responseRaw: input.text,
+                            validationErrors: validation.errors,
+                        },
+                        validation,
+                    };
+                }
+                await runs.recordResponse(run.id, {
+                    status: 'awaiting_response',
+                    validationStatus: 'invalid',
+                    responseRaw: input.text,
+                    validationErrors: validation.errors,
+                });
+                return { run: await findOrThrow(run.id), validation };
+            }
+            const chunksReceived = Math.min(run.chunksReceived + 1, run.chunksTotal);
+            const allReceived = chunksReceived >= run.chunksTotal;
+            const nextStatus = allReceived ? 'validated' : 'awaiting_response';
+            const validationStatus = validation.errors.length > 0 ? 'partial' : 'valid';
+            if (dryRun) {
+                // The row the caller WOULD have got — computed from the same values the
+                // write below uses, so the projection cannot drift from the real thing.
+                return {
+                    run: {
+                        ...run,
+                        status: nextStatus,
+                        validationStatus,
+                        responseRaw: input.text,
+                        responseJson: validation.response,
+                        validationErrors: validation.errors.length > 0 ? validation.errors : null,
+                        chunksReceived,
+                    },
+                    validation,
+                };
+            }
+            await runs.recordResponse(run.id, {
+                status: nextStatus,
+                validationStatus,
+                responseRaw: input.text,
+                responseJson: validation.response,
+                validationErrors: validation.errors.length > 0 ? validation.errors : null,
+                chunksReceived,
+            });
+            return { run: await findOrThrow(run.id), validation };
+        },
+        /**
+         * Persist the accepted/rejected suggestion-id lists (§8.3). Allowed once the
+         * run is `validated` and before it terminates; survives reload for re-review.
+         */
+        async recordReview(runId, review) {
+            const run = await findOrThrow(runId);
+            if (isTerminalRunStatus(run.status))
+                throw new RunImmutableError(run.id, run.status);
+            if (run.status !== 'validated') {
+                throw new InvalidRunTransitionError(run.id, run.status, run.status);
+            }
+            await runs.recordReview(run.id, review);
+            return findOrThrow(run.id);
+        },
+        /**
+         * validated → applied | partially_applied. The transactional overrides/pages
+         * writes are the apply-EXECUTOR's job (T10b); this only stamps the terminal
+         * run row (and, optionally, the final review).
+         */
+        async markApplied(runId, input = {}) {
+            const run = await findOrThrow(runId);
+            const to = input.partial === true ? 'partially_applied' : 'applied';
+            assertTransition(run, to);
+            await runs.markApplied(run.id, {
+                appliedBy: input.appliedBy ?? null,
+                status: to,
+                ...(input.review !== undefined ? { review: input.review } : {}),
+            }, now());
+            return findOrThrow(run.id);
+        },
+        /**
+         * running → validated for the direct path (T08). Records the merged parsed
+         * response, token usage and wall-clock duration; `validation_status` is
+         * `partial` when per-item errors survived, else `valid` (§7.4).
+         */
+        async recordDirectResult(runId, input) {
+            const run = await findOrThrow(runId);
+            if (isTerminalRunStatus(run.status))
+                throw new RunImmutableError(run.id, run.status);
+            if (run.status !== 'running') {
+                throw new InvalidRunTransitionError(run.id, run.status, 'validated');
+            }
+            const hasItemErrors = (input.validationErrors?.length ?? 0) > 0;
+            await runs.recordResponse(run.id, {
+                status: 'validated',
+                validationStatus: hasItemErrors ? 'partial' : 'valid',
+                responseJson: input.response,
+                validationErrors: hasItemErrors ? input.validationErrors ?? null : null,
+                chunksReceived: input.chunksReceived,
+                tokensIn: input.tokensIn,
+                tokensOut: input.tokensOut,
+                durationMs: input.durationMs,
+            });
+            return findOrThrow(run.id);
+        },
+        /**
+         * Bump `chunks_received` on a still-`running` chunked run (§7.5 map phase
+         * progress). Best-effort — swallows the terminal/immutable case so a
+         * cancellation racing the update never resurrects a discarded run.
+         */
+        async recordChunkProgress(runId, chunksReceived) {
+            const run = await runs.findById(runId);
+            if (run === null || run.status !== 'running')
+                return;
+            await runs.recordResponse(runId, {
+                status: 'running',
+                validationStatus: 'pending',
+                chunksReceived,
+            });
+        },
+        /** running | awaiting_response → failed (repair exhausted / provider error, §7.5). */
+        async markFailed(runId, input = {}) {
+            const run = await findOrThrow(runId);
+            assertTransition(run, 'failed');
+            await runs.recordResponse(run.id, {
+                status: 'failed',
+                validationStatus: 'invalid',
+                validationErrors: input.errors ?? null,
+                ...(input.tokensIn !== undefined ? { tokensIn: input.tokensIn } : {}),
+                ...(input.tokensOut !== undefined ? { tokensOut: input.tokensOut } : {}),
+                ...(input.durationMs !== undefined ? { durationMs: input.durationMs } : {}),
+            });
+            return findOrThrow(run.id);
+        },
+        /** Abandon a non-terminal run (user cancel) → discarded. */
+        async discard(runId) {
+            const run = await findOrThrow(runId);
+            return transition(run, 'discarded');
+        },
+    };
+}
+//# sourceMappingURL=run-service.js.map