@lincyaw/kernel 1.0.0-rc.0 → 1.0.0-rc.2

package/src/node/resources.ts

@@ -0,0 +1,86 @@
+import { spawn } from 'node:child_process'
+import type { ChildProcess, SpawnOptions } from 'node:child_process'
+import { availableParallelism, constants, freemem, loadavg, setPriority } from 'node:os'
+import { TYPESCRIPT_IMPORT } from './packages.ts'
+
+const THREAD_VARIABLES = ['GOMAXPROCS', 'RAYON_NUM_THREADS', 'OMP_NUM_THREADS', 'OPENBLAS_NUM_THREADS', 'MKL_NUM_THREADS', 'BLIS_NUM_THREADS', 'VECLIB_MAXIMUM_THREADS', 'NUMEXPR_MAX_THREADS', 'NUMEXPR_NUM_THREADS', 'POLARS_MAX_THREADS']
+export const NODE_RESOURCE_ARGS: readonly string[] = ['--v8-pool-size=1']
+
+/**
+ * `interactive`: what the author waits for, the workspace service and the previews' dev servers; `background`: what
+ * runs while the author does something else, builds, exports and code runs.
+ */
+export type ResourceClass = 'interactive' | 'background'
+
+/** What the machine has now: its processors, how many of them are busy (the one-minute load), and its free memory. */
+export interface MachineState {
+  cpus: number
+  load: number
+  free: number
+}
+
+export function machineState(): MachineState {
+  return { cpus: availableParallelism(), load: loadavg()[0] ?? 0, free: freemem() }
+}
+
+// Bundlers gain little from more threads than this, and each thread holds memory.
+const INTERACTIVE_MAX = 8
+// Below this much free memory an interactive child takes two threads at most.
+const LOW_MEMORY = 2 * 1024 ** 3
+
+/**
+ * The native threads a child may use. A background child keeps to the operator's `PRESMIUM_MAX_THREADS`, one by default
+ * and at most half the processors. An interactive child takes three quarters of the processors that are idle now (all
+ * of them where the load is not known, as on Windows), keeping one for the rest of the machine, at most eight, and two
+ * when memory is short; `PRESMIUM_MAX_THREADS` caps it.
+ */
+export function threadBudget(kind: ResourceClass, source: NodeJS.ProcessEnv = process.env, machine: MachineState = machineState()): number {
+  const requested = Number(source.PRESMIUM_MAX_THREADS)
+  const operator = Number.isInteger(requested) && requested > 0 ? requested : undefined
+  if (kind === 'background') return Math.min(operator ?? 1, Math.max(1, Math.floor(machine.cpus / 2)))
+  const idle = Math.max(1, machine.cpus - Math.min(machine.load, machine.cpus))
+  let threads = Math.max(1, Math.min(Math.floor(idle * 0.75), machine.cpus - 1, INTERACTIVE_MAX))
+  if (machine.free < LOW_MEMORY) threads = Math.min(threads, 2)
+  return operator === undefined ? threads : Math.min(threads, operator)
+}
+
+/** Bound native thread pools as well as JS jobs; leave CPU capacity for other apps. */
+export function resourceEnvironment(source: NodeJS.ProcessEnv = process.env, kind: ResourceClass = 'background', machine?: MachineState): Record<string, string> {
+  const env = Object.fromEntries(Object.entries(source).filter((entry): entry is [string, string] => entry[1] !== undefined))
+  const threads = threadBudget(kind, source, machine)
+  if (source.PRESMIUM_MAX_THREADS !== undefined && kind === 'background') env.PRESMIUM_MAX_THREADS = String(threads)
+  for (const name of THREAD_VARIABLES) {
+    const current = Number(source[name])
+    // An interactive child takes its own budget: a smaller value it inherited came from a background parent's limit.
+    env[name] = String(kind === 'background' && Number.isInteger(current) && current > 0 ? Math.min(current, threads) : threads)
+  }
+  const ioThreads = Number(source.UV_THREADPOOL_SIZE)
+  env.UV_THREADPOOL_SIZE = kind === 'interactive'
+    ? String(Math.max(4, threads))
+    : String(Number.isInteger(ioThreads) && ioThreads > 0 ? Math.min(ioThreads, 2) : 2)
+  return env
+}
+
+/** Node's own arguments for a child: V8's background pool as large as its thread budget. */
+export function nodeResourceArgs(kind: ResourceClass, source: NodeJS.ProcessEnv = process.env, machine?: MachineState): string[] {
+  return kind === 'background' ? [...NODE_RESOURCE_ARGS] : [`--v8-pool-size=${threadBudget(kind, source, machine)}`]
+}
+
+/** Child priorities are best effort on platforms that restrict changing niceness. */
+export function backgroundPriority(pid: number | undefined): void {
+  if (pid === undefined) return
+  try { setPriority(pid, constants.priority.PRIORITY_BELOW_NORMAL) } catch {}
+}
+
+/** Starts Node on `script` as a background child: one V8 worker, bounded thread pools, TypeScript imports and a lower priority. */
+export function spawnBackgroundNode(script: string, args: readonly string[], options: SpawnOptions = {}): ChildProcess {
+  const child = spawn(process.execPath, [...NODE_RESOURCE_ARGS, ...TYPESCRIPT_IMPORT, script, ...args], { env: resourceEnvironment(), ...options })
+  backgroundPriority(child.pid)
+  return child
+}
+
+/** Starts Node on `script` as a child the author waits for: the interactive thread budget at normal priority, with TypeScript imports. */
+export function spawnInteractiveNode(script: string, args: readonly string[], options: SpawnOptions = {}): ChildProcess {
+  const machine = machineState()
+  return spawn(process.execPath, [...nodeResourceArgs('interactive', process.env, machine), ...TYPESCRIPT_IMPORT, script, ...args], { env: resourceEnvironment(process.env, 'interactive', machine), ...options })
+}

