@lincyaw/kernel 0.0.0-stage → 1.0.0-rc.1

package/src/node/index.ts

@@ -0,0 +1,29 @@
+export { copyPublished, productionAssetFile } from './assets.ts'
+export { fileVersion } from './file-version.ts'
+export { DOCUMENT_CHANGE_JSON_SCHEMA, validateDocumentChange, validateDocumentPageChange, validateDocumentPageChangeApply, validateDocumentPageDuplication, validateDocumentPageDuplicationApply } from '../authoring.ts'
+export { validateDocumentOutlineQuery, validateDocumentPartQuery } from './document-reads.ts'
+export { DOCUMENT_AUTHORING_ACTION_SCHEMA, DOCUMENT_AUTHORING_ACTION_APPLY_SCHEMA, DOCUMENT_AUTHORING_ACTION_IMPACT_SCHEMA, validateDocumentAuthoringAction, validateDocumentAuthoringActionReference, validateDocumentAuthoringActionImpact } from './authoring-actions.ts'
+export { validateDocumentTranscriptionRequest } from './transcription.ts'
+export { validateDocumentRecordingAdoption, validateDocumentAudioInspect, validateDocumentWorkspaceAudioImport, validateDocumentWorkspaceAudioInspect, validateDocumentMediaClipValidation, validateDocumentMediaClipEdit, validateDocumentProductionPlanQuery } from './document-audio.ts'
+export { validateDocumentVoiceCatalogQuery } from './document-voice.ts'
+export { createVoiceoverOwner, VoiceoverOperationError, validateVoiceoverStart, validateVoiceoverStatus, validateVoiceoverJobQuery, validateVoicePreviewCheck, validateVoicePreviewStart } from './voiceover.ts'
+export { createVoiceoverRoutes } from './voiceover-routes.ts'
+export { validateTranscriptionAdoptionDraft, validateTranscriptionAdoptionApply } from './transcription-adoption.ts'
+export { FONT_LICENSE, fontLicense } from './fonts.ts'
+export { findPackageBin, importSpecifier, literalGlob, packageOf, playwrightChromium, TYPESCRIPT_IMPORT } from './packages.ts'
+export { ffmpegInstallCommand, findFfmpeg } from './ffmpeg.ts'
+export type { Ffmpeg } from './ffmpeg.ts'
+export { bracketIPv6, lanAddresses } from './network.ts'
+export { forEachLine } from './lines.ts'
+export { isInside } from './paths.ts'
+export { backgroundPriority, machineState, NODE_RESOURCE_ARGS, nodeResourceArgs, resourceEnvironment, spawnBackgroundNode, spawnInteractiveNode, threadBudget } from './resources.ts'
+export type { MachineState, ResourceClass } from './resources.ts'
+export { irRevision } from './revision.ts'
+export { findInstalledPackage } from './installed-packages.ts'
+export { directSandbox, minimalRunEnv, RUN_REQUEST_FILE, RUN_RESULT_PREFIX, runResultFile } from './run-directory.ts'
+export { validateDocumentHistoryQuery, validateDocumentHistoryRead, validateDocumentHistoryChange } from './document-history.ts'
+export { validateAuthoringClientRequest, validateAuthoringClientQuery, validateAuthoringClientRequestQuery, validateAuthoringClientOpen, validateAuthoringClientReport, validateAuthoringClientAcknowledgement, validateAuthoringClientLease } from './authoring-clients.ts'
+export { validateProjectPlan, validateProjectApply } from './projects.ts'
+export { validateDocumentWorkspaceImageInspect, validateDocumentWorkspaceImageImport } from './document-image.ts'
+export { systemLocale } from './locale.ts'
+export { OperatorSpeechSettings, operatorSpeechSecrets, SpeechSettingsError } from './operator-speech.ts'

package/src/node/installed-packages.ts

