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

package/src/node/document-voice.ts

@@ -0,0 +1,115 @@
+import { DOCUMENT_ENTRY, fnv1a64, hasRole, speechEngineId } from '@lincyaw/kernel'
+import type { CanonicalSource, DocumentVoiceAuthoring, Finding, Member, SpeechService, VoiceoverExecution, VoiceoverJob } from '@lincyaw/kernel'
+import { createVoiceoverOwner, createVoiceoverRoutes, validateDocumentVoiceCatalogQuery, validateVoicePreviewStart } from '@lincyaw/kernel/node'
+import { readAuthoringDocument } from './document-editor.ts'
+import { RequestError } from './errors.ts'
+import type { SourceEditor } from './source-editor.ts'
+
+export interface DocumentVoiceServices { speech?: SpeechService, voiceover?: { version: 1, preview: true }, voiceoverExecution?: VoiceoverExecution, findings?: Finding[] }
+export interface DocumentVoiceAuthoringOptions {
+  editor: SourceEditor
+  services(document: string, source: CanonicalSource): Promise<DocumentVoiceServices>
+  revision?(document: string): string | undefined
+}
+const same = (a: CanonicalSource, b: CanonicalSource) => a.documentId === b.documentId && a.version === b.version && a.fingerprint === b.fingerprint
+
+export function createDocumentVoiceAuthoring({ editor, services, revision }: DocumentVoiceAuthoringOptions) {
+  const pending = new Set<{ controller: AbortController, finished: Promise<unknown> }>()
+  const owners = new Map<string, ReturnType<typeof createVoiceoverOwner>>()
+  let closed = false
+  const authorize = (document: string, member: Member) => {
+    if (!hasRole(member, 'editor')) throw new RequestError(403, 'voice-authoring-permission-denied')
+    if (closed) throw new RequestError(503, 'voice-authoring-closed')
+    if (!owners.has(document)) editor.readableFile({ document, home: false }, document ? `${document}/${DOCUMENT_ENTRY}` : DOCUMENT_ENTRY, member)
+  }
+  const ownerOf = (document: string, member: Member) => {
+    authorize(document, member)
+    let owner = owners.get(document)
+    if (!owner) { owner = createVoiceoverOwner(); owners.set(document, owner) }
+    return owner
+  }
+  const current = (document: string, member: Member, expected?: CanonicalSource) => {
+    const opened = readAuthoringDocument(editor, { document, member })
+    const source = { documentId: opened.content.id, version: opened.source.version, fingerprint: fnv1a64(opened.source.content) }
+    if (expected && !same(source, expected)) throw new RequestError(409, 'document-version-changed', { currentSource: source })
+    return { source, lang: opened.content.metadata.lang }
+  }
+  const work = <T>(signal: AbortSignal | undefined, run: (signal: AbortSignal) => Promise<T>): Promise<T> => {
+    if (closed) throw new RequestError(503, 'voice-authoring-closed')
+    signal?.throwIfAborted()
+    if (pending.size >= 4) throw new RequestError(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> }
+    pending.add(operation)
+    const finished = Promise.resolve().then(() => { combined.throwIfAborted(); return run(combined) }).finally(() => pending.delete(operation))
+    operation.finished = finished
+    return finished
+  }
+  const load = async (document: string, member: Member, signal: AbortSignal, expected?: CanonicalSource) => {
+    authorize(document, member)
+    const opened = current(document, member, expected), loaded = await services(document, opened.source)
+    signal.throwIfAborted(); current(document, member, opened.source)
+    return { ...opened, ...loaded }
+  }
+  const execution = (document: string, member: Member) => async (expected: CanonicalSource | undefined, signal: AbortSignal) => {
+    const loaded = await load(document, member, signal, expected)
+    if (!loaded.voiceoverExecution) throw new RequestError(503, 'voiceover-unavailable')
+    return loaded.voiceoverExecution
+  }
+  const isCurrent = (document: string, member: Member, job: VoiceoverJob): boolean | 'unknown' => {
+    try { const actual = current(document, member).source; if (!same(actual, job.source)) return false; const known = revision?.(document); return known === undefined ? 'unknown' : known === job.revision }
+    catch { return 'unknown' }
+  }
+  const service: DocumentVoiceAuthoring = {
+    capabilities: (document, member, signal) => work(signal, async signal => {
+      const loaded = await load(document, member, signal)
+      const [engines, defaultEngine] = await Promise.all([loaded.speech?.engines() ?? [], loaded.speech?.defaultSynthesisEngine?.()])
+      signal.throwIfAborted(); current(document, member, loaded.source)
+      const configured = engines.some(engine => engine.tts), unknown = !loaded.speech && loaded.findings?.some(finding => finding.severity === 'error')
+      const implemented = Boolean(loaded.voiceoverExecution)
+      return { document, source: loaded.source, verification: 'configuration-only', status: configured ? 'configured' : unknown ? 'unknown' : 'unavailable', ...!configured ? { reason: unknown ? 'services-unavailable' : 'not-configured' } as const : {}, voiceover: implemented, preview: implemented, engines, ...defaultEngine ? { defaultEngine } : {}, ...loaded.findings?.length ? { findings: loaded.findings } : {}, actions: { status: implemented, list: true, get: true, start: implemented && configured, cancel: true, quotePreview: implemented, preview: implemented && configured, readPreview: true }, tasks: { idempotency: 'process', limits: ownerOf(document, member).limits } }
+    }),
+    catalog: (document, query, member, signal) => work(signal, async signal => {
+      if (!validateDocumentVoiceCatalogQuery(query)) throw new RequestError(400, 'voice-catalog-query-invalid')
+      const loaded = await load(document, member, signal, query.source)
+      const engines = await loaded.speech?.engines() ?? []
+      signal.throwIfAborted(); current(document, member, loaded.source)
+      const preferred = query.engine ?? await loaded.speech?.defaultSynthesisEngine?.()
+      signal.throwIfAborted(); current(document, member, loaded.source)
+      const chosen = preferred ? engines.find(engine => engine.tts && engine.id === speechEngineId(preferred)) : undefined
+      const unknown = !loaded.speech && loaded.findings?.some(finding => finding.severity === 'error')
+      const catalog = chosen && loaded.speech ? await loaded.speech.voiceCatalog?.(chosen.id, query.lang ?? loaded.lang, signal) ?? { status: 'unavailable' as const, reason: 'unknown' as const, voices: [] } : { status: 'unavailable' as const, reason: unknown ? 'unknown' as const : 'not-configured' as const, voices: [] }
+      signal.throwIfAborted(); current(document, member, loaded.source)
+      return { document, source: loaded.source, engines, catalog, ...catalog.status === 'available' && chosen ? { engine: chosen.id } : {}, ...loaded.findings?.length ? { findings: loaded.findings } : {} }
+    }),
+    snapshot: (document, query, member, signal) => ownerOf(document, member).snapshot(query, execution(document, member), signal),
+    listJobs: async (document, member) => {
+      const owner = ownerOf(document, member)
+      return { document, jobs: owner.list().map(job => ({ ...job, current: isCurrent(document, member, job) })), idempotency: 'process', limits: owner.limits }
+    },
+    getJob: async (document, query, member) => {
+      const value = ownerOf(document, member).get(query)
+      return { ...value, current: value.job ? isCurrent(document, member, value.job) : 'unknown' }
+    },
+    start: (document, request, member, signal) => ownerOf(document, member).start(request, execution(document, member), signal),
+    checkStart: (document, request, member, signal) => ownerOf(document, member).checkStart(request, execution(document, member), signal),
+    checkCancel: async (document, query, member) => ownerOf(document, member).checkCancel(query),
+    checkPreview: async (document, request, member, signal) => {
+      if (!validateVoicePreviewStart(request)) throw new RequestError(400, 'voice-preview-invalid')
+      const owner = ownerOf(document, member)
+      current(document, member, request.source)
+      await owner.checkPreview(request, signal)
+      current(document, member, request.source)
+    },
+    cancel: async (document, query, member) => ownerOf(document, member).cancel(query),
+    quotePreview: (document, query, member, signal) => ownerOf(document, member).quote(query, execution(document, member), signal),
+    preview: (document, request, member, signal) => {
+      if (!validateVoicePreviewStart(request)) throw new RequestError(400, 'voice-preview-invalid')
+      const owner = ownerOf(document, member)
+      current(document, member, request.source)
+      return owner.preview(request, signal)
+    },
+    readPreview: async (document, id, member) => ownerOf(document, member).readPreview(id),
+  }
+  return { service, routes: createVoiceoverRoutes(service), async close() { closed = true; for (const operation of pending) operation.controller.abort(); await Promise.allSettled([...owners.values()].map(owner => owner.close())); await Promise.allSettled([...pending].map(operation => operation.finished)); owners.clear() } }
+}