package/src/node/revision.ts

@@ -0,0 +1,6 @@
+import { createHash } from 'node:crypto'
+import type { IRDocument } from '../ir.ts'
+
+export function irRevision(doc: IRDocument): string {
+  return createHash('sha256').update(JSON.stringify(doc)).digest('hex').slice(0, 16)
+}

package/src/node/run-directory.ts

@@ -0,0 +1,70 @@
+import { spawn } from 'node:child_process'
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import type { ProcessSandbox, SandboxResult, SandboxRun } from '../contracts/execution.ts'
+import { backgroundPriority, resourceEnvironment } from './resources.ts'
+
+/** The runner reads its requests from this file of the run directory (`runner.py`, the script and WASI runners). */
+export const RUN_REQUEST_FILE = '.presmium/request.json'
+
+export const RUN_RESULT_PREFIX = '.presmium/result-'
+
+/** The runner writes the result of the request at this index here, once it is complete. */
+export function runResultFile(index: number): string {
+  return `${RUN_RESULT_PREFIX}${index}.json`
+}
+
+/** The environment of a run that is given none: `PATH`, `LANG` and a temporary `HOME`, no credentials. */
+export function minimalRunEnv(): Record<string, string> {
+  const home = join(tmpdir(), 'presmium-home')
+  mkdirSync(home, { recursive: true })
+  return { PATH: process.env.PATH ?? '', LANG: process.env.LANG ?? 'C.UTF-8', HOME: home }
+}
+
+/** The process sandbox when none is configured: runs the command directly, in a new temporary run directory. */
+export const directSandbox: ProcessSandbox = {
+  kind: 'none',
+  run(request: SandboxRun): Promise<SandboxResult> {
+    const dir = mkdtempSync(join(tmpdir(), 'presmium-run-'))
+    for (const [path, content] of Object.entries(request.files)) {
+      mkdirSync(dirname(join(dir, path)), { recursive: true })
+      writeFileSync(join(dir, path), content)
+    }
+    return new Promise((resolve) => {
+      const [command, ...args] = request.argv
+      const child = spawn(command!, args, { cwd: dir, env: resourceEnvironment(request.env), stdio: ['ignore', 'pipe', 'pipe'] })
+      backgroundPriority(child.pid)
+      const out: Buffer[] = []
+      const err: Buffer[] = []
+      let stopped = false
+      const stop = () => {
+        stopped = true
+        child.kill('SIGKILL')
+      }
+      const timer = setTimeout(stop, request.timeoutMs)
+      if (request.signal?.aborted) stop()
+      request.signal?.addEventListener('abort', stop, { once: true })
+      child.stdout.on('data', (chunk: Buffer) => out.push(chunk))
+      child.stderr.on('data', (chunk: Buffer) => err.push(chunk))
+      let settled = false
+      const finish = (exitCode: number | null, error?: Error) => {
+        if (settled) return
+        settled = true
+        clearTimeout(timer)
+        request.signal?.removeEventListener('abort', stop)
+        const files: Record<string, Uint8Array> = {}
+        for (const path of request.collect) {
+          try {
+            files[path] = readFileSync(join(dir, path))
+          } catch {}
+        }
+        rmSync(dir, { recursive: true, force: true })
+        const stderr = Buffer.concat(err).toString('utf8').replaceAll(dir, '.')
+        resolve({ exitCode: stopped ? null : exitCode, stdout: Buffer.concat(out).toString('utf8'), stderr: error ? `${stderr}${error.message}` : stderr, files })
+      }
+      child.on('error', error => finish(null, error))
+      child.on('close', code => finish(code))
+    })
+  },
+}

