import { EngineError, EngineErrorCode } from '@embedpdf/engine-core/runtime'; import type { WirePack, WorkerJobId, WorkerRequest, WorkerResultPayload, } from '@embedpdf/engine-core/runtime'; export type BuildPack = (jobId: WorkerJobId) => WirePack; /** * Dispatch metadata for ad-hoc work. `lane: 'background'` marks * known-disposable work (today: exactly the thumbnail warm) for the * scheduler's capped lane; everything else — including the ingestion * security probe, which a user's commit waits on — defaults to * interactive. Base pools ignore it; only `SchedulingEnginePool` reads it. */ export interface RunAdHocOptions { lane?: 'background'; } /** * The engine plane's entire surface. `WorkerThreadPool` (inline mode — * worker threads in this process) and `EngineHostClient` (host mode — a * supervised child process) both implement it; every service and route * depends only on this. Extraction, not design: the shape is exactly * what the pool exposed before host mode existed. */ export interface EnginePool { runOpen( docId: string, baseSha: string, build: BuildPack, signal?: AbortSignal, ): Promise; runOpen(docId: string, build: BuildPack, signal?: AbortSignal): Promise; run(docId: string, build: BuildPack, signal?: AbortSignal): Promise; runAdHoc( baseSha: string | undefined, build: BuildPack, signal?: AbortSignal, opts?: RunAdHocOptions, ): Promise; close(docId: string, signal?: AbortSignal): Promise; destroy(): Promise; inspect(): Array<{ slot: number; docIds: string[]; baseShas: string[] }>; stats(): { slots: number; docs: number; inFlight: number }; /** * Monotonic engine generation: bumps on every engine (re)spawn. The * The write pipeline captures it at write-alignment time and refuses * to bless a session created under a later generation (see * `DocumentService.advanceLayerSession`). Inline pool: constant 0 — * the fence is vacuously satisfied and pre-host semantics are * untouched. */ generation(): number; /** * The generation of the shard serving this document, which the write * fence captures and re-checks (both fence sites use only this). * Single-engine pools ignore docId; the sharded composite returns the * resident shard's generation, or -1 when the doc is not resident (a * value no real generation takes, so a bless-time compare always * refuses when the doc's shard died in the window). `generation()` * stays as the max-across-shards diagnostics number. */ generationFor(docId: string): number; /** * Readiness detail for `/readyz`. Inline: always ready. Host mode: * `starting`/`backoff` with how long the engine has been unavailable — * readiness only fails past a persistence threshold so a sub-second * respawn never flaps the pod out of its load balancer. */ health(): { state: 'ready' | 'starting' | 'backoff'; downSinceMs: number | null }; } /** * One-shot `DocNotOpen` recovery for read dispatches. A read that parked * across an engine respawn (crash or planned recycle) dispatches into a * successor that no longer holds the document — the pre-dispatch ensure * ran against the old world. Re-ensure (the restart hook already cleared * the service caches, so this genuinely reopens) and retry once. * Mutations never use this: their retry path uses generation fencing and rebase. */ export async function runReadWithReopen( reensure: () => Promise, dispatch: () => Promise, ): Promise { try { return await dispatch(); } catch (err) { if (!(err instanceof EngineError && err.code === EngineErrorCode.DocNotOpen)) throw err; await reensure(); return dispatch(); } }