@@ -0,0 +1,11 @@
+import { existsSync, realpathSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+/** The real directory of the package `name` installed in a `node_modules` at or above `from`, as Node resolves it. */
+export function findInstalledPackage(name: string, from: string): string | undefined {
+  for (let dir = from; ; dir = dirname(dir)) {
+    const candidate = join(dir, 'node_modules', name)
+    if (existsSync(join(candidate, 'package.json'))) return realpathSync(candidate)
+    if (dirname(dir) === dir) return undefined
+  }
+}

package/src/node/lines.ts

@@ -0,0 +1,24 @@
+import type { Readable } from 'node:stream'
+
+// Terminal colours and cursor moves, which a log shown on a page does not draw.
+const ESCAPES = /\x1B\[[0-?]*[ -/]*[@-~]|\x1B\][^\x07]*\x07/g
+
+/** Calls `each` with every line `stream` writes (carriage returns end a line too), without terminal escapes. */
+export function forEachLine(stream: Readable | null | undefined, each: (line: string) => void): void {
+  if (!stream) return
+  let rest = ''
+  stream.setEncoding('utf8')
+  stream.on('data', (chunk: string) => {
+    const parts = (rest + chunk).split(/\r\n|\r|\n/)
+    rest = parts.pop() ?? ''
+    for (const part of parts) {
+      const line = part.replace(ESCAPES, '')
+      if (line.trim()) each(line)
+    }
+  })
+  stream.on('end', () => {
+    const line = rest.replace(ESCAPES, '')
+    if (line.trim()) each(line)
+    rest = ''
+  })
+}

package/src/node/locale.ts

@@ -0,0 +1,7 @@
+import type { Locale } from '../contracts/locale.ts'
+
+/** The language of command-line output: the system's (`LC_ALL`, `LC_MESSAGES`, `LANG`, else `Intl`'s); `zh*` is zh-CN. */
+export function systemLocale(env: NodeJS.ProcessEnv = process.env): Locale {
+  const tag = env.LC_ALL || env.LC_MESSAGES || env.LANG || Intl.DateTimeFormat().resolvedOptions().locale
+  return /^zh/i.test(tag) ? 'zh-CN' : 'en'
+}

package/src/node/network.ts

@@ -0,0 +1,11 @@
+import { networkInterfaces } from 'node:os'
+
+/** This machine's IPv4 addresses on its local networks, for printing the addresses other devices can use. */
+export function lanAddresses(): string[] {
+  return Object.values(networkInterfaces()).flatMap(entries => entries ?? []).filter(entry => entry.family === 'IPv4' && !entry.internal).map(entry => entry.address)
+}
+
+/** The host as a URL writes it: an IPv6 address in brackets. */
+export function bracketIPv6(host: string): string {
+  return host.includes(':') && !host.startsWith('[') ? `[${host}]` : host
+}

package/src/node/operator-speech.ts

@@ -0,0 +1,91 @@
+import { createRequire } from 'node:module'
+import { randomUUID } from 'node:crypto'
+import { constants, closeSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import type { SpeechSettingsAnswer, SpeechSettingsChange } from '../contracts/speech-settings.ts'
+
+const KEY = 'PRESMIUM_SPEECH_VOLCENGINE_KEY', APPID = 'PRESMIUM_SPEECH_VOLCENGINE_APPID'
+const MAX_BYTES = 16384
+const lockfile = createRequire(import.meta.url)('proper-lockfile') as { lock(file: string, options: { realpath: boolean, retries: number }): Promise<() => Promise<void>> }
+interface Stored { version: 1, revision: string, key?: string, appId?: string }
+const empty = (): Stored => ({ version: 1, revision: 'none' })
+
+export class SpeechSettingsError extends Error {
+  readonly code: 'speech-settings-conflict' | 'speech-settings-invalid' | 'speech-settings-unavailable' | 'speech-settings-busy'
+  constructor(code: SpeechSettingsError['code']) { super(code); this.code = code }
+}
+
+/** One operator-owned file; no values leave this module except through the Node secret resolver. */
+export class OperatorSpeechSettings {
+  readonly #file: string | undefined
+  readonly #fallback: (name: string) => string | undefined
+  constructor(directory: string | undefined, fallback: (name: string) => string | undefined) {
+    this.#file = directory ? join(directory, 'speech', 'credentials.json') : undefined
+    this.#fallback = fallback
+  }
+  #read(): Stored {
+    if (!this.#file) return empty()
+    let fd: number | undefined
+    try {
+      fd = openSync(this.#file, constants.O_RDONLY | constants.O_NOFOLLOW)
+      const stat = fstatSync(fd)
+      if (!stat.isFile() || stat.size > MAX_BYTES) throw new SpeechSettingsError('speech-settings-unavailable')
+      const value = JSON.parse(readFileSync(fd, 'utf8')) as Stored
+      if (value?.version !== 1 || typeof value.revision !== 'string' || value.key !== undefined && typeof value.key !== 'string' || value.appId !== undefined && (typeof value.appId !== 'string' || !/^\d{1,32}$/.test(value.appId))) throw new SpeechSettingsError('speech-settings-unavailable')
+      return value
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return empty()
+      throw new SpeechSettingsError('speech-settings-unavailable')
+    } finally { if (fd !== undefined) closeSync(fd) }
+  }
+  secret = (name: string): string | undefined => {
+    if (name !== KEY && name !== APPID) return this.#fallback(name)
+    const saved = this.#read()
+    // API-key authentication must not inherit a different environment credential's App ID.
+    if (name === APPID && saved.key) return saved.appId
+    return (name === KEY ? saved.key : undefined) ?? this.#fallback(name)
+  }
+  read(): SpeechSettingsAnswer {
+    const value = this.#read(), key = value.key ?? this.#fallback(KEY)?.trim()
+    return { provider: 'volcengine', model: 'seed-tts-2.0', revision: value.revision, configured: Boolean(key), appIdConfigured: Boolean(value.key ? value.appId : this.#fallback(APPID)), source: value.key ? 'saved' : key ? 'environment' : 'none', stored: Boolean(value.key), writable: Boolean(this.#file), verification: 'configuration-only' }
+  }
+  async change(change: SpeechSettingsChange): Promise<SpeechSettingsAnswer> {
+    if (!this.#file) throw new SpeechSettingsError('speech-settings-unavailable')
+    const directory = dirname(this.#file)
+    try {
+      mkdirSync(directory, { recursive: true, mode: 0o700 })
+      if (lstatSync(directory).isSymbolicLink()) throw new Error('unsafe-directory')
+    } catch { throw new SpeechSettingsError('speech-settings-unavailable') }
+    let release: () => Promise<void>
+    try { release = await lockfile.lock(this.#file, { realpath: false, retries: 0 }) }
+    catch { throw new SpeechSettingsError('speech-settings-busy') }
+    let temporary: string | undefined
+    try {
+      const previous = this.#read()
+      if (change.revision !== previous.revision) throw new SpeechSettingsError('speech-settings-conflict')
+      let next: Stored = { version: 1, revision: randomUUID() }
+      if (change.action === 'save') {
+        const key = change.apiKey?.trim() || previous.key || this.#fallback(KEY)?.trim()
+        if (!key || !/^[\x21-\x7e]{8,8192}$/.test(key)) throw new SpeechSettingsError('speech-settings-invalid')
+        const appId = change.appId?.trim() ?? (change.apiKey?.trim() ? undefined : previous.key ? previous.appId : this.#fallback(APPID)?.trim())
+        if (appId && !/^\d{1,32}$/.test(appId)) throw new SpeechSettingsError('speech-settings-invalid')
+        next = { ...next, key, ...appId ? { appId } : {} }
+      }
+      temporary = `${this.#file}.${randomUUID()}.tmp`
+      writeFileSync(temporary, `${JSON.stringify(next)}\n`, { mode: 0o600, flag: 'wx' })
+      renameSync(temporary, this.#file)
+      temporary = undefined
+      return this.read()
+    } catch (error) {
+      if (error instanceof SpeechSettingsError) throw error
+      throw new SpeechSettingsError('speech-settings-unavailable')
+    } finally {
+      if (temporary) rmSync(temporary, { force: true })
+      await release()
+    }
+  }
+}
+
+export function operatorSpeechSecrets(directory: string | undefined, fallback: (name: string) => string | undefined): (name: string) => string | undefined {
+  return new OperatorSpeechSettings(directory, fallback).secret
+}

package/src/node/packages.ts

@@ -0,0 +1,74 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { createRequire, findPackageJSON } from 'node:module'
+import { dirname, isAbsolute, join, relative, sep } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+export const TYPESCRIPT_IMPORT: readonly string[] = ['--import', new URL('./strip-types.mjs', import.meta.url).href]
+
+/**
+ * The import specifier of `file` in a module generated in `dir`: relative where it can be (Vite's dependency scan does
+ * not follow an import written as an absolute path), else absolute (another drive on Windows).
+ */
+export function importSpecifier(dir: string, file: string): string {
+  const path = relative(dir, file)
+  if (isAbsolute(path)) return file
+  const posix = path.split(sep).join('/')
+  return posix.startsWith('.') ? posix : `./${posix}`
+}
+
+/** `file` as a glob that matches only it: Vite's `optimizeDeps.entries` are globs. */
+export function literalGlob(file: string): string {
+  return file.split(sep).join('/').replace(/[\\*?[\]{}()!@+|]/g, '\\$&')
+}
+
+export function packageOf(file: string): string | undefined {
+  const manifest = findPackageJSON(pathToFileURL(file))
+  return manifest && dirname(manifest)
+}
+
+function manifestOf(name: string, from: string): string | undefined {
+  const require = createRequire(from)
+  try {
+    return require.resolve(`${name}/package.json`)
+  } catch {}
+  let dir: string
+  try {
+    dir = dirname(require.resolve(name))
+  } catch {
+    return undefined
+  }
+  for (; dirname(dir) !== dir; dir = dirname(dir)) {
+    const file = join(dir, 'package.json')
+    if (existsSync(file) && (JSON.parse(readFileSync(file, 'utf8')) as { name?: string }).name === name) return file
+  }
+  return undefined
+}
+
+/** The file of the package's command `command` (its `bin`), the package as Node resolves it from `from`; undefined when either is missing. */
+export function findPackageBin(name: string, command: string, from: string): string | undefined {
+  const manifest = manifestOf(name, from)
+  if (!manifest) return undefined
+  const { bin } = JSON.parse(readFileSync(manifest, 'utf8')) as { bin?: string | Record<string, string> }
+  const file = typeof bin === 'string' ? bin : bin?.[command]
+  return file === undefined ? undefined : join(dirname(manifest), file)
+}
+
+/**
+ * Playwright's Chromium (`playwright-chromium`), as the deck installs it, else as `fallbackFrom` (a module's URL or a
+ * `package.json`) finds it.
+ */
+export async function playwrightChromium<T = unknown>(deckDir: string, fallbackFrom?: string): Promise<T> {
+  for (const from of [join(deckDir, 'package.json'), ...fallbackFrom ? [fallbackFrom] : []]) {
+    let entry: string
+    try {
+      entry = createRequire(from).resolve('playwright-chromium')
+    } catch {
+      continue
+    }
+    const loaded = await import(pathToFileURL(entry).href) as { chromium?: T, default?: { chromium?: T } }
+    const chromium = loaded.chromium ?? loaded.default?.chromium
+    if (chromium) return chromium
+    throw new Error('playwright-chromium does not export its Chromium browser')
+  }
+  throw new Error('this needs playwright-chromium: install it in the deck (and its browser with pnpm exec playwright install chromium)')
+}

package/src/node/paths.ts

@@ -0,0 +1,7 @@
+import { isAbsolute, relative, sep } from 'node:path'
+
+/** Whether path is root itself or lies under it; symbolic links are not resolved. */
+export function isInside(path: string, root: string): boolean {
+  const rel = relative(root, path)
+  return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel))
+}

package/src/node/projects.ts

@@ -0,0 +1,7 @@
+import type { Schema } from '@cfworker/json-schema'
+import { Validator } from '@cfworker/json-schema'
+import { PROJECT_APPLY_SCHEMA, PROJECT_PLAN_SCHEMA } from '../contracts/projects.ts'
+import type { ProjectApply, ProjectPlanRequest } from '../contracts/projects.ts'
+const plan = new Validator(structuredClone(PROJECT_PLAN_SCHEMA) as unknown as Schema, '2020-12', false), apply = new Validator(structuredClone(PROJECT_APPLY_SCHEMA) as unknown as Schema, '2020-12', false)
+export const validateProjectPlan = (value: unknown): value is ProjectPlanRequest => plan.validate(value).valid
+export const validateProjectApply = (value: unknown): value is ProjectApply => apply.validate(value).valid

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/strip-types.mjs

@@ -0,0 +1,15 @@
+import { readFileSync } from 'node:fs'
+import { registerHooks, stripTypeScriptTypes } from 'node:module'
+import { fileURLToPath } from 'node:url'
+
+const emitWarning = process.emitWarning
+process.emitWarning = (warning, ...args) => {
+  if (!String(warning).includes('stripTypeScriptTypes')) emitWarning.call(process, warning, ...args)
+}
+
+registerHooks({
+  load(url, context, nextLoad) {
+    if (!url.startsWith('file:') || !/\.m?ts$/.test(url) || !url.includes('/node_modules/')) return nextLoad(url, context)
+    return { format: 'module', source: stripTypeScriptTypes(readFileSync(fileURLToPath(url), 'utf8')), shortCircuit: true }
+  },
+})

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' } })
+    }),
+  }
+}