package/src/node/transcription-adoption.ts

@@ -0,0 +1,9 @@
+import { Validator } from '@cfworker/json-schema'
+import type { Schema } from '@cfworker/json-schema'
+import { TRANSCRIPTION_ADOPTION_APPLY_SCHEMA, TRANSCRIPTION_ADOPTION_DRAFT_SCHEMA } from '../contracts/transcription-adoption.ts'
+import type { TranscriptionAdoptionApply, TranscriptionAdoptionDraft } from '../contracts/transcription-adoption.ts'
+
+const draft = new Validator(structuredClone(TRANSCRIPTION_ADOPTION_DRAFT_SCHEMA) as unknown as Schema, '2020-12', false)
+const apply = new Validator(structuredClone(TRANSCRIPTION_ADOPTION_APPLY_SCHEMA) as unknown as Schema, '2020-12', false)
+export function validateTranscriptionAdoptionDraft(value: unknown): value is TranscriptionAdoptionDraft { return draft.validate(value).valid }
+export function validateTranscriptionAdoptionApply(value: unknown): value is TranscriptionAdoptionApply { return apply.validate(value).valid }

package/src/node/transcription.ts

@@ -0,0 +1,10 @@
+import { Validator } from '@cfworker/json-schema'
+import type { Schema } from '@cfworker/json-schema'
+import { DOCUMENT_TRANSCRIPTION_REQUEST_SCHEMA } from '../contracts/transcription.ts'
+import type { DocumentTranscriptionRequest } from '../contracts/transcription.ts'
+
+const requestValidator = new Validator(structuredClone(DOCUMENT_TRANSCRIPTION_REQUEST_SCHEMA) as unknown as Schema, '2020-12', false)
+
+export function validateDocumentTranscriptionRequest(value: unknown): value is DocumentTranscriptionRequest {
+  return requestValidator.validate(value).valid
+}

package/src/node/voiceover-routes.ts