package/src/node/errors.ts

@@ -0,0 +1,23 @@
+import { errorMessage, jsonResponse, problemResponse } from '@lincyaw/kernel'
+
+export class RequestError extends Error {
+  readonly status: number
+  readonly detail?: Record<string, unknown>
+  readonly headers?: Record<string, string>
+  constructor(status: number, message: string, detail?: Record<string, unknown>, headers?: Record<string, string>) {
+    super(message)
+    this.status = status
+    this.detail = detail
+    this.headers = headers
+  }
+}
+
+/** Runs a route's work and answers a RequestError it throws with its status, detail and headers, anything else with 500. */
+export async function catchRequestErrors(work: () => Promise<Response>): Promise<Response> {
+  try {
+    return await work()
+  } catch (error) {
+    if (error instanceof RequestError) return jsonResponse({ error: error.message, ...error.detail }, error.status, error.headers)
+    return problemResponse(500, errorMessage(error))
+  }
+}

package/src/node/git.ts

@@ -26,36 +26,36 @@ export class Git {
     }
   }
 
-  static ignores(dir: string, path: string): boolean {
-    try {
-      execFileSync('git', [...gitConfigArgs(), 'check-ignore', '-q', '--', path], { cwd: dir, stdio: 'ignore', env: gitEnvironment(process.env) })
-      return true
-    } catch {
-      return false
-    }
-  }
-
-  run(command: string[], env: Record<string, string> = {}): Promise<GitResult> {
+  run(command: string[], env: Record<string, string> = {}, input?: Uint8Array): Promise<GitResult> {
     return new Promise((done) => {
-      execFile('git', [...gitConfigArgs(), ...command], {
+      let inputError: Error | undefined
+      const child = execFile('git', [...gitConfigArgs(), ...command], {
         cwd: this.root,
         encoding: 'buffer',
         maxBuffer: 1 << 30,
         env: { ...gitEnvironment(process.env), ...env },
       }, (error, stdout, stderr) => {
-        const code = !error ? 0 : typeof error.code === 'number' ? error.code : 1
-        done({ code, stdout, stderr: stderr.toString('utf8') })
+        const code = inputError ? 1 : !error ? 0 : typeof error.code === 'number' ? error.code : 1
+        done({ code, stdout, stderr: stderr.toString('utf8') + (inputError?.message ?? '') })
       })
+      if (input !== undefined) {
+        if (child.stdin) {
+          child.stdin.on('error', error => { inputError = error; child.kill() })
+          child.stdin.end(input)
+        } else { inputError = new Error('git stdin is unavailable'); child.kill() }
+      }
     })
   }
 
-  async raw(command: string[], env?: Record<string, string>): Promise<string> {
+  /** The command's output; throws when it fails. */
+  async output(command: string[], env?: Record<string, string>): Promise<string> {
     const result = await this.run(command, env)
     if (result.code !== 0) throw new Error(result.stderr.trim() || `git ${command[0]} exited with ${result.code}`)
     return result.stdout.toString('utf8')
   }
 
-  async attempt(command: string[], env?: Record<string, string>): Promise<{ ok: boolean, output: string }> {
+  /** Whether the command succeeded, with its output, or its error output when it failed. */
+  async tryOutput(command: string[], env?: Record<string, string>): Promise<{ ok: boolean, output: string }> {
     const result = await this.run(command, env)
     return { ok: result.code === 0, output: result.code === 0 ? result.stdout.toString('utf8') : `${result.stderr}${result.stdout.toString('utf8')}` }
   }

package/src/node/jobs.ts

@@ -0,0 +1,361 @@
+import { createHash, randomBytes } from 'node:crypto'
+import { createReadStream, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { join, relative, sep } from 'node:path'
+import { availableRenderers, build, compileTranslations, documentExporters, exportDocument, serveDirectory } from '@lincyaw/compiler'
+import type { Compilation } from '@lincyaw/compiler'
+import { errorMessage, fnv1a64 } from '@lincyaw/kernel'
+import { lookup } from 'mime-types'
+import type { CompileJob, JobFile, JobSource, Logger, OutputJobs, OutputTarget } from '@lincyaw/kernel'
+import { RequestError } from './errors.ts'
+import { versionOf } from './source-editor.ts'
+
+/**
+ * The documents' heavy outputs as jobs, one running at a time: the renderers' builds (the slides' site, the notebook, the
+ * lecture) and the plugins' exporters (the slides as PDF or PowerPoint, the lecture as a video). A job shows its progress
+ * and log; its files are kept below the service's `/__outputs/<job>/`, and a job of the same target and IR revision is
+ * not run again.
+ */
+
+export const OUTPUTS_PATH = '/__outputs/'
+const JOB_FILE = 'job.json'
+// The last lines of a job's log the job keeps.
+const LOG_LINES = 400
+// The jobs a document keeps of each target, with their files.
+const KEEP = 3
+// The files a job lists (a site has many; the rest are still served).
+const LISTED = 500
+// Progress and log lines are told at most this often.
+const TELL_MS = 250
+
+export interface JobsOptions {
+  stateDir: string
+  /** The service's origin as browsers use it. */
+  url(): string
+  /** The path of the jobs' files on that origin (default `/__outputs/`; below the base when a proxy fronts the service). */
+  outputsPath?: string
+  compilation(document: string, fresh?: boolean): Promise<Compilation>
+  revision(compilation: Compilation): string
+  /** The workbench's origins, whose pages may read the files (a video's captions). */
+  origins: string[]
+  log: Logger
+}
+
+export interface Jobs extends OutputJobs {
+  get(id: string): CompileJob | undefined
+  /** Where a job's output is on this machine: a renderer's site or files, an exporter's files. */
+  directory(job: CompileJob): string
+  /** Each change of a job (state, progress, log), as it happens. */
+  subscribe(listener: (job: CompileJob) => void): () => void
+  /** The address that serves the jobs' files (the service forwards `/__outputs/` to it). */
+  origin(): Promise<string>
+  close(): Promise<void>
+}
+
+interface Running {
+  job: CompileJob
+  dir: string
+  controller: AbortController
+  ended: Promise<CompileJob>
+  end(): void
+  told: number
+  timer?: ReturnType<typeof setTimeout>
+}
+
+class Cancelled extends Error {
+  constructor() {
+    super('the job was cancelled')
+  }
+}
+
+// Where an exporter's renderer project is written, inside the job's directory, removed when it ends.
+
+const now = () => new Date().toISOString()
+const newId = () => `${Date.now().toString(36)}${randomBytes(4).toString('hex')}`
+const sameSource = (a: JobSource | undefined, b: JobSource): boolean => a?.version === b.version && a.fingerprint === b.fingerprint
+const sourceOf = (compilation: Compilation): JobSource => {
+  const bytes = readFileSync(compilation.entry)
+  return { version: versionOf(bytes), fingerprint: fnv1a64(bytes.toString('utf8')) }
+}
+
+/** Files a renderer/exporter may read after compilation must remain the captured inputs until output completion. */
+async function inputVersion(file: string): Promise<string | undefined> {
+  try {
+    const hash = createHash('sha256')
+    // Media inputs can be large. Hash streams without blocking requests or retaining the whole file in memory.
+    for await (const chunk of createReadStream(file)) hash.update(chunk)
+    return hash.digest('hex')
+  } catch { return undefined }
+}
+
+async function inputVersions(files: Iterable<string>): Promise<Map<string, string | undefined>> {
+  const pending = [...new Set(files)], versions = new Map<string, string | undefined>()
+  await Promise.all(Array.from({ length: Math.min(4, pending.length) }, async () => {
+    let file: string | undefined
+    while ((file = pending.pop()) !== undefined) versions.set(file, await inputVersion(file))
+  }))
+  return versions
+}
+
+async function checkInputs(inputs: Map<string, string | undefined>): Promise<void> {
+  const actual = await inputVersions(inputs.keys())
+  for (const [file, expected] of inputs) if (actual.get(file) !== expected) throw new RequestError(409, 'job-inputs-changed')
+}
+
+/** A file of a job, its path relative to the job's directory, its media type by its extension (`mime-types`). */
+function jobFile(root: string, path: string): JobFile {
+  return { path: relative(root, path).split(sep).join('/'), size: statSync(path).size, type: lookup(path) || 'application/octet-stream' }
+}
+
+/** The files below `dir`, at most LISTED, paths relative to `root`. */
+function listFiles(root: string, dir: string): JobFile[] {
+  const files: JobFile[] = []
+  const walk = (at: string) => {
+    for (const entry of readdirSync(at, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      if (files.length >= LISTED) return
+      const path = join(at, entry.name)
+      if (entry.isDirectory()) walk(path)
+      else if (entry.isFile() && entry.name !== JOB_FILE) files.push(jobFile(root, path))
+    }
+  }
+  if (existsSync(dir)) walk(dir)
+  return files
+}
+
+/** The file of a renderer's output to open first: a site's page, else its first file. */
+function mainFile(target: string, files: JobFile[]): string | undefined {
+  return files.find(file => file.path === `${target}/index.html`)?.path ?? files.find(file => file.path.startsWith(`${target}/`))?.path
+}
+
+export function createJobs(options: JobsOptions): Jobs {
+  const outputs = options.outputsPath ?? OUTPUTS_PATH
+  const root = join(options.stateDir, 'outputs')
+  // The jobs, oldest first, without their address (`present` adds it: the service's port changes between sessions).
+  const jobs = new Map<string, CompileJob>()
+  const running = new Map<string, Running>()
+  const listeners = new Set<(job: CompileJob) => void>()
+  let queue = Promise.resolve()
+  let server: ReturnType<typeof serveDirectory> | undefined
+  let closed = false
+
+  const present = (job: CompileJob): CompileJob => ({ ...job, url: `${options.url()}${outputs}${job.id}/`, log: [...job.log], files: [...job.files] })
+
+  // The jobs of earlier sessions whose files are still there.
+  mkdirSync(root, { recursive: true })
+  for (const id of readdirSync(root).sort()) {
+    try {
+      const job = JSON.parse(readFileSync(join(root, id, JOB_FILE), 'utf8')) as CompileJob
+      if (job.state === 'done' && job.id === id) jobs.set(id, { ...job, sequence: job.sequence ?? 0 })
+      else rmSync(join(root, id), { recursive: true, force: true })
+    } catch {
+      rmSync(join(root, id), { recursive: true, force: true })
+    }
+  }
+
+  const tell = (job: CompileJob) => {
+    job.sequence++
+    const shown = present(job)
+    for (const listener of listeners) listener(shown)
+  }
+  /** Tells a change at once (state), or within TELL_MS (progress, log). */
+  const changed = (entry: Running, soon = false) => {
+    clearTimeout(entry.timer)
+    entry.timer = setTimeout(() => {
+      entry.told = Date.now()
+      tell(entry.job)
+    }, soon ? 0 : Math.max(0, entry.told + TELL_MS - Date.now()))
+  }
+
+  /** Leaves the newest KEEP ended jobs of the document's target, with their files. */
+  const prune = (document: string, target: string) => {
+    const ended = [...jobs.values()].filter(job => job.document === document && job.target === target && !running.has(job.id))
+    for (const job of ended.slice(0, Math.max(0, ended.length - KEEP))) {
+      jobs.delete(job.id)
+      rmSync(join(root, job.id), { recursive: true, force: true })
+    }
+  }
+
+  const targetsOf = async (compilation: Compilation): Promise<OutputTarget[]> => {
+    const renderers = await availableRenderers(compilation)
+    const exports = (await documentExporters(compilation))
+      .filter(({ exporter, config }) => !renderers.includes(exporter.id) && (exporter.available?.(compilation.doc, config) ?? true))
+      .map(({ exporter }): OutputTarget => ({ id: exporter.id, kind: 'export', label: exporter.label }))
+    return [...renderers.map((id): OutputTarget => ({ id, kind: 'render', label: { 'zh-CN': id, 'en': id } })), ...exports]
+  }
+
+  const run = async (entry: Running, compilation: Compilation) => {
+    const { job, dir, controller } = entry
+    const log = (line: string) => {
+      options.log.info(`[job ${job.id}] document=${JSON.stringify(job.document || '.')} target=${job.target} ${line}`)
+      job.log.push(line)
+      if (job.log.length > LOG_LINES) job.log.splice(0, job.log.length - LOG_LINES)
+      changed(entry)
+    }
+    const progress = (phase: string, done?: number, total?: number) => {
+      if (job.progress?.phase !== phase) options.log.info(`[job ${job.id}] document=${JSON.stringify(job.document || '.')} target=${job.target} phase=${JSON.stringify(phase)}`)
+      job.progress = { phase, ...done === undefined ? {} : { done }, ...total === undefined ? {} : { total } }
+      changed(entry)
+    }
+    if (job.kind === 'render') {
+      progress(job.target)
+      const report = await build(compilation, { outDir: dir, to: [job.target], base: `${outputs}${job.id}/${job.target}/`, log })
+      if (controller.signal.aborted) throw new Cancelled()
+      job.warnings = report.findings.filter(finding => finding.severity === 'warning').map(finding => finding.message)
+      if (!report.outputs.some(output => output.renderer === job.target)) {
+        throw new Error(report.findings.filter(finding => finding.severity === 'error').map(finding => finding.message).join('\n') || `the ${job.target} renderer made nothing`)
+      }
+      job.files = listFiles(dir, join(dir, job.target))
+      job.main = mainFile(job.target, job.files)
+      return
+    }
+    const output = await exportDocument(compilation, job.target, { outDir: dir, signal: controller.signal, progress, log })
+    if (controller.signal.aborted) throw new Cancelled()
+    job.warnings = output.warnings ?? []
+    const named = output.files.map(file => file.split(sep).join('/'))
+    const first = named.flatMap(path => (existsSync(join(dir, path)) ? [jobFile(dir, join(dir, path))] : []))
+    job.files = [...first, ...listFiles(dir, dir).filter(file => !named.includes(file.path))]
+    job.main = first[0]?.path
+    if (output.captions) job.captions = Object.fromEntries(Object.entries(output.captions).map(([lang, file]) => [lang, file.split(sep).join('/')]))
+  }
+
+  /** Runs the job once the ones before it have ended. */
+  const schedule = (entry: Running, compilation: Compilation, inputs: Map<string, string | undefined>) => {
+    queue = queue.then(async () => {
+      const { job, controller } = entry
+      if (job.state !== 'queued') return
+      job.state = 'running'
+      job.startedAt = now()
+      const started = Date.now()
+      options.log.info(`[job ${job.id}] document=${JSON.stringify(job.document || '.')} target=${job.target} state=running queuedMs=${started - Date.parse(job.createdAt)}`)
+      changed(entry, true)
+      try {
+        await checkInputs(inputs)
+        if (controller.signal.aborted) throw new Cancelled()
+        mkdirSync(entry.dir, { recursive: true })
+        await run(entry, compilation)
+        await checkInputs(inputs)
+        if (controller.signal.aborted) throw new Cancelled()
+        job.state = 'done'
+      } catch (error) {
+        job.state = controller.signal.aborted ? 'cancelled' : 'failed'
+        if (job.state === 'failed') job.error = errorMessage(error)
+        options.log.warn(`the ${job.target} of ${job.document || '.'} ${job.state === 'cancelled' ? 'was cancelled' : `failed: ${job.error}`}`)
+      }
+      job.finishedAt = now()
+      options.log.info(`[job ${job.id}] document=${JSON.stringify(job.document || '.')} target=${job.target} state=${job.state} elapsedMs=${Date.now() - started}`)
+      delete job.progress
+      if (job.state === 'done') writeFileSync(join(entry.dir, JOB_FILE), `${JSON.stringify(job, null, 2)}\n`)
+      else rmSync(entry.dir, { recursive: true, force: true })
+      entry.end()
+    })
+  }
+
+  /** Everything start checks before it queues a job, and the job of the same target, source and inputs it would reuse. */
+  const admission = async (document: string, target: string, expected?: JobSource) => {
+    if (closed) throw new Error('the workspace service is closing')
+    // The interactive preview may still hold an older successful compilation. An explicit output compiles afresh.
+    const compilation = await options.compilation(document, true)
+    const source = sourceOf(compilation)
+    const confirmed = () => {
+      if (closed) throw new Error('the workspace service is closing')
+      if (expected && !sameSource(expected, source) || !sameSource(sourceOf(compilation), source)) throw new RequestError(409, 'job-source-changed')
+      if (compilation.sourceFingerprints?.[compilation.entry] !== source.fingerprint) throw new RequestError(409, 'job-source-not-compiled')
+    }
+    confirmed()
+    const revision = options.revision(compilation)
+    const targets = await targetsOf(compilation)
+    const known = targets.find(own => own.id === target)
+    if (!known) throw new RequestError(422, 'job-target-unknown', { target, targets: targets.map(own => own.id) })
+    // Locale sources are compiled by renderers later, so they are not part of the original's tracked input list.
+    const translations = await compileTranslations(compilation)
+    if (translations.findings.some(finding => finding.severity === 'error')) throw new RequestError(422, 'job-translations-invalid')
+    confirmed()
+    const inputs = await inputVersions([...compilation.inputs.files, ...translations.translations.flatMap(translation => translation.files)].filter(file => !compilation.sourceFiles.includes(file)))
+    confirmed()
+    // A site is built for the path its files are served at: one made below another base is not reused.
+    const inputFingerprint = fnv1a64(JSON.stringify([outputs, ...[...inputs].sort(([a], [b]) => a.localeCompare(b))]))
+    // The same target of the same revision, made or being made: not again.
+    const same = [...jobs.values()].reverse().find(job => job.document === document && job.target === target && job.revision === revision && sameSource(job.source, source) && job.inputFingerprint === inputFingerprint && ['queued', 'running', 'done'].includes(job.state))
+    return { compilation, source, revision, known, inputs, inputFingerprint, same }
+  }
+
+  return {
+    async targets(document) {
+      return await targetsOf(await options.compilation(document))
+    },
+    list(document) {
+      return [...jobs.values()].filter(job => document === undefined || job.document === document).reverse().map(present)
+    },
+    get(id) {
+      const job = jobs.get(id)
+      return job && present(job)
+    },
+    directory: job => (job.kind === 'render' ? join(root, job.id, job.target) : join(root, job.id)),
+    async check(document, target, expected) {
+      const admitted = await admission(document, target, expected)
+      return admitted.same && present(admitted.same)
+    },
+    async start(document, target, expected) {
+      const { compilation, source, revision, known, inputs, inputFingerprint, same } = await admission(document, target, expected)
+      if (same) {
+        options.log.info(`[job ${same.id}] document=${JSON.stringify(document || '.')} target=${target} reuse=${same.state}`)
+        return present(same)
+      }
+      const id = newId()
+      const job: CompileJob = { id, sequence: 0, document, target, kind: known.kind, state: 'queued', revision, source, inputFingerprint, createdAt: now(), url: '', files: [], warnings: [], log: [] }
+      jobs.set(id, job)
+      options.log.info(`[job ${id}] document=${JSON.stringify(document || '.')} target=${target} state=queued revision=${revision}`)
+      let resolve!: (job: CompileJob) => void
+      const entry: Running = {
+        job,
+        dir: join(root, id),
+        controller: new AbortController(),
+        ended: new Promise<CompileJob>(done => resolve = done),
+        end() {
+          running.delete(id)
+          clearTimeout(entry.timer)
+          tell(job)
+          prune(document, target)
+          resolve(present(job))
+        },
+        told: 0,
+      }
+      running.set(id, entry)
+      tell(job)
+      schedule(entry, compilation, inputs)
+      return present(job)
+    },
+    async wait(id) {
+      const entry = running.get(id)
+      if (entry) return await entry.ended
+      const job = jobs.get(id)
+      if (!job) throw new Error(`no job ${id}`)
+      return present(job)
+    },
+    cancel(id) {
+      const entry = running.get(id)
+      if (!entry) return this.get(id)
+      entry.controller.abort(new Cancelled())
+      // A job still waiting ends now; a running one when its exporter or renderer stops.
+      if (entry.job.state === 'queued') {
+        entry.job.state = 'cancelled'
+        entry.job.finishedAt = now()
+        entry.end()
+      }
+      return present(entry.job)
+    },
+    subscribe(listener) {
+      listeners.add(listener)
+      return () => listeners.delete(listener)
+    },
+    async origin() {
+      server ??= serveDirectory(root, { base: outputs, origins: options.origins })
+      return (await server).url
+    },
+    async close() {
+      closed = true
+      for (const id of [...running.keys()]) this.cancel(id)
+      await queue
+      if (server) await (await server).close()
+    },
+  }
+}

package/src/node/locks.ts

@@ -1,11 +1,12 @@
-import type { DocumentLockService } from '@lincyaw/kernel'
-import { lockKind } from '../domain/api.ts'
+import type { DocumentLockService, LockedAnswer } from '@lincyaw/kernel'
+import { lockKind } from '../domain/locks.ts'
+import { RequestError } from './errors.ts'
 
 export class DocumentLocks implements DocumentLockService {
   readonly #held = new Map<string, string>()
 
   claim(document: string, holder: string): (() => void) | undefined {
-    if (this.#held.has(document)) return undefined
+    if (this.holder(document) !== undefined) return undefined
     this.#held.set(document, holder)
     let released = false
     return () => {
@@ -16,12 +17,12 @@ export class DocumentLocks implements DocumentLockService {
   }
 
   holder(document: string): string | undefined {
-    return this.#held.get(document)
+    return this.#held.get('') ?? (document === '' ? this.#held.values().next().value : this.#held.get(document))
   }
 
   claimAll(documents: string[], holder: string): { release(): void } | { document: string, holder: string } {
     const releases: (() => void)[] = []
-    for (const document of new Set(documents)) {
+    for (const document of documents.includes('') ? [''] : new Set(documents)) {
       const release = this.claim(document, holder)
       if (release) {
         releases.push(release)
@@ -39,3 +40,7 @@ export function lockedMessage(document: string, holder: string): string {
   const what = kind === 'agent' ? 'an agent\'s change task runs or waits for its review' : kind === 'revert' ? 'a change is being undone' : 'a document operation is under way'
   return `${document || 'the document'} cannot change now: ${what} (${holder}); try again once it is done`
 }
+
+export function lockedError(document: string, holder: string): RequestError {
+  return new RequestError(409, lockedMessage(document, holder), { locked: { document, holder } } satisfies Omit<LockedAnswer, 'error'>)
+}