@@ -0,0 +1,73 @@
+import { errorMessage, hasRole, isRecord, jsonResponse } from '../index.ts'
+import type { DocumentVoiceTasks, VoicePreviewCheck, VoicePreviewStart, VoiceoverStart } from '../contracts/voiceover-execution.ts'
+import type { Route } from '../contracts/server.ts'
+import { validateVoiceoverJobQuery, validateVoiceoverStart, validateVoicePreviewCheck, validateVoicePreviewStart, VoiceoverOperationError } from './voiceover.ts'
+
+/** The legacy Web wire shapes adapt to the same author service used by MCP. */
+export function createVoiceoverRoutes(service: DocumentVoiceTasks): Record<string, Route> {
+  const route = (handle: Route['handle']): Route => ({ role: 'editor', maxBody: 64 << 10, async handle(request, ctx) {
+    try {
+      if (!hasRole(ctx.member, 'editor')) throw new VoiceoverOperationError(403, 'voice-authoring-permission-denied')
+      return await handle(request, ctx)
+    } catch (error) {
+      const status = isRecord(error) && typeof error.status === 'number' ? error.status : 502
+      return jsonResponse({ error: errorMessage(error) }, status)
+    }
+  } })
+  const body = async (request: Request) => await request.json().catch(() => undefined) as unknown
+  const confirmed = (value: unknown) => {
+    if (!isRecord(value)) throw new VoiceoverOperationError(400, 'voice-generation-invalid')
+    if (value.confirmed !== true) throw new VoiceoverOperationError(409, 'voice-confirmation-required')
+    const { confirmed: _confirmed, ...request } = value
+    return request
+  }
+  return {
+    voiceover: route(async (request, ctx) => {
+      if (request.method === 'GET') return jsonResponse(await service.snapshot(ctx.document, {}, ctx.member, request.signal))
+      if (request.method !== 'POST') throw new VoiceoverOperationError(405, 'GET or POST')
+      const value = confirmed(await body(request))
+      if (!validateVoiceoverStart(value)) throw new VoiceoverOperationError(400, 'voice-generation-invalid')
+      return jsonResponse(await service.start(ctx.document, value as VoiceoverStart, ctx.member, request.signal), 202)
+    }),
+    'voiceover/jobs': route(async (request, ctx) => {
+      if (request.method !== 'GET') throw new VoiceoverOperationError(405, 'GET')
+      return jsonResponse(await service.listJobs(ctx.document, ctx.member))
+    }),
+    'voiceover/job': route(async (request, ctx) => {
+      if (request.method !== 'GET') throw new VoiceoverOperationError(405, 'GET')
+      const query = Object.fromEntries([...new URL(request.url).searchParams].filter(([key]) => key !== 'document'))
+      if (!validateVoiceoverJobQuery(query)) throw new VoiceoverOperationError(400, 'voice-job-query-invalid')
+      return jsonResponse(await service.getJob(ctx.document, query, ctx.member))
+    }),
+    'voiceover/cancel': route(async (request, ctx) => {
+      if (request.method !== 'POST') throw new VoiceoverOperationError(405, 'POST')
+      const value = await body(request)
+      if (!validateVoiceoverJobQuery(value)) throw new VoiceoverOperationError(400, 'voice-cancel-invalid')
+      const answer = await service.cancel(ctx.document, value, ctx.member)
+      return jsonResponse('id' in value ? answer.job : answer)
+    }),
+    'voice-preview': route(async (request, ctx) => {
+      if (request.method === 'GET') {
+        const params = new URL(request.url).searchParams
+        let voice: unknown, target: unknown, source: unknown
+        try { voice = JSON.parse(params.get('voice') ?? 'null'); target = JSON.parse(params.get('target') ?? 'null'); source = JSON.parse(params.get('source') ?? 'null') }
+        catch { throw new VoiceoverOperationError(400, 'voice-preview-invalid') }
+        const query = { revision: params.get('revision'), voice, mode: params.get('mode'), ...target !== null ? { target } : {}, ...source !== null ? { source } : {} }
+        if (!validateVoicePreviewCheck(query)) throw new VoiceoverOperationError(400, 'voice-preview-invalid')
+        return jsonResponse(await service.quotePreview(ctx.document, query as VoicePreviewCheck, ctx.member, request.signal))
+      }
+      if (request.method !== 'POST') throw new VoiceoverOperationError(405, 'GET or POST')
+      const value = confirmed(await body(request))
+      if (!validateVoicePreviewStart(value)) throw new VoiceoverOperationError(400, 'voice-preview-invalid')
+      const result = await service.preview(ctx.document, value as VoicePreviewStart, ctx.member, request.signal)
+      const { resource, bytes } = await service.readPreview(ctx.document, result.id, ctx.member)
+      const { id: _id, byteLength: _length, sha256: _sha, mediaType, ...answer } = resource
+      return jsonResponse({ ...answer, audio: `data:${mediaType};base64,${Buffer.from(bytes).toString('base64')}` })
+    }),
+    'voice-preview/media': route(async (request, ctx) => {
+      if (request.method !== 'GET') throw new VoiceoverOperationError(405, 'GET')
+      const id = new URL(request.url).searchParams.get('id') ?? '', result = await service.readPreview(ctx.document, id, ctx.member)
+      return new Response(new Uint8Array(result.bytes), { headers: { 'Content-Type': result.resource.mediaType, 'Content-Length': String(result.bytes.byteLength), 'Cache-Control': 'no-store' } })
+    }),
+  }
+}

package/src/node/voiceover.ts

@@ -0,0 +1,199 @@
+import { createHash, randomUUID } from 'node:crypto'
+import { Validator } from '@cfworker/json-schema'
+import type { Schema } from '@cfworker/json-schema'
+import { VOICEOVER_JOB_QUERY_SCHEMA, VOICEOVER_START_SCHEMA, VOICEOVER_STATUS_SCHEMA, VOICE_PREVIEW_CHECK_SCHEMA, VOICE_PREVIEW_START_SCHEMA } from '../contracts/voiceover-execution.ts'
+import type { VoiceoverExecution, VoiceoverJobQuery, VoiceoverObservation, VoiceoverStart, VoiceoverStatusQuery, VoicePreviewCheck, VoicePreviewResource, VoicePreviewResourceData, VoicePreviewStart } from '../contracts/voiceover-execution.ts'
+import type { CanonicalSource } from '../ir.ts'
+import type { VoiceoverCancellation, VoiceoverJob, VoicePreviewQuote } from '../contracts/voice.ts'
+
+const validator = <T>(schema: unknown) => { const checked = new Validator(structuredClone(schema) as Schema, '2020-12', false); return (value: unknown): value is T => checked.validate(value).valid }
+export const validateVoiceoverStart = validator<VoiceoverStart>(VOICEOVER_START_SCHEMA)
+export const validateVoiceoverStatus = validator<VoiceoverStatusQuery>(VOICEOVER_STATUS_SCHEMA)
+export const validateVoiceoverJobQuery = validator<VoiceoverJobQuery>(VOICEOVER_JOB_QUERY_SCHEMA)
+export const validateVoicePreviewCheck = validator<VoicePreviewCheck>(VOICE_PREVIEW_CHECK_SCHEMA)
+export const validateVoicePreviewStart = validator<VoicePreviewStart>(VOICE_PREVIEW_START_SCHEMA)
+export class VoiceoverOperationError extends Error {
+  readonly status: number
+  constructor(status: number, message: string) { super(message); this.status = status }
+}
+type Load = (source: CanonicalSource | undefined, signal: AbortSignal) => Promise<VoiceoverExecution>
+interface ActiveJob { job: VoiceoverJob, controller: AbortController }
+interface Intent { payload?: string, controller: AbortController, job?: ActiveJob, state: 'preparing' | 'cancelled' | 'failed', error?: string, finished: Promise<void>, finish(): void }
+const MAX_INTENTS = 1024, RECENT_JOBS = 20, MAX_OPERATIONS = 4, MAX_QUOTES = 64, QUOTE_MS = 120_000, MAX_PREVIEWS = 8, MAX_MEDIA_BYTES = 16 << 20
+const digest = (value: unknown) => createHash('sha256').update(JSON.stringify(value)).digest('hex')
+const targetKey = (target: { section: string, step: number, binding: string }) => [target.section, target.step, target.binding]
+const sourceKey = (source?: CanonicalSource) => source && [source.documentId, source.version, source.fingerprint]
+const startPayload = (request: VoiceoverStart) => digest([request.revision, sourceKey(request.source), request.scope.kind, request.scope.kind === 'page' ? request.scope.section : request.scope.kind === 'step' ? targetKey(request.scope.target) : request.scope.kind === 'steps' ? [...new Set(request.scope.targets.map(target => JSON.stringify(targetKey(target))))].sort() : []])
+const previewPayload = (request: VoicePreviewCheck) => digest([sourceKey(request.source), request.revision, request.voice.engine, request.voice.voice, request.voice.rate, request.voice.style, request.mode, request.target && targetKey(request.target)])
+
+/** The existing in-process intent/job coordinator, shared by Workspace and standalone lecture servers. */
+export function createVoiceoverOwner() {
+  const jobs = new Map<string, ActiveJob>(), intents = new Map<string, Intent>()
+  const operations = new Set<{ controller: AbortController, finished: Promise<unknown> }>()
+  const quotes = new Map<string, { value: VoicePreviewQuote, underlying: string, execution: VoiceoverExecution, expires: number }>()
+  const media = new Map<string, VoicePreviewResourceData>()
+  let closed = false
+  const available = () => { if (closed) throw new VoiceoverOperationError(503, 'voice-service-closing') }
+  const work = <T>(signal: AbortSignal | undefined, run: (signal: AbortSignal) => Promise<T>): Promise<T> => {
+    available(); signal?.throwIfAborted()
+    if (operations.size >= MAX_OPERATIONS) throw new VoiceoverOperationError(503, 'voice-authoring-busy')
+    const controller = new AbortController(), combined = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal
+    const operation = { controller, finished: Promise.resolve() as Promise<unknown> }
+    operations.add(operation)
+    const finished = Promise.resolve().then(() => { available(); combined.throwIfAborted(); return run(combined) }).catch(error => { if (closed) throw new VoiceoverOperationError(503, 'voice-service-closing'); throw error }).finally(() => operations.delete(operation))
+    operation.finished = finished
+    return finished
+  }
+  const patch = (job: VoiceoverJob, value: Partial<VoiceoverJob>) => {
+    if (Object.entries(value).some(([key, value]) => job[key as keyof VoiceoverJob] !== value)) { Object.assign(job, value); job.sequence++ }
+  }
+  const newIntent = (id: string, payload?: string): Intent => {
+    if (intents.size >= MAX_INTENTS) throw new VoiceoverOperationError(503, 'voice-intent-capacity')
+    let finish!: () => void
+    const finished = new Promise<void>(resolve => { finish = resolve })
+    const intent: Intent = { payload, controller: new AbortController(), state: 'preparing', finished, finish }
+    intents.set(id, intent)
+    return intent
+  }
+  const cancelJob = (entry: ActiveJob) => {
+    if (entry.job.state === 'queued' || entry.job.state === 'running') {
+      const queued = entry.job.state === 'queued'
+      patch(entry.job, { state: queued ? 'cancelled' : 'cancelling', ...queued ? { finishedAt: new Date().toISOString() } : {} })
+      entry.controller.abort(new Error('voice-cancelled'))
+    }
+  }
+  const find = (query: VoiceoverJobQuery): Intent | undefined => 'intent' in query ? intents.get(query.intent) : [...intents.values()].find(intent => intent.job?.job.id === query.id)
+  const observation = (id: string, intent: Intent): VoiceoverObservation => ({ intent: id, state: intent.job?.job.state ?? (intent.state === 'preparing' ? 'queued' : intent.state), ...intent.job ? { job: structuredClone(intent.job.job) } : {}, ...intent.error ? { error: intent.error } : {} })
+  return {
+    limits: { intents: MAX_INTENTS, recentJobs: RECENT_JOBS, concurrent: MAX_OPERATIONS, quotes: MAX_QUOTES, quoteLifetimeMs: QUOTE_MS, previewBytes: 8 << 20, previewResources: MAX_PREVIEWS, retainedPreviewBytes: MAX_MEDIA_BYTES },
+    snapshot(query: VoiceoverStatusQuery, load: Load, signal?: AbortSignal) {
+      if (!validateVoiceoverStatus(query)) throw new VoiceoverOperationError(400, 'voice-status-invalid')
+      return work(signal, async signal => { const execution = await load(query.source, signal), status = await execution.status(query, signal); signal.throwIfAborted(); return { ...status, jobs: [...jobs.values()].map(entry => structuredClone(entry.job)) } })
+    },
+    list() { available(); return [...jobs.values()].map(entry => structuredClone(entry.job)) },
+    get(query: VoiceoverJobQuery): VoiceoverObservation {
+      available()
+      if (!validateVoiceoverJobQuery(query)) throw new VoiceoverOperationError(400, 'voice-job-query-invalid')
+      const intent = find(query)
+      if (!intent) throw new VoiceoverOperationError(404, 'voice-job-unknown')
+      return observation('intent' in query ? query.intent : intent.job!.job.intent, intent)
+    },
+    cancel(query: VoiceoverJobQuery): VoiceoverCancellation {
+      available()
+      if (!validateVoiceoverJobQuery(query)) throw new VoiceoverOperationError(400, 'voice-cancel-invalid')
+      const intent = 'intent' in query ? intents.get(query.intent) ?? newIntent(query.intent) : find(query)
+      if (!intent) throw new VoiceoverOperationError(404, 'voice-job-unknown')
+      if (intent.job) cancelJob(intent.job)
+      else { intent.state = 'cancelled'; intent.controller.abort(new Error('voice-cancelled')); if (!intent.payload) intent.finish() }
+      return observation('intent' in query ? query.intent : intent.job!.job.intent, intent)
+    },
+    /** Cancellation that would change nothing (the job or intent already ended) is answered here, without asking. */
+    checkCancel(query: VoiceoverJobQuery): VoiceoverCancellation | undefined {
+      available()
+      if (!validateVoiceoverJobQuery(query)) throw new VoiceoverOperationError(400, 'voice-cancel-invalid')
+      const intent = find(query)
+      if (!intent) { if ('intent' in query) return undefined; throw new VoiceoverOperationError(404, 'voice-job-unknown') }
+      const state = intent.job?.job.state ?? intent.state
+      return state === 'queued' || state === 'running' || state === 'preparing' ? undefined : observation('intent' in query ? query.intent : intent.job!.job.intent, intent)
+    },
+    /** The same admission as start, released at once: a request that passes would be admitted unless the document changes. */
+    checkStart(request: VoiceoverStart, load: Load, signal?: AbortSignal): Promise<void> {
+      if (!validateVoiceoverStart(request)) throw new VoiceoverOperationError(400, 'voice-generation-invalid')
+      return work(signal, async signal => {
+        const known = intents.get(request.intent)
+        if (known?.payload && known.payload !== startPayload(request)) throw new VoiceoverOperationError(409, 'voice-intent-changed')
+        if (known?.job) return
+        if (known?.state === 'cancelled') throw new VoiceoverOperationError(409, 'voice-cancelled')
+        if (known?.state === 'failed') throw new VoiceoverOperationError(409, 'voice-intent-failed')
+        if (known) throw new VoiceoverOperationError(409, 'voice-job-busy')
+        const execution = await load(request.source, signal)
+        ;(await execution.prepare(structuredClone(request), signal)).dispose()
+      })
+    },
+    checkPreview(request: VoicePreviewStart, signal?: AbortSignal): Promise<void> {
+      if (!validateVoicePreviewStart(request)) throw new VoiceoverOperationError(400, 'voice-preview-invalid')
+      return work(signal, async signal => {
+        const quoted = quotes.get(request.quote)
+        if (!quoted || quoted.expires < Date.now() || previewPayload(quoted.value) !== previewPayload(request)) throw new VoiceoverOperationError(409, 'voice-preview-changed')
+        const { quote: _, ...check } = request
+        if ((await quoted.execution.quote(check, signal)).quote !== quoted.underlying) throw new VoiceoverOperationError(409, 'voice-preview-changed')
+      })
+    },
+    start(request: VoiceoverStart, load: Load, signal?: AbortSignal): Promise<VoiceoverJob> {
+      if (!validateVoiceoverStart(request)) throw new VoiceoverOperationError(400, 'voice-generation-invalid')
+      request = structuredClone(request)
+      return work(signal, async signal => {
+        const payload = startPayload(request), known = intents.get(request.intent)
+        if (known?.payload && known.payload !== payload) throw new VoiceoverOperationError(409, 'voice-intent-changed')
+        if (known?.job) return structuredClone(known.job.job)
+        if (known?.state === 'cancelled') throw new VoiceoverOperationError(409, 'voice-cancelled')
+        if (known?.state === 'failed') throw new VoiceoverOperationError(409, 'voice-intent-failed')
+        if (known) throw new VoiceoverOperationError(409, 'voice-job-busy')
+        const intent = newIntent(request.intent, payload), combined = AbortSignal.any([signal, intent.controller.signal])
+        let prepared: Awaited<ReturnType<VoiceoverExecution['prepare']>> | undefined, admitted = false
+        try {
+          combined.throwIfAborted()
+          const execution = await load(request.source, combined)
+          combined.throwIfAborted(); prepared = await execution.prepare(request, combined); combined.throwIfAborted(); available()
+          const job: VoiceoverJob = { id: randomUUID(), sequence: 1, intent: request.intent, source: prepared.source, revision: prepared.revision, scope: prepared.scope, state: 'queued', total: prepared.total, completed: 0, failed: 0, createdAt: new Date().toISOString() }
+          const entry = { job, controller: intent.controller }, task = prepared
+          intent.job = entry; jobs.set(job.id, entry); admitted = true
+          void Promise.resolve().then(async () => {
+            if (job.state !== 'queued') return
+            patch(job, { state: 'running', startedAt: new Date().toISOString() })
+            try { const result = await task.run(intent.controller.signal, progress => patch(job, progress)); patch(job, { ...result, finishedAt: new Date().toISOString() }) }
+            catch (error) { patch(job, { state: intent.controller.signal.aborted ? 'cancelled' : 'failed', error: error instanceof Error ? error.message : String(error), finishedAt: new Date().toISOString() }) }
+          }).finally(() => { task.dispose(); intent.finish() })
+          for (const [id, old] of jobs) if (jobs.size > RECENT_JOBS && !['queued', 'running', 'cancelling'].includes(old.job.state)) jobs.delete(id)
+          return structuredClone(job)
+        } catch (error) {
+          const intentCancelled = intent.controller.signal.aborted
+          intent.state = combined.aborted ? 'cancelled' : 'failed'; intent.error = error instanceof Error ? error.message : String(error)
+          intent.controller.abort(error)
+          if (closed) throw new VoiceoverOperationError(503, 'voice-service-closing')
+          if (intentCancelled) throw new VoiceoverOperationError(409, 'voice-cancelled')
+          throw error
+        } finally { if (!admitted) { prepared?.dispose(); intent.finish() } }
+      })
+    },
+    quote(query: VoicePreviewCheck, load: Load, signal?: AbortSignal): Promise<VoicePreviewQuote> {
+      if (!validateVoicePreviewCheck(query)) throw new VoiceoverOperationError(400, 'voice-preview-invalid')
+      return work(signal, async signal => {
+        const execution = await load(query.source, signal), quoted = await execution.quote(query, signal)
+        signal.throwIfAborted(); available()
+        const token = digest([randomUUID(), quoted.quote]), value = { ...quoted, quote: token }
+        quotes.set(token, { value, underlying: quoted.quote, execution, expires: Date.now() + QUOTE_MS })
+        while (quotes.size > MAX_QUOTES) quotes.delete(quotes.keys().next().value!)
+        return structuredClone(value)
+      })
+    },
+    preview(request: VoicePreviewStart, signal?: AbortSignal): Promise<VoicePreviewResource> {
+      if (!validateVoicePreviewStart(request)) throw new VoiceoverOperationError(400, 'voice-preview-invalid')
+      return work(signal, async signal => {
+        const quoted = quotes.get(request.quote)
+        if (!quoted || quoted.expires < Date.now() || previewPayload(quoted.value) !== previewPayload(request)) throw new VoiceoverOperationError(409, 'voice-preview-changed')
+        const value = await quoted.execution.preview({ ...request, quote: quoted.underlying }, signal)
+        signal.throwIfAborted(); available()
+        if (value.bytes.byteLength > 8 << 20) throw new VoiceoverOperationError(413, 'voice-preview-too-large')
+        const { bytes, ...answer } = value, resource: VoicePreviewResource = { ...answer, id: randomUUID(), byteLength: bytes.byteLength, sha256: createHash('sha256').update(bytes).digest('hex') }
+        media.set(resource.id, { resource, bytes: new Uint8Array(bytes) })
+        while (media.size > MAX_PREVIEWS || [...media.values()].reduce((sum, value) => sum + value.bytes.byteLength, 0) > MAX_MEDIA_BYTES) media.delete(media.keys().next().value!)
+        return structuredClone(resource)
+      })
+    },
+    readPreview(id: string): VoicePreviewResourceData {
+      available()
+      const value = media.get(id)
+      if (!value) throw new VoiceoverOperationError(404, 'voice-preview-resource-unknown')
+      return { resource: structuredClone(value.resource), bytes: new Uint8Array(value.bytes) }
+    },
+    async close() {
+      closed = true
+      for (const operation of operations) operation.controller.abort(new Error('voice-service-closing'))
+      for (const intent of intents.values()) { if (intent.job) cancelJob(intent.job); else intent.controller.abort(new Error('voice-service-closing')) }
+      await Promise.allSettled([...operations].map(operation => operation.finished))
+      await Promise.allSettled([...intents.values()].map(intent => intent.finished))
+      quotes.clear(); media.clear()
+    },
+  }
+}